@farthershore/backend 0.12.0 → 0.14.0

package/dist/types/core/post-stream-usage.d.ts

@@ -0,0 +1,45 @@
+import type { RuntimeMeteringConfig } from "../runtime-types.js";
+export type ReportUsageInput = {
+    requestId: string;
+    subscriptionId: string;
+    meters: Record<string, number>;
+    creditUnitsConsumed?: Record<string, number>;
+    measureContext?: Record<string, unknown>;
+};
+export type RequestScopedReportUsageInput = Omit<ReportUsageInput, "requestId" | "subscriptionId"> & {
+    requestId?: string;
+    subscriptionId?: string;
+};
+export type ReportUsageResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type PostStreamUsageClientOptions = {
+    config: RuntimeMeteringConfig;
+    coreUrl?: string;
+    fetchImpl?: typeof fetch;
+    newNonce?: () => string;
+    logger?: (message: string) => void;
+    /** Injectable for tests; defaults to a normal timer-backed delay. */
+    sleep?: (delayMs: number) => Promise<void>;
+    /** Backoff after each request-not-found response. */
+    retryDelaysMs?: readonly number[];
+};
+/**
+ * Best-effort, attested post-stream billing reporter. The callback is
+ * request-bound in Core but never settles a Durable Object enforcement window.
+ * Every failure resolves ok:false.
+ */
+export declare class PostStreamUsageClient {
+    private readonly config;
+    private readonly endpoint;
+    private readonly fetchImpl;
+    private readonly newNonce;
+    private readonly logger;
+    private readonly sleep;
+    private readonly retryDelaysMs;
+    constructor(options: PostStreamUsageClientOptions);
+    reportUsage(input: ReportUsageInput): Promise<ReportUsageResult>;
+}

package/dist/types/core/runtime.d.ts

@@ -1,6 +1,7 @@
 import { type RuntimeBootstrapResponse, type RuntimeHealthReport } from "../runtime-types.js";
 import type { ReconcileResult } from "../reflect/reconcile.js";
 import { type MeterOptions } from "./metering.js";
+import { type ReportUsageInput, type ReportUsageResult } from "./post-stream-usage.js";
 import { type SpawnFn } from "./tunnel.js";
 import { type FartherShoreRequestContext, type VerifyRequestInput } from "./verifyRequest.js";
 /** Advanced opt-in tunnel config. The embedded runner is the default DX. */
