feat(server): bind each member their own session-scoped token, release 0.0.5

[Dere-Wah]

Why

Every member of a slot holds the same JWT. PR #46 chose that design because the platform bound a session to the token that created it, at creation time only. A token minted later could not reach a session that already existed.

Three costs follow:

• A shared session (usersPerSession > 1) gives several browsers one identical credential.
• A member token cannot refresh. A new mint starts an empty grant, and the existing session rejects it. So the queue must mint each token to outlive the whole turn, and tokenTtlSeconds became a floor, not a lifetime.
• An acquireSession override receives no scope at all. Members of those deployments hold an unscoped, account-wide JWT.

POST /tokens now accepts resources.sessions.bind, which binds a token to a session that already exists. The session must be open. Its owner must be the user that owns the API key. The queue server holds that key, so this change removes all three costs.

What this changes

The slot no longer owns a token. mintConnectionOnSlot creates the session and the connection with the server JWT. CoordinatorClient.createSession and createConnection drop their per-call jwt parameter.

mintMemberToken(sessionId) mints one token per member. Each token names the configured model and binds to the one session assigned to that member. It omits max_sessions, so the limit resolves to the bound count. The grant arrives full, and the token cannot open a session of its own.

A token is no longer single-use, because the bind targets a live session. sendMemberToken mints a fresh token on every call. request_token and the client getJwt resolver now refresh for real. tokenTtlSeconds is a true 60 second lifetime again.

A token cannot exist before its session. A member who reserves a new slot receives the token at claim, just before session_ready. A member who joins a running slot receives it at once. Each token binds to the session that the member lands on, so a member moved to another slot needs no second delivery.

No unscoped path remains. The scopedTokens switch is gone, so an acquireSession override is scoped like every other deployment. Its session must come from RQ_REACTOR_API_KEY, or from another key of the same user. The platform checks ownership per user, not per account. The README said "same Reactor account", which is too weak, and this PR corrects it.

A session from a different user now fails visibly. The Coordinator refuses the mint. The member receives { type: "error", message: "token_mint_failed" }, and the admin log records the 403. A silent fallback would let an operator believe that members are scoped when they are not.

API surface

Nothing changes for clients. Members still receive { type: "token", jwt, expiresAt } and attach with connect({ sessionId, connectionId }). Only the request that the server sends is new:

POST /tokens
{
  "expires_after": 60,
  "authorization_details": [
    {
      "type": "session",
      "resources": {
        "models": { "match": ["helios"] },
        "sessions": { "bind": ["<the member's session id>"] }
      }
    }
  ]
}

RQ_TOKEN_TTL_SECONDS recovers its documented meaning. Set it back to a small value if you raised it because of the old floor.

Verification

pnpm typecheck, pnpm test (133 tests), pnpm build, pnpm format:check, and ./scripts/check-license.sh pass.

New tests cover:

• the bind payload, and the token order around session_ready
• distinct tokens on a shared session, and request_token re-mints
• a member moved to another slot, and a slot that version 0.0.4 persisted
• a bound acquireSession session, and a refused bind that raises an error

Two invariants also hold. No member token authorizes a session or connection call, and no member holds an unscoped token.

A live deployment confirmed the behaviour. Several tokens each took their own connection on one shared session, and the Coordinator applied a short expires_after to a bound mint. The refusals held too. A full grant cannot create a session, cannot reach another session, and cannot call a non-session API.

[Dere-Wah]

• feat(server): bind each member their own session-scoped token, release 0.0.5 #48 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.