@farthershore/backend/testing exports

Import from @farthershore/backend/testing. This reference is extracted from the published declaration surface for version 0.21.2. Read the collection's guides for workflows, prerequisites and failure handling.

assertNotProduction

Throw {@link DevModeInProductionError} when `NODE_ENV=production`. Call at the
TOP of every dev-runtime constructor. `context` names the entry point for the
error message (e.g. "createDevRuntime", "FS_DEV_MODE").

Declaration source: packages/backend/dist/types/testing/prodGuard.d.ts#L12.

export declare function assertNotProduction(context: string, env?: Record<string, string | undefined>): void;

AuthzDecisionEntry

Public export AuthzDecisionEntry.

Declaration source: packages/backend/dist/types/testing/traceSink.d.ts#L3.

export type AuthzDecisionEntry = {
    permission: string;
    decision: "allow" | "deny";
    reason?: string;
};

buildPersonaMap

Merge caller personas over the built-in defaults into a name→def map.

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L90.

export declare function buildPersonaMap(overrides?: Record<string, PersonaDefinition> | PersonaDefinition[]): Map<string, PersonaDefinition>;

CONTEXT_HEADER_NAME

The header name for the signed context (exported for assertions).

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L92.

declare const CONTEXT_HEADER_NAME = "x-fs-context";

createDevGateway

Build the in-process dev gateway. `mode` drives `verification.required`:
`passthrough` → false (the adapter passes requests through unverified, matching
the pre-keystone deploy order), `simulated` → true (fail-closed verification is
exercised end-to-end).

Declaration source: packages/backend/dist/types/testing/devGateway.d.ts#L40.

export declare function createDevGateway(options: DevGatewayOptions): DevGateway;

createDevRuntime

Build a dev runtime: a real `FartherShore` wired to the in-process gateway and
signed personas, plus assertable usage/trace side channels.

Declaration source: packages/backend/dist/types/testing/devRuntime.d.ts#L71.

export declare function createDevRuntime(options: CreateDevRuntimeOptions): DevRuntime;

createDevRuntimeFromEnv

Self-construct the dev simulator from the environment. Called by `initFromEnv`
when `FS_DEV_MODE` is set. Prints a LOUD banner, wires JSONL usage/trace sinks
+ a mode-600 dev-keys file, and returns the augmented runtime.

Declaration source: packages/backend/dist/types/testing/devRuntime.d.ts#L79.

export declare function createDevRuntimeFromEnv(env?: Record<string, string | undefined>): FartherShoreDevInstance;

CreateDevRuntimeOptions

Public export CreateDevRuntimeOptions.

Declaration source: packages/backend/dist/types/testing/devRuntime.d.ts#L30.

export type CreateDevRuntimeOptions = {
    mode: DevMode;
    /** Persona overrides merged over the built-in owner/admin/member/anonymous. */
    personas?: Record<string, PersonaDefinition> | PersonaDefinition[];
    /** Route ids to expose in bootstrap (for route-binding tests). */
    routes?: string[];
    /** Meter keys (informational — the dev gateway accepts any meter). */
    meters?: string[];
    businessId?: string;
    backendId?: string;
    /** Optional app transport for persona `.fetch()`; defaults to global fetch. */
    appFetch?: typeof fetch;
    /** Reuse a fixed key set (cross-process). Defaults to a fresh ephemeral set. */
    keys?: DevSignerKeys;
};

createPersonaClient

Build a persona client bound to a set of dev keys + bootstrap ids. Returns an
`asPersona(name)` factory. Constructed by the dev runtime; also constructible
standalone from a dev-keys file (see `personaClientFromKeysFile`).

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L85.

export declare function createPersonaClient(ctx: PersonaClientContext): {
    asPersona(name: string): PersonaRequest;
    personas: Map<string, PersonaDefinition>;
};

DEFAULT_KEYS_FILE

Public export DEFAULT_KEYS_FILE.

Declaration source: packages/backend/dist/types/testing/keysFile.d.ts#L4.

declare const DEFAULT_KEYS_FILE = ".farthershore/dev-keys.json";

DEFAULT_PERSONAS

The four built-in personas: owner / admin / member / anonymous.

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L34.

declare const DEFAULT_PERSONAS: Record<string, PersonaDefinition>;

definePersona

Identity-neutral pass-through of a persona definition (readability sugar).

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L32.

export declare function definePersona(def: PersonaDefinition): PersonaDefinition;

DEV_CORE_URL

Public export DEV_CORE_URL.

Declaration source: packages/backend/dist/types/testing/devGateway.d.ts#L4.

declare const DEV_CORE_URL = "https://dev-gateway.farthershore.local";

DEV_JWKS_URL

Public export DEV_JWKS_URL.

Declaration source: packages/backend/dist/types/testing/devGateway.d.ts#L5.

declare const DEV_JWKS_URL = "https://dev-gateway.farthershore.local/.well-known/jwks.json";

DEV_METERING_ENDPOINT

Public export DEV_METERING_ENDPOINT.

Declaration source: packages/backend/dist/types/testing/devGateway.d.ts#L6.

declare const DEV_METERING_ENDPOINT = "https://dev-gateway.farthershore.local/v1/metering/events";

DevGateway

Public export DevGateway.

Declaration source: packages/backend/dist/types/testing/devGateway.d.ts#L21.

export type DevGateway = {
    /** Inject this as `fetchImpl` when constructing the FartherShore runtime. */
    fetchImpl: typeof fetch;
    /** The bootstrap response this fixture serves. */
    bootstrap: RuntimeBootstrapResponse__aecc7a0d671f;
    /** Every captured background metering event (a capture == an ACK). */
    meterEvents: RuntimeMeteringEvent__418138753c49[];
    /** Every captured attested post-stream usage report. */
    reportUsageEvents: RuntimePostStreamUsageEvent__1827aaa16965[];
    businessId: string;
    backendId: string;
    jwksUrl: string;
};

DevGatewayOptions

Public export DevGatewayOptions.

Declaration source: packages/backend/dist/types/testing/devGateway.d.ts#L7.

export type DevGatewayOptions = {
    mode: DevMode;
    keys: DevSignerKeys;
    businessId?: string;
    backendId?: string;
    businessSlug?: string;
    backendSlug?: string;
    /** Extra route ids to expose in bootstrap for route-binding tests. */
    routeIds?: string[];
    /** Called for each captured metering event (at-least-once ACK). */
    onMeterEvent?: (event: RuntimeMeteringEvent__418138753c49) => void;
    /** Called for each captured attested post-stream report. */
    onReportUsage?: (event: RuntimePostStreamUsageEvent__1827aaa16965) => void;
};

DevKeysFile

The on-disk shape of the dev-keys handoff file.

Declaration source: packages/backend/dist/types/testing/keysFile.d.ts#L6.

export type DevKeysFile = {
    version: 1;
    mode: DevMode;
    keys: DevSignerKeys;
    businessId: string;
    backendId: string;
    /** Persona definitions in effect for this dev session. */
    personas: Record<string, PersonaDefinition>;
};

DevMode

Public export DevMode.

Declaration source: packages/backend/dist/types/testing/traceSink.d.ts#L1.

export type DevMode = "passthrough" | "simulated";

devModeFromEnv

Whether `FS_DEV_MODE` selects a dev mode. Returns the mode or null.

Declaration source: packages/backend/dist/types/testing/devRuntime.d.ts#L73.

export declare function devModeFromEnv(env: Record<string, string | undefined>): DevMode | null;

DevModeInProductionError

Thrown when a dev runtime is constructed in a production process.

Declaration source: packages/backend/dist/types/testing/prodGuard.d.ts#L4.

export declare class DevModeInProductionError extends Error {
    constructor(context: string);
}

DevRuntime

The dev harness returned by `createDevRuntime` and attached as `fs.dev`.

Declaration source: packages/backend/dist/types/testing/devRuntime.d.ts#L46.

export type DevRuntime = {
    fs: FartherShoreDevInstance;
    asPersona(name: string): PersonaRequest;
    usage: DevUsageSink;
    trace: DevTraceSink;
    gateway: DevGateway;
    keys: DevSignerKeys;
    personas: Map<string, PersonaDefinition>;
    mode: DevMode;
    bootstrap: DevGateway["bootstrap"];
    /** Traced authz helpers — delegate to the REAL permission functions and
     *  record each decision into the trace (keyed by ctx.requestId). */
    authz: {
        hasPermission(ctx: TracedCarrier, key: string): boolean;
        requirePermission(ctx: TracedCarrier, key: string): void;
    };
    /** A trace-aware Express middleware (wraps the real fail-closed middleware). */
    middleware(options?: MiddlewareOptions__b16fbb0c44c2): ExpressMiddleware__416c4ad228c7;
    /** Clear usage + trace + captured meter events. */
    reset(): void;
};