@@ -95,6 +96,7 @@ export declare class FartherShore {
     private readonly shutdownManager;
     private jwks;
     private meteringClient;
+    private postStreamUsageClient;
     private tunnel;
     private bootstrapped;
     constructor(options?: FartherShoreInitOptions);
@@ -137,6 +139,8 @@ export declare class FartherShore {
     start(): Promise<void>;
     /** Record metering usage (billing-only). */
     meter(meter: string, qty: number, options?: MeterOptions): Promise<void>;
+    /** Best-effort attested post-stream usage callback. Never rejects. */
+    reportUsage(input: ReportUsageInput): Promise<ReportUsageResult>;
     /** Current local health report. */
     health(): RuntimeHealthReport;
     /** Graceful shutdown: flush metering + send a stopping heartbeat. */

package/dist/types/core/verifyRequest.d.ts

@@ -1,3 +1,4 @@
+import type { ReportUsageResult, RequestScopedReportUsageInput } from "./post-stream-usage.js";
 import { type FartherShoreSignedContext } from "./verifyContext.js";
 import type { JwksClient } from "./jwks.js";
 import type { NonceCache } from "./nonceCache.js";
@@ -48,6 +49,8 @@ export type FartherShoreRequestContext = {
     signedContext?: FartherShoreSignedContext;
     /** Managed-RBAC role keys the acting user holds (display/audit only). */
     roles?: string[];
+    /** Request-bound post-stream reporter, attached by the runtime facade. */
+    reportUsage?: (input: RequestScopedReportUsageInput) => Promise<ReportUsageResult>;
 };
 export type VerifyRequestDeps = {
     jwks: JwksClient;

package/dist/types/generated/runtime-contract.d.ts

@@ -149,14 +149,29 @@ export declare const RUNTIME_METERING_CONTRACT: {
         readonly backend_id: "string";
         readonly route_id: "string?";
         readonly request_id: "string?";
+        readonly requestId: "string?";
+        readonly subscriptionId: "string";
+        readonly nonce: "string?";
         readonly meter: "string";
         readonly qty: "number";
         readonly timestamp: "string";
     };
+    readonly postStreamEvent: {
+        readonly requestId: "string";
+        readonly subscriptionId: "string?";
+        readonly nonce: "string";
+        readonly meters: "Record<string, number>";
+        readonly creditUnitsConsumed: "Record<string, number>?";
+        readonly measureContext: "Record<string, unknown>?";
+        readonly signature: "string";
+    };
     readonly idempotencyKey: "event_id";
     readonly delivery: "at-least-once";
     readonly billingOnly: true;
     readonly realtimeEnforced: false;
+    readonly postStreamBillingOnly: true;
+    readonly postStreamRealtimeEnforced: false;
+    readonly postStreamTrustModel: "HMAC-attested and bound to one served postStreamBilling gateway request. Core writes one billable UsageEvent using the served plan and time. The callback never mutates Durable Object enforcement windows.";
     readonly trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
 };
 export declare const RUNTIME_RESPONSE_METERING_CONTRACT: {

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions } from "./core/nonceCache.js";
 export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";
 export { MeteringClient, type MeteringClientOptions, type MeterOptions, } from "./core/metering.js";
+export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type RequestScopedReportUsageInput, type ReportUsageResult, } from "./core/post-stream-usage.js";
 export { buildHealthReport, reportHealth, type HealthSnapshot, type HealthStatus, type HeartbeatOptions, } from "./core/health.js";
 export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
 export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";
@@ -19,7 +20,7 @@ export { createExpressMiddleware, type ExpressMiddleware, type ExpressRequestLik
 export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_CAPABILITIES, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenCapability, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, RUNTIME_ERROR_CODE_TO_ERROR_CODE, runtimeErrorToErrorCode, type LimitDescriptor, type RuntimeMappedErrorCode, } from "./runtime-types.js";
 export { RUNTIME_ERROR_CODES } from "./generated/runtime-contract.js";
 export { hashBody, buildCanonicalSigningString, canonicalizeQuery, signCanonicalString, verifyCanonicalSignature, runtimeTokenKind, } from "./runtime-signing.js";
-export { createUsage, withUsage, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, } from "./response-metering.js";
+export { createUsage, withUsage, computeMeteringHeaders, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, type MeteringHeaders, type ComputeMeteringOptions, type ResponseMeteringUsagePayload, } from "./response-metering.js";
 /**
  * The conceptual public entrypoint. `fartherShore.initFromEnv()` mirrors the
  * language-neutral spec. The returned instance is augmented with `middleware()`

package/dist/types/response-metering.d.ts

@@ -4,6 +4,41 @@ declare const RESPONSE_METERING_ERROR_CODES: {
     readonly invalidMeterValue: "invalid_meter_value";
 };
 type ResponseMeteringErrorCode = (typeof RESPONSE_METERING_ERROR_CODES)[keyof typeof RESPONSE_METERING_ERROR_CODES];
+/**
+ * The signed response-metering payload. `computeMeteringHeaders` accepts one of
+ * these directly, so a non-Express / non-Fetch handler (or a Python/Go backend
+ * following the wire recipe) can stamp valid headers without `withUsage`.
+ */
+export type ResponseMeteringUsagePayload = {
+    method: string;
+    path: string;
+    rawDimsUnits: Record<string, number>;
+    measureContext?: Record<string, unknown>;
+    creditUnitsConsumed?: Record<string, number>;
+    operationKey?: string;
+    usagePolicyId?: string;
+};
+/** The three response-metering headers as a plain, attachable name→value map. */
+export type MeteringHeaders = Record<string, string>;
+export type ComputeMeteringOptions = {
+    token?: string;
+    env?: Record<string, string | undefined>;
+    /** Gateway request id, for dev-mode trace/usage association (never signed). */
+    requestId?: string;
+    /**
+     * Called (instead of throwing) when headers cannot be stamped at request time
+     * — e.g. no token. The endpoint is never broken; usage is simply not metered.
+     */
+    onSkip?: (reason: string) => void;
+};
+export type DevMeteringHooks = {
+    /** Ephemeral token used when no real token is configured (dev only). */
+    fallbackToken?: () => string | undefined;
+    /** Record a reported payload (never alters the response). */
+    record?: (payload: ResponseMeteringUsagePayload, requestId?: string) => void;
+    /** Observe a request-time skip ("metering headers skipped: <reason>"). */
+    onSkip?: (reason: string, requestId?: string) => void;
+};
 export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
 export declare const METERING_SIGNATURE_HEADER: "x-fs-metering-sig";
 export declare const METERING_TOKEN_HEADER: "x-fs-metering-token";
@@ -38,4 +73,14 @@ export declare class MeteringError extends Error {
 }
 export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
 export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;
+/**
+ * Compute the three response-metering headers for a payload as a plain
+ * name→value map, attachable to ANY response mechanism (Fetch `Response`,
+ * Express `res.set`, a raw header object). This is the metering-availability
+ * primitive: it NEVER throws at request time — if no token is resolvable (or
+ * signing fails) it skips stamping, reports the reason (`onSkip` / dev hook /
+ * a `console.warn`), and returns `{}` so the builder's endpoint is never broken.
+ * `withUsage`/`createUsage` are thin sugar over it.
+ */
+export declare function computeMeteringHeaders(payload: ResponseMeteringUsagePayload, options?: ComputeMeteringOptions): Promise<MeteringHeaders>;
 export {};

package/dist/types/runtime-types.d.ts

@@ -255,6 +255,16 @@ export type RuntimeMeteringEvent = {
     qty: number;
     timestamp: string;
 };
+/** Attested, request-bound billing callback sent after a stream completes. */
+export type RuntimePostStreamUsageEvent = {
+    requestId: string;
+    subscriptionId: string;
+    nonce: string;
+    meters: Record<string, number>;
+    creditUnitsConsumed?: Record<string, number>;
+    measureContext?: Record<string, unknown>;
+    signature: string;
+};
 export declare const RUNTIME_READINESS_STATES: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
 export type RuntimeReadinessState = (typeof RUNTIME_READINESS_STATES)[number];
 export type RuntimeHealthReport = {

package/dist/types/testing/devGateway.d.ts

@@ -0,0 +1,40 @@
+import { type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimePostStreamUsageEvent } from "../runtime-types.js";
+import type { DevMode } from "./traceSink.js";
+import type { DevSignerKeys } from "./signers.js";
+export declare const DEV_CORE_URL = "https://dev-gateway.farthershore.local";
+export declare const DEV_JWKS_URL = "https://dev-gateway.farthershore.local/.well-known/jwks.json";
+export declare const DEV_METERING_ENDPOINT = "https://dev-gateway.farthershore.local/v1/metering/events";
+export type DevGatewayOptions = {
+    mode: DevMode;
+    keys: DevSignerKeys;
+    productId?: string;
+    backendId?: string;
+    productSlug?: 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) => void;
+    /** Called for each captured attested post-stream report. */
+    onReportUsage?: (event: RuntimePostStreamUsageEvent) => void;
+};
+export type DevGateway = {
+    /** Inject this as `fetchImpl` when constructing the FartherShore runtime. */
+    fetchImpl: typeof fetch;
+    /** The bootstrap response this fixture serves. */
+    bootstrap: RuntimeBootstrapResponse;
+    /** Every captured background metering event (a capture == an ACK). */
+    meterEvents: RuntimeMeteringEvent[];
+    /** Every captured attested post-stream usage report. */
+    reportUsageEvents: RuntimePostStreamUsageEvent[];
+    productId: string;
+    backendId: string;
+    jwksUrl: string;
+};
+/**
+ * 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).
+ */
+export declare function createDevGateway(options: DevGatewayOptions): DevGateway;

package/dist/types/testing/devRuntime.d.ts

@@ -0,0 +1,68 @@
+import { FartherShore } from "../core/runtime.js";
+import { type ExpressMiddleware, type MiddlewareOptions } from "../adapters/express.js";
+import { type PermissionCarrier } from "../core/permissions.js";
+import { type DevGateway } from "./devGateway.js";
+import { DevUsageSink } from "./usageSink.js";
+import { DevTraceSink, type DevMode } from "./traceSink.js";
+import { type DevSignerKeys } from "./signers.js";
+import { type PersonaDefinition, type PersonaRequest } from "./personas.js";
+/** A permission carrier that also knows its request id (for trace keying). */
+export type TracedCarrier = PermissionCarrier & {
+    requestId?: string;
+};
+/** The FartherShore instance augmented with a bound Express middleware. */
+export type FartherShoreDevInstance = FartherShore & {
+    middleware(options?: MiddlewareOptions): ExpressMiddleware;
+    /** The dev harness attached to this runtime. */
+    dev: DevRuntime;
+};
+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[];
+    productId?: 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;
+};
+/** The dev harness returned by `createDevRuntime` and attached as `fs.dev`. */
+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): ExpressMiddleware;
+    /** Clear usage + trace + captured meter events. */
+    reset(): void;
+};
+/**
+ * Build a dev runtime: a real `FartherShore` wired to the in-process gateway and
+ * signed personas, plus assertable usage/trace side channels.
+ */
+export declare function createDevRuntime(options: CreateDevRuntimeOptions): DevRuntime;
+/** Whether `FS_DEV_MODE` selects a dev mode. Returns the mode or null. */
+export declare function devModeFromEnv(env: Record<string, string | undefined>): DevMode | null;
+/**
+ * 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.
+ */
+export declare function createDevRuntimeFromEnv(env?: Record<string, string | undefined>): FartherShoreDevInstance;

