@_mustachio/openauth 0.9.2 → 0.11.0

package/dist/esm/domain/method-cache.js

@@ -0,0 +1,136 @@
+// src/domain/method-cache.ts
+import { authError } from "../types/error";
+import { err, ok } from "../types/result";
+
+class MethodCache {
+  #factories;
+  #auditLog;
+  #now;
+  #cache = new Map;
+  #disabled = new Set;
+  constructor(opts) {
+    this.#factories = opts.factories;
+    this.#auditLog = opts.auditLog;
+    this.#now = opts.now;
+  }
+  async resolve(tenant, methodId) {
+    const cacheKey = this.#key(tenant.id, methodId);
+    const hit = this.#cache.get(cacheKey);
+    if (hit)
+      return ok(hit);
+    if (this.#disabled.has(cacheKey)) {
+      return err(authError.methodNotFound(`method "${methodId}" is disabled or has invalid config`, { methodId }));
+    }
+    const cfg = tenant.methods.find((m) => m.id === methodId);
+    if (!cfg) {
+      return err(authError.methodNotFound(`method "${methodId}" not configured`, {
+        methodId
+      }));
+    }
+    if (!cfg.enabled) {
+      return err(authError.methodNotFound(`method "${methodId}" is disabled`, {
+        methodId
+      }));
+    }
+    const built = await this.#build(tenant.id, cfg);
+    if (built.ok) {
+      this.#cache.set(cacheKey, built.value);
+    } else {
+      this.#disabled.add(cacheKey);
+    }
+    return built;
+  }
+  invalidate(tenantId, methodId) {
+    if (methodId !== undefined) {
+      const key = this.#key(tenantId, methodId);
+      this.#cache.delete(key);
+      this.#disabled.delete(key);
+      return;
+    }
+    for (const k of [...this.#cache.keys()]) {
+      if (k.startsWith(`${tenantId}\x00`))
+        this.#cache.delete(k);
+    }
+    for (const k of [...this.#disabled]) {
+      if (k.startsWith(`${tenantId}\x00`))
+        this.#disabled.delete(k);
+    }
+  }
+  async listAvailable(tenant) {
+    const results = [];
+    for (const cfg of tenant.methods) {
+      if (!cfg.enabled)
+        continue;
+      const m = await this.resolve(tenant, cfg.id);
+      if (m.ok)
+        results.push(m.value);
+    }
+    return results;
+  }
+  async#build(tenantId, cfg) {
+    const factory = this.#factories[cfg.kind];
+    if (!factory) {
+      await this.#audit({
+        kind: "unknown_method_kind",
+        tenantId,
+        methodId: cfg.id,
+        methodKind: cfg.kind,
+        timestamp: this.#now()
+      });
+      return err(authError.methodNotFound(`no factory registered for kind "${cfg.kind}"`, {
+        methodId: cfg.id,
+        methodKind: cfg.kind
+      }));
+    }
+    let parsed = factory.configSchema["~standard"].validate(cfg.config);
+    if (parsed instanceof Promise)
+      parsed = await parsed;
+    if ("issues" in parsed && parsed.issues) {
+      await this.#audit({
+        kind: "invalid_method_config",
+        tenantId,
+        methodId: cfg.id,
+        methodKind: cfg.kind,
+        errorPath: parsed.issues.map((issue) => (issue.path ?? []).map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".")).join(","),
+        timestamp: this.#now()
+      });
+      return err(authError.methodNotFound(`invalid method config for "${cfg.id}" (kind "${cfg.kind}")`, { methodId: cfg.id, methodKind: cfg.kind }));
+    }
+    let method;
+    try {
+      method = await factory.build({
+        id: cfg.id,
+        kind: cfg.kind,
+        tenantId,
+        config: parsed.value
+      });
+    } catch (e) {
+      return err(authError.internalError(`factory "${cfg.kind}" build threw for instance "${cfg.id}"`, e));
+    }
+    if (method.id !== cfg.id || method.kind !== cfg.kind) {
+      await this.#audit({
+        kind: "factory_id_mismatch",
+        tenantId,
+        methodId: cfg.id,
+        expectedKind: cfg.kind,
+        actualKind: method.kind,
+        timestamp: this.#now()
+      });
+      return err(authError.internalError(`factory "${cfg.kind}" returned AuthMethod with id/kind ${method.id}/${method.kind}; expected ${cfg.id}/${cfg.kind}`));
+    }
+    return ok(method);
+  }
+  #key(tenantId, methodId) {
+    return `${tenantId}\x00${methodId}`;
+  }
+  async#audit(event) {
+    if (!this.#auditLog)
+      return;
+    try {
+      await this.#auditLog.log(event);
+    } catch {}
+  }
+}
+export {
+  MethodCache
+};

