@foir/sdk 0.11.0 → 0.12.0

package/dist/react.js

@@ -81,7 +81,12 @@ var FoirRequestError = class extends Error {
    * failed on the first attempt for an hour.
    */
   get retryable() {
-    if (this.status === void 0) return true;
+    if (this.status === void 0) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      return true;
+    }
     if (this.status === 429 || this.code === "RATE_LIMITED") return true;
     if (this.status >= 500) return true;
     return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
@@ -111,6 +116,7 @@ function refuseCredentialHeaders(extra) {
     }
   }
 }
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -135,6 +141,9 @@ function buildFoirHeaders(input) {
     if (input.orgUrl) {
       headers["X-Org-Url"] = input.orgUrl;
     }
+    if (input.visitorAddress) {
+      headers[FOIR_VISITOR_IP_HEADER] = input.visitorAddress;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -150,6 +159,26 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
+var FoirAuthDowngradedError = class extends FoirRequestError {
+  downgrade;
+  constructor(downgrade) {
+    super(
+      `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "customer token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
+    );
+    this.name = "FoirAuthDowngradedError";
+    this.downgrade = downgrade;
+  }
+};
+var FoirSessionExpiredError = class extends FoirRequestError {
+  constructor(options) {
+    super("[foir] the customer session has expired and could not be refreshed: sign in again", {
+      cause: options?.cause,
+      graphQLErrors: [{ message: "session expired", extensions: { code: "SESSION_EXPIRED" } }]
+    });
+    this.name = "FoirSessionExpiredError";
+  }
+};
 var warnedDowngrade = null;
 function reportAuthDowngrade(envelope) {
   const downgrade = envelope.extensions?.auth;
@@ -182,6 +211,9 @@ function answeredAnything(data) {
   return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
 }
 function readFoirEnvelope(json, options) {
+  if (options?.rejectDowngrade && json.extensions?.auth) {
+    throw new FoirAuthDowngradedError(json.extensions.auth);
+  }
   reportAuthDowngrade(json);
   refusePrunedDocument(json, options);
   if (json.errors?.length) {
@@ -700,6 +732,12 @@ function operationName(scope, op) {
 function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
+async function resolveVisitorAddress(config) {
+  const source = config.visitor;
+  const value = typeof source === "function" ? await source() : source;
+  const address = value?.trim();
+  return address ? address : void 0;
+}
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
   if (typeof source === "function") return await source() ?? void 0;
@@ -732,6 +770,7 @@ async function resolveFoirAuth(config) {
       bearerToken,
       orgId: config.orgId,
       orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
       extra: config.headers
     }),
     key: { apiKey: config.apiKey, bearerToken }
@@ -755,7 +794,33 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
+var renewing = /* @__PURE__ */ new WeakMap();
+function renewBearerOnce(refresh) {
+  const running = renewing.get(refresh);
+  if (running) return running;
+  const next = refresh().finally(() => renewing.delete(refresh));
+  renewing.set(refresh, next);
+  return next;
+}
 async function runFoirDocument(config, document2, mutation, variables, options) {
+  try {
+    return await sendFoirDocument(config, document2, mutation, variables, options);
+  } catch (err) {
+    const refresh = config.refreshBearer;
+    if (!(err instanceof FoirAuthDowngradedError) || !refresh || err.downgrade.reason === "wrong_project") {
+      throw err;
+    }
+    const token = err.downgrade.reason === "expired" ? await renewBearerOnce(refresh) : null;
+    if (!token) throw new FoirSessionExpiredError({ cause: err });
+    try {
+      return await sendFoirDocument({ ...config, bearerToken: token }, document2, mutation, variables, options);
+    } catch (again) {
+      if (again instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: again });
+      throw again;
+    }
+  }
+}
+async function sendFoirDocument(config, document2, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
   const { headers, key } = await resolveFoirAuth(config);
@@ -804,7 +869,7 @@ async function runFoirDocument(config, document2, mutation, variables, options)
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json, options);
+  return readFoirEnvelope(json, { ...options, rejectDowngrade: Boolean(key?.bearerToken) });
 }
 async function readErrorBody(res) {
   try {
@@ -970,6 +1035,9 @@ async function getAuthProviders(env) {
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
+  if (!result.customerId) {
+    return await getSessionCustomer(adapter) ?? { id: "", email: "" };
+  }
   await adapter.set(CUSTOMER_ID_KEY, result.customerId);
   await adapter.set(EMAIL_KEY, result.email);
   return { id: result.customerId, email: result.email };

package/dist/server/callback-client.d.ts

@@ -17,14 +17,21 @@
  *
  * Each call carries:
  *   - `Authorization: Bearer <callback.token>` — Ed25519 scoped token.
- *   - `X-Foir-Signature: sha256=<hex>` — HMAC of the raw request body
- *     keyed on the project's `operations.signing_secret`. The secret is
- *     out-of-band (CLI publishes it to the extension on push); the SDK
- *     only handles the HMAC computation.
+ *   - `X-Foir-Signature: sha256=<hex>` — HMAC of the raw request body, keyed
+ *     on the run's own key (`callback.signingKey`), which the platform makes
+ *     for each run and sends with it. An endpoint that still holds the
+ *     project's signing secret may pass it as `signingSecret` instead; the
+ *     platform accepts either.
+ *
+ * A call that fails before the platform answers, or that the platform answers
+ * with a 5xx or a 429, is tried again: a report that is lost leaves the run to
+ * be closed by the platform's watchdog as timed out, and every one of these
+ * calls is safe to repeat.
  *
  * Both response body shape and content-type follow the GraphQL spec —
  * extensions importing this client receive typed result data.
  */
+import { type FoirRetryPolicy } from '../transport/retry';
 import type { OperationCallback } from './operation-types.js';
 /** Shape of a successful response from any callback mutation. */
 export interface CallbackResult {
@@ -78,15 +85,29 @@ export interface CallbackClient<TResult = unknown> {
  * `callback`; pass them together so the SDK doesn't have to re-parse the
  * payload structure on every call.
  *
- * `signingSecret` lives on the extension (set as `FOIR_SIGNING_SECRET` or
- * equivalent env var). `foir push` writes it there from the project's
- * signing secret, so it's available before any callback runs.
+ * The signature is keyed on `callback.signingKey`, the run's own key, which
+ * the platform sends with every ASYNC dispatch. `signingSecret` is for an
+ * endpoint that holds the project's signing secret instead (`foir push`
+ * writes it to `FOIR_SIGNING_SECRET`); when it is passed it is the key used.
+ * One of the two must be there.
  *
  * `fetch` is overridable for testability and to support runtimes (CF
- * Workers, Node) where `fetch` may not be the global.
+ * Workers, Node) where `fetch` may not be the global. `retry` is how a call
+ * that got no answer, a 5xx or a 429 is tried again (three attempts unless
+ * told otherwise; `{ attempts: 1 }` turns it off).
+ *
+ * `apiUrl` is the Foir API origin the endpoint is configured with. The
+ * dispatch names the address to report to and that address is the one used; a
+ * platform with no public address of its own configured names none, and the
+ * run then reports to the data API at `apiUrl`.
  */
 export declare function createCallbackClient<TResult = unknown>(callback: OperationCallback, opts: {
     executionId: string;
-    signingSecret: string;
+    signingSecret?: string;
+    /** The Foir API origin, used when the dispatch names no address to report to. */
+    apiUrl?: string;
     fetch?: typeof fetch;
+    retry?: FoirRetryPolicy;
+    /** Aborts a call in flight, and the wait before a retry is not started. */
+    signal?: AbortSignal;
 }): CallbackClient<TResult>;

package/dist/server/continue-run.d.ts

@@ -0,0 +1,56 @@
+/**
+ * continueRun: answer one slice of an ASYNC run and ask to be called again.
+ *
+ * A run that takes longer than one call is cut into slices. Each dispatch does
+ * a bounded amount of work and then either answers `202 Accepted` and reports
+ * the outcome through the callback, as an ASYNC run always has, or answers a
+ * continuation: the cursor the next slice resumes from. The platform queues the
+ * next call, at once or after `delayMs`, and hands the cursor back as
+ * `continuation` on the dispatch body (`readDispatch` reads it). Each slice
+ * gets a fresh callback, so the one that finishes reports through its own.
+ *
+ * ```ts
+ * const payload = await readDispatch(request);
+ * const page = await syncOnePage(payload.continuation?.cursor);
+ * if (page.next) return continueRun({ cursor: page.next, progressPct: page.pct });
+ * await createCallbackClient(payload.callback!, { executionId, signingSecret }).complete(page.summary);
+ * return new Response(null, { status: 202 });
+ * ```
+ *
+ * Only an ASYNC run can continue: a caller waiting on a SYNC call cannot be
+ * answered by a later one, so the platform fails a SYNC call answered this
+ * way. A continuation is not a retry and does not spend the retry budget; a run
+ * takes at most 1000 slices, and one that asks for more is dead-lettered
+ * holding its last cursor, so a retry resumes from it.
+ *
+ * On the wire it is a 200 under {@link CONTINUATION_MEDIA_TYPE} with the
+ * continuation as the JSON body. The content type is what marks it, so a
+ * framework without fetch `Response` objects sends the same thing by setting
+ * that header and writing `JSON.stringify(continuation)`.
+ */
+/** The content type a continuation is answered under. */
+export declare const CONTINUATION_MEDIA_TYPE = "application/vnd.foir.continuation+json";
+/** The longest cursor the platform keeps, in bytes. */
+export declare const MAX_CONTINUATION_CURSOR_BYTES: number;
+/** The longest wait a continuation may ask for, in milliseconds. */
+export declare const MAX_CONTINUATION_DELAY_MS: number;
+/** What a slice answers when the run is not finished. */
+export interface Continuation {
+    /** Where the next slice resumes. Opaque to the platform, never empty. */
+    cursor: string;
+    /**
+     * How long to wait before the next slice, for a slice waiting on a third
+     * party, such as an export that finishes later. At most 15 minutes.
+     */
+    delayMs?: number;
+    /** Progress shown on the execution while it runs, 0 to 100. */
+    progressPct?: number;
+    /** A line shown beside the progress. */
+    progressMessage?: string;
+}
+/**
+ * Build the continuation answer. Throws, before anything is sent, on a
+ * continuation the platform would refuse, so the mistake surfaces in the
+ * endpoint rather than as a failed run.
+ */
+export declare function continueRun(continuation: Continuation): Response;

package/dist/server/index.d.ts

@@ -1,14 +1,16 @@
 export { createServerClient, ServerClientError } from './server-client';
 export { verifyWebhookSignature } from './webhook-helpers';
 export { verifyScopedToken, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, type ScopedTokenClaims, type ScopedTokenSubject, type VerifyScopedTokenOptions, } from './verify-scoped-token';
-export { requireScopedToken, ScopedTokenError, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
+export { createScopedTokenVerifier, ScopedTokenUnavailableError, type ScopedTokenVerifier, type ScopedTokenVerifierOptions, type ScopedTokenVerifierStats, } from './verify-scoped-token';
+export { requireScopedToken, ScopedTokenError, FOIR_TOKEN_HEADER, FOIR_CONTEXT_HEADER, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
 export { readDispatch, OperationPayloadError, type BodyCarrier, } from './read-dispatch';
 export type { ServerClient, ServerClientOptions, GraphQLResponse, EditorPlacement, } from './types';
-export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, } from './operation-types';
+export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, OperationContinuationBlock, } from './operation-types';
+export { continueRun, CONTINUATION_MEDIA_TYPE, MAX_CONTINUATION_CURSOR_BYTES, MAX_CONTINUATION_DELAY_MS, type Continuation, } from './continue-run';
 export { createCallbackClient } from './callback-client';
 export type { CallbackClient, CallbackResult } from './callback-client';
 export { createEventsClient, FoirEventCursorExpiredError, isFoirEventCursorExpired, FOIR_EVENTS_PATH, FOIR_EVENTS_SCOPE, FOIR_EVENTS_RETENTION_DAYS, } from './events-client';
 export type { FoirEvent, FoirEventActor, FoirEventPage, FoirEventRetention, FoirEventsClient, FoirEventsClientConfig, FoirEventsListParams, FoirEventsStreamParams, FoirEventsSubscribeParams, } from './events-client';
 export type { FoirSubscription, FoirSubscriptionHandlers } from '../data/ws-transport';
-export { FoirRequestError, isFoirForbidden, isFoirNotFound, isFoirRateLimited, isFoirUnauthenticated, } from '../transport/foir-http';
+export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, isFoirForbidden, isFoirNotFound, isFoirRateLimited, isFoirUnauthenticated, } from '../transport/foir-http';
 export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem, FoirAuthDowngrade, } from '../transport/foir-http';

package/dist/server/operation-types.d.ts

@@ -67,17 +67,32 @@ export interface OperationPayload<TInput extends object = Record<string, unknown
      * present to tell the two modes apart.
      */
     callback?: OperationCallback;
+    /**
+     * Where this slice of a run resumes. Present when the previous slice answered
+     * with `continueRun`: the cursor it answered, and which slice this is. Slice
+     * 0 is a run a dead-letter retry resumes. Absent on a run's first call.
+     */
+    continuation?: OperationContinuationBlock;
+}
+/** The dispatch body's continuation block (see `continueRun`). */
+export interface OperationContinuationBlock {
+    /** The cursor the previous slice answered, as it wrote it. */
+    cursor: string;
+    /** Which slice of the run this is. */
+    slice: number;
 }
 /**
- * Callback context the platform hands the extension when it dispatches an
- * async-callback operation. Everything the extension needs to call back is
- * here — endpoint, auth token, signing secret reference (the secret itself
- * lives on the extension, set out of band; the platform only sends the
- * token), and the per-op mutation names so the extension doesn't need to
- * derive them from the operation key.
+ * Callback context the platform hands the endpoint when it dispatches an
+ * ASYNC operation. Everything the endpoint needs to call back is here: the
+ * address, the token, the key this run signs with, and the per-operation
+ * mutation names, so the endpoint derives none of them from the operation key.
  */
 export interface OperationCallback {
-    /** api-public GraphQL endpoint, e.g. https://api.foir.dev/graphql */
+    /**
+     * The address to report to, e.g. https://api.foir.dev/graphql. Empty when the
+     * platform that dispatched has no public address of its own configured;
+     * `createCallbackClient` then reports to the `apiUrl` it is given.
+     */
     gqlEndpoint: string;
     /** Bearer token for the Authorization header (Ed25519, single execution scope) */
     token: string;
@@ -95,6 +110,12 @@ export interface OperationCallback {
      * run was caused by another operation's work.
      */
     causationChain?: string[];
+    /**
+     * The key this run signs its callbacks with, made by the platform for this
+     * run alone. `createCallbackClient` signs with it, so an endpoint holds no
+     * signing secret of its own. Treat it as a secret: never log or store it.
+     */
+    signingKey?: string;
 }
 /**
  * How a run was started. The four values are the platform's own; a caller that

package/dist/server/require-scoped-token.d.ts

@@ -27,9 +27,10 @@
  * const foir = createFoirClient({ apiUrl: env.PLATFORM_API_URL, dispatch, generated });
  * ```
  *
- * Throws {@link ScopedTokenError} with `status` 401 (missing/invalid token)
- * or 403 (valid token for the wrong tenant/project) — map it to a response
- * in one place:
+ * Throws {@link ScopedTokenError} with `status` 401 (missing/invalid token),
+ * 403 (valid token for the wrong tenant/project) or 503 (the token could not
+ * be checked, because a `verifier`'s keys could not be read) — map it to a
+ * response in one place:
  *
  * ```ts
  * catch (err) {
@@ -40,16 +41,31 @@
  * }
  * ```
  */
-import type { ScopedTokenClaims, ScopedTokenSubject, VerifyScopedTokenOptions } from './verify-scoped-token';
+import type { ScopedTokenClaims, ScopedTokenSubject, ScopedTokenVerifier, VerifyScopedTokenOptions } from './verify-scoped-token';
 import type { FoirDispatchCredential } from '../data/transport';
+/** The header the platform sends a dispatch's token in. */
+export declare const FOIR_TOKEN_HEADER = "X-Foir-Token";
+/** The header carrying a dispatch's context: which operation, how it was triggered, the run's id. */
+export declare const FOIR_CONTEXT_HEADER = "X-Foir-Context";
 /**
  * Verification failure with the HTTP status the route should answer with:
  * 401 for a missing or invalid token, 403 for a valid token bound to the
- * wrong tenant or project.
+ * wrong tenant or project, and 503 when the token could not be checked at all
+ * (a `verifier` whose keys could not be read and which holds none). The 503
+ * matters: the platform retries it, where a 401 fails the run for this
+ * server's own outage.
  */
 export declare class ScopedTokenError extends Error {
-    readonly status: 401 | 403;
-    constructor(message: string, status: 401 | 403);
+    readonly status: 401 | 403 | 503;
+    /**
+     * Why, for a route that answers the cases differently: `missing` (the
+     * request carried no token at all, so it did not come from the platform),
+     * `invalid` (a token that does not verify), `forbidden` (a valid token for
+     * another tenant or project) and `unavailable` (the token could not be
+     * checked).
+     */
+    readonly reason: 'missing' | 'invalid' | 'forbidden' | 'unavailable';
+    constructor(message: string, status: 401 | 403 | 503, reason?: 'missing' | 'invalid' | 'forbidden' | 'unavailable');
 }
 /** The minimal request shape needed — satisfied by any fetch-API Request. */
 export interface HeaderCarrier {
@@ -72,6 +88,13 @@ export interface RequireScopedTokenOptions extends VerifyScopedTokenOptions {
     expectedProjectId?: string;
     /** Tenant analogue of {@link expectedProjectId}. */
     expectedTenantId?: string;
+    /**
+     * Verify with this verifier's own key cache instead of fetching `jwksUrl`
+     * per isolate: see `createScopedTokenVerifier`. For a server that stays up
+     * and has to keep answering through a JWKS outage. `jwksUrl` and
+     * `expectedIssuer` are then the verifier's.
+     */
+    verifier?: ScopedTokenVerifier;
 }
 export interface ScopedTokenIngress {
     claims: ScopedTokenClaims;
@@ -85,6 +108,28 @@ export interface ScopedTokenIngress {
      * `X-Foir-Token` with the dispatch's `X-Foir-Context`, and never an api key.
      */
     dispatch: FoirDispatchCredential;
+    /**
+     * The organization the token acts at, as the platform signed it: the id of
+     * one organization, or the empty string for the project itself. `null` when
+     * the token states no level at all.
+     *
+     * An app installed at two organizations of one project is dispatched once
+     * for each, and this is what tells the two apart: name it, with the project,
+     * in anything you keep about one install. Treat `null` as a token you cannot
+     * place rather than as the project.
+     */
+    orgId: string | null;
+    /**
+     * The customer the run acts for, when it acts for one: the signed-in
+     * customer who ran the operation, or the owner of the record whose event
+     * fired it. Verified with the rest of the token, so it is the one to trust
+     * over anything in the input.
+     */
+    customerId?: string;
+    /** When the token stops being accepted. There is no refresh: finish, or report, before it. */
+    expiresAt: Date;
+    /** The token's own id (`jti`). The run's id on a dispatch that carries no other. */
+    tokenId: string;
 }
 /**
  * Verify the platform-minted scoped token on an inbound dispatch request.

package/dist/server/verify-scoped-token.d.ts

@@ -44,17 +44,31 @@ export interface ScopedTokenClaims {
      * a record write for a specific model.
      */
     rwm?: Array<string>;
+    /**
+     * The customer the token acts for, when it acts for one: the signed-in
+     * customer who ran the operation, or the owner of the record whose event
+     * fired it. `requireScopedToken` answers it as `customerId`.
+     */
+    cid?: string;
 }
 export interface ScopedTokenSubject {
     tenantId: string;
     projectId: string;
+    /**
+     * What the minting site put in the third segment: the app's name on an app's
+     * dispatch, the operation's key on a callback token, and empty on a token
+     * bound to the project and to no app. It names nothing reliably, so route on
+     * your own URL and never on this.
+     */
     appName: string;
 }
 /**
  * Parse the pipe-delimited `sub` claim emitted by the platform's
- * scoped-token minter into its three components. Throws on a missing or
- * empty segment — the platform never emits a partially-populated subject,
- * so a malformed sub indicates a forged or corrupt token.
+ * scoped-token minter into its three components, as the platform itself
+ * parses it: split on the first two pipes only, so the third segment keeps any
+ * pipe it holds. The tenant and the project are required, and a subject
+ * missing either is a forged or corrupt token. The third segment may be empty:
+ * a token bound to the project and to no app.
  *
  * @example
  * ```ts
@@ -98,3 +112,95 @@ export declare function verifyScopedToken(token: string, jwksUrl: string, option
  * `project=P;app=A;operation=O;triggered_by=T;execution_id=E;causation_chain=a,b,c`.
  */
 export declare function parseContextHeader(raw: string | null): Record<string, string>;
+/**
+ * The key set could not be read and none is cached, so the token could not be
+ * checked either way. Not a verdict on the token: answer 503, never 401. A 401
+ * tells the platform its own token was refused, which fails a run with no
+ * retry; a 503 is retried.
+ */
+export declare class ScopedTokenUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** How a {@link ScopedTokenVerifier}'s key cache is doing. */
+export interface ScopedTokenVerifierStats {
+    /** Keys currently held. 0 before the first successful fetch. */
+    keyCount: number;
+    /** How long ago the held set was fetched or confirmed, or null when none is held. */
+    ageMs: number | null;
+    /** Verifications answered from a set past its lifetime, because a refetch failed. */
+    staleServes: number;
+    /** Fetches that failed. */
+    refetchFailures: number;
+    /** Refetches the endpoint answered 304 to. */
+    notModified: number;
+}
+export interface ScopedTokenVerifierOptions extends VerifyScopedTokenOptions {
+    /** The platform's JWKS endpoint, e.g. `https://api.foir.dev/.well-known/jwks.json`. */
+    jwksUrl: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Extra init for the JWKS fetch, e.g. a runtime's own connection options. The signal is the verifier's. */
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'signal'>;
+    /** The deadline for one JWKS fetch, in milliseconds. Default 5000. */
+    timeoutMs?: number;
+    /** How long a fetched set is used before it is refreshed, in milliseconds. Default one hour. */
+    ttlMs?: number;
+    /** Injectable clock, in milliseconds since the epoch. */
+    now?: () => number;
+    /**
+     * Called when a refetch fails and the held set is served past its lifetime.
+     * For logging; must not throw.
+     */
+    onStale?: (info: {
+        error: unknown;
+        ageMs: number;
+        staleServes: number;
+    }) => void;
+}
+/**
+ * A scoped-token verifier with a key cache of its own, for a server that
+ * stays up for a long time and takes every dispatch through one process.
+ */
+export interface ScopedTokenVerifier {
+    /**
+     * Verify a token. Throws {@link ScopedTokenUnavailableError} when the keys
+     * cannot be read and none are held, and an ordinary Error naming the fault
+     * for a token that does not verify.
+     */
+    verify(token: string): Promise<ScopedTokenClaims>;
+    /** Fetch the keys now, so the first dispatch does not wait on it. Never throws. */
+    warm(): Promise<void>;
+    stats(): ScopedTokenVerifierStats;
+}
+/**
+ * Build a verifier that keeps answering when the JWKS endpoint does not.
+ *
+ * `verifyScopedToken` fetches the key set and caches it for five minutes, which
+ * suits a function that lives for one request. A server that lives for days
+ * needs the outage behaviour decided:
+ *
+ * - **A failed refetch serves the held keys**, for as long as it keeps failing.
+ *   Rotation adds keys, so a stale set can only lack a new key; it never accepts
+ *   a removed one for longer than the platform's own caches already do.
+ * - **Nothing held and nothing readable is `ScopedTokenUnavailableError`**, which
+ *   `requireScopedToken` answers as 503. A 401 there would refuse the
+ *   platform's own token over this server's outage.
+ * - **The fetch is bounded** (`timeoutMs`), so a host that accepts the
+ *   connection and goes quiet cannot hold every dispatch behind it, and **a
+ *   failure holds off the next attempt for a minute**, so an outage costs one
+ *   attempt a minute rather than one per request.
+ * - **An unknown key id refetches at once**, at most once a minute, so a
+ *   rotation is picked up without waiting out the lifetime and a flood of made
+ *   up key ids cannot become a flood of fetches.
+ * - **`If-None-Match` is sent**, so an unchanged set costs a 304.
+ *
+ * ```ts
+ * const verifier = createScopedTokenVerifier({ jwksUrl });
+ * await verifier.warm();
+ * // per request:
+ * const { subject, dispatch } = await requireScopedToken(request, { verifier });
+ * ```
+ */
+export declare function createScopedTokenVerifier(options: ScopedTokenVerifierOptions): ScopedTokenVerifier;