DevSignerKeys

Public export DevSignerKeys.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L80.

export type DevSignerKeys = {
    /** Ed25519 signing keypair as JWKs (request-signature keys). */
    kid: string;
    privateJwk: JsonWebKey;
    publicJwk: JsonWebKey;
    /** HS256 context-signing secret + its kid (X-Fs-Context keys). */
    contextKid: string;
    contextSecret: string;
    /** Ephemeral fsrt_test_ runtime token (bootstrap bearer + metering HMAC). */
    runtimeToken: string;
};

DevTrace

Public export DevTrace.

Declaration source: packages/backend/dist/types/testing/traceSink.d.ts#L12.

export type DevTrace = {
    requestId: string;
    method?: string;
    path?: string;
    persona?: string;
    mode: DevMode;
    verification?: {
        outcome: VerificationOutcome;
        reason?: string;
    };
    authz: AuthzDecisionEntry[];
    metering: MeteringTraceEntry[];
    response?: {
        status: number;
    };
};

DevTraceSink

Accumulates one `DevTrace` per request id and (optionally) appends each
completed trace as a single JSONL line via the injected `appendLine` sink.

Declaration source: packages/backend/dist/types/testing/traceSink.d.ts#L34.

export declare class DevTraceSink {
    private readonly traces;
    private readonly flushed;
    private readonly appendLine?;
    constructor(options?: {
        appendLine?: (line: string) => void;
    });
    private ensure;
    /** Record how a request's signature/context verification resolved. */
    recordVerification(requestId: string, mode: DevMode, outcome: VerificationOutcome, fields?: {
        method?: string;
        path?: string;
        persona?: string;
        reason?: string;
    }): void;
    /** Record a single hasPermission / requirePermission decision. */
    recordAuthz(requestId: string, mode: DevMode, entry: AuthzDecisionEntry): void;
    /** Record usage reported for this request. */
    recordMetering(requestId: string, mode: DevMode, entry: MeteringTraceEntry): void;
    /** Record the final response status and flush the trace as one JSONL line. */
    recordResponse(requestId: string, mode: DevMode, status: number): void;
    /**
     * Append a trace's current state as one JSONL line (if a sink is wired).
     * Flushes at most ONCE per request id, so wrapping several response methods
     * (status/json/end) never produces duplicate JSONL lines.
     */
    flush(requestId: string): void;
    /** The accumulated trace for a request id, or `undefined`. */
    forRequest(requestId: string): DevTrace | undefined;
    /** Every accumulated trace (insertion order). */
    all(): DevTrace[];
    /** Clear all traces. */
    reset(): void;
}

DevUsageEvent

One recorded usage observation. `source` distinguishes the two channels.

Declaration source: packages/backend/dist/types/testing/usageSink.d.ts#L3.

export type DevUsageEvent = {
    source: "response";
    /** rawDimsUnits from the signed response-metering payload. */
    meters: Record<string, number>;
    /** The full response-metering payload (method/path/rawDimsUnits/…). */
    payload: Record<string, unknown>;
    /** The gateway request id this usage was reported against, when known. */
    requestId?: string;
    at: number;
} | {
    source: "meter";
    /** `{ [meter]: qty }` for a single background metering event. */
    meters: Record<string, number>;
    event: RuntimeMeteringEvent__418138753c49;
    requestId?: string;
    at: number;
} | {
    source: "reportUsage";
    meters: Record<string, number>;
    event: RuntimePostStreamUsageEvent__1827aaa16965;
    requestId: string;
    at: number;
};

DevUsageSink

In-memory, assertable sink for all dev usage.

Declaration source: packages/backend/dist/types/testing/usageSink.d.ts#L27.

export declare class DevUsageSink {
    readonly events: DevUsageEvent[];
    /** Record a signed response-metering payload (report() in-band / computeMeteringHeaders). */
    recordResponse(payload: Record<string, unknown>, requestId?: string): void;
    /** Record a background `fs.meter()` event captured by the dev gateway. */
    recordMeterEvent(event: RuntimeMeteringEvent__418138753c49): void;
    /** Record an attested post-stream report captured by the dev gateway. */
    recordReportUsage(event: RuntimePostStreamUsageEvent__1827aaa16965): void;
    /** Total quantity per meter key across every recorded event. */
    byMeter(): Record<string, number>;
    /** Clear all recorded usage. */
    reset(): void;
}

FartherShoreDevInstance

The FartherShore instance augmented with a bound Express middleware.

Declaration source: packages/backend/dist/types/testing/devRuntime.d.ts#L14.

export type FartherShoreDevInstance = FartherShore__b6398b2ddfc7 & {
    middleware(options?: MiddlewareOptions__b16fbb0c44c2): ExpressMiddleware__416c4ad228c7;
    /** Strict-context handler wrapper (guaranteed non-optional ctx). */
    handler: {
        <Req extends ExpressRequestLike__f93080abdbb9 = ExpressRequestLike__f93080abdbb9, Res extends ExpressResponseLike__7a6dd95793e1 = ExpressResponseLike__7a6dd95793e1>(handler: VerifiedExpressHandler__ca6f4e2c232b<Req, Res>): ExpressMiddleware__416c4ad228c7;
        /** Options-first overload — declarative `permission` gate. */
        <Req extends ExpressRequestLike__f93080abdbb9 = ExpressRequestLike__f93080abdbb9, Res extends ExpressResponseLike__7a6dd95793e1 = ExpressResponseLike__7a6dd95793e1>(options: HandlerOptions__89c221f2c3e0, handler: VerifiedExpressHandler__ca6f4e2c232b<Req, Res>): ExpressMiddleware__416c4ad228c7;
    };
    /** Traced authz helpers — the SAME shape as the prod facade's `fs.authz`. */
    authz: {
        hasPermission(ctx: TracedCarrier, key: string): boolean;
        requirePermission(ctx: TracedCarrier, key: string): void;
    };
    /** The dev harness attached to this runtime. */
    dev: DevRuntime;
};

generateDevSignerKeys

Generate a fresh, ephemeral set of dev signer keys: an Ed25519 request-signing
keypair, an HS256 context secret, and a `fsrt_test_` runtime token. Fully
synchronous (uses `node:crypto`) so a dev simulator can be built without
awaiting. NEVER call this in production (guarded upstream).

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L97.

export declare function generateDevSignerKeys(): DevSignerKeys;

isProductionEnv

