src/portal-auth.ts

Functions

Imports

It imports src/access-login.ts, src/auth.ts, src/encoding.ts, src/env.ts, src/portal-host.ts. Imported by src/ops-feed.ts, src/portal-actions.ts, src/portal-app.ts, src/portal-claims.ts, src/portal-convergence.ts, src/portal-library.ts, src/portal-maintenance.ts, src/portal-overnight.ts, src/portal-packages.ts, src/portal-stale.ts, src/portal-trends.ts, src/push.ts, src/routes.ts.

Source

1import { clearStateCookie, completeAccessLogin, type LoginFlow, startAccessLogin } from "./access-login";
2import { getCookie, hmacHex, isAdminEmail } from "./auth";
3import { safeEqual } from "@dustinedwards/site-runtime/compare";
4import { b64urlDecode, b64urlEncode } from "./encoding";
5import type { Env } from "./env";
6import { isPortalHost, isSameOriginPath, PORTAL_HOST, portalCookiePath, publicPortalPath } from "./portal-host";
7
8// Capsid Portal's own session. The OAuth provider mints tokens for MCP clients, and a
9// browser opening /portal has nothing to present, so the Portal signs in through the
10// same Access for SaaS app as the MCP login (src/access-login.ts, design PR 3 of
11// capsid/research/design-capsid-access-login.md) with its own redirect URL, state
12// cookie and KV prefix, and turns the verified email into a signed cookie. It does not
13// go through the MCP provider, whose flow ends at a client redirect_uri.
14//
15// The cookie is a signed assertion (HMAC over a base64url payload with the email and
16// an expiry), not a session record. It cannot be revoked before it expires, so the
17// TTL is twelve hours and the admin check (ADMIN_EMAIL or CO_OWNER_EMAILS) runs again on every request.
18// Sign out expires it in this browser; a copy taken elsewhere stays valid until it
19// expires, which is the cost of a stateless cookie.
20//
21// Every cookie here is host-only (no Domain attribute, ever) and scoped by portalCookiePath
22// (src/portal-host.ts): Path=/ on portal.dustinedwards.info, a host that serves nothing
23// but the Portal, and Path=/portal on workers.dev, so /mcp and /ops there never see it. The Portal was at /console until PR B
24// of capsid/research/design-portal-unify.md. A Path=/console cookie from then is never
25// sent here, so a browser signed in there signs in once more.
26
27export const PORTAL_PATH = "/portal";
28export const PORTAL_PREFIX = "/portal/";
29export const PORTAL_CALLBACK_PATH = "/portal/callback";
30
31const PORTAL_SESSION_COOKIE = "capsid_portal";
32// The double-submit CSRF cookie (OpsFeed.csrf). Minted when absent or malformed and
33// then left alone, never rotated per poll, so a preview and its perform carry one
34// value (src/ops-feed.ts).
35export const PORTAL_CSRF_COOKIE = "capsid_portal_csrf";
36export const PORTAL_SESSION_TTL_SECONDS = 12 * 60 * 60;
37
38// The Portal's half of the Access login. The state stored against the token is the
39// Portal path to return to. The callback and the state cookie follow the host: on
40// portal.dustinedwards.info the callback is /callback, which the host rewrite hands to
41// PORTAL_CALLBACK_PATH; Access must list each host's callback URL (docs/auth.md).
42function portalLogin(url: URL): LoginFlow {
43  return {
44    callbackPath: publicPortalPath(url, PORTAL_CALLBACK_PATH),
45    stateCookie: "capsid_portal_state",
46    cookiePath: portalCookiePath(url),
47    kvPrefix: "capsid:portal-state:",
48    restartHint: isPortalHost(url) ? `Open https://${PORTAL_HOST} again.` : "Open /portal again.",
49  };
50}
51
52export interface PortalUser {
53  email: string;
54  // From the Access ID token's name claim, when the identity provider sent one.
55  name?: string;
56}
57
58interface SessionPayload extends PortalUser {
59  exp: number;
60}
61
62export async function portalSessionCookie(user: PortalUser, secret: string, now: Date, cookiePath: string = PORTAL_PATH): Promise<string> {
63  const payload: SessionPayload = {
64    email: user.email,
65    ...(user.name ? { name: user.name } : {}),
66    exp: Math.floor(now.getTime() / 1000) + PORTAL_SESSION_TTL_SECONDS,
67  };
68  const encoded = b64urlEncode(JSON.stringify(payload));
69  const sig = await hmacHex(secret, encoded);
70  return `${PORTAL_SESSION_COOKIE}=${sig}.${encoded}; HttpOnly; Secure; SameSite=Lax; Path=${cookiePath}; Max-Age=${PORTAL_SESSION_TTL_SECONDS}`;
71}
72
73/** The Set-Cookie values that sign this browser out: the session and CSRF cookies,
74 *  same name, path and attributes, Max-Age=0. */
75export function portalSignOutCookies(cookiePath: string = PORTAL_PATH): string[] {
76  return [
77    `${PORTAL_SESSION_COOKIE}=; HttpOnly; Secure; SameSite=Lax; Path=${cookiePath}; Max-Age=0`,
78    `${PORTAL_CSRF_COOKIE}=; HttpOnly; Secure; SameSite=Lax; Path=${cookiePath}; Max-Age=0`,
79  ];
80}
81
82// The session's user, or null for anything that does not verify. The admin check
83// means changing ADMIN_EMAIL or CO_OWNER_EMAILS invalidates every outstanding Portal cookie.
84export async function readPortalSession(request: Request, env: Env, now: Date): Promise<PortalUser | null> {
85  const raw = getCookie(request, PORTAL_SESSION_COOKIE);
86  if (!raw) return null;
87  const dot = raw.indexOf(".");
88  if (dot === -1) return null;
89  const sig = raw.slice(0, dot);
90  const encoded = raw.slice(dot + 1);
91  if (!await safeEqual(sig, await hmacHex(env.COOKIE_ENCRYPTION_KEY, encoded))) return null;
92  let payload: SessionPayload;
93  try {
94    payload = JSON.parse(b64urlDecode(encoded)) as SessionPayload;
95  } catch {
96    return null;
97  }
98  if (typeof payload?.email !== "string" || typeof payload.exp !== "number") return null;
99  if (payload.exp * 1000 <= now.getTime()) return null;
100  if (!await isAdminEmail(env, payload.email)) return null;
101  return typeof payload.name === "string" && payload.name ? { email: payload.email, name: payload.name } : { email: payload.email };
102}
103
104/** What the top bar shows for the signed-in person: the name from their Access identity,
105 *  else the local part of their email, never a fixed label. Initials are the first letters
106 *  of the first and last word. */
107export function portalDisplay(user: PortalUser): { name: string; initials: string } {
108  const name = user.name?.trim() || user.email.split("@")[0] || user.email;
109  const words = name.split(/[\s._-]+/).filter(Boolean);
110  const first = Array.from(words[0] ?? name)[0] ?? "?";
111  const last = words.length > 1 ? (Array.from(words[words.length - 1] ?? "")[0] ?? "") : "";
112  return { name, initials: (first + last).toUpperCase() };
113}
114
115export function startPortalLogin(request: Request, env: Env, returnTo: string): Promise<Response> {
116  return startAccessLogin(request, env, portalLogin(new URL(request.url)), returnTo);
117}
118
119/** /portal itself or a path under /portal/. A bare startsWith("/portal") would also
120 *  pass /portalx, and /portal//host would leave the origin once /portal is cut off. */
121function isPortalPath(path: string): boolean {
122  if (path === PORTAL_PATH) return true;
123  return path.startsWith(PORTAL_PREFIX) && isSameOriginPath(path.slice(PORTAL_PATH.length));
124}
125
126export async function handlePortalCallback(request: Request, env: Env, now: Date): Promise<Response> {
127  const url = new URL(request.url);
128  const flow = portalLogin(url);
129  const login = await completeAccessLogin(request, env, flow, (stored) => stored, now);
130  if (!login.ok) return login.response;
131  const { email, name, state: returnTo } = login;
132
133  // A relative Portal path only, checked rather than trusted from KV, so a bad write
134  // cannot become an open redirect.
135  // The stored path is internal (/portal/x); the browser on the Portal host goes to /x.
136  const safeReturn = isPortalPath(returnTo) ? returnTo : PORTAL_PREFIX;
137  const headers = new Headers({ Location: publicPortalPath(url, safeReturn) });
138  headers.append("Set-Cookie", await portalSessionCookie(name ? { email, name } : { email }, env.COOKIE_ENCRYPTION_KEY, now, portalCookiePath(url)));
139  headers.append("Set-Cookie", clearStateCookie(flow));
140  return new Response(null, { status: 302, headers });
141}
142
143// A bearer token is refused, not redirected. An agent or operator key presented to
144// the Portal is a caller that cannot follow a login redirect: a 302 would send a
145// machine to the Access sign-in and look, from its side, like the Portal being down.
146// The refusal names what was presented and what the page admits instead.
147const BEARER_REFUSAL =
148  "forbidden: Capsid Portal admits the administrator's Access session only. An operator key or an agent key authenticates to /ops/mcp, not to this page; the same state is served by capsid_run_improve action status and capsid_work_jobs there. Open the Portal in a browser to sign in as the administrator.";
149
150export type PortalGate = { ok: true; user: PortalUser } | { ok: false; response: Response };
151
152/** Every Portal route but the callback answers to this: a 403 for any Authorization
153 *  header, the Access sign-in with no session, else the administrator. */
154export async function portalGate(request: Request, env: Env, now: Date, returnTo: string): Promise<PortalGate> {
155  if (request.headers.get("Authorization")) {
156    return {
157      ok: false,
158      response: new Response(BEARER_REFUSAL, { status: 403, headers: { "Content-Type": "text/plain;charset=utf-8" } }),
159    };
160  }
161  const user = await readPortalSession(request, env, now);
162  if (!user) return { ok: false, response: await startPortalLogin(request, env, returnTo) };
163  return { ok: true, user };
164}
165
166// The address a Portal request came from, for its audit row. Cloudflare's edge sets
167// CF-Connecting-IP on every request and replaces any value a client sends, so it is
168// the visitor's address. A value that is not an IPv4 or IPv6 address is recorded as
169// null rather than stored as given.
170const ADDRESS = /^[0-9A-Fa-f:.]{2,45}$/;
171export function sourceAddress(request: Request): string | null {
172  const raw = request.headers.get("CF-Connecting-IP")?.trim() ?? "";
173  return ADDRESS.test(raw) && /[.:]/.test(raw) ? raw : null;
174}