@mandujs/core 0.21.0 → 0.22.0

package/src/middleware/oauth/index.ts

@@ -0,0 +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";

package/src/middleware/oauth/providers.ts

@@ -0,0 +1,115 @@
+/**
+ * Provider presets for the OAuth middleware.
+ *
+ * Each factory returns a fresh {@link OAuthProvider} — callers should treat
+ * the returned object as immutable, but constructing a new one per `oauth()`
+ * invocation means mutations by one consumer never leak across another.
+ *
+ * Only GitHub and Google ship here. Twitter, Discord, Microsoft etc. are
+ * user-contribution territory — the {@link OAuthProvider} shape is stable
+ * and narrow on purpose.
+ *
+ * @module middleware/oauth/providers
+ */
+
+import type { OAuthProfile, OAuthProvider } from "./index";
+
+// ========== GitHub ==========
+
+/** Raw shape of `GET https://api.github.com/user`. Fields we consume + passthrough. */
+interface GitHubRawUser {
+  id: number | string;
+  email?: string | null;
+  name?: string | null;
+  avatar_url?: string | null;
+  [key: string]: unknown;
+}
+
+/**
+ * GitHub OAuth preset.
+ *
+ * Docs: https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps
+ *
+ * Notes:
+ *   - The token endpoint defaults to urlencoded responses; the middleware
+ *     sets `Accept: application/json` on the POST so we always parse JSON.
+ *   - `user:email` scope covers the case where the user's primary email is
+ *     private — without it, `raw.email` comes back as `null`.
+ *   - PKCE is supported and enabled by default.
+ */
+export function github(): OAuthProvider {
+  return {
+    name: "github",
+    authorizationEndpoint: "https://github.com/login/oauth/authorize",
+    tokenEndpoint: "https://github.com/login/oauth/access_token",
+    userinfoEndpoint: "https://api.github.com/user",
+    scopes: ["read:user", "user:email"],
+    pkce: true,
+    normalizeProfile: (raw: unknown): OAuthProfile => {
+      if (!raw || typeof raw !== "object") {
+        throw new Error("[Mandu OAuth/github] userinfo payload is not an object");
+      }
+      const r = raw as GitHubRawUser;
+      if (r.id === undefined || r.id === null) {
+        throw new Error("[Mandu OAuth/github] userinfo payload missing `id`");
+      }
+      return {
+        id: String(r.id),
+        email: typeof r.email === "string" ? r.email : undefined,
+        name: typeof r.name === "string" ? r.name : undefined,
+        avatarUrl: typeof r.avatar_url === "string" ? r.avatar_url : undefined,
+        raw,
+      };
+    },
+  };
+}
+
+// ========== Google ==========
+
+/** Raw shape of Google's OIDC `userinfo` endpoint. */
+interface GoogleRawUser {
+  sub: string;
+  email?: string;
+  name?: string;
+  picture?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Google OAuth preset (OpenID Connect flavor).
+ *
+ * Docs: https://developers.google.com/identity/protocols/oauth2/openid-connect
+ *
+ * Notes:
+ *   - Uses the static OIDC userinfo endpoint (no discovery at runtime).
+ *   - `sub` is the stable provider-scoped user id; `email` may still change
+ *     if the user renames their account, so consumers keying user records
+ *     should prefer `profile.id` over `profile.email`.
+ *   - PKCE is supported and enabled by default.
+ */
+export function google(): OAuthProvider {
+  return {
+    name: "google",
+    authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenEndpoint: "https://oauth2.googleapis.com/token",
+    userinfoEndpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+    scopes: ["openid", "email", "profile"],
+    pkce: true,
+    normalizeProfile: (raw: unknown): OAuthProfile => {
+      if (!raw || typeof raw !== "object") {
+        throw new Error("[Mandu OAuth/google] userinfo payload is not an object");
+      }
+      const r = raw as GoogleRawUser;
+      if (typeof r.sub !== "string" || r.sub.length === 0) {
+        throw new Error("[Mandu OAuth/google] userinfo payload missing `sub`");
+      }
+      return {
+        id: r.sub,
+        email: typeof r.email === "string" ? r.email : undefined,
+        name: typeof r.name === "string" ? r.name : undefined,
+        avatarUrl: typeof r.picture === "string" ? r.picture : undefined,
+        raw,
+      };
+    },
+  };
+}