@oxy.so/core 7.15.1 → 7.17.0

package/src/server/callerAuthority.ts

@@ -0,0 +1,267 @@
+/**
+ * What every "may the person behind this request …?" read on `OxyServer`
+ * shares: which requests carry a person at all, the one failure type and its
+ * status mapping, the response envelope, and the positive-only answer cache.
+ *
+ * The readers built on it answer different questions — keep them apart:
+ *
+ * | Question | Reader |
+ * |---|---|
+ * | Does this person hold one of MY application's declared operator keys (`payments.operate`)? | `appPermissionsFor` (`./appPermissions`) |
+ * | What may this person do in Oxy account X (an organization, store, channel)? | `accountAccessFor` (`./callerAccess`) |
+ * | What may this person do to application A, through the account that owns it (`app:read`, `app:update`)? | `applicationAccessFor` (`./callerAccess`) |
+ *
+ * ## The outcome mapping, and why an outage is never a "no"
+ *
+ * Every reader asks Oxy with the request's OWN verified bearer and maps the
+ * answer the same way: a 401 means the session is gone (sign in again); a 403
+ * or 404 is Oxy's definitive refusal; anything else — a 5xx, a timeout, a
+ * malformed body — is UNAVAILABLE, answered 503. Only a positive answer is
+ * cached, so a blip can never be remembered as a refusal, and a refusal is
+ * never remembered at all (the next request asks again).
+ *
+ * Node only; reachable solely from `@oxy.so/core/server`.
+ */
+
+/** Entries kept per reader; the oldest goes first. */
+const CALLER_AUTHORITY_CACHE_MAX = 1000;
+
+/** The request fields a caller-authority read uses — all set by `middleware.auth()`. */
+export interface OxyCallerRequest {
+  userId?: string | null;
+  sessionId?: string | null;
+  accessToken?: string;
+  /** Set when the request is authenticated by a SERVICE token; such a request carries no person. */
+  serviceApp?: unknown;
+}
+
+/** The verified person behind a request. */
+export interface OxyCallerSession {
+  readonly userId: string;
+  readonly sessionId: string;
+  readonly accessToken: string;
+}
+
+/**
+ * The person behind `req`, or why there is none: `service` for a request
+ * authenticated by a service token (delegated or not — its bearer is the
+ * service's, never the person's), `missing` when `middleware.auth()` resolved
+ * no user session.
+ */
+export function readCallerSession(
+  req: OxyCallerRequest,
+): { ok: true; session: OxyCallerSession } | { ok: false; reason: 'service' | 'missing' } {
+  if (req.serviceApp) return { ok: false, reason: 'service' };
+  const { userId, sessionId, accessToken } = req;
+  if (
+    typeof userId !== 'string' ||
+    userId.length === 0 ||
+    typeof sessionId !== 'string' ||
+    sessionId.length === 0 ||
+    typeof accessToken !== 'string' ||
+    !isBearerToken(accessToken)
+  ) {
+    return { ok: false, reason: 'missing' };
+  }
+  return { ok: true, session: { userId, sessionId, accessToken } };
+}
+
+/** A bearer that can be put in an `Authorization` header unchanged. */
+export function isBearerToken(token: string): boolean {
+  return token.length > 0 && !/\s/.test(token);
+}
+
+/**
+ * - `ACCESS_SESSION_REQUIRED` — no person on the request (anonymous, or a
+ *   service token), or Oxy refused the session (401). Ask them to sign in.
+ * - `ACCESS_DENIED` — Oxy answered "no" (403, 404), or the answer lacks the
+ *   permission a gate required. Definitive.
+ * - `ACCESS_UNAVAILABLE` — Oxy could not be asked or gave no usable answer.
+ *   Fails closed, answered 503, never cached, never a "no".
+ */
+export type OxyAccessErrorCode = 'ACCESS_SESSION_REQUIRED' | 'ACCESS_DENIED' | 'ACCESS_UNAVAILABLE';
+
+/** The typed failure of `asUser`, `accountAccessFor`, `applicationAccessFor` and their middleware. */
+export class OxyAccessError extends Error {
+  readonly code: OxyAccessErrorCode;
+  /** The permission a gate required, when a gate refused. */
+  readonly permission: string | undefined;
+  /** The underlying failure (an `OxyApiError`), if any. Never sent to a client. */
+  readonly cause: unknown;
+
+  constructor(
+    code: OxyAccessErrorCode,
+    message: string,
+    options: { permission?: string; cause?: unknown } = {},
+  ) {
+    super(message);
+    this.name = 'OxyAccessError';
+    this.code = code;
+    this.permission = options.permission;
+    this.cause = options.cause;
+  }
+}
+
+/** What a refused request is answered with. */
+export type OxyAccessDenyStatus = 403 | 404;
+
+/**
+ * The status for an {@link OxyAccessError}: `deny` (default `403`) for a
+ * refusal; `401` for no session (`404` when `deny` is `404`, so a hidden
+ * surface stays hidden from the signed-out too); `503` when Oxy could not say.
+ */
+export function accessErrorStatus(
+  error: OxyAccessError,
+  deny: OxyAccessDenyStatus = 403,
+): 401 | 403 | 404 | 503 {
+  switch (error.code) {
+    case 'ACCESS_DENIED':
+      return deny;
+    case 'ACCESS_SESSION_REQUIRED':
+      return deny === 404 ? 404 : 401;
+    case 'ACCESS_UNAVAILABLE':
+      return 503;
+  }
+}
+
+/** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
+export function authorityErrorBody(status: number): {
+  error: { code: string; message: string };
+} {
+  switch (status) {
+    case 401:
+      return { error: { code: 'unauthorized', message: 'Authentication required' } };
+    case 403:
+      return { error: { code: 'forbidden', message: 'Not permitted' } };
+    case 404:
+      return { error: { code: 'not_found', message: 'Not found' } };
+    case 503:
+      return { error: { code: 'service_unavailable', message: 'Temporarily unavailable' } };
+    default:
+      return { error: { code: 'internal_error', message: 'Internal error' } };
+  }
+}
+
+/** The HTTP status an `OxyApiError` (or anything shaped like one) carries. */
+export function errorStatus(error: unknown): number | undefined {
+  const status = (error as { status?: unknown } | null)?.status;
+  return typeof status === 'number' ? status : undefined;
+}
+
+/**
+ * Map a failed caller-bearer read of Oxy to its outcome: 401 → session
+ * required, 403/404 → denied, everything else → unavailable.
+ */
+export function accessFailure(error: unknown, what: string): OxyAccessError {
+  const status = errorStatus(error);
+  if (status === 401) {
+    return new OxyAccessError(
+      'ACCESS_SESSION_REQUIRED',
+      `Oxy refused the session reading ${what}`,
+      {
+        cause: error,
+      },
+    );
+  }
+  if (status === 403 || status === 404) {
+    return new OxyAccessError('ACCESS_DENIED', `Oxy refused ${what} to this session`, {
+      cause: error,
+    });
+  }
+  return new OxyAccessError('ACCESS_UNAVAILABLE', `Could not read ${what} from Oxy`, {
+    cause: error,
+  });
+}
+
+interface CacheEntry<T> {
+  value: T;
+  userId: string;
+  startedAt: number;
+  expiresAt: number;
+}
+
+/**
+ * The positive-only answer cache one caller-authority reader keeps, keyed by
+ * (resource, session, person). Concurrent identical reads share one lookup; a
+ * `fresh` read skips the cache and refreshes it; a slower, OLDER answer never
+ * overwrites a newer one (the newer may be the fresh read that saw a
+ * revocation); a failure is never stored.
+ */
+export class CallerAuthorityCache<T> {
+  private readonly entries = new Map<string, CacheEntry<T>>();
+  private readonly pending = new Map<string, Promise<T>>();
+
+  /**
+   * @param ttlMs How long an answer is reused; `0` disables the cache.
+   * @param isAbout Whether a cached answer concerns `userId` beyond the
+   *   session's own user (an application-permissions answer names the
+   *   resolved operator), for {@link invalidate}.
+   */
+  constructor(
+    private readonly ttlMs: number,
+    private readonly isAbout: (value: T, userId: string) => boolean = () => false,
+  ) {}
+
+  async read(
+    resourceKey: readonly string[],
+    session: OxyCallerSession,
+    fresh: boolean,
+    lookup: () => Promise<T>,
+  ): Promise<T> {
+    const key = JSON.stringify([...resourceKey, session.sessionId, session.userId]);
+    const ttl = this.ttlMs;
+    if (!fresh && ttl > 0) {
+      const cached = this.entries.get(key);
+      if (cached && cached.expiresAt > Date.now()) return cached.value;
+      const inFlight = this.pending.get(key);
+      if (inFlight) return inFlight;
+    }
+
+    const startedAt = Date.now();
+    const answer = lookup().then((value) => {
+      if (ttl > 0) this.remember(key, session.userId, value, startedAt, ttl);
+      return value;
+    });
+    if (fresh || ttl <= 0) return answer;
+
+    this.pending.set(key, answer);
+    try {
+      return await answer;
+    } finally {
+      if (this.pending.get(key) === answer) this.pending.delete(key);
+    }
+  }
+
+  /** Forget every answer, or those about one person. */
+  invalidate(filter: { userId?: string } = {}): void {
+    const { userId } = filter;
+    if (!userId) {
+      this.entries.clear();
+      return;
+    }
+    for (const [key, entry] of this.entries) {
+      if (entry.userId === userId || this.isAbout(entry.value, userId)) this.entries.delete(key);
+    }
+  }
+
+  private remember(key: string, userId: string, value: T, startedAt: number, ttl: number): void {
+    const existing = this.entries.get(key);
+    if (existing && existing.startedAt > startedAt) return;
+    this.entries.delete(key);
+    this.entries.set(key, { value, userId, startedAt, expiresAt: startedAt + ttl });
+    if (this.entries.size > CALLER_AUTHORITY_CACHE_MAX) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest !== undefined) this.entries.delete(oldest);
+    }
+  }
+}
+
+/** A frozen, sorted permission set with `has`. */
+export function permissionSet(permissions: readonly string[]): {
+  readonly permissions: readonly string[];
+  has(permission: string): boolean;
+} {
+  const sorted = Object.freeze([...new Set(permissions)].sort());
+  const held = new Set(sorted);
+  return { permissions: sorted, has: (permission: string) => held.has(permission) };
+}

