@farthershore/backend 0.11.0 → 0.13.0

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

@@ -1,3 +1,4 @@
+import type { FartherShoreSignedContext } from "./verifyContext.js";
 /**
  * Thrown by {@link requirePermission} when the acting user lacks a permission.
  * Distinct from {@link FartherShoreError} (which models signing/verification
@@ -13,25 +14,26 @@ export declare class FartherShorePermissionError extends Error {
 }
 /**
  * Parse the comma-joined `x-fs-permissions` header into a permission list.
- * Returns `undefined` when the header is absent (full-access grace) and `[]`
- * for a present-but-empty header (deny-all — an authenticated user with no
- * grants). Whitespace-trimmed; empty segments dropped.
+ * Returns `undefined` when the header is absent (no permission source ⇒
+ * carrier-level DENY under FAR-723) and `[]` for a present-but-empty header
+ * (deny-all — an authenticated user with no grants). Whitespace-trimmed; empty
+ * segments dropped.
  */
 export declare function parsePermissionHeader(raw: string | null | undefined): string[] | undefined;
 /**
- * Pure grant check. `undefined` permissions (no header) grant everything —
- * this backend SDK's LOCAL policy, parity with the edge treating an absent
- * claim as `["*"]`. Over a DEFINED array the rule is the shared core primitive:
- * a `"*"` entry grants everything, otherwise the key must be an exact member.
+ * Pure grant check — a FAITHFUL COPY of the canonical `permissionGrants` in
+ * `@farthershore/contracts` (`rbac.ts`). Over a DEFINED array: a `"*"` entry
+ * grants everything, otherwise the key must be an exact member. Its
+ * `undefined → true` codomain is the PRIMITIVE's contract (kept byte-identical
+ * to contracts for parity); it is NOT the SDK's carrier policy. Under FAR-723
+ * the carrier gate {@link hasPermission} DENIES an absent permission set before
+ * this primitive is consulted, so absence never grants at the boundary.
  *
- * The defined-array branch is a FAITHFUL COPY of the canonical
- * `permissionGrants` in `@farthershore/contracts` (`rbac.ts`) — the published
- * SDK surface must stay contracts-free, so it can't import it. A TEST-ONLY
- * parity guard (`permissions-parity.test.ts`, which CAN import contracts as a
- * devDependency) asserts this copy agrees with the canonical primitive across a
- * shared golden vector table, so the copy can't silently drift. The
- * `undefined → grant-all` grace is documented here as the SDK's own policy; the
- * shared primitive only covers the defined-array rule.
+ * The published SDK surface must stay contracts-free, so it can't import the
+ * canonical primitive. A TEST-ONLY parity guard (`permissions-parity.test.ts`,
+ * which CAN import contracts as a devDependency) asserts this copy agrees with
+ * the canonical primitive across a shared golden vector table, so the copy
+ * can't silently drift.
  */
 export declare function permissionGrants(permissions: readonly string[] | undefined, key: string): boolean;
 /**
@@ -39,8 +41,11 @@ export declare function permissionGrants(permissions: readonly string[] | undefi
  * unified grammar: `"*"` (global), `"<subject>:*"` (subject wildcard), or the
  * EXACT key. NO verb-class widening (class forms are expanded to concrete verbs
  * server-side at save time). Superset of {@link permissionGrants} — it adds the
- * `<subject>:*` rung — and keeps the backend SDK's `undefined → grant-all`
- * grace (absent `x-fs-permissions` header ⇒ full access, today's behavior).
+ * `<subject>:*` rung. NOTE: the `granted === undefined → true` codomain here is
+ * the PRIMITIVE's contract (kept byte-identical to contracts for parity); it is
+ * NOT the SDK's carrier policy. Callers gate through {@link hasPermission},
+ * which under FAR-723 DENIES an absent permission set before ever reaching this
+ * primitive — so absence never grants at the carrier level.
  *
  * FAITHFUL COPY of the canonical `permissionSatisfies` in
  * `@farthershore/contracts` (`authz/verbs.ts`); the published bundle is
@@ -51,13 +56,26 @@ export declare function permissionSatisfies(required: string, granted: readonly
 /** The subset of a verified context these helpers read. */
 export interface PermissionCarrier {
     permissions?: readonly string[];
+    /** The verified X-Fs-Context claims, when the request carried a valid token. */
+    signedContext?: FartherShoreSignedContext;
 }
 /**
  * True when the acting user holds `key`. Call only with a verified request
  * context ({@link parsePermissionHeader} output lives on `context.permissions`).
  * NOTE: this is a convenience for in-handler gating; the edge `permission`
- * constraint is the security boundary for route-level access. Uses the unified
- * {@link permissionSatisfies} rule (`*` / `<subject>:*` / exact).
+ * constraint is the security boundary for route-level access.
+ *
+ * FAR-723 FAIL-CLOSED: an ABSENT permission set (`ctx.permissions === undefined`)
+ * DENIES — the reverse of the former grant-all grace — UNLESS the request
+ * carried a cryptographically VERIFIED context token that simply omits the
+ * `perms` claim. Core deliberately mints ORG-actor (and unidentified-user-actor)
+ * `fsc_` tokens with no `perms` claim — RBAC never applies to them, and the edge
+ * `permission` constraint treats a verified claimless token as full access. The
+ * carrier mirrors the edge: verified-but-claimless ⇒ grant; no verified context
+ * AND no permission set ⇒ no trusted permission source ⇒ deny. A DEFINED array
+ * uses the unified {@link permissionSatisfies} rule (`*` / `<subject>:*` /
+ * exact), so an explicit `["*"]` (org OWNER / RBAC-disabled) still grants
+ * everything and `[]` denies.
  */
 export declare function hasPermission(ctx: PermissionCarrier, key: string): boolean;
 /**

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

@@ -39,6 +39,38 @@ export type FartherShoreInitOptions = {
     tunnel?: FartherShoreTunnelOptions;
     /** SDK metadata forwarded to bootstrap. */
     instanceId?: string;
