@celilo/console-server 0.4.4 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/console-server",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "HTTP surface for the celilo web console. Serves the SPA and hosts the tsrpc API. Holds no database: it reaches celilo-mgr over the SSH remote API as a read-only principal.",
   "type": "module",
   "main": "./src/index.ts",

package/src/main.ts

@@ -12,6 +12,7 @@
  */
 
 import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
+import { oidcBrowserGate } from './oidc-login';
 import { type AuthGate, type AuthSubject, serve } from './serve';
 
 /**
@@ -108,15 +109,28 @@ export function startFromEnv(env: Record<string, string | undefined> = process.e
   port: number;
   stop: () => void;
 } {
+  // The Bearer half of the gate. The browser half — the authorization-code +
+  // PKCE flow — is layered in front of it by `oidcBrowserGate`, which
+  // delegates bearer verification here so the JWKS policy stays in one place.
+  const bearerGate = oidcGate({
+    issuer: required(env, 'OIDC_ISSUER'),
+    clientId: required(env, 'OIDC_CLIENT_ID'),
+  });
+  const login = oidcBrowserGate(
+    {
+      issuer: required(env, 'OIDC_ISSUER'),
+      clientId: required(env, 'OIDC_CLIENT_ID'),
+      clientSecret: required(env, 'OIDC_CLIENT_SECRET'),
+    },
+    bearerGate,
+  );
   const server = serve({
     port: Number(env.PORT ?? 8443),
     dest: env.CELILO_API_DEST ?? DEFAULT_DEST,
     identityFile: env.CELILO_IDENTITY_FILE ?? DEFAULT_IDENTITY_FILE,
     ...(env.CONSOLE_SPA_DIR ? { spaDir: env.CONSOLE_SPA_DIR } : {}),
-    authenticate: oidcGate({
-      issuer: required(env, 'OIDC_ISSUER'),
-      clientId: required(env, 'OIDC_CLIENT_ID'),
-    }),
+    authenticate: login.authenticate,
+    login: { handleCallback: login.handleCallback, redirectToLogin: login.redirectUri },
   });
   console.log(`[console] listening on :${server.port}`);
   return server;

package/src/oidc-login.ts

@@ -0,0 +1,343 @@
+/**
+ * The console's login: the OIDC authorization-code + PKCE flow, run by the app.
+ *
+ * D8 settles both halves of this. The console authenticates PEOPLE, and it
+ * authenticates them itself: an unauthenticated browser is redirected to the
+ * identity provider, the provider sends back a code, the app exchanges it
+ * (confidential client, so the secret stays server-side) and verifies the
+ * resulting id_token against the provider's JWKS. Nothing ever trusts a header
+ * or a client-supplied assertion.
+ *
+ * What OIDC is NOT here is worth restating, because claiming more for it is
+ * how the caddy-internal mistake gets made a second time (design.md D7, D8):
+ * the primary access control is the control-plane VPN key. OIDC supplies
+ * identity — an acknowledgement records WHO clicked — and a second factor
+ * against a forgotten unlocked laptop. It is not the wall.
+ *
+ * ## Why a cookie session rather than the id_token itself
+ *
+ * The id_token is a JWT meant for the app, not for the browser. Storing it in
+ * a cookie would hand a token that satisfies `oidcGate`'s Bearer check to
+ * JavaScript, and a shorter-lived opaque session token is the cheaper secret
+ * to lose. The session maps to the subject the token was verified against,
+ * and nothing else is carried.
+ *
+ * ## Why the pending-flow state is in memory
+ *
+ * A `state`/PKCE-verifier pair waiting for its callback lives only as long as
+ * the login it belongs to, and the console is one process. A store that
+ * survives restart would let a half-finished login outlive the key it was
+ * minted against. The maps are bounded by expiry sweeps, so a client that
+ * starts flows and never finishes them cannot grow them without limit.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
+import type { AuthGate, AuthSubject } from './serve';
+
+/** The path the identity provider sends the browser back to. Must be one of the redirect_uris registered at client creation. */
+export const CALLBACK_PATH = '/auth/callback';
+
+/** Name of the session cookie the callback sets. */
+export const SESSION_COOKIE = 'console_session';
+
+/** A login in progress: the state that identifies it and the PKCE verifier that completes it. */
+interface PendingLogin {
+  verifier: string;
+  expiresAt: number;
+}
+
+/** A completed, verified login. */
+interface Session {
+  subject: string;
+  name?: string;
+  expiresAt: number;
+}
+
+/** Milliseconds a completed session stays valid. */
+const SESSION_TTL_MS = 12 * 60 * 60 * 1000;
+/** Milliseconds a started-but-never-finished login is kept. */
+const PENDING_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * The OIDC endpoints the flow needs, read from discovery.
+ *
+ * Per-application issuer for authentik is `https://auth.<domain>/application/o/<slug>/`,
+ * and its discovery document lives one level below that. Deriving endpoint
+ * URLs by appending known paths works on some providers and silently fails on
+ * this one, which is why `oidcGate` already discovers — the same reasoning
+ * applies to the authorization and token endpoints.
+ */
+interface DiscoveryDocument {
+  authorization_endpoint?: string;
+  token_endpoint?: string;
+  jwks_uri?: string;
+}
+
+export interface OidcBrowserGateOptions {
+  /** The `iss` claim exactly — authentik's per-application issuer. */
+  issuer: string;
+  /** Also the expected audience: authentik puts the client id in `aud`. */
+  clientId: string;
+  /** The confidential client's secret, needed to exchange the code. */
+  clientSecret: string;
+  /** Injectable so tests drive the flow without a live provider. */
+  fetchImpl?: typeof fetch;
+  /** Clock injection for expiry sweeps in tests. */
+  now?: () => number;
+}
+
+export interface OidcBrowserGate {
+  /**
+   * Who is asking, from a session cookie or a Bearer token.
+   *
+   * The Bearer half is `oidcGate`'s contract unchanged: an API client that
+   * presents a provider-verified token directly is answered, and the shape is
+   * what tests already drive.
+   */
+  authenticate: AuthGate;
+  /**
+   * Answer the callback, or `null` when the request is not one.
+   *
+   * Runs BEFORE `authenticate` on every request: the callback arrives from a
+   * browser that has no session yet, so running the gate first would refuse
+   * the one request whose job is to create one.
+   */
+  handleCallback: (request: Request) => Promise<Response | null>;
+  /**
+   * Send an unauthenticated browser to the identity provider.
+   *
+   * A page navigation rather than an API call, so a redirect is the right
+   * refusal: the person ends up on a login form instead of an error.
+   */
+  redirectUri: (request: Request) => Promise<Response>;
+}
+
+/**
+ * The discovery document, fetched lazily and memoized — the same policy
+ * `oidcGate` applies to the JWKS, for the same reason: an eager fetch turns a
+ * slow provider into a console that will not boot.
+ */
+export class OidcLoginFlow {
+  private readonly doFetch: typeof fetch;
+  private readonly nowFn: () => number;
+  private readonly pending = new Map<string, PendingLogin>();
+  private readonly sessions = new Map<string, Session>();
+  private discovery: DiscoveryDocument | undefined;
+  private keys: ReturnType<typeof createRemoteJWKSet> | undefined;
+
+  constructor(
+    private readonly options: OidcBrowserGateOptions,
+    private readonly jwksFallback: AuthGate,
+  ) {
+    this.doFetch = options.fetchImpl ?? fetch;
+    this.nowFn = options.now ?? Date.now;
+  }
+
+  private async discoveryDoc(): Promise<DiscoveryDocument> {
+    if (this.discovery === undefined) {
+      const url = new URL('.well-known/openid-configuration', this.options.issuer);
+      const response = await this.doFetch(url);
+      if (!response.ok) {
+        throw new Error(`OIDC discovery at ${url} returned ${response.status}`);
+      }
+      const document = (await response.json()) as DiscoveryDocument;
+      if (
+        typeof document.authorization_endpoint !== 'string' ||
+        typeof document.token_endpoint !== 'string' ||
+        typeof document.jwks_uri !== 'string'
+      ) {
+        throw new Error(
+          `OIDC discovery at ${url} carried no authorization, token or jwks endpoint`,
+        );
+      }
+      this.discovery = document;
+    }
+    return this.discovery;
+  }
+
+  private async endpoints(): Promise<{ authorize: string; token: string }> {
+    const document = await this.discoveryDoc();
+    return {
+      authorize: document.authorization_endpoint as string,
+      token: document.token_endpoint as string,
+    };
+  }
+
+  private async keysFor(): Promise<ReturnType<typeof createRemoteJWKSet>> {
+    if (this.keys !== undefined) return this.keys;
+    const document = await this.discoveryDoc();
+    this.keys = createRemoteJWKSet(new URL(document.jwks_uri as string), {
+      [customFetch]: (target, init) => this.doFetch(target, init),
+    });
+    return this.keys;
+  }
+
+  /** Verify a provider token, or say nothing about why it failed (an expired token is a refusal, not an error report). */
+  private async verify(idToken: string): Promise<AuthSubject | null> {
+    try {
+      const { payload } = await jwtVerify(idToken, await this.keysFor(), {
+        issuer: this.options.issuer,
+        audience: this.options.clientId,
+      });
+      const name = [payload.preferred_username, payload.name, payload.email].find(
+        (value): value is string => typeof value === 'string' && value.length > 0,
+      );
+      return { subject: String(payload.sub), ...(name === undefined ? {} : { name }) };
+    } catch {
+      return null;
+    }
+  }
+
+  private sweep(): void {
+    const now = this.nowFn();
+    for (const [key, login] of this.pending) {
+      if (login.expiresAt <= now) this.pending.delete(key);
+    }
+    for (const [key, session] of this.sessions) {
+      if (session.expiresAt <= now) this.sessions.delete(key);
+    }
+  }
+
+  /**
+   * Start a login: build the provider redirect with PKCE + state.
+   *
+   * The redirect_uri is derived from the REQUEST, not from config. The
+   * console serves whatever address the VPN peer dialed — a zone-side IP and
+   * port — and authentik refuses any redirect it was not registered with, so
+   * inventing the origin here would be wrong exactly when the request is the
+   * evidence of what was registered.
+   */
+  async redirect(request: Request): Promise<Response> {
+    this.sweep();
+    const { authorize } = await this.endpoints();
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = Buffer.from(
+      await crypto.subtle.digest('SHA-256', Buffer.from(verifier)),
+    ).toString('base64url');
+    const state = randomBytes(16).toString('base64url');
+    this.pending.set(state, { verifier, expiresAt: this.nowFn() + PENDING_TTL_MS });
+
+    const origin = new URL(request.url).origin;
+    const target = new URL(authorize);
+    target.searchParams.set('response_type', 'code');
+    target.searchParams.set('client_id', this.options.clientId);
+    target.searchParams.set('redirect_uri', `${origin}${CALLBACK_PATH}`);
+    target.searchParams.set('scope', 'openid profile');
+    target.searchParams.set('state', state);
+    target.searchParams.set('code_challenge', challenge);
+    target.searchParams.set('code_challenge_method', 'S256');
+    return new Response(null, { status: 302, headers: { location: target.toString() } });
+  }
+
+  /**
+   * Finish a login, or `null` when this request is not a callback.
+   *
+   * Every failure inside a real callback is a redirect to the provider to try
+   * again rather than an error page, for the same reason the initial refusal
+   * is a redirect: the person at the browser has no other way forward.
+   */
+  async handleCallback(request: Request): Promise<Response | null> {
+    const url = new URL(request.url);
+    if (url.pathname !== CALLBACK_PATH) return null;
+
+    const code = url.searchParams.get('code');
+    const state = url.searchParams.get('state');
+    const pending = typeof state === 'string' ? this.pending.get(state) : undefined;
+    if (typeof state === 'string' && pending !== undefined) this.pending.delete(state);
+    if (code === null || pending === undefined) {
+      return this.redirect(request);
+    }
+    if (pending.expiresAt <= this.nowFn()) {
+      return this.redirect(request);
+    }
+
+    const { token } = await this.endpoints();
+    const origin = url.origin;
+    const form = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: `${origin}${CALLBACK_PATH}`,
+      client_id: this.options.clientId,
+      client_secret: this.options.clientSecret,
+      code_verifier: pending.verifier,
+    });
+    const response = await this.doFetch(token, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: form.toString(),
+    });
+    if (!response.ok) {
+      return this.redirect(request);
+    }
+    const tokens = (await response.json()) as { id_token?: string };
+    if (typeof tokens.id_token !== 'string') {
+      return this.redirect(request);
+    }
+    const subject = await this.verify(tokens.id_token);
+    if (subject === null) {
+      return this.redirect(request);
+    }
+
+    const sessionToken = randomBytes(32).toString('base64url');
+    this.sessions.set(sessionToken, {
+      subject: subject.subject,
+      ...(subject.name === undefined ? {} : { name: subject.name }),
+      expiresAt: this.nowFn() + SESSION_TTL_MS,
+    });
+    return new Response(null, {
+      status: 303,
+      headers: {
+        location: '/',
+        'set-cookie': `${SESSION_COOKIE}=${sessionToken}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${SESSION_TTL_MS / 1000}`,
+      },
+    });
+  }
+
+  /** The session a request carries, if any. Used by `authenticate`. */
+  private session(request: Request): AuthSubject | null {
+    const header = request.headers.get('cookie') ?? '';
+    const match = header
+      .split(';')
+      .map((part) => part.trim())
+      .find((part) => part.startsWith(`${SESSION_COOKIE}=`));
+    if (match === undefined) return null;
+    const token = match.slice(SESSION_COOKIE.length + 1);
+    const session = this.sessions.get(token);
+    if (session === undefined) return null;
+    if (session.expiresAt <= this.nowFn()) {
+      this.sessions.delete(token);
+      return null;
+    }
+    return {
+      subject: session.subject,
+      ...(session.name === undefined ? {} : { name: session.name }),
+    };
+  }
+
+  authenticate: AuthGate = async (request) => {
+    this.sweep();
+    const fromSession = this.session(request);
+    if (fromSession !== null) return fromSession;
+    return this.jwksFallback(request);
+  };
+}
+
+/**
+ * Build the login flow and the two entry points `serve` drives.
+ *
+ * `jwksFallback` is the Bearer path (`oidcGate`): the flow verifies the
+ * id_token it exchanges itself, and delegates bearer verification to the same
+ * gate the process already had, so there is one JWKS policy, not two.
+ */
+export function oidcBrowserGate(
+  options: OidcBrowserGateOptions,
+  jwksFallback: AuthGate,
+): OidcBrowserGate {
+  const flow = new OidcLoginFlow(options, jwksFallback);
+  return {
+    authenticate: flow.authenticate,
+    handleCallback: (request) => flow.handleCallback(request),
+    redirectUri: (request) => flow.redirect(request),
+  };
+}