Case-insensitive `NODE_ENV=production` check (matches core's `isProductionEnv`).

Declaration source: packages/backend/dist/types/testing/prodGuard.d.ts#L2.

export declare function isProductionEnv(env?: Record<string, string | undefined>): boolean;

makeSignedRequest

Produce a valid signed claim + the X-FS-* header bag. Returns both the verify
input shape and a mutable header record you can corrupt for negative tests.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L53.

export declare function makeSignedRequest(spec?: SignedRequestSpec): Promise<{
    input: {
        method: string;
        path: string;
        query: string;
        body: Uint8Array | null;
        streamingExempt: boolean;
    };
    claim: CanonicalSigningInput__d7cf4cea4ad9;
    headers: Record<string, string>;
}>;

memoryJwks

A JwksClient backed by an in-memory key set (no network).

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L65.

export declare function memoryJwks(keys?: Array<JsonWebKey & {
    kid?: string;
}>): JwksClient__3bf9d241c5e2;

MeteringTraceEntry

Public export MeteringTraceEntry.

Declaration source: packages/backend/dist/types/testing/traceSink.d.ts#L8.

export type MeteringTraceEntry = {
    meters: Record<string, number>;
    source: "response" | "meter";
};

PersonaClientContext

The context a persona client signs against (bootstrap ids + dev keys).

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L54.

export type PersonaClientContext = {
    keys: DevSignerKeys;
    businessId: string;
    backendId: string;
    contextSecret: string;
    contextKid: string;
    personas: Map<string, PersonaDefinition>;
    mode: DevMode;
    /** fetch used by `.fetch()`; defaults to global fetch for real app listeners. */
    fetchImpl?: typeof fetch;
};

personaClientFromKeysFile

Construct a persona client from a dev-keys file — the cross-process entry
point. A test runner in a separate process reads the file the running service
wrote and can immediately `asPersona("member").fetch(url)` against it.

Declaration source: packages/backend/dist/types/testing/keysFile.d.ts#L24.

export declare function personaClientFromKeysFile(path?: string, options?: {
    fetchImpl?: typeof fetch;
}): {
    asPersona(name: string): PersonaRequest;
    personas: Map<string, PersonaDefinition>;
    file: DevKeysFile;
};

PersonaDefinition

A named identity in the platform's test-persona claim vocabulary.

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L4.

export type PersonaDefinition = {
    name: string;
    orgId?: string;
    actor?: {
        type: string;
        id: string | null;
    };
    productId?: string;
    environmentId?: string | null;
    compiledPlanId?: string;
    subscriptionId?: string;
    subscriberId?: string;
    /**
     * The unified-authz permission grant. `["*"]` = full access (org OWNER /
     * RBAC-disabled). `[]` = authenticated with no grants (fail-closed on every
     * check). Omit to mint a verified-but-claimless context (RBAC N/A ⇒ grant).
     */
    permissions?: string[];
    roles?: string[];
    subjectKey?: string;
    /**
     * When true, `asPersona` emits NO `X-Fs-Context` — an unidentified caller.
     * Under `simulated` mode the request still verifies (valid signature) but
     * carrier-level permission checks fail closed. Used by the `anonymous` default.
     */
    anonymous?: boolean;
};

PersonaRequest

The request-builder returned by `asPersona(name)`.

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L66.

export type PersonaRequest = {
    /** The persona name. */
    readonly persona: string;
    /**
     * The 9 signed `x-fs-*` headers + `X-Fs-Context` (unless anonymous).
     * Defaults to GET; pass `method` for non-GET requests so the signature
     * matches the request the caller sends.
     */
    headers(spec?: PersonaRequestSpec): Promise<Record<string, string>>;
    /** Real HTTP with signed headers (uses the wired fetch). */
    fetch(url: string, init?: RequestInit): Promise<Response>;
    /** Set the signed headers on any `.set()`-carrying request (supertest, etc.). */
    inject(req: SettableRequest, spec?: PersonaRequestSpec): Promise<SettableRequest>;
};

PersonaRequestSpec

A single request spec for `.headers()`.

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L43.

export type PersonaRequestSpec = {
    method?: string;
    path?: string;
    query?: string;
    body?: Uint8Array | null;
    streamingExempt?: boolean;
    routeId?: string;
    requestId?: string;
    timestamp?: number;
};

readDevKeysFile

Read + parse a dev-keys file.

Declaration source: packages/backend/dist/types/testing/keysFile.d.ts#L18.

export declare function readDevKeysFile(path?: string): DevKeysFile;

redactValue

Redact anything that smells like a credential from a free-form string.

Declaration source: packages/backend/dist/types/testing/traceSink.d.ts#L29.

export declare function redactValue(input: string): string;

SettableRequest

A minimal `.set(name, value)`-carrying request (supertest `Test`, etc.).

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L36.

export type SettableRequest = {
    method?: string;
    url?: string;
    path?: string;
    set(field: string, value: string): unknown;
};

signContextToken

Mint an HS256-signed `X-Fs-Context` token — the exact INVERSE of
`verifyContext.ts`. The header is `{alg:"HS256",typ:"JWT",kid}` and the
payload is the cv=2 `ConsumerContextClaims` shape (sub / client_id? / act? /
subjectKind / org / businessId / compiledPlanId / subscriptionId /
subscriberId / environmentId / subjectKey plus optional permissions / roles).
Signs with the same secret the SDK would verify against (`contextSecrets` /
`FS_CONTEXT_SECRETS`).

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L79.

export declare function signContextToken(claim: FartherShoreSignedContext__24c947c09583, secret?: string, kid?: string): Promise<string>;

SIGNED_HEADER_NAMES

The signed request header names (exported for assertions).

Declaration source: packages/backend/dist/types/testing/personas.d.ts#L94.

declare const SIGNED_HEADER_NAMES: {
    readonly signature: "x-fs-signature";
    readonly keyId: "x-fs-key-id";
    readonly requestId: "x-fs-request-id";
    readonly timestamp: "x-fs-timestamp";
    readonly businessId: "x-fs-business-id";
    readonly backendId: "x-fs-backend-id";
    readonly routeId: "x-fs-route-id";
    readonly policyVersion: "x-fs-policy-version";
    readonly bodyHash: "x-fs-body-hash";
};

SignedHeaderOverrides

Public export SignedHeaderOverrides.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L11.

export type SignedHeaderOverrides = Partial<{
    signature: string;
    kid: string;
    requestId: string;
    timestamp: number;
    businessId: string;
    backendId: string;
    routeId: string;
    policyVersion: string;
    bodyHash: string;
}>;

SignedRequestSpec

Public export SignedRequestSpec.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L22.

export type SignedRequestSpec = {
    method?: string;
    path?: string;
    query?: string;
    body?: Uint8Array | null;
    streamingExempt?: boolean;
    businessId?: string;
    backendId?: string;
    routeId?: string;
    policyVersion?: string;
    requestId?: string;
    timestamp?: number;
    /**
     * Ed25519 private JWK to sign with. Defaults to {@link TEST_PRIVATE_JWK}. A
     * dev simulator passes its ephemeral signer here.
     */
    privateJwk?: JsonWebKey;
    /** Key id stamped into `x-fs-key-id`. Defaults to {@link TEST_KID}. */
    kid?: string;
    /**
     * Consumer-principal wave (D3) — the signed `X-Fs-Context` JWT to bind into
     * the request signature (and stamp as the `x-fs-context` header). Its SHA-256
     * is appended to the canonical string, exactly as the gateway signer does. A
     * missing token binds the empty-string hash (identity-less request).
     */
    contextToken?: string;
};

SignedTestWebhook

Public export SignedTestWebhook.

Declaration source: packages/backend/dist/types/testing/webhooks.d.ts#L16.

export interface SignedTestWebhook<T extends WebhookEnvelopeType__22116d242a71> {
    envelope: WebhookEnvelope__f1da89296e6d<T>;
    /** The exact bytes to POST. */
    body: string;
    /** `webhook-id` / `webhook-timestamp` / `webhook-signature` / event / content-type. */
    headers: Record<string, string>;
    /** Convenience: a `Request` you can hand straight to `handler.fetch`. */
    request(url?: string): Request;
}

signWebhookForTesting

Build + sign one delivery the way the platform does (Standard Webhooks
over `${id}.${timestamp}.${body}`). Pass several secrets to emulate the
24 h dual-signing rotation window.

Declaration source: packages/backend/dist/types/testing/webhooks.d.ts#L30.

export declare function signWebhookForTesting<T extends WebhookEnvelopeType__22116d242a71>(input: SignWebhookForTestingInput<T>): SignedTestWebhook<T>;

SignWebhookForTestingInput

Public export SignWebhookForTestingInput.

Declaration source: packages/backend/dist/types/testing/webhooks.d.ts#L2.

export interface SignWebhookForTestingInput<T extends WebhookEnvelopeType__22116d242a71> {
    /** The endpoint secret(s) the receiver is configured with (current first). */
    secret: string | readonly string[];
    type: T;
    data: WebhookEventData__3ab81689f0bb[T];
    /** Defaults to a random delivery id. */
    id?: string;
    businessId?: string;
    environmentId?: string | null;
    /** Defaults to now (ISO). */
    createdAt?: string;
    /** Signing timestamp (unix seconds); defaults to now. */
    timestamp?: number;
}

TEST_CONTEXT_KID

The default context-signing kid stamped into the JWT header.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L10.

declare const TEST_CONTEXT_KID = "fs-context-test-2026";

TEST_CONTEXT_SECRET

The default HS256 context-signing secret for dev fixtures (NEVER production).

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L8.

declare const TEST_CONTEXT_SECRET = "fs-dev-context-secret-2026";

TEST_KID

Public export TEST_KID.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L4.

declare const TEST_KID = "fs-runtime-test-2026";

TEST_PRIVATE_JWK

Public export TEST_PRIVATE_JWK.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L5.

declare const TEST_PRIVATE_JWK: JsonWebKey;

TEST_PUBLIC_JWK

Public export TEST_PUBLIC_JWK.

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L6.

declare const TEST_PUBLIC_JWK: JsonWebKey;

TracedCarrier

A permission carrier that also knows its request id (for trace keying).

Declaration source: packages/backend/dist/types/testing/devRuntime.d.ts#L10.

export type TracedCarrier = PermissionCarrier__227d98a75a82 & {
    requestId?: string;
};

unreachableJwks

A JwksClient whose fetch always throws (cold-cache failure).

Declaration source: packages/backend/dist/types/testing/signers.d.ts#L69.

export declare function unreachableJwks(): JwksClient__3bf9d241c5e2;

VerificationOutcome

Public export VerificationOutcome.

Declaration source: packages/backend/dist/types/testing/traceSink.d.ts#L2.

export type VerificationOutcome = "verified" | "passthrough" | "rejected";

writeDevKeysFile

Write the dev-keys file with 0600 permissions (owner read/write only).

Declaration source: packages/backend/dist/types/testing/keysFile.d.ts#L16.

export declare function writeDevKeysFile(path: string, contents: DevKeysFile): void;

Supporting declarations

These declarations explain types reachable from the public exports above. They are source evidence, not supported package imports. Suffixed names are documentation identifiers that preserve distinct lexical bindings. Standard-library and third-party types (for example Promise, React and Zod) remain external boundaries; their implementation declarations are not expanded here.

CanonicalSigningInput__d7cf4cea4ad9

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L153.

export type CanonicalSigningInput__d7cf4cea4ad9 = {
    /** HTTP method; canonicalized to upper-case. */
    method: string;
    /** Request path (no host, no query). */
    path: string;
    /** Raw query string (without leading '?'), or "" when absent. */
    query: string;
    /** Lowercase-hex SHA-256 of the raw body, EMPTY_BODY_SHA256, or "STREAM". */
    bodyHash: string;
    /** Gateway-minted request id (also the replay nonce). */
    requestId: string;
    /** Unix epoch seconds at signing time. */
    timestamp: number;
    businessId: string;
    backendId: string;
    /** Resolved route id; "" when unresolved. */
    routeId: string;
    policyVersion: string;
    /**
     * Consumer-principal wave (D3) — SHA-256 hex of the presented `X-Fs-Context`
     * JWT string, or the SHA-256 of the EMPTY string when context signing is off.
     * Bound into the canonical string so one request-signature verification
     * covers both the request and the identity context. Compute via
     * {@link hashContextToken}.
     */
    contextHash: string;
};

ConsumerPrincipal__16f951b9786d

Declaration source: packages/backend/dist/types/core/verifyContext.d.ts#L8.

export type ConsumerPrincipal__16f951b9786d = {
    org: {
        id: string;
    };
    subject: {
        kind: "member";
        /** The member's stable internal id (never an IdP subject/email). */
        memberId: string;
        /** How this request's identity was proven. */
        via: "session" | "api_key";
        /** The personal `fsk_` key id when `via === "api_key"` (audit). */
        keyId?: string;
    } | {
        kind: "service";
        /** The org-owned service account id — the stable service identity. */
        serviceAccountId: string;
        /** The specific service `fsk_` key id (rotates; audit). */
        keyId: string;
    };
};

ExpressMiddleware__416c4ad228c7

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L30.

export type ExpressMiddleware__416c4ad228c7 = (req: ExpressRequestLike__f93080abdbb9, res: ExpressResponseLike__7a6dd95793e1, next: ExpressNext__c3f550fc71bd) => void;

ExpressNext__c3f550fc71bd

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L29.

export type ExpressNext__c3f550fc71bd = (err?: unknown) => void;

ExpressRequestLike__f93080abdbb9

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L5.

export type ExpressRequestLike__f93080abdbb9 = {
    method: string;
    /** Original URL incl. query, e.g. "/v1/x?a=1". */
    originalUrl?: string;
    url?: string;
    path?: string;
    headers: Record<string, string | string[] | undefined>;
    /** Raw body bytes if captured by an upstream raw parser. */
    rawBody?: Buffer | Uint8Array;
    body?: unknown;
    fartherShore?: FartherShoreRequestContext__fee40dd450e8;
};

ExpressResponseLike__7a6dd95793e1

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L17.

export type ExpressResponseLike__7a6dd95793e1 = {
    status(code: number): ExpressResponseLike__7a6dd95793e1;
    json(body: unknown): unknown;
    setHeader(name: string, value: string): void;
    /**
     * Node's `ServerResponse.headersSent`. This is what makes the reporting verb's
     * transport choice AUTOMATIC: while it is false the measurement rides signed
     * response headers (no network call); once the response is on the wire
     * `ctx.report()` transparently switches to the post-stream channel.
     */
    headersSent?: boolean;
};

FartherShore__b6398b2ddfc7

Declaration source: packages/backend/dist/types/core/runtime.d.ts#L84.

export declare class FartherShore__b6398b2ddfc7 {
    private readonly bootstrapClient;
    private readonly fetchImpl;
    private readonly verificationEnabled;
    private readonly meteringEnabledOverride;
    private readonly runtimeToken;
    private readonly coreUrl;
    private readonly instanceId?;
    private readonly tunnelOptions;
    /** OPTIONAL HS256 secret(s) — defense-in-depth over the cv=2 X-Fs-Context. */
    private readonly contextSecrets;
    private readonly nonceCache;
    private readonly replayProtectionDiagnostic;
    private readonly shutdownManager;
    /** Bounds the on-demand bootstrap refreshes an unknown route id can trigger. */
    private readonly routeRefreshLimiter;
    private jwks;
    private postStreamUsageClient;
    private tunnel;
    private bootstrapped;
    constructor(options?: FartherShoreInitOptions__d009c6effb6b);
    /** Ensure bootstrap config is loaded; build the JWKS + metering clients. */
    ensureBootstrapped(): Promise<RuntimeBootstrapResponse__aecc7a0d671f>;
    /**
     * Boot-time route reconciliation (call once, before `listen()`). Reflects the
     * app's real route surface, diffs it against the declared lock from bootstrap,
     * REPORTS drift to the platform, and CONFIRMS the declared `pending` routes
     * this replica serves. Fail-OPEN: never throws / never blocks boot.
     *
     * The reflection code is dynamically imported so it stays OFF the per-request
     * verification hot path (the runtime stays route-unaware there). The report is
     * an OUTBOUND backend→core call (same channel as bootstrap/metering), so it
     * works for every transport (direct / tunnel).
     *
     * Returns the reconcile result (or null if reflection is unavailable / boot
     * reporting failed). v1 reflects Express; `app` omitted → no-op.
     */
    ready(app?: unknown): Promise<ReconcileResult__9286f3220e09 | null>;
    /** Outbound report sink for `ready()` — runtime-token-authed POSTs to core. */
    private buildReportSink;
    /**
     * Framework-neutral verification primitive. Fail-closed: throws a typed
     * FartherShoreError on any verification failure. Returns the verified context.
     */
    verifyRequest(input: VerifyRequestInput__5a17124b6df7, options?: VerifyRequestHostOptions__981e9466821d): Promise<FartherShoreRequestContext__fee40dd450e8>;
    /**
     * Bind the ONE reporting verb to a verified context. Identity comes from the
     * context (`signedContext.subscriptionId` + `requestId`) — never from the
     * caller — so a handler cannot forget it, and a background job that is handed
     * this context keeps reporting against the SAME served identity.
     */
    private buildReportFn;
    /** Whether verification is required (bootstrap × opt-out). */
    verificationRequired(): Promise<boolean>;
    /**
     * Start the embedded runner. For a `tunnel` backend whose runner is
     * `embedded`, this supervises `cloudflared` as a child process
     * (spawned via the injected/default spawner) using the tunnel token from
     * bootstrap. For every other transport (`direct`, or the `sidecar` runner)
     * it is a no-op — there is no SDK-managed process to run.
     *
     * Fail-open by default: a tunnel that cannot start does NOT crash the host app
     * (request verification stays fail-closed regardless — a different axis).
     */
    start(): Promise<void>;
    /**
     * PRIVATE transport for the post-stream lane of `ctx.report()`. Never rejects
     * — a metering hiccup must not break a builder's endpoint. This is machinery,
     * not surface: the ONE public reporting verb is `ctx.report()`.
     */
    private reportPostStreamUsage;
    /**
     * How far replay protection actually reaches — `"shared"` (enforced across
     * every replica) or `"single-instance"` (this process only). Deployment
     * diagnostic: log it at boot, or assert on it in a smoke test, so the mode is
     * never a surprise. See {@link FartherShoreInitOptions.nonceStore}.
     */
    replayProtection(): ReplayProtectionDiagnostic__a3a9ef1278f1;
    /** Current local health report. */
    health(): RuntimeHealthReport__0174b488600d;
    /** Graceful shutdown: flush metering + send a stopping heartbeat. */
    shutdown(): Promise<void>;
    /** Register an additional shutdown hook (e.g. the cloudflared supervisor). */
    onShutdown(hook: () => Promise<void> | void): void;
}

FartherShoreInitOptions__d009c6effb6b

Declaration source: packages/backend/dist/types/core/runtime.d.ts#L21.

export type FartherShoreInitOptions__d009c6effb6b = {
    /** Explicit runtime token. Defaults to process.env.FS_RUNTIME_TOKEN. */
    runtimeToken?: string;
    /** Core base URL. Defaults to FS_CORE_URL or https://core.farthershore.com. */
    coreUrl?: string;
    /** Env map (tests). Defaults to process.env. */
    env?: Record<string, string | undefined>;
    /** Injectable fetch (tests). */
    fetchImpl?: typeof fetch;
    /** Optional advanced opt-outs (default: everything on). */
    verification?: {
        enabled?: boolean;
    };
    metering?: {
        enabled?: boolean;
    };
    /** Embedded-cloudflared runner config (advanced opt-in; default DX is on). */
    tunnel?: FartherShoreTunnelOptions__07694d2dbe44;
    /** SDK metadata forwarded to bootstrap. */
    instanceId?: string;
    /**
     * OPTIONAL HS256 secret(s) for the gateway's cv=2 `X-Fs-Context` claim — pure
     * DEFENSE-IN-DEPTH, NOT required to derive identity. The consumer principal is
     * always produced from the `X-Fs-Context` token whose bytes are vouched for by
     * the Ed25519 request signature (the token's SHA-256 is bound into the signed
     * canonical string). These secrets add a second, independent HS256 proof: when
     * configured, a presented token must ALSO pass HS256 or the request is
     * rejected. They are the GATEWAY CONTEXT-SIGNING keyring values
     * (`CONTEXT_SIGNING_KEYS_JSON`; supply every live key during rotation —
     * try-all), NOT the business's `contextTokenSecret` (which signs `fsc_`
     * INGRESS tokens verified BY the gateway — setting that here would reject every
     * valid gateway request). Defaults to `FS_CONTEXT_SECRETS` (comma-separated)
     * from the env. Leaving it unset is the common case.
     */
    contextSecrets?: readonly string[];
    /**
     * OPTIONAL shared replay-prevention store. Not required: the signature's
     * ~305s time window is the always-on defense, and the zero-config default is
     * an in-memory per-process cache. Inject a shared atomic store (Redis /
     * Memcached / Cloudflare KV / Durable Object) implementing {@link NonceStore}
     * only if you want one-time-use enforced ACROSS replicas rather than within
     * each one. `checkAndRemember` may be async, and should be TTL-bound to the
     * signature validity window.
     *
     * If you do inject one, an outage of that store fails requests CLOSED — it
     * never degrades to "not a replay".
     */
    nonceStore?: NonceStore__85b099a3f9b9;
};

FartherShoreRequestContext__fee40dd450e8

Declaration source: packages/backend/dist/types/core/verifyRequest.d.ts#L24.

export type FartherShoreRequestContext__fee40dd450e8 = {
    requestId: string;
    businessId: string;
    backendId: string;
    routeId: string;
    policyVersion: string;
    timestamp: number;
    bodyHash: string;
    /** Filled by the host bootstrap layer (tenant/customer), not by verify. */
    tenantId?: string;
    customerId?: string;
    meters?: string[];
    features?: Record<string, unknown>;
    /**
     * The verified CONSUMER PRINCIPAL behind this request (consumer-principal
     * wave, D3) — derived from the cv=2 `X-Fs-Context` whose bytes are vouched for
     * by the Ed25519 request signature (the token hash is bound into the canonical
     * signing string). OPTIONAL on this raw `fs.middleware()` path: a valid gateway
     * request MAY be identity-less (no `X-Fs-Context` — the gateway signs an
     * empty context hash), in which case there is no principal to resolve. This
     * field is typed honestly here; the `fs.handler()` path (createExpressHandler)
     * is where the GUARANTEED non-optional principal lives — it rejects an
     * identity-less request with `401 principal_required` before the callback runs.
     * Use {@link requireMember} to narrow to the member arm on member-only routes.
     */
    principal?: ConsumerPrincipal__16f951b9786d;
    /**
     * Managed-RBAC permissions the gateway resolved for the acting subject —
     * sourced ONLY from the VERIFIED signed `X-Fs-Context` claim (the unsigned
     * `x-fs-permissions` fallback is GONE). `undefined` when the claim was absent
     * ⇒ FAR-723 carrier-level DENY; `[]` for an authenticated subject with no
     * grants. Read via {@link hasPermission} / {@link requirePermission}.
     */
    permissions?: string[];
    /** Exact current-G product permissions default-allowed for this request. */
    unassignedProductPermissions?: string[];
    /** The VERIFIED signed cv=2 context payload. Its permissions/roles populated
     *  the fields above; its claims derived {@link principal}. */
    signedContext?: FartherShoreSignedContext__24c947c09583;
    /** Managed-RBAC role keys the acting subject holds (display/audit only). */
    roles?: string[];
    /**
     * THE reporting verb. `report({ meter, values, dims?, quote? })` reports
     * MEASUREMENTS against the served identity this context already carries —
     * there is no subscription/release argument to forget. The SDK picks the
     * transport (signed in-band headers before the response is sent, the attested
     * post-stream channel after it, or from a background job), so the builder
     * never chooses one.
     *
     * Attached by the runtime facade. A context produced by the BARE
     * `verifyRequest()` primitive has no metering channel, so its `report()`
     * throws an error naming the fix rather than dropping the measurement.
     */
    report: ReportFn__89e79b33cabf;
};

FartherShoreSignedContext__24c947c09583

Declaration source: packages/backend/dist/types/core/verifyContext.d.ts#L33.

export type FartherShoreSignedContext__24c947c09583 = {
    /** Claim-format version. This SDK understands ONLY cv=2 (consumer principal). */
    cv: 2;
    /** Resource owner: member id (member) or service account id (service). */
    sub: string;
    /** API key / service credential id, when the call is key-borne. */
    client_id?: string;
    /** Nested actor (on-behalf-of): personal-key traffic sets `{ sub: keyId }`. */
    act?: {
        sub: string;
    };
    /** The org (tenant) id. */
    org: string;
    businessId: string;
    compiledPlanId: string;
    subscriptionId: string;
    subscriberId: string;
    environmentId: string | null;
    subjectKey: string;
    /** Which subject arm this context resolves to. */
    subjectKind: "member" | "service";
    /** The org-owned service account id, for service subjects (mirror of `sub`). */
    serviceAccountId?: string;
    /** The bound role keys (absent when unminted). */
    roles?: string[];
    /** The unified-authz permission claim (absent when unminted). */
    permissions?: string[];
    /** Exact current-G product permissions default-allowed for this request. */
    unassignedProductPermissions?: string[];
};

FartherShoreTunnelOptions__07694d2dbe44

Declaration source: packages/backend/dist/types/core/runtime.d.ts#L9.

export type FartherShoreTunnelOptions__07694d2dbe44 = {
    /** Opt out of the embedded cloudflared runner (e.g. sidecar mode). */
    enabled?: boolean;
    /** Injected spawner (tests/non-default hosts). Defaults to node:child_process. */
    spawn?: SpawnFn__a4d2414f74db;
    /** Explicit cloudflared binary path. */
    binaryPath?: string;
    /** Crash the host app if the tunnel cannot start. Default: fail-open. */
    failClosed?: boolean;
    /** Log sink for redacted cloudflared output. */
    logger?: (line: string) => void;
};

HandlerOptions__89c221f2c3e0

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L91.

export type HandlerOptions__89c221f2c3e0 = {
    /**
     * Permission key the verified principal must hold (unified grammar:
     * `*` / `<subject>:*` / exact — custom strings work). Checked with the
     * FAIL-CLOSED carrier gate (`requirePermission`): an ABSENT permission set
     * denies. On failure the wrapper responds `403 { error: "permission_denied" }`
     * before the callback runs.
     */
    permission?: string;
};

HeadersLike__89315298f855

Declaration source: packages/backend/dist/types/core/verifyRequest.d.ts#L22.

export type HeadersLike__89315298f855 = Headers | Record<string, string | string[] | undefined>;

Jwk__10747812bcb3

Declaration source: packages/backend/dist/types/core/jwks.d.ts#L1.

export type Jwk__10747812bcb3 = JsonWebKey & {
    kid?: string;
};

JwksCacheState__075013cca763

Declaration source: packages/backend/dist/types/core/jwks.d.ts#L5.

export type JwksCacheState__075013cca763 = "fresh" | "soft_stale" | "hard_stale" | "cold";

JwksClient__3bf9d241c5e2

Declaration source: packages/backend/dist/types/core/jwks.d.ts#L43.

export declare class JwksClient__3bf9d241c5e2 {
    private readonly jwksUrl;
    private readonly fetchImpl;
    private readonly cacheTtlMs;
    private readonly hardStaleMs;
    private readonly negativeCacheMs;
    private readonly now;
    private readonly onObservation;
    private keysByKid;
    private fetchedAt;
    private hasFetchedOnce;
    private inflight;
    private readonly negativeKids;
    constructor(options: JwksClientOptions__1aedfc6c12a8);
    /**
     * Resolve a public JWK for `kid`, fail-closed. Throws FartherShoreError with
     * `jwks_unavailable` (cold cache, or a hard-stale cache whose refresh is
     * failing) or `unknown_key_id`.
     */
    getKey(kid: string): Promise<Jwk__10747812bcb3>;
    /** Record a confirmed-missing kid, evicting the oldest if at capacity. */
    private rememberMissingKid;
    private ageMs;
    private isStale;
    private isHardStale;
    /** Current freshness of the cached key set. */
    private cacheState;
    private observe;
    /** Fail closed when the cached key set is past the hard-stale ceiling. */
    private assertWithinHardStale;
    /** Single-flight refresh: concurrent callers share one fetch. */
    private refresh;
    private doFetch;
    /**
     * BOUNDED stale-while-revalidate. A COLD cache fails closed. A warm cache
     * inside the soft window swallows the failure and keeps serving. Past the
     * hard-stale ceiling it fails closed too — availability is worth a bounded
     * window of degraded trust, not an unbounded one.
     */
    private handleRefreshFailure;
}

JwksClientOptions__1aedfc6c12a8

Declaration source: packages/backend/dist/types/core/jwks.d.ts#L19.

export type JwksClientOptions__1aedfc6c12a8 = {
    jwksUrl: string;
    /** Injectable fetch (tests). Defaults to globalThis.fetch. */
    fetchImpl?: typeof fetch;
    /** How long a successful fetch stays fresh before a background refresh. */
    cacheTtlMs?: number;
    /**
     * Hard ceiling on serving a key set whose refresh is failing. Past this age
     * the client FAILS CLOSED rather than vouching for keys it can no longer
     * confirm. Must be ≥ cacheTtlMs.
     */
    hardStaleMs?: number;
    /** How long an unknown-kid result is negatively cached (avoids hammering). */
    negativeCacheMs?: number;
    /** Injectable clock (tests). */
    now?: () => number;
    /** Freshness//staleness observations for metrics. */
    onObservation?: JwksObserver__4d7082fe0d6b;
};

JwksObservation__b0d7452a7cf1

Declaration source: packages/backend/dist/types/core/jwks.d.ts#L6.

export type JwksObservation__b0d7452a7cf1 = {
    state: JwksCacheState__075013cca763;
    /** Age of the cached key set in ms (0 when cold). */
    ageMs: number;
    /** The `kid` being resolved, when the observation is tied to one. */
    kid?: string;
};

JwksObserver__4d7082fe0d6b

Declaration source: packages/backend/dist/types/core/jwks.d.ts#L18.

export type JwksObserver__4d7082fe0d6b = (observation: JwksObservation__b0d7452a7cf1) => void;

MeasurementDimensions__e2d8137e24a6

Declaration source: packages/backend/dist/types/core/report.d.ts#L5.

export type MeasurementDimensions__e2d8137e24a6 = Record<string, string>;

MeasurementValues__ab2d89ace8f2

Declaration source: packages/backend/dist/types/core/report.d.ts#L3.

export type MeasurementValues__ab2d89ace8f2 = Record<string, number>;

MiddlewareOptions__b16fbb0c44c2

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L31.

export type MiddlewareOptions__b16fbb0c44c2 = {
    /**
     * STRICT BY DEFAULT (`true`). Every request is verified FAIL-CLOSED and its
     * inbound `x-fs-*` headers are stripped before the handler runs — the verified
     * `req.fartherShore` context is the only identity source. The builder need not
     * pass this: the gateway signs every request, and a missing/invalid signature
     * or context is a `401`.
     *
     * Set `always: false` to instead DEFER to bootstrap's
     * `verification.required` flag — when the backend contract does not require
     * verification, the request passes through WITHOUT a context (and without
     * stripping). This is an advanced escape hatch for a backend that intentionally
     * consumes no identity; the secure default is strict.
     */
    always?: boolean;
    /**
     * Called when verification REJECTS a request, with the diagnostic detail that
     * is deliberately withheld from the response body.
     *
     * The wire response is only `{ error: <code> }` (plus the error's `details`,
     * if any) — several distinct causes share one code (`route_mismatch` covers
     * both a business mismatch and a backend mismatch; an unserved route id is
     * the separate `route_unknown`), and the specifics must not leak to an
     * unauthenticated caller. But discarding them entirely leaves the operator
     * with no way to tell which cause fired, in their OWN logs, for their OWN
     * server. That is what this hook restores.
     *
     * Defaults to a one-line `console.warn`. Pass a function to route it into a
     * structured logger, or `() => {}` to silence it.
     */
    onVerificationError?: (detail: {
        code: string;
        message: string;
        status: number;
        method: string;
        path: string;
    }) => void;
};

NonceStore__85b099a3f9b9

Declaration source: packages/backend/dist/types/core/nonceCache.d.ts#L13.

export interface NonceStore__85b099a3f9b9 {
    checkAndRemember(id: string): boolean | Promise<boolean>;
}

PermissionCarrier__227d98a75a82

Declaration source: packages/backend/dist/types/core/permissions.d.ts#L61.

export interface PermissionCarrier__227d98a75a82 {
    permissions?: readonly string[];
    /** Exact product permissions default-allowed by the current G+A decision. */
    unassignedProductPermissions?: readonly string[];
    /**
     * The verified X-Fs-Context claims, when the request carried a valid token.
     * NOT consulted for permission decisions — its presence NEVER grants (an
     * absent `permissions` set always denies). Retained only as part of the
     * verified-context shape a carrier is built from.
     */
    signedContext?: FartherShoreSignedContext__24c947c09583;
}

ReconcileResult__9286f3220e09

Declaration source: packages/backend/dist/types/reflect/reconcile.d.ts#L23.

export interface ReconcileResult__9286f3220e09 {
    /** Reflected surface matched the declared lock. */
    inSync: boolean;
    /** A drift report was sent. */
    reportedDrift: boolean;
    /** Route ids confirmed served (pending → clearable). */
    confirmedRouteIds: string[];
    /** A report sink call failed (swallowed — boot never blocks on it). */
    reportError?: string;
}

ReplayProtectionDiagnostic__a3a9ef1278f1

Declaration source: packages/backend/dist/types/core/replay-protection.d.ts#L4.

export type ReplayProtectionDiagnostic__a3a9ef1278f1 = {
    mode: ReplayProtectionMode__c5da7b084f0a;
    /** True when replay is enforced across every replica, not just this process. */
    crossReplica: boolean;
};

ReplayProtectionMode__c5da7b084f0a

Declaration source: packages/backend/dist/types/core/replay-protection.d.ts#L3.

export type ReplayProtectionMode__c5da7b084f0a = "shared" | "single-instance";

ReportFn__89e79b33cabf

Declaration source: packages/backend/dist/types/core/report.d.ts#L115.

export type ReportFn__89e79b33cabf = (input: ReportInput__0f8959765e13 | readonly ReportInput__0f8959765e13[]) => Promise<ReportResult__1d967fd166a1>;

ReportInput__0f8959765e13

Declaration source: packages/backend/dist/types/core/report.d.ts#L28.

export type ReportInput__0f8959765e13 = {
    /** Meter key as declared in the business release (plain string at the wire). */
    meter: string;
    /** Observed values keyed by measure key, e.g. `{ input_tokens: 1200 }`. */
    values: MeasurementValues__ab2d89ace8f2;
    /** Catalog selectors, e.g. `{ model: "acme-4", cache_status: "hit" }`. */
    dims?: MeasurementDimensions__e2d8137e24a6;
    /**
     * OPTIONAL money proposal for a `backendQuoted` pricing rule: a PER-UNIT
     * rate in nanodollars (multiplied by the measured quantity — never a
     * total). Opaque at the authoring boundary (a job result carries it through
     * untyped); validated against {@link QuoteInput} here and transmitted as a
     * {@link QuoteProposal}. Applies to every backend-quoted component of this
     * report; ignored by rules that are not backend-quoted.
     */
    quote?: unknown;
};

ReportResult__1d967fd166a1

Declaration source: packages/backend/dist/types/core/report.d.ts#L53.

export type ReportResult__1d967fd166a1 = {
    ok: true;
    transport: ReportTransport__0721adbb43b4;
} | {
    ok: false;
    transport: ReportTransport__0721adbb43b4;
    reason: string;
    /** The PLATFORM's error code, when the failure came back in a response
     *  body (e.g. `post_stream_request_not_found`). Absent for local faults.
     *  Surfaced so a builder can act on the cause without wrapping fetch. */
    code?: string;
    /** The platform's own error message, verbatim. */
    message?: string;
    /** HTTP status of the final delivery attempt, when there was one. */
    status?: number;
};

ReportTransport__0721adbb43b4

Declaration source: packages/backend/dist/types/core/report.d.ts#L46.

export type ReportTransport__0721adbb43b4 = "in_band" | "post_stream";

ResponseSink__b746e2445083

Declaration source: packages/backend/dist/types/core/report.d.ts#L78.

export type ResponseSink__b746e2445083 = {
    /** True while headers can still be stamped onto the outgoing response. */
    canStampHeaders(): boolean;
    /** Stamp the signed metering headers onto the outgoing response. */
    stampHeaders(headers: Record<string, string>): void;
};

RUNTIME_HEADER_NAMES__adc010c1041a

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L126.

declare const RUNTIME_HEADER_NAMES__adc010c1041a: {
    readonly signature: "x-fs-signature";
    readonly keyId: "x-fs-key-id";
    readonly requestId: "x-fs-request-id";
    readonly timestamp: "x-fs-timestamp";
    readonly businessId: "x-fs-business-id";
    readonly backendId: "x-fs-backend-id";
    readonly routeId: "x-fs-route-id";
    readonly policyVersion: "x-fs-policy-version";
    readonly bodyHash: "x-fs-body-hash";
};

RUNTIME_TOKEN_OPERATIONS__1b6bc2f07e6d

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L124.

declare const RUNTIME_TOKEN_OPERATIONS__1b6bc2f07e6d: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];

