@kedge/server 0.0.0-stage → 0.10.0

package/src/auth-routes.ts

@@ -0,0 +1,381 @@
+// The credential ceremonies over HTTP (p0.5-auth-and-access.md §2): staff on
+// /auth/admin/*, customers on /auth/store/*. Every route here is in §2.8's
+// rate table; anything else under /auth answers 404. A session-creating
+// ceremony sets the pool's HttpOnly cookie, or, called with
+// `X-Kedge-Session-Mode: bearer`, returns the token in its body and sets
+// nothing (§2.9), so a page's scripts never read a cookie session.
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import { isKedgeError, KedgeError } from "@kedge/core";
+import type { Context } from "hono";
+import {
+  checkCsrf,
+  clientOf,
+  cookieValues,
+  DEVICE_COOKIE,
+  deviceCookie,
+  type KedgeEnv,
+  type RequestAccess,
+  resolveSession,
+  sessionCookie,
+  sessionCredential,
+  storefrontOf,
+} from "./access";
+import { adminOriginsFor, authzFingerprint, checkView, nameAnswer } from "./admin-shell";
+import { jsonBody, ok } from "./http";
+import type { AuthDeps, IssuedSession, Pool } from "./types";
+
+/** The known-device cookie lives as long as its row (§2.8). */
+const DEVICE_MAX_AGE_S = 90 * 86_400;
+
+const iso = (ms: number | null) => (ms === null ? null : new Date(ms).toISOString());
+const Email = z.string().min(3).max(320);
+const Password = z.string().min(1).max(1024);
+const Token = z.string().min(16).max(256);
+
+/** Every /auth route, for the test that diffs the router against §2.8's table. */
+export const AUTH_ROUTES = [
+  "POST /auth/admin/sign-in",
+  "POST /auth/admin/totp/challenge",
+  "POST /auth/admin/totp/enrol",
+  "POST /auth/admin/totp/confirm",
+  "POST /auth/admin/password",
+  "POST /auth/admin/sign-out",
+  "POST /auth/admin/sign-out-everywhere",
+  "GET /auth/admin/session",
+  "POST /auth/admin/invites/accept",
+  "POST /auth/admin/invites/resume",
+  "POST /auth/store/code",
+  "POST /auth/store/verify",
+  "POST /auth/store/sign-out",
+  "POST /auth/store/sign-out-everywhere",
+  "GET /auth/store/session",
+] as const;
+
+export function authRoutes(app: OpenAPIHono<KedgeEnv>, auth: AuthDeps, now: () => number): void {
+  const { ceremonies } = auth;
+
+  /** The pool's allow-list: `ADMIN_ORIGINS` and the Worker's own origin (p0.9 §4.1), or the publishable key's storefront's. */
+  const originsOf = async (c: Context, pool: Pool, t: number) =>
+    pool === "staff" ? adminOriginsFor(c, auth) : (await storefrontOf(c, auth, t)).origins;
+
+  /**
+   * A session-creating ceremony has no session yet: JSON, `X-Kedge-CSRF: 1`
+   * and an allowed `Origin`, always, even in bearer mode (§2.9 rule 3), so a
+   * foreign page can't sign someone in to an account it controls.
+   */
+  const creating = async (c: Context, pool: Pool, t: number) => {
+    c.header("cache-control", "no-store");
+    await checkCsrf(c, auth, await originsOf(c, pool, t), { sessionToken: null, json: true }, t);
+  };
+
+  /** A session-bound ceremony: the caller's session; CSRF unless it came as a bearer token. */
+  const bound = async (c: Context, pool: Pool, t: number): Promise<RequestAccess & { token: string }> => {
+    c.header("cache-control", "no-store");
+    const cred = sessionCredential(c, pool);
+    if (!cred) throw new KedgeError("UNAUTHORIZED", "Sign in first");
+    const origins = await originsOf(c, pool, t);
+    const access = await resolveSession(c, auth, pool, cred, t);
+    // A staff answer names its session, errors included, so a form's `401` with it is the form's error (p0.9 §4.3).
+    const fingerprint =
+      pool === "staff" && access.session
+        ? await authzFingerprint(access.ctx, access.session.method, auth.accessContract ?? "")
+        : null;
+    if (fingerprint && access.session) nameAnswer(c, access.session.id, fingerprint);
+    if (cred.via === "cookie" && c.req.method !== "GET")
+      await checkCsrf(c, auth, origins, { sessionToken: cred.token, json: true }, t);
+    // The view a form was built under, as the admin gate checks it (p0.9 §6.3): a password
+    // change sent from another member's view is refused before it runs (codex code r10).
+    if (fingerprint && c.req.method !== "GET") checkView(c, fingerprint);
+    return { ...access, token: cred.token };
+  };
+
+  /** The ceremony's session to the client: a cookie, or the token in the body in bearer mode. */
+  const issue = (c: Context, s: IssuedSession, t: number) => {
+    const body = { session: { id: s.id, pool: s.pool, method: s.method, expires_at: iso(s.expiresAt) } };
+    if (c.req.header("x-kedge-session-mode") === "bearer") return { ...body, session_token: s.token };
+    c.header("set-cookie", sessionCookie(s.pool, s.token, s.expiresAt, t), { append: true });
+    return { ...body, csrf_token: s.csrfToken };
+  };
+
+  /** The known-device token: a cookie, or in the body for a bearer client (§2.8). */
+  const device = (c: Context, token: string | null) => {
+    if (!token) return {};
+    if (c.req.header("x-kedge-session-mode") === "bearer") return { device_token: token };
+    c.header("set-cookie", deviceCookie(token, DEVICE_MAX_AGE_S), { append: true });
+    return {};
+  };
+  const presentedDevice = (c: Context, body: { device_token?: string | undefined }) => {
+    const cookies = cookieValues(c.req.header("cookie"), DEVICE_COOKIE);
+    return body.device_token ?? (cookies.length === 1 ? (cookies[0] as string) : null);
+  };
+
+  const signedOut = (c: Context, pool: Pool, t: number) => {
+    c.header("set-cookie", sessionCookie(pool, null, null, t), { append: true });
+    return c.json({ signed_out: true }, 200);
+  };
+
+  // ---- staff ----------------------------------------------------------------------
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/admin/sign-in",
+      request: jsonBody(z.object({ email: Email, password: Password, device_token: Token.optional() })),
+      responses: ok("A session, or a TOTP challenge"),
+    }),
+    async (c) => {
+      const t = now();
+      await creating(c, "staff", t);
+      const b = c.req.valid("json");
+      const r = await ceremonies.staffSignIn(
+        { email: b.email, password: b.password, deviceToken: presentedDevice(c, b) },
+        clientOf(c),
+        t,
+      );
+      if (r.kind === "challenge")
+        return c.json({ challenge: { token: r.challengeToken, expires_at: iso(r.expiresAt) } }, 200);
+      return c.json({ ...issue(c, r.session, t), ...device(c, r.deviceToken) }, 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/admin/totp/challenge",
+      request: jsonBody(
+        z.object({ challenge_token: Token, code: z.string().regex(/^[0-9]{6}$/), device_token: Token.optional() }),
+      ),
+      responses: ok("A password+totp session"),
+    }),
+    async (c) => {
+      const t = now();
+      await creating(c, "staff", t);
+      const b = c.req.valid("json");
+      const r = await ceremonies.staffTotpChallenge(
+        { challengeToken: b.challenge_token, code: b.code, deviceToken: presentedDevice(c, b) },
+        clientOf(c),
+        t,
+      );
+      return c.json({ ...issue(c, r.session, t), ...device(c, r.deviceToken) }, 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/admin/totp/enrol",
+      responses: ok("The otpauth URI, shown once, and the account's email"),
+    }),
+    async (c) => {
+      const t = now();
+      const a = await bound(c, "staff", t);
+      const staffId = a.session?.principalId as string;
+      const email = await ceremonies.staffEmail(staffId);
+      const r = await ceremonies.totpEnrolStart(
+        { sessionId: a.session?.id as string, principalId: staffId },
+        email ?? staffId,
+        t,
+      );
+      // The invite page signs in after enrolment with this, not with an address the member typed:
+      // the account is the invite's email, and a different one only ever fails to sign in.
+      return c.json({ otpauth_uri: r.uri, email, expires_at: iso(r.expiresAt) }, 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/admin/totp/confirm",
+      request: jsonBody(z.object({ code: z.string().regex(/^[0-9]{6}$/) })),
+      responses: ok("Enrolled; every other session ended"),
+    }),
+    async (c) => {
+      const t = now();
+      const a = await bound(c, "staff", t);
+      await ceremonies.totpEnrolConfirm(
+        { sessionId: a.session?.id as string, principalId: a.session?.principalId as string },
+        c.req.valid("json").code,
+        clientOf(c),
+        t,
+      );
+      return c.json({ enrolled: true }, 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/admin/password",
+      request: jsonBody(z.object({ current_password: Password, new_password: Password })),
+      responses: ok("Changed; every other session ended"),
+    }),
+    async (c) => {
+      const t = now();
+      const a = await bound(c, "staff", t);
+      const b = c.req.valid("json");
+      await ceremonies.staffChangePassword(
+        { sessionId: a.session?.id as string, principalId: a.session?.principalId as string },
+        b.current_password,
+        b.new_password,
+        clientOf(c),
+        t,
+      );
+      return c.json({ changed: true }, 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/admin/invites/accept",
+      request: jsonBody(z.object({ token: Token, password: Password, resume_nonce: z.string().min(32).max(128) })),
+      responses: ok("An enrolment session"),
+    }),
+    async (c) => {
+      const t = now();
+      await creating(c, "staff", t);
+      const b = c.req.valid("json");
+      const s = await ceremonies.acceptInvite(
+        { token: b.token, password: b.password, resumeNonce: b.resume_nonce },
+        clientOf(c),
+        t,
+      );
+      return c.json(issue(c, s, t), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/admin/invites/resume",
+      request: jsonBody(z.object({ token: Token, password: Password, resume_nonce: z.string().min(32).max(128) })),
+      responses: ok("The enrolment session, replaced"),
+    }),
+    async (c) => {
+      const t = now();
+      await creating(c, "staff", t);
+      const b = c.req.valid("json");
+      const s = await ceremonies.resumeInvite(
+        { token: b.token, password: b.password, resumeNonce: b.resume_nonce },
+        clientOf(c),
+        t,
+      );
+      return c.json(issue(c, s, t), 200);
+    },
+  );
+
+  // ---- customers ------------------------------------------------------------------
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/store/code",
+      request: jsonBody(z.object({ email: Email })),
+      responses: ok("Sent, if the address can receive it"),
+    }),
+    async (c) => {
+      const t = now();
+      await creating(c, "customer", t);
+      await ceremonies.requestCode(c.req.valid("json").email, clientOf(c), t);
+      return c.json({ sent: true }, 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/auth/store/verify",
+      request: jsonBody(z.object({ email: Email, code: z.string().max(16) })),
+      responses: ok("A customer session"),
+    }),
+    async (c) => {
+      const t = now();
+      await creating(c, "customer", t);
+      const b = c.req.valid("json");
+      return c.json(issue(c, await ceremonies.verifyCode(b.email, b.code, clientOf(c), t), t), 200);
+    },
+  );
+
+  // ---- both pools: sign-out and the session read ------------------------------------
+
+  for (const [pool, base] of [
+    ["staff", "/auth/admin"],
+    ["customer", "/auth/store"],
+  ] as const) {
+    const limited = async (policy: "session" | "session_read", c: Context, sessionId: string | null, t: number) => {
+      const subjects = sessionId ? { session: sessionId } : { address: clientOf(c).ip ?? "unknown" };
+      if (!(await auth.access.limit(policy, pool, subjects, t)))
+        throw new KedgeError("RATE_LIMITED", "Too many requests; wait a little");
+    };
+    /**
+     * The caller's session; a credential that resolves to none (forged,
+     * expired, signed out) is counted against the address first (codex code
+     * r11), so trying tokens costs what a request without one does.
+     */
+    const counted = async (c: Context, t: number) => {
+      try {
+        return await bound(c, pool, t);
+      } catch (e) {
+        if (isKedgeError(e) && e.code === "UNAUTHORIZED") await limited("session_read", c, null, t);
+        throw e;
+      }
+    };
+
+    app.openapi(createRoute({ method: "post", path: `${base}/sign-out`, responses: ok("Signed out") }), async (c) => {
+      const t = now();
+      const a = await counted(c, t);
+      await limited("session", c, a.session?.id ?? null, t);
+      await ceremonies.signOut(pool, a.token, t, { principalId: a.session?.principalId as string, ip: clientOf(c).ip });
+      return signedOut(c, pool, t);
+    });
+
+    app.openapi(
+      createRoute({ method: "post", path: `${base}/sign-out-everywhere`, responses: ok("Every session ended") }),
+      async (c) => {
+        const t = now();
+        const a = await counted(c, t);
+        await limited("session", c, a.session?.id ?? null, t);
+        await ceremonies.signOutEverywhere(
+          { sessionId: a.session?.id as string, principalId: a.session?.principalId as string },
+          pool,
+          t,
+          clientOf(c).ip,
+        );
+        return signedOut(c, pool, t);
+      },
+    );
+
+    app.openapi(
+      createRoute({ method: "get", path: `${base}/session`, responses: ok("The session and its CSRF token") }),
+      async (c) => {
+        const t = now();
+        c.header("cache-control", "no-store");
+        const cred = sessionCredential(c, pool);
+        if (!cred) {
+          await limited("session_read", c, null, t);
+          throw new KedgeError("UNAUTHORIZED", "Sign in first");
+        }
+        const a = await counted(c, t);
+        const s = a.session as NonNullable<RequestAccess["session"]>;
+        await limited("session_read", c, s.id, t);
+        const csrf = a.via === "cookie" ? await ceremonies.refreshCsrf(a.token, t) : null;
+        return c.json(
+          {
+            session: {
+              id: s.id,
+              pool: s.pool,
+              principal_id: s.principalId,
+              method: s.method,
+              expires_at: iso(s.expiresAt),
+              enrol_until: iso(s.enrolUntil),
+              // After a lost confirm the `invite:*` session stays; this says sign-in comes next (p0.9 §4.2).
+              ...(pool === "staff" ? { factor_enrolled: await ceremonies.staffFactorEnrolled(s.principalId) } : {}),
+            },
+            ...(csrf ? { csrf_token: csrf.csrfToken, csrf_expires_at: iso(csrf.expiresAt) } : {}),
+          },
+          200,
+        );
+      },
+    );
+  }
+}