@tokenoftrust/storefront-runner 0.1.0

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

@@ -0,0 +1,107 @@
+/**
+ * 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/");
+}
+
+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 (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);
+}

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. "bigdvapor") 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);
+}