RUNTIME_TOKEN_PREFIXES__449e80fc59d4

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L119.

declare const RUNTIME_TOKEN_PREFIXES__449e80fc59d4: {
    readonly live: "fsrt_live_";
    readonly test: "fsrt_test_";
};

RuntimeBootstrapResponse__aecc7a0d671f

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L228.

export type RuntimeBootstrapResponse__aecc7a0d671f = {
    business: {
        id: string;
        slug: string;
    };
    backend: {
        id: string;
        slug: string;
        name: string;
    };
    /**
     * Every backend id this token may serve, across ALL of the business's
     * environments — `backend.id` is always a member.
     *
     * One deployment holds exactly one `FS_RUNTIME_TOKEN`, so an
     * environment-scoped token forced a SEPARATE deployment per environment:
     * serving a preview env meant repointing (and breaking) production. A
     * business-scoped token serves every environment from one deployment, and the
     * SDK checks the gateway's signed backend id for MEMBERSHIP of this set
     * rather than equality with a single id.
     *
     * Optional and additive: an older core omits it and the SDK falls back to the
     * single-id equality check.
     */
    backendIds?: string[];
    environment: {
        id: string | null;
        kind: RuntimeEnvironmentKind__ac9ea026fbe7;
    };
    operations: RuntimeTokenOperation__29f1e3868c88[];
    verification: RuntimeVerificationConfig__5494b13a9008;
    metering: RuntimeMeteringConfig__3d27722db6c2;
    transport: RuntimeTransportConfig__7254e971c589;
    routes: RuntimeRouteDescriptor__48a862559af0[];
    /** Reflected route-surface lock (surfaceHash + version). Present once core
     *  serves it; `fs.ready()` diffs the reflected surface against it. */
    lock?: RuntimeLockDescriptor__0d22ecd0bb58;
    policyVersion: string;
    refreshAfterSeconds: number;
};

