Skip to main content
Status: design, pending independent security review. Nothing on this page is implemented or enabled. Implementation lands in reviewed slices behind flags that default off, and landing a slice does not authorize a flag flip. Database access, the migration phases, the threat model and the stop fence are in Tuturuuu session rollout. Tuturuuu has one signed-in session for all of tuturuuu.com. Tuturuuu issues and manages it, whichever identity provider authenticated the user. Supabase Auth is the provider today; Better Auth is next, and a custom provider can follow. Swapping the provider must not change any app. This page is the end state of the server-held session decision. HttpOnly session cookie is its phase P0. The product rules stay in Shared session.

Principles

  1. One session authority. The session service is the only component that creates, rotates, refreshes or revokes a session. Other apps and Workers consume a derived identity and never see the session secret.
  2. Provider tokens stay in the trusted adapter. Browsers, mobile, the CLI, external apps and mounted app code never receive a Supabase, Better Auth or OAuth-provider token.
  3. User IDs are stable. The Tuturuuu user ID is the existing public.users.id, today equal to auth.users.id. Providers map onto it.
  4. Portable core, thin adapters. Session logic lives in a framework-free package with one adapter per runtime.
  5. Fail closed. An unknown, expired, revoked, ambiguous or unverifiable session is signed out. It never falls back to a weaker credential.
  6. Trusted ingress first. A host reads first-party identity only after every path into it passes through a component that strips client-supplied credentials and identity headers.

Components

1. Session model

The browser cookie names a device, not a user. The active account is a server-side pointer in the device’s Durable Object. A switch moves that pointer and issues a new generation, so a late response carrying an older generation cannot restore the superseded account. Codec invariants, in @tuturuuu/session:
  • The whole value matches one strict pattern and is at most 128 bytes. Base64url must be canonical: no padding and no non-zero trailing bits.
  • The codec counts the name across every Cookie field value it is given, including split headers. More than one __Host-ttr_session is ambiguous and resolves to signed out for every method. The response clears the name with Max-Age=0 and the same attributes.
  • The MAC is an admission filter, not authorization. It lets the auth Worker drop forged or random cookies before any Durable Object call. The device secret hash in storage still decides. k comes from TTR_SESSION_COOKIE_MAC_KEYS (HMAC-SHA-256, sign-capable), scoped by environment and host through the MAC input. The host is the hostname from trusted routing, lowercase, with no port and no trailing dot. Verification accepts the current key and at most one previous key for a 24-hour rollover. Emergency retirement removes a key, and its cookies fall through to storage-backed checks under the abuse limits.
  • dev reveals nothing about the user. The cookie carries no claims.
  • Adapters pass the Cookie field values as received and never fold them with commas. Pairs split only on ;, because browsers allow commas inside cookie values, and only spaces and tabs are trimmed.
Pre-authentication state (OAuth state, PKCE verifier, WebAuthn challenge, return target, QR and handoff redemption secrets) lives in a separate __Host-ttr_flow cookie. Each value is bound to one ceremony, lasts at most 10 minutes and is consumed once. It never becomes a session.

Generations and rotation

The device record keeps one current generation. A new generation (new gen, new secret, the previous secret invalid at once) is issued on:
  • every sign-in and account addition, including when the browser already sends a cookie, so a planted pre-login cookie dies at login;
  • step-up, MFA enrollment or removal, password change and account switch;
  • every 24 hours of use.
Only the 24-hour rotation keeps the previous generation for 30 seconds, so parallel requests from one tab do not sign out. During that window the previous generation has read authority only:
  • it resolves with stale: true only for routes the effect registry classes as read, whatever their HTTP method;
  • it carries no step-up and cannot use a step-up grant;
  • it cannot mint any credential, extend expiry or receive a Set-Cookie;
  • any other or unknown route with it gets 401 SESSION_ROTATED, and the client retries with the current cookie.
The BrowserDevice object serializes every write for its device, so rotation, account switch, sign-in and logout apply in one order. Each write that emits Set-Cookie carries the new gen. A response carrying an older gen cannot win, because any secret with a gen below the current one fails resolution (except the read-only window above). Recovery from an unusable cookie is a document navigation to Web’s sign-in, which keeps the device’s saved accounts.

Session record

Sessions are rows inside their device’s object: Saved accounts are sibling sessions on the same device; activeSid selects one. Switching moves the pointer inside one object and issues a new generation.

Expiry

lastSeenAt is written at most once every 5 minutes per session. Expiry is a pure function of the record and an injected clock.