+    /**
+     * FAR-723 / UA-6 — HS256 secret(s) for verifying the gateway's SIGNED
+     * `X-Fs-Context` claim. These are the GATEWAY CONTEXT-SIGNING keyring values
+     * (`CONTEXT_SIGNING_KEYS_JSON` — the keys `forward-upstream` stamps the
+     * header with; supply every live key during rotation — try-all). They are
+     * NOT the product's `contextTokenSecret`, which signs `fsc_` INGRESS tokens
+     * verified BY the gateway — setting that here would reject every valid
+     * gateway request in `"required"` mode. When present, a VERIFIED context's
+     * `permissions`/`roles` claims are the AUTHORITATIVE identity source
+     * (preferred over the transitional unsigned `x-fs-permissions`/`x-fs-roles`
+     * headers). Defaults to `FS_CONTEXT_SECRETS` (comma-separated) from the env.
+     *
+     * NOTE (core-side dependency, FAR-723 publish gate): no bootstrap field
+     * carries these keys yet, and handing the raw platform keyring to builder
+     * backends is NOT the end-state (it would allow cross-product context
+     * forgery). The distribution mechanism — per-product derived keys or an
+     * asymmetric context signature verified via JWKS like the request
+     * signature — is decided at the FAR-723 gate before the headers retire;
+     * until then this option (or `FS_CONTEXT_SECRETS`) is the manual wiring for
+     * platform-operated deployments.
+     */
+    contextSecrets?: readonly string[];
+    /**
+     * FAR-723 / UA-6 — `"preferred"` (default): a missing/unverifiable signed
+     * context falls back to the transitional unsigned headers.
+     * `"required"`: a missing or invalid signed context REJECTS the request
+     * (fail-closed), including when the context-secret keyring is empty or
+     * unconfigured. Defaults to `FS_CONTEXT_VERIFICATION` from the env, else
+     * `"preferred"`. The unsigned fallback is transitional and is removed after
+     * the backend-v* publish gate.
+     */
+    contextVerification?: "preferred" | "required";
 };
 export declare const SDK_VERSION: string;
 export declare const CONTRACTS_FP: string;
@@ -55,6 +87,10 @@ export declare class FartherShore {
     private readonly coreUrl;
     private readonly instanceId?;
     private readonly tunnelOptions;
+    /** FAR-723 — HS256 secret(s) for verifying the signed X-Fs-Context claim. */
+    private readonly contextSecrets;
+    /** FAR-723 — "preferred" (fallback to unsigned) | "required" (fail-closed). */
+    private readonly contextVerification;
     private readonly nonceCache;
     private readonly shutdownManager;
     private jwks;

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

@@ -34,11 +34,12 @@ export type FartherShoreRequestContext = {
     meters?: string[];
     features?: Record<string, unknown>;
     /**
-     * Managed-RBAC permissions the gateway resolved for the acting user, from
-     * the UNSIGNED `x-fs-permissions` identity header (trusted transitively on a
-     * verified request — see permissions.ts). `undefined` when the header is
-     * absent (full-access grace); `[]` for an authenticated user with no grants.
-     * Read via {@link hasPermission} / {@link requirePermission}.
+     * Managed-RBAC permissions the gateway resolved for the acting user —
+     * preferred from the VERIFIED signed `X-Fs-Context` claim, else the UNSIGNED
+     * `x-fs-permissions` identity header (both trusted transitively on a verified
+     * request — see permissions.ts). `undefined` when NO permission source was
+     * present ⇒ FAR-723 carrier-level DENY; `[]` for an authenticated user with
+     * no grants. Read via {@link hasPermission} / {@link requirePermission}.
      */
     permissions?: string[];
     /** UA-6 — the VERIFIED signed context payload, when context secrets are

package/dist/types/index.d.ts

@@ -19,7 +19,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/testing/devGateway.d.ts

@@ -0,0 +1,36 @@
+import { type RuntimeBootstrapResponse, type RuntimeMeteringEvent } 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;
+};
+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[];
+    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;
+}