@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/lib/auth/identityToken.ts

@@ -0,0 +1,341 @@
+/**
+ * Offline verification of tot's identity assertion (`id_token`) — the consuming
+ * half of the decoupled-authZ architecture (Phase 3).
+ *
+ * tot signs a short-lived ES256 assertion ONCE at sign-in with its PRIVATE key
+ * (`/api/internal/access-code/verify` → `id_token`). This module verifies it
+ * OFFLINE using tot's published JWKS (fetched once, cached, key-selected by
+ * `kid`) and derives the storefront session from the VERIFIED claims — no shared
+ * secret, no per-request callback to tot. Removing tot's network reachability
+ * after sign-in must not break authorization; the token's own `exp` bounds
+ * staleness.
+ *
+ * This mirrors the Phase-2 launchpad kernel's lightweight offline verifier
+ * (`launchpad src/modules/authz/jwks-verifier.ts` + `identity-claims.ts`) and the
+ * tot-internal verify path proven in
+ * `tot20 services/InternalAuthService/identityTokenService.jest.js`.
+ *
+ * PROTOTYPE SCOPE: this replicates ONLY the JWKS offline-verify + a coarse
+ * claims→session derivation. The full Cedar PDP (`can()` policy engine, staff
+ * sandbox) and consuming the launchpad kernel as an installed package are
+ * Phase 4 — see branch `feat/authz-cedar-kernel`. Do NOT vendor the Cedar-wasm
+ * PDP into the Worker; it is unnecessary for the current coarse gate.
+ *
+ * Contract: /tmp/authz-token-claims-contract.md (AS-BUILT). Key points mirrored
+ * here: §2 (ES256 + jose), §3 (claim set), §5 (consumer verify algorithm),
+ * §6 (field name `id_token`), §6b (JWKS host is per-env app config; jose
+ * cross-version 4↔6 is wire-compatible by construction).
+ */
+import {
+  jwtVerify,
+  createRemoteJWKSet,
+  createLocalJWKSet,
+  decodeProtectedHeader,
+  type JWTVerifyGetKey,
+  type JSONWebKeySet,
+} from "jose";
+import { readEnv } from "@/lib/env";
+
+/** tot's issuer — consumers pin/allowlist this (`auth.jwt.issuer`). */
+export const TOT_ISSUER = "tokenoftrust-internal-ops";
+
+/** The only signing algorithm tot uses. Consumers MUST reject anything else. */
+export const TOT_ALG = "ES256";
+
+/**
+ * JWKS path (host is per-env app config — §6b). Contract also serves
+ * `/api/internal/auth/jwks`; the well-known path is the canonical one.
+ */
+export const JWKS_PATH = "/api/.well-known/jwks.json";
+
+/**
+ * Coarse tenant role, collapsed by tot from its per-tenant capability
+ * (`developer`/`inviter`/none → `member`). Org standing only; finer granularity
+ * is the storefront's own job to derive locally (Phase-4 PDP work).
+ */
+export type CoarseRole = "owner" | "admin" | "member";
+
+/** A single tenant membership carried in the assertion. */
+export interface TenantMembership {
+  resource: string;
+  role: CoarseRole;
+}
+
+/**
+ * The verified identity assertion payload (tot-authoritative + registered
+ * claims). Everything here is an INPUT to the storefront's policy, not a
+ * decision. Mirrors the launchpad kernel's `IdentityClaims`.
+ */
+export interface IdentityClaims {
+  // Registered claims
+  iss: string;
+  sub: string;
+  aud: string;
+  iat: number;
+  exp: number;
+  jti?: string;
+  // tot-authoritative claims
+  email: string;
+  /** Baseline verification signal today (email control proven at sign-in). */
+  email_verified: boolean;
+  tenants: TenantMembership[];
+  /**
+   * ToT-staff cross-domain scope (present for ToT staff). CARRIED as a principal
+   * attribute; the coarse gate grants NOTHING from it — staff must never elevate
+   * app privileges (enforced by the Phase-4 PDP staff sandbox).
+   */
+  staff: string[];
+}
+
+/** Coarse-role collapse guard: anything tot didn't send as owner/admin → member. */
+function coerceRole(role: unknown): CoarseRole {
+  return role === "owner" || role === "admin" ? role : "member";
+}
+
+/**
+ * Normalize a jose JWT payload into typed {@link IdentityClaims}, coercing the
+ * loosely-typed pieces and filling contract defaults (`staff: []`). Throws if a
+ * required tot-authoritative claim is missing or malformed. Mirrors the kernel's
+ * `toIdentityClaims`.
+ */
+export function toIdentityClaims(payload: Record<string, unknown>): IdentityClaims {
+  const email = payload.email;
+  if (typeof email !== "string" || !email) {
+    throw new Error("identity assertion missing `email` claim");
+  }
+  const tenantsRaw = Array.isArray(payload.tenants) ? payload.tenants : [];
+  const tenants: TenantMembership[] = tenantsRaw.map((t): TenantMembership => {
+    const entry = t as { resource?: unknown; role?: unknown };
+    if (typeof entry.resource !== "string") {
+      throw new Error("identity assertion `tenants[].resource` must be a string");
+    }
+    return { resource: entry.resource, role: coerceRole(entry.role) };
+  });
+  const staff = Array.isArray(payload.staff)
+    ? payload.staff.filter((s): s is string => typeof s === "string")
+    : [];
+
+  return {
+    iss: String(payload.iss ?? ""),
+    sub: String(payload.sub ?? email),
+    aud: String(payload.aud ?? ""),
+    iat: Number(payload.iat ?? 0),
+    exp: Number(payload.exp ?? 0),
+    jti: typeof payload.jti === "string" ? payload.jti : undefined,
+    email: email.toLowerCase(),
+    email_verified: payload.email_verified === true,
+    tenants,
+    staff,
+  };
+}
+
+/** Derive tot's JWKS URL from the configured tot API base (§6b: path fixed, host app-config). */
+export function deriveJwksUri(baseUrl: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}${JWKS_PATH}`;
+}
+
+export interface IdentityVerifierConfig {
+  /**
+   * This host's tenant appDomain / `resource` — enforced as the `aud` claim (tot
+   * sets `aud` per-assertion to the target app). REQUIRED: a token minted for
+   * another tenant must be rejected.
+   */
+  audience: string;
+  /** Allowlisted issuer. Defaults to tot's. */
+  issuer?: string;
+  /**
+   * tot's JWKS endpoint, e.g. `https://qa.tokenoftrust.com/api/.well-known/jwks.json`.
+   * Provide in production. jose caches the fetch, selects the key by `kid`, and
+   * re-fetches once on an unknown `kid` before failing closed.
+   */
+  jwksUri?: string;
+  /**
+   * Pre-resolved JWKS (test / air-gapped path). The storefront holds ONLY the
+   * published public material — no private key, no secret. Exactly one of
+   * {@link jwksUri} or {@link jwks} must be supplied.
+   */
+  jwks?: JSONWebKeySet;
+}
+
+/**
+ * Verifies tot identity assertions offline against the published JWKS. One
+ * instance per (audience, JWKS host); its `audience` is fixed. Never calls tot
+ * per request — the JWKS fetch is cached inside jose's key resolver, so once the
+ * key material is in-process, verification survives tot being unreachable.
+ */
+export class IdentityAssertionVerifier {
+  private readonly audience: string;
+  private readonly issuer: string;
+  private readonly keys: JWTVerifyGetKey;
+
+  constructor(config: IdentityVerifierConfig) {
+    if (!config.audience) {
+      throw new Error("IdentityAssertionVerifier requires an `audience` (this host's resource)");
+    }
+    if (!!config.jwksUri === !!config.jwks) {
+      throw new Error("IdentityAssertionVerifier requires exactly one of `jwksUri` or `jwks`");
+    }
+    this.audience = config.audience;
+    this.issuer = config.issuer ?? TOT_ISSUER;
+    this.keys = config.jwks
+      ? createLocalJWKSet(config.jwks)
+      : createRemoteJWKSet(new URL(config.jwksUri as string));
+  }
+
+  /**
+   * Verify a compact JWS and return typed claims. Rejects (throws) on: any
+   * `alg` ≠ ES256 (blocks `alg:none` and every HS*), bad signature, wrong/absent
+   * `aud`, unlisted `iss`, or expired/not-yet-valid `exp`/`iat`.
+   */
+  async verify(token: string): Promise<IdentityClaims> {
+    // Fail fast + loud on the algorithm before touching keys. jose's `algorithms`
+    // allowlist below is the authoritative guard; this makes the reason explicit.
+    const header = decodeProtectedHeader(token);
+    if (header.alg !== TOT_ALG) {
+      throw new Error(`unexpected JWT alg ${String(header.alg)}; only ${TOT_ALG} is accepted`);
+    }
+
+    const { payload } = await jwtVerify(token, this.keys, {
+      issuer: this.issuer,
+      audience: this.audience,
+      algorithms: [TOT_ALG],
+    });
+
+    return toIdentityClaims(payload as Record<string, unknown>);
+  }
+}
+
+// --- Verifier cache -----------------------------------------------------------
+//
+// In-memory, module-scoped cache keyed by (jwksUri | audience). Good enough for
+// the prototype: each Worker isolate builds its verifier once and reuses jose's
+// cached JWKS across requests. FOLLOW-UP (multi-instance): promote the JWKS cache
+// to KV or a Durable Object so isolates share fetched key material and honour a
+// single rotation signal. Tracked with the Phase-4 kernel adoption.
+const verifierCache = new Map<string, IdentityAssertionVerifier>();
+
+/**
+ * Get (or build + cache) the verifier for a resource, deriving the JWKS URL from
+ * the configured tot API base (`TOT_CORE_URL` — the same base `totAccessClient`
+ * posts the access-code endpoints to). Returns `null` when tot's base URL is not
+ * configured (routes fail closed). Pass `overrides.jwks`/`overrides.jwksUri` in
+ * tests to inject key material without a network fetch.
+ */
+export async function getIdentityVerifier(
+  resource: string,
+  overrides: { jwksUri?: string; jwks?: JSONWebKeySet; baseUrl?: string } = {},
+): Promise<IdentityAssertionVerifier | null> {
+  if (overrides.jwks) {
+    // Test / air-gapped: never cached (keys are per-test) and never networked.
+    return new IdentityAssertionVerifier({ audience: resource, jwks: overrides.jwks });
+  }
+  const jwksUri =
+    overrides.jwksUri ??
+    deriveJwksUri(overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "");
+  if (jwksUri === JWKS_PATH) return null; // empty base → unconfigured
+
+  const cacheKey = `${jwksUri}|${resource}`;
+  let v = verifierCache.get(cacheKey);
+  if (!v) {
+    v = new IdentityAssertionVerifier({ audience: resource, jwksUri });
+    verifierCache.set(cacheKey, v);
+  }
+  return v;
+}
+
+/**
+ * Get (or build + cache) the FEDERATED verifier — the one for multi-tenant
+ * sign-in. Its audience is the STOREFRONT'S OWN app identity (`STOREFRONT_APP_DOMAIN`),
+ * because tot20's federated `id_token` sets `aud` = the calling app (storefront),
+ * NOT a tenant. The token then carries ALL of the email's memberships in
+ * `tenants[]`. Returns null when the tot base URL (`TOT_CORE_URL`) or the
+ * storefront app identity (`STOREFRONT_APP_DOMAIN`) is unconfigured — the route
+ * fails closed. Pass overrides in tests to inject key material + audience.
+ */
+export async function getFederatedVerifier(
+  overrides: { jwksUri?: string; jwks?: JSONWebKeySet; baseUrl?: string; audience?: string } = {},
+): Promise<IdentityAssertionVerifier | null> {
+  const audience = overrides.audience ?? (await readEnv("STOREFRONT_APP_DOMAIN")) ?? "";
+  if (!audience) return null; // storefront's own app identity must be configured
+  if (overrides.jwks) {
+    return new IdentityAssertionVerifier({ audience, jwks: overrides.jwks });
+  }
+  const jwksUri =
+    overrides.jwksUri ??
+    deriveJwksUri(overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "");
+  if (jwksUri === JWKS_PATH) return null; // empty base → unconfigured
+  const cacheKey = `${jwksUri}|${audience}`;
+  let v = verifierCache.get(cacheKey);
+  if (!v) {
+    v = new IdentityAssertionVerifier({ audience, jwksUri });
+    verifierCache.set(cacheKey, v);
+  }
+  return v;
+}
+
+// --- Session derivation from verified claims ---------------------------------
+
+/** The session fields derived from the VERIFIED token — the Phase-3 source of truth. */
+export interface DerivedSessionFields {
+  email: string;
+  resource: string;
+  /** Coarse standing on THIS resource, surfaced as the display capability. */
+  capability: CoarseRole | "none";
+  /** Display roles derived from the coarse claim (not tot's raw app roles). */
+  roles: string[];
+  /** Full multi-tenant memberships carried in the token (policy input). */
+  tenants: TenantMembership[];
+  /** ToT-staff scope carried in the token (sandboxed; grants nothing here). */
+  staff: string[];
+}
+
+/**
+ * Derive the storefront session from VERIFIED claims for a given resource — the
+ * Phase-3 replacement for trusting tot's flat `{roles, capability}`. Picks the
+ * membership matching `resource` and collapses its coarse role to the display
+ * capability. Throws if the verified token carries no membership for `resource`
+ * (a token for another tenant must not open this gate — belt-and-braces on top
+ * of the `aud` check).
+ */
+export function sessionFromClaims(claims: IdentityClaims, resource: string): DerivedSessionFields {
+  const membership = claims.tenants.find((t) => t.resource === resource);
+  if (!membership) {
+    throw new Error(`verified assertion carries no membership for resource "${resource}"`);
+  }
+  return {
+    email: claims.email,
+    resource,
+    capability: membership.role,
+    roles: [membership.role],
+    tenants: claims.tenants,
+    staff: claims.staff,
+  };
+}
+
+/** The multi-tenant fields derived from a verified FEDERATED assertion. */
+export interface FederatedSessionFields {
+  email: string;
+  /** The verified `aud` — the storefront app identity this console session is for. */
+  resource: string;
+  /** EVERY tenant membership the token carries (the dashboard picker's input). */
+  tenants: TenantMembership[];
+  /** ToT-staff scope carried in the token (sandboxed; grants nothing here). */
+  staff: string[];
+}
+
+/**
+ * Derive the storefront CONSOLE session from a verified FEDERATED assertion. Unlike
+ * {@link sessionFromClaims}, this does NOT require (or scope to) a single tenant:
+ * it binds ALL of `claims.tenants` so a user with N memberships yields an N-vendor
+ * session. `resource` is the verified `aud` (the storefront app identity), not a
+ * tenant — it exists only to satisfy the session record shape; the dashboard reads
+ * `tenants[]`, and the tenant-scoped preview gate never matches it.
+ */
+export function sessionFromFederatedClaims(claims: IdentityClaims): FederatedSessionFields {
+  return {
+    email: claims.email,
+    resource: claims.aud,
+    tenants: claims.tenants,
+    staff: claims.staff,
+  };
+}