RuntimeEnvironmentKind__ac9ea026fbe7

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L180.

export type RuntimeEnvironmentKind__ac9ea026fbe7 = RuntimeTokenKind__821c369e851d;

RuntimeHealthReport__0174b488600d

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L306.

export type RuntimeHealthReport__0174b488600d = {
    runtimeToken: boolean;
    bootstrap: boolean;
    tunnel: string | null;
    verification: boolean;
    metering: boolean;
};

RuntimeLockDescriptor__0d22ecd0bb58

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L224.

export type RuntimeLockDescriptor__0d22ecd0bb58 = {
    surfaceHash: string;
    lockVersion: number;
};

RuntimeMeteringConfig__3d27722db6c2

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L195.

export type RuntimeMeteringConfig__3d27722db6c2 = {
    enabled: boolean;
    endpoint: string;
    credential: string;
    allowedMeters: string[];
    allowedRoutes: string[];
    perEventMax: number;
};

RuntimeMeteringEvent__418138753c49

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L268.

export type RuntimeMeteringEvent__418138753c49 = {
    event_id: string;
    business_id: string;
    backend_id: string;
    route_id?: string;
    request_id?: string;
    /** Subscription the usage belongs to (billing attribution). Optional and
     *  additive: legacy emitters omit it; core then falls back to resolving the
     *  served gateway request via `request_id`, and rows that resolve neither
     *  way are persisted unbilled + flagged unattributable. */
    subscription_id?: string;
    meter: string;
    qty: number;
    timestamp: string;
};

