@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/oauth.cjs

@@ -0,0 +1,1696 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/plugins/oauth/index.ts
+var oauth_exports = {};
+__export(oauth_exports, {
+  generateCodeChallenge: () => generateCodeChallenge,
+  generateCodeVerifier: () => generateCodeVerifier,
+  matchRedirectUri: () => matchRedirectUri,
+  oauth: () => oauth,
+  toOidcUserinfo: () => toOidcUserinfo,
+  verifyCodeChallenge: () => verifyCodeChallenge
+});
+module.exports = __toCommonJS(oauth_exports);
+
+// src/core/auth/refresh-token.ts
+async function generateRefreshToken() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const raw = base64UrlEncode(bytes);
+  const hash = await hashToken(raw);
+  return { raw, hash };
+}
+function generateTokenFamily() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function hashToken(raw) {
+  const data = new TextEncoder().encode(raw);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return hexEncode(new Uint8Array(hashBuffer));
+}
+function base64UrlEncode(bytes) {
+  const binString = Array.from(bytes, (b) => String.fromCodePoint(b)).join("");
+  return btoa(binString).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function hexEncode(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/core/auth/timing-safe.ts
+function timingSafeEqualHex(a, b) {
+  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;
+}
+
+// src/core/errors.ts
+var FortressError = class extends Error {
+  code;
+  statusCode;
+  retryAfter;
+  details;
+  /** RFC 6749 §5.2 / §4.1.2.1 machine code. Set by `Errors.oauth()`. */
+  oauthError;
+  /** Human-readable description for the OAuth `error_description` field. */
+  oauthDescription;
+  /** Optional URI for the OAuth `error_uri` field (§5.2). */
+  oauthErrorUri;
+  constructor(code, message, statusCode, options) {
+    super(message, { cause: options?.cause });
+    this.code = code;
+    this.statusCode = statusCode;
+    this.retryAfter = options?.retryAfter;
+    this.details = options?.details;
+    this.oauthError = options?.oauthError;
+    this.oauthDescription = options?.oauthDescription;
+    this.oauthErrorUri = options?.oauthErrorUri;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      ...this.details !== void 0 && { details: this.details }
+    };
+  }
+};
+var Errors = {
+  unauthorized: (message = "Unauthorized") => new FortressError("UNAUTHORIZED", message, 401),
+  tokenReuse: () => new FortressError("TOKEN_REUSE", "Token reuse detected", 401),
+  sessionIdleTimeout: () => new FortressError("SESSION_IDLE_TIMEOUT", "Session idle timeout exceeded", 401),
+  sessionAbsoluteTimeout: () => new FortressError("SESSION_ABSOLUTE_TIMEOUT", "Session absolute timeout exceeded", 401),
+  forbidden: (message = "Forbidden") => new FortressError("FORBIDDEN", message, 403),
+  badRequest: (message = "Bad request") => new FortressError("BAD_REQUEST", message, 400),
+  notFound: (message = "Not found") => new FortressError("NOT_FOUND", message, 404),
+  conflict: (message = "Conflict", options) => new FortressError("CONFLICT", message, 409, options),
+  unprocessable: (message = "Unprocessable entity", options) => new FortressError("UNPROCESSABLE_ENTITY", message, 422, options),
+  rateLimited: (retryAfter) => new FortressError("RATE_LIMITED", "Too many requests", 429, { retryAfter }),
+  database: (message = "Database error", cause) => new FortressError("DATABASE_ERROR", message, 500, { cause }),
+  serviceUnavailable: (message = "Service unavailable", options) => new FortressError("SERVICE_UNAVAILABLE", message, 503, options),
+  validationError: (issues) => new FortressError("VALIDATION_ERROR", "Validation failed", 422, { details: issues }),
+  /**
+   * RFC 6749 §5.2 / §4.1.2.1 OAuth error.
+   *
+   * The HTTP error mapper detects `oauthError` and emits the OAuth-spec
+   * JSON body `{ error, error_description, error_uri? }` instead of the
+   * default fortress `{ code, message }` shape, so strict OAuth clients
+   * (Moodle, openid-client, Spring Security, etc.) can switch behaviour
+   * on the machine-readable `error` field.
+   *
+   * Status is inferred from the OAuth code per the spec table:
+   * - `invalid_client` → 401
+   * - everything else → 400
+   */
+  oauth: (error, description, options) => {
+    const status = options?.status ?? (error === "invalid_client" ? 401 : 400);
+    const code = status === 401 ? "UNAUTHORIZED" : "BAD_REQUEST";
+    return new FortressError(code, description ?? error, status, {
+      oauthError: error,
+      oauthDescription: description,
+      oauthErrorUri: options?.errorUri,
+      cause: options?.cause
+    });
+  },
+  /**
+   * Reconstruct a {@link FortressError} from a JSON error body emitted by
+   * `errorToResponse`. Used by the in-process `fortress.call.*` client to
+   * convert non-2xx responses into typed throws that mirror what a direct
+   * service-method call would produce.
+   *
+   * Maps by HTTP status when the body doesn't carry a recognizable
+   * `{ code, message }` payload, so network errors and opaque upstream
+   * failures still become structured `FortressError`s.
+   */
+  fromHttpResponse: (status, body) => {
+    const payload = body && typeof body === "object" ? body : {};
+    const message = typeof payload.message === "string" ? payload.message : `HTTP ${status}`;
+    const code = typeof payload.code === "string" && isFortressErrorCode(payload.code) ? payload.code : statusToErrorCode(status);
+    return new FortressError(code, message, status, { details: payload.details });
+  }
+};
+function isFortressErrorCode(code) {
+  return code === "UNAUTHORIZED" || code === "TOKEN_REUSE" || code === "SESSION_IDLE_TIMEOUT" || code === "SESSION_ABSOLUTE_TIMEOUT" || code === "FORBIDDEN" || code === "BAD_REQUEST" || code === "NOT_FOUND" || code === "CONFLICT" || code === "UNPROCESSABLE_ENTITY" || code === "RATE_LIMITED" || code === "DATABASE_ERROR" || code === "VALIDATION_ERROR" || code === "SERVICE_UNAVAILABLE";
+}
+function statusToErrorCode(status) {
+  if (status === 401)
+    return "UNAUTHORIZED";
+  if (status === 403)
+    return "FORBIDDEN";
+  if (status === 404)
+    return "NOT_FOUND";
+  if (status === 409)
+    return "CONFLICT";
+  if (status === 422)
+    return "UNPROCESSABLE_ENTITY";
+  if (status === 429)
+    return "RATE_LIMITED";
+  if (status === 503)
+    return "SERVICE_UNAVAILABLE";
+  if (status >= 500)
+    return "DATABASE_ERROR";
+  return "BAD_REQUEST";
+}
+
+// src/plugins/oauth/id-token.ts
+var import_jose = require("jose");
+async function issueIdToken(params) {
+  const ttl = params.ttlSeconds ?? 3600;
+  const now = Math.floor(Date.now() / 1e3);
+  const scopes = params.scope ? params.scope.split(" ").filter(Boolean) : [];
+  const exposeEmail = scopes.includes("email");
+  const exposeProfile = scopes.includes("profile");
+  const claims = {};
+  if (params.authTimeSeconds !== void 0)
+    claims.auth_time = params.authTimeSeconds;
+  if (params.nonce)
+    claims.nonce = params.nonce;
+  if (exposeEmail) {
+    claims.email = params.user.email;
+    if (typeof params.user.emailVerified === "boolean")
+      claims.email_verified = params.user.emailVerified;
+  }
+  if (exposeProfile) {
+    claims.name = params.user.name;
+    claims.preferred_username = params.user.email;
+  }
+  if (params.user.updatedAt) {
+    claims.updated_at = Math.floor(new Date(params.user.updatedAt).getTime() / 1e3);
+  }
+  return new import_jose.SignJWT(claims).setProtectedHeader({ alg: "RS256", kid: params.signingKey.kid, typ: "JWT" }).setIssuer(params.issuerUrl).setSubject(String(params.user.id)).setAudience(params.clientId).setIssuedAt(now).setExpirationTime(now + ttl).sign(params.signingKey.privateKey);
+}
+
+// src/plugins/oauth/jwks.ts
+var import_jose2 = require("jose");
+async function getActiveSigningKey(db) {
+  const existing = await db.findOne({
+    model: "oauth_signing_key",
+    where: [{ field: "rotatedAt", operator: "isNull", value: null }]
+  });
+  if (existing)
+    return hydrate(existing);
+  const { publicKey, privateKey } = await (0, import_jose2.generateKeyPair)("RS256", { extractable: true });
+  const publicJwk = await (0, import_jose2.exportJWK)(publicKey);
+  const privateJwk = await (0, import_jose2.exportJWK)(privateKey);
+  const kid = await (0, import_jose2.calculateJwkThumbprint)(publicJwk, "sha256");
+  publicJwk.kid = kid;
+  publicJwk.alg = "RS256";
+  publicJwk.use = "sig";
+  privateJwk.kid = kid;
+  privateJwk.alg = "RS256";
+  await db.create({
+    model: "oauth_signing_key",
+    data: {
+      kid,
+      alg: "RS256",
+      publicJwk: JSON.stringify(publicJwk),
+      privateJwk: JSON.stringify(privateJwk),
+      rotatedAt: null
+    }
+  });
+  return {
+    kid,
+    alg: "RS256",
+    privateKey,
+    publicJwk
+  };
+}
+async function listJwks(db, graceSeconds = 3600) {
+  const all = await db.findMany({
+    model: "oauth_signing_key",
+    where: []
+  });
+  const cutoff = Date.now() - Math.max(0, graceSeconds) * 1e3;
+  return {
+    keys: all.filter((row) => row.rotatedAt === null || new Date(row.rotatedAt).getTime() > cutoff).sort((a, b) => {
+      if (a.rotatedAt === null && b.rotatedAt !== null)
+        return -1;
+      if (a.rotatedAt !== null && b.rotatedAt === null)
+        return 1;
+      return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+    }).map((row) => JSON.parse(row.publicJwk))
+  };
+}
+async function rotateSigningKey(db, graceSeconds = 3600) {
+  return db.transaction(async (tx) => {
+    if (tx.dialect === "pg" && tx.rawQuery)
+      await tx.rawQuery("SELECT pg_advisory_xact_lock(hashtext(?))", ["fortress-oauth-signing-key"]);
+    const now = /* @__PURE__ */ new Date();
+    const active = await tx.findOne({
+      model: "oauth_signing_key",
+      where: [{ field: "rotatedAt", operator: "isNull", value: null }]
+    });
+    if (active) {
+      await tx.update({
+        model: "oauth_signing_key",
+        where: [{ field: "id", operator: "=", value: active.id }],
+        data: { rotatedAt: now }
+      });
+    }
+    const cutoff = new Date(now.getTime() - Math.max(0, graceSeconds) * 1e3);
+    const expired = await tx.findMany({
+      model: "oauth_signing_key",
+      where: [{ field: "rotatedAt", operator: "lt", value: cutoff }]
+    });
+    for (const key of expired) {
+      await tx.delete({
+        model: "oauth_signing_key",
+        where: [{ field: "id", operator: "=", value: key.id }]
+      });
+    }
+    return getActiveSigningKey(tx);
+  });
+}
+async function hydrate(record) {
+  const publicJwk = JSON.parse(record.publicJwk);
+  const privateJwk = JSON.parse(record.privateJwk);
+  const privateKey = await (0, import_jose2.importJWK)(privateJwk, "RS256");
+  return {
+    kid: record.kid,
+    alg: "RS256",
+    privateKey,
+    publicJwk
+  };
+}
+
+// src/plugins/oauth/pkce.ts
+var CODE_VERIFIER_PATTERN = /^[\w.~-]{43,128}$/;
+function generateCodeVerifier() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function generateCodeChallenge(verifier) {
+  const data = new TextEncoder().encode(verifier);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return btoa(String.fromCharCode(...new Uint8Array(hash))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+async function verifyCodeChallenge(verifier, challenge, method) {
+  if (method !== "S256")
+    return false;
+  if (!CODE_VERIFIER_PATTERN.test(verifier))
+    return false;
+  const computed = await generateCodeChallenge(verifier);
+  return timingSafeEqualHex(computed, challenge);
+}
+
+// src/plugins/oauth/index.ts
+function oauth(config = {}) {
+  const authCodeExpiry = config.authCodeExpirySeconds ?? 600;
+  const pendingFlowExpiry = config.pendingFlowExpirySeconds ?? 600;
+  const accessTokenExpiry = config.accessTokenExpirySeconds ?? 3600;
+  const refreshTokenExpiry = config.refreshTokenExpirySeconds ?? 30 * 24 * 3600;
+  const refreshEnabled = refreshTokenExpiry > 0;
+  const idTokenExpiry = config.idTokenExpirySeconds ?? 3600;
+  const signingKeyGraceSeconds = config.signingKeyGraceSeconds ?? idTokenExpiry;
+  const scopePermissionMap = config.scopePermissionMap;
+  const issuerUrl = config.issuerUrl ?? "https://localhost";
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production" && !issuerUrl.startsWith("https://")) {
+    throw new Error(
+      `[fortress/oauth] issuerUrl must use https:// in production (got: ${issuerUrl})`
+    );
+  }
+  return {
+    name: "oauth",
+    models: [
+      {
+        name: "oauth_client",
+        fields: {
+          id: { type: "number", required: true },
+          clientId: { type: "string", required: true, unique: true },
+          // For public clients (`tokenEndpointAuthMethod === 'none'`) the
+          // hash is set to the empty string — the column is required by the
+          // adapter for backwards compat, but never compared against an
+          // inbound secret.
+          clientSecretHash: { type: "string", required: true },
+          name: { type: "string", required: true },
+          redirectUris: { type: "string", required: true },
+          grantTypes: { type: "string", required: true },
+          // RFC 6749 §3.3 / RFC 9700 §2.2.1 per-client scope allow-list.
+          // Optional for backwards compatibility with legacy v0 clients
+          // created before this column existed.
+          allowedScopes: { type: "string" },
+          // RFC 6749 §2.1 client type. Optional — absent on legacy clients,
+          // which are treated as confidential (`client_secret_basic`).
+          tokenEndpointAuthMethod: { type: "string" },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        name: "oauth_authorization_code",
+        fields: {
+          id: { type: "number", required: true },
+          code: { type: "string", required: true, unique: true },
+          clientId: { type: "string", required: true },
+          userId: { type: "number", required: true },
+          redirectUri: { type: "string", required: true },
+          scope: { type: "string" },
+          codeChallenge: { type: "string" },
+          codeChallengeMethod: { type: "string" },
+          // OIDC Core §3.1.2.1 nonce — echoed into the id_token verbatim.
+          nonce: { type: "string" },
+          // Unix seconds; OIDC `auth_time` claim source.
+          authTime: { type: "number" },
+          expiresAt: { type: "date", required: true },
+          usedAt: { type: "date" },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        name: "oauth_access_token",
+        fields: {
+          id: { type: "number", required: true },
+          token: { type: "string", required: true, unique: true },
+          clientId: { type: "string", required: true },
+          userId: { type: "number" },
+          scope: { type: "string" },
+          expiresAt: { type: "date", required: true },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        name: "oauth_refresh_token",
+        fields: {
+          id: { type: "number", required: true },
+          token: { type: "string", required: true, unique: true },
+          familyId: { type: "string", required: true },
+          clientId: { type: "string", required: true },
+          userId: { type: "number", required: true },
+          scope: { type: "string" },
+          issuedAt: { type: "date", required: true },
+          expiresAt: { type: "date", required: true },
+          usedAt: { type: "date" },
+          parentId: { type: "number" },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        name: "oauth_pending_flow",
+        fields: {
+          id: { type: "number", required: true },
+          flowId: { type: "string", required: true, unique: true },
+          clientId: { type: "string", required: true },
+          redirectUri: { type: "string", required: true },
+          scope: { type: "string" },
+          state: { type: "string", required: true },
+          codeChallenge: { type: "string" },
+          codeChallengeMethod: { type: "string" },
+          nonce: { type: "string" },
+          // H6 fix: subject the flow is bound to. Nullable for back-compat
+          // and to model the trust-on-first-use claim.
+          userId: { type: "number" },
+          // Single-use approval/denial claim. Older rows may have null.
+          usedAt: { type: "date" },
+          expiresAt: { type: "date", required: true },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        // OIDC Core §2 / RFC 7517 signing key persistence. RS256 only for
+        // now; the row stores both public and private JWKs as JSON. Active
+        // key has rotatedAt == null.
+        name: "oauth_signing_key",
+        fields: {
+          id: { type: "number", required: true },
+          kid: { type: "string", required: true, unique: true },
+          alg: { type: "string", required: true },
+          publicJwk: { type: "string", required: true },
+          privateJwk: { type: "string", required: true },
+          createdAt: { type: "date", required: true },
+          rotatedAt: { type: "date" }
+        }
+      }
+    ],
+    methods: (ctx) => ({
+      /**
+       * Register a new OAuth client.
+       * Returns the clientId and raw clientSecret (shown once, stored as hash).
+       */
+      async createClient(data) {
+        const isPublic = data.tokenEndpointAuthMethod === "none";
+        const { raw: clientSecret, hash: clientSecretHash } = isPublic ? { raw: "", hash: "" } : await generateRefreshToken();
+        const { raw: clientIdRaw } = await generateRefreshToken();
+        const clientId = clientIdRaw.slice(0, 24);
+        await ctx.db.create({
+          model: "oauth_client",
+          data: {
+            clientId,
+            clientSecretHash,
+            name: data.name,
+            redirectUris: JSON.stringify(data.redirectUris),
+            grantTypes: JSON.stringify(data.grantTypes),
+            allowedScopes: data.allowedScopes ? JSON.stringify(data.allowedScopes) : null,
+            tokenEndpointAuthMethod: data.tokenEndpointAuthMethod ?? "client_secret_basic"
+          }
+        });
+        return {
+          clientId,
+          // Public clients have no secret — returning `null` makes the
+          // contract explicit at compile time.
+          clientSecret: isPublic ? null : clientSecret
+        };
+      },
+      /**
+       * Generate an authorization code for a user+client.
+       * Used after the user authenticates and authorizes the client.
+       */
+      async createAuthorizationCode(params) {
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: params.clientId }]
+        });
+        if (!client)
+          throw Errors.oauth("invalid_request", "Invalid client_id");
+        const uris = JSON.parse(client.redirectUris);
+        if (!uris.some((r) => matchRedirectUri(r, params.redirectUri)))
+          throw Errors.oauth("invalid_request", "Invalid redirect_uri");
+        const isPublic = client.tokenEndpointAuthMethod === "none";
+        if (isPublic && (!params.codeChallenge || params.codeChallengeMethod !== "S256"))
+          throw Errors.oauth("invalid_request", "PKCE (S256) is required for public clients");
+        const { raw: code, hash: codeHash } = await generateRefreshToken();
+        const expiresAt = new Date(Date.now() + authCodeExpiry * 1e3);
+        await ctx.db.create({
+          model: "oauth_authorization_code",
+          data: {
+            code: codeHash,
+            clientId: params.clientId,
+            userId: params.userId,
+            redirectUri: params.redirectUri,
+            scope: params.scope ?? null,
+            codeChallenge: params.codeChallenge ?? null,
+            codeChallengeMethod: params.codeChallengeMethod ?? null,
+            nonce: params.nonce ?? null,
+            authTime: params.authTime ?? null,
+            expiresAt,
+            usedAt: null
+          }
+        });
+        return { code };
+      },
+      /**
+       * Exchange an authorization code for an access token.
+       */
+      async exchangeCode(params) {
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: params.clientId }]
+        });
+        if (!client)
+          throw Errors.oauth("invalid_client", "Invalid client credentials");
+        const isPublic = client.tokenEndpointAuthMethod === "none";
+        if (!isPublic) {
+          if (!params.clientSecret)
+            throw Errors.oauth("invalid_client", "Client secret required");
+          const secretValid = timingSafeEqualHex(
+            await hashToken(params.clientSecret),
+            client.clientSecretHash
+          );
+          if (!secretValid)
+            throw Errors.oauth("invalid_client", "Invalid client credentials");
+        } else if (params.clientSecret) {
+          throw Errors.oauth("invalid_client", "Public clients must not present a client_secret");
+        }
+        const grantTypes = JSON.parse(client.grantTypes);
+        if (!grantTypes.includes("authorization_code"))
+          throw Errors.oauth("unauthorized_client", "Client does not support authorization_code grant");
+        const codeHash = await hashToken(params.code);
+        return ctx.db.transaction(async (tx) => {
+          const authCode = await tx.findOne({
+            model: "oauth_authorization_code",
+            where: [{ field: "code", operator: "=", value: codeHash }]
+          });
+          if (!authCode)
+            throw Errors.oauth("invalid_grant", "Invalid authorization code");
+          if (authCode.expiresAt < /* @__PURE__ */ new Date())
+            throw Errors.oauth("invalid_grant", "Authorization code expired");
+          if (authCode.clientId !== params.clientId)
+            throw Errors.oauth("invalid_grant", "Client mismatch");
+          if (authCode.redirectUri !== params.redirectUri)
+            throw Errors.oauth("invalid_grant", "Redirect URI mismatch");
+          if (isPublic && !authCode.codeChallenge)
+            throw Errors.oauth("invalid_grant", "PKCE required for public clients");
+          if (authCode.codeChallenge && authCode.codeChallengeMethod) {
+            if (!params.codeVerifier)
+              throw Errors.oauth("invalid_grant", "code_verifier required");
+            const valid = await verifyCodeChallenge(
+              params.codeVerifier,
+              authCode.codeChallenge,
+              authCode.codeChallengeMethod
+            );
+            if (!valid)
+              throw Errors.oauth("invalid_grant", "Invalid code_verifier");
+          }
+          const claimed = await tx.update({
+            model: "oauth_authorization_code",
+            where: [
+              { field: "id", operator: "=", value: authCode.id },
+              { field: "usedAt", operator: "isNull", value: null }
+            ],
+            data: { usedAt: /* @__PURE__ */ new Date() }
+          });
+          if (!claimed)
+            throw Errors.oauth("invalid_grant", "Authorization code already used");
+          const { raw: tokenRaw, hash: tokenHash } = await generateRefreshToken();
+          const expiresAt = new Date(Date.now() + accessTokenExpiry * 1e3);
+          await tx.create({
+            model: "oauth_access_token",
+            data: {
+              token: tokenHash,
+              clientId: params.clientId,
+              userId: authCode.userId,
+              scope: authCode.scope,
+              expiresAt
+            }
+          });
+          let idToken;
+          const scopes = (authCode.scope ?? "").split(" ").filter(Boolean);
+          if (scopes.includes("openid")) {
+            const user = await tx.findOne({
+              model: "user",
+              where: [{ field: "id", operator: "=", value: authCode.userId }]
+            });
+            if (user) {
+              const signingKey = await getActiveSigningKey(tx);
+              idToken = await issueIdToken({
+                user,
+                clientId: params.clientId,
+                issuerUrl,
+                ttlSeconds: idTokenExpiry,
+                nonce: authCode.nonce ?? void 0,
+                authTimeSeconds: authCode.authTime ?? Math.floor(Date.now() / 1e3),
+                scope: authCode.scope,
+                signingKey
+              });
+            }
+          }
+          let refreshTokenRaw;
+          if (refreshEnabled) {
+            const { raw, hash } = await generateRefreshToken();
+            refreshTokenRaw = raw;
+            await tx.create({
+              model: "oauth_refresh_token",
+              data: {
+                token: hash,
+                familyId: generateTokenFamily(),
+                clientId: params.clientId,
+                userId: authCode.userId,
+                scope: authCode.scope ?? null,
+                issuedAt: /* @__PURE__ */ new Date(),
+                expiresAt: new Date(Date.now() + refreshTokenExpiry * 1e3),
+                usedAt: null,
+                parentId: null
+              }
+            });
+          }
+          return {
+            accessToken: tokenRaw,
+            tokenType: "Bearer",
+            expiresIn: accessTokenExpiry,
+            scope: authCode.scope ?? void 0,
+            ...refreshTokenRaw ? { refreshToken: refreshTokenRaw } : {},
+            ...idToken ? { idToken } : {}
+          };
+        });
+      },
+      /**
+       * RFC 6749 §6 refresh-token grant with RFC 9700 §2.2.2 rotation.
+       *
+       * Flow:
+       * 1. Look up the inbound refresh token by hash.
+       * 2. If it's already been used (`usedAt != null`), this is a replay
+       *    attack — delete every refresh token in the same family and
+       *    throw `invalid_grant`. The legitimate client's most recent
+       *    refresh dies with the family, so the user is forced to
+       *    re-authenticate, but the attacker's stolen token is now
+       *    useless.
+       * 3. Otherwise mark the old token used, mint a new access token +
+       *    a new refresh token in the same family, link the new refresh
+       *    via `parentId`, and return the pair.
+       */
+      async refreshTokenGrant(params) {
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: params.clientId }]
+        });
+        if (!client)
+          throw Errors.oauth("invalid_client", "Invalid client credentials");
+        const isPublic = client.tokenEndpointAuthMethod === "none";
+        if (!isPublic) {
+          if (!params.clientSecret)
+            throw Errors.oauth("invalid_client", "Client secret required");
+          const secretValid = timingSafeEqualHex(
+            await hashToken(params.clientSecret),
+            client.clientSecretHash
+          );
+          if (!secretValid)
+            throw Errors.oauth("invalid_client", "Invalid client credentials");
+        } else if (params.clientSecret) {
+          throw Errors.oauth("invalid_client", "Public clients must not present a client_secret");
+        }
+        const refreshGrantTypes = JSON.parse(client.grantTypes);
+        if (!refreshGrantTypes.includes("refresh_token"))
+          throw Errors.oauth("unauthorized_client", "Client does not support refresh_token grant");
+        const tokenHash = await hashToken(params.refreshToken);
+        const grant = await ctx.db.transaction(async (tx) => {
+          const record = await tx.findOne({
+            model: "oauth_refresh_token",
+            where: [{ field: "token", operator: "=", value: tokenHash }]
+          });
+          if (!record)
+            throw Errors.oauth("invalid_grant", "Invalid refresh token");
+          if (record.clientId !== params.clientId)
+            throw Errors.oauth("invalid_grant", "Refresh token client mismatch");
+          if (record.expiresAt < /* @__PURE__ */ new Date())
+            throw Errors.oauth("invalid_grant", "Refresh token expired");
+          if (record.usedAt) {
+            await tx.delete({
+              model: "oauth_refresh_token",
+              where: [{ field: "familyId", operator: "=", value: record.familyId }]
+            });
+            return { replayDetected: true };
+          }
+          let scope = record.scope;
+          if (params.scope) {
+            const requested = params.scope.split(" ").filter(Boolean);
+            const original = (record.scope ?? "").split(" ").filter(Boolean);
+            const originalSet = new Set(original);
+            const widened = requested.find((s) => !originalSet.has(s));
+            if (widened) {
+              throw Errors.oauth("invalid_scope", `Refreshed scope cannot widen: ${widened}`);
+            }
+            scope = requested.join(" ");
+          }
+          const claimed = await tx.update({
+            model: "oauth_refresh_token",
+            where: [
+              { field: "id", operator: "=", value: record.id },
+              { field: "usedAt", operator: "isNull", value: null }
+            ],
+            data: { usedAt: /* @__PURE__ */ new Date() }
+          });
+          if (!claimed) {
+            await tx.delete({
+              model: "oauth_refresh_token",
+              where: [{ field: "familyId", operator: "=", value: record.familyId }]
+            });
+            return { replayDetected: true };
+          }
+          const { raw: accessRaw, hash: accessHash } = await generateRefreshToken();
+          await tx.create({
+            model: "oauth_access_token",
+            data: {
+              token: accessHash,
+              clientId: params.clientId,
+              userId: record.userId,
+              scope,
+              expiresAt: new Date(Date.now() + accessTokenExpiry * 1e3)
+            }
+          });
+          let idToken;
+          if ((scope ?? "").split(" ").filter(Boolean).includes("openid")) {
+            const user = await tx.findOne({
+              model: "user",
+              where: [{ field: "id", operator: "=", value: record.userId }]
+            });
+            if (user) {
+              const signingKey = await getActiveSigningKey(tx);
+              idToken = await issueIdToken({
+                user,
+                clientId: params.clientId,
+                issuerUrl,
+                ttlSeconds: idTokenExpiry,
+                // The original authentication time is not stored on the
+                // refresh family. Omit auth_time rather than fabricating a
+                // fresh authentication event at token rotation.
+                scope,
+                signingKey
+              });
+            }
+          }
+          const { raw: refreshRaw, hash: refreshHash } = await generateRefreshToken();
+          await tx.create({
+            model: "oauth_refresh_token",
+            data: {
+              token: refreshHash,
+              familyId: record.familyId,
+              clientId: params.clientId,
+              userId: record.userId,
+              scope,
+              issuedAt: /* @__PURE__ */ new Date(),
+              expiresAt: new Date(Date.now() + refreshTokenExpiry * 1e3),
+              usedAt: null,
+              parentId: record.id
+            }
+          });
+          return {
+            accessToken: accessRaw,
+            tokenType: "Bearer",
+            expiresIn: accessTokenExpiry,
+            refreshToken: refreshRaw,
+            ...scope ? { scope } : {},
+            ...idToken ? { idToken } : {}
+          };
+        });
+        if ("replayDetected" in grant)
+          throw Errors.oauth("invalid_grant", "Refresh token reuse detected; family revoked");
+        return grant;
+      },
+      /**
+       * Client credentials grant — issue token for a service client (no user).
+       */
+      async clientCredentialsGrant(params) {
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: params.clientId }]
+        });
+        if (!client)
+          throw Errors.oauth("invalid_client", "Invalid client credentials");
+        if (client.tokenEndpointAuthMethod === "none")
+          throw Errors.oauth("unauthorized_client", "Public clients cannot use client_credentials");
+        const grantTypes = JSON.parse(client.grantTypes);
+        if (!grantTypes.includes("client_credentials"))
+          throw Errors.oauth("unauthorized_client", "Client does not support client_credentials grant");
+        const secretValid = timingSafeEqualHex(
+          await hashToken(params.clientSecret),
+          client.clientSecretHash
+        );
+        if (!secretValid)
+          throw Errors.oauth("invalid_client", "Invalid client credentials");
+        const effectiveScope = intersectScope(params.scope ?? null, client.allowedScopes);
+        if (params.scope && effectiveScope === "") {
+          throw Errors.oauth("invalid_scope", "No requested scope is allowed for this client");
+        }
+        const { raw: tokenRaw, hash: tokenHash } = await generateRefreshToken();
+        const expiresAt = new Date(Date.now() + accessTokenExpiry * 1e3);
+        await ctx.db.create({
+          model: "oauth_access_token",
+          data: {
+            token: tokenHash,
+            clientId: params.clientId,
+            userId: null,
+            scope: effectiveScope || null,
+            expiresAt
+          }
+        });
+        return {
+          accessToken: tokenRaw,
+          tokenType: "Bearer",
+          expiresIn: accessTokenExpiry
+        };
+      },
+      /**
+       * Revoke an access token OR refresh token (RFC 7009).
+       *
+       * Per §2.1: revoking a refresh token also revokes the related access
+       * tokens. When a refresh token is revoked here, the entire token
+       * family is dropped — every rotated descendant becomes unusable.
+       */
+      async revokeToken(token) {
+        const tokenHash = await hashToken(token);
+        await ctx.db.delete({
+          model: "oauth_access_token",
+          where: [{ field: "token", operator: "=", value: tokenHash }]
+        });
+        if (refreshEnabled) {
+          const refreshRecord = await ctx.db.findOne({
+            model: "oauth_refresh_token",
+            where: [{ field: "token", operator: "=", value: tokenHash }]
+          });
+          if (refreshRecord) {
+            await ctx.db.delete({
+              model: "oauth_refresh_token",
+              where: [{ field: "familyId", operator: "=", value: refreshRecord.familyId }]
+            });
+          }
+        }
+      },
+      /**
+       * Validate an access token and return associated user/client info.
+       */
+      async introspectToken(token) {
+        const tokenHash = await hashToken(token);
+        const record = await ctx.db.findOne({
+          model: "oauth_access_token",
+          where: [{ field: "token", operator: "=", value: tokenHash }]
+        });
+        if (!record || record.expiresAt < /* @__PURE__ */ new Date()) {
+          return { active: false };
+        }
+        return {
+          active: true,
+          clientId: record.clientId,
+          userId: record.userId ?? void 0,
+          scope: record.scope ?? void 0
+        };
+      },
+      /**
+       * Create a pending OAuth flow for unauthenticated users (identity broker pattern).
+       */
+      async createPendingFlow(params) {
+        const expiresAt = new Date(Date.now() + pendingFlowExpiry * 1e3);
+        const { raw: flowId } = await generateRefreshToken();
+        const flow = await ctx.db.create({
+          model: "oauth_pending_flow",
+          data: {
+            flowId,
+            clientId: params.clientId,
+            redirectUri: params.redirectUri,
+            scope: params.scope ?? null,
+            state: params.state,
+            codeChallenge: params.codeChallenge ?? null,
+            codeChallengeMethod: params.codeChallengeMethod ?? null,
+            userId: params.userId ?? null,
+            usedAt: null,
+            expiresAt
+          }
+        });
+        return { flowId: flow.flowId };
+      },
+      /**
+       * Read a pending OAuth flow without consuming it.
+       *
+       * Used by the consent UI to fetch flow metadata (client, scopes, redirect URI)
+       * before the user approves or denies. Safe to call multiple times.
+       *
+       * @throws {FortressError} `not_found` if the flow doesn't exist.
+       * @throws {FortressError} `bad_request` if the flow has expired.
+       */
+      async getPendingFlow(flowId, context) {
+        const flow = await ctx.db.findOne({
+          model: "oauth_pending_flow",
+          where: pendingFlowLookupWhere(flowId)
+        });
+        if (!flow)
+          throw Errors.notFound("Pending flow not found");
+        if (flow.usedAt)
+          throw Errors.notFound("Pending flow not found");
+        if (flow.expiresAt < /* @__PURE__ */ new Date())
+          throw Errors.badRequest("Pending flow expired");
+        if (context?.userId !== void 0 && flow.userId !== null && flow.userId !== context.userId) {
+          throw Errors.notFound("Pending flow not found");
+        }
+        return flow;
+      },
+      /**
+       * Resume a pending OAuth flow after user authenticates (single-use consume).
+       *
+       * Returns the stored flow params and deletes the row so the same flow can't
+       * be replayed. Use {@link OAuthMethods.getPendingFlow} for non-destructive reads.
+       */
+      async resumePendingFlow(flowId, context) {
+        const flow = await ctx.db.findOne({
+          model: "oauth_pending_flow",
+          where: pendingFlowLookupWhere(flowId)
+        });
+        if (!flow)
+          throw Errors.notFound("Pending flow not found");
+        if (flow.usedAt)
+          throw Errors.notFound("Pending flow not found");
+        if (flow.expiresAt < /* @__PURE__ */ new Date())
+          throw Errors.badRequest("Pending flow expired");
+        if (context?.userId !== void 0 && flow.userId !== null && flow.userId !== context.userId) {
+          throw Errors.notFound("Pending flow not found");
+        }
+        await ctx.db.delete({
+          model: "oauth_pending_flow",
+          where: [{ field: "id", operator: "=", value: flow.id }]
+        });
+        return flow;
+      },
+      /**
+       * Get userinfo for an access token (OpenID Connect userinfo endpoint).
+       */
+      /**
+       * Handle the authorize endpoint. Validates the OAuth query, creates a
+       * pending flow row, and decides whether the browser should be sent to
+       * the host app's login page or consent page next.
+       *
+       * The dispatcher turns `redirectUrl` into a 302 response. Errors are
+       * thrown as {@link FortressError}s so they surface as a 4xx JSON body
+       * (the OAuth client is expected to handle that).
+       */
+      async handleAuthorizeRequest(query, context) {
+        const nonce = query.nonce;
+        if (!config.loginUrl || !config.consentUrl) {
+          throw Errors.badRequest(
+            "OAuth plugin is missing loginUrl/consentUrl configuration"
+          );
+        }
+        const clientId = query.client_id;
+        const redirectUri = query.redirect_uri;
+        const responseType = query.response_type;
+        const state = query.state;
+        const scope = query.scope;
+        const codeChallenge = query.code_challenge;
+        const codeChallengeMethod = query.code_challenge_method;
+        if (!clientId)
+          throw Errors.oauth("invalid_request", "client_id is required");
+        if (!redirectUri)
+          throw Errors.oauth("invalid_request", "redirect_uri is required");
+        if (responseType !== "code")
+          throw Errors.oauth("unsupported_response_type", 'response_type must be "code"');
+        if (!state)
+          throw Errors.oauth("invalid_request", "state is required");
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: clientId }]
+        });
+        if (!client)
+          throw Errors.oauth("invalid_request", "Unknown client_id");
+        const allowedRedirects = JSON.parse(client.redirectUris);
+        if (!allowedRedirects.some((r) => matchRedirectUri(r, redirectUri)))
+          throw Errors.oauth("invalid_request", "Invalid redirect_uri");
+        if (!codeChallenge && !config.allowNonPkceConfidentialClients) {
+          throw Errors.oauth("invalid_request", "code_challenge is required (PKCE)");
+        }
+        if (codeChallenge && codeChallengeMethod && codeChallengeMethod !== "S256") {
+          throw Errors.oauth("invalid_request", "Only S256 code_challenge_method is supported");
+        }
+        if (codeChallenge && !codeChallengeMethod) {
+          throw Errors.oauth(
+            "invalid_request",
+            "code_challenge_method is required when code_challenge is set; only S256 is supported"
+          );
+        }
+        const effectiveScope = intersectScope(scope ?? null, client.allowedScopes);
+        if (scope && effectiveScope === "") {
+          throw Errors.oauth("invalid_scope", "No requested scope is allowed for this client");
+        }
+        const expiresAt = new Date(Date.now() + pendingFlowExpiry * 1e3);
+        const { raw: flowId } = await generateRefreshToken();
+        const flow = await ctx.db.create({
+          model: "oauth_pending_flow",
+          data: {
+            flowId,
+            clientId,
+            redirectUri,
+            scope: effectiveScope || null,
+            state,
+            codeChallenge: codeChallenge ?? null,
+            codeChallengeMethod: codeChallengeMethod ?? null,
+            nonce: nonce ?? null,
+            // H6 fix — bind the flow to the authenticated user up front when
+            // the authorize endpoint already knows them. The login redirect
+            // path leaves userId null and lets the first authenticated
+            // GetFlow / Approve claim it.
+            userId: context.userId ?? null,
+            usedAt: null,
+            expiresAt
+          }
+        });
+        const target = context.userId ? config.consentUrl : config.loginUrl;
+        const url = new URL(target);
+        url.searchParams.set("flow", flow.flowId);
+        return { redirectUrl: url.toString(), flowId: flow.flowId };
+      },
+      /**
+       * Read a pending flow as the consent UI's data source. Strips fields
+       * that should never leave the server (PKCE challenge / method).
+       */
+      async handleGetFlow(flowId, context) {
+        const flow = await this.getPendingFlow(flowId, context);
+        if (flow.userId === null) {
+          await ctx.db.update({
+            model: "oauth_pending_flow",
+            where: [
+              { field: "id", operator: "=", value: flow.id },
+              { field: "userId", operator: "isNull", value: null }
+            ],
+            data: { userId: context.userId }
+          });
+        }
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: flow.clientId }]
+        });
+        if (!client)
+          throw Errors.notFound("OAuth client not found");
+        return {
+          flowId: flow.flowId,
+          client: { clientId: client.clientId, name: client.name },
+          redirectUri: flow.redirectUri,
+          scopes: flow.scope ? flow.scope.split(" ").filter(Boolean) : [],
+          state: flow.state
+        };
+      },
+      /**
+       * Approve a pending flow on behalf of the authenticated user. Creates
+       * the authorization code, consumes the pending flow, and returns the
+       * client's redirect URI with `?code=...&state=...` appended.
+       */
+      async handleApproveFlow(flowId, context) {
+        const { flow, code } = await ctx.db.transaction(async (tx) => {
+          const flow2 = await tx.findOne({
+            model: "oauth_pending_flow",
+            where: pendingFlowLookupWhere(flowId)
+          });
+          if (!flow2)
+            throw Errors.notFound("Pending flow not found");
+          if (flow2.usedAt)
+            throw Errors.notFound("Pending flow not found");
+          if (flow2.expiresAt < /* @__PURE__ */ new Date())
+            throw Errors.badRequest("Pending flow expired");
+          if (flow2.userId !== null && flow2.userId !== context.userId)
+            throw Errors.notFound("Pending flow not found");
+          const claimed = await tx.update({
+            model: "oauth_pending_flow",
+            where: [
+              { field: "id", operator: "=", value: flow2.id },
+              { field: "usedAt", operator: "isNull", value: null }
+            ],
+            data: {
+              usedAt: /* @__PURE__ */ new Date(),
+              userId: flow2.userId ?? context.userId
+            }
+          });
+          if (!claimed)
+            throw Errors.notFound("Pending flow not found");
+          const client = await tx.findOne({
+            model: "oauth_client",
+            where: [{ field: "clientId", operator: "=", value: flow2.clientId }]
+          });
+          if (!client)
+            throw Errors.oauth("invalid_request", "Invalid client_id");
+          const uris = JSON.parse(client.redirectUris);
+          if (!uris.some((r) => matchRedirectUri(r, flow2.redirectUri)))
+            throw Errors.oauth("invalid_request", "Invalid redirect_uri");
+          const isPublic = client.tokenEndpointAuthMethod === "none";
+          if (isPublic && (!flow2.codeChallenge || flow2.codeChallengeMethod !== "S256"))
+            throw Errors.oauth("invalid_request", "PKCE (S256) is required for public clients");
+          const { raw: code2, hash: codeHash } = await generateRefreshToken();
+          await tx.create({
+            model: "oauth_authorization_code",
+            data: {
+              code: codeHash,
+              clientId: flow2.clientId,
+              userId: context.userId,
+              redirectUri: flow2.redirectUri,
+              scope: flow2.scope ?? null,
+              codeChallenge: flow2.codeChallenge ?? null,
+              codeChallengeMethod: flow2.codeChallengeMethod ?? null,
+              nonce: flow2.nonce ?? null,
+              authTime: context.authTimeSeconds ?? Math.floor(Date.now() / 1e3),
+              expiresAt: new Date(Date.now() + authCodeExpiry * 1e3),
+              usedAt: null
+            }
+          });
+          await tx.delete({
+            model: "oauth_pending_flow",
+            where: [{ field: "id", operator: "=", value: flow2.id }]
+          });
+          return { flow: flow2, code: code2 };
+        });
+        const url = new URL(flow.redirectUri);
+        url.searchParams.set("code", code);
+        url.searchParams.set("state", flow.state);
+        url.searchParams.set("iss", issuerUrl);
+        return { redirectUrl: url.toString() };
+      },
+      /**
+       * Deny a pending flow. Consumes the flow row and returns the OAuth
+       * client's redirect URI with `?error=access_denied&state=...&iss=...`.
+       *
+       * Per RFC 9207 §2, the issuer parameter is included on error responses
+       * too — the RP needs to validate the AS identity before trusting any
+       * field, including `error`.
+       */
+      async handleDenyFlow(flowId, context) {
+        const flow = await this.resumePendingFlow(flowId, context);
+        const url = new URL(flow.redirectUri);
+        url.searchParams.set("error", "access_denied");
+        url.searchParams.set("state", flow.state);
+        url.searchParams.set("iss", issuerUrl);
+        return { redirectUrl: url.toString() };
+      },
+      async getUserInfo(token) {
+        const result = await this._lookupBearer(token);
+        return result?.user ?? null;
+      },
+      /**
+       * Internal: resolve a bearer token to its access-token row + user.
+       * Shared by `getUserInfo` (returns the raw user) and
+       * `handleUserInfoRequest` (maps to OIDC claims).
+       */
+      async _lookupBearer(token) {
+        const tokenHash = await hashToken(token);
+        const record = await ctx.db.findOne({
+          model: "oauth_access_token",
+          where: [{ field: "token", operator: "=", value: tokenHash }]
+        });
+        if (!record || !record.userId || record.expiresAt < /* @__PURE__ */ new Date())
+          return null;
+        const user = await ctx.db.findOne({
+          model: "user",
+          where: [{ field: "id", operator: "=", value: record.userId }]
+        });
+        if (!user)
+          return null;
+        return { user, scope: record.scope };
+      },
+      // --- HTTP handler methods (RFC 6749 / 7662 / 7009) ---
+      /**
+       * Handle POST /oauth/token — dispatches to exchangeCode or clientCredentialsGrant.
+       */
+      async handleTokenRequest(body, clientAuth) {
+        const clientId = clientAuth?.clientId ?? body.client_id;
+        const clientSecret = clientAuth?.clientSecret ?? body.client_secret;
+        if (!clientId)
+          throw Errors.oauth("invalid_client", "Client authentication required");
+        const clientRecord = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: clientId }]
+        });
+        if (!clientRecord)
+          throw Errors.oauth("invalid_client", "Invalid client credentials");
+        const isPublic = clientRecord.tokenEndpointAuthMethod === "none";
+        if (!isPublic && !clientSecret)
+          throw Errors.oauth("invalid_client", "Client authentication required");
+        if (body.grant_type === "authorization_code") {
+          if (!body.code || !body.redirect_uri)
+            throw Errors.oauth("invalid_request", "Missing required parameters: code, redirect_uri");
+          if (isPublic && !body.code_verifier)
+            throw Errors.oauth("invalid_grant", "code_verifier required for public clients");
+          const result = await this.exchangeCode({
+            code: body.code,
+            clientId,
+            clientSecret: isPublic ? void 0 : clientSecret,
+            redirectUri: body.redirect_uri,
+            codeVerifier: body.code_verifier
+          });
+          return {
+            access_token: result.accessToken,
+            token_type: result.tokenType,
+            expires_in: result.expiresIn,
+            ...result.refreshToken ? { refresh_token: result.refreshToken } : {},
+            ...result.idToken ? { id_token: result.idToken } : {},
+            ...result.scope ? { scope: result.scope } : {}
+          };
+        }
+        if (body.grant_type === "refresh_token") {
+          if (!body.refresh_token)
+            throw Errors.oauth("invalid_request", "refresh_token is required");
+          const result = await this.refreshTokenGrant({
+            clientId,
+            clientSecret: isPublic ? void 0 : clientSecret,
+            refreshToken: body.refresh_token,
+            scope: body.scope
+          });
+          return {
+            access_token: result.accessToken,
+            token_type: result.tokenType,
+            expires_in: result.expiresIn,
+            refresh_token: result.refreshToken,
+            ...result.idToken ? { id_token: result.idToken } : {},
+            ...result.scope ? { scope: result.scope } : {}
+          };
+        }
+        if (body.grant_type === "client_credentials") {
+          if (!clientSecret)
+            throw Errors.oauth("invalid_client", "client_credentials requires a client secret");
+          const result = await this.clientCredentialsGrant({
+            clientId,
+            clientSecret,
+            scope: body.scope
+          });
+          return {
+            access_token: result.accessToken,
+            token_type: result.tokenType,
+            expires_in: result.expiresIn
+          };
+        }
+        throw Errors.oauth("unsupported_grant_type", `Unsupported grant_type: ${body.grant_type}`);
+      },
+      /**
+       * Handle POST /oauth/introspect (RFC 7662).
+       */
+      async handleIntrospectRequest(body, clientAuth) {
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: clientAuth.clientId }]
+        });
+        if (!client)
+          throw Errors.unauthorized("Invalid client credentials");
+        const secretValid = timingSafeEqualHex(
+          await hashToken(clientAuth.clientSecret),
+          client.clientSecretHash
+        );
+        if (!secretValid)
+          throw Errors.oauth("invalid_client", "Invalid client credentials");
+        const result = await this.introspectToken(body.token);
+        if (!result.active || result.clientId !== clientAuth.clientId)
+          return { active: false };
+        return {
+          active: true,
+          client_id: result.clientId,
+          ...result.userId != null ? { sub: String(result.userId) } : {},
+          ...result.scope ? { scope: result.scope } : {},
+          token_type: "Bearer"
+        };
+      },
+      /**
+       * Handle POST /oauth/revoke (RFC 7009). Always returns success.
+       */
+      async handleRevokeRequest(body, clientAuth) {
+        const client = await ctx.db.findOne({
+          model: "oauth_client",
+          where: [{ field: "clientId", operator: "=", value: clientAuth.clientId }]
+        });
+        if (!client || !timingSafeEqualHex(await hashToken(clientAuth.clientSecret), client.clientSecretHash))
+          throw Errors.oauth("invalid_client", "Invalid client credentials");
+        const tokenHash = await hashToken(body.token);
+        await ctx.db.delete({
+          model: "oauth_access_token",
+          where: [
+            { field: "token", operator: "=", value: tokenHash },
+            { field: "clientId", operator: "=", value: clientAuth.clientId }
+          ]
+        });
+        if (refreshEnabled) {
+          const refreshRecord = await ctx.db.findOne({
+            model: "oauth_refresh_token",
+            where: [
+              { field: "token", operator: "=", value: tokenHash },
+              { field: "clientId", operator: "=", value: clientAuth.clientId }
+            ]
+          });
+          if (refreshRecord) {
+            await ctx.db.delete({
+              model: "oauth_refresh_token",
+              where: [
+                { field: "familyId", operator: "=", value: refreshRecord.familyId },
+                { field: "clientId", operator: "=", value: clientAuth.clientId }
+              ]
+            });
+          }
+        }
+      },
+      /**
+       * Handle GET /oauth/userinfo (OpenID Connect Core §5.3).
+       *
+       * Returns the OIDC-shaped claims object expected by strict RPs (Moodle
+       * `core\oauth2\client::get_userinfo()`, openid-client, Keycloak
+       * federation, Spring Security). The pre-1.0 fortress shape that
+       * leaked DB-internal fields (`id`, `isActive`, `createdAt`) is gone
+       * — callers must rely on the spec-conformant fields below.
+       *
+       * Standard claim coverage (OIDC Core §5.1) gated by access-token
+       * scope (§5.4):
+       * - `sub` always (stringified `user.id`)
+       * - `email`, `email_verified` only when scope contains `email`
+       * - `name`, `preferred_username` only when scope contains `profile`
+       * - `updated_at` always (Unix seconds, per §5.1)
+       *
+       * Extra claims can be added per-deployment via
+       * {@link OAuthConfig.userinfoClaims}.
+       */
+      async handleUserInfoRequest(bearerToken) {
+        const result = await this._lookupBearer(bearerToken);
+        if (!result)
+          throw Errors.unauthorized("Invalid or expired access token");
+        const claims = toOidcUserinfo(result.user, result.scope);
+        if (config.userinfoClaims) {
+          const extra = await config.userinfoClaims(result.user, result.scope);
+          Object.assign(claims, extra);
+        }
+        return claims;
+      },
+      /**
+       * Handle GET /.well-known/openid-configuration (RFC 8414 + OIDC
+       * Discovery 1.0). Includes the RFC 9207 metadata flag and the OIDC
+       * fields strict RPs (Moodle, openid-client, Spring Security) require
+       * for autoconfig.
+       */
+      handleDiscovery() {
+        const issuer = issuerUrl;
+        const mappedScopes = scopePermissionMap ? Object.keys(scopePermissionMap) : [];
+        const scopesSupported = Array.from(/* @__PURE__ */ new Set([
+          "openid",
+          "email",
+          "profile",
+          ...config.scopesSupported ?? [],
+          ...mappedScopes
+        ]));
+        return {
+          issuer,
+          authorization_endpoint: `${issuer}/oauth/authorize`,
+          token_endpoint: `${issuer}/oauth/token`,
+          introspection_endpoint: `${issuer}/oauth/introspect`,
+          revocation_endpoint: `${issuer}/oauth/revoke`,
+          userinfo_endpoint: `${issuer}/oauth/userinfo`,
+          jwks_uri: `${issuer}/oauth/.well-known/jwks.json`,
+          response_types_supported: ["code"],
+          response_modes_supported: ["query"],
+          grant_types_supported: refreshEnabled ? ["authorization_code", "client_credentials", "refresh_token"] : ["authorization_code", "client_credentials"],
+          token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post", "none"],
+          code_challenge_methods_supported: ["S256"],
+          subject_types_supported: ["public"],
+          // OIDC Discovery §3 REQUIRED when id_tokens are issued.
+          id_token_signing_alg_values_supported: ["RS256"],
+          scopes_supported: scopesSupported,
+          claims_supported: [
+            "sub",
+            "email",
+            "email_verified",
+            "name",
+            "preferred_username",
+            "updated_at",
+            "iss",
+            "aud",
+            "exp",
+            "iat",
+            "auth_time",
+            "nonce"
+          ],
+          // RFC 9207 §3.
+          authorization_response_iss_parameter_supported: true
+        };
+      },
+      /**
+       * Handle GET /oauth/.well-known/jwks.json (RFC 7517).
+       *
+       * Returns the AS's JSON Web Key Set: the active RS256 public key
+       * plus any rotated keys still in the verification grace window. RPs
+       * fetch this URL (advertised via discovery's `jwks_uri`) and use it
+       * to verify id_token signatures by `kid`.
+       */
+      async rotateSigningKey() {
+        const key = await rotateSigningKey(ctx.db, signingKeyGraceSeconds);
+        return { kid: key.kid };
+      },
+      async handleJwksRequest() {
+        const jwks = await listJwks(ctx.db, signingKeyGraceSeconds);
+        if (jwks.keys.length === 0) {
+          await getActiveSigningKey(ctx.db);
+          return await listJwks(ctx.db, signingKeyGraceSeconds);
+        }
+        return jwks;
+      },
+      /**
+       * Resolve an access token's scopes to IAM permissions using the configured scopePermissionMap.
+       */
+      async resolveTokenPermissions(token) {
+        const info = await this.introspectToken(token);
+        if (!info.active || !info.scope || !scopePermissionMap)
+          return [];
+        const scopes = info.scope.split(" ");
+        const permissions = [];
+        for (const scope of scopes) {
+          const mapping = scopePermissionMap[scope];
+          if (mapping) {
+            permissions.push(mapping);
+          }
+        }
+        return permissions;
+      }
+    }),
+    routes: {
+      // Front door for the auth-code flow. Opt-in: only mounted when the
+      // host app has wired up `loginUrl` and `consentUrl`.
+      ...config.enableAuthorizeEndpoint ? {
+        handleAuthorizeRequest: {
+          method: "GET",
+          path: "/oauth/authorize",
+          handler: "handleAuthorizeRequest",
+          meta: {
+            summary: "Start an OAuth authorization-code flow",
+            tags: ["OAuth"],
+            security: ["none"],
+            bearerKind: "oauth"
+          },
+          input: {
+            query: {
+              type: "object",
+              properties: {
+                client_id: { type: "string", description: "Registered OAuth client ID" },
+                redirect_uri: { type: "string", format: "uri", description: "Must match a redirect URI registered with the client" },
+                response_type: { type: "string", enum: ["code"], description: 'Only "code" is supported' },
+                scope: { type: "string", description: "Space-separated requested scopes" },
+                state: { type: "string", description: "Opaque value returned to the client; required to prevent CSRF" },
+                code_challenge: { type: "string", description: "PKCE code challenge (recommended for public clients)" },
+                code_challenge_method: { type: "string", enum: ["S256"], description: "PKCE method \u2014 only S256 is supported" }
+              },
+              required: ["client_id", "redirect_uri", "response_type", "state"]
+            }
+          },
+          responses: {
+            302: { description: "Redirect to login (unauthenticated) or consent (authenticated) page with ?flow=<id>" },
+            400: { description: "Invalid request" }
+          }
+        }
+      } : {},
+      // Consent API — SPA-friendly flow inspection + approve/deny.
+      ...config.enableConsentApi ? {
+        handleGetFlow: {
+          method: "GET",
+          path: "/oauth/flows/:flowId",
+          handler: "handleGetFlow",
+          meta: {
+            summary: "Fetch pending OAuth flow metadata",
+            tags: ["OAuth"],
+            security: ["bearer"]
+          },
+          responses: {
+            200: {
+              description: "Flow metadata",
+              schema: {
+                type: "object",
+                properties: {
+                  flowId: { type: "string" },
+                  client: {
+                    type: "object",
+                    properties: {
+                      clientId: { type: "string" },
+                      name: { type: "string" }
+                    }
+                  },
+                  redirectUri: { type: "string" },
+                  scopes: { type: "array", items: { type: "string" } },
+                  state: { type: "string" }
+                }
+              }
+            },
+            401: { description: "Authentication required" },
+            404: { description: "Flow not found" }
+          }
+        },
+        handleApproveFlow: {
+          method: "POST",
+          path: "/oauth/flows/:flowId/approve",
+          handler: "handleApproveFlow",
+          meta: {
+            summary: "Approve a pending OAuth flow",
+            tags: ["OAuth"],
+            security: ["bearer"]
+          },
+          responses: {
+            200: {
+              description: "Authorization code issued",
+              schema: {
+                type: "object",
+                properties: { redirectUrl: { type: "string" } }
+              }
+            },
+            401: { description: "Authentication required" },
+            404: { description: "Flow not found" }
+          }
+        },
+        handleDenyFlow: {
+          method: "POST",
+          path: "/oauth/flows/:flowId/deny",
+          handler: "handleDenyFlow",
+          meta: {
+            summary: "Deny a pending OAuth flow",
+            tags: ["OAuth"],
+            security: ["bearer"]
+          },
+          responses: {
+            200: {
+              description: "Flow denied",
+              schema: {
+                type: "object",
+                properties: { redirectUrl: { type: "string" } }
+              }
+            },
+            401: { description: "Authentication required" },
+            404: { description: "Flow not found" }
+          }
+        }
+      } : {},
+      handleTokenRequest: {
+        method: "POST",
+        path: "/oauth/token",
+        handler: "handleTokenRequest",
+        meta: { summary: "Exchange credentials for tokens", tags: ["OAuth"], security: ["basic"], bearerKind: "oauth" },
+        input: {
+          body: {
+            type: "object",
+            properties: {
+              grant_type: { type: "string", enum: ["authorization_code", "client_credentials", "refresh_token"], description: "OAuth grant type" },
+              code: { type: "string", description: "Authorization code" },
+              redirect_uri: { type: "string", format: "uri", description: "Redirect URI used in authorize" },
+              client_id: { type: "string", description: "Client ID (if not using Basic auth)" },
+              client_secret: { type: "string", description: "Client secret (if not using Basic auth)" },
+              code_verifier: { type: "string", description: "PKCE code verifier" },
+              refresh_token: { type: "string", description: "Refresh token for grant_type=refresh_token" },
+              scope: { type: "string", description: "Space-separated scopes" }
+            },
+            required: ["grant_type"]
+          }
+        },
+        responses: {
+          200: { description: "Token issued", schema: { type: "object", properties: { access_token: { type: "string" }, token_type: { type: "string" }, expires_in: { type: "number" }, refresh_token: { type: "string" }, id_token: { type: "string" }, scope: { type: "string" } } } },
+          400: { description: "Invalid request" },
+          401: { description: "Invalid client credentials" }
+        }
+      },
+      handleIntrospectRequest: {
+        method: "POST",
+        path: "/oauth/introspect",
+        handler: "handleIntrospectRequest",
+        meta: { summary: "Introspect a token (RFC 7662)", tags: ["OAuth"], security: ["basic"], bearerKind: "oauth" },
+        input: { body: { type: "object", properties: { token: { type: "string" } }, required: ["token"] } },
+        responses: {
+          200: { description: "Token info", schema: { type: "object", properties: { active: { type: "boolean" }, sub: { type: "string" }, scope: { type: "string" }, exp: { type: "number" } } } },
+          401: { description: "Client authentication required" }
+        }
+      },
+      handleRevokeRequest: {
+        method: "POST",
+        path: "/oauth/revoke",
+        handler: "handleRevokeRequest",
+        meta: { summary: "Revoke a token (RFC 7009)", tags: ["OAuth"], security: ["basic"], bearerKind: "oauth" },
+        input: { body: { type: "object", properties: { token: { type: "string" } }, required: ["token"] } },
+        responses: { 200: { description: "Token revoked" } }
+      },
+      handleUserInfoRequest: {
+        method: "GET",
+        path: "/oauth/userinfo",
+        handler: "handleUserInfoRequest",
+        meta: { summary: "Get user info (OIDC Core \xA75.3)", tags: ["OAuth"], security: ["bearer"], bearerKind: "oauth" },
+        responses: {
+          200: {
+            description: "OIDC userinfo response",
+            schema: {
+              type: "object",
+              properties: {
+                sub: { type: "string", description: "Stringified user identifier" },
+                email: { type: "string", format: "email" },
+                email_verified: { type: "boolean" },
+                name: { type: "string" },
+                preferred_username: { type: "string" },
+                updated_at: { type: "number", description: "Unix seconds since the user record was last updated" }
+              },
+              required: ["sub"],
+              additionalProperties: true
+            }
+          },
+          401: { description: "Invalid or expired bearer token" }
+        }
+      },
+      handleDiscovery: {
+        method: "GET",
+        path: "/oauth/.well-known/openid-configuration",
+        handler: "handleDiscovery",
+        meta: { summary: "OIDC discovery document", tags: ["OAuth"], security: ["none"], bearerKind: "oauth" },
+        responses: { 200: { description: "OIDC configuration", schema: { type: "object", additionalProperties: true } } }
+      },
+      handleJwksRequest: {
+        method: "GET",
+        path: "/oauth/.well-known/jwks.json",
+        handler: "handleJwksRequest",
+        meta: { summary: "JSON Web Key Set (RFC 7517)", tags: ["OAuth"], security: ["none"], bearerKind: "oauth" },
+        responses: {
+          200: {
+            description: "JWKS for verifying id_token signatures",
+            schema: {
+              type: "object",
+              properties: {
+                keys: {
+                  type: "array",
+                  items: { type: "object", additionalProperties: true }
+                }
+              },
+              required: ["keys"]
+            }
+          }
+        }
+      }
+    }
+  };
+}
+function matchRedirectUri(registered, inbound) {
+  if (registered === inbound)
+    return true;
+  let r, i;
+  try {
+    r = new URL(registered);
+    i = new URL(inbound);
+  } catch {
+    return false;
+  }
+  const isLoopback = r.protocol === "http:" && (r.hostname === "127.0.0.1" || r.hostname === "[::1]") && r.hostname === i.hostname;
+  if (!isLoopback)
+    return false;
+  return r.protocol === i.protocol && r.pathname === i.pathname && r.search === i.search;
+}
+function pendingFlowLookupWhere(flowId) {
+  return typeof flowId === "number" ? [{ field: "id", operator: "=", value: flowId }] : [{ field: "flowId", operator: "=", value: flowId }];
+}
+function intersectScope(requested, clientAllowedJson) {
+  if (!requested)
+    return "";
+  if (clientAllowedJson == null)
+    return requested;
+  const allowed = JSON.parse(clientAllowedJson);
+  const allowedSet = new Set(allowed);
+  return requested.split(" ").filter(Boolean).filter((s) => allowedSet.has(s)).join(" ");
+}
+function toOidcUserinfo(user, scope) {
+  const scopes = scope ? scope.split(" ").filter(Boolean) : [];
+  const exposeEmail = scopes.includes("email");
+  const exposeProfile = scopes.includes("profile");
+  const claims = { sub: String(user.id) };
+  if (exposeEmail) {
+    claims.email = user.email;
+    if (typeof user.emailVerified === "boolean")
+      claims.email_verified = user.emailVerified;
+  }
+  if (exposeProfile) {
+    claims.name = user.name;
+    claims.preferred_username = user.email;
+  }
+  if (user.updatedAt) {
+    claims.updated_at = Math.floor(new Date(user.updatedAt).getTime() / 1e3);
+  }
+  return claims;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateCodeChallenge,
+  generateCodeVerifier,
+  matchRedirectUri,
+  oauth,
+  toOidcUserinfo,
+  verifyCodeChallenge
+});