package/dist/types/testing/index.d.ts

@@ -0,0 +1,8 @@
+export { TEST_KID, TEST_PRIVATE_JWK, TEST_PUBLIC_JWK, TEST_CONTEXT_SECRET, TEST_CONTEXT_KID, makeSignedRequest, memoryJwks, unreachableJwks, signContextToken, generateDevSignerKeys, type SignedHeaderOverrides, type SignedRequestSpec, type DevSignerKeys, } from "./signers.js";
+export { definePersona, createPersonaClient, buildPersonaMap, DEFAULT_PERSONAS, CONTEXT_HEADER_NAME, SIGNED_HEADER_NAMES, type PersonaDefinition, type PersonaRequest, type PersonaRequestSpec, type PersonaClientContext, type SettableRequest, } from "./personas.js";
+export { createDevGateway, DEV_CORE_URL, DEV_JWKS_URL, DEV_METERING_ENDPOINT, type DevGateway, type DevGatewayOptions, } from "./devGateway.js";
+export { createDevRuntime, createDevRuntimeFromEnv, devModeFromEnv, type DevRuntime, type CreateDevRuntimeOptions, type FartherShoreDevInstance, type TracedCarrier, } from "./devRuntime.js";
+export { writeDevKeysFile, readDevKeysFile, personaClientFromKeysFile, DEFAULT_KEYS_FILE, type DevKeysFile, } from "./keysFile.js";
+export { DevUsageSink, type DevUsageEvent } from "./usageSink.js";
+export { DevTraceSink, redactValue, type DevTrace, type DevMode, type VerificationOutcome, type AuthzDecisionEntry, type MeteringTraceEntry, } from "./traceSink.js";
+export { isProductionEnv, assertNotProduction, DevModeInProductionError, } from "./prodGuard.js";