RuntimePostStreamUsageEvent__1827aaa16965

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L284.

export type RuntimePostStreamUsageEvent__1827aaa16965 = {
    requestId: string;
    subscriptionId: string;
    nonce: string;
    meters: Record<string, number>;
    creditUnitsConsumed?: Record<string, number>;
    measureContext?: Record<string, unknown>;
    /** Schema version of {@link measurements}; currently `1`. */
    measurementsVersion?: number;
    /** Measurement lane — `{ meter, values, dims }` as declared in the release. */
    measurements?: {
        meter: string;
        values: Record<string, number>;
        dims?: Record<string, string>;
    }[];
    /** Proposed rate input for a `backendQuoted` pricing rule (core clamps it). */
    quote?: {
        currency: string;
        amountNanos: string;
    };
    signature: string;
};

RuntimeRouteDescriptor__48a862559af0

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L214.

export type RuntimeRouteDescriptor__48a862559af0 = {
    id: string;
    method: string;
    path: string;
    backendId: string;
    /** Declared-but-not-yet-confirmed-served route. `fs.ready()` confirms the ones
     *  this replica actually serves so core can clear the flag and publish. */
    pending?: boolean;
};

RuntimeTokenKind__821c369e851d

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L123.

export type RuntimeTokenKind__821c369e851d = keyof typeof RUNTIME_TOKEN_PREFIXES__449e80fc59d4;

