@jeffjassky/oauth-host 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -3,6 +3,7 @@
 var mongoose = require('mongoose');
 var express2 = require('express');
 var crypto = require('crypto');
+var jose = require('jose');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -29,9 +30,11 @@ function clientSchema() {
     {
       clientId: { type: String, required: true, unique: true },
       name: { type: String, required: true },
-      // `public` exists for CIMD clients, which hold no secret and are bound by
-      // PKCE instead. The enum was written with this widening in mind, so it
-      // was one member rather than a migration.
+      // `public` is a client that holds no secret and is bound by PKCE instead.
+      // Two ways in and they are independent: a CIMD row is written public, and
+      // `clients.create({ type: 'public' })` registers one by hand. The enum was
+      // written with this widening in mind, so it was one member rather than a
+      // migration.
       type: { type: String, enum: ["confidential", "public"], default: "confidential" },
       // How the row got here. A `cimd` row is re-derived from the client's own
       // metadata document, so this is what tells the re-fetch path which fields
@@ -40,6 +43,18 @@ function clientSchema() {
       metadataUrl: String,
       metadataFetchedAt: Date,
       metadataEtag: String,
+      // The usable (intersected) token endpoint auth method set for a CIMD
+      // client — absent on a manual registration, whose behavior derives from
+      // `type` exactly as before. A row with no value here supports no
+      // assertion-based method; see `authenticateClient`'s fallback rule.
+      tokenEndpointAuthMethods: [String],
+      // Exactly one of these two is set when `private_key_jwt` is in
+      // `tokenEndpointAuthMethods` — `validateMetadataDocument` refuses a
+      // document declaring both. Neither is ever required at the schema
+      // level: a manual client, or a CIMD client that only offers `none`,
+      // legitimately has neither.
+      jwksUri: String,
+      jwks: mongoose__default.default.Schema.Types.Mixed,
       trusted: { type: Boolean, default: false },
       // An array, not a string: rotation needs two live secrets at once or it
       // cannot be deployed without downtime.
@@ -383,7 +398,10 @@ function resolveCimd(input, scopeIndex) {
     fetchTimeoutMs: 5e3,
     maxBytes: 65536,
     allowedScopes: [],
-    failures: /* @__PURE__ */ new Map()
+    failures: /* @__PURE__ */ new Map(),
+    jwksCache: /* @__PURE__ */ new Map(),
+    jwksForceRefetchAt: /* @__PURE__ */ new Map(),
+    assertionReplay: /* @__PURE__ */ new Map()
   };
   if (!input || !input.enabled) return off;
   if (!Array.isArray(input.allowedHosts) || input.allowedHosts.length === 0) {
@@ -416,7 +434,10 @@ function resolveCimd(input, scopeIndex) {
     fetchTimeoutMs: positive(input.fetchTimeoutMs, "fetchTimeoutMs", 5e3),
     maxBytes: positive(input.maxBytes, "maxBytes", 65536),
     allowedScopes: [...allowedScopes],
-    failures: /* @__PURE__ */ new Map()
+    failures: /* @__PURE__ */ new Map(),
+    jwksCache: /* @__PURE__ */ new Map(),
+    jwksForceRefetchAt: /* @__PURE__ */ new Map(),
+    assertionReplay: /* @__PURE__ */ new Map()
   };
 }
 function resolveConfig(config) {
@@ -664,15 +685,19 @@ function authorizationServerMetadata(ctx, mountPath) {
     // S256 only. `plain` is not implemented anywhere in this package, so
     // advertising it would be a lie a client would discover at redemption.
     code_challenge_methods_supported: ["S256"],
-    // `none` is advertised only when CIMD is on. Listing it unconditionally
-    // would tell every client that secretless authentication is available here,
-    // and the only clients that can use it are the ones this server would then
-    // refuse to register.
+    // `none` and `private_key_jwt` are advertised only when CIMD is on.
+    // Listing either unconditionally would tell every client that secretless
+    // authentication is available here, and the only clients that can use it
+    // are the ones this server would then refuse to register.
     token_endpoint_auth_methods_supported: [
       "client_secret_basic",
       "client_secret_post",
-      ...ctx.cimd.enabled ? ["none"] : []
+      ...ctx.cimd.enabled ? ["none", "private_key_jwt"] : []
     ],
+    // RFC 7523 §2.2 — the only two algorithms `authenticateClient` accepts
+    // for a `client_assertion` signature. Same gate as the line above: it
+    // names a capability that only exists for a CIMD client.
+    ...ctx.cimd.enabled ? { token_endpoint_auth_signing_alg_values_supported: ["RS256", "ES256"] } : {},
     // What tells Claude and ChatGPT to skip registration entirely and send
     // their metadata document URL as `client_id`.
     ...ctx.cimd.enabled ? { client_id_metadata_document_supported: true } : {},
@@ -1275,749 +1300,1055 @@ function createKeyManager(ctx) {
   };
 }
 
-// src/server/services/admin.ts
-var MAX_LIST = 200;
-var DEFAULT_LIST = 50;
-function clampLimit(requested) {
-  const n = typeof requested === "number" && Number.isFinite(requested) ? Math.floor(requested) : DEFAULT_LIST;
-  if (n < 1) return 1;
-  return Math.min(n, MAX_LIST);
+// src/server/services/cimd.ts
+var NEGATIVE_TTL_MS = 6e4;
+var MAX_REMEMBERED_FAILURES = 1e3;
+function refuse(description) {
+  return new UnredirectableError("invalid_client", description);
 }
-function clampSkip(requested) {
-  const n = typeof requested === "number" && Number.isFinite(requested) ? Math.floor(requested) : 0;
-  return n > 0 ? n : 0;
+function isMetadataUrl(clientId) {
+  return /^https:\/\//i.test(clientId);
 }
-function notFound(clientId) {
-  return new Error(`oauth-host: no client registered with clientId '${clientId}'`);
+function hostAllowed(rules, url) {
+  const hostname = url.hostname.toLowerCase();
+  return rules.some((rule) => {
+    if (url.port !== rule.port) return false;
+    if (hostname === rule.host) return true;
+    return rule.subdomains && hostname.endsWith(`.${rule.host}`);
+  });
 }
-function toPublicClient(doc) {
+function assertFetchableUrl(ctx, clientId) {
+  let url;
+  try {
+    url = new URL(clientId);
+  } catch {
+    throw refuse(`client_id is not a valid URL: '${clientId}'`);
+  }
+  if (url.protocol !== "https:") {
+    throw refuse(`client_id metadata must be served over https (got '${url.protocol}')`);
+  }
+  if (url.username || url.password) {
+    throw refuse("client_id must not contain URL credentials");
+  }
+  if (url.hash) {
+    throw refuse("client_id must not contain a fragment");
+  }
+  if (!hostAllowed(ctx.cimd.allowedHosts, url)) {
+    throw refuse(`client_id host '${url.host}' is not in clientIdMetadata.allowedHosts`);
+  }
+  return url;
+}
+var JSON_CONTENT_TYPE = /^application\/(?:[\w.+-]+\+)?json\s*(?:;|$)/i;
+async function readCapped(res, maxBytes, docSubject) {
+  const body = res.body;
+  if (!body) throw refuse(`${docSubject} was empty`);
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      void reader.cancel();
+      throw refuse(`${docSubject} exceeds ${maxBytes} bytes`);
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function hardenedFetch(ctx, url, opts) {
+  const { subject, redirectAdvice, etag } = opts;
+  const docSubject = `${subject} document`;
+  let res;
+  try {
+    res = await fetch(url.toString(), {
+      method: "GET",
+      // The single most important line in this file. A 3xx is a failure below,
+      // not a hop: following redirects would let an allowlisted host forward us
+      // to any address it likes, allowlist intact.
+      redirect: "manual",
+      headers: {
+        accept: "application/json",
+        ...etag ? { "if-none-match": etag } : {}
+      },
+      signal: AbortSignal.timeout(ctx.cimd.fetchTimeoutMs)
+    });
+  } catch (err) {
+    const name = err?.name;
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw refuse(`${subject} fetch timed out after ${ctx.cimd.fetchTimeoutMs}ms`);
+    }
+    throw refuse(`${subject} could not be fetched: ${err?.message ?? "network error"}`);
+  }
+  if (res.status === 304) return { document: null };
+  if (res.status >= 300 && res.status < 400) {
+    throw refuse(`${subject} returned a ${res.status} redirect, which is not followed \u2014 ${redirectAdvice}`);
+  }
+  if (res.status !== 200) {
+    throw refuse(`${subject} returned HTTP ${res.status}`);
+  }
+  const contentType = res.headers.get("content-type") ?? "";
+  if (!JSON_CONTENT_TYPE.test(contentType)) {
+    throw refuse(`${subject} must be JSON (got content-type '${contentType || "none"}')`);
+  }
+  const text = await readCapped(res, ctx.cimd.maxBytes, docSubject);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw refuse(`${docSubject} is not valid JSON`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw refuse(`${docSubject} must be a JSON object`);
+  }
   return {
-    clientId: doc.clientId,
-    name: doc.name,
-    type: doc.type,
-    // Defaulted rather than read straight through: rows written before the
-    // field existed have no value, and `undefined` here would read as "unknown
-    // provenance" on a client that plainly was registered by hand.
-    registration: doc.registration ?? "manual",
-    ...doc.metadataUrl ? { metadataUrl: doc.metadataUrl } : {},
-    trusted: Boolean(doc.trusted),
-    redirectUris: [...doc.redirectUris ?? []],
-    allowedScopes: [...doc.allowedScopes ?? []],
-    allowedResources: [...doc.allowedResources ?? []],
-    branding: { ...doc.branding ?? {} },
-    status: doc.status,
-    createdAt: doc.createdAt
+    document: parsed,
+    ...res.headers.get("etag") ? { etag: res.headers.get("etag") } : {}
   };
 }
-function assertRedirectUri(value) {
-  if (typeof value !== "string" || !value) {
-    throw new TypeError(`oauth-host: every redirectUri must be a string (got ${JSON.stringify(value)})`);
+async function fetchMetadata(ctx, url, etag) {
+  return hardenedFetch(ctx, url, {
+    subject: "client_id metadata",
+    redirectAdvice: "serve the document at the client_id URL itself",
+    etag
+  });
+}
+async function fetchJwks(ctx, jwksUri) {
+  const url = new URL(jwksUri);
+  const { document } = await hardenedFetch(ctx, url, {
+    subject: "jwks_uri",
+    redirectAdvice: "serve the JWK Set at the jwks_uri URL itself"
+  });
+  if (!document) throw refuse("jwks_uri fetch returned no document");
+  return document;
+}
+var SERVER_CIMD_AUTH_METHODS = ["none", "private_key_jwt"];
+function assertJwksUri(ctx, value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw refuse("client_id metadata field 'jwks_uri' must be a non-empty string");
   }
   let url;
   try {
     url = new URL(value);
   } catch {
-    throw new TypeError(`oauth-host: redirectUri must be an absolute URI: '${value}'`);
+    throw refuse(`client_id metadata field 'jwks_uri' is not a valid URL: '${value}'`);
   }
-  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
-  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
-    throw new TypeError(
-      `oauth-host: redirectUri must be https (http is allowed only on localhost/127.0.0.1): '${value}'`
-    );
+  if (url.protocol !== "https:") {
+    throw refuse(`client_id metadata field 'jwks_uri' must be served over https (got '${url.protocol}')`);
+  }
+  if (url.username || url.password) {
+    throw refuse("client_id metadata field 'jwks_uri' must not contain URL credentials");
   }
   if (url.hash) {
-    throw new TypeError(`oauth-host: redirectUri must not contain a fragment: '${value}'`);
+    throw refuse("client_id metadata field 'jwks_uri' must not contain a fragment");
   }
-  return value;
-}
-function assertRedirectUris(input) {
-  if (!Array.isArray(input) || input.length === 0) {
-    throw new TypeError("oauth-host: a client needs at least one redirectUri");
+  if (!hostAllowed(ctx.cimd.allowedHosts, url)) {
+    throw refuse(`client_id metadata field 'jwks_uri' host '${url.host}' is not in clientIdMetadata.allowedHosts`);
   }
-  return input.map(assertRedirectUri);
+  return url.href;
 }
-function assertScopes(ctx, input) {
-  if (!Array.isArray(input) || input.length === 0) {
-    throw new TypeError("oauth-host: a client needs at least one entry in allowedScopes");
+function assertInlineJwks(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw refuse("client_id metadata field 'jwks' must be a JSON object");
   }
-  for (const id of input) {
-    if (typeof id !== "string" || !ctx.scopeIndex.has(id)) {
-      throw new TypeError(
-        `oauth-host: allowedScopes contains '${String(id)}', which is not in the configured scope catalog`
-      );
+  const keys = value.keys;
+  if (!Array.isArray(keys) || keys.length === 0) {
+    throw refuse("client_id metadata field 'jwks' must contain a non-empty 'keys' array");
+  }
+  for (const key of keys) {
+    if (!key || typeof key !== "object" || Array.isArray(key)) {
+      throw refuse("client_id metadata field 'jwks' contains a non-object entry in 'keys'");
     }
   }
-  return [...input];
+  return value;
 }
-function assertResources(ctx, input) {
-  const declared = new Set(ctx.resources.map((r) => r.id));
-  if (input === void 0) return ctx.resources.map((r) => r.id);
-  if (!Array.isArray(input) || input.length === 0) {
-    throw new TypeError("oauth-host: allowedResources, when given, must list at least one resource");
-  }
-  for (const id of input) {
-    if (typeof id !== "string" || !declared.has(id)) {
-      throw new TypeError(
-        `oauth-host: allowedResources contains '${String(id)}', which is not a configured resource`
+function offeredAuthMethods(doc) {
+  const plural = doc.token_endpoint_auth_methods_supported;
+  if (plural !== void 0) {
+    if (!Array.isArray(plural) || plural.length === 0 || !plural.every((entry) => typeof entry === "string" && entry.length > 0)) {
+      throw refuse(
+        "client_id metadata field 'token_endpoint_auth_methods_supported' must be a non-empty array of strings"
       );
     }
+    return [...new Set(plural)];
   }
-  return [...input];
+  const singular = doc.token_endpoint_auth_method;
+  if (singular !== void 0) {
+    if (typeof singular !== "string" || !singular) {
+      throw refuse("client_id metadata field 'token_endpoint_auth_method' must be a string");
+    }
+    return [singular];
+  }
+  return ["none"];
 }
-function assertName(value) {
+function requireString(doc, field) {
+  const value = doc[field];
   if (typeof value !== "string" || !value.trim()) {
-    throw new TypeError("oauth-host: a client needs a non-empty `name` \u2014 it is what the consent screen shows");
+    throw refuse(`client_id metadata field '${field}' must be a non-empty string`);
   }
   return value.trim();
 }
-async function revokeGrantsMatching(ctx, filter, by) {
-  const res = await ctx.models.Grant.updateMany(
-    { ...filter, revokedAt: null },
-    { $set: { revokedAt: /* @__PURE__ */ new Date(), revokedBy: by } }
-  );
-  return { grantsRevoked: res.modifiedCount ?? 0 };
+function optionalHttpsUri(doc, field) {
+  const value = doc[field];
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string" || !value.trim()) {
+    throw refuse(`client_id metadata field '${field}' must be a string`);
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw refuse(`client_id metadata field '${field}' must be an absolute URL: '${value}'`);
+  }
+  if (url.protocol !== "https:") {
+    throw refuse(`client_id metadata field '${field}' must be https (got '${url.protocol}')`);
+  }
+  return value;
 }
-async function revokeTokensMatching(ctx, filter) {
-  const res = await ctx.models.Token.updateMany(
-    { ...filter, revokedAt: null },
-    { $set: { revokedAt: /* @__PURE__ */ new Date() } }
-  );
-  return res.modifiedCount ?? 0;
+function assertRedirectUris(doc) {
+  const value = doc.redirect_uris;
+  if (!Array.isArray(value) || value.length === 0) {
+    throw refuse("client_id metadata field 'redirect_uris' must be a non-empty array");
+  }
+  return value.map((entry) => {
+    if (typeof entry !== "string" || !entry) {
+      throw refuse(`client_id metadata 'redirect_uris' entries must be strings (got ${JSON.stringify(entry)})`);
+    }
+    let url;
+    try {
+      url = new URL(entry);
+    } catch {
+      throw refuse(`client_id metadata 'redirect_uris' entry must be an absolute URI: '${entry}'`);
+    }
+    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+      throw refuse(
+        `client_id metadata 'redirect_uris' entry must be https (http is allowed only on localhost/127.0.0.1): '${entry}'`
+      );
+    }
+    if (url.hash) {
+      throw refuse(`client_id metadata 'redirect_uris' entry must not contain a fragment: '${entry}'`);
+    }
+    return entry;
+  });
 }
-function createClientsApi(ctx) {
-  return {
-    async create(spec) {
-      if (!spec || typeof spec !== "object") {
-        throw new TypeError("oauth-host: clients.create(spec) requires a spec object");
-      }
-      const name = assertName(spec.name);
-      const redirectUris = assertRedirectUris(spec.redirectUris);
-      const allowedScopes = assertScopes(ctx, spec.allowedScopes);
-      const allowedResources = assertResources(ctx, spec.allowedResources);
-      const clientId = spec.clientId ?? generateClientId();
-      const clientSecret = generateClientSecret();
-      const doc = await ctx.models.Client.create({
-        clientId,
-        name,
-        type: "confidential",
-        registration: "manual",
-        trusted: Boolean(spec.trusted),
-        // Only the digest is stored. `clientSecret` below is the only time the
-        // raw value exists outside the caller's variable.
-        secrets: [{ hash: sha256(clientSecret), label: "initial", createdAt: /* @__PURE__ */ new Date() }],
-        redirectUris,
-        allowedScopes,
-        allowedResources,
-        branding: spec.branding ?? {},
-        status: "active"
-      });
-      await ctx.audit({ type: "oauth.client_created", actor: "admin", clientId });
-      return { client: toPublicClient(doc), clientId, clientSecret };
-    },
-    async rotateSecret(clientId, opts = {}) {
-      const doc = await ctx.models.Client.findOne({ clientId });
-      if (!doc) throw notFound(clientId);
-      if (doc.type === "public") {
-        throw new Error(
-          `oauth-host: client '${clientId}' is a public client and has no secret to rotate. Public clients authenticate with client_id and PKCE.`
-        );
-      }
-      const retireAfter = typeof opts.retireAfter === "number" && opts.retireAfter > 0 ? opts.retireAfter : 0;
-      const retiresAt = new Date(Date.now() + retireAfter);
-      for (const record of doc.secrets) {
-        record.retiresAt = record.retiresAt && record.retiresAt < retiresAt ? record.retiresAt : retiresAt;
-      }
-      const clientSecret = generateClientSecret();
-      doc.secrets.push({
-        hash: sha256(clientSecret),
-        label: opts.label ?? `rotated-${(/* @__PURE__ */ new Date()).toISOString()}`,
-        createdAt: /* @__PURE__ */ new Date()
-      });
-      doc.markModified("secrets");
-      await doc.save();
-      ctx.track({ type: "oauth.client_secret_rotated", clientId });
-      await ctx.audit({
-        type: "oauth.client_secret_rotated",
-        actor: "admin",
-        clientId,
-        meta: { retireAfter, retiresAt }
-      });
-      return { client: toPublicClient(doc), clientId, clientSecret };
-    },
-    async update(clientId, patch) {
-      const doc = await ctx.models.Client.findOne({ clientId });
-      if (!doc) throw notFound(clientId);
-      if (patch.name !== void 0) doc.name = assertName(patch.name);
-      if (patch.redirectUris !== void 0) doc.redirectUris = assertRedirectUris(patch.redirectUris);
-      if (patch.allowedScopes !== void 0) doc.allowedScopes = assertScopes(ctx, patch.allowedScopes);
-      if (patch.allowedResources !== void 0) {
-        doc.allowedResources = assertResources(ctx, patch.allowedResources);
-      }
-      if (patch.branding !== void 0) doc.branding = patch.branding;
-      if (patch.trusted !== void 0) doc.trusted = Boolean(patch.trusted);
-      await doc.save();
-      await ctx.audit({ type: "oauth.client_updated", actor: "admin", clientId });
-      return toPublicClient(doc);
-    },
-    async list(query = {}) {
-      const limit = clampLimit(query.limit);
-      const skip = clampSkip(query.skip);
-      const filter = {};
-      if (query.status) filter.status = query.status;
-      const docs = await ctx.models.Client.find(filter).sort({ createdAt: -1 }).skip(skip).limit(limit).lean();
-      return { items: docs.map(toPublicClient), limit };
-    },
-    async get(clientId) {
-      const doc = await ctx.models.Client.findOne({ clientId }).lean();
-      return doc ? toPublicClient(doc) : null;
-    },
-    async disable(clientId) {
-      const doc = await ctx.models.Client.findOne({ clientId });
-      if (!doc) throw notFound(clientId);
-      doc.status = "disabled";
-      await doc.save();
-      const { grantsRevoked } = await revokeGrantsMatching(ctx, { clientId }, "admin");
-      const tokensRevoked = await revokeTokensMatching(ctx, { clientId });
-      await ctx.models.Code.deleteMany({ clientId });
-      await ctx.models.Request.deleteMany({ clientId });
-      await ctx.audit({
-        type: "oauth.client_disabled",
-        actor: "admin",
-        clientId,
-        meta: { grantsRevoked, tokensRevoked }
-      });
-      return { grantsRevoked, tokensRevoked };
-    }
-  };
-}
-function formUrlDecode(value) {
+function validateMetadataDocument(ctx, url, doc) {
+  const declared = requireString(doc, "client_id");
+  let declaredUrl;
   try {
-    return decodeURIComponent(value.replace(/\+/g, " "));
+    declaredUrl = new URL(declared);
   } catch {
-    return value;
+    throw refuse(`client_id metadata field 'client_id' is not a URL: '${declared}'`);
   }
-}
-function readCredentials(req) {
-  const header = req.headers?.authorization;
-  if (typeof header === "string" && /^Basic /i.test(header)) {
-    const decoded = Buffer.from(header.slice(6).trim(), "base64").toString("utf8");
-    const sep = decoded.indexOf(":");
-    const clientId = formUrlDecode(sep < 0 ? decoded : decoded.slice(0, sep));
-    const secret = sep < 0 ? "" : formUrlDecode(decoded.slice(sep + 1));
-    return { clientId, clientSecret: secret === "" ? null : secret, viaBasic: true };
+  if (declaredUrl.href !== url.href) {
+    throw refuse(
+      `client_id metadata field 'client_id' is '${declared}', which is not the URL it was fetched from ('${url.href}')`
+    );
   }
-  const body = req.body ?? {};
-  if (typeof body.client_id === "string" && body.client_id) {
-    return {
-      clientId: body.client_id,
-      clientSecret: typeof body.client_secret === "string" && body.client_secret ? body.client_secret : null,
-      viaBasic: false
-    };
+  const offered = offeredAuthMethods(doc);
+  let usableMethods = offered.filter((m) => SERVER_CIMD_AUTH_METHODS.includes(m));
+  if (usableMethods.length === 0) {
+    throw refuse(
+      `client_id metadata offers token endpoint auth methods [${offered.join(", ")}]; this server supports [${SERVER_CIMD_AUTH_METHODS.join(", ")}] for CIMD clients \u2014 no usable method in the intersection`
+    );
   }
-  return null;
-}
-function authFailure(viaBasic) {
-  return new OAuthError(401, "invalid_client", "client authentication failed", {
-    // RFC 6749 §5.2 — a 401 answering a Basic credential MUST carry the challenge.
-    headers: viaBasic ? { "WWW-Authenticate": 'Basic realm="oauth", charset="UTF-8"' } : {}
-  });
+  let jwksUri;
+  let jwks;
+  if (usableMethods.includes("private_key_jwt")) {
+    const hasJwksUri = doc.jwks_uri !== void 0 && doc.jwks_uri !== null;
+    const hasJwks = doc.jwks !== void 0 && doc.jwks !== null;
+    if (hasJwksUri && hasJwks) {
+      throw refuse("client_id metadata must not contain both 'jwks' and 'jwks_uri'");
+    }
+    if (hasJwksUri) {
+      jwksUri = assertJwksUri(ctx, doc.jwks_uri);
+    } else if (hasJwks) {
+      jwks = assertInlineJwks(doc.jwks);
+    } else if (usableMethods.includes("none")) {
+      usableMethods = usableMethods.filter((m) => m !== "private_key_jwt");
+    } else {
+      throw refuse("client_id metadata offers private_key_jwt but carries no 'jwks' or 'jwks_uri'");
+    }
+  }
+  const name = requireString(doc, "client_name");
+  const redirectUris = assertRedirectUris(doc);
+  const permitted = new Set(ctx.cimd.allowedScopes.filter((id) => ctx.scopeIndex.has(id)));
+  let allowedScopes;
+  if (doc.scope === void 0 || doc.scope === null) {
+    allowedScopes = [...permitted];
+  } else {
+    if (typeof doc.scope !== "string") {
+      throw refuse("client_id metadata field 'scope' must be a space-delimited string");
+    }
+    const requested = new Set(doc.scope.split(/\s+/).filter(Boolean));
+    allowedScopes = [...permitted].filter((id) => requested.has(id));
+  }
+  if (allowedScopes.length === 0) {
+    throw refuse(
+      "client_id metadata field 'scope' has no overlap with what this server offers \u2014 there is nothing this client could be granted"
+    );
+  }
+  const branding = {};
+  const logoUrl = optionalHttpsUri(doc, "logo_uri");
+  const homepageUrl = optionalHttpsUri(doc, "client_uri");
+  const tosUrl = optionalHttpsUri(doc, "tos_uri");
+  const privacyUrl = optionalHttpsUri(doc, "policy_uri");
+  if (logoUrl) branding.logoUrl = logoUrl;
+  if (homepageUrl) branding.homepageUrl = homepageUrl;
+  if (tosUrl) branding.tosUrl = tosUrl;
+  if (privacyUrl) branding.privacyUrl = privacyUrl;
+  return {
+    name,
+    redirectUris,
+    allowedScopes,
+    branding,
+    usableMethods,
+    ...jwksUri ? { jwksUri } : {},
+    ...jwks ? { jwks } : {}
+  };
 }
-async function authenticateClient(ctx, req) {
-  const creds = readCredentials(req);
-  if (!creds || !creds.clientId) throw authFailure(Boolean(creds?.viaBasic));
-  const client = await ctx.models.Client.findOne({ clientId: creds.clientId });
-  if (!client || client.status !== "active") throw authFailure(creds.viaBasic);
-  if (client.type === "public") {
-    if (creds.clientSecret !== null) throw authFailure(creds.viaBasic);
-    return client;
+function rememberFailure(ctx, key, message) {
+  const { failures } = ctx.cimd;
+  if (failures.size >= MAX_REMEMBERED_FAILURES) {
+    const oldest = failures.keys().next();
+    if (!oldest.done) failures.delete(oldest.value);
   }
-  if (creds.clientSecret === null) throw authFailure(creds.viaBasic);
-  const now = Date.now();
-  let matched;
-  for (const record of client.secrets) {
-    if (record.retiresAt && record.retiresAt.getTime() <= now) continue;
-    if (safeEqual(sha256(creds.clientSecret), record.hash)) matched = record;
+  failures.set(key, { until: Date.now() + NEGATIVE_TTL_MS, message });
+}
+function rememberedFailure(ctx, key) {
+  const found = ctx.cimd.failures.get(key);
+  if (!found) return null;
+  if (found.until <= Date.now()) {
+    ctx.cimd.failures.delete(key);
+    return null;
   }
-  if (!matched) throw authFailure(creds.viaBasic);
-  const usedAt = /* @__PURE__ */ new Date();
-  matched.lastUsedAt = usedAt;
-  await ctx.models.Client.updateOne(
-    { clientId: client.clientId, "secrets.hash": matched.hash },
-    { $set: { "secrets.$.lastUsedAt": usedAt } }
-  );
-  return client;
+  return found.message;
 }
-function describeGrantScopes(ctx, ids) {
-  return ids.map((id) => ctx.scopeIndex.get(id) ?? { id, label: id });
+function isFresh(ctx, client) {
+  const fetchedAt = client.metadataFetchedAt?.getTime();
+  if (fetchedAt === void 0) return false;
+  return Date.now() - fetchedAt < ctx.cimd.cacheTtlMs;
 }
-function createGrantsApi(ctx) {
-  return {
-    async list(query) {
-      const limit = clampLimit(query?.limit);
-      const skip = clampSkip(query?.skip);
-      const filter = { revokedAt: null };
-      if (query?.userId !== void 0) filter.userId = query.userId;
-      if (query?.clientId !== void 0) filter.clientId = query.clientId;
-      const grants = await ctx.models.Grant.find(filter).sort({ createdAt: -1 }).skip(skip).limit(limit).lean();
-      if (grants.length === 0) return { items: [], limit };
-      const clientIds = [...new Set(grants.map((g) => g.clientId))];
-      const clients = await ctx.models.Client.find({ clientId: { $in: clientIds } }).lean();
-      const byId = new Map(clients.map((c) => [c.clientId, toPublicClient(c)]));
-      const contextCache = /* @__PURE__ */ new Map();
-      const items = [];
-      for (const grant of grants) {
-        const client = byId.get(grant.clientId);
-        const summary = {
-          id: String(grant._id),
-          client: client ? { clientId: client.clientId, name: client.name, branding: client.branding } : { clientId: grant.clientId, name: grant.clientId, branding: {} },
-          scopes: describeGrantScopes(ctx, grant.scopes ?? []),
-          createdAt: grant.createdAt,
-          ...grant.lastUsedAt ? { lastUsedAt: grant.lastUsedAt } : {}
-        };
-        if (ctx.grantContext && grant.contextId) {
-          const cacheKey = `${String(grant.userId)}:${grant.clientId}`;
-          let available = contextCache.get(cacheKey);
-          if (!available) {
-            const user = { id: grant.userId };
-            available = client ? await ctx.grantContext.list(user, { client, scopes: grant.scopes ?? [] }) : [];
-            contextCache.set(cacheKey, available);
-          }
-          summary.context = available.find((c) => c.id === grant.contextId) ?? { id: grant.contextId, label: grant.contextId };
-        }
-        items.push(summary);
+async function persist(ctx, clientId, url, registration, etag) {
+  const unset = {};
+  const jwksFields = {};
+  if (registration.jwksUri) jwksFields.jwksUri = registration.jwksUri;
+  else unset.jwksUri = "";
+  if (registration.jwks) jwksFields.jwks = registration.jwks;
+  else unset.jwks = "";
+  const doc = await ctx.models.Client.findOneAndUpdate(
+    { clientId },
+    {
+      $set: {
+        name: registration.name,
+        redirectUris: registration.redirectUris,
+        allowedScopes: registration.allowedScopes,
+        // Every declared resource. A CIMD client cannot express an audience
+        // preference, and RFC 8707 validation at `/authorize` narrows it anyway.
+        allowedResources: ctx.resources.map((r) => r.id),
+        branding: registration.branding,
+        metadataUrl: url.href,
+        metadataFetchedAt: /* @__PURE__ */ new Date(),
+        tokenEndpointAuthMethods: registration.usableMethods,
+        ...jwksFields,
+        ...etag ? { metadataEtag: etag } : {}
+      },
+      ...Object.keys(unset).length ? { $unset: unset } : {},
+      $setOnInsert: {
+        type: "public",
+        registration: "cimd",
+        trusted: false,
+        secrets: [],
+        status: "active"
       }
-      return { items, limit };
     },
-    async revoke(grantId, opts = {}) {
-      const by = opts.by ?? "admin";
-      const grant = await ctx.models.Grant.findById(grantId).catch(() => null);
-      if (!grant) return { tokensRevoked: 0 };
-      const alreadyRevoked = Boolean(grant.revokedAt);
-      if (!alreadyRevoked) {
-        grant.revokedAt = /* @__PURE__ */ new Date();
-        grant.revokedBy = by;
-        await grant.save();
-      }
-      const tokensRevoked = await revokeTokensMatching(ctx, { grantId: grant._id });
-      if (!alreadyRevoked) {
-        ctx.track({
-          type: "oauth.grant_revoked",
-          userId: grant.userId,
-          clientId: grant.clientId,
-          grantId: String(grant._id),
-          ...grant.contextId ? { contextId: grant.contextId } : {},
-          scopes: grant.scopes
-        });
-        await ctx.audit({
-          type: "oauth.grant_revoked",
-          actor: by,
-          clientId: grant.clientId,
-          userId: grant.userId,
-          grantId: grant._id,
-          meta: { tokensRevoked }
-        });
-      }
-      return { tokensRevoked };
-    }
-  };
+    { upsert: true, returnDocument: "after", setDefaultsOnInsert: false }
+  ).exec();
+  return doc;
 }
-function pairwiseKey(userId) {
-  const key = String(userId);
-  if (!key || key.includes(".") || key.startsWith("$")) return null;
-  return key;
-}
-function createUsersApi(ctx) {
-  return {
-    /**
-     * Erasure. The user is gone and every trace of them has to go with them.
-     *
-     * This is the destructive twin of `revokeAll`, and the difference is the
-     * whole reason both exist: `forget` DELETES the grant documents and the
-     * user's audit rows, `revokeAll` keeps both. A password change must leave a
-     * history an operator can read; a deletion request must not.
-     *
-     * Idempotent — it will be called twice, by a retry or by a host that wires
-     * it to both a soft-delete and a hard-delete hook.
-     */
-    async forget(userId) {
-      const grantsResult = await ctx.models.Grant.deleteMany({ userId });
-      const tokensResult = await ctx.models.Token.deleteMany({ userId });
-      await ctx.models.Code.deleteMany({ userId });
-      await ctx.models.Request.deleteMany({ userId });
-      const key = pairwiseKey(userId);
-      if (key) {
-        await ctx.models.Client.updateMany(
-          { [`pairwiseSubjects.${key}`]: { $exists: true } },
-          { $unset: { [`pairwiseSubjects.${key}`]: "" } }
-        );
-      }
-      await ctx.models.Audit.deleteMany({ userId });
-      const grants = grantsResult.deletedCount ?? 0;
-      const tokens = tokensResult.deletedCount ?? 0;
-      await ctx.audit({ type: "oauth.user_forgotten", actor: "system", meta: { grants, tokens } });
-      return { grants, tokens };
-    },
-    /**
-     * Password change, deactivation, suspected compromise.
-     *
-     * Kills live access and KEEPS everything else: the grant documents stay so
-     * the audit trail still resolves and so the user's connected apps remain
-     * visible, and the audit rows stay because that is the record the operator
-     * called this to create. See `forget` above for the destructive twin.
-     */
-    async revokeAll(userId, opts = {}) {
-      const live = await ctx.models.Grant.find({ userId, revokedAt: null }).limit(MAX_LIST).lean();
-      const { grantsRevoked } = await revokeGrantsMatching(ctx, { userId }, "system");
-      const tokensRevoked = await revokeTokensMatching(ctx, { userId });
-      await ctx.models.Code.deleteMany({ userId });
-      await ctx.models.Request.deleteMany({ userId });
-      for (const grant of live) {
-        ctx.track({
-          type: "oauth.grant_revoked",
-          userId,
-          clientId: grant.clientId,
-          grantId: String(grant._id),
-          ...grant.contextId ? { contextId: grant.contextId } : {},
-          scopes: grant.scopes
-        });
-      }
-      await ctx.audit({
-        type: "oauth.user_access_revoked",
-        actor: "system",
-        userId,
-        meta: { grantsRevoked, tokensRevoked, ...opts.reason ? { reason: opts.reason } : {} }
-      });
-      return { grantsRevoked, tokensRevoked };
+async function resolveCimdClient(ctx, clientId) {
+  const url = assertFetchableUrl(ctx, clientId);
+  const existing = await ctx.models.Client.findOne({ clientId }).exec();
+  if (existing) {
+    if (existing.status !== "active") {
+      throw refuse(`client '${clientId}' is disabled`);
     }
-  };
-}
-function createContextsApi(ctx) {
-  return {
-    /**
-     * A grant made as an employee has to die when the employment does.
-     *
-     * `grantContext.verify()` catches this on the next refresh, but an access
-     * token already issued is valid for its full hour and nothing re-checks it.
-     * This is the push half of that pair, and it is why the adapter has an
-     * outbound direction at all.
-     */
-    async revoked(userId, contextId) {
-      const live = await ctx.models.Grant.find({ userId, contextId, revokedAt: null }).limit(MAX_LIST).lean();
-      const { grantsRevoked } = await revokeGrantsMatching(ctx, { userId, contextId }, "system");
-      const tokensRevoked = await revokeTokensMatching(ctx, { userId, contextId });
-      await ctx.models.Code.deleteMany({ userId, contextId });
-      for (const grant of live) {
-        ctx.track({
-          type: "oauth.grant_revoked",
-          userId,
-          clientId: grant.clientId,
-          grantId: String(grant._id),
-          contextId,
-          scopes: grant.scopes
-        });
-        await ctx.audit({
-          type: "oauth.grant_revoked",
-          actor: "system",
-          clientId: grant.clientId,
-          userId,
-          grantId: grant._id,
-          meta: { contextId, reason: "context_membership_ended" }
-        });
+    if (existing.registration !== "cimd") return existing;
+    if (isFresh(ctx, existing)) return existing;
+  }
+  const remembered = rememberedFailure(ctx, url.href);
+  if (remembered) throw refuse(remembered);
+  try {
+    const { document, etag } = await fetchMetadata(ctx, url, existing?.metadataEtag);
+    if (!document) {
+      if (existing) {
+        existing.metadataFetchedAt = /* @__PURE__ */ new Date();
+        await existing.save();
+        return existing;
       }
-      return { grantsRevoked, tokensRevoked };
+      throw refuse("client_id metadata returned 304 with nothing cached to answer from");
     }
-  };
+    const registration = validateMetadataDocument(ctx, url, document);
+    const client = await persist(ctx, clientId, url, registration, etag);
+    ctx.logger.debug?.({ clientId }, "oauth-host: client_id metadata document resolved");
+    return client;
+  } catch (err) {
+    const message = err instanceof UnredirectableError ? err.description ?? "client_id metadata could not be resolved" : "client_id metadata could not be resolved";
+    rememberFailure(ctx, url.href, message);
+    ctx.logger.warn?.({ clientId, err }, "oauth-host: client_id metadata resolution failed");
+    throw err instanceof UnredirectableError ? err : refuse(message);
+  }
 }
 
-// src/server/services/cimd.ts
-var NEGATIVE_TTL_MS = 6e4;
-var MAX_REMEMBERED_FAILURES = 1e3;
-function refuse(description) {
-  return new UnredirectableError("invalid_client", description);
+// src/server/services/admin.ts
+var MAX_LIST = 200;
+var DEFAULT_LIST = 50;
+function clampLimit(requested) {
+  const n = typeof requested === "number" && Number.isFinite(requested) ? Math.floor(requested) : DEFAULT_LIST;
+  if (n < 1) return 1;
+  return Math.min(n, MAX_LIST);
 }
-function isMetadataUrl(clientId) {
-  return /^https:\/\//i.test(clientId);
+function clampSkip(requested) {
+  const n = typeof requested === "number" && Number.isFinite(requested) ? Math.floor(requested) : 0;
+  return n > 0 ? n : 0;
 }
-function hostAllowed(rules, url) {
-  const hostname = url.hostname.toLowerCase();
-  return rules.some((rule) => {
-    if (url.port !== rule.port) return false;
-    if (hostname === rule.host) return true;
-    return rule.subdomains && hostname.endsWith(`.${rule.host}`);
-  });
+function notFound(clientId) {
+  return new Error(`oauth-host: no client registered with clientId '${clientId}'`);
 }
-function assertFetchableUrl(ctx, clientId) {
+function toPublicClient(doc) {
+  return {
+    clientId: doc.clientId,
+    name: doc.name,
+    type: doc.type,
+    // Defaulted rather than read straight through: rows written before the
+    // field existed have no value, and `undefined` here would read as "unknown
+    // provenance" on a client that plainly was registered by hand.
+    registration: doc.registration ?? "manual",
+    ...doc.metadataUrl ? { metadataUrl: doc.metadataUrl } : {},
+    trusted: Boolean(doc.trusted),
+    redirectUris: [...doc.redirectUris ?? []],
+    allowedScopes: [...doc.allowedScopes ?? []],
+    allowedResources: [...doc.allowedResources ?? []],
+    branding: { ...doc.branding ?? {} },
+    status: doc.status,
+    createdAt: doc.createdAt
+  };
+}
+function assertRedirectUri(value) {
+  if (typeof value !== "string" || !value) {
+    throw new TypeError(`oauth-host: every redirectUri must be a string (got ${JSON.stringify(value)})`);
+  }
   let url;
   try {
-    url = new URL(clientId);
+    url = new URL(value);
   } catch {
-    throw refuse(`client_id is not a valid URL: '${clientId}'`);
-  }
-  if (url.protocol !== "https:") {
-    throw refuse(`client_id metadata must be served over https (got '${url.protocol}')`);
+    throw new TypeError(`oauth-host: redirectUri must be an absolute URI: '${value}'`);
   }
-  if (url.username || url.password) {
-    throw refuse("client_id must not contain URL credentials");
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new TypeError(
+      `oauth-host: redirectUri must be https (http is allowed only on localhost/127.0.0.1): '${value}'`
+    );
   }
   if (url.hash) {
-    throw refuse("client_id must not contain a fragment");
+    throw new TypeError(`oauth-host: redirectUri must not contain a fragment: '${value}'`);
   }
-  if (!hostAllowed(ctx.cimd.allowedHosts, url)) {
-    throw refuse(`client_id host '${url.host}' is not in clientIdMetadata.allowedHosts`);
+  return value;
+}
+function assertRedirectUris2(input) {
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new TypeError("oauth-host: a client needs at least one redirectUri");
   }
-  return url;
+  return input.map(assertRedirectUri);
 }
-var JSON_CONTENT_TYPE = /^application\/(?:[\w.+-]+\+)?json\s*(?:;|$)/i;
-async function readCapped(res, maxBytes) {
-  const body = res.body;
-  if (!body) throw refuse("client_id metadata document was empty");
-  const reader = body.getReader();
-  const chunks = [];
-  let total = 0;
-  for (; ; ) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (!value) continue;
-    total += value.byteLength;
-    if (total > maxBytes) {
-      void reader.cancel();
-      throw refuse(`client_id metadata document exceeds ${maxBytes} bytes`);
+function assertScopes(ctx, input) {
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new TypeError("oauth-host: a client needs at least one entry in allowedScopes");
+  }
+  for (const id of input) {
+    if (typeof id !== "string" || !ctx.scopeIndex.has(id)) {
+      throw new TypeError(
+        `oauth-host: allowedScopes contains '${String(id)}', which is not in the configured scope catalog`
+      );
     }
-    chunks.push(Buffer.from(value));
   }
-  return Buffer.concat(chunks).toString("utf8");
+  return [...input];
 }
-async function fetchMetadata(ctx, url, etag) {
-  let res;
-  try {
-    res = await fetch(url.toString(), {
-      method: "GET",
-      // The single most important line in this file. A 3xx is a failure below,
-      // not a hop: following redirects would let an allowlisted host forward us
-      // to any address it likes, allowlist intact.
-      redirect: "manual",
-      headers: {
-        accept: "application/json",
-        ...etag ? { "if-none-match": etag } : {}
-      },
-      signal: AbortSignal.timeout(ctx.cimd.fetchTimeoutMs)
-    });
-  } catch (err) {
-    const name = err?.name;
-    if (name === "TimeoutError" || name === "AbortError") {
-      throw refuse(`client_id metadata fetch timed out after ${ctx.cimd.fetchTimeoutMs}ms`);
+function assertResources(ctx, input) {
+  const declared = new Set(ctx.resources.map((r) => r.id));
+  if (input === void 0) return ctx.resources.map((r) => r.id);
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new TypeError("oauth-host: allowedResources, when given, must list at least one resource");
+  }
+  for (const id of input) {
+    if (typeof id !== "string" || !declared.has(id)) {
+      throw new TypeError(
+        `oauth-host: allowedResources contains '${String(id)}', which is not a configured resource`
+      );
     }
-    throw refuse(`client_id metadata could not be fetched: ${err?.message ?? "network error"}`);
   }
-  if (res.status === 304) return { document: null };
-  if (res.status >= 300 && res.status < 400) {
-    throw refuse(
-      `client_id metadata returned a ${res.status} redirect, which is not followed \u2014 serve the document at the client_id URL itself`
+  return [...input];
+}
+function assertClientType(value) {
+  if (value === void 0) return "confidential";
+  if (value !== "confidential" && value !== "public") {
+    throw new TypeError(
+      `oauth-host: client type must be 'confidential' or 'public' (got ${JSON.stringify(value)})`
     );
   }
-  if (res.status !== 200) {
-    throw refuse(`client_id metadata returned HTTP ${res.status}`);
+  return value;
+}
+function assertName(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError("oauth-host: a client needs a non-empty `name` \u2014 it is what the consent screen shows");
   }
-  const contentType = res.headers.get("content-type") ?? "";
-  if (!JSON_CONTENT_TYPE.test(contentType)) {
-    throw refuse(`client_id metadata must be JSON (got content-type '${contentType || "none"}')`);
+  return value.trim();
+}
+async function revokeGrantsMatching(ctx, filter, by) {
+  const res = await ctx.models.Grant.updateMany(
+    { ...filter, revokedAt: null },
+    { $set: { revokedAt: /* @__PURE__ */ new Date(), revokedBy: by } }
+  );
+  return { grantsRevoked: res.modifiedCount ?? 0 };
+}
+async function revokeTokensMatching(ctx, filter) {
+  const res = await ctx.models.Token.updateMany(
+    { ...filter, revokedAt: null },
+    { $set: { revokedAt: /* @__PURE__ */ new Date() } }
+  );
+  return res.modifiedCount ?? 0;
+}
+function createClientsApi(ctx) {
+  async function create(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new TypeError("oauth-host: clients.create(spec) requires a spec object");
+    }
+    const name = assertName(spec.name);
+    const type = assertClientType(spec.type);
+    const redirectUris = assertRedirectUris2(spec.redirectUris);
+    const allowedScopes = assertScopes(ctx, spec.allowedScopes);
+    const allowedResources = assertResources(ctx, spec.allowedResources);
+    const clientId = spec.clientId ?? generateClientId();
+    const clientSecret = type === "confidential" ? generateClientSecret() : void 0;
+    const doc = await ctx.models.Client.create({
+      clientId,
+      name,
+      type,
+      registration: "manual",
+      trusted: Boolean(spec.trusted),
+      // Only the digest is stored. `clientSecret` below is the only time the
+      // raw value exists outside the caller's variable. Empty for a public
+      // client, which is the same shape a CIMD row is written with.
+      secrets: clientSecret ? [{ hash: sha256(clientSecret), label: "initial", createdAt: /* @__PURE__ */ new Date() }] : [],
+      redirectUris,
+      allowedScopes,
+      allowedResources,
+      branding: spec.branding ?? {},
+      status: "active"
+    });
+    await ctx.audit({ type: "oauth.client_created", actor: "admin", clientId, meta: { type } });
+    return clientSecret ? { client: toPublicClient(doc), clientId, type: "confidential", clientSecret } : { client: toPublicClient(doc), clientId, type: "public" };
   }
-  const text = await readCapped(res, ctx.cimd.maxBytes);
-  let parsed;
+  return {
+    create,
+    async rotateSecret(clientId, opts = {}) {
+      const doc = await ctx.models.Client.findOne({ clientId });
+      if (!doc) throw notFound(clientId);
+      if (doc.type === "public") {
+        throw new Error(
+          `oauth-host: client '${clientId}' is a public client and has no secret to rotate. Public clients authenticate with client_id and PKCE.`
+        );
+      }
+      const retireAfter = typeof opts.retireAfter === "number" && opts.retireAfter > 0 ? opts.retireAfter : 0;
+      const retiresAt = new Date(Date.now() + retireAfter);
+      for (const record of doc.secrets) {
+        record.retiresAt = record.retiresAt && record.retiresAt < retiresAt ? record.retiresAt : retiresAt;
+      }
+      const clientSecret = generateClientSecret();
+      doc.secrets.push({
+        hash: sha256(clientSecret),
+        label: opts.label ?? `rotated-${(/* @__PURE__ */ new Date()).toISOString()}`,
+        createdAt: /* @__PURE__ */ new Date()
+      });
+      doc.markModified("secrets");
+      await doc.save();
+      ctx.track({ type: "oauth.client_secret_rotated", clientId });
+      await ctx.audit({
+        type: "oauth.client_secret_rotated",
+        actor: "admin",
+        clientId,
+        meta: { retireAfter, retiresAt }
+      });
+      return { client: toPublicClient(doc), clientId, type: "confidential", clientSecret };
+    },
+    async update(clientId, patch) {
+      const doc = await ctx.models.Client.findOne({ clientId });
+      if (!doc) throw notFound(clientId);
+      if (patch.name !== void 0) doc.name = assertName(patch.name);
+      if (patch.redirectUris !== void 0) doc.redirectUris = assertRedirectUris2(patch.redirectUris);
+      if (patch.allowedScopes !== void 0) doc.allowedScopes = assertScopes(ctx, patch.allowedScopes);
+      if (patch.allowedResources !== void 0) {
+        doc.allowedResources = assertResources(ctx, patch.allowedResources);
+      }
+      if (patch.branding !== void 0) doc.branding = patch.branding;
+      if (patch.trusted !== void 0) doc.trusted = Boolean(patch.trusted);
+      await doc.save();
+      await ctx.audit({ type: "oauth.client_updated", actor: "admin", clientId });
+      return toPublicClient(doc);
+    },
+    async list(query = {}) {
+      const limit = clampLimit(query.limit);
+      const skip = clampSkip(query.skip);
+      const filter = {};
+      if (query.status) filter.status = query.status;
+      const docs = await ctx.models.Client.find(filter).sort({ createdAt: -1 }).skip(skip).limit(limit).lean();
+      return { items: docs.map(toPublicClient), limit };
+    },
+    async get(clientId) {
+      const doc = await ctx.models.Client.findOne({ clientId }).lean();
+      return doc ? toPublicClient(doc) : null;
+    },
+    async disable(clientId) {
+      const doc = await ctx.models.Client.findOne({ clientId });
+      if (!doc) throw notFound(clientId);
+      doc.status = "disabled";
+      await doc.save();
+      const { grantsRevoked } = await revokeGrantsMatching(ctx, { clientId }, "admin");
+      const tokensRevoked = await revokeTokensMatching(ctx, { clientId });
+      await ctx.models.Code.deleteMany({ clientId });
+      await ctx.models.Request.deleteMany({ clientId });
+      await ctx.audit({
+        type: "oauth.client_disabled",
+        actor: "admin",
+        clientId,
+        meta: { grantsRevoked, tokensRevoked }
+      });
+      return { grantsRevoked, tokensRevoked };
+    }
+  };
+}
+function formUrlDecode(value) {
   try {
-    parsed = JSON.parse(text);
+    return decodeURIComponent(value.replace(/\+/g, " "));
   } catch {
-    throw refuse("client_id metadata document is not valid JSON");
+    return value;
   }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw refuse("client_id metadata document must be a JSON object");
+}
+function readCredentials(req) {
+  const header = req.headers?.authorization;
+  if (typeof header === "string" && /^Basic /i.test(header)) {
+    const decoded = Buffer.from(header.slice(6).trim(), "base64").toString("utf8");
+    const sep = decoded.indexOf(":");
+    const clientId = formUrlDecode(sep < 0 ? decoded : decoded.slice(0, sep));
+    const secret = sep < 0 ? "" : formUrlDecode(decoded.slice(sep + 1));
+    return { clientId, clientSecret: secret === "" ? null : secret, viaBasic: true };
   }
-  return {
-    document: parsed,
-    ...res.headers.get("etag") ? { etag: res.headers.get("etag") } : {}
-  };
+  const body = req.body ?? {};
+  if (typeof body.client_id === "string" && body.client_id) {
+    return {
+      clientId: body.client_id,
+      clientSecret: typeof body.client_secret === "string" && body.client_secret ? body.client_secret : null,
+      viaBasic: false
+    };
+  }
+  return null;
 }
-function requireString(doc, field) {
-  const value = doc[field];
-  if (typeof value !== "string" || !value.trim()) {
-    throw refuse(`client_id metadata field '${field}' must be a non-empty string`);
+function authFailure(viaBasic) {
+  return new OAuthError(401, "invalid_client", "client authentication failed", {
+    // RFC 6749 §5.2 — a 401 answering a Basic credential MUST carry the challenge.
+    headers: viaBasic ? { "WWW-Authenticate": 'Basic realm="oauth", charset="UTF-8"' } : {}
+  });
+}
+var CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+var MAX_ASSERTION_BYTES = 8192;
+var COMPACT_JWS_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+var ASSERTION_ALGORITHMS = ["RS256", "ES256"];
+var MAX_ASSERTION_AGE_S = 3600;
+var MAX_JTI_LEN = 256;
+var REPLAY_CACHE_MAX = 1e4;
+var JWKS_CACHE_MAX = 100;
+var JWKS_FORCE_REFETCH_INTERVAL_MS = 6e4;
+var ASSERTION_CLOCK_TOLERANCE_S = 60;
+function tokenEndpointUrl(ctx) {
+  return `${ctx.issuer}${ctx.mountPath}/token`;
+}
+function isJwkSet(doc) {
+  return Boolean(doc) && typeof doc === "object" && Array.isArray(doc.keys);
+}
+function assertionFailure(reason) {
+  return new Error(reason);
+}
+function selectCandidateKeys(keys, header) {
+  return keys.filter((key) => {
+    if (header.kid !== void 0 && key.kid !== header.kid) return false;
+    const use = key.use;
+    if (use !== void 0 && use !== "sig") return false;
+    const alg = key.alg;
+    if (alg !== void 0 && alg !== header.alg) return false;
+    return true;
+  });
+}
+async function resolveJwksKeys(ctx, jwksUri, forceRefetch) {
+  const { jwksCache, jwksForceRefetchAt } = ctx.cimd;
+  const now = Date.now();
+  const cached = jwksCache.get(jwksUri);
+  const fresh = cached !== void 0 && now - cached.fetchedAt < ctx.cimd.cacheTtlMs;
+  if (fresh && !forceRefetch) return cached.keys;
+  if (forceRefetch) {
+    const lastForced = jwksForceRefetchAt.get(jwksUri) ?? 0;
+    if (now - lastForced < JWKS_FORCE_REFETCH_INTERVAL_MS) {
+      return cached?.keys ?? [];
+    }
+    jwksForceRefetchAt.set(jwksUri, now);
   }
-  return value.trim();
+  const doc = await fetchJwks(ctx, jwksUri);
+  if (!isJwkSet(doc)) throw assertionFailure(`jwks_uri '${jwksUri}' did not serve a JWK Set`);
+  if (!jwksCache.has(jwksUri) && jwksCache.size >= JWKS_CACHE_MAX) {
+    const oldest = jwksCache.keys().next();
+    if (!oldest.done) jwksCache.delete(oldest.value);
+  }
+  jwksCache.set(jwksUri, { keys: doc.keys, fetchedAt: now });
+  return doc.keys;
 }
-function optionalHttpsUri(doc, field) {
-  const value = doc[field];
-  if (value === void 0 || value === null) return void 0;
-  if (typeof value !== "string" || !value.trim()) {
-    throw refuse(`client_id metadata field '${field}' must be a string`);
+async function loadClientJwks(ctx, client) {
+  if (client.jwks !== void 0 && client.jwks !== null) {
+    if (!isJwkSet(client.jwks)) {
+      throw assertionFailure(`client '${client.clientId}' has a malformed stored 'jwks'`);
+    }
+    return client.jwks.keys;
   }
-  let url;
+  if (client.jwksUri) {
+    return resolveJwksKeys(ctx, client.jwksUri, false);
+  }
+  throw assertionFailure(`client '${client.clientId}' has neither 'jwks' nor 'jwksUri' stored`);
+}
+async function verifyClientAssertion(ctx, body) {
+  if (body.client_assertion_type !== CLIENT_ASSERTION_TYPE) {
+    throw assertionFailure(
+      `client_assertion_type must be '${CLIENT_ASSERTION_TYPE}' (got ${JSON.stringify(body.client_assertion_type)})`
+    );
+  }
+  const assertion = body.client_assertion;
+  if (typeof assertion !== "string" || !assertion || Buffer.byteLength(assertion, "utf8") > MAX_ASSERTION_BYTES || !COMPACT_JWS_RE.test(assertion)) {
+    throw assertionFailure("client_assertion is not a well-formed compact JWS");
+  }
+  if (typeof body.client_secret === "string" && body.client_secret) {
+    throw assertionFailure("client_assertion was presented alongside a client_secret");
+  }
+  let unverified;
   try {
-    url = new URL(value);
+    unverified = jose.decodeJwt(assertion);
   } catch {
-    throw refuse(`client_id metadata field '${field}' must be an absolute URL: '${value}'`);
+    throw assertionFailure("client_assertion could not be decoded");
   }
-  if (url.protocol !== "https:") {
-    throw refuse(`client_id metadata field '${field}' must be https (got '${url.protocol}')`);
+  const iss = unverified.iss;
+  if (typeof iss !== "string" || !iss) {
+    throw assertionFailure("client_assertion is missing iss");
   }
-  return value;
-}
-function assertRedirectUris2(doc) {
-  const value = doc.redirect_uris;
-  if (!Array.isArray(value) || value.length === 0) {
-    throw refuse("client_id metadata field 'redirect_uris' must be a non-empty array");
+  if (typeof body.client_id === "string" && body.client_id && body.client_id !== iss) {
+    throw assertionFailure("client_assertion iss does not match client_id");
   }
-  return value.map((entry) => {
-    if (typeof entry !== "string" || !entry) {
-      throw refuse(`client_id metadata 'redirect_uris' entries must be strings (got ${JSON.stringify(entry)})`);
-    }
-    let url;
-    try {
-      url = new URL(entry);
-    } catch {
-      throw refuse(`client_id metadata 'redirect_uris' entry must be an absolute URI: '${entry}'`);
-    }
-    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
-    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
-      throw refuse(
-        `client_id metadata 'redirect_uris' entry must be https (http is allowed only on localhost/127.0.0.1): '${entry}'`
-      );
-    }
-    if (url.hash) {
-      throw refuse(`client_id metadata 'redirect_uris' entry must not contain a fragment: '${entry}'`);
-    }
-    return entry;
-  });
-}
-function validateMetadataDocument(ctx, url, doc) {
-  const declared = requireString(doc, "client_id");
-  let declaredUrl;
+  const client = await ctx.models.Client.findOne({ clientId: iss });
+  if (!client || client.status !== "active" || !client.tokenEndpointAuthMethods?.includes("private_key_jwt")) {
+    throw assertionFailure(`client '${iss}' does not support private_key_jwt`);
+  }
+  let header;
   try {
-    declaredUrl = new URL(declared);
+    header = jose.decodeProtectedHeader(assertion);
   } catch {
-    throw refuse(`client_id metadata field 'client_id' is not a URL: '${declared}'`);
+    throw assertionFailure("client_assertion header could not be decoded");
   }
-  if (declaredUrl.href !== url.href) {
-    throw refuse(
-      `client_id metadata field 'client_id' is '${declared}', which is not the URL it was fetched from ('${url.href}')`
-    );
+  const alg = header.alg;
+  if (alg !== "RS256" && alg !== "ES256") {
+    throw assertionFailure(`client_assertion alg '${String(alg)}' is not permitted`);
   }
-  const method = doc.token_endpoint_auth_method;
-  if (method !== void 0 && method !== "none") {
-    throw refuse(
-      `client_id metadata field 'token_endpoint_auth_method' must be 'none' (got ${JSON.stringify(method)}) \u2014 a CIMD client holds no secret`
-    );
+  const stored = await loadClientJwks(ctx, client);
+  let candidates = selectCandidateKeys(stored, { alg, kid: header.kid });
+  if (candidates.length === 0 && client.jwksUri) {
+    const refetched = await resolveJwksKeys(ctx, client.jwksUri, true);
+    candidates = selectCandidateKeys(refetched, { alg, kid: header.kid });
   }
-  const name = requireString(doc, "client_name");
-  const redirectUris = assertRedirectUris2(doc);
-  const permitted = new Set(ctx.cimd.allowedScopes.filter((id) => ctx.scopeIndex.has(id)));
-  let allowedScopes;
-  if (doc.scope === void 0 || doc.scope === null) {
-    allowedScopes = [...permitted];
-  } else {
-    if (typeof doc.scope !== "string") {
-      throw refuse("client_id metadata field 'scope' must be a space-delimited string");
+  if (candidates.length === 0) {
+    throw assertionFailure(`no candidate key for kid '${String(header.kid)}'`);
+  }
+  const tokenEndpoint = tokenEndpointUrl(ctx);
+  let verified;
+  let lastJoseError;
+  for (const jwk of candidates) {
+    try {
+      const key = await jose.importJWK(jwk, alg);
+      verified = await jose.jwtVerify(assertion, key, {
+        // Passed explicitly rather than trusting the header a second time —
+        // this is the actual alg-confusion guard, not the earlier check,
+        // which only short-circuits the common case before a fetch.
+        algorithms: [...ASSERTION_ALGORITHMS],
+        audience: [tokenEndpoint, ctx.issuer],
+        clockTolerance: ASSERTION_CLOCK_TOLERANCE_S
+      });
+      break;
+    } catch (err) {
+      lastJoseError = err;
     }
-    const requested = new Set(doc.scope.split(/\s+/).filter(Boolean));
-    allowedScopes = [...permitted].filter((id) => requested.has(id));
   }
-  if (allowedScopes.length === 0) {
-    throw refuse(
-      "client_id metadata field 'scope' has no overlap with what this server offers \u2014 there is nothing this client could be granted"
+  if (!verified) {
+    throw assertionFailure(
+      `client_assertion did not verify: ${lastJoseError instanceof Error ? lastJoseError.message : "unknown error"}`
     );
   }
-  const branding = {};
-  const logoUrl = optionalHttpsUri(doc, "logo_uri");
-  const homepageUrl = optionalHttpsUri(doc, "client_uri");
-  const tosUrl = optionalHttpsUri(doc, "tos_uri");
-  const privacyUrl = optionalHttpsUri(doc, "policy_uri");
-  if (logoUrl) branding.logoUrl = logoUrl;
-  if (homepageUrl) branding.homepageUrl = homepageUrl;
-  if (tosUrl) branding.tosUrl = tosUrl;
-  if (privacyUrl) branding.privacyUrl = privacyUrl;
-  return { name, redirectUris, allowedScopes, branding };
-}
-function rememberFailure(ctx, key, message) {
-  const { failures } = ctx.cimd;
-  if (failures.size >= MAX_REMEMBERED_FAILURES) {
-    const oldest = failures.keys().next();
-    if (!oldest.done) failures.delete(oldest.value);
+  const { payload } = verified;
+  if (payload.iss !== client.clientId || payload.sub !== client.clientId) {
+    throw assertionFailure("client_assertion iss/sub must both equal the client_id");
   }
-  failures.set(key, { until: Date.now() + NEGATIVE_TTL_MS, message });
-}
-function rememberedFailure(ctx, key) {
-  const found = ctx.cimd.failures.get(key);
-  if (!found) return null;
-  if (found.until <= Date.now()) {
-    ctx.cimd.failures.delete(key);
-    return null;
+  const exp = payload.exp;
+  const nowS = Math.floor(Date.now() / 1e3);
+  if (typeof exp !== "number" || exp - nowS > MAX_ASSERTION_AGE_S) {
+    throw assertionFailure("client_assertion exp is too far in the future");
   }
-  return found.message;
+  const jti = payload.jti;
+  if (typeof jti !== "string" || !jti || jti.length > MAX_JTI_LEN) {
+    throw assertionFailure("client_assertion is missing jti");
+  }
+  const replay = ctx.cimd.assertionReplay;
+  const replayKey = `${client.clientId}:${jti}`;
+  const existing = replay.get(replayKey);
+  if (existing !== void 0 && existing > Date.now()) {
+    ctx.logger.warn?.({ clientId: client.clientId }, "oauth-host: private_key_jwt assertion replay detected");
+    throw assertionFailure("client_assertion jti has already been used");
+  }
+  if (!replay.has(replayKey) && replay.size >= REPLAY_CACHE_MAX) {
+    const oldest = replay.keys().next();
+    if (!oldest.done) replay.delete(oldest.value);
+  }
+  replay.set(replayKey, (exp + 60) * 1e3);
+  return client;
 }
-function isFresh(ctx, client) {
-  const fetchedAt = client.metadataFetchedAt?.getTime();
-  if (fetchedAt === void 0) return false;
-  return Date.now() - fetchedAt < ctx.cimd.cacheTtlMs;
+async function authenticateClient(ctx, req) {
+  const body = req.body ?? {};
+  const header = req.headers?.authorization;
+  const viaBasic = typeof header === "string" && /^Basic /i.test(header);
+  if (body.client_assertion !== void 0 || body.client_assertion_type !== void 0) {
+    if (viaBasic) {
+      ctx.logger.debug?.(
+        "oauth-host: client_assertion presented alongside a Basic Authorization header"
+      );
+      throw authFailure(viaBasic);
+    }
+    try {
+      return await verifyClientAssertion(ctx, body);
+    } catch (err) {
+      ctx.logger.debug?.(
+        { err: err instanceof Error ? err.message : err },
+        "oauth-host: private_key_jwt assertion rejected"
+      );
+      throw authFailure(viaBasic);
+    }
+  }
+  const creds = readCredentials(req);
+  if (!creds || !creds.clientId) throw authFailure(Boolean(creds?.viaBasic));
+  const client = await ctx.models.Client.findOne({ clientId: creds.clientId });
+  if (!client || client.status !== "active") throw authFailure(creds.viaBasic);
+  if (client.type === "public") {
+    if (creds.clientSecret !== null) throw authFailure(creds.viaBasic);
+    return client;
+  }
+  if (creds.clientSecret === null) throw authFailure(creds.viaBasic);
+  const now = Date.now();
+  let matched;
+  for (const record of client.secrets) {
+    if (record.retiresAt && record.retiresAt.getTime() <= now) continue;
+    if (safeEqual(sha256(creds.clientSecret), record.hash)) matched = record;
+  }
+  if (!matched) throw authFailure(creds.viaBasic);
+  const usedAt = /* @__PURE__ */ new Date();
+  matched.lastUsedAt = usedAt;
+  await ctx.models.Client.updateOne(
+    { clientId: client.clientId, "secrets.hash": matched.hash },
+    { $set: { "secrets.$.lastUsedAt": usedAt } }
+  );
+  return client;
 }
-async function persist(ctx, clientId, url, registration, etag) {
-  const doc = await ctx.models.Client.findOneAndUpdate(
-    { clientId },
-    {
-      $set: {
-        name: registration.name,
-        redirectUris: registration.redirectUris,
-        allowedScopes: registration.allowedScopes,
-        // Every declared resource. A CIMD client cannot express an audience
-        // preference, and RFC 8707 validation at `/authorize` narrows it anyway.
-        allowedResources: ctx.resources.map((r) => r.id),
-        branding: registration.branding,
-        metadataUrl: url.href,
-        metadataFetchedAt: /* @__PURE__ */ new Date(),
-        ...etag ? { metadataEtag: etag } : {}
-      },
-      $setOnInsert: {
-        type: "public",
-        registration: "cimd",
-        trusted: false,
-        secrets: [],
-        status: "active"
+function describeGrantScopes(ctx, ids) {
+  return ids.map((id) => ctx.scopeIndex.get(id) ?? { id, label: id });
+}
+function createGrantsApi(ctx) {
+  return {
+    async list(query) {
+      const limit = clampLimit(query?.limit);
+      const skip = clampSkip(query?.skip);
+      const filter = { revokedAt: null };
+      if (query?.userId !== void 0) filter.userId = query.userId;
+      if (query?.clientId !== void 0) filter.clientId = query.clientId;
+      const grants = await ctx.models.Grant.find(filter).sort({ createdAt: -1 }).skip(skip).limit(limit).lean();
+      if (grants.length === 0) return { items: [], limit };
+      const clientIds = [...new Set(grants.map((g) => g.clientId))];
+      const clients = await ctx.models.Client.find({ clientId: { $in: clientIds } }).lean();
+      const byId = new Map(clients.map((c) => [c.clientId, toPublicClient(c)]));
+      const contextCache = /* @__PURE__ */ new Map();
+      const items = [];
+      for (const grant of grants) {
+        const client = byId.get(grant.clientId);
+        const summary = {
+          id: String(grant._id),
+          client: client ? { clientId: client.clientId, name: client.name, branding: client.branding } : { clientId: grant.clientId, name: grant.clientId, branding: {} },
+          scopes: describeGrantScopes(ctx, grant.scopes ?? []),
+          createdAt: grant.createdAt,
+          ...grant.lastUsedAt ? { lastUsedAt: grant.lastUsedAt } : {}
+        };
+        if (ctx.grantContext && grant.contextId) {
+          const cacheKey = `${String(grant.userId)}:${grant.clientId}`;
+          let available = contextCache.get(cacheKey);
+          if (!available) {
+            const user = { id: grant.userId };
+            available = client ? await ctx.grantContext.list(user, { client, scopes: grant.scopes ?? [] }) : [];
+            contextCache.set(cacheKey, available);
+          }
+          summary.context = available.find((c) => c.id === grant.contextId) ?? { id: grant.contextId, label: grant.contextId };
+        }
+        items.push(summary);
       }
+      return { items, limit };
     },
-    { upsert: true, returnDocument: "after", setDefaultsOnInsert: false }
-  ).exec();
-  return doc;
+    async revoke(grantId, opts = {}) {
+      const by = opts.by ?? "admin";
+      const grant = await ctx.models.Grant.findById(grantId).catch(() => null);
+      if (!grant) return { tokensRevoked: 0 };
+      const alreadyRevoked = Boolean(grant.revokedAt);
+      if (!alreadyRevoked) {
+        grant.revokedAt = /* @__PURE__ */ new Date();
+        grant.revokedBy = by;
+        await grant.save();
+      }
+      const tokensRevoked = await revokeTokensMatching(ctx, { grantId: grant._id });
+      if (!alreadyRevoked) {
+        ctx.track({
+          type: "oauth.grant_revoked",
+          userId: grant.userId,
+          clientId: grant.clientId,
+          grantId: String(grant._id),
+          ...grant.contextId ? { contextId: grant.contextId } : {},
+          scopes: grant.scopes
+        });
+        await ctx.audit({
+          type: "oauth.grant_revoked",
+          actor: by,
+          clientId: grant.clientId,
+          userId: grant.userId,
+          grantId: grant._id,
+          meta: { tokensRevoked }
+        });
+      }
+      return { tokensRevoked };
+    }
+  };
 }
-async function resolveCimdClient(ctx, clientId) {
-  const url = assertFetchableUrl(ctx, clientId);
-  const existing = await ctx.models.Client.findOne({ clientId }).exec();
-  if (existing) {
-    if (existing.status !== "active") {
-      throw refuse(`client '${clientId}' is disabled`);
+function pairwiseKey(userId) {
+  const key = String(userId);
+  if (!key || key.includes(".") || key.startsWith("$")) return null;
+  return key;
+}
+function createUsersApi(ctx) {
+  return {
+    /**
+     * Erasure. The user is gone and every trace of them has to go with them.
+     *
+     * This is the destructive twin of `revokeAll`, and the difference is the
+     * whole reason both exist: `forget` DELETES the grant documents and the
+     * user's audit rows, `revokeAll` keeps both. A password change must leave a
+     * history an operator can read; a deletion request must not.
+     *
+     * Idempotent — it will be called twice, by a retry or by a host that wires
+     * it to both a soft-delete and a hard-delete hook.
+     */
+    async forget(userId) {
+      const grantsResult = await ctx.models.Grant.deleteMany({ userId });
+      const tokensResult = await ctx.models.Token.deleteMany({ userId });
+      await ctx.models.Code.deleteMany({ userId });
+      await ctx.models.Request.deleteMany({ userId });
+      const key = pairwiseKey(userId);
+      if (key) {
+        await ctx.models.Client.updateMany(
+          { [`pairwiseSubjects.${key}`]: { $exists: true } },
+          { $unset: { [`pairwiseSubjects.${key}`]: "" } }
+        );
+      }
+      await ctx.models.Audit.deleteMany({ userId });
+      const grants = grantsResult.deletedCount ?? 0;
+      const tokens = tokensResult.deletedCount ?? 0;
+      await ctx.audit({ type: "oauth.user_forgotten", actor: "system", meta: { grants, tokens } });
+      return { grants, tokens };
+    },
+    /**
+     * Password change, deactivation, suspected compromise.
+     *
+     * Kills live access and KEEPS everything else: the grant documents stay so
+     * the audit trail still resolves and so the user's connected apps remain
+     * visible, and the audit rows stay because that is the record the operator
+     * called this to create. See `forget` above for the destructive twin.
+     */
+    async revokeAll(userId, opts = {}) {
+      const live = await ctx.models.Grant.find({ userId, revokedAt: null }).limit(MAX_LIST).lean();
+      const { grantsRevoked } = await revokeGrantsMatching(ctx, { userId }, "system");
+      const tokensRevoked = await revokeTokensMatching(ctx, { userId });
+      await ctx.models.Code.deleteMany({ userId });
+      await ctx.models.Request.deleteMany({ userId });
+      for (const grant of live) {
+        ctx.track({
+          type: "oauth.grant_revoked",
+          userId,
+          clientId: grant.clientId,
+          grantId: String(grant._id),
+          ...grant.contextId ? { contextId: grant.contextId } : {},
+          scopes: grant.scopes
+        });
+      }
+      await ctx.audit({
+        type: "oauth.user_access_revoked",
+        actor: "system",
+        userId,
+        meta: { grantsRevoked, tokensRevoked, ...opts.reason ? { reason: opts.reason } : {} }
+      });
+      return { grantsRevoked, tokensRevoked };
     }
-    if (existing.registration !== "cimd") return existing;
-    if (isFresh(ctx, existing)) return existing;
-  }
-  const remembered = rememberedFailure(ctx, url.href);
-  if (remembered) throw refuse(remembered);
-  try {
-    const { document, etag } = await fetchMetadata(ctx, url, existing?.metadataEtag);
-    if (!document) {
-      if (existing) {
-        existing.metadataFetchedAt = /* @__PURE__ */ new Date();
-        await existing.save();
-        return existing;
+  };
+}
+function createContextsApi(ctx) {
+  return {
+    /**
+     * A grant made as an employee has to die when the employment does.
+     *
+     * `grantContext.verify()` catches this on the next refresh, but an access
+     * token already issued is valid for its full hour and nothing re-checks it.
+     * This is the push half of that pair, and it is why the adapter has an
+     * outbound direction at all.
+     */
+    async revoked(userId, contextId) {
+      const live = await ctx.models.Grant.find({ userId, contextId, revokedAt: null }).limit(MAX_LIST).lean();
+      const { grantsRevoked } = await revokeGrantsMatching(ctx, { userId, contextId }, "system");
+      const tokensRevoked = await revokeTokensMatching(ctx, { userId, contextId });
+      await ctx.models.Code.deleteMany({ userId, contextId });
+      for (const grant of live) {
+        ctx.track({
+          type: "oauth.grant_revoked",
+          userId,
+          clientId: grant.clientId,
+          grantId: String(grant._id),
+          contextId,
+          scopes: grant.scopes
+        });
+        await ctx.audit({
+          type: "oauth.grant_revoked",
+          actor: "system",
+          clientId: grant.clientId,
+          userId,
+          grantId: grant._id,
+          meta: { contextId, reason: "context_membership_ended" }
+        });
       }
-      throw refuse("client_id metadata returned 304 with nothing cached to answer from");
+      return { grantsRevoked, tokensRevoked };
     }
-    const registration = validateMetadataDocument(ctx, url, document);
-    const client = await persist(ctx, clientId, url, registration, etag);
-    ctx.logger.debug?.({ clientId }, "oauth-host: client_id metadata document resolved");
-    return client;
-  } catch (err) {
-    const message = err instanceof UnredirectableError ? err.description ?? "client_id metadata could not be resolved" : "client_id metadata could not be resolved";
-    rememberFailure(ctx, url.href, message);
-    ctx.logger.warn?.({ clientId, err }, "oauth-host: client_id metadata resolution failed");
-    throw err instanceof UnredirectableError ? err : refuse(message);
-  }
+  };
 }
 
 // src/server/services/scopes.ts