api-rest – REST API Gateway

Exposes MuxCore capabilities via a RESTful HTTP API.

A MuxCore sidecar module that routes external HTTP requests to internal gRPC services. Provides rest.api and auth.delegate.

---

How It Works

HTTP client ──→ api-rest (:8080) ──→ muxcored (gRPC)
                      │
                      ▼
              /api/v1/* handlers
              (modules, storage,
               audit, events, …)

Implements contracts.Module via the module SDK. External callers hit the HTTP listener; handlers proxy into core over gRPC.

---

Configuration

Variable	Default	Description
API_REST_HTTP_ADDR	:8080	Public HTTP listen address
API_REST_GRPC_ADDR	:9400	Module gRPC listen address
API_REST_MODULE_ID	api-rest	Override module identity
MUXCORE_GRPC_ADDR	``	Core mesh address (required for registration; also --muxcore-mesh-addr)
MUXCORE_MODULE_ID	``	SDK module ID override
MUXCORE_INSECURE_DISABLE_TLS	``	Set true to disable TLS (dev only)

---

Quick Start

make build

export MUXCORE_INSECURE_DISABLE_TLS=true
./api-rest --muxcore-mesh-addr localhost:9090

---

Capabilities

• rest.api — REST API gateway
• auth.delegate — Delegated bearer validation (see below)

Auth delegation (auth.delegate)

api-rest does not store users or issue tokens. Protected /api/v1/* routes (except GET /api/v1/health and CORS OPTIONS) require Authorization: Bearer <token>. Validation is delegated to whichever mesh peer advertises the auth capability:

Peer	Typical role	Notes
auth-local	Dev / single-node	Username+password + session tokens; MVP host uses public AUTH_HTTP_URL for browser redirects and loopback AUTH_HTTP_INTERNAL_URL for server-side exchange. api-rest dials the module’s gRPC/HTTP addr from discovery (MUXCORE_MESH_DIAL_LOCAL=true rewrites empty hosts to 127.0.0.1 on host stacks).
auth-oidc	SSO	Same auth capability + Validate RPC; browsers complete OIDC against the OIDC module’s HTTP surface, then present the resulting bearer to api-rest. User CRUD / TOTP / WebAuthn may be Unimplemented — see auth-oidc docs.

Flow:

1. Client obtains a bearer from auth-local or auth-oidc (login / OIDC callback).
2. Client calls api-rest with Authorization: Bearer ….
3. api-rest FindByCapability("auth") → dials that module → AuthService.Validate.
4. On success, the bearer is forwarded on outbound core gRPC metadata so core’s sidecar identity can see the token.

Invalid/expired tokens → 401. No auth peer or dial/Validate failure → 503 with an auth unavailable message. Only one auth peer is selected (first discovery hit); run either auth-local or auth-oidc as the active auth provider, not both competing without call-policy.

License

GPL-3.0