RuntimeTokenOperation__29f1e3868c88

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L125.

export type RuntimeTokenOperation__29f1e3868c88 = (typeof RUNTIME_TOKEN_OPERATIONS__1b6bc2f07e6d)[number];

RuntimeTransportConfig__7254e971c589

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L203.

export type RuntimeTransportConfig__7254e971c589 = {
    mode: TransportMode__341e38853a53;
    runner: TransportRunner__21383ffda4d0 | null;
    originUrl?: string;
    originHostname?: string;
    localTarget?: string;
    cloudflared?: {
        tunnelToken: string;
        version: string;
    };
};

RuntimeVerificationConfig__5494b13a9008

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L188.

export type RuntimeVerificationConfig__5494b13a9008 = {
    required: boolean;
    jwksUrl: string;
    clockSkewSeconds: number;
    replayWindowSeconds: number;
    headerNames: typeof RUNTIME_HEADER_NAMES__adc010c1041a;
};

SpawnedTunnelProcess__65f87a1c4fc6

Declaration source: packages/backend/dist/types/core/tunnel.d.ts#L11.

export interface SpawnedTunnelProcess__65f87a1c4fc6 {
    readonly stdout: StdioStream__d26eea00aaf1 | null;
    readonly stderr: StdioStream__d26eea00aaf1 | null;
    readonly pid?: number;
    /** Register the process-exit handler. */
    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
    /** Signal the child to stop. */
    kill(signal?: NodeJS.Signals | number): boolean;
}

SpawnFn__a4d2414f74db

Declaration source: packages/backend/dist/types/core/tunnel.d.ts#L25.

export type SpawnFn__a4d2414f74db = (command: string, args: string[], options?: {
    env?: NodeJS.ProcessEnv;
}) => SpawnedTunnelProcess__65f87a1c4fc6;

StdioStream__d26eea00aaf1

