@ultimat3/auth 20.2.0 → 21.0.0

package/CLAUDE.md

@@ -514,6 +514,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `kdf-gate.ts` | the one bound on concurrent argon2 work, and the `X_OVERLOADED` past it — core's `createFlightGate` with auth's own refusal injected |
 | `email.ts` | `normaliseEmail` — the one normalisation an address gets before it is an identity key |
 | `json.ts` | reading untrusted JSON: `isRecord`, and a base64url JWT segment as an object or `null` |
+| `sign-out.ts` | `signOutHeaders({ session? })` — what a sign-out RESPONSE appends: the framework session cookie expired (when `session` is given) and `Clear-Site-Data: "cache", "storage"` (`SIGN_OUT_CLEAR_SITE_DATA`), so the browser drops the previous principal's IndexedDB (the page store's `ultimate-client`), local storage, service worker and Cache Storage. Never `"cookies"`: the response sets the signed-out cookie itself. THE TRADE-OFF, decided 2026-09-22: a PWA's offline cache does not survive a sign-out — the worker is unregistered and the next load reinstalls and re-precaches it — because a cached private page IS the previous principal's data. The page boot's rescope wipe stays as the second line, for a sign-out with no navigation. Browsers honour the header only in a secure context (HTTPS, or localhost) |
+| `client-scope.ts` | `clientScopeOf(actor)` — the OPAQUE per-principal id a private document hands the page's client store (`<meta name="ultimate-scope">`, plan 101). Keyed SHA-256 (`SESSION_SECRET`) over kind, id and the impersonator, 32 hex; `''` for anonymous. Never the raw id: the HTML is readable by every script on the page. `SESSION_SECRET` is optional in the env schema, so its absence falls back to a random PER-PROCESS key with one `auth.client_scope.process_key` warning — the id then changes across replicas and restarts, which rescopes (clears) a page's store and never leaks one |
 
 ```bash
 bun test packages/auth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "20.2.0",
+  "version": "21.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.2.0",
-    "@ultimat3/db": "20.2.0",
-    "@ultimat3/schema": "20.2.0"
+    "@ultimat3/core": "21.0.0",
+    "@ultimat3/db": "21.0.0",
+    "@ultimat3/schema": "21.0.0"
   }
 }

package/src/client-scope.ts

@@ -0,0 +1,68 @@
+// The browser page's client scope id: an OPAQUE name for the principal a per-request document was
+// rendered for, carried in `<meta name="ultimate-scope">` so the page's one client store fences
+// itself per principal (plan 101, decision 8). Keyed SHA-256 over the principal, never the id:
+// the HTML is cacheable by a browser and readable by every script on the page.
+
+import type { Actor } from '@ultimat3/core';
+import { logger } from '@ultimat3/core';
+import { clientScopeSecretShort } from './errors';
+
+/** 128 bits: a scope only has to differ between principals, never to authenticate anyone. */
+const SCOPE_HEX_CHARS = 32;
+
+/** `wiki/Configuration.md`'s floor for `SESSION_SECRET`, the same one the oauth handshake reads. */
+const MIN_SECRET_LENGTH = 32;
+
+export interface ClientScopeOptions {
+  /** Defaults to `SESSION_SECRET`. */
+  readonly secret?: string | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/** Minted on first need when no `SESSION_SECRET` exists: stable per process, never per request. */
+let processKey: string | undefined;
+
+/**
+ * `''` for the anonymous page — the empty scope core reads as "nobody". Otherwise the principal
+ * AND who is really acting, so an admin impersonating a user is not the user's own scope: their
+ * stores must never share records, on the page or on disk.
+ */
+export function clientScopeOf(actor: Actor, options: ClientScopeOptions = {}): string {
+  if (actor.kind === 'anonymous') return '';
+  const material = JSON.stringify([
+    actor.kind,
+    actor.id,
+    actor.onBehalfOf?.actorKind ?? null,
+    actor.onBehalfOf?.actorId ?? null,
+  ]);
+  return new Bun.CryptoHasher('sha256', scopeKey(options))
+    .update(material)
+    .digest('hex')
+    .slice(0, SCOPE_HEX_CHARS);
+}
+
+function scopeKey(options: ClientScopeOptions): string {
+  if (options.secret !== undefined) {
+    // The same floor as the env path below: an explicit key is a caller's value, so a short one is
+    // refused rather than silently swapped for the process key.
+    if (options.secret.length < MIN_SECRET_LENGTH) {
+      throw clientScopeSecretShort(options.secret.length, MIN_SECRET_LENGTH);
+    }
+    return options.secret;
+  }
+  const configured = (options.env ?? Bun.env)['SESSION_SECRET']?.trim() ?? '';
+  if (configured.length >= MIN_SECRET_LENGTH) return configured;
+  if (processKey === undefined) {
+    // `SESSION_SECRET` is optional in the env schema, so its absence cannot refuse a render. A
+    // random per-process key keeps the id opaque; what it costs is stability across replicas and
+    // restarts — a principal's page then rescopes, which clears its store, never leaks it.
+    processKey = Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) =>
+      byte.toString(16).padStart(2, '0'),
+    ).join('');
+    logger.warn('auth.client_scope.process_key', {
+      reason: 'SESSION_SECRET unset or shorter than 32 chars',
+      fix: 'export SESSION_SECRET="$(openssl rand -hex 32)"',
+    });
+  }
+  return processKey;
+}

package/src/errors.ts

@@ -241,6 +241,19 @@ export const authPolicyNumberInvalid = (
     meta: { option: key, value: String(value) },
   });
 
+/**
+ * An explicit key for `clientScopeOf` under the floor `SESSION_SECRET` is held to. The env path
+ * already refused a short secret; the option skipped the screen, so `{ secret: 'x' }` keyed every
+ * page's scope id with one character. `X_CONFIG_INVALID`, borrowed like the two above.
+ */
+export const clientScopeSecretShort = (length: number, minLength: number): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `clientScopeOf({ secret }) was passed a key of ${String(length)} characters and at least ${String(minLength)} are required, so the scope id would be keyed by a guessable secret`,
+    fix: 'omit secret so clientScopeOf reads SESSION_SECRET, or pass one generated with: openssl rand -hex 32',
+    meta: { option: 'secret', minLength },
+  });
+
 export const passwordWeak = (reasons: readonly string[]): AuthError =>
   new AuthError({
     code: 'X_PASSWORD_WEAK',

package/src/index.ts

@@ -52,6 +52,9 @@ export {
 } from './auth';
 
 export { BuiltinAdapter } from './builtin-adapter';
+/** The opaque per-principal id a per-request document hands the page's client store. */
+export type { ClientScopeOptions } from './client-scope';
+export { clientScopeOf } from './client-scope';
 export type { AuthUserSummary } from './directory';
 export { describeUser, findUserByExternalId, listOrgUsers } from './directory';
 // The one normalisation an address gets before it is an identity key. Public because an app
@@ -316,6 +319,9 @@ export {
   sessionExpiry,
   verifySession,
 } from './session';
+/** A sign-out response's headers: the session cookie expired, and `Clear-Site-Data`. */
+export type { SignOutHeadersOptions } from './sign-out';
+export { SIGN_OUT_CLEAR_SITE_DATA, signOutHeaders } from './sign-out';
 
 export {
   AUTH_TABLE_NAMES,

package/src/sign-out.ts

@@ -0,0 +1,44 @@
+// What a sign-out RESPONSE carries, beside ending the session row (`logout`): the session cookie
+// expired, and `Clear-Site-Data`, so the browser drops everything the previous principal left on
+// the origin — the page store's IndexedDB, local storage, the service worker and its cached pages.
+
+import type { SessionPolicy } from './session';
+import { clearSessionCookie } from './session';
+
+/**
+ * `"cache", "storage"` and never `"cookies"`: the response itself sets the cookie that marks the
+ * browser signed out, and `"cookies"` would clear that too. `"storage"` unregisters the service
+ * worker and empties Cache Storage — which is the point, since a cached private page is the previous
+ * principal's data — so the next load reinstalls the worker and re-precaches. That cost is paid once
+ * per sign-out, and it is the trade the framework makes: a PWA's offline cache does not outlive the
+ * person it was cached for.
+ */
+export const SIGN_OUT_CLEAR_SITE_DATA = '"cache", "storage"';
+
+export interface SignOutHeadersOptions {
+  /**
+   * The framework session's policy, when the app signs out of `@ultimat3/auth`'s own session: the
+   * cookie is then expired here. Absent for an app with its own cookie (it sets that itself).
+   */
+  readonly session?: SessionPolicy | undefined;
+  readonly cookieName?: string | undefined;
+}
+
+/**
+ * The headers a sign-out response appends, in order: `for (const [name, value] of
+ * signOutHeaders()) ctx.headers.append(name, value)`. The browser acts on them only for a secure
+ * context (HTTPS, or localhost) — which is every deployed app and every `x dev`.
+ */
+export function signOutHeaders(options: SignOutHeadersOptions = {}): readonly [string, string][] {
+  return [
+    ...(options.session === undefined
+      ? []
+      : [
+          ['set-cookie', clearSessionCookie(options.session, options.cookieName)] as [
+            string,
+            string,
+          ],
+        ]),
+    ['clear-site-data', SIGN_OUT_CLEAR_SITE_DATA],
+  ];
+}