package/dist/types/testing/keysFile.d.ts

@@ -0,0 +1,30 @@
+import type { DevMode } from "./traceSink.js";
+import type { DevSignerKeys } from "./signers.js";
+import { type PersonaDefinition, type PersonaRequest } from "./personas.js";
+export declare const DEFAULT_KEYS_FILE = ".farthershore/dev-keys.json";
+/** The on-disk shape of the dev-keys handoff file. */
+export type DevKeysFile = {
+    version: 1;
+    mode: DevMode;
+    keys: DevSignerKeys;
+    productId: string;
+    backendId: string;
+    /** Persona definitions in effect for this dev session. */
+    personas: Record<string, PersonaDefinition>;
+};
+/** Write the dev-keys file with 0600 permissions (owner read/write only). */
+export declare function writeDevKeysFile(path: string, contents: DevKeysFile): void;
+/** Read + parse a dev-keys file. */
+export declare function readDevKeysFile(path?: string): DevKeysFile;
+/**
+ * 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.
+ */
+export declare function personaClientFromKeysFile(path?: string, options?: {
+    fetchImpl?: typeof fetch;
+}): {
+    asPersona(name: string): PersonaRequest;
+    personas: Map<string, PersonaDefinition>;
+    file: DevKeysFile;
+};

package/dist/types/testing/personas.d.ts

@@ -0,0 +1,104 @@
+import type { DevMode } from "./traceSink.js";
+import { type DevSignerKeys } from "./signers.js";
+/** A named identity in the platform's test-persona claim vocabulary. */
+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;
+};
+/** Identity-neutral pass-through of a persona definition (readability sugar). */
+export declare function definePersona(def: PersonaDefinition): PersonaDefinition;
+/** The four built-in personas: owner / admin / member / anonymous. */
+export declare const DEFAULT_PERSONAS: Record<string, PersonaDefinition>;
+/** A minimal `.set(name, value)`-carrying request (supertest `Test`, etc.). */
+export type SettableRequest = {
+    method?: string;
+    url?: string;
+    path?: string;
+    set(field: string, value: string): unknown;
+};
+/** A single request spec for `.headers()`. */
+export type PersonaRequestSpec = {
+    method?: string;
+    path?: string;
+    query?: string;
+    body?: Uint8Array | null;
+    streamingExempt?: boolean;
+    routeId?: string;
+    requestId?: string;
+    timestamp?: number;
+};
+/** The context a persona client signs against (bootstrap ids + dev keys). */
+export type PersonaClientContext = {
+    keys: DevSignerKeys;
+    productId: 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;
+};
+/** The request-builder returned by `asPersona(name)`. */
+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>;
+};
+/**
+ * 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`).
+ */
+export declare function createPersonaClient(ctx: PersonaClientContext): {
+    asPersona(name: string): PersonaRequest;
+    personas: Map<string, PersonaDefinition>;
+};
+/** Merge caller personas over the built-in defaults into a name→def map. */
+export declare function buildPersonaMap(overrides?: Record<string, PersonaDefinition> | PersonaDefinition[]): Map<string, PersonaDefinition>;
+/** The header name for the signed context (exported for assertions). */
+export declare const CONTEXT_HEADER_NAME = "x-fs-context";
+/** The signed request header names (exported for assertions). */
+export 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 productId: "x-fs-product-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";
+};

