@farthershore/backend 0.14.0 → 0.16.0

package/dist/types/index.d.ts

@@ -1,14 +1,15 @@
 import { FartherShore, type FartherShoreInitOptions } from "./core/runtime.js";
-import { type ExpressMiddleware, type MiddlewareOptions } from "./adapters/express.js";
+import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type MiddlewareOptions, type VerifiedExpressHandler } from "./adapters/express.js";
 export { FartherShore } from "./core/runtime.js";
 export type { FartherShoreInitOptions } from "./core/runtime.js";
 export { FartherShoreError, statusForCode } from "./core/errors.js";
 export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
-export { verifyContext } from "./core/verifyContext.js";
-export type { FartherShoreSignedContext } from "./core/verifyContext.js";
-export { hasPermission, requirePermission, permissionGrants, permissionSatisfies, parsePermissionHeader, FartherShorePermissionError, IDENTITY_HEADER_NAMES, type PermissionCarrier, } from "./core/permissions.js";
+export { verifyContext, decodeContextClaims, principalFromContextClaims, } from "./core/verifyContext.js";
+export type { FartherShoreSignedContext, ConsumerPrincipal, } from "./core/verifyContext.js";
+export { requireMember, requireService, type MemberSubject, type ServiceSubject, type PrincipalCarrier, } from "./core/subject.js";
+export { hasPermission, requirePermission, permissionGrants, permissionSatisfies, FartherShorePermissionError, type PermissionCarrier, } from "./core/permissions.js";
 export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