package/dist/esm/domain/method-dispatch.js

@@ -0,0 +1,36 @@
+// src/domain/method-dispatch.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+async function dispatchMethod(input) {
+  const handler = input.method.routes[input.route];
+  if (!handler) {
+    return err(authError.invalidRequest(`method "${input.method.id}" has no handler for route "${input.route}"`));
+  }
+  const ctx = {
+    request: input.request,
+    subPath: input.subPath,
+    tenant: input.tenant,
+    flow: input.flow,
+    methodState: input.flow?.methodState ?? null,
+    cookies: input.cookies,
+    dispatch: input.dispatch
+  };
+  let result;
+  try {
+    result = await handler(ctx);
+  } catch (e) {
+    return err(authError.serverError(`method "${input.method.id}" handler threw on route "${input.route}"`, e));
+  }
+  if (result.kind === "challenge" && result.saveMethodState !== undefined) {
+    if (!input.flow) {
+      return err(authError.internalError(`method "${input.method.id}" returned saveMethodState without an active flow`));
+    }
+    const persisted = await input.sessionStore.updateFlowMethodState(input.flow.flowId, result.saveMethodState);
+    if (isErr(persisted))
+      return err(persisted.error);
+  }
+  return ok(result);
+}
+export {
+  dispatchMethod
+};

package/dist/esm/domain/method-route.js

@@ -0,0 +1,111 @@
+// src/domain/method-route.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { safeAudit } from "./audit";
+import { AUTH_CODE_TTL_MS } from "./authorize";
+import { randomToken } from "./crypto";
+import { dispatchMethod } from "./method-dispatch";
+import { saveEncryptedCode } from "./token";
+async function handleMethodRoute(input, deps) {
+  const flowRes = await deps.sessionStore.readFlow(input.flowId);
+  if (isErr(flowRes))
+    return err(flowRes.error);
+  const flow = flowRes.value;
+  if (flow.tenantId !== input.tenant.id) {
+    await safeAudit(deps, {
+      kind: "flow_tenant_mismatch",
+      stateTenantId: input.tenant.id,
+      flowTenantId: flow.tenantId,
+      flowId: flow.flowId,
+      timestamp: deps.clock()
+    });
+    return err(authError.invalidRequest("tenant mismatch", "flow"));
+  }
+  if (flow.methodId !== input.methodId) {
+    return err(authError.invalidRequest(`method "${input.methodId}" does not own flow "${flow.flowId}" (expected "${flow.methodId}")`, "methodId"));
+  }
+  const methodRes = await deps.methodCache.resolve(input.tenant.config, input.methodId);
+  if (isErr(methodRes))
+    return err(methodRes.error);
+  const route = `${input.httpMethod} ${input.subPath}`;
+  const dispatched = await dispatchMethod({
+    method: methodRes.value,
+    route,
+    tenant: input.tenant,
+    request: input.rawRequest,
+    subPath: input.subPath,
+    flow,
+    cookies: input.cookies,
+    sessionStore: deps.sessionStore,
+    dispatch: null
+  });
+  if (isErr(dispatched))
+    return err(dispatched.error);
+  return translate(dispatched.value, flow, deps);
+}
+async function translate(result, flow, deps) {
+  switch (result.kind) {
+    case "success": {
+      const consumed = await deps.sessionStore.consumeFlow(flow.flowId);
+      if (isErr(consumed))
+        return err(consumed.error);
+      const final = consumed.value;
+      const code = (deps.newCodeId ?? randomToken)();
+      const now = deps.clock();
+      const saved = await saveEncryptedCode(code, {
+        tenantId: final.tenantId,
+        clientId: final.clientId,
+        appRedirectUri: final.appRedirectUri,
+        appState: final.appState,
+        scopes: final.scopes,
+        audience: final.audience,
+        clientPkce: final.clientPkce,
+        methodId: final.methodId,
+        methodKind: final.methodKind,
+        context: final.context ?? null,
+        providerSubject: result.providerSubject,
+        properties: result.properties,
+        ...final.appNonce !== undefined ? { appNonce: final.appNonce } : {},
+        ...final.claimsRequest !== undefined ? { claimsRequest: final.claimsRequest } : {},
+        authTime: Math.floor(now / 1000),
+        expiresAt: now + AUTH_CODE_TTL_MS
+      }, AUTH_CODE_TTL_MS, { keyStore: deps.keyStore, tokenStore: deps.tokenStore });
+      if (isErr(saved))
+        return err(saved.error);
+      return ok({
+        kind: "issue-code",
+        code,
+        appRedirectUri: final.appRedirectUri,
+        appState: final.appState
+      });
+    }
+    case "challenge":
+      return ok({
+        kind: "challenge",
+        response: result.response,
+        setCookies: result.setCookies ?? [],
+        ...result.cache !== undefined ? { cache: result.cache } : {}
+      });
+    case "denied":
+      await safeAudit(deps, {
+        kind: "authorize_failed",
+        tenantId: flow.tenantId,
+        clientId: flow.clientId,
+        methodId: flow.methodId,
+        methodKind: flow.methodKind,
+        flowId: flow.flowId,
+        reason: result.reason,
+        timestamp: deps.clock()
+      });
+      return ok({
+        kind: "denied",
+        reason: result.reason,
+        setCookies: result.setCookies ?? []
+      });
+    case "error":
+      return err(result.error);
+  }
+}
+export {
+  handleMethodRoute
+};