package/dist/types/testing/prodGuard.d.ts

@@ -0,0 +1,12 @@
+/** Case-insensitive `NODE_ENV=production` check (matches core's `isProductionEnv`). */
+export declare function isProductionEnv(env?: Record<string, string | undefined>): boolean;
+/** Thrown when a dev runtime is constructed in a production process. */
+export declare class DevModeInProductionError extends Error {
+    constructor(context: string);
+}
+/**
+ * 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").
+ */
+export declare function assertNotProduction(context: string, env?: Record<string, string | undefined>): void;

package/dist/types/testing/signers.d.ts

@@ -0,0 +1,89 @@
+import { type CanonicalSigningInput } from "../runtime-types.js";
+import { JwksClient } from "../core/jwks.js";
+import type { FartherShoreSignedContext } from "../core/verifyContext.js";
+export declare const TEST_KID = "fs-runtime-test-2026";
+export declare const TEST_PRIVATE_JWK: JsonWebKey;
+export declare const TEST_PUBLIC_JWK: JsonWebKey;
+/** The default HS256 context-signing secret for dev fixtures (NEVER production). */
+export declare const TEST_CONTEXT_SECRET = "fs-dev-context-secret-2026";
+/** The default context-signing kid stamped into the JWT header. */
+export declare const TEST_CONTEXT_KID = "fs-context-test-2026";
+export type SignedHeaderOverrides = Partial<{
+    signature: string;
+    kid: string;
+    requestId: string;
+    timestamp: number;
+    productId: string;
+    backendId: string;
+    routeId: string;
+    policyVersion: string;
+    bodyHash: string;
+}>;
+export type SignedRequestSpec = {
+    method?: string;
+    path?: string;
+    query?: string;
+    body?: Uint8Array | null;
+    streamingExempt?: boolean;
+    productId?: 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;
+};
+/**
+ * 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.
+ */
+export declare function makeSignedRequest(spec?: SignedRequestSpec): Promise<{
+    input: {
+        method: string;
+        path: string;
+        query: string;
+        body: Uint8Array | null;
+        streamingExempt: boolean;
+    };
+    claim: CanonicalSigningInput;
+    headers: Record<string, string>;
+}>;
+/** A JwksClient backed by an in-memory key set (no network). */
+export declare function memoryJwks(keys?: Array<JsonWebKey & {
+    kid?: string;
+}>): JwksClient;
+/** A JwksClient whose fetch always throws (cold-cache failure). */
+export declare function unreachableJwks(): JwksClient;
+/**
+ * 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:1` claim shape (orgId / actor / productId / compiledPlanId
+ * / subscriptionId / subscriberId / environmentId / subjectKey plus optional
+ * permissions / roles). Signs with the same secret the SDK would verify against
+ * (`contextSecrets` / `FS_CONTEXT_SECRETS`).
+ */
+export declare function signContextToken(claim: FartherShoreSignedContext, secret?: string, kid?: string): Promise<string>;
+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;
+};
+/**
+ * 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).
+ */
+export declare function generateDevSignerKeys(): DevSignerKeys;

package/dist/types/testing/traceSink.d.ts

@@ -0,0 +1,67 @@
+export type DevMode = "passthrough" | "simulated";
+export type VerificationOutcome = "verified" | "passthrough" | "rejected";
+export type AuthzDecisionEntry = {
+    permission: string;
+    decision: "allow" | "deny";
+    reason?: string;
+};
+export type MeteringTraceEntry = {
+    meters: Record<string, number>;
+    source: "response" | "meter";
+};
+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;
+    };
+};
+/** Redact anything that smells like a credential from a free-form string. */
+export declare function redactValue(input: string): string;
+/**
+ * Accumulates one `DevTrace` per request id and (optionally) appends each
+ * completed trace as a single JSONL line via the injected `appendLine` sink.
+ */
+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;
+}