@micacms/auth-oidc 0.5.0 → 0.6.0-rc.1

package/src/oidc.ts

@@ -0,0 +1,314 @@
+/**
+ * OpenID Connect.
+ *
+ * Mica does not authenticate anybody. It asks a provider who you are, and
+ * records the answer. Hashing, reset flows, MFA, passkeys and breach response
+ * all belong to the identity provider, and none of them are Mica's to get
+ * wrong.
+ *
+ * What is Mica's is the small part here: run the authorization code flow
+ * correctly and report what the provider said. Whether that person may edit
+ * this site is `services/admission.ts`, and deliberately not a table.
+ *
+ * Three checks carry the security of the flow, and all three are enforced
+ * rather than assumed:
+ *
+ *   - **PKCE** binds the authorization code to this browser, so a code
+ *     intercepted in a redirect is useless to anyone else.
+ *   - **state** binds the callback to a request Mica actually started, which
+ *     is what stops an attacker feeding a victim their own login.
+ *   - **nonce** binds the ID token to that same request, so a token replayed
+ *     from elsewhere does not validate.
+ *
+ * They are carried in a short-lived signed cookie rather than in the database:
+ * the transaction lasts one redirect, and a table of them would be a table of
+ * garbage to collect.
+ */
+
+import { createHmac, hkdfSync, randomBytes, timingSafeEqual } from "node:crypto";
+
+import * as client from "openid-client";
+
+import { ApiError, type Logger } from "@micacms/runtime";
+
+import type { AuthConfig } from "./config.js";
+
+/**
+ * How long a sign-in may take.
+ *
+ * Long enough to enter a second factor and read an email; short enough that an
+ * abandoned transaction cookie is not a lasting liability.
+ */
+const TRANSACTION_TTL_MS = 15 * 60 * 1000;
+
+export interface OidcTransaction {
+  state: string;
+  nonce: string;
+  verifier: string;
+  /** Where to send the browser once the session exists. */
+  returnTo: string;
+  expiresAt: number;
+}
+
+/** What the provider told us about the person signing in. */
+export interface OidcClaims {
+  issuer: string;
+  subject: string;
+  email: string;
+  /** The provider's `email_verified`. Absent counts as false, never as true. */
+  emailVerified: boolean;
+  name: string;
+  /** The configured groups claim, or empty when the provider sends none. */
+  groups: string[];
+}
+
+/* ------------------------------------------------------------------ *
+ * The transaction cookie
+ * ------------------------------------------------------------------ */
+
+// Its own key, derived like the session's: one secret, never used directly for two purposes (#91).
+const transactionKey = (secret: string): Buffer =>
+  Buffer.from(hkdfSync("sha256", secret, "", "mica oidc transaction v1", 32));
+
+function sign(value: string, secret: string): string {
+  return createHmac("sha256", transactionKey(secret)).update(value).digest("base64url");
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+export function sealTransaction(transaction: OidcTransaction, secret: string): string {
+  const payload = Buffer.from(JSON.stringify(transaction)).toString("base64url");
+  return `${payload}.${sign(payload, secret)}`;
+}
+
+export function openTransaction(cookie: string, secret: string): OidcTransaction | null {
+  const separator = cookie.lastIndexOf(".");
+  if (separator < 1) return null;
+
+  const payload = cookie.slice(0, separator);
+  const signature = cookie.slice(separator + 1);
+
+  if (!safeEqual(signature, sign(payload, secret))) return null;
+
+  try {
+    const transaction = JSON.parse(
+      Buffer.from(payload, "base64url").toString("utf8"),
+    ) as OidcTransaction;
+
+    return transaction.expiresAt > Date.now() ? transaction : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The address and its `email_verified` flag, always from the same answer, so
+ * that a flag cannot vouch for an address it was not sent with (#91). Userinfo
+ * fills in an address the ID token lacks, or confirms the token's own address.
+ */
+export function emailFrom(
+  claims: Record<string, unknown>,
+  info?: Record<string, unknown>,
+): { email: string; emailVerified: boolean } {
+  const tokenEmail = typeof claims["email"] === "string" ? claims["email"] : "";
+  const infoEmail = typeof info?.["email"] === "string" ? info["email"] : "";
+  const infoVerified = info?.["email_verified"] === true;
+
+  if (tokenEmail) {
+    const confirmed = infoEmail === tokenEmail && infoVerified;
+    return { email: tokenEmail, emailVerified: claims["email_verified"] === true || confirmed };
+  }
+  return { email: infoEmail, emailVerified: Boolean(infoEmail) && infoVerified };
+}
+
+/* ------------------------------------------------------------------ *
+ * The service
+ * ------------------------------------------------------------------ */
+
+export interface OidcServiceDeps {
+  config: AuthConfig;
+  logger: Logger;
+}
+
+export function createOidcService(deps: OidcServiceDeps) {
+  const { config, logger } = deps;
+
+  const redirectUri = new URL("/api/auth/callback", config.MICA_PUBLIC_URL).toString();
+
+  /**
+   * Discovery, done once and remembered.
+   *
+   * Lazy rather than at startup: an identity provider that is briefly
+   * unreachable should delay the first sign-in, not stop Mica from booting and
+   * taking its health check down with it.
+   */
+  let discovered: Promise<client.Configuration> | null = null;
+
+  function configuration(): Promise<client.Configuration> {
+    discovered ??= client
+      .discovery(
+        new URL(config.MICA_OIDC_ISSUER!),
+        config.MICA_OIDC_CLIENT_ID!,
+        config.MICA_OIDC_CLIENT_SECRET,
+        undefined,
+        // Only ever for a provider on localhost, and only outside production —
+        // the config layer refuses the combination anywhere else.
+        config.oidcAllowInsecure ? { execute: [client.allowInsecureRequests] } : undefined,
+      )
+      .catch((error: unknown) => {
+        // Forget the failure so the next attempt retries rather than caching a
+        // rejected promise for the life of the process.
+        discovered = null;
+        logger.error("OIDC discovery failed", {
+          issuer: config.MICA_OIDC_ISSUER,
+          error: String(error),
+        });
+        throw new ApiError(
+          "service_unavailable",
+          "The identity provider could not be reached. Try again shortly.",
+        );
+      });
+
+    return discovered;
+  }
+
+  return {
+    /** Where to send a browser to sign in, plus the transaction to remember. */
+    async begin(returnTo: string): Promise<{ url: string; transaction: OidcTransaction }> {
+      const as = await configuration();
+
+      const verifier = client.randomPKCECodeVerifier();
+      const transaction: OidcTransaction = {
+        state: client.randomState(),
+        nonce: client.randomNonce(),
+        verifier,
+        returnTo,
+        expiresAt: Date.now() + TRANSACTION_TTL_MS,
+      };
+
+      const url = client.buildAuthorizationUrl(as, {
+        redirect_uri: redirectUri,
+        scope: config.MICA_OIDC_SCOPE,
+        state: transaction.state,
+        nonce: transaction.nonce,
+        code_challenge: await client.calculatePKCECodeChallenge(verifier),
+        code_challenge_method: "S256",
+      });
+
+      return { url: url.toString(), transaction };
+    },
+
+    /**
+     * Completes the flow and returns who signed in.
+     *
+     * `authorizationCodeGrant` verifies the ID token signature, the issuer, the
+     * audience, the expiry, the nonce and the PKCE verifier. Doing any of that
+     * by hand here would be reimplementing the part of this that is genuinely
+     * hard to get right.
+     */
+    async complete(currentUrl: URL, transaction: OidcTransaction): Promise<OidcClaims> {
+      const as = await configuration();
+
+      let tokens: client.TokenEndpointResponse & client.TokenEndpointResponseHelpers;
+      try {
+        tokens = await client.authorizationCodeGrant(as, currentUrl, {
+          pkceCodeVerifier: transaction.verifier,
+          expectedState: transaction.state,
+          expectedNonce: transaction.nonce,
+        });
+      } catch (error) {
+        logger.warn("OIDC callback rejected", { error: String(error) });
+        throw new ApiError("unauthenticated", "Sign-in could not be completed. Please try again.");
+      }
+
+      const claims = tokens.claims();
+      if (!claims?.sub) {
+        throw new ApiError("unauthenticated", "The identity provider returned no subject.");
+      }
+
+      // Not every provider puts email, name and groups in the ID token; some
+      // keep them at the userinfo endpoint, and some only release groups
+      // there. Ask only when something is missing.
+      const groupsClaim = config.MICA_OIDC_GROUPS_CLAIM;
+
+      let { email, emailVerified } = emailFrom(claims);
+      let name = typeof claims["name"] === "string" ? claims["name"] : "";
+      let groups = readGroups(claims[groupsClaim]);
+
+      if (!email || !emailVerified || !name || groups.length === 0) {
+        try {
+          const info = await client.fetchUserInfo(as, tokens.access_token, claims.sub);
+          ({ email, emailVerified } = emailFrom(claims, info));
+          name ||= typeof info.name === "string" ? info.name : "";
+          if (groups.length === 0) groups = readGroups(info[groupsClaim]);
+        } catch (error) {
+          logger.debug("OIDC userinfo unavailable", { error: String(error) });
+        }
+      }
+
+      if (!email) {
+        // Mica names people by email — it is who the commits are from. An
+        // identity without one cannot be shown to anybody, so it is refused
+        // rather than displayed as blank.
+        throw new ApiError(
+          "unauthenticated",
+          "The identity provider did not release an email address. " +
+            "Grant Mica the `email` scope.",
+        );
+      }
+
+      return {
+        issuer: String(claims.iss),
+        subject: String(claims.sub),
+        email,
+        emailVerified,
+        name: name || email,
+        groups,
+      };
+    },
+
+    /**
+     * Where to send the browser to end the provider's session too.
+     *
+     * Null when the provider does not advertise the endpoint: signing out of
+     * Mica always works, and signing out of the IdP is a bonus that not every
+     * deployment can offer.
+     */
+    async endSessionUrl(): Promise<string | null> {
+      try {
+        const as = await configuration();
+        return client
+          .buildEndSessionUrl(as, {
+            post_logout_redirect_uri: new URL("/admin/", config.MICA_PUBLIC_URL).toString(),
+          })
+          .toString();
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+export type OidcService = ReturnType<typeof createOidcService>;
+
+/**
+ * A groups claim, from a provider that may not send one and is under no
+ * obligation to send it as an array.
+ *
+ * Keycloak sends a list of paths, Entra a list of ids, some deployments a
+ * single string, and a misconfigured mapper sends an object. Everything that
+ * is not a string in a list is dropped rather than coerced, because a group
+ * name Mica invented would be a group name that could match a rule.
+ */
+function readGroups(value: unknown): string[] {
+  if (typeof value === "string") return value.split(/[,\s]+/).filter(Boolean);
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+/** A random return path token, for the local mode that has no provider. */
+export const randomToken = (): string => randomBytes(32).toString("base64url");

package/src/return-to.ts

@@ -0,0 +1,21 @@
+/**
+ * Where the browser goes after sign-in: a page of this editor, or the start page.
+ *
+ * Parsed the way a browser parses a `Location`, so that `/\evil.example`, a
+ * tab or a line break cannot turn a path into another host (#87).
+ */
+export function safeReturnTo(raw: string | undefined, publicUrl: string): string {
+  const fallback = "/admin/";
+  if (!raw || !raw.startsWith("/")) return fallback;
+
+  let url: URL;
+  try {
+    url = new URL(raw, publicUrl);
+  } catch {
+    return fallback;
+  }
+
+  if (url.origin !== new URL(publicUrl).origin) return fallback;
+  if (url.pathname !== "/admin" && !url.pathname.startsWith("/admin/")) return fallback;
+  return `${url.pathname}${url.search}${url.hash}`;
+}

package/src/routes.ts

@@ -0,0 +1,196 @@
+/**
+ * Authentication routes.
+ *
+ * The authorization code flow, and nothing else. There is no login form here,
+ * no password check and no reset: the browser is sent to an identity provider,
+ * comes back with a code, and Mica exchanges it for a statement about who the
+ * person is.
+ *
+ * What Mica still decides is whether that person may edit *this site*. A valid
+ * token from a correctly configured provider proves an identity and nothing
+ * more; `admission.ts` is the gate, and an unknown person hits it.
+ */
+
+import { Hono } from "hono";
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+
+import { ApiError, clientIp, type Env, type RateLimiter } from "@micacms/runtime";
+
+import type { AdmissionPolicy } from "./admission.js";
+import type { AuthConfig } from "./config.js";
+import { requireAccess, sessionOf, type GateDeps } from "./gate.js";
+import { safeReturnTo } from "./return-to.js";
+import {
+  establishSession,
+  type SessionIdentity,
+  type SessionService,
+} from "./session.js";
+import {
+  openTransaction,
+  sealTransaction,
+  type OidcClaims,
+  type OidcService,
+} from "./oidc.js";
+
+const identityOf = (claims: OidcClaims): SessionIdentity => ({
+  issuer: claims.issuer,
+  subject: claims.subject,
+  email: claims.email,
+  emailVerified: claims.emailVerified,
+  name: claims.name,
+  groups: claims.groups,
+});
+
+/** Why a sign-in came back to the login view. The SPA has the words for each. */
+export type SignInRefusal = "rate_limited" | "expired" | "failed" | "not_admitted" | "too_large";
+
+export interface AuthRoutesDeps {
+  config: AuthConfig;
+  sessions: SessionService;
+  oidc: OidcService;
+  admission: AdmissionPolicy;
+  loginLimiter: RateLimiter;
+}
+
+export function authRoutes(deps: AuthRoutesDeps): Hono<Env> {
+  const app = new Hono<Env>();
+  const { config, sessions, oidc, admission } = deps;
+  const gate: GateDeps = deps;
+
+  /**
+   * What the sign-in screen needs to know before it draws anything.
+   *
+   * Public: it reveals only that this deployment authenticates and which
+   * provider it uses, which the redirect would reveal a moment later anyway.
+   */
+  app.get("/config", (c) =>
+    c.json({
+      authRequired: true,
+      provider: config.MICA_OIDC_ISSUER ? new URL(config.MICA_OIDC_ISSUER).hostname : null,
+    }),
+  );
+
+  /** Starts the flow. A redirect, not a form post. */
+  app.get("/login", async (c) => {
+    const returnTo = safeReturnTo(c.req.query("returnTo"), config.MICA_PUBLIC_URL);
+
+    // Rate limited on the way out and on the way back (in /callback): starting a
+    // flow is cheap for a client and costs Mica a discovery request.
+    const limit = deps.loginLimiter.check(`oidc:${clientIp(c)}`);
+    if (!limit.allowed) {
+      throw new ApiError(
+        "rate_limited",
+        `Too many sign-in attempts. Try again in ${Math.ceil(limit.retryAfter / 60)} minutes.`,
+        { headers: { "retry-after": String(limit.retryAfter) } },
+      );
+    }
+
+    const { url, transaction } = await oidc.begin(returnTo);
+
+    setCookie(c, sessions.names.transaction, sealTransaction(transaction, config.sessionSecret), {
+      path: "/api/auth",
+      httpOnly: true,
+      secure: config.cookieSecure,
+      // Lax, not Strict: the provider redirects the browser back here from
+      // another origin, and Strict would withhold the cookie exactly then.
+      sameSite: "Lax",
+      maxAge: 15 * 60,
+    });
+
+    return c.redirect(url);
+  });
+
+  /**
+   * Where the provider sends the browser back.
+   *
+   * A browser is following a redirect here, not making an XHR, so a failure
+   * must not be a JSON error envelope — that would put a wall of braces on the
+   * screen. Everything that can go wrong goes back to the sign-in page with a
+   * message the person can act on.
+   */
+  app.get("/callback", async (c) => {
+    const logger = c.get("logger");
+
+    // A code, not a sentence: the URL lands in browser history and proxy logs,
+    // so it must not carry the person's address (#150). The login view words it.
+    const refuse = (code: SignInRefusal) => c.redirect(`/admin/login?error=${code}`);
+
+    // A replayed transaction cookie would call the token endpoint each time.
+    // Its own key, so that one sign-in does not count twice against the start.
+    if (!deps.loginLimiter.check(`oidc-callback:${clientIp(c)}`).allowed) {
+      return refuse("rate_limited");
+    }
+
+    const sealed = getCookie(c, sessions.names.transaction);
+    deleteCookie(c, sessions.names.transaction, { path: "/api/auth", secure: config.cookieSecure });
+
+    const transaction = sealed ? openTransaction(sealed, config.sessionSecret) : null;
+    if (!transaction) {
+      // Expired, tampered with, or a callback nobody asked for.
+      return refuse("expired");
+    }
+
+    let claims: OidcClaims;
+    try {
+      claims = await oidc.complete(new URL(c.req.url), transaction);
+    } catch (error) {
+      logger.warn("Sign-in could not be completed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return refuse("failed");
+    }
+
+    const identity = identityOf(claims);
+
+    /**
+     * Authentication succeeded; admission is a separate question.
+     *
+     * A provider may vouch for an entire company. The admission rules are what
+     * say this particular person may edit this particular site, and their
+     * refusal is the expected answer for everybody who was not meant to be
+     * here — so it is a plain message, not an error.
+     */
+    const verdict = admission.admits(identity);
+    if (!verdict.admitted) {
+      logger.warn("Authenticated but not admitted", {
+        subject: identity.subject,
+        reason: verdict.reason,
+      });
+      return refuse("not_admitted");
+    }
+
+    try {
+      establishSession(c, sessions, identity);
+    } catch (error) {
+      logger.error("Could not start a session", { subject: identity.subject, error });
+      return refuse("too_large");
+    }
+    logger.info("Signed in", { subject: identity.subject, issuer: identity.issuer });
+
+    return c.redirect(transaction.returnTo);
+  });
+
+  // There is no server-side session to end; clearing the cookies is sign-out.
+  app.post("/logout", async (c) => {
+    deleteCookie(c, sessions.names.session, sessions.clearedCookieOptions());
+    deleteCookie(c, sessions.names.csrf, sessions.clearedCookieOptions());
+
+    // Offered, not followed: ending the provider's session is the provider's
+    // decision to make, and the SPA sends the browser there if it is there.
+    return c.json({ ok: true, endSession: await oidc.endSessionUrl() });
+  });
+
+  /** The session this request is in, and who it belongs to. */
+  app.get("/me", requireAccess(gate), (c) => {
+    const session = sessionOf(c);
+    const { identity } = c.get("access");
+
+    return c.json({
+      identity,
+      csrfToken: session.csrfToken,
+      expiresAt: session.expiresAt,
+    });
+  });
+
+  return app;
+}