@foir/sdk 0.10.0 → 0.12.0

package/dist/server/read-dispatch.d.ts

@@ -0,0 +1,53 @@
+/**
+ * readDispatch: the body of an operation dispatch, parsed and checked.
+ *
+ * An operation endpoint is handed two things. The headers carry the dispatch
+ * token, which `requireScopedToken` verifies. The body carries the run: its id,
+ * the operation's key, how it was started, the context it runs in, and the
+ * caller's input under `input`. Reading the body as though it WERE the input is
+ * the mistake this exists to prevent, because it fails quietly: every field the
+ * endpoint looks for is absent, and the endpoint refuses every call on a
+ * missing field it was in fact sent.
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { expectedProjectId });
+ * const { input, context } = await readDispatch<{ email: string }>(request);
+ * const foir = createFoirClient({ apiUrl, dispatch, generated });
+ * ```
+ *
+ * The shape is the platform's `buildOperationPayload`, field for field; see
+ * `OperationPayload`. A body that is not that shape is refused with
+ * {@link OperationPayloadError}, naming what is wrong, rather than handed on
+ * half-read.
+ *
+ * What it does not do is drop fields. A key the platform adds later is kept on
+ * the returned object, untyped, because a reader that re-built the body from
+ * the fields it knows would delete whatever it did not, which is the exact way
+ * blocks of this payload have gone missing on their way to an endpoint before.
+ */
+import type { OperationPayload } from './operation-types';
+/**
+ * The dispatch body was not an operation payload. `status` is the HTTP status
+ * the route should answer with: 400, since the request is malformed rather than
+ * unauthorised (the token has already been verified by the time the body is
+ * read).
+ */
+export declare class OperationPayloadError extends Error {
+    readonly status: 400;
+    constructor(message: string);
+}
+/** The minimal request shape needed: satisfied by any fetch-API Request. */
+export interface BodyCarrier {
+    text(): Promise<string>;
+}
+/**
+ * Read the dispatch body off an operation request.
+ *
+ * `TInput` types `input`, as an assertion: the platform has already checked the
+ * input against the operation's input schema, and this is where the endpoint
+ * says what that schema is.
+ *
+ * Reads the body, so call it once per request and after nothing else has
+ * consumed it.
+ */
+export declare function readDispatch<TInput extends object = Record<string, unknown>>(request: BodyCarrier): Promise<OperationPayload<TInput>>;

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

@@ -16,9 +16,21 @@
  * });
  * ```
  *
- * 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:
+ * The verified token is also the endpoint's credential for calling Foir back.
+ * `dispatch` on the result is the token as a data-client credential, so the
+ * endpoint acts as the operation, with the capabilities the operation
+ * declared, and holds no key of its own. `generated` is the module
+ * `foir types --operation <key>` wrote for the operation:
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { expectedProjectId });
+ * const foir = createFoirClient({ apiUrl: env.PLATFORM_API_URL, dispatch, generated });
+ * ```
+ *
+ * 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) {
@@ -29,15 +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 {
@@ -60,12 +88,48 @@ 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;
     subject: ScopedTokenSubject;
     /** Parsed `X-Foir-Context` correlation metadata (empty when absent). */
     context: Record<string, string>;
+    /**
+     * The token this call verified, as the credential for a data client that
+     * calls Foir AS the operation:
+     * `createFoirClient({ apiUrl, dispatch, generated })`. It sends the token as
+     * `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;