package/dist/esm/domain/par.js

@@ -0,0 +1,51 @@
+// src/domain/par.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { verifyClientCredentials } from "./client-auth";
+import { randomToken } from "./crypto";
+var PAR_URI_PREFIX = "urn:ietf:params:oauth:request_uri:";
+var DEFAULT_PAR_TTL_MS = 60 * 1000;
+async function pushAuthorizationRequest(req, tenant, deps) {
+  if (!deps.sessionStore.savePar || !deps.sessionStore.consumePar) {
+    return err(authError.invalidRequest("session adapter does not implement PAR storage"));
+  }
+  const client = tenant.config.clients.find((c) => c.id === req.clientId);
+  if (!client) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`));
+  }
+  if (client.type === "confidential") {
+    const authErr = await verifyClientCredentials(client, req.clientSecret);
+    if (authErr)
+      return err(authErr);
+  } else if (req.clientSecret !== undefined) {
+    return err(authError.invalidClient("public client must not present client_secret"));
+  }
+  if (req.params.client_id && req.params.client_id !== req.clientId) {
+    return err(authError.invalidRequest("client_id in body conflicts with authenticated client", "client_id"));
+  }
+  if ("request_uri" in req.params) {
+    return err(authError.invalidRequest("request_uri MUST NOT be present in a PAR request", "request_uri"));
+  }
+  const suffix = (deps.newRequestUriSuffix ?? randomToken)();
+  const requestUri = PAR_URI_PREFIX + suffix;
+  const ttl = deps.ttlMs ?? DEFAULT_PAR_TTL_MS;
+  const now = deps.clock();
+  const saved = await deps.sessionStore.savePar(requestUri, {
+    requestUri,
+    params: { ...req.params, client_id: req.clientId },
+    clientId: req.clientId,
+    issuedAt: now,
+    expiresAt: now + ttl
+  }, ttl);
+  if (isErr(saved))
+    return err(saved.error);
+  return ok({
+    request_uri: requestUri,
+    expires_in: Math.floor(ttl / 1000)
+  });
+}
+export {
+  pushAuthorizationRequest,
+  PAR_URI_PREFIX,
+  DEFAULT_PAR_TTL_MS
+};

package/dist/esm/domain/pkce.js

@@ -0,0 +1,16 @@
+// src/domain/pkce.ts
+import { base64url, sha256, timingSafeEqualStr, utf8 } from "./crypto";
+async function s256Challenge(verifier) {
+  return base64url.encode(await sha256(utf8.encode(verifier)));
+}
+async function validatePkce(verifier, challenge) {
+  if (typeof verifier !== "string" || typeof challenge !== "string" || verifier.length < 43 || verifier.length > 128) {
+    return false;
+  }
+  const computed = await s256Challenge(verifier);
+  return timingSafeEqualStr(computed, challenge);
+}
+export {
+  validatePkce,
+  s256Challenge
+};

package/dist/esm/domain/refresh.js

@@ -0,0 +1,102 @@
+// src/domain/refresh.ts
+import { authError } from "../types/error";
+import { err, isErr } from "../types/result";
+import { safeAudit } from "./audit";
+import { verifyClientCredentials } from "./client-auth";
+import { mintTokens } from "./token";
+async function refreshTokens(req, deps) {
+  const peek = await deps.tokenStore.peekRefresh(req.refreshToken);
+  if (isErr(peek))
+    return err(peek.error);
+  const peekedPayload = peek.value;
+  const tenantCfg = await deps.configStore.getTenantConfig(peekedPayload.tenantId);
+  if (isErr(tenantCfg))
+    return err(tenantCfg.error);
+  const INVALID_REFRESH_DESC = "refresh token is invalid";
+  const client = tenantCfg.value.clients.find((c) => c.id === peekedPayload.clientId);
+  if (!client) {
+    return err(authError.invalidGrant(INVALID_REFRESH_DESC));
+  }
+  if (req.clientId !== undefined) {
+    const presenting = tenantCfg.value.clients.find((c) => c.id === req.clientId);
+    if (!presenting) {
+      return err(authError.invalidGrant(INVALID_REFRESH_DESC));
+    }
+    const authErr = await verifyClientCredentials(presenting, req.clientSecret);
+    if (authErr)
+      return err(authError.invalidGrant(INVALID_REFRESH_DESC));
+    if (req.clientId !== peekedPayload.clientId) {
+      return err(authError.invalidGrant(INVALID_REFRESH_DESC));
+    }
+  } else if (client.type === "confidential") {
+    return err(authError.invalidGrant(INVALID_REFRESH_DESC));
+  }
+  if (peekedPayload.dpopJkt !== undefined) {
+    if (req.dpopJkt === undefined) {
+      return err(authError.invalidDpopProof("refresh token is DPoP-bound; request is missing a DPoP proof"));
+    }
+    if (req.dpopJkt !== peekedPayload.dpopJkt) {
+      return err(authError.invalidDpopProof("refresh token DPoP jkt does not match the original binding"));
+    }
+  }
+  const consumed = await deps.tokenStore.consumeRefresh(req.refreshToken, {
+    reuseWindowMs: deps.reuseWindowMs
+  });
+  if (isErr(consumed)) {
+    if (consumed.error.code === "invalid_grant" && consumed.error.reuseSignal) {
+      const signal = consumed.error.reuseSignal;
+      await safeAudit(deps, {
+        kind: "refresh_reuse_detected",
+        tenantId: peekedPayload.tenantId,
+        clientId: peekedPayload.clientId,
+        family: signal.family,
+        timestamp: deps.clock()
+      });
+    }
+    return err(consumed.error);
+  }
+  const payload = consumed.value;
+  const requestedScopes = req.scope ? req.scope.split(" ").filter(Boolean) : payload.scopes;
+  for (const s of requestedScopes) {
+    if (!payload.scopes.includes(s)) {
+      return err(authError.invalidScope(`requested scope "${s}" not granted by original refresh token`));
+    }
+  }
+  const tenant = {
+    id: payload.tenantId,
+    config: tenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} }
+  };
+  return mintTokens({
+    tenant,
+    claim: payload.claim,
+    payload: {
+      tenantId: payload.tenantId,
+      clientId: payload.clientId,
+      methodId: payload.methodId,
+      methodKind: payload.methodKind,
+      scopes: requestedScopes,
+      audience: payload.audience,
+      authTime: payload.authTime,
+      ...payload.dpopJkt !== undefined ? { dpopJkt: payload.dpopJkt } : {},
+      ...payload.claimsRequest !== undefined ? { claimsRequest: payload.claimsRequest } : {}
+    },
+    family: payload.family,
+    deps
+  }).then(async (result) => {
+    if (result.ok) {
+      await safeAudit(deps, {
+        kind: "token_refreshed",
+        tenantId: payload.tenantId,
+        clientId: payload.clientId,
+        subjectId: payload.subjectId,
+        family: payload.family,
+        timestamp: deps.clock()
+      });
+    }
+    return result;
+  });
+}
+export {
+  refreshTokens
+};

package/dist/esm/domain/register.js

@@ -0,0 +1,74 @@
+// src/domain/register.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { randomId, randomToken } from "./crypto";
+import { hashClientSecret } from "./token";
+async function registerNewClient(request, tenant, deps) {
+  if (!deps.registerClient) {
+    return err(authError.invalidRequest("dynamic client registration is not enabled on this deployment"));
+  }
+  if (!Array.isArray(request.redirect_uris) || request.redirect_uris.length === 0) {
+    return err(authError.invalidRequest("redirect_uris must be a non-empty array", "redirect_uris"));
+  }
+  for (const uri of request.redirect_uris) {
+    try {
+      new URL(uri);
+    } catch {
+      return err(authError.invalidRequest(`redirect_uri "${uri}" is not a valid absolute URI`, "redirect_uris"));
+    }
+  }
+  const authMethod = request.token_endpoint_auth_method ?? "client_secret_basic";
+  const isPublic = authMethod === "none";
+  const clientId = (deps.newClientId ?? randomId)();
+  const grantTypes = request.grant_types ?? ["authorization_code"];
+  const responseTypes = request.response_types ?? ["code"];
+  const scopes = request.scope ? request.scope.split(/\s+/).filter(Boolean) : ["openid"];
+  let secret;
+  let secretHash;
+  if (!isPublic) {
+    secret = (deps.newClientSecret ?? randomToken)();
+    secretHash = await hashClientSecret(secret);
+  }
+  const clientPartial = {
+    id: clientId,
+    name: request.client_name ?? clientId,
+    redirectUris: request.redirect_uris,
+    scopes,
+    grantTypes: grantTypes.filter((g) => g === "authorization_code" || g === "refresh_token" || g === "client_credentials"),
+    ...request.post_logout_redirect_uris !== undefined ? { postLogoutRedirectUris: request.post_logout_redirect_uris } : {},
+    ...request.sector_identifier_uri !== undefined ? { sectorIdentifier: request.sector_identifier_uri } : {}
+  };
+  const clientConfig = isPublic ? {
+    ...clientPartial,
+    type: "public",
+    pkceRequired: true
+  } : {
+    ...clientPartial,
+    type: "confidential",
+    secretHash,
+    pkceRequired: true
+  };
+  const hookResult = await deps.registerClient({
+    tenant,
+    request
+  });
+  if (isErr(hookResult))
+    return err(hookResult.error);
+  const persisted = hookResult.value.client;
+  const persistedSecret = hookResult.value.secret;
+  const issuedAt = Math.floor(deps.clock() / 1000);
+  return ok({
+    client_id: persisted.id,
+    ...persistedSecret !== undefined ? { client_secret: persistedSecret } : {},
+    client_id_issued_at: issuedAt,
+    client_secret_expires_at: 0,
+    redirect_uris: persisted.redirectUris,
+    grant_types: persisted.grantTypes,
+    response_types: responseTypes,
+    token_endpoint_auth_method: authMethod,
+    ...request.client_name !== undefined ? { client_name: request.client_name } : {}
+  });
+}
+export {
+  registerNewClient
+};

package/dist/esm/domain/revoke.js

@@ -0,0 +1,81 @@
+// src/domain/revoke.ts
+import { authError } from "../types/error";
+import { err, isErr, ok } from "../types/result";
+import { safeAudit } from "./audit";
+import { verifyClientCredentials } from "./client-auth";
+async function revokeToken(req, deps) {
+  if (req.tokenTypeHint === "access_token") {
+    return ok(undefined);
+  }
+  const peek = await deps.tokenStore.peekRefresh(req.token);
+  if (isErr(peek)) {
+    return ok(undefined);
+  }
+  const payload = peek.value;
+  const tenantCfg = await deps.configStore.getTenantConfig(payload.tenantId);
+  if (isErr(tenantCfg)) {
+    return ok(undefined);
+  }
+  const client = tenantCfg.value.clients.find((c) => c.id === payload.clientId);
+  if (!client) {
+    return ok(undefined);
+  }
+  if (client.type === "confidential") {
+    if (!req.clientId || !req.clientSecret) {
+      return err(authError.invalidClient("confidential client must authenticate to revoke its tokens"));
+    }
+  }
+  if (req.clientId !== undefined && req.clientId !== payload.clientId) {
+    await safeAudit(deps, {
+      kind: "custom",
+      type: "revoke_wrong_client_attempt",
+      tenantId: payload.tenantId,
+      data: {
+        presentedClientId: req.clientId,
+        tokenClientId: payload.clientId,
+        subjectId: payload.subjectId
+      },
+      timestamp: deps.clock()
+    });
+    return ok(undefined);
+  }
+  if (req.clientId !== undefined) {
+    const authErr = await verifyClientCredentials(client, req.clientSecret);
+    if (authErr)
+      return err(authErr);
+  }
+  const consumed = await deps.tokenStore.consumeRefresh(req.token, {
+    reuseWindowMs: 0
+  });
+  if (isErr(consumed)) {
+    return ok(undefined);
+  }
+  await safeAudit(deps, {
+    kind: "token_revoked",
+    tenantId: payload.tenantId,
+    clientId: payload.clientId,
+    subjectId: payload.subjectId,
+    family: payload.family,
+    reason: "client_revoke",
+    timestamp: deps.clock()
+  });
+  return ok(undefined);
+}
+async function revokeAllForSubject(tenantId, subjectId, deps) {
+  const res = await deps.tokenStore.revokeBySubject(tenantId, subjectId);
+  if (isErr(res))
+    return err(res.error);
+  await safeAudit(deps, {
+    kind: "token_revoked",
+    tenantId,
+    clientId: null,
+    subjectId,
+    reason: "subject_revoke",
+    timestamp: deps.clock()
+  });
+  return ok(undefined);
+}
+export {
+  revokeToken,
+  revokeAllForSubject
+};

package/dist/esm/domain/state-envelope.js

@@ -0,0 +1,80 @@
+// src/domain/state-envelope.ts
+import { authError } from "../types/error";
+import { err, ok } from "../types/result";
+import { asTenantId } from "../types/tenant";
+import { base64url, hmacSign, hmacVerify, importHmacKey, utf8 } from "./crypto";
+function canonicalize(env) {
+  return JSON.stringify({
+    tenantId: env.tenantId,
+    flowId: env.flowId,
+    nonce: env.nonce,
+    kid: env.kid
+  });
+}
+async function mintStateEnvelope(envelope, keyRing) {
+  const active = keyRing.active;
+  const stamped = { ...envelope, kid: active.kid };
+  const payloadBytes = utf8.encode(canonicalize(stamped));
+  const key = await importHmacKey(active.key, ["sign"]);
+  const sig = await hmacSign(key, payloadBytes);
+  return `${base64url.encode(payloadBytes)}.${base64url.encode(sig)}`;
+}
+async function verifyStateEnvelope(state, keyRing) {
+  if (typeof state !== "string" || !state.includes(".")) {
+    return err(authError.unknownState("malformed state"));
+  }
+  const dotIdx = state.indexOf(".");
+  const headerB64u = state.slice(0, dotIdx);
+  const sigB64u = state.slice(dotIdx + 1);
+  if (!headerB64u || !sigB64u || sigB64u.includes(".")) {
+    return err(authError.unknownState("malformed state"));
+  }
+  let payloadBytes;
+  let sigBytes;
+  try {
+    payloadBytes = base64url.decode(headerB64u);
+    sigBytes = base64url.decode(sigB64u);
+  } catch {
+    return err(authError.unknownState("malformed state encoding"));
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(utf8.decode(payloadBytes));
+  } catch {
+    return err(authError.unknownState("malformed state payload"));
+  }
+  if (!isEnvelopeShape(parsed)) {
+    return err(authError.unknownState("state payload missing fields"));
+  }
+  const candidate = findKey(keyRing, parsed.kid);
+  if (!candidate) {
+    return err(authError.unknownState(`unknown state kid "${parsed.kid}"`));
+  }
+  const key = await importHmacKey(candidate.key, ["verify"]);
+  const okSig = await hmacVerify(key, sigBytes, payloadBytes);
+  if (!okSig) {
+    return err(authError.unknownState("state signature mismatch"));
+  }
+  if (parsed.kid !== candidate.kid) {
+    return err(authError.unknownState("state kid drift"));
+  }
+  return ok({
+    tenantId: asTenantId(parsed.tenantId),
+    flowId: parsed.flowId,
+    nonce: parsed.nonce,
+    kid: parsed.kid
+  });
+}
+function findKey(ring, kid) {
+  return ring.verify.find((k) => k.kid === kid);
+}
+function isEnvelopeShape(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const v = value;
+  return typeof v.tenantId === "string" && typeof v.flowId === "string" && typeof v.nonce === "string" && typeof v.kid === "string";
+}
+export {
+  verifyStateEnvelope,
+  mintStateEnvelope
+};