@farthershore/backend 0.15.0 → 0.17.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, credentialKind, isPortalSession, 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,8 +17,8 @@ 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 { 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 { 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_OPERATIONS, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenOperation, 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, 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";
@@ -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
@@ -119,8 +119,8 @@ export declare const RUNTIME_TOKEN_PREFIXES: {
     readonly test: "fsrt_test_";
 };
 export type RuntimeTokenKind = keyof typeof RUNTIME_TOKEN_PREFIXES;
-export declare const RUNTIME_TOKEN_CAPABILITIES: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];
-export type RuntimeTokenCapability = (typeof RUNTIME_TOKEN_CAPABILITIES)[number];
+export declare const RUNTIME_TOKEN_OPERATIONS: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];
+export type RuntimeTokenOperation = (typeof RUNTIME_TOKEN_OPERATIONS)[number];
 export declare const RUNTIME_HEADER_NAMES: {
     readonly signature: "x-fs-signature";
     readonly keyId: "x-fs-key-id";
@@ -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";
@@ -234,7 +237,7 @@ export type RuntimeBootstrapResponse = {
         id: string | null;
         kind: RuntimeEnvironmentKind;
     };
-    capabilities: RuntimeTokenCapability[];
+    operations: RuntimeTokenOperation[];
     verification: RuntimeVerificationConfig;
     metering: RuntimeMeteringConfig;
     transport: RuntimeTransportConfig;
@@ -270,8 +273,6 @@ export type RuntimePostStreamUsageEvent = {
     measureContext?: Record<string, unknown>;
     signature: string;
 };
-export declare const RUNTIME_READINESS_STATES: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
-export type RuntimeReadinessState = (typeof RUNTIME_READINESS_STATES)[number];
 export type RuntimeHealthReport = {
     runtimeToken: boolean;
     bootstrap: boolean;

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.17.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"