package/apps/storefront/src/lib/auth/loginGate.ts

@@ -0,0 +1,119 @@
+/**
+ * Login-gate decision (pure) — the "Sign in with ToT" enforcement mode for a
+ * gated demo host, the eventual replacement for the interim Basic-Auth password
+ * (see `@/lib/demoGate`). Same `DEMO_GATE_HOSTS` list, switched by `DEMO_GATE_MODE`:
+ *
+ *   DEMO_GATE_MODE = "password"  → interim Basic-Auth gate (evaluateDemoGate)
+ *   DEMO_GATE_MODE = "login"     → this: redirect to /auth/login unless a valid,
+ *                                  resource-bound tot_session cookie is present.
+ *
+ * This module is PURE (no KV, no cookies, no env I/O): the middleware reads the
+ * session (KV) and passes the resolved record in. Keeping the decision pure makes
+ * the exemption + redirect logic unit-testable and keeps the two gate modes from
+ * drifting apart. The auth surface itself (/auth/*, /api/auth/*) is always exempt
+ * so a visitor can actually sign in.
+ */
+import { hostInGateList } from "@/lib/demoGate";
+import { viewerCanAccess } from "@/lib/dashboard/tenantSelection";
+import type { SessionRecord } from "./session.js";
+
+export type GateMode = "password" | "login";
+
+/**
+ * The platform's own "self" home tenant (tenants.ts `HOME_TENANT`, registry
+ * default). It is NEVER login-gated — `storefront.tokenoftrust.store` renders its
+ * public home so people can browse + sign up. Every OTHER tenant on a gated host
+ * (path-prefix or per-tenant subdomain) is gated behind sign-in.
+ */
+export const PUBLIC_HOME_TENANT_ID = "home";
+
+/**
+ * Whether a (federated) viewer session admits the gated HOST — i.e. the signed-in
+ * user holds a membership for the host's tenant (`hostResource`, the host's
+ * appDomain). This UNIFIES the preview-host gate onto the single federated session:
+ * federated sign-in mints a multi-tenant session whose `aud`/`resource` is the
+ * storefront app (not a tenant), so the old resource-scoped session match never
+ * fit; membership in `tenants[]` is the right test. Deny-closed: no session, or a
+ * session without a membership for `hostResource`, is not admitted. (Backward-
+ * compatible with a legacy resource-scoped session, whose `tenants[]` still lists
+ * its own resource.)
+ */
+export function sessionAdmitsHost(
+  record: Pick<SessionRecord, "tenants" | "staffSelection" | "staff"> | null,
+  hostResource: string,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): boolean {
+  if (!record) return false;
+  // ToT STAFF get in everywhere: any session carrying a verified `staff` scope is
+  // admitted to EVERY gated demo host with just a login — no per-vendor selection
+  // needed. This is a GATE-level admission for demo BROWSING only; dashboard-action
+  // authorization (viewerCanAccess) stays membership/selection-bound + audited.
+  if (Array.isArray(record.staff) && record.staff.length > 0) return true;
+  // Otherwise: a membership OR a live ToT-staff selection for this exact host admits
+  // — the staff-selection path is distinct from tenants[] (never a synthesized member).
+  return viewerCanAccess(record.tenants, hostResource, {
+    selection: record.staffSelection,
+    nowSeconds,
+  });
+}
+
+/** Parse `DEMO_GATE_MODE` (default "password"). */
+export function parseGateMode(raw: string | null | undefined): GateMode {
+  return (raw ?? "").trim().toLowerCase() === "login" ? "login" : "password";
+}
+
+/**
+ * Paths that MUST stay reachable without a session, or the visitor could never
+ * authenticate: the login page and the send/verify endpoints. Everything else on
+ * a login-gated host requires a session.
+ */
+export function isAuthPath(pathname: string): boolean {
+  return pathname === "/auth/login" || pathname.startsWith("/api/auth/");
+}
+
+/**
+ * Genuinely-public API paths that must answer without a session even on a
+ * login-gated host — the CLI version-support policy is fetched by an
+ * unauthenticated `tot` install (src/pages/api/cli/policy.ts). Kept exact (not a
+ * broad `/api/cli/` prefix) so a future authed CLI endpoint isn't accidentally
+ * exposed.
+ */
+export function isPublicPath(pathname: string): boolean {
+  return pathname === "/api/cli/policy";
+}
+
+export type LoginGateDecision =
+  | { action: "pass" }
+  | { action: "redirect"; location: string };
+
+export interface LoginGateInput {
+  host: string;
+  pathname: string;
+  search: string;
+  mode: GateMode;
+  /** The gated-host list (`DEMO_GATE_HOSTS`). */
+  gatedHosts: string | null | undefined;
+  /** True when a valid, resource-bound session was resolved for this request. */
+  hasValidSession: boolean;
+  /**
+   * True when the resolved tenant is the platform's own public home (self) —
+   * exempt from the gate so it renders publicly. See {@link PUBLIC_HOME_TENANT_ID}.
+   */
+  tenantExempt?: boolean;
+}
+
+/**
+ * Decide what the login gate should do. Returns `pass` when the host isn't
+ * login-gated, the path is an auth path, or a valid session exists; otherwise a
+ * `redirect` to /auth/login carrying the intended destination as `next`.
+ */
+export function evaluateLoginGate(input: LoginGateInput): LoginGateDecision {
+  if (input.mode !== "login") return { action: "pass" };
+  if (!hostInGateList(input.host, input.gatedHosts)) return { action: "pass" };
+  if (input.tenantExempt) return { action: "pass" };
+  if (isAuthPath(input.pathname)) return { action: "pass" };
+  if (isPublicPath(input.pathname)) return { action: "pass" };
+  if (input.hasValidSession) return { action: "pass" };
+  const next = input.pathname + (input.search ?? "");
+  return { action: "redirect", location: `/auth/login?next=${encodeURIComponent(next)}` };
+}

