feat(be): mint short-lived app delegations from a revocable session

[sea-snake]

Design: #4224. Overview: #4230.

This is the PR the feature turns on: after it, a delegation an app holds is short-lived and its session is revocable.

Read hardest: the seed derivation, and the reclaim ordering in reclaim_order / reclaim_sessions. The seed decides what survives an account being renamed; the ordering decides which of a user's sessions dies when they hit the cap.

Motivation

DEFAULT_EXPIRATION_PERIOD_NS is 30 minutes and MAX_EXPIRATION_PERIOD_NS is 30 days, with the app choosing. Nothing II can do reaches an artifact it has already handed out; rotating the salt changes what future derivations produce without touching an already-signed delegation.

The minting half already ships, scoped to MCP: a grant in mcp_grant_memory, delegations capped at 5 minutes, prepare_account_delegation(max_expiration) enforcing the absolute cap. What MCP does not need, and apps do, is many sessions per identity and somewhere to put them.

Changes

The identity. session_seed = H(salt, "session", account_seed, created_at, device_id), every field length-prefixed. Building on the account seed rather than on the numbers is what makes a session survive anything that leaves the account's principal unchanged — naming a default account is exactly that.

Finding a session from a call. A new index maps the principal a session's chain is rooted at to {account_principal, device_id}. An app-facing call therefore names nothing and attaches nothing: caller() is looked up, the account principal resolves through the principal index, and device_id picks the record. A hit is itself the proof that the caller is that session.

The account is named by principal rather than by locator deliberately: materialising a default changes its locator and leaves its principal alone, so naming an account touches one index entry instead of every session on it.

Nothing signed travels with the call, so there is no artifact to issue per session, none to decode, none to witness on the get, and nothing an app's agent has to attach.

The browser proof. prepare_account_session takes device_key, the next_device_key it rotates to, and two signatures: the current key over the session key and the successor, and the successor over the session key and the current key, under a different domain so neither can be replayed in the other's role. Proving possession of the successor is what stops a key read off the wire — ingress messages are public — being announced by someone who does not hold it and claimed when its browser next presents one.

Replacement, not reuse. A ceremony from a browser that already holds a session at that account deletes it and mints a new one. A copy of the old session's chain therefore stops working at the user's next sign-in rather than at its expiry, and the consent special case disappears: a change of consent and a repeat of the same consent take one path.

The session cap is per identity. 500 stored records — expired ones included, since nothing observes a session dying — reclaimed to a watermark of 450 rather than blocking. A session_count on the anchor decides whether to act; the pass it triggers walks every row the identity has, takes dead sessions before live ones, and orders the live on last_used + (last_used − created_at), so an app in weekly use outranks one opened once and abandoned yesterday. Reclaiming runs before the new record is admitted, and admission is granted against what that pass counted rather than against the counter, so the stored set never sits above the cap. There is no per-reference cap: one browser holds one session per account, so the browser registry bounds a reference at 20 by construction.

Note what this cap does not do: it puts no bound on a flood of sign-ins. Standing rises with use, so anyone who can provoke sign-ins and keep refreshing them can outrank idle sessions. What stands in the way is the ceremony — creating a session needs an access method — and a stronger bound is deliberately left for whoever finds this one too weak.

The app-facing pair. app_prepare_delegation / app_get_delegation, capped at 5 minutes and not requestable by the app. The get re-derives the ceiling rather than trusting the expiration it is handed, since longer-lived delegations over the same account seed exist. An account principal is absent from the session index, so an app delegation cannot mint its own replacement.

Tests

Unit (46). session_creation_tests (14): the browser's session is replaced rather than reused, a different browser gets its own, expired records are pruned on write, one reference holds one session per browser, the cap reclaims to the watermark taking expired records first and then the stalest, an account the identity does not hold is refused, and the seed binds every immutable field. session_consent_change_tests (4). device_key::tests (10): a browser holding both keys is accepted; a successor the caller cannot prove, a successor signature replayed as the current one, a signature over another session key, one paired with a substituted successor, another browser's signature, a signature over the bare session key, a key that is not P-256, a wrong length and an empty signature are each refused.

PocketIC (29). Creation and witnessing, browser reuse, refusal for another identity, minting through the session index, the minted principal equalling the account's own and the account principal minting nothing itself, an expired session refused, a delegation longer than the TTL refused, replacement invalidating the previous chain, a consent change not reused, a browser dropped by the registry cap losing its sessions, the registration archived with the name redacted, and for the proof: a successor the caller cannot prove, a successor another browser holds even when proven, a retired key coming back as a new browser, a replayed announcement refused, the current key accepted after a lost response, and a rotation keeping the browser entry.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to d6bc4e9.

Security Overview

• 🔎 Scanned files: 28 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/6d3e3b61-710b-4b2b-9c0b-43458b6314b6?scanId=3be7a122-1ddc-4448-bc7a-2c151ad41207&codeScanTypes=PrScan&tab=issues

Detected Code Changes

The diff is too large to display a summary of code changes.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sea-snake]

Superseded by a four-way split of this PR, each layer under 500 lines of implementation:

• feat(be): verify a browser's key and its announced successor #4264 — verify a browser's key and its announced successor
• feat(be): store a revocable session on the account reference #4266 — store a revocable session on the account reference
• feat(be): cap sessions per identity #4267 — cap sessions per identity
• feat(be): sign a session to the II frontend at sign-in #4268 — sign a session to the II frontend at sign-in
• feat(be): mint short-lived app delegations from a session #4265 — mint short-lived app delegations from a session

The combined content is unchanged; the split was verified lossless against this branch's tree.