@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,203 @@
+/**
+ * Signed-in viewer session for the demo access gate (Track: "Sign in with ToT").
+ *
+ * After a visitor verifies a one-time email code (tot20 `verifyAccessCode`), we
+ * hold a server-side session so the gate can let them back in without re-auth.
+ * The session is **KV-backed** (revocable + no signing-key handling): the cookie
+ * carries only an opaque random id; the record (email, resource, roles) lives in
+ * the `SESSION` KV namespace with a TTL. Deleting the KV entry (or letting it
+ * expire) revokes access — a static bearer password can't do that.
+ *
+ * Renderer-agnostic and runtime-portable (WebCrypto + a small store seam). The
+ * store is an interface so routes/gate use `KvSessionStore` in the worker and an
+ * in-memory impl in tests. Nothing here reads env or touches cookies — the
+ * routes own cookie I/O (via Astro `context.cookies`) and the gate owns the
+ * host↔resource check.
+ */
+
+/** The cookie the browser carries; value is an opaque session id (not the record). */
+export const SESSION_COOKIE = "tot_session";
+
+/**
+ * A ToT-staff viewer's ACTIVE vendor selection — the two-phase-admission marker
+ * (#8425 staff cross-vendor access). This is a DISTINCT access path from
+ * `tenants[]`: a staff user isn't a member of a bounded set of vendors, so we
+ * NEVER synthesize a `tenants[]` entry for them. Instead, after the staff viewer
+ * explicitly searches + enters a vendor and tot20's `staffVendorAccess` writes
+ * the server-side audit row, we stamp THIS marker on the session (KV) scoped to
+ * the returned staffRoles `capability` and a short `exp`. The dashboard guard and
+ * login gate consult it as a separate branch from membership.
+ */
+export interface StaffSelection {
+  /** The vendor appDomain the staff viewer was admitted to (exact match only). */
+  resource: string;
+  /** staffRoles-scoped capability tot20 returned for this admission. */
+  capability: string;
+  /** Expiry (epoch seconds) — short-lived; re-checked on every gate/guard read. */
+  exp: number;
+}
+
+/** Default session lifetime — a demo viewing session, revocable via KV. */
+export const DEFAULT_SESSION_TTL_SECONDS = 7 * 24 * 3600;
+
+/**
+ * What we know about a signed-in viewer.
+ *
+ * Phase 3: `email`/`resource`/`roles`/`capability` are now derived from tot's
+ * OFFLINE-VERIFIED `id_token` claims (see `@/lib/auth/identityToken`
+ * `sessionFromClaims`), not from trusting tot's flat `/verify` JSON. `capability`
+ * is the coarse standing on `resource` (owner|admin|member). `tenants`/`staff`
+ * are the multi-tenant claims carried in the verified token (present when the
+ * session was minted via the Phase-3 path; optional for backward compatibility).
+ */
+export interface SessionRecord {
+  /** Verified email (lowercased) — the principal that passed the grant check. */
+  email: string;
+  /** The resource (appDomain/tenant, e.g. "sample-store.example") this session authorizes. */
+  resource: string;
+  /** Display roles for `resource` (Phase 3: the coarse role from verified claims). */
+  roles: string[];
+  /** Coarse capability on `resource` (owner|admin|member; legacy: developer|inviter|staff|none). */
+  capability: string;
+  /** All tenant memberships from the verified assertion (policy input). Phase-3 path only. */
+  tenants?: { resource: string; role: string }[];
+  /** ToT-staff scope from the verified assertion (sandboxed; grants nothing today). Phase-3 path only. */
+  staff?: string[];
+  /**
+   * A staff viewer's active, explicitly-entered vendor selection (the two-phase
+   * admission marker). Present ONLY after `/api/dashboard/enter-vendor` succeeds;
+   * DISTINCT from `tenants[]` — never a synthesized membership. See {@link StaffSelection}.
+   */
+  staffSelection?: StaffSelection;
+  /** Issued-at, epoch seconds. */
+  createdAt: number;
+  /** Expiry, epoch seconds. The store TTL mirrors this; we re-check on read. */
+  exp: number;
+}
+
+/** Minimal KV-ish seam so this unit-tests without a live KVNamespace. */
+export interface SessionStore {
+  put(id: string, value: string, ttlSeconds: number): Promise<void>;
+  get(id: string): Promise<string | null>;
+  delete(id: string): Promise<void>;
+}
+
+/** Namespacing so session ids never collide with other SESSION-KV keys. */
+const KEY_PREFIX = "authsession:";
+
+/** A `SessionStore` over a Cloudflare `KVNamespace` (the `SESSION` binding). */
+export class KvSessionStore implements SessionStore {
+  constructor(private readonly kv: KVNamespace) {}
+  async put(id: string, value: string, ttlSeconds: number): Promise<void> {
+    // KV requires expirationTtl >= 60; clamp so short TTLs in tests/dev don't throw.
+    await this.kv.put(KEY_PREFIX + id, value, {
+      expirationTtl: Math.max(60, Math.floor(ttlSeconds)),
+    });
+  }
+  async get(id: string): Promise<string | null> {
+    return this.kv.get(KEY_PREFIX + id);
+  }
+  async delete(id: string): Promise<void> {
+    await this.kv.delete(KEY_PREFIX + id);
+  }
+}
+
+/** A cryptographically-random, URL-safe session id (128 bits). */
+export function newSessionId(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Create a session for a verified viewer: mint an id, persist the record with a
+ * matching TTL, return the id (the caller sets it as the cookie). `nowSeconds`
+ * is injected so this stays pure/testable.
+ */
+export async function createSession(
+  store: SessionStore,
+  fields: Omit<SessionRecord, "createdAt" | "exp">,
+  ttlSeconds: number,
+  nowSeconds: number,
+): Promise<{ id: string; record: SessionRecord }> {
+  const record: SessionRecord = {
+    ...fields,
+    email: fields.email.toLowerCase(),
+    createdAt: nowSeconds,
+    exp: nowSeconds + ttlSeconds,
+  };
+  const id = newSessionId();
+  await store.put(id, JSON.stringify(record), ttlSeconds);
+  return { id, record };
+}
+
+/**
+ * Read + validate a session by id. Returns the record only when it exists, is
+ * well-formed, has not expired, and (when `resource` is given) authorizes THAT
+ * resource — so a session minted for tenant A can never open tenant B's gate.
+ * A malformed or expired record is best-effort deleted.
+ */
+export async function readSession(
+  store: SessionStore,
+  id: string | null | undefined,
+  nowSeconds: number,
+  resource?: string,
+): Promise<SessionRecord | null> {
+  if (!id) return null;
+  const raw = await store.get(id);
+  if (!raw) return null;
+  let record: SessionRecord;
+  try {
+    record = JSON.parse(raw) as SessionRecord;
+  } catch {
+    await store.delete(id);
+    return null;
+  }
+  if (
+    !record ||
+    typeof record.email !== "string" ||
+    typeof record.resource !== "string" ||
+    typeof record.exp !== "number"
+  ) {
+    await store.delete(id);
+    return null;
+  }
+  if (record.exp <= nowSeconds) {
+    await store.delete(id);
+    return null;
+  }
+  if (resource && record.resource !== resource) return null;
+  return record;
+}
+
+/**
+ * Read a session, apply `mutate`, and re-persist it under the SAME id with the
+ * record's REMAINING lifetime (`exp - now`) as the store TTL — so stamping a
+ * staff selection (or any field) never extends the session past its original
+ * expiry. Returns the updated record, or null when there's no valid session to
+ * mutate (expired/missing/malformed are handled by {@link readSession}). The
+ * caller must NOT change `exp` in `mutate` unless it also intends to change TTL.
+ */
+export async function updateSession(
+  store: SessionStore,
+  id: string | null | undefined,
+  mutate: (record: SessionRecord) => SessionRecord,
+  nowSeconds: number,
+): Promise<SessionRecord | null> {
+  const current = await readSession(store, id, nowSeconds);
+  if (!current || !id) return null;
+  const next = mutate({ ...current });
+  const ttl = Math.max(1, next.exp - nowSeconds);
+  await store.put(id, JSON.stringify(next), ttl);
+  return next;
+}
+
+/** Revoke a session (logout / admin kill). Idempotent. */
+export async function revokeSession(
+  store: SessionStore,
+  id: string | null | undefined,
+): Promise<void> {
+  if (id) await store.delete(id);
+}