package/apps/storefront/src/lib/auth/route.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared helpers for the `/auth/*` + `/api/auth/*` sign-in surface. Kept out of
+ * the pure session/client modules so those stay transport- and Astro-free and
+ * unit-test against the in-memory impls.
+ *
+ * The flow (no-JS-friendly, all on the tenant's own branded host):
+ *   GET  /auth/login                 → email card (step 1) / code card (step 2)
+ *   POST /api/auth/send  {email}     → tot20 sendAccessCode → 303 back to step 2
+ *   POST /api/auth/verify{email,code}→ tot20 verifyAccessCode → session cookie → 303 next
+ *
+ * The gate ("login" mode) redirects unauthenticated viewers of a gated host to
+ * /auth/login and lets a valid `tot_session` cookie back through. The `resource`
+ * (the tot20 appDomain the grant is checked against) comes from the resolved
+ * tenant — never from request input.
+ */
+import type { APIContext } from "astro";
+import { readKv } from "@/lib/env";
+import { createTotAccessClient, type TotAccessClient } from "./totAccessClient.js";
+import {
+  KvSessionStore,
+  readSession,
+  type SessionRecord,
+  type SessionStore,
+  SESSION_COOKIE,
+} from "./session.js";
+import {
+  getIdentityVerifier as buildIdentityVerifier,
+  type IdentityAssertionVerifier,
+} from "./identityToken.js";
+
+/** Permissive email shape — tot20 is the real authority on eligibility. */
+export const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * The tot20 `resource` (appDomain) the email's roles are checked against for this
+ * host. Derived from the resolved tenant, never from input.
+ *
+ * INTEGRATION NOTE: which tenant field equals tot20's appDomain for a store is
+ * confirmed at integration (task #4). We use `appDomain` (the tenant's app
+ * identity) and allow a per-tenant override via `commerce`/config later.
+ */
+export function resolveResource(context: APIContext): string | null {
+  const t = context.locals.tenant;
+  if (!t) return null;
+  return t.appDomain || t.tenant_id || null;
+}
+
+/** The access client from env, or null when the integration isn't configured. */
+export async function getAccessClient(): Promise<TotAccessClient | null> {
+  try {
+    return await createTotAccessClient();
+  } catch {
+    return null; // unconfigured → routes return 503
+  }
+}
+
+/** KV-backed session store, or null in runtimes without the SESSION binding (dev). */
+export async function getSessionStore(): Promise<SessionStore | null> {
+  const kv = await readKv("SESSION");
+  return kv ? new KvSessionStore(kv) : null;
+}
+
+/**
+ * Read the signed-in viewer's FULL session (email + all tenant memberships), or
+ * null when there's no valid session. Unlike the gate's read, this is NOT scoped
+ * to a single host `resource` — the vendor dashboard needs every membership in
+ * `tenants[]` to route (single → in, multiple → picker) and to authorize actions
+ * against the SELECTED vendor. Returns null in runtimes without the SESSION KV.
+ */
+export async function readViewerSession(
+  context: { cookies: APIContext["cookies"] },
+): Promise<SessionRecord | null> {
+  const store = await getSessionStore();
+  if (!store) return null;
+  const sid = context.cookies.get(SESSION_COOKIE)?.value ?? null;
+  return readSession(store, sid, Math.floor(Date.now() / 1000));
+}
+
+/**
+ * The session store + the current request's opaque session id, for callers that
+ * need to MUTATE the stored record (e.g. stamping a staff vendor selection). Null
+ * when there's no SESSION KV (dev) or no session cookie. Kept alongside
+ * {@link readViewerSession} so mutation and read share the same store/cookie seam.
+ */
+export async function getSessionMutationHandle(
+  context: { cookies: APIContext["cookies"] },
+): Promise<{ store: SessionStore; id: string } | null> {
+  const store = await getSessionStore();
+  if (!store) return null;
+  const id = context.cookies.get(SESSION_COOKIE)?.value ?? null;
+  if (!id) return null;
+  return { store, id };
+}
+
+/**
+ * The offline `id_token` verifier for this host's `resource`, or null when the
+ * tot JWKS host (`TOT_CORE_URL`) isn't configured. Derives the JWKS URL from the
+ * same tot API base the access-code client posts to; jose caches the fetch so
+ * verification survives tot being unreachable after sign-in (Phase-3 property).
+ */
+export async function getVerifier(resource: string): Promise<IdentityAssertionVerifier | null> {
+  return buildIdentityVerifier(resource);
+}
+
+export { getVerifier as getIdentityVerifier };
+
+/** Set the session cookie (HttpOnly/Secure/SameSite=Lax) for `maxAgeSeconds`. */
+export function setSessionCookie(context: APIContext, id: string, maxAgeSeconds: number): void {
+  context.cookies.set(SESSION_COOKIE, id, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/",
+    maxAge: maxAgeSeconds,
+  });
+}
+
+/** Clear the session cookie (logout). */
+export function clearSessionCookie(context: APIContext): void {
+  context.cookies.delete(SESSION_COOKIE, { path: "/" });
+}
+
+/**
+ * Sanitize a `next` redirect target to a same-origin PATH only (starts with a
+ * single "/", not "//" or a scheme) — closes the open-redirect hole. Falls back
+ * to "/".
+ */
+export function safeNext(next: string | null | undefined): string {
+  if (!next) return "/";
+  if (!next.startsWith("/") || next.startsWith("//")) return "/";
+  return next;
+}
+
+/** Redirect back to the login page carrying step-2 state (email/error), no-JS-safe. */
+export function loginRedirect(
+  context: APIContext,
+  params: { sent?: boolean; email?: string; error?: string; next?: string },
+): Response {
+  const q = new URLSearchParams();
+  if (params.sent) q.set("sent", "1");
+  if (params.email) q.set("email", params.email);
+  if (params.error) q.set("error", params.error);
+  if (params.next && params.next !== "/") q.set("next", params.next);
+  const qs = q.toString();
+  return context.redirect(`/auth/login${qs ? `?${qs}` : ""}`, 303);
+}