@mandujs/core 0.54.31 → 0.55.0-beta.1

package/src/middleware/oauth/index.ts

@@ -1,505 +1,505 @@
-/**
- * OAuth 2.0 Authorization-Code + PKCE Middleware
- *
- * Single middleware that owns two request paths:
- *
- *   1. `/auth/:provider`          — initiates the OAuth flow by redirecting to
- *                                   the provider's authorization endpoint with
- *                                   a freshly generated `state` (and optional
- *                                   PKCE `code_challenge`) stashed in session.
- *   2. `/auth/:provider/callback` — completes the flow: verifies `state`,
- *                                   exchanges `code` for an access token,
- *                                   fetches userinfo, delegates to the
- *                                   caller's `resolveUser`, and finally calls
- *                                   `loginUser(ctx, userId)`.
- *
- * All other paths pass through unchanged (middleware returns `void`).
- *
- * Session dependency: the state/nonce for each in-flight auth is stored in
- * the session under `oauth:pending`. Install {@link session} upstream — we
- * throw a clear error when it is missing rather than silently failing.
- *
- * @example
- * ```ts
- * import { oauth, github, session } from "@mandujs/core/middleware";
- *
- * export default Mandu.filling()
- *   .use(session({ storage }))
- *   .use(oauth({
- *     provider: github(),
- *     clientId: process.env.GITHUB_CLIENT_ID!,
- *     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
- *     redirectUri: "https://example.com/auth/github/callback",
- *     resolveUser: async (profile) => {
- *       const user = await db.users.upsertByOAuth("github", profile.id, {
- *         email: profile.email,
- *         name: profile.name,
- *       });
- *       return user.id;
- *     },
- *   }));
- * ```
- *
- * @module middleware/oauth
- */
-
-import type { ManduContext } from "../../filling/context";
-import type { Session } from "../../filling/session";
-import { AuthenticationError } from "../../filling/auth";
-import { saveSession } from "../session";
-import { loginUser } from "../../auth/login";
-import { newId } from "../../id";
-
-// ========== Public Types ==========
-
-/**
- * Provider preset describing the OAuth endpoints, default scopes, and profile
- * normalizer. Ship custom presets by constructing this struct directly.
- */
-export interface OAuthProvider {
-  /** Short identifier (e.g. `"github"`, `"google"`). Appears in the path and in the pending-state record. */
-  name: string;
-  /** Provider-side authorization URL the user is redirected to. */
-  authorizationEndpoint: string;
-  /** Provider-side token endpoint the middleware POSTs to for the code-for-token exchange. */
-  tokenEndpoint: string;
-  /** Provider-side userinfo endpoint the middleware GETs after obtaining an access token. */
-  userinfoEndpoint: string;
-  /** Default scopes requested when `options.scopes` is not supplied. */
-  scopes: string[];
-  /** Maps the raw userinfo JSON into Mandu's {@link OAuthProfile} shape. */
-  normalizeProfile: (raw: unknown) => OAuthProfile;
-  /** Enable PKCE (default: `true`). Both GitHub and Google support it. */
-  pkce?: boolean;
-}
-
-/** Normalized profile produced by `provider.normalizeProfile`. */
-export interface OAuthProfile {
-  /** Provider-scoped user id. Always a string — presets coerce numeric IDs. */
-  id: string;
-  email?: string;
-  name?: string;
-  avatarUrl?: string;
-  /** Raw provider JSON — preserved for app-specific extraction beyond the common fields. */
-  raw: unknown;
-}
-
-export interface OAuthOptions {
-  /** Provider preset or custom {@link OAuthProvider}. */
-  provider: OAuthProvider;
-  /** OAuth app `client_id`. Public. */
-  clientId: string;
-  /** OAuth app `client_secret`. Treated as sensitive — never echoed to the user. */
-  clientSecret: string;
-  /** Absolute URL the user is redirected to after authorization. Must match the value registered with the provider. */
-  redirectUri: string;
-  /** Optional override for `provider.scopes`. */
-  scopes?: string[];
-  /**
-   * Called after the provider returns a verified profile. Return either:
-   *   - a local user id (`string`) → middleware calls `loginUser(ctx, id)` then redirects to `postLoginRedirect`
-   *   - a full `Response`        → bubbled up unchanged (e.g. redirect to /signup for unknown users)
-   */
-  resolveUser: (profile: OAuthProfile, ctx: ManduContext) => Promise<string | Response>;
-  /**
-   * Paths owned by this middleware. Defaults:
-   *   `{ start: "/auth/:provider", callback: "/auth/:provider/callback" }`
-   *
-   * The `:provider` placeholder is replaced with `provider.name` at factory time.
-   */
-  paths?: { start?: string; callback?: string };
-  /** Where to redirect after a successful login. Default: `"/"`. */
-  postLoginRedirect?: string;
-}
-
-/** Middleware signature shared with `csrf.ts` / `session.ts`. */
-type Middleware = (ctx: ManduContext) => Promise<Response | void>;
-
-/**
- * Fetch seam. Tests inject a recorder; production uses `globalThis.fetch`.
- * Kept as an internal type so only {@link _oauthWith} exposes it.
- */
-type FetchFn = typeof globalThis.fetch;
-
-// ========== Constants ==========
-
-const SESSION_PENDING_KEY = "oauth:pending";
-const DEFAULT_START_PATH = "/auth/:provider";
-const DEFAULT_CALLBACK_PATH = "/auth/:provider/callback";
-const DEFAULT_POST_LOGIN_REDIRECT = "/";
-/** Guard against oversized state values coming back from providers. */
-const MAX_STATE_LENGTH = 256;
-
-// ========== Shape of the pending state record we stash in session ==========
-
-interface OAuthPending {
-  state: string;
-  codeVerifier: string | null;
-  provider: string;
-}
-
-// ========== Public Factory ==========
-
-/**
- * Construct an OAuth middleware bound to `globalThis.fetch`.
- *
- * See {@link _oauthWith} for the testable variant that accepts an injected
- * fetch implementation — tests use it to record/mock provider HTTP round-trips
- * without hitting the network.
- */
-export function oauth(options: OAuthOptions): Middleware {
-  return _oauthWith(globalThis.fetch.bind(globalThis), options);
-}
-
-/**
- * Testing seam — identical behavior to {@link oauth} except the HTTP client is
- * injected. Exported under an underscore prefix to signal "public API for
- * tests only"; not part of the framework's semver surface.
- *
- * @internal
- */
-export function _oauthWith(fetchImpl: FetchFn, options: OAuthOptions): Middleware {
-  validateOptions(options);
-
-  const startPath = resolveOwnedPath(
-    options.paths?.start ?? DEFAULT_START_PATH,
-    options.provider.name,
-  );
-  const callbackPath = resolveOwnedPath(
-    options.paths?.callback ?? DEFAULT_CALLBACK_PATH,
-    options.provider.name,
-  );
-  const pkceEnabled = options.provider.pkce ?? true;
-  const scopes = options.scopes ?? options.provider.scopes;
-  const postLoginRedirect = options.postLoginRedirect ?? DEFAULT_POST_LOGIN_REDIRECT;
-
-  return async (ctx: ManduContext): Promise<Response | void> => {
-    const url = new URL(ctx.request.url);
-    const pathname = url.pathname;
-
-    if (pathname === startPath) {
-      return handleStart(ctx, {
-        provider: options.provider,
-        clientId: options.clientId,
-        redirectUri: options.redirectUri,
-        scopes,
-        pkceEnabled,
-      });
-    }
-
-    if (pathname === callbackPath) {
-      return handleCallback(ctx, url, {
-        fetchImpl,
-        provider: options.provider,
-        clientId: options.clientId,
-        clientSecret: options.clientSecret,
-        redirectUri: options.redirectUri,
-        pkceEnabled,
-        resolveUser: options.resolveUser,
-        postLoginRedirect,
-      });
-    }
-
-    // Any other path: pass through. Other middleware / handlers will take over.
-    return;
-  };
-}
-
-// ========== Start Flow ==========
-
-interface StartParams {
-  provider: OAuthProvider;
-  clientId: string;
-  redirectUri: string;
-  scopes: string[];
-  pkceEnabled: boolean;
-}
-
-async function handleStart(ctx: ManduContext, params: StartParams): Promise<Response> {
-  const session = requireSession(ctx);
-
-  // 1. Generate state + optional PKCE pair.
-  const state = newId();
-  const codeVerifier = params.pkceEnabled ? generateCodeVerifier() : null;
-  const codeChallenge = codeVerifier ? await sha256Base64Url(codeVerifier) : null;
-
-  // 2. Stash { state, codeVerifier, provider } under "oauth:pending" so the
-  //    callback can later verify and consume it. Storing `codeVerifier` in
-  //    session (server-signed cookie) never exposes it to the browser URL.
-  const pending: OAuthPending = {
-    state,
-    codeVerifier,
-    provider: params.provider.name,
-  };
-  session.set(SESSION_PENDING_KEY, pending);
-
-  // 3. Commit the session BEFORE building the redirect Response so the
-  //    Set-Cookie lands on this response. (Redirects snapshot cookies at
-  //    build time — same ordering hazard as loginUser.)
-  await saveSession(ctx);
-
-  // 4. Build authorization URL and redirect.
-  const authUrl = new URL(params.provider.authorizationEndpoint);
-  authUrl.searchParams.set("response_type", "code");
-  authUrl.searchParams.set("client_id", params.clientId);
-  authUrl.searchParams.set("redirect_uri", params.redirectUri);
-  authUrl.searchParams.set("scope", params.scopes.join(" "));
-  authUrl.searchParams.set("state", state);
-  if (codeChallenge) {
-    authUrl.searchParams.set("code_challenge", codeChallenge);
-    authUrl.searchParams.set("code_challenge_method", "S256");
-  }
-
-  return ctx.redirect(authUrl.toString());
-}
-
-// ========== Callback Flow ==========
-
-interface CallbackParams {
-  fetchImpl: FetchFn;
-  provider: OAuthProvider;
-  clientId: string;
-  clientSecret: string;
-  redirectUri: string;
-  pkceEnabled: boolean;
-  resolveUser: OAuthOptions["resolveUser"];
-  postLoginRedirect: string;
-}
-
-async function handleCallback(
-  ctx: ManduContext,
-  url: URL,
-  params: CallbackParams,
-): Promise<Response> {
-  const session = requireSession(ctx);
-
-  const returnedState = url.searchParams.get("state");
-  const code = url.searchParams.get("code");
-
-  // Pull pending state regardless of later outcome so a failed callback can't
-  // be retried against the same captured state (replay defense).
-  const pending = session.get<OAuthPending>(SESSION_PENDING_KEY) ?? null;
-  if (pending) {
-    session.unset(SESSION_PENDING_KEY);
-    // Flush the session so the cleared pending record persists even if this
-    // callback ultimately returns 403 — without this, a second callback hit
-    // would still see the pending record and succeed on a replayed state.
-    await saveSession(ctx);
-  }
-
-  if (
-    !pending ||
-    pending.provider !== params.provider.name ||
-    typeof returnedState !== "string" ||
-    returnedState.length === 0 ||
-    returnedState.length > MAX_STATE_LENGTH ||
-    typeof pending.state !== "string" ||
-    !safeEqual(returnedState, pending.state)
-  ) {
-    return ctx.forbidden("OAuth state mismatch");
-  }
-
-  if (typeof code !== "string" || code.length === 0) {
-    return ctx.forbidden("OAuth state mismatch");
-  }
-
-  // --- Token exchange ---
-  let accessToken: string;
-  try {
-    accessToken = await exchangeCode(params, code, pending.codeVerifier);
-  } catch {
-    return ctx.json(
-      { error: "oauth_failed", provider: params.provider.name },
-      502,
-    );
-  }
-
-  // --- Userinfo ---
-  let rawProfile: unknown;
-  try {
-    rawProfile = await fetchUserinfo(params, accessToken);
-  } catch {
-    return ctx.json(
-      { error: "oauth_failed", provider: params.provider.name },
-      502,
-    );
-  }
-
-  // --- Normalize + delegate to caller ---
-  const profile = params.provider.normalizeProfile(rawProfile);
-  const resolved = await params.resolveUser(profile, ctx);
-
-  if (resolved instanceof Response) {
-    // Caller took control (e.g. redirect to /signup). Bubble up unchanged —
-    // they did NOT opt into loginUser, so we honor that.
-    return resolved;
-  }
-
-  if (typeof resolved !== "string" || resolved.length === 0) {
-    throw new AuthenticationError(
-      "OAuth resolveUser must return a non-empty user id string or a Response",
-    );
-  }
-
-  await loginUser(ctx, resolved);
-  return ctx.redirect(params.postLoginRedirect);
-}
-
-// ========== Token exchange helpers ==========
-
-async function exchangeCode(
-  params: CallbackParams,
-  code: string,
-  codeVerifier: string | null,
-): Promise<string> {
-  const body = new URLSearchParams();
-  body.set("grant_type", "authorization_code");
-  body.set("code", code);
-  body.set("redirect_uri", params.redirectUri);
-  body.set("client_id", params.clientId);
-  body.set("client_secret", params.clientSecret);
-  if (params.pkceEnabled && codeVerifier) {
-    body.set("code_verifier", codeVerifier);
-  }
-
-  // `Accept: application/json` asks GitHub to return JSON instead of its
-  // default urlencoded response. Google + most modern providers already
-  // default to JSON — the extra header is harmless for them.
-  const response = await params.fetchImpl(params.provider.tokenEndpoint, {
-    method: "POST",
-    headers: {
-      "Accept": "application/json",
-      "Content-Type": "application/x-www-form-urlencoded",
-    },
-    body: body.toString(),
-  });
-
-  if (!response.ok) {
-    throw new Error(`token endpoint returned ${response.status}`);
-  }
-
-  const payload = (await response.json()) as unknown;
-  const token = extractAccessToken(payload);
-  if (!token) {
-    throw new Error("token endpoint returned no access_token");
-  }
-  return token;
-}
-
-async function fetchUserinfo(params: CallbackParams, accessToken: string): Promise<unknown> {
-  const response = await params.fetchImpl(params.provider.userinfoEndpoint, {
-    method: "GET",
-    headers: {
-      "Accept": "application/json",
-      "Authorization": `Bearer ${accessToken}`,
-      // GitHub requires a User-Agent — harmless for other providers.
-      "User-Agent": "mandu-oauth-middleware",
-    },
-  });
-
-  if (!response.ok) {
-    throw new Error(`userinfo endpoint returned ${response.status}`);
-  }
-
-  return (await response.json()) as unknown;
-}
-
-function extractAccessToken(payload: unknown): string | null {
-  if (!payload || typeof payload !== "object") return null;
-  const rec = payload as Record<string, unknown>;
-  const token = rec["access_token"];
-  return typeof token === "string" && token.length > 0 ? token : null;
-}
-
-// ========== Internal utilities ==========
-
-function validateOptions(options: OAuthOptions): void {
-  if (!options || typeof options !== "object") {
-    throw new Error("[Mandu OAuth] options is required");
-  }
-  if (!options.provider || typeof options.provider !== "object") {
-    throw new Error("[Mandu OAuth] `provider` is required");
-  }
-  if (typeof options.provider.name !== "string" || options.provider.name.length === 0) {
-    throw new Error("[Mandu OAuth] `provider.name` must be a non-empty string");
-  }
-  if (typeof options.clientId !== "string" || options.clientId.length === 0) {
-    throw new Error("[Mandu OAuth] `clientId` must be a non-empty string");
-  }
-  if (typeof options.clientSecret !== "string" || options.clientSecret.length === 0) {
-    throw new Error("[Mandu OAuth] `clientSecret` must be a non-empty string");
-  }
-  if (typeof options.redirectUri !== "string" || options.redirectUri.length === 0) {
-    throw new Error("[Mandu OAuth] `redirectUri` must be a non-empty string");
-  }
-  if (typeof options.resolveUser !== "function") {
-    throw new Error("[Mandu OAuth] `resolveUser` must be a function");
-  }
-}
-
-/**
- * Replace a `:provider` placeholder in the configured path with the actual
- * provider name. We do NOT try to reuse the router — middleware runs inline
- * for every request, so path matching here is simple string equality.
- */
-function resolveOwnedPath(template: string, providerName: string): string {
-  return template.replace(/:provider\b/g, providerName);
-}
-
-/** Require an installed session or throw a 500-class wiring error. */
-function requireSession(ctx: ManduContext): Session {
-  const session = ctx.get<Session>("session");
-  if (!session) {
-    throw new AuthenticationError(
-      "OAuth middleware requires session middleware upstream — add `.use(session({ storage }))` before `.use(oauth(...))`.",
-    );
-  }
-  return session;
-}
-
-/**
- * Constant-time comparison shared with {@link "../csrf".safeEqual}. Kept as a
- * local copy (rather than importing) to avoid creating a public export from
- * csrf.ts just for this — the logic is four lines and identical behavior.
- *
- * IMPORTANT: we still return `false` on length mismatch because our state
- * values are fixed-format UUIDs; the length itself is not secret.
- */
-function safeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return diff === 0;
-}
-
-/**
- * RFC 7636 §4.1 code_verifier: 43-128 character high-entropy string. We emit
- * the 43-character lower bound (32 random bytes → 43 base64url chars) which
- * is well above the RFC's 256-bit entropy minimum.
- */
-function generateCodeVerifier(): string {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  return base64UrlEncode(bytes);
-}
-
-/** RFC 7636 §4.2 S256: BASE64URL(SHA-256(ASCII(code_verifier))). */
-async function sha256Base64Url(input: string): Promise<string> {
-  const encoded = new TextEncoder().encode(input);
-  const digest = await crypto.subtle.digest("SHA-256", encoded);
-  return base64UrlEncode(new Uint8Array(digest));
-}
-
-function base64UrlEncode(bytes: Uint8Array): string {
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-
-// ========== Provider presets ==========
-
-export { github, google } from "./providers";
+/**
+ * OAuth 2.0 Authorization-Code + PKCE Middleware
+ *
+ * Single middleware that owns two request paths:
+ *
+ *   1. `/auth/:provider`          — initiates the OAuth flow by redirecting to
+ *                                   the provider's authorization endpoint with
+ *                                   a freshly generated `state` (and optional
+ *                                   PKCE `code_challenge`) stashed in session.
+ *   2. `/auth/:provider/callback` — completes the flow: verifies `state`,
+ *                                   exchanges `code` for an access token,
+ *                                   fetches userinfo, delegates to the
+ *                                   caller's `resolveUser`, and finally calls
+ *                                   `loginUser(ctx, userId)`.
+ *
+ * All other paths pass through unchanged (middleware returns `void`).
+ *
+ * Session dependency: the state/nonce for each in-flight auth is stored in
+ * the session under `oauth:pending`. Install {@link session} upstream — we
+ * throw a clear error when it is missing rather than silently failing.
+ *
+ * @example
+ * ```ts
+ * import { oauth, github, session } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(session({ storage }))
+ *   .use(oauth({
+ *     provider: github(),
+ *     clientId: process.env.GITHUB_CLIENT_ID!,
+ *     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     redirectUri: "https://example.com/auth/github/callback",
+ *     resolveUser: async (profile) => {
+ *       const user = await db.users.upsertByOAuth("github", profile.id, {
+ *         email: profile.email,
+ *         name: profile.name,
+ *       });
+ *       return user.id;
+ *     },
+ *   }));
+ * ```
+ *
+ * @module middleware/oauth
+ */
+
+import type { ManduContext } from "../../filling/context";
+import type { Session } from "../../filling/session";
+import { AuthenticationError } from "../../filling/auth";
+import { saveSession } from "../session";
+import { loginUser } from "../../auth/login";
+import { newId } from "../../id";
+
+// ========== Public Types ==========
+
+/**
+ * Provider preset describing the OAuth endpoints, default scopes, and profile
+ * normalizer. Ship custom presets by constructing this struct directly.
+ */
+export interface OAuthProvider {
+  /** Short identifier (e.g. `"github"`, `"google"`). Appears in the path and in the pending-state record. */
+  name: string;
+  /** Provider-side authorization URL the user is redirected to. */
+  authorizationEndpoint: string;
+  /** Provider-side token endpoint the middleware POSTs to for the code-for-token exchange. */
+  tokenEndpoint: string;
+  /** Provider-side userinfo endpoint the middleware GETs after obtaining an access token. */
+  userinfoEndpoint: string;
+  /** Default scopes requested when `options.scopes` is not supplied. */
+  scopes: string[];
+  /** Maps the raw userinfo JSON into Mandu's {@link OAuthProfile} shape. */
+  normalizeProfile: (raw: unknown) => OAuthProfile;
+  /** Enable PKCE (default: `true`). Both GitHub and Google support it. */
+  pkce?: boolean;
+}
+
+/** Normalized profile produced by `provider.normalizeProfile`. */
+export interface OAuthProfile {
+  /** Provider-scoped user id. Always a string — presets coerce numeric IDs. */
+  id: string;
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  /** Raw provider JSON — preserved for app-specific extraction beyond the common fields. */
+  raw: unknown;
+}
+
+export interface OAuthOptions {
+  /** Provider preset or custom {@link OAuthProvider}. */
+  provider: OAuthProvider;
+  /** OAuth app `client_id`. Public. */
+  clientId: string;
+  /** OAuth app `client_secret`. Treated as sensitive — never echoed to the user. */
+  clientSecret: string;
+  /** Absolute URL the user is redirected to after authorization. Must match the value registered with the provider. */
+  redirectUri: string;
+  /** Optional override for `provider.scopes`. */
+  scopes?: string[];
+  /**
+   * Called after the provider returns a verified profile. Return either:
+   *   - a local user id (`string`) → middleware calls `loginUser(ctx, id)` then redirects to `postLoginRedirect`
+   *   - a full `Response`        → bubbled up unchanged (e.g. redirect to /signup for unknown users)
+   */
+  resolveUser: (profile: OAuthProfile, ctx: ManduContext) => Promise<string | Response>;
+  /**
+   * Paths owned by this middleware. Defaults:
+   *   `{ start: "/auth/:provider", callback: "/auth/:provider/callback" }`
+   *
+   * The `:provider` placeholder is replaced with `provider.name` at factory time.
+   */
+  paths?: { start?: string; callback?: string };
+  /** Where to redirect after a successful login. Default: `"/"`. */
+  postLoginRedirect?: string;
+}
+
+/** Middleware signature shared with `csrf.ts` / `session.ts`. */
+type Middleware = (ctx: ManduContext) => Promise<Response | void>;
+
+/**
+ * Fetch seam. Tests inject a recorder; production uses `globalThis.fetch`.
+ * Kept as an internal type so only {@link _oauthWith} exposes it.
+ */
+type FetchFn = typeof globalThis.fetch;
+
+// ========== Constants ==========
+
+const SESSION_PENDING_KEY = "oauth:pending";
+const DEFAULT_START_PATH = "/auth/:provider";
+const DEFAULT_CALLBACK_PATH = "/auth/:provider/callback";
+const DEFAULT_POST_LOGIN_REDIRECT = "/";
+/** Guard against oversized state values coming back from providers. */
+const MAX_STATE_LENGTH = 256;
+
+// ========== Shape of the pending state record we stash in session ==========
+
+interface OAuthPending {
+  state: string;
+  codeVerifier: string | null;
+  provider: string;
+}
+
+// ========== Public Factory ==========
+
+/**
+ * Construct an OAuth middleware bound to `globalThis.fetch`.
+ *
+ * See {@link _oauthWith} for the testable variant that accepts an injected
+ * fetch implementation — tests use it to record/mock provider HTTP round-trips
+ * without hitting the network.
+ */
+export function oauth(options: OAuthOptions): Middleware {
+  return _oauthWith(globalThis.fetch.bind(globalThis), options);
+}
+
+/**
+ * Testing seam — identical behavior to {@link oauth} except the HTTP client is
+ * injected. Exported under an underscore prefix to signal "public API for
+ * tests only"; not part of the framework's semver surface.
+ *
+ * @internal
+ */
+export function _oauthWith(fetchImpl: FetchFn, options: OAuthOptions): Middleware {
+  validateOptions(options);
+
+  const startPath = resolveOwnedPath(
+    options.paths?.start ?? DEFAULT_START_PATH,
+    options.provider.name,
+  );
+  const callbackPath = resolveOwnedPath(
+    options.paths?.callback ?? DEFAULT_CALLBACK_PATH,
+    options.provider.name,
+  );
+  const pkceEnabled = options.provider.pkce ?? true;
+  const scopes = options.scopes ?? options.provider.scopes;
+  const postLoginRedirect = options.postLoginRedirect ?? DEFAULT_POST_LOGIN_REDIRECT;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    const url = new URL(ctx.request.url);
+    const pathname = url.pathname;
+
+    if (pathname === startPath) {
+      return handleStart(ctx, {
+        provider: options.provider,
+        clientId: options.clientId,
+        redirectUri: options.redirectUri,
+        scopes,
+        pkceEnabled,
+      });
+    }
+
+    if (pathname === callbackPath) {
+      return handleCallback(ctx, url, {
+        fetchImpl,
+        provider: options.provider,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        redirectUri: options.redirectUri,
+        pkceEnabled,
+        resolveUser: options.resolveUser,
+        postLoginRedirect,
+      });
+    }
+
+    // Any other path: pass through. Other middleware / handlers will take over.
+    return;
+  };
+}
+
+// ========== Start Flow ==========
+
+interface StartParams {
+  provider: OAuthProvider;
+  clientId: string;
+  redirectUri: string;
+  scopes: string[];
+  pkceEnabled: boolean;
+}
+
+async function handleStart(ctx: ManduContext, params: StartParams): Promise<Response> {
+  const session = requireSession(ctx);
+
+  // 1. Generate state + optional PKCE pair.
+  const state = newId();
+  const codeVerifier = params.pkceEnabled ? generateCodeVerifier() : null;
+  const codeChallenge = codeVerifier ? await sha256Base64Url(codeVerifier) : null;
+
+  // 2. Stash { state, codeVerifier, provider } under "oauth:pending" so the
+  //    callback can later verify and consume it. Storing `codeVerifier` in
+  //    session (server-signed cookie) never exposes it to the browser URL.
+  const pending: OAuthPending = {
+    state,
+    codeVerifier,
+    provider: params.provider.name,
+  };
+  session.set(SESSION_PENDING_KEY, pending);
+
+  // 3. Commit the session BEFORE building the redirect Response so the
+  //    Set-Cookie lands on this response. (Redirects snapshot cookies at
+  //    build time — same ordering hazard as loginUser.)
+  await saveSession(ctx);
+
+  // 4. Build authorization URL and redirect.
+  const authUrl = new URL(params.provider.authorizationEndpoint);
+  authUrl.searchParams.set("response_type", "code");
+  authUrl.searchParams.set("client_id", params.clientId);
+  authUrl.searchParams.set("redirect_uri", params.redirectUri);
+  authUrl.searchParams.set("scope", params.scopes.join(" "));
+  authUrl.searchParams.set("state", state);
+  if (codeChallenge) {
+    authUrl.searchParams.set("code_challenge", codeChallenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+  }
+
+  return ctx.redirect(authUrl.toString());
+}
+
+// ========== Callback Flow ==========
+
+interface CallbackParams {
+  fetchImpl: FetchFn;
+  provider: OAuthProvider;
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  pkceEnabled: boolean;
+  resolveUser: OAuthOptions["resolveUser"];
+  postLoginRedirect: string;
+}
+
+async function handleCallback(
+  ctx: ManduContext,
+  url: URL,
+  params: CallbackParams,
+): Promise<Response> {
+  const session = requireSession(ctx);
+
+  const returnedState = url.searchParams.get("state");
+  const code = url.searchParams.get("code");
+
+  // Pull pending state regardless of later outcome so a failed callback can't
+  // be retried against the same captured state (replay defense).
+  const pending = session.get<OAuthPending>(SESSION_PENDING_KEY) ?? null;
+  if (pending) {
+    session.unset(SESSION_PENDING_KEY);
+    // Flush the session so the cleared pending record persists even if this
+    // callback ultimately returns 403 — without this, a second callback hit
+    // would still see the pending record and succeed on a replayed state.
+    await saveSession(ctx);
+  }
+
+  if (
+    !pending ||
+    pending.provider !== params.provider.name ||
+    typeof returnedState !== "string" ||
+    returnedState.length === 0 ||
+    returnedState.length > MAX_STATE_LENGTH ||
+    typeof pending.state !== "string" ||
+    !safeEqual(returnedState, pending.state)
+  ) {
+    return ctx.forbidden("OAuth state mismatch");
+  }
+
+  if (typeof code !== "string" || code.length === 0) {
+    return ctx.forbidden("OAuth state mismatch");
+  }
+
+  // --- Token exchange ---
+  let accessToken: string;
+  try {
+    accessToken = await exchangeCode(params, code, pending.codeVerifier);
+  } catch {
+    return ctx.json(
+      { error: "oauth_failed", provider: params.provider.name },
+      502,
+    );
+  }
+
+  // --- Userinfo ---
+  let rawProfile: unknown;
+  try {
+    rawProfile = await fetchUserinfo(params, accessToken);
+  } catch {
+    return ctx.json(
+      { error: "oauth_failed", provider: params.provider.name },
+      502,
+    );
+  }
+
+  // --- Normalize + delegate to caller ---
+  const profile = params.provider.normalizeProfile(rawProfile);
+  const resolved = await params.resolveUser(profile, ctx);
+
+  if (resolved instanceof Response) {
+    // Caller took control (e.g. redirect to /signup). Bubble up unchanged —
+    // they did NOT opt into loginUser, so we honor that.
+    return resolved;
+  }
+
+  if (typeof resolved !== "string" || resolved.length === 0) {
+    throw new AuthenticationError(
+      "OAuth resolveUser must return a non-empty user id string or a Response",
+    );
+  }
+
+  await loginUser(ctx, resolved);
+  return ctx.redirect(params.postLoginRedirect);
+}
+
+// ========== Token exchange helpers ==========
+
+async function exchangeCode(
+  params: CallbackParams,
+  code: string,
+  codeVerifier: string | null,
+): Promise<string> {
+  const body = new URLSearchParams();
+  body.set("grant_type", "authorization_code");
+  body.set("code", code);
+  body.set("redirect_uri", params.redirectUri);
+  body.set("client_id", params.clientId);
+  body.set("client_secret", params.clientSecret);
+  if (params.pkceEnabled && codeVerifier) {
+    body.set("code_verifier", codeVerifier);
+  }
+
+  // `Accept: application/json` asks GitHub to return JSON instead of its
+  // default urlencoded response. Google + most modern providers already
+  // default to JSON — the extra header is harmless for them.
+  const response = await params.fetchImpl(params.provider.tokenEndpoint, {
+    method: "POST",
+    headers: {
+      "Accept": "application/json",
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    throw new Error(`token endpoint returned ${response.status}`);
+  }
+
+  const payload = (await response.json()) as unknown;
+  const token = extractAccessToken(payload);
+  if (!token) {
+    throw new Error("token endpoint returned no access_token");
+  }
+  return token;
+}
+
+async function fetchUserinfo(params: CallbackParams, accessToken: string): Promise<unknown> {
+  const response = await params.fetchImpl(params.provider.userinfoEndpoint, {
+    method: "GET",
+    headers: {
+      "Accept": "application/json",
+      "Authorization": `Bearer ${accessToken}`,
+      // GitHub requires a User-Agent — harmless for other providers.
+      "User-Agent": "mandu-oauth-middleware",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`userinfo endpoint returned ${response.status}`);
+  }
+
+  return (await response.json()) as unknown;
+}
+
+function extractAccessToken(payload: unknown): string | null {
+  if (!payload || typeof payload !== "object") return null;
+  const rec = payload as Record<string, unknown>;
+  const token = rec["access_token"];
+  return typeof token === "string" && token.length > 0 ? token : null;
+}
+
+// ========== Internal utilities ==========
+
+function validateOptions(options: OAuthOptions): void {
+  if (!options || typeof options !== "object") {
+    throw new Error("[Mandu OAuth] options is required");
+  }
+  if (!options.provider || typeof options.provider !== "object") {
+    throw new Error("[Mandu OAuth] `provider` is required");
+  }
+  if (typeof options.provider.name !== "string" || options.provider.name.length === 0) {
+    throw new Error("[Mandu OAuth] `provider.name` must be a non-empty string");
+  }
+  if (typeof options.clientId !== "string" || options.clientId.length === 0) {
+    throw new Error("[Mandu OAuth] `clientId` must be a non-empty string");
+  }
+  if (typeof options.clientSecret !== "string" || options.clientSecret.length === 0) {
+    throw new Error("[Mandu OAuth] `clientSecret` must be a non-empty string");
+  }
+  if (typeof options.redirectUri !== "string" || options.redirectUri.length === 0) {
+    throw new Error("[Mandu OAuth] `redirectUri` must be a non-empty string");
+  }
+  if (typeof options.resolveUser !== "function") {
+    throw new Error("[Mandu OAuth] `resolveUser` must be a function");
+  }
+}
+
+/**
+ * Replace a `:provider` placeholder in the configured path with the actual
+ * provider name. We do NOT try to reuse the router — middleware runs inline
+ * for every request, so path matching here is simple string equality.
+ */
+function resolveOwnedPath(template: string, providerName: string): string {
+  return template.replace(/:provider\b/g, providerName);
+}
+
+/** Require an installed session or throw a 500-class wiring error. */
+function requireSession(ctx: ManduContext): Session {
+  const session = ctx.get<Session>("session");
+  if (!session) {
+    throw new AuthenticationError(
+      "OAuth middleware requires session middleware upstream — add `.use(session({ storage }))` before `.use(oauth(...))`.",
+    );
+  }
+  return session;
+}
+
+/**
+ * Constant-time comparison shared with {@link "../csrf".safeEqual}. Kept as a
+ * local copy (rather than importing) to avoid creating a public export from
+ * csrf.ts just for this — the logic is four lines and identical behavior.
+ *
+ * IMPORTANT: we still return `false` on length mismatch because our state
+ * values are fixed-format UUIDs; the length itself is not secret.
+ */
+function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+/**
+ * RFC 7636 §4.1 code_verifier: 43-128 character high-entropy string. We emit
+ * the 43-character lower bound (32 random bytes → 43 base64url chars) which
+ * is well above the RFC's 256-bit entropy minimum.
+ */
+function generateCodeVerifier(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+
+/** RFC 7636 §4.2 S256: BASE64URL(SHA-256(ASCII(code_verifier))). */
+async function sha256Base64Url(input: string): Promise<string> {
+  const encoded = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", encoded);
+  return base64UrlEncode(new Uint8Array(digest));
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// ========== Provider presets ==========
+
+export { github, google } from "./providers";