mos-backbone  —  mos.mubble.net
===============================

The backbone is a reverse tunnel: backend services open a persistent
outbound connection to the backbone and receive forwarded client requests
through it. Clients reach a service at  <service>.mos.mubble.net.

── FOR BACKEND SERVICES ────────────────────────────────────────────────────

1. Get a service token (admin only)
   POST https://mos.mubble.net/admin/api/tokens
   Authorization: Bearer <admin-token>
     {"service_name": "myapp"}

   Response: {"token": "mosb_<id>_<secret>", "service": "myapp", ...}
   The agent authenticates its tunnel connection with this token.

2. Connect the agent tunnel
   The agent dials the backbone over HTTP/2 or WebSocket, presents the
   service token, and parks a reverse connection. Once connected, clients
   can reach it at  https://myapp.mos.mubble.net/.

3. What the agent receives
   Every tunnelled request arrives with the client's identity headers
   already injected (stripped of all x-backbone-* credentials):

     x-mosb-sub      principal UUID          (present when authenticated)
     x-mosb-name     display name
     x-mosb-email    email
     x-mosb-sub-id   sub-identity (present when the client sent an assertion)

   Requests from unauthenticated clients arrive with no x-mosb-* headers.
   Services may choose to require or ignore principal identity.

── FOR CLIENTS / PRINCIPALS ────────────────────────────────────────────────

1. Register a principal
   POST https://mos.mubble.net/principals
     {"name": "Your Name", "email": "you@example.com", "note": "optional"}

   Response includes your principal_id (UUID) and credential string.
   The credential is shown ONCE — save it.

     {"credential": "mosb_pr_<id>_<key>", "principal": {...}}

2. Get access to a service
   A service admin must grant your principal_id access:

     POST https://mos.mubble.net/admin/api/grants
     Authorization: Bearer <admin-token>
       {"principal_id": "<your-uuid>", "service": "myapp"}

3. Call a service with your identity
   Include your credential on every request:

     x-backbone-principal: mosb_pr_<credential>

   The backbone verifies the credential, checks your grant, injects the
   x-mosb-* headers, strips x-backbone-principal, and forwards the request.

4. Optional: sub-assertions (per-request identity refinement)
   Sign a JSON payload with your derived key to assert a finer-grained
   identity on a single request. Claims override your registered name/email.

     x-backbone-assertion: <base64url(payload)>.<base64url(hmac)>

     payload: {"sub_id": "alice-session-7", "name": "Alice", "exp": <unix>}
     hmac:    HMAC-SHA256(derived_key, "assertion:" <> base64url(payload))

   derived_key = HMAC-SHA256(master_secret, "mosb-principal-v1:<id>:<vsn>")
   — your credential string embeds base64url(derived_key).

5. Optional: pre-signed URL tokens (no auth header needed)
   Generate a signed URL token scoped to a specific service:

     POST https://mos.mubble.net/url-tokens
     x-backbone-principal: mosb_pr_<credential>
       {"service": "myapp", "expires_in": 3600}

   Response: {"token": "...", "url": "https://myapp.mos.mubble.net?_mosb=<token>"}

   Append ?_mosb=<token> to any request URL — no header required.
   Rotating your key_version immediately invalidates all outstanding tokens.

── QUICK REFERENCE ─────────────────────────────────────────────────────────

Endpoint                           Auth             Description
──────────────────────────────────────────────────────────────────────────
POST /principals                   none             register as a principal
POST /url-tokens                   principal cred   generate a signed URL
GET  /healthz                      none             health check

POST /admin/api/tokens             admin token      create a service token
GET  /admin/api/tokens             admin token      list service tokens
DELETE /admin/api/tokens/:id       admin token      revoke a service token
POST /admin/api/grants             admin token      grant principal → service
DELETE /admin/api/grants/:pid/:svc admin token      revoke a grant
GET  /admin/api/grants/:pid        admin token      list grants for principal
GET  /admin/api/principals         admin token      list principals
DELETE /admin/api/principals/:cid  admin token      revoke a principal
GET  /admin/api/services           admin token      list connected services
GET  /admin/api/cluster            admin token      cluster node status
────────────────────────────────────────────────────────────────────────────
JSON? Send  Accept: application/json