Device list and revocation

  • List: GET /api/v1/auth/sessions reads the user’s device index from UserSessions and each device’s sessions. It returns device, location, lastSeenAt and current: true for this session, never secrets or grants.
  • Revoke one: DELETE /api/v1/auth/sessions/:sid revokes the row in its device object and its children there. It takes effect on the next resolution.
  • Revoke all: POST /api/v1/auth/sessions/revoke-all increments the user’s epoch in UserSessions, then revokes the user’s sessions in every indexed device object with bounded concurrency, retried by an alarm until each one acknowledges. Each device object re-reads the user’s epoch when its cached copy is older than 30 seconds, so a device the fan-out has not reached still stops within 30 seconds. The response reports any device still pending.
  • Upstream: every revocation calls the adapter’s revokeUpstream for that session’s grant, retried through the Queue. A provider failure never undoes the first-party revocation.
  • Account deletion, an admin “compromised” action and the revoke-all endpoint revoke every session on every device, including the caller’s.
  • Password change, MFA reset, and MFA or passkey removal bump the epoch and revoke every other device; the session that made the change stays signed in at the new epoch.
Revocation bounds are listed in Tuturuuu session rollout.

Step-up grants

A sensitive action needs a step-up grant, not a general window. The user confirms the named action on a Web-owned page with passkey user verification, or password plus a second factor. The session service then issues a grant bound to:
  • the action name and a hash of its parameters (for example the CLI user code, the external client ID and scopes, or the API key name and role);
  • the sid and the current generation;
  • an expiry of 5 minutes.
The action consumes the grant atomically in the device object. Covered actions: API keys, CLI device approval, QR-login approval, external-app consent, passkey and MFA changes, email or password change, account deletion and revoke-all.

Audit events

session.created, session.rotated, session.switched, session.step_up, session.revoked (with reason), session.revoked_all, session.reuse_detected, identity.linked, identity.unlinked, token.issued (with class and aud) and provider.error. Events carry IDs, the event type, the actor, a /24 (IPv4) or /48 (IPv6) prefix, the user-agent family and the time. They never carry secrets, tokens, raw cookies or full IP addresses. Event IDs are idempotent, and a lost event never changes a session decision. Users see their own events in the device list; support access follows the data protection standard.

2. Identity provider adapters

The session service talks to providers only through this interface, in @tuturuuu/session/provider:
  • Subject mapping. Each adapter maps its provider subject to a userId. A missing mapping is rejected: 'unprovisioned'.
  • Provisioning. Through P2, user creation stays with the existing auth.users triggers. Moving provisioning out of Supabase is a P3 work item with its own transactional function; see the rollout page.
  • One refresh owner per grant. Only the device object that holds a grant refreshes it, serialized there. UpstreamUnknown (a refresh whose outcome was lost) is reconciled by one bounded retry with the same grant, then the session is signed out. It is never retried blindly.
  • Grant custody. UpstreamGrant is encrypted with AES-256-GCM under TTR_SESSION_UPSTREAM_KEY, with dev and sid as associated data. Only the trusted data adapter (rollout page) receives a decrypted upstream access token, and only per request.
  • Linking needs proof of both identities, as OAuth sign-in requires. A matching email alone never links accounts.
  • Uniform controls. Rate limits, lockouts and MFA assurance are enforced in the session service, so they behave the same whichever adapter runs.
Supabase adapter (P1). Wraps the provider-thin flow modules in apps/web/src/lib/auth. providerSubject equals userId. The grant is the Supabase session, and revokeUpstream signs that Supabase session out. Better Auth adapter (P3). Runs Better Auth inside the session service with its tables in a better_auth schema, keyed by the existing UUIDs. Better Auth sessions stay internal to the adapter.

3. App identity

Principal

A Principal says who the request is for. Workspace membership and action permissions stay with the existing permission helpers, and step-up is a grant (section 1), not a principal field.

Package layout

Portable entry points have no framework or Cloudflare runtime imports, no request globals, no implicit network fetch and no signing keys. A boundary test parses the module graph reachable from every entry point and enforces it. An ephemeral-key test issuer lives in packages/session/src/testing.ts. It is not a package entry point, and creating an issuer requires VITEST=true. The boundary test parses every tracked JavaScript and TypeScript file in apps and packages whose text matches a testing specifier prefilter, and fails if a non-test file among them imports the issuer. Escaped or computed specifiers can miss that prefilter. The VITEST check guards against accidental use and is not a security boundary; isolation comes from keeping the issuer out of every entry point and from verifiers trusting only configured keys. Only the verifier can mark an object as a verified assertion, and principalFromAssertion accepts nothing else. Supabase and Better Auth code live only in the session service.

