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

package/src/admission.ts

@@ -0,0 +1,132 @@
+/**
+ * Admission — who may edit this site.
+ *
+ * OpenID Connect states who a person is. It says nothing about whether that
+ * person may edit this website: a provider vouches for a whole company, and a
+ * perfectly valid ID token is the beginning of the question rather than the
+ * answer to it.
+ *
+ * Mica has no accounts, so admission is configuration:
+ *
+ *   MICA_ADMIT_GROUPS=mica-editors            a claim the provider sends
+ *   MICA_ADMIT_DOMAINS=example.com            every verified address there
+ *   MICA_ADMIT_EMAILS=alice@gmail.com        these verified addresses
+ *   MICA_ADMIT_SUBJECTS=https://id.example.com|a1b2c3
+ *
+ * The group rule is the one to grow into. Adding an editor is then a group
+ * change in the identity provider — where the operator already manages
+ * joiners and leavers — and Mica is not touched, not restarted, and holds no
+ * copy of the list to go stale. The email list exists for a provider with no
+ * groups, such as Google; the subject list for one that verifies no addresses.
+ *
+ * What this costs, and it is a real cost: removing somebody from a group at
+ * the provider does not take effect until their next sign-in, because the
+ * claims Mica checks are the ones it was given. Configuration changes *are*
+ * immediate — this policy is re-read on every request — and the session
+ * lifetime is the upper bound on the rest. docs/decisions.md records the trade.
+ */
+
+import type { AuthConfig } from "./config.js";
+import type { SessionIdentity } from "./session.js";
+
+export type AdmissionResult = { admitted: true } | { admitted: false; reason: string };
+
+export interface AdmissionPolicy {
+  /** One line for the startup log, so an operator can see what is in force. */
+  readonly summary: string;
+  admits(identity: SessionIdentity): AdmissionResult;
+}
+
+/**
+ * The strictest rule: the subject never changes and is never reassigned. The
+ * issuer is part of the key because a subject is only unique within the
+ * provider that issued it.
+ */
+function matchesSubject(
+  identity: SessionIdentity,
+  entries: ReadonlyArray<{ issuer: string; subject: string }>,
+): boolean {
+  return entries.some(
+    (entry) => entry.issuer === identity.issuer && entry.subject === identity.subject,
+  );
+}
+
+function matchesEmail(identity: SessionIdentity, emails: readonly string[]): boolean {
+  return emails.includes(identity.email.toLowerCase());
+}
+
+function matchesDomain(identity: SessionIdentity, domains: readonly string[]): boolean {
+  const at = identity.email.lastIndexOf("@");
+  if (at < 0) return false;
+  return domains.includes(identity.email.slice(at + 1).toLowerCase());
+}
+
+/**
+ * Group names are compared case-sensitively, and a leading `/` is ignored.
+ *
+ * Keycloak sends group paths — `/mica-editors` — while most other providers
+ * send bare names. Accepting both means an operator writes the name they see
+ * in their own console, which is the only name they have.
+ */
+function matchesGroup(identity: SessionIdentity, groups: readonly string[]): boolean {
+  const held = new Set(identity.groups.map((group) => group.replace(/^\//, "")));
+  return groups.some((group) => held.has(group.replace(/^\//, "")));
+}
+
+export function createAdmissionPolicy(
+  config: Pick<AuthConfig, "admitGroups" | "admitDomains" | "admitEmails" | "admitSubjects">,
+): AdmissionPolicy {
+  const { admitGroups, admitDomains, admitEmails, admitSubjects } = config;
+
+  const summary = [
+    admitGroups.length > 0 ? `group=${admitGroups.join("|")}` : null,
+    admitDomains.length > 0 ? `domain=${admitDomains.join("|")}` : null,
+    admitEmails.length > 0 ? `emails=${admitEmails.length}` : null,
+    admitSubjects.length > 0 ? `subjects=${admitSubjects.length}` : null,
+  ]
+    .filter(Boolean)
+    .join(", ");
+
+  return {
+    summary,
+
+    admits(identity) {
+      // The explicit list first: it is the escape hatch, and it has to work
+      // when the group claim is missing or the address is unverified.
+      if (matchesSubject(identity, admitSubjects)) return { admitted: true };
+
+      if (matchesGroup(identity, admitGroups)) return { admitted: true };
+
+      const byEmail = matchesEmail(identity, admitEmails);
+      if (byEmail || matchesDomain(identity, admitDomains)) {
+        /**
+         * An email or domain rule trusts the provider to have checked the address.
+         *
+         * Where a provider allows self-registration, an unverified address is
+         * a claim the person typed. Admitting on that would let anybody enter
+         * an address they do not hold, so the rule refuses and says why — the
+         * operator can turn verification on, or use a group or subject rule
+         * instead.
+         *
+         * What remains is reassignment: an organisation that gives a former
+         * editor's address to somebody new gives them this site too. Public
+         * providers such as Gmail never reuse an address; the trade is
+         * recorded in docs/decisions.md.
+         */
+        if (identity.emailVerified) return { admitted: true };
+
+        return {
+          admitted: false,
+          reason:
+            `${identity.email} is ${byEmail ? "an admitted address" : "in an admitted domain"}, ` +
+            "but the identity provider does not report the address as verified.",
+        };
+      }
+
+      return {
+        admitted: false,
+        reason: `${identity.email || identity.subject} is not admitted to this site.`,
+      };
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,221 @@
+/**
+ * The auth gate's slice of the environment.
+ *
+ * A fragment, like the runtime's: the self-hosted app spreads `authEnv` into
+ * its own schema, derives with `deriveAuth`, and passes the result here. The
+ * local editor never touches any of this — these variables do not exist in
+ * its configuration at all, which is a stronger statement than ignoring them.
+ */
+
+import { z } from "zod";
+
+import { ConfigError, list } from "@micacms/runtime";
+
+export const authEnv = {
+  /**
+   * OpenID Connect. Mica implements no passwords, no reset flow and no second
+   * factor. It asks a provider who you are; the admission rules below decide
+   * whether that person may edit this site.
+   */
+  MICA_OIDC_ISSUER: z.string().url().optional(),
+  MICA_OIDC_CLIENT_ID: z.string().optional(),
+  /** Omit for a public client using PKCE alone. */
+  MICA_OIDC_CLIENT_SECRET: z.string().optional(),
+  MICA_OIDC_SCOPE: z.string().default("openid profile email"),
+  /**
+   * Which claim carries the person's groups. There is no standard one:
+   * Keycloak and Entra normally send `groups`, others send `roles`, and some
+   * send whatever the operator mapped. Naming it here is what keeps
+   * `MICA_ADMIT_GROUPS` working against any provider.
+   */
+  MICA_OIDC_GROUPS_CLAIM: z.string().default("groups"),
+
+  /**
+   * Who may edit this site. Authentication says who somebody is; these say
+   * whether that person gets in. At least one is required — the composition
+   * refuses to start without one. Comma-separated, all four.
+   */
+  MICA_ADMIT_GROUPS: z.string().optional(),
+  MICA_ADMIT_DOMAINS: z.string().optional(),
+  /** Verified addresses — the list for a provider with no groups, such as Google. */
+  MICA_ADMIT_EMAILS: z.string().optional(),
+  /** `issuer|subject` pairs — see admission.ts. */
+  MICA_ADMIT_SUBJECTS: z.string().optional(),
+
+  /** Signs session cookies. Rotating it invalidates every session. */
+  MICA_SESSION_SECRET: z.string().min(32).optional(),
+  /**
+   * Deliberately short. Admission is configuration and is re-read on every
+   * request; what cannot be immediate is a change *at the provider*, which
+   * Mica only sees at the next sign-in. The session lifetime is therefore the
+   * upper bound on how long a revoked editor keeps working.
+   */
+  MICA_SESSION_TTL_HOURS: z.coerce.number().int().positive().default(8),
+  MICA_SESSION_IDLE_HOURS: z.coerce.number().int().positive().default(4),
+
+  MICA_SIGNIN_MAX_ATTEMPTS: z.coerce.number().int().positive().default(10),
+  MICA_SIGNIN_WINDOW_MS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(15 * 60 * 1000),
+};
+
+const authSchema = z.object(authEnv);
+export type AuthEnv = z.infer<typeof authSchema>;
+
+/** The derived values the gate reads, on top of the parsed environment. */
+export function deriveAuth<T extends AuthEnv & { NODE_ENV: string; MICA_PUBLIC_URL: string }>(
+  env: T,
+) {
+  return {
+    ...env,
+    /**
+     * Discovery over plain HTTP, for an identity provider running on
+     * localhost. Never in production, and never for a remote host.
+     */
+    oidcAllowInsecure:
+      env.NODE_ENV !== "production" &&
+      /^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(env.MICA_OIDC_ISSUER ?? ""),
+    admitGroups: list(env.MICA_ADMIT_GROUPS),
+    // Lowercased: a domain is case-insensitive, and an operator who writes
+    // `Example.com` means the same thing the provider spells `example.com`.
+    admitDomains: list(env.MICA_ADMIT_DOMAINS).map((domain) =>
+      domain.toLowerCase().replace(/^@/, ""),
+    ),
+    admitEmails: list(env.MICA_ADMIT_EMAILS).map((email) => email.toLowerCase()),
+    admitSubjects: list(env.MICA_ADMIT_SUBJECTS).map((entry) => {
+      const separator = entry.indexOf("|");
+      return {
+        issuer: separator < 0 ? "" : entry.slice(0, separator).trim(),
+        subject: separator < 0 ? entry : entry.slice(separator + 1).trim(),
+      };
+    }),
+    // Secure cookies are not sent over plain HTTP, which would break a
+    // localhost trial run.
+    cookieSecure: env.MICA_PUBLIC_URL.startsWith("https://"),
+  };
+}
+
+/** What the gate requires of a finished configuration. */
+export interface AuthConfig {
+  MICA_PUBLIC_URL: string;
+  isProduction: boolean;
+  MICA_OIDC_ISSUER?: string | undefined;
+  MICA_OIDC_CLIENT_ID?: string | undefined;
+  MICA_OIDC_CLIENT_SECRET?: string | undefined;
+  MICA_OIDC_SCOPE: string;
+  MICA_OIDC_GROUPS_CLAIM: string;
+  oidcAllowInsecure: boolean;
+  admitGroups: string[];
+  admitDomains: string[];
+  admitEmails: string[];
+  admitSubjects: Array<{ issuer: string; subject: string }>;
+  /** Resolved by the app: mandatory in production, ephemeral in development. */
+  sessionSecret: string;
+  cookieSecure: boolean;
+  MICA_SESSION_TTL_HOURS: number;
+  MICA_SESSION_IDLE_HOURS: number;
+  MICA_SIGNIN_MAX_ATTEMPTS: number;
+  MICA_SIGNIN_WINDOW_MS: number;
+}
+
+/**
+ * Domains where anybody can register an address. A domain rule naming one
+ * admits the public, so it is refused; name the addresses instead.
+ */
+const PUBLIC_EMAIL_DOMAINS = new Set([
+  "gmail.com",
+  "googlemail.com",
+  "outlook.com",
+  "hotmail.com",
+  "live.com",
+  "msn.com",
+  "yahoo.com",
+  "icloud.com",
+  "me.com",
+  "aol.com",
+  "proton.me",
+  "protonmail.com",
+  "gmx.com",
+  "gmx.net",
+  "gmx.de",
+  "gmx.ch",
+  "web.de",
+]);
+
+/**
+ * The refusals that make a deployment honest before it serves a request.
+ *
+ * An OIDC deployment that admits every person its issuer knows is a
+ * misconfiguration, not a default — see decisions.md.
+ */
+export function requireAuthConfig(config: {
+  MICA_PUBLIC_URL: string;
+  MICA_OIDC_ISSUER?: string | undefined;
+  MICA_OIDC_CLIENT_ID?: string | undefined;
+  admitGroups: string[];
+  admitDomains: string[];
+  admitEmails: string[];
+  admitSubjects: Array<{ issuer: string; subject: string }>;
+}): void {
+  const needed = (["MICA_OIDC_ISSUER", "MICA_OIDC_CLIENT_ID"] as const).filter(
+    (key) => !config[key],
+  );
+
+  if (needed.length > 0) {
+    throw new ConfigError(
+      `This deployment authenticates with OpenID Connect, so ` +
+        `${needed.join(" and ")} must be set.\n` +
+        "  Mica implements no passwords. Point it at Keycloak, Authentik,\n" +
+        "  ZITADEL, Entra, Okta, Google — anything that speaks OIDC.\n" +
+        `  The redirect URI to register is ${config.MICA_PUBLIC_URL}/api/auth/callback`,
+    );
+  }
+
+  if (
+    config.admitGroups.length === 0 &&
+    config.admitDomains.length === 0 &&
+    config.admitEmails.length === 0 &&
+    config.admitSubjects.length === 0
+  ) {
+    throw new ConfigError(
+      "Nothing says who may edit this site.\n" +
+        "  Authentication is not admission: your provider will happily vouch for\n" +
+        "  everybody it knows. Set at least one of these:\n\n" +
+        "    MICA_ADMIT_GROUPS=mica-editors            a claim your provider sends\n" +
+        "    MICA_ADMIT_DOMAINS=example.com            every verified address there\n" +
+        "    MICA_ADMIT_EMAILS=alice@gmail.com        these verified addresses\n" +
+        "    MICA_ADMIT_SUBJECTS=https://id.example.com|a1b2c3\n\n" +
+        "  The group rule is the one to grow into: adding an editor is then a\n" +
+        "  change in the identity provider, and Mica is not touched.",
+    );
+  }
+
+  const open = config.admitDomains.filter((domain) => PUBLIC_EMAIL_DOMAINS.has(domain));
+  if (open.length > 0) {
+    throw new ConfigError(
+      `MICA_ADMIT_DOMAINS names ${open.join(", ")}, where anybody can register an address.\n` +
+        "  That rule would let the public edit this site. Name the people instead:\n" +
+        "    MICA_ADMIT_EMAILS=alice@gmail.com,bob@gmail.com",
+    );
+  }
+
+  const malformed = config.admitEmails.filter((email) => !/^[^@\s]+@[^@\s]+$/.test(email));
+  if (malformed.length > 0) {
+    throw new ConfigError(
+      `MICA_ADMIT_EMAILS entries are email addresses, and these are not: ${malformed.join(", ")}`,
+    );
+  }
+
+  const wrong = config.admitSubjects.filter((entry) => !entry.issuer || !entry.subject);
+  if (wrong.length > 0) {
+    throw new ConfigError(
+      "MICA_ADMIT_SUBJECTS entries are `issuer|subject` pairs, and one is not:\n" +
+        `    ${wrong.map((entry) => entry.subject || "(empty)").join(", ")}\n\n` +
+        "  The issuer is part of the key because a subject is only unique within\n" +
+        "  the provider that issued it. To admit an address, use MICA_ADMIT_EMAILS.\n" +
+        `    MICA_ADMIT_SUBJECTS=${config.MICA_OIDC_ISSUER ?? "https://id.example.com"}|a1b2c3`,
+    );
+  }
+}

package/src/gate.ts

@@ -0,0 +1,112 @@
+/**
+ * The gate: what stands between a request and the admin API.
+ *
+ * Two layers, in order. `requireAccess` turns a session cookie into an
+ * `AccessContext` — or a 401 — re-checking admission on every request so a
+ * configuration change is immediate, and re-issuing the cookie while the
+ * session is in use. `csrfProtection` is the double-submit
+ * token over the Origin check the runtime already applies: cross-origin
+ * JavaScript can neither read the cookie nor set the header.
+ */
+
+import { getCookie, setCookie } from "hono/cookie";
+import type { Context, MiddlewareHandler } from "hono";
+
+import { ApiError, type Env } from "@micacms/runtime";
+
+import type { AdmissionPolicy } from "./admission.js";
+import {
+  CSRF_HEADER,
+  safeEqual,
+  type SessionRecord,
+  type SessionService,
+} from "./session.js";
+
+/**
+ * The session behind the current request. Auth's own context variable —
+ * the runtime knows only the `access` it derives from it.
+ */
+const SESSION_VARIABLE = "authSession";
+
+export function sessionOf(c: Context<Env>): SessionRecord {
+  // Set by requireAccess, which runs in front of everything that calls this.
+  return c.get(SESSION_VARIABLE as never) as SessionRecord;
+}
+
+export interface GateDeps {
+  sessions: SessionService;
+  admission: AdmissionPolicy;
+}
+
+/**
+ * Rejects the request unless there is a live session whose person is still
+ * admitted.
+ *
+ * Admission is re-read on every request, not decided once at sign-in. That is
+ * what makes a configuration change immediate: an operator who takes somebody
+ * out of `MICA_ADMIT_SUBJECTS` and restarts has removed them. What it cannot
+ * make immediate is a group removal at the provider — the claims here are the
+ * ones the provider sent, and Mica learns better at the next sign-in.
+ */
+export function requireAccess(deps: GateDeps): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    let session = deps.sessions.resolve(getCookie(c, deps.sessions.names.session));
+
+    if (!session) {
+      throw new ApiError("unauthenticated", "Your session has expired. Please sign in again.");
+    }
+
+    const { identity } = session;
+
+    const verdict = deps.admission.admits(identity);
+    if (!verdict.admitted) {
+      c.get("logger").warn("Session no longer admitted", {
+        subject: identity.subject,
+        reason: verdict.reason,
+      });
+      throw new ApiError("forbidden", "You no longer have access to this site.");
+    }
+
+    const refreshed = deps.sessions.refresh(session);
+    if (refreshed) session = refreshed.record;
+
+    c.set(SESSION_VARIABLE as never, session as never);
+    c.set("access", {
+      identity: { subject: identity.subject, email: identity.email, name: identity.name },
+    });
+    await next();
+
+    // After the handler, so the cookie lands on whatever response it built.
+    if (refreshed) {
+      setCookie(c, deps.sessions.names.session, refreshed.cookie, deps.sessions.sessionCookieOptions());
+    }
+  };
+}
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * Second CSRF layer: double-submit token. The session's token is issued in a
+ * cookie the SPA can read and must be echoed in a header.
+ *
+ * Runs after `requireAccess`, and complements the session cookie's
+ * `SameSite=Lax`, which already blocks the classic cross-site form post.
+ */
+export function csrfProtection(deps: GateDeps): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    if (SAFE_METHODS.has(c.req.method)) {
+      await next();
+      return;
+    }
+
+    const session = sessionOf(c);
+    const header = c.req.header(CSRF_HEADER);
+    const cookie = getCookie(c, deps.sessions.names.csrf);
+
+    if (!header || !cookie || !safeEqual(header, cookie) || !safeEqual(header, session.csrfToken)) {
+      throw new ApiError("forbidden", "Invalid or missing CSRF token. Reload the page and retry.");
+    }
+
+    await next();
+  };
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @micacms/auth-oidc — the server-only OIDC gate around @micacms/runtime.
+ *
+ * One factory: hand it the finished configuration and a logger, and it
+ * returns the `AuthSurface` the runtime mounts — sign-in
+ * routes at `/api/auth`, and the session-plus-CSRF gate in front of the admin
+ * API — together with the services the composing app reports on.
+ *
+ * This package is a dependency of `@micacms/self-hosted` and of nothing else.
+ * The local editor must never gain a path to it: that absence is the product
+ * boundary that keeps `npx @micacms/editor` free of authentication code.
+ */
+
+import type { AuthSurface, Logger } from "@micacms/runtime";
+import { createRateLimiter, type RateLimiter } from "@micacms/runtime";
+
+import { createAdmissionPolicy, type AdmissionPolicy } from "./admission.js";
+import type { AuthConfig } from "./config.js";
+import { csrfProtection, requireAccess } from "./gate.js";
+import { createOidcService, type OidcService } from "./oidc.js";
+import { authRoutes } from "./routes.js";
+import { createSessionService, type SessionService } from "./session.js";
+
+export interface OidcAuthDeps {
+  config: AuthConfig;
+  logger: Logger;
+}
+
+export interface OidcAuth {
+  /** What `createApp` mounts: routes at /api/auth, the gate before /api/admin. */
+  surface: AuthSurface;
+  sessions: SessionService;
+  admission: AdmissionPolicy;
+  oidc: OidcService;
+  loginLimiter: RateLimiter;
+}
+
+export function createOidcAuth(deps: OidcAuthDeps): OidcAuth {
+  const { config, logger } = deps;
+
+  const sessions = createSessionService(config);
+  const admission = createAdmissionPolicy(config);
+  const oidc = createOidcService({ config, logger });
+  const loginLimiter = createRateLimiter({
+    limit: config.MICA_SIGNIN_MAX_ATTEMPTS,
+    windowMs: config.MICA_SIGNIN_WINDOW_MS,
+  });
+
+  const gate = { sessions, admission };
+
+  return {
+    surface: {
+      routes: authRoutes({ config, sessions, oidc, admission, loginLimiter }),
+      gate: [requireAccess(gate), csrfProtection(gate)],
+    },
+    sessions,
+    admission,
+    oidc,
+    loginLimiter,
+  };
+}
+
+export { createAdmissionPolicy, type AdmissionPolicy, type AdmissionResult } from "./admission.js";
+export {
+  authEnv,
+  deriveAuth,
+  requireAuthConfig,
+  type AuthConfig,
+  type AuthEnv,
+} from "./config.js";
+export { csrfProtection, requireAccess, sessionOf } from "./gate.js";
+export { createOidcService, type OidcService } from "./oidc.js";
+export {
+  cookieNames,
+  createSessionService,
+  CSRF_COOKIE,
+  CSRF_HEADER,
+  SESSION_COOKIE,
+  type SessionIdentity,
+  type SessionRecord,
+  type SessionService,
+} from "./session.js";