package/src/server/capabilityTicket.ts

@@ -29,11 +29,28 @@ export interface CapabilityTicketVerificationOptions {
   maximumTtlSeconds?: number;
 }
 
+/**
+ * A signing-key lookup that may be asynchronous — `createOxyJwksKeyResolver`
+ * is — for the verifiers that already run asynchronously (the middleware and
+ * `createLiveCapabilityTicketVerifier`). The ticket's own `kid` is passed; no
+ * caller needs to decode the header first.
+ */
+export type CapabilityTicketKeyResolver = (
+  keyId: string,
+) => KeyObject | undefined | Promise<KeyObject | undefined>;
+
+/** {@link CapabilityTicketVerificationOptions} with a key lookup that may be asynchronous. */
+export interface AsyncCapabilityTicketVerificationOptions
+  extends Omit<CapabilityTicketVerificationOptions, 'resolvePublicKey'> {
+  resolvePublicKey: CapabilityTicketKeyResolver;
+}
+
 export interface CapabilityTicketRequest extends Request {
   capabilityTicket?: CapabilityTicketClaims;
 }
 
-export interface CapabilityTicketMiddlewareOptions extends CapabilityTicketVerificationOptions {
+export interface CapabilityTicketMiddlewareOptions
+  extends AsyncCapabilityTicketVerificationOptions {
   authorize: (claims: CapabilityTicketClaims) => Promise<PolicyDecision>;
 }
 
@@ -99,10 +116,15 @@ export function issueCapabilityTicket(
   return `${signingInput}.${base64UrlEncode(signBytes(null, Buffer.from(signingInput), options.privateKey))}`;
 }
 
-export function verifyCapabilityTicket(
-  token: string,
-  options: CapabilityTicketVerificationOptions,
-): CapabilityTicketClaims {
+/** A ticket split and its header checked, before any key is looked up. */
+interface ParsedCapabilityTicket {
+  readonly keyId: string;
+  readonly signingInput: string;
+  readonly encodedPayload: string;
+  readonly encodedSignature: string;
+}
+
+function parseCapabilityTicket(token: string): ParsedCapabilityTicket {
   const segments = token.split('.');
   if (segments.length !== 3) {
     throw new CapabilityTicketError('malformed', 'Capability ticket must have three segments');
@@ -126,28 +148,34 @@ export function verifyCapabilityTicket(
   ) {
     throw new CapabilityTicketError('malformed', 'Capability ticket header is not supported');
   }
-  const publicKey = options.resolvePublicKey(headerRecord.kid);
+  return {
+    keyId: headerRecord.kid,
+    signingInput: `${encodedHeader}.${encodedPayload}`,
+    encodedPayload,
+    encodedSignature,
+  };
+}
+
+/** Signature and claims of a parsed ticket against the key its `kid` resolved to. */
+function checkCapabilityTicket(
+  ticket: ParsedCapabilityTicket,
+  publicKey: KeyObject | undefined,
+  options: Omit<CapabilityTicketVerificationOptions, 'resolvePublicKey'>,
+): CapabilityTicketClaims {
   if (!publicKey || publicKey.asymmetricKeyType !== 'ed25519') {
     throw new CapabilityTicketError('unknown_key', 'Capability ticket signing key is not trusted');
   }
   let providedSignature: Buffer;
   try {
-    providedSignature = Buffer.from(encodedSignature, 'base64url');
+    providedSignature = Buffer.from(ticket.encodedSignature, 'base64url');
   } catch {
     throw new CapabilityTicketError('malformed', 'Capability ticket signature is malformed');
   }
-  if (
-    !verifyBytes(
-      null,
-      Buffer.from(`${encodedHeader}.${encodedPayload}`),
-      publicKey,
-      providedSignature,
-    )
-  ) {
+  if (!verifyBytes(null, Buffer.from(ticket.signingInput), publicKey, providedSignature)) {
     throw new CapabilityTicketError('invalid_signature', 'Capability ticket signature is invalid');
   }
 
-  const parsed = capabilityTicketClaimsSchema.safeParse(decodeJsonSegment(encodedPayload));
+  const parsed = capabilityTicketClaimsSchema.safeParse(decodeJsonSegment(ticket.encodedPayload));
   if (!parsed.success) {
     throw new CapabilityTicketError('invalid_claims', 'Capability ticket claims are invalid');
   }
@@ -179,6 +207,37 @@ export function verifyCapabilityTicket(
   return claims;
 }
 
+export function verifyCapabilityTicket(
+  token: string,
+  options: CapabilityTicketVerificationOptions,
+): CapabilityTicketClaims {
+  const ticket = parseCapabilityTicket(token);
+  return checkCapabilityTicket(ticket, options.resolvePublicKey(ticket.keyId), options);
+}
+
+/**
+ * A verifier for one ticket whose key lookup may be asynchronous: the key is
+ * resolved once, and the returned `check` re-verifies signature and claims
+ * against it (the live verifier checks again after introspection, so a slow
+ * authority answer cannot outlive the ticket).
+ *
+ * @internal Shared by the middleware and `createLiveCapabilityTicketVerifier`.
+ */
+export async function resolveCapabilityTicketKey(
+  token: string,
+  options: AsyncCapabilityTicketVerificationOptions,
+): Promise<{ check: () => CapabilityTicketClaims }> {
+  const ticket = parseCapabilityTicket(token);
+  let publicKey: KeyObject | undefined;
+  try {
+    publicKey = await options.resolvePublicKey(ticket.keyId);
+  } catch {
+    // A key set that cannot be read trusts no key; never a different error class.
+    publicKey = undefined;
+  }
+  return { check: () => checkCapabilityTicket(ticket, publicKey, options) };
+}
+
 export function readCapabilityAuthorization(authorization: string | undefined): string | null {
   if (!authorization) return null;
   const [scheme, token, extra] = authorization.trim().split(/\s+/);
@@ -203,7 +262,7 @@ export function createCapabilityTicketMiddleware(
 
     let claims: CapabilityTicketClaims;
     try {
-      claims = verifyCapabilityTicket(token, options);
+      claims = (await resolveCapabilityTicketKey(token, options)).check();
     } catch (error) {
       const code = error instanceof CapabilityTicketError ? error.code : 'invalid_claims';
       response.status(401).json({ error: 'invalid_capability_ticket', code });

package/src/server/cors.ts

@@ -197,6 +197,67 @@ export function matchesAllowedOrigin(explicit: ReadonlySet<string>, origin: stri
   return isOxyFamilyOrigin(normalized);
 }
 
+/**
+ * The origin predicate `createOxyCors` applies, for any other transport that
+ * must admit the same browsers: the built-in HTTPS Oxy apex family plus the
+ * exact `appOrigins`, never an opaque origin (`exp://`, `file:`, …).
+ *
+ * ```ts
+ * const allowed = createOxyOriginCheck(['https://app.example.com']);
+ * allowed('https://mention.oxy.so'); // true
+ * ```
+ */
+export function createOxyOriginCheck(appOrigins: string[] = []): (origin: string) => boolean {
+  const explicit = normalizeAppOrigins(appOrigins);
+  return (origin: string) => matchesAllowedOrigin(explicit, origin);
+}
+
+/** Options of {@link createOxySocketCors}. */
+export interface OxySocketCorsOptions {
+  /** Explicit additional allowed origins, as {@link OxyCorsOptions.appOrigins}. */
+  appOrigins?: string[];
+  /** Whether the polling transport sends `Access-Control-Allow-Credentials: true`. Default `true`. */
+  allowCredentials?: boolean;
+}
+
+/**
+ * The Socket.IO server options that admit exactly the origins `createOxyCors`
+ * admits — spread them into `new Server(httpServer, { ...createOxySocketCors(…) })`.
+ *
+ * Two halves, because Socket.IO has two transports: `cors` answers the
+ * long-polling requests (which browsers check), and `allowRequest` refuses a
+ * handshake from any other browser origin, which is the only check a WebSocket
+ * upgrade gets — browsers apply no CORS to it. A request with no `Origin`
+ * header (a native app, a server) is not a browser cross-origin request and is
+ * admitted; authenticate it with `oxy.middleware.socket()` as every socket.
+ */
+export function createOxySocketCors(options: OxySocketCorsOptions = {}): {
+  cors: {
+    origin: (
+      origin: string | undefined,
+      callback: (error: Error | null, allow?: boolean) => void,
+    ) => void;
+    credentials: boolean;
+    methods: string[];
+  };
+  allowRequest: (
+    req: { headers: Record<string, string | string[] | undefined> },
+    callback: (error: string | null | undefined, success: boolean) => void,
+  ) => void;
+} {
+  const allowed = createOxyOriginCheck(options.appOrigins);
+  const admits = (origin: string | string[] | undefined): boolean =>
+    origin === undefined || (typeof origin === 'string' && (origin === '' || allowed(origin)));
+  return {
+    cors: {
+      origin: (origin, callback) => callback(null, admits(origin)),
+      credentials: options.allowCredentials ?? true,
+      methods: ['GET', 'POST'],
+    },
+    allowRequest: (req, callback) => callback(null, admits(req.headers.origin)),
+  };
+}
+
 /**
  * Create a strict Oxy CORS middleware. See module docs.
  *
@@ -215,7 +276,7 @@ export function createOxyCors(options: OxyCorsOptions = {}): RequestHandler {
     maxAgeSeconds = DEFAULT_MAX_AGE_SECONDS,
   } = options;
 
-  const explicitOrigins = normalizeAppOrigins(appOrigins);
+  const allowed = createOxyOriginCheck(appOrigins);
   const methodsHeader = methods.join(', ');
   const allowedHeadersHeader = allowedHeaders.join(', ');
   const exposedHeadersHeader = exposedHeaders.join(', ');
@@ -237,7 +298,7 @@ export function createOxyCors(options: OxyCorsOptions = {}): RequestHandler {
     // Origin is present. Caching correctness: this response varies by Origin.
     res.setHeader('Vary', 'Origin');
 
-    if (!matchesAllowedOrigin(explicitOrigins, origin)) {
+    if (!allowed(origin)) {
       // DENY: do NOT reflect the origin, do NOT emit a wildcard. The browser
       // will block the cross-origin read. Preflights for denied origins get a
       // 204 with no CORS headers (the actual request then fails CORS).

package/src/server/index.ts

@@ -4,14 +4,33 @@
  * This subpath export provides Express middleware and Node.js-specific
  * utilities that are not available in React Native or browser environments.
  *
+ * One `OxyServer` per process, authenticated as the backend's own workload
+ * (ADR 0026/0049 — no api key, no client secret):
+ *
  * @example
  * ```ts
- * import { OxyServer, createOxyAuthMiddleware, createOxyRateLimit } from '@oxy.so/core/server';
+ * import {
+ *   OxyServer,
+ *   createOxyAuthMiddleware,
+ *   createOxyCors,
+ *   createOxyRateLimit,
+ *   createOxySecurityHeaders,
+ *   oxyTrustProxy,
+ * } from '@oxy.so/core/server';
  *
- * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', serviceAuth: { apiKey, apiSecret } });
+ * export const oxy = new OxyServer({
+ *   baseURL: process.env.OXY_API_URL ?? 'https://api.oxy.so',
+ *   applicationId: process.env.OXY_APPLICATION_ID,
+ *   serviceIdentity: 'when-anonymous',
+ * });
  *
+ * app.set('trust proxy', oxyTrustProxy);
+ * app.use(createOxySecurityHeaders(), createOxyCors({ appOrigins }));
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * app.use('/api', createOxyAuthMiddleware(oxy));
+ *
+ * // As the person behind the request, never on the shared client:
+ * const node = await oxy.withUser(req, (user) => user.accounts.get(accountId));
  * ```
  */
 
@@ -24,6 +43,17 @@ export {
   DEFAULT_SERVICE_TOKEN_AUDIENCE,
 } from './OxyServer';
 export type { OxyServerConfig, ServiceTokenAudience, ServiceTokenResponse } from './OxyServer';
+// The requesting person: an isolated client bound to their bearer, and what
+// they may do in an account or over an application (with typed outcomes).
+export { OxyUserClient } from './userClient';
+export type { OxyUserSource } from './userClient';
+export { OxyAccessError, accessErrorStatus } from './callerAuthority';
+export type { OxyAccessDenyStatus, OxyAccessErrorCode, OxyCallerRequest } from './callerAuthority';
+export type {
+  CallerAccessOptions,
+  OxyAccountAccess,
+  OxyApplicationAccess,
+} from './callerAccess';
 export {
   ServerAccountsApi,
   ServerAppsApi,
@@ -53,6 +83,7 @@ export type {
   CapabilityTicketGrant,
   CapabilityTicketIntrospection,
   CreateExecutionAuthorizationInput,
+  ServiceCallOptions,
   ServiceCapabilityCatalog,
   ServiceUploadBody,
   ServiceUploadDescription,
@@ -77,6 +108,7 @@ export type {
   OxyAccountEventFeedItem,
   OxyAccountEventFeedPage,
   OxyMiddleware,
+  RequireAccessOptions,
   ServiceActingAsVerification,
   ServiceApp,
   VerifyAccountEventOptions,
@@ -186,8 +218,8 @@ export type {
 } from './largeUpload';
 
 // Strict CORS allowlist (Oxy apex family + explicit app origins).
-export { createOxyCors } from './cors';
-export type { OxyCorsOptions } from './cors';
+export { createOxyCors, createOxyOriginCheck, createOxySocketCors } from './cors';
+export type { OxyCorsOptions, OxySocketCorsOptions } from './cors';
 
 // Shared Helmet + Content-Security-Policy baseline (Cloudflare Insights beacon,
 // Oxy API/CDN origins) with additive, per-app extensions.
@@ -224,6 +256,8 @@ export {
   verifyCapabilityTicket,
 } from './capabilityTicket';
 export type {
+  AsyncCapabilityTicketVerificationOptions,
+  CapabilityTicketKeyResolver,
   CapabilityTicketMiddlewareOptions,
   CapabilityTicketRequest,
   CapabilityTicketSigningOptions,

package/src/server/liveCapabilityTicket.ts

@@ -4,12 +4,17 @@ import {
   type CapabilityTicketClaims,
 } from '@oxy.so/contracts';
 import {
-  verifyCapabilityTicket,
-  type CapabilityTicketVerificationOptions,
+  resolveCapabilityTicketKey,
+  type AsyncCapabilityTicketVerificationOptions,
 } from './capabilityTicket';
 import type { CapabilityTicketIntrospection } from './namespaces';
 
-export interface LiveCapabilityTicketVerifierOptions extends CapabilityTicketVerificationOptions {
+/**
+ * `resolvePublicKey` may be asynchronous — pass `createOxyJwksKeyResolver({ jwksUrl })`
+ * as it is; the ticket's `kid` is looked up once per verification.
+ */
+export interface LiveCapabilityTicketVerifierOptions
+  extends AsyncCapabilityTicketVerificationOptions {
   issuer: string;
   introspect: (
     ticket: string,
@@ -32,7 +37,9 @@ export function createLiveCapabilityTicketVerifier(options: LiveCapabilityTicket
     input: { signal?: AbortSignal } = {},
   ): Promise<CapabilityTicketClaims> => {
     input.signal?.throwIfAborted();
-    const signed = verifyCapabilityTicket(ticket, options);
+    const verifier = await resolveCapabilityTicketKey(ticket, options);
+    input.signal?.throwIfAborted();
+    const signed = verifier.check();
     if (!signed.catalog) throw new Error('Internal MCP requires a signed catalogue binding');
     const controller = new AbortController();
     const abort = () => controller.abort(input.signal?.reason);
@@ -59,7 +66,7 @@ export function createLiveCapabilityTicketVerifier(options: LiveCapabilityTicket
       if (canonicalCapabilityJson(live) !== canonicalCapabilityJson(signed))
         throw new Error('Capability introspection claims mismatch');
       // An authority response delayed past expiry cannot extend the signed grant.
-      return verifyCapabilityTicket(ticket, options);
+      return verifier.check();
     } finally {
       clearTimeout(timer);
       input.signal?.removeEventListener('abort', abort);