@farthershore/backend 0.15.0 → 0.16.0

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
@@ -133,11 +133,6 @@ export declare const RUNTIME_HEADER_NAMES: {
     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;
@@ -171,6 +166,14 @@ export type CanonicalSigningInput = {
     /** 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";

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;
 };

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

@@ -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.15.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,16 +30,17 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "optionalDependencies": {
     "@farthershore/cloudflared-linux-x64": "0.0.0",
-    "@farthershore/cloudflared-darwin-arm64": "0.0.0",
     "@farthershore/cloudflared-linux-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"