-export { NonceCache, type NonceCacheOptions } from "./core/nonceCache.js";
+export { NonceCache, type NonceCacheOptions, type NonceStore, } 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";
@@ -16,7 +17,7 @@ export { buildHealthReport, reportHealth, type HealthSnapshot, type HealthStatus
 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";
 export type { FartherShoreTunnelOptions } from "./core/runtime.js";
-export { createExpressMiddleware, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type MiddlewareOptions, } from "./adapters/express.js";
+export { createExpressMiddleware, createExpressHandler, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type MiddlewareOptions, type VerifiedExpressHandler, type VerifiedPrincipalContext, } from "./adapters/express.js";
 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";
@@ -27,8 +28,16 @@ export { createUsage, withUsage, computeMeteringHeaders, MeteringError, METERING
  * (the Express adapter) bound to itself.
  */
 export type FartherShoreInstance = FartherShore & {
-    /** Express middleware: fail-closed verify → req.fartherShore. */
+    /** Express middleware: strict fail-closed verify → req.fartherShore (+ strip x-fs-*). */
     middleware(options?: MiddlewareOptions): ExpressMiddleware;
+    /**
+     * Wrap a route handler so it runs only with a GUARANTEED verified PRINCIPAL —
+     * the handler's first argument is a {@link VerifiedPrincipalContext} whose
+     * `principal` is NON-OPTIONAL. Fails closed (401 `context_unverified` when the
+     * context is absent, `principal_required` when it is identity-less) before the
+     * callback runs. Pairs with the strict `middleware()`.
+     */
+    handler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
 };
 export declare const fartherShore: {
     /** Derive everything from FS_RUNTIME_TOKEN via bootstrap. */

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

@@ -48,6 +48,13 @@ export type BillableUsageMap = UsageMap;
 export type MeteringOptions = {
     token?: string;
     env?: Record<string, string | undefined>;
+    /**
+     * Gateway request id for dev-mode trace/usage association (never signed).
+     * Thread the VERIFIED `ctx.requestId` here — the strict middleware strips the
+     * inbound `x-fs-request-id` header, so the request object no longer carries it.
+     * Falls back to the request's `x-fs-request-id` header when unset.
+     */
+    requestId?: string;
     measureContext?: Record<string, unknown>;
     creditUnitsConsumed?: BillableUsageMap;
     /** Gateway-validated operation identity hint. The SDK signs and transports it

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

@@ -14,6 +14,13 @@ export declare const canonicalizeQuery: (query: string) => string;
  * dependence on JSON key order or Node Buffer serialization.
  */
 export declare const buildCanonicalSigningString: (input: CanonicalSigningInput) => string;
+/**
+ * SHA-256 hex of the presented `X-Fs-Context` JWT string (identity-context
+ * binding). A missing/empty context hashes the EMPTY string, so signer and
+ * verifier agree byte-for-byte when there is no identity context. The value
+ * feeds {@link CanonicalSigningInput.contextHash}.
+ */
+export declare const hashContextToken: (token: string | null | undefined) => Promise<string>;
 /** Sign the canonical string with an Ed25519 private JWK → base64url signature. */
 export declare const signCanonicalString: (canonical: string, privateJwk: JsonWebKey) => Promise<string>;
 /** Verify a base64url Ed25519 signature over the canonical string. */

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

@@ -99,7 +99,7 @@ export declare const DENY_ENVELOPE_FIELDS: {
  * the subset its bridge produces. Each is a verbatim core `ErrorCode` string —
  * the drift guard asserts membership in the canonical enum.
  */
-export type RuntimeMappedErrorCode = "UNAUTHORIZED" | "SERVICE_UNAVAILABLE" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+export type RuntimeMappedErrorCode = "UNAUTHORIZED" | "FORBIDDEN" | "SERVICE_UNAVAILABLE" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
 /**
  * C-2 — map every canonical {@link RuntimeErrorCode} (wire snake_case value) to
  * the core `ErrorCode` it belongs to. Total over `RuntimeErrorCode` (the
@@ -126,18 +126,13 @@ export declare const RUNTIME_HEADER_NAMES: {
     readonly keyId: "x-fs-key-id";
     readonly requestId: "x-fs-request-id";
     readonly timestamp: "x-fs-timestamp";
-    readonly productId: "x-fs-product-id";
+    readonly businessId: "x-fs-business-id";
     readonly backendId: "x-fs-backend-id";
     readonly routeId: "x-fs-route-id";
     readonly policyVersion: "x-fs-policy-version";
     readonly bodyHash: "x-fs-body-hash";
 };
 export type RuntimeHeaderName = (typeof RUNTIME_HEADER_NAMES)[keyof typeof RUNTIME_HEADER_NAMES];
-export declare const RUNTIME_IDENTITY_HEADER_NAMES: {
-    readonly permissions: "x-fs-permissions";
-    readonly roles: "x-fs-roles";
-};
-export type RuntimeIdentityHeaderName = (typeof RUNTIME_IDENTITY_HEADER_NAMES)[keyof typeof RUNTIME_IDENTITY_HEADER_NAMES];
 /** Mirrors SERVICE_JWT_CLOCK_SKEW_SECONDS — the per-request signer reuses the
  * same Ed25519/JWKS infra so the skew allowance is kept identical. */
 export declare const RUNTIME_CLOCK_SKEW_SECONDS = 5;
@@ -166,11 +161,19 @@ export type CanonicalSigningInput = {
     requestId: string;
     /** Unix epoch seconds at signing time. */
     timestamp: number;
-    productId: string;
+    businessId: string;
     backendId: string;
     /** Resolved route id; "" when unresolved. */
     routeId: string;
     policyVersion: string;
+    /**
+     * Consumer-principal wave (D3) — SHA-256 hex of the presented `X-Fs-Context`
+     * JWT string, or the SHA-256 of the EMPTY string when context signing is off.
+     * Bound into the canonical string so one request-signature verification
+     * covers both the request and the identity context. Compute via
+     * {@link hashContextToken}.
+     */
+    contextHash: string;
 };
 export type RuntimeEnvironmentKind = RuntimeTokenKind;
 export type TransportMode = "direct" | "tunnel";
@@ -221,7 +224,7 @@ export type RuntimeLockDescriptor = {
     lockVersion: number;
 };
 export type RuntimeBootstrapResponse = {
-    product: {
+    business: {
         id: string;
         slug: string;
     };
@@ -247,10 +250,15 @@ export type RuntimeBootstrapResponse = {
 };
 export type RuntimeMeteringEvent = {
     event_id: string;
-    product_id: string;
+    business_id: string;
     backend_id: string;
     route_id?: string;
     request_id?: string;
+    /** Subscription the usage belongs to (billing attribution). Optional and
+     *  additive: legacy emitters omit it; core then falls back to resolving the
+     *  served gateway request via `request_id`, and rows that resolve neither
+     *  way are persisted unbilled + flagged unattributable. */
+    subscription_id?: string;
     meter: string;
     qty: number;
     timestamp: string;

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

@@ -7,9 +7,9 @@ export declare const DEV_METERING_ENDPOINT = "https://dev-gateway.farthershore.l
 export type DevGatewayOptions = {
     mode: DevMode;
     keys: DevSignerKeys;
-    productId?: string;
+    businessId?: string;
     backendId?: string;
-    productSlug?: string;
+    businessSlug?: string;
     backendSlug?: string;
     /** Extra route ids to expose in bootstrap for route-binding tests. */
     routeIds?: string[];
@@ -27,7 +27,7 @@ export type DevGateway = {
     meterEvents: RuntimeMeteringEvent[];
     /** Every captured attested post-stream usage report. */
     reportUsageEvents: RuntimePostStreamUsageEvent[];
-    productId: string;
+    businessId: string;
     backendId: string;
     jwksUrl: string;
 };

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

@@ -1,5 +1,5 @@
 import { FartherShore } from "../core/runtime.js";
-import { type ExpressMiddleware, type MiddlewareOptions } from "../adapters/express.js";
+import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type MiddlewareOptions, type VerifiedExpressHandler } from "../adapters/express.js";
 import { type PermissionCarrier } from "../core/permissions.js";
 import { type DevGateway } from "./devGateway.js";
 import { DevUsageSink } from "./usageSink.js";
@@ -13,6 +13,8 @@ export type TracedCarrier = PermissionCarrier & {
 /** The FartherShore instance augmented with a bound Express middleware. */
 export type FartherShoreDevInstance = FartherShore & {
     middleware(options?: MiddlewareOptions): ExpressMiddleware;
+    /** Strict-context handler wrapper (guaranteed non-optional ctx). */
+    handler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
     /** The dev harness attached to this runtime. */
     dev: DevRuntime;
 };
@@ -24,7 +26,7 @@ export type CreateDevRuntimeOptions = {
     routes?: string[];
     /** Meter keys (informational — the dev gateway accepts any meter). */
     meters?: string[];
-    productId?: string;
+    businessId?: string;
     backendId?: string;
     /** Optional app transport for persona `.fetch()`; defaults to global fetch. */
     appFetch?: typeof fetch;

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

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

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

@@ -53,7 +53,7 @@ export type PersonaRequestSpec = {
 /** The context a persona client signs against (bootstrap ids + dev keys). */
 export type PersonaClientContext = {
     keys: DevSignerKeys;
-    productId: string;
+    businessId: string;
     backendId: string;
     contextSecret: string;
     contextKid: string;
@@ -96,7 +96,7 @@ export declare const SIGNED_HEADER_NAMES: {
     readonly keyId: "x-fs-key-id";
     readonly requestId: "x-fs-request-id";
     readonly timestamp: "x-fs-timestamp";
-    readonly productId: "x-fs-product-id";
+    readonly businessId: "x-fs-business-id";
     readonly backendId: "x-fs-backend-id";
     readonly routeId: "x-fs-route-id";
     readonly policyVersion: "x-fs-policy-version";

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

@@ -13,7 +13,7 @@ export type SignedHeaderOverrides = Partial<{
     kid: string;
     requestId: string;
     timestamp: number;
-    productId: string;
+    businessId: string;
     backendId: string;
     routeId: string;
     policyVersion: string;
@@ -25,7 +25,7 @@ export type SignedRequestSpec = {
     query?: string;
     body?: Uint8Array | null;
     streamingExempt?: boolean;
-    productId?: string;
+    businessId?: string;
     backendId?: string;
     routeId?: string;
     policyVersion?: string;
@@ -38,6 +38,13 @@ export type SignedRequestSpec = {
     privateJwk?: JsonWebKey;
     /** Key id stamped into `x-fs-key-id`. Defaults to {@link TEST_KID}. */
     kid?: string;
+    /**
+     * Consumer-principal wave (D3) — the signed `X-Fs-Context` JWT to bind into
+     * the request signature (and stamp as the `x-fs-context` header). Its SHA-256
+     * is appended to the canonical string, exactly as the gateway signer does. A
+     * missing token binds the empty-string hash (identity-less request).
+     */
+    contextToken?: string;
 };
 /**
  * Produce a valid signed claim + the X-FS-* header bag. Returns both the verify
@@ -63,10 +70,11 @@ 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`).
+ * payload is the cv=2 `ConsumerContextClaims` shape (sub / client_id? / act? /
+ * subjectKind / org / businessId / compiledPlanId / subscriptionId /
+ * subscriberId / environmentId / subjectKey plus optional permissions / roles).
+ * Signs with the same secret the SDK would verify against (`contextSecrets` /
+ * `FS_CONTEXT_SECRETS`).
  */
 export declare function signContextToken(claim: FartherShoreSignedContext, secret?: string, kid?: string): Promise<string>;
 export type DevSignerKeys = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, health, and lifecycle from FS_RUNTIME_TOKEN",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -38,8 +39,8 @@
   "optionalDependencies": {
     "@farthershore/cloudflared-linux-x64": "0.0.0",
     "@farthershore/cloudflared-linux-arm64": "0.0.0",
-    "@farthershore/cloudflared-darwin-arm64": "0.0.0",
-    "@farthershore/cloudflared-darwin-x64": "0.0.0"
+    "@farthershore/cloudflared-darwin-x64": "0.0.0",
+    "@farthershore/cloudflared-darwin-arm64": "0.0.0"
   },
   "peerDependencies": {
     "express": "^4.0.0 || ^5.0.0"