package/src/serve.ts

@@ -17,6 +17,7 @@
 
 import { join } from 'node:path';
 import type { ServiceType } from '@celilo/console-protocol';
+import { CALLBACK_PATH } from './oidc-login';
 import { Upstream, type UpstreamOptions, UpstreamUnavailable } from './upstream';
 import {
   ackAlert,
@@ -47,6 +48,23 @@ export interface ServeOptions {
   spaDir?: string;
   /** Decides who is asking. See `AuthGate`. */
   authenticate: AuthGate;
+  /**
+   * The browser login, when the deployment runs the OIDC flow (D8).
+   *
+   * Two hooks, and the split is the whole design. `handleCallback` answers the
+   * provider's redirect — it must run BEFORE the gate, because the one request
+   * whose job is to CREATE a session arrives without one. `redirectToLogin`
+   * is how a page navigation is refused: a person at a browser gets the login
+   * form, not an error page.
+   *
+   * API calls are refused differently — 401, below — because a `fetch()` that
+   * follows a 302 to an HTML login page reports a JSON parse error and sends
+   * the reader looking at the wrong layer.
+   */
+  login?: {
+    handleCallback: (request: Request) => Promise<Response | null>;
+    redirectToLogin: (request: Request) => Promise<Response>;
+  };
   cacheTtlMs?: number;
   /**
    * Injectable so tests drive the whole surface without SSH, matching
@@ -236,11 +254,22 @@ export function createHandler(options: ServeOptions): (request: Request) => Prom
   return async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
 
+    // The callback runs before any gate. It arrives from a browser that has
+    // completed the provider's login and holds no session yet, so gating it
+    // would refuse the only request that can create one.
+    if (options.login) {
+      const answered = await options.login.handleCallback(request);
+      if (answered !== null) return answered;
+    }
+
     // The gate runs FIRST, for every path including the SPA. Serving the shell
     // to an unauthenticated caller would leak the fleet's shape through the
     // bundle even with every API call refused.
     const subject = await options.authenticate(request);
     if (subject === null) {
+      if (options.login && !url.pathname.startsWith('/api/') && url.pathname !== CALLBACK_PATH) {
+        return options.login.redirectToLogin(request);
+      }
       return new Response('Unauthorized', {
         status: 401,
         headers: { 'WWW-Authenticate': 'Bearer' },