@farthershore/backend 0.15.0 → 0.17.0

package/dist/types/adapters/express.d.ts

@@ -1,5 +1,6 @@
 import type { FartherShore } from "../core/runtime.js";
 import type { FartherShoreRequestContext } from "../core/verifyRequest.js";
+import type { ConsumerPrincipal } from "../core/verifyContext.js";
 /** Minimal Express-shaped types so we don't hard-depend on @types/express. */
 export type ExpressRequestLike = {
     method: string;
@@ -22,16 +23,65 @@ export type ExpressNext = (err?: unknown) => void;
 export type ExpressMiddleware = (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNext) => void;
 export type MiddlewareOptions = {
     /**
-     * When true (default), a request is verified only if verification is REQUIRED
-     * by bootstrap. While verificationRequired=false (pre-keystone) the middleware
-     * passes requests through WITHOUT attaching a context — matching the deploy
-     * order where the signer is not yet live. Set `always: true` to verify
-     * regardless (the readiness harness / strict deployments).
+     * 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;
 };
+/**
+ * A verified request context whose {@link ConsumerPrincipal} is GUARANTEED
+ * present — the shape handed to a {@link VerifiedExpressHandler}. The raw
+ * `FartherShoreRequestContext.principal` is optional (an identity-less gateway
+ * request is legitimate on the `fs.middleware()` path); `fs.handler()` narrows to
+ * this type only AFTER rejecting an absent principal with `401 principal_required`,
+ * so the callback can read `ctx.principal` (and narrow with
+ * `requireMember`/`requireService`) without any optional-chaining.
+ */
+export type VerifiedPrincipalContext = FartherShoreRequestContext & {
+    principal: ConsumerPrincipal;
+};
+/**
+ * A route handler that runs only with a GUARANTEED verified PRINCIPAL. The first
+ * argument is the {@link VerifiedPrincipalContext} — read `ctx.principal` (and
+ * narrow with `requireMember`/`requireService`) without any optional-chaining.
+ * See {@link createExpressHandler}.
+ */
+export type VerifiedExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike> = (ctx: VerifiedPrincipalContext, req: Req, res: Res, next: ExpressNext) => void | Promise<void>;
 /**
  * Build the Express middleware. Captures raw body bytes, calls verifyRequest,
  * and fail-closes on any error.
  */
 export declare function createExpressMiddleware(fs: FartherShore, options?: MiddlewareOptions): ExpressMiddleware;
+/**
+ * Wrap a route handler so it runs only with a GUARANTEED verified PRINCIPAL. The
+ * strict {@link createExpressMiddleware} already attaches `req.fartherShore`
+ * before any handler runs; this closes the type gap by handing the handler a
+ * {@link VerifiedPrincipalContext} whose `principal` is NON-OPTIONAL (no
+ * optional-chaining to read `ctx.principal`). It enforces that guarantee at
+ * runtime with two fail-closed 401s BEFORE the callback runs:
+ *   - `context_unverified` when there is no verified context at all (handler
+ *     mounted without the middleware);
+ *   - `principal_required` when the context is verified but identity-less (a
+ *     valid gateway request that carried no `X-Fs-Context`) — so the callback is
+ *     never invoked with an absent `ctx.principal`.
+ * A thrown `FartherShoreError` / `FartherShorePermissionError` — e.g. from
+ * `requireMember(ctx)` — is mapped to its typed status; any other error is
+ * forwarded to `next` for the app's error pipeline.
+ *
+ * Returns the wide {@link ExpressMiddleware} so it drops straight into
+ * `app.post(path, fs.handler(...))`: a handler whose `req` is narrowed to a
+ * `{ fartherShore: ... }` request type is a SUBTYPE of Express's `Request` and
+ * would fail Express's `RequestHandler` assignability — moving the verified
+ * context onto its own `ctx` argument (not the `req` type) is what keeps the
+ * non-optional guarantee AND Express compatibility.
+ */
+export declare function createExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;

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

@@ -21,6 +21,9 @@ export declare class FartherShoreError extends Error {
 }
 /**
  * Map a runtime error code to its fail-closed HTTP status. Oversized bodies are
- * the only non-401 (413); all other verification failures are 401.
+ * 413; a wrong-credential-surface denial is 403 (the caller IS authenticated,
+ * just not on a surface this route admits — mirrors the canonical
+ * `surface_not_allowed → FORBIDDEN` mapping in contracts/error-codes.ts);
+ * all other verification failures are 401.
  */
 export declare function statusForCode(code: RuntimeErrorCode): number;

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

@@ -1,7 +1,29 @@
+/**
+ * Replay-prevention store contract. `checkAndRemember(id)` returns `true` if
+ * `id` was already seen (a REPLAY) and `false` on first sight (recording it).
+ *
+ * The default {@link NonceCache} is IN-MEMORY and PER-PROCESS: it prevents
+ * replay against a single instance only. A multi-replica backend where a
+ * captured, still-valid signed request is replayed to a DIFFERENT replica needs
+ * a SHARED store (Redis/Memcached/Cloudflare KV/Durable Object) — inject one via
+ * `FartherShoreInitOptions.nonceStore`. `checkAndRemember` may be async so a
+ * network-backed store can be awaited. (Time-bounding still caps the exposure
+ * to the signature's ~300s validity window regardless of the store.)
+ */
+export interface NonceStore {
+    checkAndRemember(id: string): boolean | Promise<boolean>;
+}
 export type NonceCacheOptions = {
-    /** Max distinct nonces retained. Oldest are evicted first. */
+    /**
+     * Max distinct nonces retained. At capacity (after expired nonces are
+     * removed) the cache FAILS CLOSED — new nonces are rejected as replays rather
+     * than evicting an unexpired one. Raise this for high single-instance
+     * throughput, or inject a shared {@link NonceStore}.
+     */
     maxEntries?: number;
-    /** TTL after which a nonce is forgotten (≥ replay window + skew). */
+    /** TTL after which a nonce is forgotten. Defaults to the signature validity
+     *  window (replay window + clock skew); a nonce older than that is rejected by
+     *  the timestamp check anyway. Must be ≥ that window. */
     ttlMs?: number;
     /** Injectable clock (tests). */
     now?: () => number;
@@ -11,7 +33,7 @@ export type NonceCacheOptions = {
  * the first time it sees an id, and true (replay) on any subsequent sighting
  * while the id is still retained.
  */
-export declare class NonceCache {
+export declare class NonceCache implements NonceStore {
     private readonly maxEntries;
     private readonly ttlMs;
     private readonly now;
@@ -25,5 +47,4 @@ export declare class NonceCache {
     /** Number of retained nonces (test/observability hook). */
     get size(): number;
     private evictExpired;
-    private evictOverflow;
 }

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

@@ -12,14 +12,6 @@ export declare class FartherShorePermissionError extends Error {
     readonly requiredPermission: string;
     constructor(requiredPermission: string, message?: string);
 }
-/**
- * Parse the comma-joined `x-fs-permissions` header into a permission list.
- * 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 — a FAITHFUL COPY of the canonical `permissionGrants` in
  * `@farthershore/contracts` (`rbac.ts`). Over a DEFINED array: a `"*"` entry
@@ -56,26 +48,28 @@ 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. */
+    /**
+     * 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;
 }
 /**
  * True when the acting user holds `key`. Call only with a verified request
- * context ({@link parsePermissionHeader} output lives on `context.permissions`).
+ * context (the verified `X-Fs-Context` permissions claim 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.
  *
- * 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
+ * FAIL-CLOSED: an ABSENT permission set (`ctx.permissions === undefined`)
+ * DENIES — absence NEVER means grant-all, and the presence of a verified signed
+ * context does NOT change that (its presence is not consulted). A DEFINED array
  * uses the unified {@link permissionSatisfies} rule (`*` / `<subject>:*` /
- * exact), so an explicit `["*"]` (org OWNER / RBAC-disabled) still grants
- * everything and `[]` denies.
+ * exact), so an explicit `["*"]` (org OWNER / RBAC-disabled) grants everything
+ * and `[]` denies. A builder that wants an ungated route simply does not call
+ * this / {@link requirePermission}.
  */
 export declare function hasPermission(ctx: PermissionCarrier, key: string): boolean;
 /**
@@ -83,8 +77,3 @@ export declare function hasPermission(ctx: PermissionCarrier, key: string): bool
  * (403) otherwise. Same trust model as {@link hasPermission}.
  */
 export declare function requirePermission(ctx: PermissionCarrier, key: string): void;
-/** Re-exported for callers that read the header name directly. */
-export declare const IDENTITY_HEADER_NAMES: {
-    readonly permissions: "x-fs-permissions";
-    readonly roles: "x-fs-roles";
-};

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

@@ -2,6 +2,7 @@ import { type RuntimeBootstrapResponse, type RuntimeHealthReport } from "../runt
 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 NonceStore } from "./nonceCache.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. */
@@ -41,40 +42,33 @@ export type FartherShoreInitOptions = {
     /** 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 business'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-business context
-     * forgery). The distribution mechanism — per-business 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.
+     * 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[];
     /**
-     * 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.
+     * OPTIONAL shared replay-prevention store. The default is an IN-MEMORY,
+     * PER-PROCESS {@link NonceCache} — it stops replay against a single instance
+     * only. A horizontally-scaled backend (multiple replicas / serverless
+     * instances) where a captured, still-valid signed request could be replayed
+     * to a DIFFERENT replica should inject a SHARED store (Redis / Memcached /
+     * Cloudflare KV / Durable Object) implementing {@link NonceStore}. The signed
+     * request's ~300s validity window bounds the exposure either way, but a shared
+     * store closes the cross-replica gap. `checkAndRemember` may be async.
      */
-    contextVerification?: "preferred" | "required";
+    nonceStore?: NonceStore;
 };
 export declare const SDK_VERSION: string;
-export declare const CONTRACTS_FP: string;
 /**
  * The runtime instance. Lazily bootstraps; holds the JWKS client, nonce cache,
  * metering buffer, and shutdown hooks.
@@ -88,10 +82,8 @@ 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. */
+    /** OPTIONAL HS256 secret(s) — defense-in-depth over the cv=2 X-Fs-Context. */
     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/subject.d.ts

@@ -0,0 +1,45 @@
+import type { ConsumerPrincipal } from "./verifyContext.js";
+/** The member arm of {@link ConsumerPrincipal}'s subject. */
+export type MemberSubject = Extract<ConsumerPrincipal["subject"], {
+    kind: "member";
+}>;
+/** The service arm of {@link ConsumerPrincipal}'s subject. */
+export type ServiceSubject = Extract<ConsumerPrincipal["subject"], {
+    kind: "service";
+}>;
+/** Anything carrying a verified {@link ConsumerPrincipal} (the request context). */
+export type PrincipalCarrier = {
+    principal?: ConsumerPrincipal;
+};
+/**
+ * Assert the request resolved to a MEMBER subject and return it narrowed. On a
+ * gateway-enforced `subject: 'member'` route this never throws; call it in
+ * handler code to read `memberId` without a manual discriminant check. Throws
+ * `member_subject_required` when the subject is a service (or absent).
+ */
+export declare function requireMember(ctx: PrincipalCarrier): MemberSubject;
+/**
+ * Assert the request resolved to a SERVICE subject and return it narrowed.
+ * Throws `service_subject_required` when the subject is a member (or absent).
+ */
+export declare function requireService(ctx: PrincipalCarrier): ServiceSubject;
+/**
+ * The credential SURFACE behind a verified request, DERIVED from the signed
+ * principal (route-surfaces wave) — no new claim, no spoofable header. A member
+ * subject carries `via`; a service subject is always key-borne. Returns
+ * `undefined` when the request carried no verified principal (identity-less), so
+ * a caller can distinguish "not a portal session" from "unknown".
+ *
+ *   - `"portal_session"` ⟺ a member via a browser session (`fsc_`).
+ *   - `"api_key"`        ⟺ a member's personal key OR any service key (`fsk_`).
+ */
+export declare function credentialKind(ctx: PrincipalCarrier): "portal_session" | "api_key" | undefined;
+/**
+ * True when the verified request came from the managed portal UI (a member
+ * browser session), false when it came from an API key, and `undefined` when
+ * there is no verified principal. Convenience over {@link credentialKind} for
+ * the common portal-vs-API branch (e.g. richer UI payloads for portal callers).
+ * The gateway's `enforce-surface` middleware is the SECURITY boundary; this is
+ * for in-handler ergonomics.
+ */
+export declare function isPortalSession(ctx: PrincipalCarrier): boolean | undefined;

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

@@ -1,33 +1,110 @@
 import { FartherShoreError } from "./errors.js";
-/** The signed context payload (claim-format cv=1). */
+/**
+ * The verified consumer principal derived from the cv=2 signed context — a
+ * tenant (`org`) plus exactly one subject. Local copy of the contracts
+ * `ConsumerPrincipal` (the SDK never leaks `@farthershore/contracts` into a
+ * public type signature; see runtime-signing.ts).
+ */
+export type ConsumerPrincipal = {
+    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;
+    };
+};
+/**
+ * The cv=2 signed-context payload the gateway stamps into `X-Fs-Context`. Local
+ * copy of the contracts `ConsumerContextClaims`. Identity rides the RFC 9068 /
+ * RFC 8693 claims (`sub`, `client_id`, `act`, `subjectKind`).
+ */
 export type FartherShoreSignedContext = {
-    /** Claim-format version. This SDK understands cv 1 (and legacy tokens
-     *  without cv, which predate UA-6 and carry no permissions). */
-    cv?: number;
-    orgId: string;
-    actor: {
-        type: string;
-        id: string | null;
+    /** 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;
     };
-    productId: string;
+    /** The org (tenant) id. */
+    org: string;
+    businessId: string;
     compiledPlanId: string;
     subscriptionId: string;
     subscriberId: string;
     environmentId: string | null;
     subjectKey: string;
-    /** UA-6 — the unified-authz permission claim (absent when unminted). */
-    permissions?: string[];
-    /** UA-6 — the bound role keys (absent when unminted). */
+    /** 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[];
 };
 /**
- * Verify an `X-Fs-Context` token against one or more HS256 secrets (try-all
- * for keyring rotation). Returns the typed payload on success, `null` on any
- * failure (malformed, wrong alg, bad signature, unparseable payload) — the
- * caller decides whether absence/invalidity is fatal (`required`) or falls
- * back to the transitional unsigned headers (`preferred`).
+ * Derive the {@link ConsumerPrincipal} from a verified cv=2 payload, FAIL-CLOSED.
+ *
+ * This is a thin, contracts-free-typed re-export of the SINGLE canonical
+ * derivation in `@farthershore/contracts` (`authz/principal.ts`). The SDK keeps
+ * its own local {@link ConsumerPrincipal} / {@link FartherShoreSignedContext}
+ * *types* (so the published `.d.ts` never leaks the private contracts package),
+ * but the derivation LOGIC lives in exactly one place — no drift is possible.
+ *
+ * Returns `null` — never a partially-populated principal — when any identity /
+ * authz field is invalid: an empty/whitespace `sub`/`org`/`businessId`, a
+ * missing/unknown `subjectKind`, a `service` subject with no `serviceAccountId`
+ * or `keyId`, a delegated `member` with an empty `act.sub`, a `permissions` /
+ * `roles` claim that is not an array of non-empty strings, or CONTRADICTORY
+ * identity evidence (a `serviceAccountId` that disagrees with `sub`, or a
+ * `client_id` that disagrees with `act.sub`). The caller (`verifyRequest`) treats
+ * `null` as tamper evidence and fails closed (`context_unverified`).
+ *
+ *  - service: `serviceAccountId = serviceAccountId ?? sub` (the two must agree),
+ *    `keyId = client_id ?? act.sub ?? sub`.
+ *  - member:  `memberId = sub`; `via = "api_key"` with `keyId = act.sub` when
+ *    the delegation claim is present, else `via = "session"`.
+ *
+ * Every derived id is the TRIMMED (canonical) value.
+ */
+export declare function principalFromContextClaims(claims: FartherShoreSignedContext): ConsumerPrincipal | null;
+/**
+ * Verify an `X-Fs-Context` token against one or more HS256 secrets (try-all for
+ * keyring rotation). Returns the typed cv=2 payload on success, `null` on any
+ * failure (malformed, wrong alg, bad signature, unparseable payload, OR a
+ * `cv !== 2` claim-format the SDK does not understand). The caller treats a
+ * `null` as fatal (fail-closed).
  */
 export declare function verifyContext(token: string, secrets: readonly string[]): Promise<FartherShoreSignedContext | null>;
-/** Thrown by verifyRequest when `contextVerification: "required"` and the
- *  signed context is missing or fails verification. */
+/**
+ * Decode + shape-check a cv=2 context token's PAYLOAD **without** verifying its
+ * HS256 signature. Safe to call ONLY after the token's authenticity has been
+ * established by another proof — in this SDK the presented `X-Fs-Context`'s
+ * SHA-256 (`contextHash`) is bound into the Ed25519-verified request signature,
+ * so once that request signature checks out the token bytes are byte-exact the
+ * ones the gateway signed and its CONTENT is gateway-vouched (no HS256 secret
+ * required). This is the DEFAULT identity path: with request signing on, a
+ * verified request always yields the principal even when no HS256 context secret
+ * is distributed to the backend. Returns the typed cv=2 claims, or `null` when
+ * the token is malformed or is not a cv=2 claim.
+ */
+export declare function decodeContextClaims(token: string): FartherShoreSignedContext | null;
+/** Thrown by verifyRequest when the signed context is missing or fails
+ *  verification (context signing is REQUIRED once context secrets exist). */
 export declare function contextRequiredError(reason: string): FartherShoreError;

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

@@ -1,7 +1,7 @@
 import type { ReportUsageResult, RequestScopedReportUsageInput } from "./post-stream-usage.js";
-import { type FartherShoreSignedContext } from "./verifyContext.js";
+import { type ConsumerPrincipal, type FartherShoreSignedContext } from "./verifyContext.js";
 import type { JwksClient } from "./jwks.js";
-import type { NonceCache } from "./nonceCache.js";
+import type { NonceStore } from "./nonceCache.js";
 /** Per-request input. `headers` keys are matched case-insensitively. */
 export type VerifyRequestInput = {
     method: string;
@@ -35,26 +35,37 @@ export type FartherShoreRequestContext = {
     meters?: string[];
     features?: Record<string, unknown>;
     /**
-     * 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}.
+     * 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;
+    /**
+     * 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[];
-    /** UA-6 — the VERIFIED signed context payload, when context secrets are
-     *  configured and the X-Fs-Context token verified. Its permissions/roles
-     *  populated the fields above (signed-preferred). */
+    /** The VERIFIED signed cv=2 context payload. Its permissions/roles populated
+     *  the fields above; its claims derived {@link principal}. */
     signedContext?: FartherShoreSignedContext;
-    /** Managed-RBAC role keys the acting user holds (display/audit only). */
+    /** Managed-RBAC role keys the acting subject 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;
-    nonceCache: NonceCache;
+    nonceCache: NonceStore;
     /** Expected business id (from bootstrap). When set, must match the signed claim. */
     businessId?: string;
     /** Expected backend id (from bootstrap). When set, must match. */
@@ -70,18 +81,17 @@ export type VerifyRequestDeps = {
     /** Injectable clock (seconds since epoch). */
     nowSeconds?: () => number;
     /**
-     * UA-6 — HS256 secret(s) for verifying the gateway's SIGNED `X-Fs-Context`
-     * claim (multiple = keyring rotation, try-all). When provided, a VERIFIED
-     * context's `permissions`/`roles` claims are preferred over the
-     * transitional unsigned identity headers.
+     * OPTIONAL HS256 secret(s) for the gateway's cv=2 `X-Fs-Context` claim
+     * (multiple = keyring rotation, try-all). Consumer-principal wave (D3): these
+     * are NOT required to produce the principal. The context token's authenticity
+     * comes from the Ed25519 REQUEST signature — the token's SHA-256 is bound into
+     * the canonical signing string, so a verified request already vouches for the
+     * token's content. Principal derivation therefore happens whenever a token is
+     * presented, with or without a configured secret. When these secrets ARE
+     * configured they add DEFENSE-IN-DEPTH: a presented token must ALSO pass HS256
+     * (a second, independent proof) or the request is rejected. Leaving this empty
+     * is the common case (the request-signature binding is sufficient).
      */
     contextSecrets?: readonly string[];
-    /**
-     * UA-6 — `"preferred"` (default): a missing/unverifiable signed context
-     * falls back to the unsigned headers. `"required"`: missing or invalid
-     * signed context REJECTS the request (fail-closed) — set this once your
-     * gateway config has context signing enabled.
-     */
-    contextVerification?: "preferred" | "required";
 };
 export declare function verifyRequest(input: VerifyRequestInput, deps: VerifyRequestDeps): Promise<FartherShoreRequestContext>;

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

@@ -73,11 +73,11 @@ export declare const RUNTIME_SIGNING_CONTRACT: {
         readonly keyValueSeparator: ":";
         readonly trailingNewline: false;
         readonly fieldEncoding: "utf-8";
-        readonly fields: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version"];
+        readonly fields: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version", "context-hash"];
         readonly fieldRules: {
             readonly method: "Uppercased HTTP method (e.g. GET, POST).";
             readonly path: "Request path, percent-encoded as received, no host, no query string. Always begins with '/'.";
-            readonly query: "Canonical query string: parse pairs, sort by (name, then value) using byte (code-unit) order, re-join name=value pairs with '&'. Names and values are NOT re-encoded (passed through as received). Empty string when there is no query.";
+            readonly query: "The request's query string bytes VERBATIM, after the caller has stripped the URL's single leading '?' delimiter. Use the RAW wire query exactly as received — NO sorting, NO filtering, NO re-stripping a leading '?', NO dropping empty pairs, NO re-encoding. The signature binds to the exact query bytes: any reorder, added/removed/relocated pair, or re-encoding changes the bytes and MUST fail verification. Every SDK verifier MUST read the raw wire query (never a re-parsed/re-serialized form, which could reorder or re-encode and would then fail legitimate requests). Any normalization (sorting by name or value, dropping/moving empty pairs, re-stripping '?') is FORBIDDEN — each collapses distinct wire queries under one signature. Empty string when there is no query.";
             readonly "body-hash": "Lowercase hex SHA-256 of the RAW request body bytes. For an empty body, the SHA-256 of zero bytes (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Streaming-exempt requests use the literal token 'STREAM'.";
             readonly "request-id": "Opaque unique request id minted by the gateway (also the replay-cache nonce).";
             readonly timestamp: "Integer Unix epoch seconds (UTC) at signing time, as a base-10 string with no padding.";
@@ -85,6 +85,7 @@ export declare const RUNTIME_SIGNING_CONTRACT: {
             readonly "backend-id": "Backend id the route binds to.";
             readonly "route-id": "Resolved route id; empty string if the route is unresolved.";
             readonly "policy-version": "Tenant artifact / policy version the gateway signed under.";
+            readonly "context-hash": "Lowercase hex SHA-256 of the presented X-Fs-Context JWT string (identity-context binding). For a request with no signed context, the SHA-256 of the empty string (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Binds the identity context into the request signature so one verification covers both.";
         };
     };
 };
@@ -92,7 +93,7 @@ export declare const RUNTIME_SIGNING_CONTRACT: {
  * Ordered list of fields in the canonical signing string. The order here is
  * load-bearing and identical across all language SDKs.
  */
-export declare const RUNTIME_CANONICAL_FIELDS: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version"];
+export declare const RUNTIME_CANONICAL_FIELDS: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version", "context-hash"];
 export declare const RUNTIME_BODY_HASH_CONTRACT: {
     readonly algorithm: "SHA-256";
     readonly encoding: "hex-lower";
@@ -137,6 +138,9 @@ export declare const RUNTIME_ERROR_CODES: {
     readonly missingToken: "missing_token";
     readonly invalidToken: "invalid_token";
     readonly contextUnverified: "context_unverified";
+    readonly memberSubjectRequired: "member_subject_required";
+    readonly serviceSubjectRequired: "service_subject_required";
+    readonly surfaceNotAllowed: "surface_not_allowed";
 };
 export type RuntimeErrorCode = (typeof RUNTIME_ERROR_CODES)[keyof typeof RUNTIME_ERROR_CODES];
 export declare const RUNTIME_METERING_CONTRACT: {