Trusted ingress

A mount Worker trusts x-ttr-identity only when the request arrived through the gateway’s service binding:
  • No public ingress. A mount whose reader flag is shadow or first-party has no zone route, custom domain, workers.dev or preview URL. A CI check on the app’s Worker configuration enforces it. Today some apex paths are zone routes straight to their Worker; those move behind the gateway before that app’s reader leaves supabase.
  • Exact routing. The gateway dispatches from an exact host and route allowlist, rejects unknown hosts, and handles assets and WebSocket upgrades on the same path.
  • Header hygiene. The gateway deletes every client-sent x-ttr-* header and the session cookie before dispatch, and before logging.
  • Bridge backstop. packages/start-bridge runs with unknownHost: 'reject'. On every request it strips __Host-ttr_session, drops any app Set-Cookie for that name, and deletes x-ttr-identity that fails verification. The P0 Supabase-cookie fences stay in force during dual-run.
  • Subdomain hosts. A subdomain app holding child sessions gets the same gateway in front of it before its reader leaves supabase.

Resolution

  1. The gateway checks the cookie’s codec without any key and, for an unsafe method with a cookie, enforces CSRF (see the rollout page); a failed check means no assertion. It classifies ingress and calls the auth Worker’s GatewayEntry.resolveForMount with its caller key.
  2. The auth Worker checks the cookie MAC before any Durable Object call, then resolves the device, its active session and the user’s epoch. It may cache a successful resolution of a read route for up to 5 seconds in its own isolate, keyed by the SHA-256 of the cookie value and the host. It never caches a failure or any other route class. On every cache hit it re-runs the route’s class and expected-account checks from its current registry and signs a new assertion for the requesting mount, so a cached entry never skips account_mismatch.
  3. The auth Worker signs x-ttr-identity for this mount and request, and the gateway forwards it.
  4. The mount’s adapter verifies it with verifyIdentityAssertion and builds a Principal. Sensitive operations, and anything that mints a credential, also call requireLiveSession(), which asks the session service and fails closed.
  5. A bearer request (Authorization: Bearer) skips the cookie path. The gateway or the app verifies the access token or resolves the workspace API key, and ignores cookies.
No runtime may resolve a session outside the gateway path, and that is a precondition, not a property of today’s gateway, which still forwards some paths to WEB_ORIGIN and leaves some apex paths on direct zone routes. Before any reader leaves supabase, APEX confirms that no session-bearing app has a direct zone route and that no session-bearing path reaches WEB_ORIGIN. Web family Workers that own auth routes call the auth Worker’s WebEntry over a service binding with their own caller key; see Tuturuuu session auth Worker.

Identity assertion profile

The header and claims sets are closed: any member not listed here is rejected. The auth Worker caps exp at the earliest of the session’s idle, absolute and parent deadlines, and for a stale assertion at the end of the grace window. No tolerance extends a deadline. Assertions are not single use. They only travel from the auth Worker through the gateway to the mount over service bindings, so an outside party cannot present one. A mount that misuses its own assertion is already inside its own boundary, and aud keeps it from using that assertion at another mount.
A successful result proves only that a trusted identity-class key signed these claims, for this issuer, environment and mount, and that the verifier’s clock is inside the accepted window. It does not prove how the request arrived, that the session is still live, or that the action is authorized. The function never throws for a bad token, makes no network call and needs no signing key. A key source that returns null gives unknown_key. A key source that returns 'unavailable' or throws gives keys_unavailable. A key that is not a public P-256 ECDSA verification key gives key_type. A key of another class, or a token with iat before the key’s notBefore or verified at or after its notAfter, gives unknown_key. Every failure is a rejection.

4. Service tokens and credential families

Token service

Refresh tokens are never JWTs. They are opaque, single-use secrets stored as HMACs in the session row and rotated on every use. Reusing a rotated refresh token revokes the whole session family.

Credential families

Mapping the existing credentials

Every family except Supabase’s own JWT signs today with a shared symmetric secret (HS256 or HMAC-SHA-256), and Tuturuuu publishes no JWKS. With one asymmetric token service, a verifier never holds a key that can mint. Rate limits use the existing apps/abuse-guard Durable Objects. Sign-out, password change, MFA reset, MFA or passkey removal, account deletion, the admin “compromised” action and revoke-all keep revoking AI temporary auth tokens and outstanding handoff codes.