@_mustachio/openauth 0.9.2 → 0.11.0

package/dist/esm/domain/client-credentials.js

@@ -0,0 +1,91 @@
+// src/domain/client-credentials.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { verifyClientCredentials } from "./client-auth";
+import { randomId } from "./crypto";
+import { mintTokens } from "./token";
+async function clientCredentialsGrant(req, deps, tenantId) {
+  const tenantCfg = await deps.configStore.getTenantConfig(tenantId);
+  if (isErr(tenantCfg))
+    return err(tenantCfg.error);
+  const client = tenantCfg.value.clients.find((c) => c.id === req.clientId);
+  if (!client) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`));
+  }
+  if (client.type !== "confidential") {
+    return err(authError.invalidClient("client_credentials requires confidential client"));
+  }
+  if (!client.grantTypes.includes("client_credentials")) {
+    return err(authError.unauthorizedClient(`client "${client.id}" is not authorized for client_credentials`));
+  }
+  const authErr = await verifyClientCredentials(client, req.clientSecret);
+  if (authErr)
+    return err(authErr);
+  const requestedScopes = req.scope ? req.scope.split(" ").filter(Boolean) : client.scopes;
+  for (const s of requestedScopes) {
+    if (!client.scopes.includes(s)) {
+      return err(authError.invalidScope(`scope "${s}" not allowed for client`));
+    }
+  }
+  const m2mCfgs = tenantCfg.value.methods.filter((m) => m.type === "m2m" && m.enabled);
+  if (m2mCfgs.length === 0) {
+    return err(authError.methodNotFound("no enabled m2m method on tenant", {}));
+  }
+  if (m2mCfgs.length > 1) {
+    return err(authError.methodNotFound("multiple m2m methods configured — only one supported", {}));
+  }
+  const methodCfg = m2mCfgs[0];
+  const methodRes = await deps.methodCache.resolve(tenantCfg.value, methodCfg.id);
+  if (isErr(methodRes))
+    return err(methodRes.error);
+  const method = methodRes.value;
+  if (!method.client) {
+    return err(authError.methodNotFound(`m2m method "${methodCfg.id}" did not register a client fn`, { methodId: methodCfg.id, methodKind: method.kind }));
+  }
+  const clientResult = await method.client({
+    clientID: req.clientId,
+    clientSecret: req.clientSecret,
+    params: req.params ?? {}
+  });
+  if (isErr(clientResult))
+    return err(clientResult.error);
+  const tenant = {
+    id: tenantCfg.value.id,
+    config: tenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} }
+  };
+  let claim;
+  try {
+    claim = await deps.success({
+      tenant,
+      methodId: method.id,
+      methodKind: method.kind,
+      providerSubject: req.clientId,
+      properties: clientResult.value,
+      context: null
+    });
+  } catch (e) {
+    return err(authError.serverError("success callback threw", e));
+  }
+  const minted = await mintTokens({
+    tenant,
+    claim,
+    payload: {
+      tenantId: tenant.id,
+      clientId: client.id,
+      methodId: method.id,
+      methodKind: method.kind,
+      scopes: requestedScopes,
+      ...client.scopes.includes("audience") ? {} : {}
+    },
+    family: (deps.newRefreshFamily ?? randomId)(),
+    skipRefresh: true,
+    deps
+  });
+  if (isErr(minted))
+    return err(minted.error);
+  return ok(minted.value);
+}
+export {
+  clientCredentialsGrant
+};

package/dist/esm/domain/crypto.js

@@ -0,0 +1,97 @@
+// src/domain/crypto.ts
+import { base64url as joseB64u, CompactEncrypt, compactDecrypt } from "jose";
+function randomToken() {
+  const buf = new Uint8Array(32);
+  crypto.getRandomValues(buf);
+  return joseB64u.encode(buf);
+}
+function randomId() {
+  const buf = new Uint8Array(16);
+  crypto.getRandomValues(buf);
+  return joseB64u.encode(buf);
+}
+function randomHex(bytes) {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function randomBytes(bytes) {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  return buf;
+}
+var base64url = {
+  encode: (data) => joseB64u.encode(data),
+  decode: (s) => joseB64u.decode(s)
+};
+var utf8 = {
+  encode: (s) => new TextEncoder().encode(s),
+  decode: (b) => new TextDecoder().decode(b)
+};
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0;i < a.length; i++)
+    diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+function timingSafeEqualStr(a, b) {
+  return timingSafeEqual(utf8.encode(a), utf8.encode(b));
+}
+async function sha256(data) {
+  const bytes = typeof data === "string" ? utf8.encode(data) : data;
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return new Uint8Array(digest);
+}
+async function importHmacKey(raw, usage = ["sign", "verify"]) {
+  return crypto.subtle.importKey("raw", raw, { name: "HMAC", hash: "SHA-256" }, false, [...usage]);
+}
+async function hmacSign(key, message) {
+  const sig = await crypto.subtle.sign("HMAC", key, message);
+  return new Uint8Array(sig);
+}
+async function hmacVerify(key, signature, message) {
+  return crypto.subtle.verify("HMAC", key, signature, message);
+}
+async function encryptPayload(payload, kid, keyBytes) {
+  if (keyBytes.byteLength !== 32) {
+    throw new Error(`encryptPayload: keyBytes must be 32 bytes (A256GCM); got ${keyBytes.byteLength}`);
+  }
+  const cek = await crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM", length: 256 }, false, ["encrypt"]);
+  const json = utf8.encode(JSON.stringify(payload));
+  return new CompactEncrypt(json).setProtectedHeader({ alg: "dir", enc: "A256GCM", kid }).encrypt(cek);
+}
+async function decryptPayload(jwe, resolveKey) {
+  const { plaintext } = await compactDecrypt(jwe, async (header) => {
+    const kid = header.kid;
+    if (typeof kid !== "string") {
+      throw new Error("decryptPayload: missing kid in JWE header");
+    }
+    const raw = await resolveKey(kid);
+    return crypto.subtle.importKey("raw", raw, { name: "AES-GCM", length: 256 }, false, ["decrypt"]);
+  });
+  return JSON.parse(utf8.decode(plaintext));
+}
+function generateSymmetricKey() {
+  const buf = new Uint8Array(32);
+  crypto.getRandomValues(buf);
+  return buf;
+}
+export {
+  utf8,
+  timingSafeEqualStr,
+  timingSafeEqual,
+  sha256,
+  randomToken,
+  randomId,
+  randomHex,
+  randomBytes,
+  importHmacKey,
+  hmacVerify,
+  hmacSign,
+  generateSymmetricKey,
+  encryptPayload,
+  decryptPayload,
+  base64url
+};

package/dist/esm/domain/discovery.js

@@ -0,0 +1,83 @@
+// src/domain/discovery.ts
+import { err, isErr, ok } from "../types/result";
+import { buildJwksDocument } from "./jwt";
+function buildDiscoveryDocument(deps) {
+  const base = deps.issuerUrl.replace(/\/+$/, "");
+  const p = deps.paths ?? {};
+  const customScopeKeys = Object.keys(deps.customScopeClaims ?? {});
+  const customClaimNames = new Set;
+  for (const list of Object.values(deps.customScopeClaims ?? {})) {
+    for (const name of list)
+      customClaimNames.add(name);
+  }
+  return {
+    issuer: deps.issuerUrl,
+    authorization_endpoint: `${base}${p.authorize ?? "/authorize"}`,
+    token_endpoint: `${base}${p.token ?? "/token"}`,
+    userinfo_endpoint: `${base}${p.userinfo ?? "/userinfo"}`,
+    jwks_uri: `${base}${p.jwks ?? "/.well-known/jwks.json"}`,
+    revocation_endpoint: `${base}${p.revoke ?? "/revoke"}`,
+    introspection_endpoint: `${base}${p.introspect ?? "/introspect"}`,
+    end_session_endpoint: `${base}${p.endSession ?? "/end_session"}`,
+    registration_endpoint: `${base}${p.register ?? "/register"}`,
+    pushed_authorization_request_endpoint: `${base}${p.par ?? "/par"}`,
+    require_pushed_authorization_requests: false,
+    dpop_signing_alg_values_supported: ["ES256", "EdDSA"],
+    response_types_supported: ["code"],
+    grant_types_supported: [
+      "authorization_code",
+      "refresh_token",
+      "client_credentials"
+    ],
+    subject_types_supported: ["public", "pairwise"],
+    id_token_signing_alg_values_supported: ["ES256", "EdDSA"],
+    scopes_supported: [
+      ...deps.scopes ?? ["openid", "email", "profile"],
+      ...customScopeKeys
+    ],
+    claims_supported: [
+      "sub",
+      "iss",
+      "aud",
+      "exp",
+      "iat",
+      "auth_time",
+      "nonce",
+      "amr",
+      "at_hash",
+      "email",
+      "email_verified",
+      "name",
+      "given_name",
+      "family_name",
+      "preferred_username",
+      "picture",
+      "locale",
+      "phone_number",
+      "phone_number_verified",
+      "address",
+      ...customClaimNames
+    ],
+    claims_parameter_supported: true,
+    request_parameter_supported: false,
+    request_uri_parameter_supported: false,
+    require_request_uri_registration: false,
+    ui_locales_supported: deps.uiLocales ?? ["en"],
+    token_endpoint_auth_methods_supported: [
+      "client_secret_basic",
+      "client_secret_post",
+      "none"
+    ],
+    code_challenge_methods_supported: ["S256"]
+  };
+}
+async function buildJwks(keyStore) {
+  const res = await keyStore.signingKeys();
+  if (isErr(res))
+    return err(res.error);
+  return ok(buildJwksDocument(res.value));
+}
+export {
+  buildJwks,
+  buildDiscoveryDocument
+};

package/dist/esm/domain/dpop.js

@@ -0,0 +1,122 @@
+// src/domain/dpop.ts
+import {
+  calculateJwkThumbprint,
+  decodeProtectedHeader,
+  importJWK,
+  jwtVerify
+} from "jose";
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { base64url, sha256, utf8 } from "./crypto";
+var DPOP_ASYMMETRIC_ALGS = new Set(["ES256", "EdDSA"]);
+var DEFAULT_DPOP_IAT_TOLERANCE_SEC = 60;
+var DEFAULT_DPOP_JTI_TTL_MS = 2 * DEFAULT_DPOP_IAT_TOLERANCE_SEC * 1000;
+async function verifyDpopProof(input, deps) {
+  if (!deps.tokenStore.recordDpopJti) {
+    return err(authError.invalidDpopProof("token-store adapter does not support DPoP replay protection"));
+  }
+  let header;
+  try {
+    header = decodeProtectedHeader(input.proofJwt);
+  } catch (e) {
+    return err(authError.invalidDpopProof(`dpop proof header is not a valid compact JWS: ${stringifyError(e)}`));
+  }
+  if (header.typ !== "dpop+jwt") {
+    return err(authError.invalidDpopProof(`dpop proof header.typ must be "dpop+jwt", got "${String(header.typ)}"`));
+  }
+  if (!header.alg || !DPOP_ASYMMETRIC_ALGS.has(header.alg)) {
+    return err(authError.invalidDpopProof(`dpop proof alg "${String(header.alg)}" not in {ES256, EdDSA}`));
+  }
+  const jwk = header.jwk;
+  if (!jwk || typeof jwk !== "object") {
+    return err(authError.invalidDpopProof("dpop proof header.jwk missing or not an object"));
+  }
+  if ("d" in jwk) {
+    return err(authError.invalidDpopProof("dpop proof header.jwk must be a public key (private material present)"));
+  }
+  let key;
+  try {
+    key = await importJWK(jwk, header.alg);
+  } catch (e) {
+    return err(authError.invalidDpopProof(`dpop proof JWK import failed: ${stringifyError(e)}`));
+  }
+  let verified;
+  try {
+    verified = await jwtVerify(input.proofJwt, key, {
+      algorithms: [header.alg]
+    });
+  } catch (e) {
+    return err(authError.invalidDpopProof(`dpop proof signature verification failed: ${stringifyError(e)}`));
+  }
+  const payload = verified.payload;
+  if (typeof payload.htm !== "string") {
+    return err(authError.invalidDpopProof("dpop proof missing string htm"));
+  }
+  if (typeof payload.htu !== "string") {
+    return err(authError.invalidDpopProof("dpop proof missing string htu"));
+  }
+  if (typeof payload.iat !== "number") {
+    return err(authError.invalidDpopProof("dpop proof missing numeric iat"));
+  }
+  if (typeof payload.jti !== "string" || payload.jti.length === 0) {
+    return err(authError.invalidDpopProof("dpop proof missing non-empty string jti"));
+  }
+  if (payload.htm !== input.htm) {
+    return err(authError.invalidDpopProof(`dpop htm "${payload.htm}" does not match request method "${input.htm}"`));
+  }
+  if (payload.htu !== input.htu) {
+    return err(authError.invalidDpopProof(`dpop htu "${payload.htu}" does not match request uri "${input.htu}"`));
+  }
+  const tolerance = input.iatToleranceSec ?? DEFAULT_DPOP_IAT_TOLERANCE_SEC;
+  const skew = Math.abs(input.nowSec - payload.iat);
+  if (skew > tolerance) {
+    return err(authError.invalidDpopProof(`dpop iat skew ${skew}s exceeds tolerance ${tolerance}s`));
+  }
+  if (input.expectedAth !== undefined) {
+    if (typeof payload.ath !== "string" || payload.ath !== input.expectedAth) {
+      return err(authError.invalidDpopProof("dpop ath does not match SHA-256 of the access token"));
+    }
+  }
+  const recorded = await deps.tokenStore.recordDpopJti(payload.jti, deps.jtiTtlMs ?? DEFAULT_DPOP_JTI_TTL_MS);
+  if (isErr(recorded)) {
+    return err(authError.invalidDpopProof(`dpop jti "${payload.jti}" replayed`, {
+      jti: payload.jti
+    }));
+  }
+  let jkt;
+  try {
+    jkt = await calculateJwkThumbprint(jwk, "sha256");
+  } catch (e) {
+    return err(authError.invalidDpopProof(`dpop jkt thumbprint computation failed: ${stringifyError(e)}`));
+  }
+  return ok({
+    jkt,
+    payload: {
+      htm: payload.htm,
+      htu: payload.htu,
+      iat: payload.iat,
+      jti: payload.jti,
+      ...payload.ath !== undefined ? { ath: payload.ath } : {},
+      ...payload.nonce !== undefined ? { nonce: payload.nonce } : {}
+    }
+  });
+}
+function canonicalHtu(rawUrl) {
+  const u = new URL(rawUrl);
+  u.search = "";
+  u.hash = "";
+  return u.toString();
+}
+async function computeAth(accessToken) {
+  return base64url.encode(await sha256(utf8.encode(accessToken)));
+}
+function stringifyError(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+export {
+  verifyDpopProof,
+  computeAth,
+  canonicalHtu,
+  DEFAULT_DPOP_JTI_TTL_MS,
+  DEFAULT_DPOP_IAT_TOLERANCE_SEC
+};

package/dist/esm/domain/id-token.js

@@ -0,0 +1,94 @@
+// src/domain/id-token.ts
+import { base64url, sha256, utf8 } from "./crypto";
+var SCOPE_TO_CLAIMS = {
+  profile: [
+    "name",
+    "given_name",
+    "family_name",
+    "middle_name",
+    "nickname",
+    "preferred_username",
+    "profile",
+    "picture",
+    "website",
+    "gender",
+    "birthdate",
+    "zoneinfo",
+    "locale",
+    "updated_at"
+  ],
+  email: ["email", "email_verified"],
+  phone: ["phone_number", "phone_number_verified"],
+  address: ["address"]
+};
+function deriveAmr(methodKind) {
+  switch (methodKind) {
+    case "password":
+      return ["pwd"];
+    case "code":
+      return ["otp"];
+    case "passkey":
+      return ["hwk"];
+    default:
+      return;
+  }
+}
+async function computeAtHash(accessToken) {
+  const digest = await sha256(utf8.encode(accessToken));
+  const half = digest.slice(0, digest.byteLength / 2);
+  return base64url.encode(half);
+}
+function pickScopedClaims(claim, scopes, extra = [], customMappings = {}) {
+  const props = claim.properties;
+  if (!props || typeof props !== "object")
+    return {};
+  const mappings = {
+    ...customMappings,
+    ...SCOPE_TO_CLAIMS
+  };
+  const granted = new Set;
+  for (const scope of scopes) {
+    const list = mappings[scope];
+    if (!list)
+      continue;
+    for (const c of list)
+      granted.add(c);
+  }
+  for (const name of extra)
+    granted.add(name);
+  const out = {};
+  for (const key of granted) {
+    if (key in props && props[key] !== undefined)
+      out[key] = props[key];
+  }
+  return out;
+}
+var DEFAULT_ID_TOKEN_TTL_MS = 5 * 60 * 1000;
+async function buildIdTokenClaims(input) {
+  const ttl = input.ttlMs ?? DEFAULT_ID_TOKEN_TTL_MS;
+  const amr = deriveAmr(input.methodKind);
+  const extraClaims = Object.keys(input.claimsRequest?.id_token ?? {});
+  return {
+    iss: input.issuerUrl,
+    sub: input.subjectId,
+    aud: input.audience,
+    exp: Math.floor((input.now + ttl) / 1000),
+    iat: Math.floor(input.now / 1000),
+    auth_time: input.authTime,
+    at_hash: await computeAtHash(input.accessToken),
+    ...input.appNonce !== undefined ? { nonce: input.appNonce } : {},
+    ...amr ? { amr } : {},
+    ...pickScopedClaims(input.claim, input.scopes, extraClaims, input.customScopeClaims ?? {})
+  };
+}
+function shouldIssueIdToken(scopes) {
+  return scopes.includes("openid");
+}
+export {
+  shouldIssueIdToken,
+  pickScopedClaims,
+  deriveAmr,
+  computeAtHash,
+  buildIdTokenClaims,
+  DEFAULT_ID_TOKEN_TTL_MS
+};

package/dist/esm/domain/introspect.js

@@ -0,0 +1,55 @@
+// src/domain/introspect.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { verifyClientCredentials } from "./client-auth";
+import { verifyAccessToken } from "./jwt";
+async function introspect(req, deps) {
+  const presenterTenantCfg = await deps.configStore.getTenantConfig(req.presenterTenantId);
+  if (isErr(presenterTenantCfg)) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`));
+  }
+  const presenter = presenterTenantCfg.value.clients.find((c) => c.id === req.clientId);
+  if (!presenter) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`));
+  }
+  const authErr = await verifyClientCredentials(presenter, req.clientSecret);
+  if (authErr)
+    return err(authErr);
+  const keysRes = await deps.keyStore.signingKeys();
+  if (isErr(keysRes))
+    return err(keysRes.error);
+  let claims;
+  try {
+    claims = await verifyAccessToken(req.token, keysRes.value, {
+      ...deps.issuerUrl ? { issuer: deps.issuerUrl } : {}
+    });
+  } catch {
+    return ok({ active: false });
+  }
+  if (claims.tid !== req.presenterTenantId) {
+    return ok({ active: false });
+  }
+  if (claims.aud !== req.clientId) {
+    return ok({ active: false });
+  }
+  const subjectType = claims.claim?.type;
+  return ok({
+    active: true,
+    sub: claims.sub,
+    aud: claims.aud,
+    iss: claims.iss,
+    exp: claims.exp,
+    iat: claims.iat,
+    scope: claims.scope,
+    client_id: claims.aud,
+    token_type: claims.cnf?.jkt !== undefined ? "DPoP" : "Bearer",
+    tid: claims.tid,
+    mid: claims.mid,
+    mkind: claims.mkind,
+    ...subjectType !== undefined ? { subject_type: subjectType } : {},
+    ...claims.cnf !== undefined ? { cnf: claims.cnf } : {}
+  });
+}
+export {
+  introspect
+};

package/dist/esm/domain/jwt.js

@@ -0,0 +1,71 @@
+// src/domain/jwt.ts
+import { importJWK, jwtVerify, SignJWT } from "jose";
+async function signAccessToken(claims, privateKey, alg, kid) {
+  return new SignJWT(claims).setProtectedHeader({ alg, typ: "JWT", kid }).sign(privateKey);
+}
+async function signIdToken(claims, privateKey, alg, kid) {
+  return new SignJWT(claims).setProtectedHeader({ alg, typ: "JWT", kid }).sign(privateKey);
+}
+async function verifyIdToken(token, keys, options = {}) {
+  const algorithms = Array.from(new Set(keys.map((k) => k.alg).filter((a) => ASYMMETRIC_ALGS.has(a))));
+  const { payload } = await jwtVerify(token, async (header) => {
+    if (!header.alg || header.alg === "none") {
+      throw new Error(`verifyIdToken: refusing alg "${header.alg ?? ""}"`);
+    }
+    const match = keys.find((k) => k.kid === header.kid);
+    if (!match) {
+      throw new Error(`verifyIdToken: unknown kid "${header.kid}"`);
+    }
+    if (match.alg !== header.alg) {
+      throw new Error(`verifyIdToken: header.alg "${header.alg}" does not match key alg "${match.alg}"`);
+    }
+    const imported = await importJWK(match.publicJwk, match.alg);
+    return imported;
+  }, {
+    algorithms,
+    ...options.issuer ? { issuer: options.issuer } : {},
+    ...options.audience ? { audience: options.audience } : {},
+    ...options.acceptExpired ? { clockTolerance: Number.MAX_SAFE_INTEGER } : {}
+  });
+  return payload;
+}
+var ASYMMETRIC_ALGS = new Set(["ES256", "EdDSA"]);
+async function verifyAccessToken(token, keys, options = {}) {
+  const algorithms = Array.from(new Set(keys.map((k) => k.alg).filter((a) => ASYMMETRIC_ALGS.has(a))));
+  const { payload } = await jwtVerify(token, async (header) => {
+    if (!header.alg || header.alg === "none") {
+      throw new Error(`verifyAccessToken: refusing alg "${header.alg ?? ""}"`);
+    }
+    const match = keys.find((k) => k.kid === header.kid);
+    if (!match) {
+      throw new Error(`verifyAccessToken: unknown kid "${header.kid}"`);
+    }
+    if (match.alg !== header.alg) {
+      throw new Error(`verifyAccessToken: header.alg "${header.alg}" does not match key alg "${match.alg}"`);
+    }
+    const imported = await importJWK(match.publicJwk, match.alg);
+    return imported;
+  }, {
+    algorithms,
+    ...options.issuer ? { issuer: options.issuer } : {},
+    ...options.audience ? { audience: options.audience } : {}
+  });
+  return payload;
+}
+function buildJwksDocument(keys) {
+  return {
+    keys: keys.map((k) => ({
+      ...k.publicJwk,
+      kid: k.kid,
+      alg: k.alg,
+      use: "sig"
+    }))
+  };
+}
+export {
+  verifyIdToken,
+  verifyAccessToken,
+  signIdToken,
+  signAccessToken,
+  buildJwksDocument
+};

package/dist/esm/domain/logout.js

@@ -0,0 +1,75 @@
+// src/domain/logout.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { safeAudit } from "./audit";
+import { verifyIdToken } from "./jwt";
+import { revokeAllForSubject } from "./revoke";
+async function endSession(req, tenant, deps) {
+  let hintSubject;
+  let hintAud;
+  if (req.idTokenHint) {
+    const keysRes = await deps.keyStore.signingKeys();
+    if (isErr(keysRes))
+      return err(keysRes.error);
+    try {
+      const claims = await verifyIdToken(req.idTokenHint, keysRes.value, {
+        issuer: deps.issuerUrl,
+        acceptExpired: true
+      });
+      hintSubject = claims.sub;
+      hintAud = claims.aud;
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      return err(authError.invalidRequest(`id_token_hint failed signature/issuer verification: ${reason}`, "id_token_hint"));
+    }
+  }
+  if (req.clientId && hintAud && req.clientId !== hintAud) {
+    return err(authError.invalidRequest("client_id does not match id_token_hint.aud", "client_id"));
+  }
+  const resolvedClientId = req.clientId ?? hintAud;
+  let client;
+  if (resolvedClientId) {
+    client = tenant.config.clients.find((c) => c.id === resolvedClientId);
+    if (!client) {
+      return err(authError.invalidRequest(`unknown client "${resolvedClientId}"`, "client_id"));
+    }
+  }
+  if (req.postLogoutRedirectUri) {
+    if (!client) {
+      return err(authError.invalidRequest("post_logout_redirect_uri requires identifying the client via client_id or id_token_hint", "post_logout_redirect_uri"));
+    }
+    const registered = client.postLogoutRedirectUris ?? [];
+    if (!registered.includes(req.postLogoutRedirectUri)) {
+      return err(authError.invalidRequest("post_logout_redirect_uri is not registered for this client", "post_logout_redirect_uri"));
+    }
+  }
+  if (hintSubject) {
+    const revoked = await revokeAllForSubject(tenant.id, hintSubject, {
+      tokenStore: deps.tokenStore,
+      ...deps.auditLog ? { auditLog: deps.auditLog } : {},
+      clock: deps.clock
+    });
+    if (isErr(revoked))
+      return err(revoked.error);
+  }
+  await safeAudit(deps, {
+    kind: "session_logout",
+    tenantId: tenant.id,
+    ...resolvedClientId ? { clientId: resolvedClientId } : {},
+    ...hintSubject ? { subjectId: hintSubject } : {},
+    timestamp: deps.clock()
+  });
+  if (req.postLogoutRedirectUri) {
+    const url = new URL(req.postLogoutRedirectUri);
+    if (req.state !== undefined)
+      url.searchParams.set("state", req.state);
+    return ok({ kind: "redirect", url: url.toString() });
+  }
+  return ok({
+    kind: "ok",
+    ...hintSubject ? { subjectId: hintSubject } : {}
+  });
+}
+export {
+  endSession
+};