Declaration source: packages/backend/dist/types/core/tunnel.d.ts#L4.

type StdioStream__d26eea00aaf1 = Pick<EventEmitter, "on">;

TransportMode__341e38853a53

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L181.

export type TransportMode__341e38853a53 = "direct" | "tunnel";

TransportRunner__21383ffda4d0

Declaration source: packages/backend/dist/types/runtime-types.d.ts#L182.

export type TransportRunner__21383ffda4d0 = "embedded" | "sidecar";

VerifiedExpressHandler__ca6f4e2c232b

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L89.

export type VerifiedExpressHandler__ca6f4e2c232b<Req extends ExpressRequestLike__f93080abdbb9 = ExpressRequestLike__f93080abdbb9, Res extends ExpressResponseLike__7a6dd95793e1 = ExpressResponseLike__7a6dd95793e1> = (ctx: VerifiedPrincipalContext__f4d6dbc0db6f, req: Req, res: Res, next: ExpressNext__c3f550fc71bd) => void | Promise<void>;

VerifiedPrincipalContext__f4d6dbc0db6f

Declaration source: packages/backend/dist/types/adapters/express.d.ts#L78.

export type VerifiedPrincipalContext__f4d6dbc0db6f = FartherShoreRequestContext__fee40dd450e8 & {
    principal: ConsumerPrincipal__16f951b9786d;
    signedContext: FartherShoreSignedContext__24c947c09583;
};

VerifyRequestHostOptions__981e9466821d

Declaration source: packages/backend/dist/types/core/runtime.d.ts#L76.

export type VerifyRequestHostOptions__981e9466821d = {
    responseSink?: ResponseSink__b746e2445083;
};

VerifyRequestInput__5a17124b6df7

Declaration source: packages/backend/dist/types/core/verifyRequest.d.ts#L6.

export type VerifyRequestInput__5a17124b6df7 = {
    method: string;
    /** Path only (no host, no query). */
    path: string;
    /** Raw query string (with or without leading '?'); "" when absent. */
    query?: string;
    headers: HeadersLike__89315298f855;
    /** Raw request bytes captured pre-parser; null/undefined for empty body. */
    body?: Uint8Array | null;
    /**
     * True when the request is body-hash-exempt (streaming). The signed hash must
     * then be the STREAM sentinel and the body is not hashed (size cap still
     * applies upstream).
     */
    streamingExempt?: boolean;
};

WEBHOOK_EVENT_NAMES__b1fde63f3b9d

Declaration source: packages/backend/dist/types/webhooks/types.d.ts#L5.

declare const WEBHOOK_EVENT_NAMES__b1fde63f3b9d: readonly ["subscription.created", "subscription.updated", "subscription.canceled", "payment.succeeded", "payment.failed", "entitlement.changed", "usage.threshold_reached"];

WEBHOOK_TEST_EVENT__6536cbfa1b3d

Declaration source: packages/backend/dist/types/webhooks/types.d.ts#L8.

declare const WEBHOOK_TEST_EVENT__6536cbfa1b3d: "webhook.test";

WebhookEnvelope__f1da89296e6d

Declaration source: packages/backend/dist/types/webhooks/types.d.ts#L68.

export type WebhookEnvelope__f1da89296e6d<T extends WebhookEnvelopeType__22116d242a71 = WebhookEnvelopeType__22116d242a71> = T extends WebhookEnvelopeType__22116d242a71 ? {
    id: string;
    type: T;
    /** ISO 8601 — when the event was recorded (stable across retries). */
    createdAt: string;
    businessId: string;
    /** `null` = production. */
    environmentId: string | null;
    data: WebhookEventData__3ab81689f0bb[T];
} : never;

WebhookEnvelopeType__22116d242a71

Declaration source: packages/backend/dist/types/webhooks/types.d.ts#L10.

export type WebhookEnvelopeType__22116d242a71 = WebhookEventName__516efeb1d3c0 | typeof WEBHOOK_TEST_EVENT__6536cbfa1b3d;

WebhookEventData__3ab81689f0bb

Declaration source: packages/backend/dist/types/webhooks/types.d.ts#L16.

export interface WebhookEventData__3ab81689f0bb {
    "subscription.created": {
        subscriptionId?: string;
        compiledPlanId?: string;
        [key: string]: unknown;
    };
    "subscription.updated": {
        subscriptionId?: string;
        /** Producer-specific change reason, e.g. `plan_changed`, `trial_ending`. */
        reason?: string;
        lifecycle?: string;
        compiledPlanId?: string;
        [key: string]: unknown;
    };
    "subscription.canceled": {
        subscriptionId?: string;
        reason?: string;
        lifecycle?: string;
        [key: string]: unknown;
    };
    "payment.succeeded": WebhookPaymentData__dc4de7029bac;
    "payment.failed": WebhookPaymentData__dc4de7029bac;
    "entitlement.changed": {
        compiledPlanId?: string;
        lineageId?: string;
        status?: string;
        [key: string]: unknown;
    };
    "usage.threshold_reached": {
        subscriptionId?: string;
        subscriberId?: string;
        limitId?: string;
        threshold?: number;
        windowStartMs?: number;
        windowEndMs?: number;
        [key: string]: unknown;
    };
    "webhook.test": {
        businessId: string;
        sentAt: string;
        [key: string]: unknown;
    };
}

WebhookEventName__516efeb1d3c0

Declaration source: packages/backend/dist/types/webhooks/types.d.ts#L6.

export type WebhookEventName__516efeb1d3c0 = (typeof WEBHOOK_EVENT_NAMES__b1fde63f3b9d)[number];

WebhookPaymentData__dc4de7029bac

Declaration source: packages/backend/dist/types/webhooks/types.d.ts#L59.

export interface WebhookPaymentData__dc4de7029bac {
    subscriptionId?: string;
    invoiceId?: string;
    amount?: number | null;
    currency?: string | null;
    reason?: string;
    [key: string]: unknown;
}

assertNotProduction#

AuthzDecisionEntry#

buildPersonaMap#

CONTEXT_HEADER_NAME#

createDevGateway#

createDevRuntime#

createDevRuntimeFromEnv#

CreateDevRuntimeOptions#

createPersonaClient#

DEFAULT_KEYS_FILE#

DEFAULT_PERSONAS#

definePersona#

DEV_CORE_URL#

DEV_JWKS_URL#

DEV_METERING_ENDPOINT#

DevGateway#

DevGatewayOptions#

DevKeysFile#

DevMode#

devModeFromEnv#

DevModeInProductionError#

DevRuntime#

DevSignerKeys#

DevTrace#

DevTraceSink#

DevUsageEvent#

DevUsageSink#

FartherShoreDevInstance#

generateDevSignerKeys#

isProductionEnv#

makeSignedRequest#

memoryJwks#

MeteringTraceEntry#

PersonaClientContext#

personaClientFromKeysFile#

PersonaDefinition#

PersonaRequest#

PersonaRequestSpec#

readDevKeysFile#

redactValue#

SettableRequest#

signContextToken#

SIGNED_HEADER_NAMES#

SignedHeaderOverrides#

SignedRequestSpec#

SignedTestWebhook#

signWebhookForTesting#

SignWebhookForTestingInput#

TEST_CONTEXT_KID#

TEST_CONTEXT_SECRET#

TEST_KID#

TEST_PRIVATE_JWK#

TEST_PUBLIC_JWK#

TracedCarrier#

unreachableJwks#

VerificationOutcome#

writeDevKeysFile#

Supporting declarations#

CanonicalSigningInput__d7cf4cea4ad9#

ConsumerPrincipal__16f951b9786d#

ExpressMiddleware__416c4ad228c7#

ExpressNext__c3f550fc71bd#

ExpressRequestLike__f93080abdbb9#

ExpressResponseLike__7a6dd95793e1#

FartherShore__b6398b2ddfc7#

FartherShoreInitOptions__d009c6effb6b#

FartherShoreRequestContext__fee40dd450e8#

FartherShoreSignedContext__24c947c09583#

FartherShoreTunnelOptions__07694d2dbe44#

HandlerOptions__89c221f2c3e0#

HeadersLike__89315298f855#

Jwk__10747812bcb3#

JwksCacheState__075013cca763#

JwksClient__3bf9d241c5e2#

JwksClientOptions__1aedfc6c12a8#

JwksObservation__b0d7452a7cf1#

JwksObserver__4d7082fe0d6b#

MeasurementDimensions__e2d8137e24a6#

MeasurementValues__ab2d89ace8f2#

MiddlewareOptions__b16fbb0c44c2#