@graph8/sdk 0.370.0 → 0.374.0

package/blocks/_foundation/server/auth.ts

@@ -0,0 +1,815 @@
+/**
+ * Ready-made `authorize` hooks for the proxy route (./proxy.ts), so a generated app can go live with sign-in
+ * instead of "bring your own auth". Every preset is OPTIONAL: `createG8Proxy({ authorize })` takes any function,
+ * and without one the proxy behaves exactly as before (local preview in `next dev`, 500 in a production build).
+ *
+ *   g8.auth.ts                     export const appAuth = sharedPassword();   (presets come from this file)
+ *   app/api/g8/[...path]/route.ts  createG8Proxy({ ..., authorize: appAuth.authorize })
+ *   app/api/g8-auth/route.ts       export const { GET, POST, DELETE } = createG8AuthRoute(appAuth);   (sign-in screen)
+ *
+ * Presets (all read their settings from the SERVER environment; nothing here is sent to the browser):
+ *   - sharedPassword(): one password for the whole team. POST /api/g8-auth signs in and sets an HttpOnly,
+ *     SameSite=Lax session cookie signed with HMAC-SHA-256. Env: G8_APP_PASSWORD (12+ characters) and
+ *     G8_SESSION_SECRET (32+ characters). Changing either signs everyone out.
+ *   - basicAuth(): HTTP Basic auth from G8_BASIC_AUTH ("user:password", comma-separated for several users).
+ *     Pair it with middleware.ts so the browser asks once for the whole site.
+ *   - jwtAuth(): verify a JWT from your identity provider (OIDC: Auth0, Okta, Cognito, Keycloak, Clerk, Supabase,
+ *     ...) with its JWKS (RS256/PS256/ES256 family), or a shared HS256 secret. Reads the Bearer header and/or a
+ *     cookie; checks exp/nbf, issuer and audience.
+ *   - sessionAuth(fn): adapter for any session library: Clerk `auth()`, NextAuth `auth()`, Supabase
+ *     `getUser()`, iron-session... Return a user (anything truthy) to allow, null/undefined to refuse.
+ *   - allowAnonymous(): an explicit "anyone may use this app's key" choice (a public demo). Logs a loud warning
+ *     and `npx @graph8/sdk doctor` flags it.
+ *
+ * Security model: secrets and passwords are compared in constant time (HMAC both sides, then compare the
+ * digests); cookie-based presets refuse cross-site writes (CSRF) by checking Sec-Fetch-Site and Origin; tokens
+ * with alg "none", an unexpected alg, a key of the wrong type, `crit` headers, or no `exp` are refused. Sign-in
+ * attempts are rate limited per client in memory (best effort on serverless: use a long password). Every
+ * refusal is a JSON 401/403/429; a missing setting is a JSON 500 that names the variable, never its value.
+ *
+ * Settings: sharedPassword and basicAuth read the environment on every request; jwtAuth and sessionAuth read it
+ * once, when the preset is created (module load in Next). Restart the server after changing them.
+ *
+ * Plain Web APIs (fetch, crypto.subtle, TextEncoder), no dependencies: runs on the Node and Edge runtimes.
+ */
+
+export type AuthKind = "password" | "basic" | "jwt" | "session" | "anonymous";
+
+/** What the sign-in screen (components/auth-gate.tsx) needs to know. Never contains a secret. */
+export interface AuthStatus {
+  kind: AuthKind;
+  signedIn: boolean;
+  /** Where to send the user to sign in (jwt and session presets; G8_SIGN_IN_URL). */
+  signInUrl?: string;
+  /** Where to send the user to sign out (G8_SIGN_OUT_URL). */
+  signOutUrl?: string;
+  /** Set when the server is missing a setting: what to set, never a value. */
+  problem?: string;
+}
+
+export interface G8AppAuth {
+  kind: AuthKind;
+  /** Pass to `createG8Proxy({ authorize })`. A plain function: safe to pass unbound. */
+  authorize: (request: Request) => Promise<Response | void>;
+  /** For the sign-in screen. */
+  status: (request: Request) => Promise<AuthStatus>;
+  /** POST /api/g8-auth (sharedPassword only). */
+  signIn?: (request: Request) => Promise<Response>;
+  /** DELETE /api/g8-auth (sharedPassword only). */
+  signOut?: (request: Request) => Promise<Response>;
+}
+
+type Env = Record<string, string | undefined>;
+const readEnv = (): Env => (typeof process !== "undefined" && process.env ? process.env : {});
+const isProduction = (): boolean => readEnv().NODE_ENV === "production";
+
+function json(status: number, body: Record<string, unknown>, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store", ...headers } });
+}
+
+const unauthenticated = (message = "Sign in to use this app.") => json(401, { error: "unauthenticated", message });
+const misconfigured = (message: string) => json(500, { error: "g8_auth_misconfigured", message });
+
+// ---------------------------------------------------------------------------------------------------------------
+// Bytes, base64url, constant time
+// ---------------------------------------------------------------------------------------------------------------
+
+const enc = new TextEncoder();
+
+function b64urlEncode(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Null on anything that is not strict base64url. */
+function b64urlDecode(text: string): Uint8Array | null {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
+  try {
+    const bin = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `as BufferSource` below: TypeScript 5.7+ types a plain Uint8Array as possibly SharedArrayBuffer-backed, which
+ * WebCrypto's signatures reject at compile time; every array here is a fresh, non-shared buffer.
+ */
+
+/** Constant time for equal lengths; a length mismatch is false (lengths are not secret here: digests). */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+async function hmacKey(secret: string | Uint8Array, hash = "SHA-256"): Promise<CryptoKey> {
+  const raw = typeof secret === "string" ? enc.encode(secret) : secret;
+  return crypto.subtle.importKey("raw", raw as BufferSource, { name: "HMAC", hash }, false, ["sign", "verify"]);
+}
+
+async function hmac(key: CryptoKey, data: string | Uint8Array): Promise<Uint8Array> {
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, (typeof data === "string" ? enc.encode(data) : data) as BufferSource));
+}
+
+/** A per-process random key: comparing HMACs of two strings hides their length and content from timing. */
+let compareKey: Promise<CryptoKey> | null = null;
+function getCompareKey(): Promise<CryptoKey> {
+  compareKey ??= hmacKey(crypto.getRandomValues(new Uint8Array(32)));
+  return compareKey;
+}
+
+/** Constant-time string equality (any lengths). */
+export async function safeEqual(a: string, b: string): Promise<boolean> {
+  const key = await getCompareKey();
+  const [x, y] = await Promise.all([hmac(key, a), hmac(key, b)]);
+  return timingSafeEqual(x, y);
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Request helpers: cookies, CSRF, client id, rate limit
+// ---------------------------------------------------------------------------------------------------------------
+
+export function readCookie(request: Request, name: string): string | undefined {
+  const header = request.headers.get("cookie");
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const i = part.indexOf("=");
+    if (i < 0) continue;
+    if (part.slice(0, i).trim() === name) {
+      const v = part.slice(i + 1).trim();
+      try {
+        return decodeURIComponent(v);
+      } catch {
+        return v;
+      }
+    }
+  }
+  return undefined;
+}
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * True when a request may come from another site: Sec-Fetch-Site says cross-site/same-site, or Origin is
+ * present and is not this request's own origin. Cookie-based presets refuse such writes (CSRF).
+ */
+export function isCrossSite(request: Request): boolean {
+  const site = request.headers.get("sec-fetch-site");
+  if (site && site !== "same-origin" && site !== "none") return true;
+  const origin = request.headers.get("origin");
+  if (!origin) return false;
+  if (origin === "null") return true;
+  const host = request.headers.get("x-forwarded-host")?.split(",")[0]?.trim() || request.headers.get("host") || new URL(request.url).host;
+  try {
+    return new URL(origin).host.toLowerCase() !== host.toLowerCase();
+  } catch {
+    return true;
+  }
+}
+
+const crossSite = () => json(403, { error: "cross_site_request", message: "Refused a request from another site." });
+
+function clientId(request: Request): string {
+  const fwd = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+  return fwd || request.headers.get("x-real-ip") || "local";
+}
+
+function isHttps(request: Request): boolean {
+  const proto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+  return proto === "https" || new URL(request.url).protocol === "https:" || isProduction();
+}
+
+/** Fixed-window attempt counter per client, bounded in size. Best effort: one process only. */
+export function createRateLimiter(limit: number, windowMs: number, maxKeys = 10_000) {
+  const hits = new Map<string, { count: number; reset: number }>();
+  return {
+    /** Seconds to wait, or 0 when this attempt is allowed. */
+    take(key: string, now = Date.now()): number {
+      let h = hits.get(key);
+      if (!h || h.reset <= now) {
+        if (hits.size >= maxKeys) hits.delete(hits.keys().next().value as string);
+        h = { count: 0, reset: now + windowMs };
+        hits.set(key, h);
+      }
+      h.count += 1;
+      return h.count > limit ? Math.ceil((h.reset - now) / 1000) : 0;
+    },
+    /** Seconds to wait if the limit is already used up, without counting an attempt. */
+    peek(key: string, now = Date.now()): number {
+      const h = hits.get(key);
+      return h && h.reset > now && h.count >= limit ? Math.ceil((h.reset - now) / 1000) : 0;
+    },
+    clear(key: string): void {
+      hits.delete(key);
+    },
+  };
+}
+
+const MAX_SIGN_IN_BODY = 4096;
+
+/** The body as text, or null when it is larger than `max` bytes (stops reading as soon as it passes). */
+async function readTextCapped(request: Request, max: number): Promise<string | null> {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > max) return null;
+  if (!request.body) return "";
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > max) {
+      await reader.cancel().catch(() => undefined);
+      return null;
+    }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(total);
+  let at = 0;
+  for (const c of chunks) {
+    all.set(c, at);
+    at += c.byteLength;
+  }
+  return new TextDecoder().decode(all);
+}
+
+async function readJsonOrForm(request: Request): Promise<Record<string, unknown>> {
+  const type = request.headers.get("content-type") ?? "";
+  const text = await readTextCapped(request, MAX_SIGN_IN_BODY).catch(() => null);
+  if (text === null) return {};
+  if (type.includes("application/x-www-form-urlencoded")) return Object.fromEntries(new URLSearchParams(text));
+  try {
+    const v = JSON.parse(text) as unknown;
+    return v && typeof v === "object" ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function urlSetting(value: string | undefined): string | undefined {
+  const v = value?.trim();
+  if (!v) return undefined;
+  if (v.startsWith("/") && !v.startsWith("//")) return v;
+  return /^https?:\/\/[^\s]+$/i.test(v) ? v : undefined;
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// sharedPassword
+// ---------------------------------------------------------------------------------------------------------------
+
+export interface SharedPasswordOptions {
+  /** Default: G8_APP_PASSWORD. At least 12 characters. */
+  password?: string;
+  /** Signs the session cookie. Default: G8_SESSION_SECRET. At least 32 characters. */
+  secret?: string;
+  /** Session length in seconds. Default 7 days. */
+  maxAgeSeconds?: number;
+  /** Default "g8_session". */
+  cookieName?: string;
+  /** Sign-in attempts per client per 15 minutes. Default 10. */
+  maxAttempts?: number;
+  /**
+   * WRONG passwords from all clients together per 15 minutes before NEW sign-ins pause for everyone. Default 100.
+   * The per-client limit keys on X-Forwarded-For, which a client can rotate; this one cannot be dodged. Trade-off:
+   * anyone who can reach the sign-in route can keep new sign-ins paused by sending wrong passwords (existing
+   * sessions keep working). With a long random password (create generates 144 bits) you can raise it, or set
+   * `Infinity` to turn it off.
+   */
+  maxFailuresGlobal?: number;
+}
+
+export const MIN_PASSWORD = 12;
+export const MIN_SECRET = 32;
+const SESSION_VERSION = "v1";
+
+function passwordSettings(o: SharedPasswordOptions): { password: string; secret: string } | string {
+  const env = readEnv();
+  const password = o.password ?? env.G8_APP_PASSWORD ?? "";
+  const secret = o.secret ?? env.G8_SESSION_SECRET ?? "";
+  const missing: string[] = [];
+  if (password.length < MIN_PASSWORD) missing.push(`G8_APP_PASSWORD (${MIN_PASSWORD}+ characters)`);
+  if (secret.length < MIN_SECRET) missing.push(`G8_SESSION_SECRET (${MIN_SECRET}+ random characters, e.g. \`openssl rand -base64 48\`)`);
+  return missing.length ? `Set ${missing.join(" and ")} in the server environment, then restart.` : { password, secret };
+}
+
+/** The signing key depends on the password too, so changing the password ends every session. */
+async function sessionKey(secret: string, password: string): Promise<CryptoKey> {
+  const material = await hmac(await hmacKey(secret), `g8-session-key\u0000${password}`);
+  return hmacKey(material);
+}
+
+export async function createSessionToken(secret: string, password: string, maxAgeSeconds: number, now = Date.now()): Promise<string> {
+  const exp = Math.floor(now / 1000) + maxAgeSeconds;
+  const nonce = b64urlEncode(crypto.getRandomValues(new Uint8Array(16)));
+  const body = `${SESSION_VERSION}.${exp}.${nonce}`;
+  const sig = b64urlEncode(await hmac(await sessionKey(secret, password), body));
+  return `${body}.${sig}`;
+}
+
+export async function verifySessionToken(token: string | undefined, secret: string, password: string, now = Date.now()): Promise<boolean> {
+  if (!token || token.length > 512) return false;
+  const parts = token.split(".");
+  if (parts.length !== 4 || parts[0] !== SESSION_VERSION || !/^\d{1,12}$/.test(parts[1])) return false;
+  const sig = b64urlDecode(parts[3]);
+  if (!sig) return false;
+  const expected = await hmac(await sessionKey(secret, password), parts.slice(0, 3).join("."));
+  if (!timingSafeEqual(sig, expected)) return false;
+  return Number(parts[1]) > Math.floor(now / 1000);
+}
+
+function sessionCookie(name: string, value: string, maxAge: number, request: Request): string {
+  const attrs = [`${name}=${value}`, "Path=/", "HttpOnly", "SameSite=Lax", `Max-Age=${maxAge}`];
+  if (isHttps(request)) attrs.push("Secure");
+  return attrs.join("; ");
+}
+
+/** One shared password for the whole team, with a signed session cookie and a sign-in screen. */
+export function sharedPassword(options: SharedPasswordOptions = {}): G8AppAuth {
+  const cookieName = options.cookieName ?? "g8_session";
+  const maxAge = options.maxAgeSeconds ?? 7 * 24 * 3600;
+  const limiter = createRateLimiter(options.maxAttempts ?? 10, 15 * 60 * 1000);
+  const failures = createRateLimiter(options.maxFailuresGlobal ?? 100, 15 * 60 * 1000);
+  const GLOBAL = "*";
+
+  const signedIn = async (request: Request, s: { password: string; secret: string }) =>
+    verifySessionToken(readCookie(request, cookieName), s.secret, s.password);
+
+  return {
+    kind: "password",
+    async authorize(request) {
+      const s = passwordSettings(options);
+      if (typeof s === "string") return misconfigured(s);
+      if (!(await signedIn(request, s))) return unauthenticated("Your session ended. Sign in again.");
+      if (!SAFE_METHODS.has(request.method.toUpperCase()) && isCrossSite(request)) return crossSite();
+    },
+    async status(request) {
+      const s = passwordSettings(options);
+      if (typeof s === "string") return { kind: "password", signedIn: false, problem: s };
+      return { kind: "password", signedIn: await signedIn(request, s) };
+    },
+    async signIn(request) {
+      if (isCrossSite(request)) return crossSite();
+      const s = passwordSettings(options);
+      if (typeof s === "string") return misconfigured(s);
+      const id = clientId(request);
+      const wait = Math.max(limiter.take(id), failures.peek(GLOBAL));
+      if (wait > 0) return json(429, { error: "too_many_attempts", message: `Too many attempts. Try again in ${Math.ceil(wait / 60)} min.`, retryAfter: wait }, { "retry-after": String(wait) });
+      const body = await readJsonOrForm(request);
+      const given = typeof body.password === "string" ? body.password : "";
+      if (!given || !(await safeEqual(given, s.password))) {
+        failures.take(GLOBAL);
+        return json(401, { error: "wrong_password", message: "That password is not right." });
+      }
+      limiter.clear(id);
+      const token = await createSessionToken(s.secret, s.password, maxAge);
+      return json(200, { kind: "password", signedIn: true }, { "set-cookie": sessionCookie(cookieName, token, maxAge, request) });
+    },
+    async signOut(request) {
+      if (isCrossSite(request)) return crossSite();
+      return json(200, { kind: "password", signedIn: false }, { "set-cookie": sessionCookie(cookieName, "", 0, request) });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// basicAuth
+// ---------------------------------------------------------------------------------------------------------------
+
+export interface BasicAuthOptions {
+  /**
+   * "user:password" pairs, comma-separated (so a password cannot contain a comma; such an entry is ignored, as is
+   * one with a password under 12 characters). Default: G8_BASIC_AUTH, read on every request.
+   */
+  credentials?: string;
+  /** Shown by the browser's prompt. Default "app". */
+  realm?: string;
+  /** WRONG credentials per client per 15 minutes before that client gets 429. Default 20. */
+  maxFailures?: number;
+}
+
+function parseCredentials(text: string): { user: string; pass: string }[] {
+  return text
+    .split(",")
+    .map((pair) => pair.trim())
+    .filter(Boolean)
+    .map((pair) => ({ user: pair.slice(0, pair.indexOf(":")), pass: pair.slice(pair.indexOf(":") + 1) }))
+    .filter((c) => c.user && c.pass && c.pass.length >= MIN_PASSWORD);
+}
+
+/** HTTP Basic auth: the browser prompts once (use with middleware.ts so pages ask too). */
+export function basicAuth(options: BasicAuthOptions = {}): G8AppAuth {
+  const realm = (options.realm ?? "app").replace(/["\\]/g, "");
+  const settings = () => parseCredentials(options.credentials ?? readEnv().G8_BASIC_AUTH ?? "");
+  const problem = `Set G8_BASIC_AUTH to user:password (${MIN_PASSWORD}+ character passwords without commas; comma-separated for several users) in the server environment.`;
+  const failures = createRateLimiter(options.maxFailures ?? 20, 15 * 60 * 1000);
+  /** "none" when no Basic header was sent (the browser has not asked yet), else whether it matches. */
+  const check = async (request: Request): Promise<"none" | "ok" | "bad"> => {
+    const header = request.headers.get("authorization") ?? "";
+    if (!/^Basic\s/i.test(header.trim())) return "none";
+    const m = /^Basic\s+([A-Za-z0-9+/=]+)$/i.exec(header.trim());
+    if (!m) return "bad";
+    let decoded: string;
+    try {
+      decoded = new TextDecoder().decode(Uint8Array.from(atob(m[1]), (c) => c.charCodeAt(0)));
+    } catch {
+      return "bad";
+    }
+    const i = decoded.indexOf(":");
+    if (i <= 0) return "bad";
+    const user = decoded.slice(0, i);
+    const pass = decoded.slice(i + 1);
+    // Compare against EVERY entry, no early exit, so timing does not reveal which user exists.
+    let ok = false;
+    for (const c of settings()) {
+      const [u, p] = await Promise.all([safeEqual(user, c.user), safeEqual(pass, c.pass)]);
+      ok = (u && p) || ok;
+    }
+    return ok ? "ok" : "bad";
+  };
+  return {
+    kind: "basic",
+    async authorize(request) {
+      if (!settings().length) return misconfigured(problem);
+      const id = clientId(request);
+      const wait = failures.peek(id);
+      if (wait > 0) return json(429, { error: "too_many_attempts", message: `Too many attempts. Try again in ${Math.ceil(wait / 60)} min.`, retryAfter: wait }, { "retry-after": String(wait) });
+      const result = await check(request);
+      if (result === "bad") failures.take(id);
+      if (result !== "ok") {
+        return new Response(JSON.stringify({ error: "unauthenticated", message: "Sign in to use this app." }), {
+          status: 401,
+          headers: { "content-type": "application/json", "www-authenticate": `Basic realm="${realm}", charset="UTF-8"`, "cache-control": "no-store" },
+        });
+      }
+      // Browsers attach cached Basic credentials to cross-site form posts too (ambient, like a cookie): CSRF.
+      if (!SAFE_METHODS.has(request.method.toUpperCase()) && isCrossSite(request)) return crossSite();
+    },
+    async status(request) {
+      if (!settings().length) return { kind: "basic", signedIn: false, problem };
+      return { kind: "basic", signedIn: (await check(request)) === "ok" };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// jwtAuth
+// ---------------------------------------------------------------------------------------------------------------
+
+export interface JwtAuthOptions {
+  /** HS256/384/512 shared secret. Default: G8_JWT_SECRET. Use this OR jwksUrl/issuer discovery. */
+  secret?: string;
+  /** The provider's JWKS. Default: G8_JWT_JWKS_URL, else discovered from `${issuer}/.well-known/openid-configuration`. */
+  jwksUrl?: string;
+  /** Expected `iss`. Default: G8_JWT_ISSUER. Required with a JWKS. */
+  issuer?: string;
+  /** Expected `aud` (one of). Default: G8_JWT_AUDIENCE (comma-separated). Required when the issuer is shared by many apps (Google). */
+  audience?: string | string[];
+  /** Cookie holding the token (e.g. "__session" for Clerk). Default: G8_JWT_COOKIE. */
+  cookie?: string;
+  /** Also accept `Authorization: Bearer <token>`. Default true. */
+  bearer?: boolean;
+  /** Allowed algorithms. Default: HS256 with a secret; RS256, PS256 and ES256 with a JWKS. */
+  algorithms?: string[];
+  /** Seconds of clock skew allowed on exp/nbf. Default 30. */
+  clockToleranceSeconds?: number;
+  /** Extra check on the verified claims (a role, an email domain). Return false to refuse. */
+  claims?: (claims: Record<string, unknown>) => boolean | Promise<boolean>;
+  /** Default: G8_SIGN_IN_URL. */
+  signInUrl?: string;
+  /** Default: G8_SIGN_OUT_URL. */
+  signOutUrl?: string;
+  /** Replace fetch (tests). */
+  fetch?: typeof fetch;
+}
+
+type Jwk = JsonWebKey & { kid?: string; use?: string; alg?: string };
+
+const ALGS: Record<string, { family: "HS" | "RS" | "PS" | "ES"; hash: string; crv?: string; saltLength?: number }> = {
+  HS256: { family: "HS", hash: "SHA-256" },
+  HS384: { family: "HS", hash: "SHA-384" },
+  HS512: { family: "HS", hash: "SHA-512" },
+  RS256: { family: "RS", hash: "SHA-256" },
+  RS384: { family: "RS", hash: "SHA-384" },
+  RS512: { family: "RS", hash: "SHA-512" },
+  PS256: { family: "PS", hash: "SHA-256", saltLength: 32 },
+  PS384: { family: "PS", hash: "SHA-384", saltLength: 48 },
+  PS512: { family: "PS", hash: "SHA-512", saltLength: 64 },
+  ES256: { family: "ES", hash: "SHA-256", crv: "P-256" },
+  ES384: { family: "ES", hash: "SHA-384", crv: "P-384" },
+};
+
+const MAX_TOKEN = 16 * 1024;
+const JWKS_TTL = 10 * 60 * 1000;
+const JWKS_MIN_REFRESH = 30 * 1000;
+
+function remoteUrlOk(url: string): boolean {
+  try {
+    const u = new URL(url);
+    return u.protocol === "https:" || (u.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname));
+  } catch {
+    return false;
+  }
+}
+
+async function fetchJson(doFetch: typeof fetch, url: string): Promise<Record<string, unknown>> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 5000);
+  try {
+    const res = await doFetch(url, { headers: { accept: "application/json" }, redirect: "error", signal: ctrl.signal, cache: "no-store" });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return (await res.json()) as Record<string, unknown>;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function decodeSegment(seg: string): Record<string, unknown> | null {
+  const bytes = b64urlDecode(seg);
+  if (!bytes) return null;
+  try {
+    const v = JSON.parse(new TextDecoder().decode(bytes)) as unknown;
+    return v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function keyMatches(jwk: Jwk, alg: string): boolean {
+  const spec = ALGS[alg];
+  if (jwk.use && jwk.use !== "sig") return false;
+  if (jwk.alg && jwk.alg !== alg) return false;
+  if (spec.family === "ES") return jwk.kty === "EC" && jwk.crv === spec.crv;
+  return jwk.kty === "RSA";
+}
+
+function importParams(alg: string): { importAlg: RsaHashedImportParams | EcKeyImportParams; verifyAlg: AlgorithmIdentifier | RsaPssParams | EcdsaParams } {
+  const spec = ALGS[alg];
+  if (spec.family === "RS") return { importAlg: { name: "RSASSA-PKCS1-v1_5", hash: spec.hash }, verifyAlg: { name: "RSASSA-PKCS1-v1_5" } };
+  if (spec.family === "PS") return { importAlg: { name: "RSA-PSS", hash: spec.hash }, verifyAlg: { name: "RSA-PSS", saltLength: spec.saltLength as number } };
+  return { importAlg: { name: "ECDSA", namedCurve: spec.crv as string }, verifyAlg: { name: "ECDSA", hash: spec.hash } };
+}
+
+/** Verify a JWT: alg allow-list, signature, exp/nbf, iss, aud. Returns the claims or null. Exported for tests. */
+export function createJwtVerifier(options: JwtAuthOptions = {}) {
+  const env = readEnv();
+  const secret = options.secret ?? env.G8_JWT_SECRET;
+  const issuer = (options.issuer ?? env.G8_JWT_ISSUER)?.trim() || undefined;
+  const audRaw = options.audience ?? env.G8_JWT_AUDIENCE;
+  const audience = (Array.isArray(audRaw) ? audRaw : (audRaw ?? "").split(",")).map((a) => a.trim()).filter(Boolean);
+  const configuredJwks = (options.jwksUrl ?? env.G8_JWT_JWKS_URL)?.trim() || undefined;
+  const tolerance = options.clockToleranceSeconds ?? 30;
+  const doFetch = options.fetch ?? ((...a: Parameters<typeof fetch>) => globalThis.fetch(...a));
+
+  let problem: string | null = null;
+  if (secret && configuredJwks) problem = "Set G8_JWT_SECRET or G8_JWT_JWKS_URL, not both.";
+  else if (!secret && !configuredJwks && !issuer) problem = "Set G8_JWT_JWKS_URL and G8_JWT_ISSUER (your identity provider), or G8_JWT_SECRET (HS256), in the server environment.";
+  else if (!secret && !issuer) problem = "Set G8_JWT_ISSUER too: a JWKS alone would accept tokens your provider issued for any app.";
+  else if (secret && secret.length < MIN_SECRET) problem = `G8_JWT_SECRET must be at least ${MIN_SECRET} characters.`;
+  else if (configuredJwks && !remoteUrlOk(configuredJwks)) problem = "G8_JWT_JWKS_URL must be an https:// URL.";
+  else if (!secret && !configuredJwks && issuer && !remoteUrlOk(issuer)) problem = "G8_JWT_ISSUER must be an https:// URL to discover its keys (or set G8_JWT_JWKS_URL).";
+
+  // Issuer alone accepts any token that issuer minted, for ANY app on a shared tenant (Auth0, Cognito, Okta).
+  if (!problem && !secret && !audience.length && !options.claims) {
+    console.warn(
+      "[graph8] jwtAuth: no audience (G8_JWT_AUDIENCE) and no claims check. Tokens the issuer minted for other apps on the same tenant will be accepted. Set G8_JWT_AUDIENCE, or pass jwtAuth({ claims }) (e.g. Clerk: check azp).",
+    );
+  }
+
+  const algorithms = (options.algorithms ?? (secret ? ["HS256"] : ["RS256", "PS256", "ES256"])).filter((a) => a in ALGS);
+  // A secret allows HS* only; a JWKS allows asymmetric only. Never both: that is the alg-confusion attack.
+  const allowed = new Set(algorithms.filter((a) => (secret ? ALGS[a].family === "HS" : ALGS[a].family !== "HS")));
+  if (!problem && !allowed.size) problem = secret ? "algorithms must include an HS* algorithm when G8_JWT_SECRET is used." : "algorithms must include an RS*, PS* or ES* algorithm with a JWKS.";
+
+  let jwks: { keys: Jwk[]; at: number } | null = null;
+  let jwksUrl: string | undefined = configuredJwks;
+  let inflight: Promise<Jwk[]> | null = null;
+
+  async function loadKeys(force: boolean): Promise<Jwk[]> {
+    const now = Date.now();
+    if (jwks && !force && now - jwks.at < JWKS_TTL) return jwks.keys;
+    if (jwks && force && now - jwks.at < JWKS_MIN_REFRESH) return jwks.keys;
+    inflight ??= (async () => {
+      try {
+        if (!jwksUrl) {
+          const conf = await fetchJson(doFetch, `${(issuer as string).replace(/\/+$/, "")}/.well-known/openid-configuration`);
+          if (typeof conf.issuer !== "string" || conf.issuer.replace(/\/+$/, "") !== (issuer as string).replace(/\/+$/, "")) throw new Error("issuer mismatch in discovery");
+          if (typeof conf.jwks_uri !== "string" || !remoteUrlOk(conf.jwks_uri)) throw new Error("bad jwks_uri");
+          jwksUrl = conf.jwks_uri;
+        }
+        const body = await fetchJson(doFetch, jwksUrl);
+        const keys = Array.isArray(body.keys) ? (body.keys as Jwk[]).filter((k) => k && typeof k === "object") : [];
+        jwks = { keys, at: Date.now() };
+        return keys;
+      } finally {
+        inflight = null;
+      }
+    })();
+    return inflight;
+  }
+
+  async function verifyKey(alg: string, kid: string | undefined): Promise<CryptoKey | null> {
+    const spec = ALGS[alg];
+    if (spec.family === "HS") return hmacKey(secret as string, spec.hash);
+    const pick = (keys: Jwk[]) => {
+      const fits = keys.filter((k) => keyMatches(k, alg));
+      return kid ? fits.find((k) => k.kid === kid) : fits.length === 1 ? fits[0] : undefined;
+    };
+    let jwk = pick(await loadKeys(false));
+    if (!jwk && kid) jwk = pick(await loadKeys(true));
+    if (!jwk) return null;
+    const { kid: _k, use: _u, alg: _a, key_ops: _o, ...material } = jwk as Jwk & { key_ops?: unknown };
+    return crypto.subtle.importKey("jwk", { ...material, ext: true }, importParams(alg).importAlg, false, ["verify"]);
+  }
+
+  async function verify(token: string, now = Date.now()): Promise<Record<string, unknown> | null> {
+    if (problem || !token || token.length > MAX_TOKEN) return null;
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const header = decodeSegment(parts[0]);
+    const claims = decodeSegment(parts[1]);
+    const sig = b64urlDecode(parts[2]);
+    if (!header || !claims || !sig || !sig.length) return null;
+    const alg = header.alg;
+    if (typeof alg !== "string" || !allowed.has(alg) || header.crit !== undefined) return null;
+    if (header.typ !== undefined && (typeof header.typ !== "string" || !/^(at\+)?jwt$/i.test(header.typ.replace(/^application\//i, "")))) return null;
+    let key: CryptoKey | null;
+    try {
+      key = await verifyKey(alg, typeof header.kid === "string" ? header.kid : undefined);
+    } catch {
+      return null;
+    }
+    if (!key) return null;
+    const data = enc.encode(`${parts[0]}.${parts[1]}`);
+    let ok: boolean;
+    try {
+      ok = ALGS[alg].family === "HS" ? timingSafeEqual(await hmac(key, data), sig) : await crypto.subtle.verify(importParams(alg).verifyAlg, key, sig as BufferSource, data as BufferSource);
+    } catch {
+      return null;
+    }
+    if (!ok) return null;
+    const t = Math.floor(now / 1000);
+    if (typeof claims.exp !== "number" || claims.exp + tolerance <= t) return null;
+    if (claims.nbf !== undefined && (typeof claims.nbf !== "number" || claims.nbf - tolerance > t)) return null;
+    if (issuer && (typeof claims.iss !== "string" || claims.iss.replace(/\/+$/, "") !== issuer.replace(/\/+$/, ""))) return null;
+    if (audience.length) {
+      const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+      if (!aud.some((a) => typeof a === "string" && audience.includes(a))) return null;
+    }
+    return claims;
+  }
+
+  return { verify, problem: () => problem };
+}
+
+function bearerToken(request: Request): string | undefined {
+  const m = /^Bearer\s+(\S+)$/i.exec(request.headers.get("authorization")?.trim() ?? "");
+  return m?.[1];
+}
+
+/** Verify a JWT from your identity provider (OIDC JWKS or an HS256 secret). */
+export function jwtAuth(options: JwtAuthOptions = {}): G8AppAuth {
+  const verifier = createJwtVerifier(options);
+  const env = readEnv();
+  const cookie = (options.cookie ?? env.G8_JWT_COOKIE)?.trim() || undefined;
+  const bearer = options.bearer ?? true;
+  const signInUrl = urlSetting(options.signInUrl ?? env.G8_SIGN_IN_URL);
+  const signOutUrl = urlSetting(options.signOutUrl ?? env.G8_SIGN_OUT_URL);
+
+  async function check(request: Request): Promise<{ ok: boolean; viaCookie: boolean }> {
+    const fromHeader = bearer ? bearerToken(request) : undefined;
+    const token = fromHeader ?? (cookie ? readCookie(request, cookie) : undefined);
+    if (!token) return { ok: false, viaCookie: false };
+    const claims = await verifier.verify(token);
+    if (!claims) return { ok: false, viaCookie: !fromHeader };
+    const extra = options.claims ? await Promise.resolve(options.claims(claims)).catch(() => false) : true;
+    return { ok: extra === true, viaCookie: !fromHeader };
+  }
+
+  return {
+    kind: "jwt",
+    async authorize(request) {
+      const p = verifier.problem();
+      if (p) return misconfigured(p);
+      const { ok, viaCookie } = await check(request);
+      if (!ok) return unauthenticated();
+      // A cookie rides along on cross-site requests; a Bearer header cannot be forged by another site.
+      if (viaCookie && !SAFE_METHODS.has(request.method.toUpperCase()) && isCrossSite(request)) return crossSite();
+    },
+    async status(request) {
+      const p = verifier.problem();
+      const base = { kind: "jwt" as const, ...(signInUrl ? { signInUrl } : {}), ...(signOutUrl ? { signOutUrl } : {}) };
+      if (p) return { ...base, signedIn: false, problem: p };
+      return { ...base, signedIn: (await check(request)).ok };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// sessionAuth
+// ---------------------------------------------------------------------------------------------------------------
+
+export interface SessionAuthOptions {
+  /** Default: G8_SIGN_IN_URL. */
+  signInUrl?: string;
+  /** Default: G8_SIGN_OUT_URL. */
+  signOutUrl?: string;
+  /**
+   * Refuse cross-site writes (CSRF), for cookie sessions. Default true; turn off only if your session check
+   * already does it.
+   */
+  sameOriginWrites?: boolean;
+}
+
+/**
+ * Adapter for any session library. Return the user (anything truthy) to allow, null/undefined/false to refuse.
+ * A throw refuses too (fail closed) and is logged without details.
+ *
+ *   Clerk:     sessionAuth(async () => (await auth()).userId)              // import { auth } from "@clerk/nextjs/server"
+ *   NextAuth:  sessionAuth(() => auth())                                   // import { auth } from "@/auth"
+ *   Supabase:  sessionAuth(async () => (await (await createClient()).auth.getUser()).data.user)
+ */
+export function sessionAuth(getUser: (request: Request) => unknown | Promise<unknown>, options: SessionAuthOptions = {}): G8AppAuth {
+  const env = readEnv();
+  const signInUrl = urlSetting(options.signInUrl ?? env.G8_SIGN_IN_URL);
+  const signOutUrl = urlSetting(options.signOutUrl ?? env.G8_SIGN_OUT_URL);
+  const sameOrigin = options.sameOriginWrites ?? true;
+  const check = async (request: Request): Promise<boolean> => {
+    try {
+      return Boolean(await getUser(request));
+    } catch {
+      console.error("[graph8] sessionAuth: the session check threw; refusing the request.");
+      return false;
+    }
+  };
+  return {
+    kind: "session",
+    async authorize(request) {
+      if (!(await check(request))) return unauthenticated();
+      if (sameOrigin && !SAFE_METHODS.has(request.method.toUpperCase()) && isCrossSite(request)) return crossSite();
+    },
+    async status(request) {
+      return { kind: "session", signedIn: await check(request), ...(signInUrl ? { signInUrl } : {}), ...(signOutUrl ? { signOutUrl } : {}) };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// allowAnonymous
+// ---------------------------------------------------------------------------------------------------------------
+
+let anonymousWarned = false;
+
+/**
+ * NO sign-in: anyone who can reach this app can use its graph8 API key through /api/g8, within allowedPrefixes.
+ * For a public demo or an app behind your own network gate. Logs a loud warning once per server start;
+ * `npx @graph8/sdk doctor` flags it.
+ */
+export function allowAnonymous(): G8AppAuth {
+  const warn = () => {
+    if (anonymousWarned) return;
+    anonymousWarned = true;
+    console.warn(
+      "[graph8] WARNING: allowAnonymous() is on. Anyone who can reach this app can use its graph8 API key through /api/g8 (within allowedPrefixes). Use a narrowly scoped key with a spend cap, or switch to a sign-in preset in g8.auth.ts.",
+    );
+  };
+  return {
+    kind: "anonymous",
+    async authorize() {
+      warn();
+    },
+    async status() {
+      return { kind: "anonymous", signedIn: true };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// The sign-in route
+// ---------------------------------------------------------------------------------------------------------------
+
+/**
+ * `app/api/g8-auth/route.ts`: GET the session status (for the sign-in screen), POST to sign in and DELETE to
+ * sign out (sharedPassword only; other presets answer 405 there, sign-in happens at your provider).
+ */
+export function createG8AuthRoute(auth: G8AppAuth) {
+  return {
+    async GET(request: Request): Promise<Response> {
+      return json(200, { ...(await auth.status(request)) });
+    },
+    async POST(request: Request): Promise<Response> {
+      if (!auth.signIn) return json(405, { error: "method_not_allowed", message: "Sign in with your identity provider." });
+      return auth.signIn(request);
+    },
+    async DELETE(request: Request): Promise<Response> {
+      if (!auth.signOut) return json(405, { error: "method_not_allowed", message: "Sign out with your identity provider." });
+      return auth.signOut(request);
+    },
+  };
+}