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
- 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.
- 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.
- User IDs are stable. The Tuturuuu user ID is the existing
public.users.id, today equal toauth.users.id. Providers map onto it. - Portable core, thin adapters. Session logic lives in a framework-free package with one adapter per runtime.
- Fail closed. An unknown, expired, revoked, ambiguous or unverifiable session is signed out. It never falls back to a weaker credential.
- 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
Device cookie
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
Cookiefield value it is given, including split headers. More than one__Host-ttr_sessionis ambiguous and resolves to signed out for every method. The response clears the name withMax-Age=0and 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.
kcomes fromTTR_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. devreveals nothing about the user. The cookie carries no claims.- Adapters pass the
Cookiefield 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.
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 (newgen,
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.
- it resolves with
stale: trueonly for routes the effect registry classes asread, 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.
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/sessionsreads the user’s device index fromUserSessionsand each device’s sessions. It returns device, location,lastSeenAtandcurrent: truefor this session, never secrets or grants. - Revoke one:
DELETE /api/v1/auth/sessions/:sidrevokes 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-allincrements the user’s epoch inUserSessions, 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
revokeUpstreamfor 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.
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
sidand the current generation; - an expiry of 5 minutes.
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 isrejected: 'unprovisioned'. - Provisioning. Through P2, user creation stays with the existing
auth.userstriggers. 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.
UpstreamGrantis encrypted with AES-256-GCM underTTR_SESSION_UPSTREAM_KEY, withdevandsidas 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.
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
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 trustsx-ttr-identity only when the request arrived through
the gateway’s service binding:
- No public ingress. A mount whose reader flag is
shadoworfirst-partyhas no zone route, custom domain,workers.devor 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 leavessupabase. - 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-bridgeruns withunknownHost: 'reject'. On every request it strips__Host-ttr_session, drops any appSet-Cookiefor that name, and deletesx-ttr-identitythat 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
- 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.resolveForMountwith its caller key. - 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
readroute 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 skipsaccount_mismatch. - The auth Worker signs
x-ttr-identityfor this mount and request, and the gateway forwards it. - The mount’s adapter verifies it with
verifyIdentityAssertionand builds aPrincipal. Sensitive operations, and anything that mints a credential, also callrequireLiveSession(), which asks the session service and fails closed. - 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.
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.
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.