@farthershore/backend 0.3.0 → 0.8.0

package/README.md

@@ -4,6 +4,10 @@ Runtime metering and gateway-verification SDK for builder upstreams. Install one
 package, set one token (`FS_RUNTIME_TOKEN`), and Farther Shore handles signed
 gateway-to-upstream request verification plus response-bound usage reporting.
 
+> **Status: `0.8.0` (lockstep SDK family).** Published at the SAME version as
+> `@farthershore/farthershore-js` and `@farthershore/product` — pin the three
+> together. Pre-1.0: minor bumps may break.
+
 ## Install
 
 ```sh

package/dist/adapters/express.js

@@ -4,11 +4,17 @@ import { createRequire as __createRequire } from "node:module";const require=__c
 var FartherShoreError = class extends Error {
   code;
   status;
-  constructor(code, message, status) {
+  /** Present only when this error is a self-minted plan-limit deny (rare; the
+   *  backend usually relays the gateway's descriptor-bearing deny instead). */
+  limitDescriptor;
+  constructor(code, message, status, limitDescriptor) {
     super(message);
     this.name = "FartherShoreError";
     this.code = code;
     this.status = status ?? statusForCode(code);
+    if (limitDescriptor !== void 0) {
+      this.limitDescriptor = limitDescriptor;
+    }
   }
 };
 function statusForCode(code) {

package/dist/index.js

@@ -184,7 +184,102 @@ var init_reconcile = __esm({
   }
 });
 
+// src/generated/runtime-contract.ts
+var RUNTIME_BODY_HASH_CONTRACT = {
+  algorithm: "SHA-256",
+  encoding: "hex-lower",
+  source: "raw-request-bytes",
+  emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  maxBodyBytes: 10485760,
+  streamingExemptToken: "STREAM",
+  streamingExemptContentTypes: [
+    "text/event-stream",
+    "application/octet-stream",
+    "multipart/form-data"
+  ],
+  overMaxStatus: 413
+};
+var RUNTIME_ERROR_CODES = {
+  missingSignature: "missing_signature",
+  malformedSignature: "malformed_signature",
+  unknownKeyId: "unknown_key_id",
+  jwksUnavailable: "jwks_unavailable",
+  badSignature: "bad_signature",
+  bodyHashMismatch: "body_hash_mismatch",
+  routeMismatch: "route_mismatch",
+  clockSkew: "clock_skew",
+  expiredSignature: "expired_signature",
+  replayedNonce: "replayed_nonce",
+  bodyTooLarge: "body_too_large",
+  environmentMismatch: "environment_mismatch",
+  missingToken: "missing_token",
+  invalidToken: "invalid_token"
+};
+var RUNTIME_RESPONSE_METERING_CONTRACT = {
+  headers: {
+    payload: "x-fs-metering",
+    signature: "x-fs-metering-sig",
+    token: "x-fs-metering-token"
+  },
+  token: {
+    environmentVariable: "FS_RUNTIME_TOKEN",
+    presentation: "x-fs-metering-token",
+    storage: "sha256-hash-only"
+  },
+  signature: {
+    algorithm: "HMAC-SHA256",
+    encoding: "base64url",
+    input: "payload-json",
+    secret: "presented-runtime-token"
+  },
+  payload: {
+    method: "string",
+    path: "string",
+    rawDimsUnits: "Record<string, number>",
+    measureContext: "Record<string, unknown>?",
+    creditUnitsConsumed: "Record<string, number>?"
+  },
+  errors: {
+    missingToken: "missing_token",
+    invalidMeterKey: "invalid_meter_key",
+    invalidMeterValue: "invalid_meter_value"
+  },
+  httpAdapter: {
+    input: "Request",
+    output: "Response",
+    networkCalls: false,
+    preserves: ["body", "headers", "status", "statusText"],
+    gatewayStripsInternalHeaders: true
+  }
+};
+
 // src/runtime-types.ts
+var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
+  // Credential / token presentation faults → UNAUTHORIZED (401).
+  [RUNTIME_ERROR_CODES.missingToken]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.invalidToken]: "UNAUTHORIZED",
+  // Signature / key faults → UNAUTHORIZED (401, fail-closed verification).
+  [RUNTIME_ERROR_CODES.missingSignature]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.malformedSignature]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.unknownKeyId]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.badSignature]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.expiredSignature]: "UNAUTHORIZED",
+  // Replay / freshness faults → UNAUTHORIZED (401).
+  [RUNTIME_ERROR_CODES.clockSkew]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.replayedNonce]: "UNAUTHORIZED",
+  // Request/route binding faults → UNAUTHORIZED (401, fail-closed).
+  [RUNTIME_ERROR_CODES.bodyHashMismatch]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.routeMismatch]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.environmentMismatch]: "UNAUTHORIZED",
+  // JWKS fetch unavailable — dependency fault (still 401 to the client), but
+  // the canonical code keeps the "dependency down" semantic for callers.
+  [RUNTIME_ERROR_CODES.jwksUnavailable]: "SERVICE_UNAVAILABLE",
+  // The single non-401 (413) — oversized request body.
+  [RUNTIME_ERROR_CODES.bodyTooLarge]: "VALIDATION_ERROR"
+};
+function runtimeErrorToErrorCode(code) {
+  return RUNTIME_ERROR_CODE_TO_ERROR_CODE[code] ?? "INTERNAL_ERROR";
+}
 var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
 var RUNTIME_TOKEN_PREFIXES = {
   live: "fsrt_live_",
@@ -195,8 +290,11 @@ var RUNTIME_TOKEN_CAPABILITIES = [
   "metering",
   "health",
   "tunnel",
-  // Mirror of @farthershore/contracts RUNTIME_TOKEN_CAPABILITIES — kept in
-  // lockstep (golden-vector test). Opt-in capability for reporting route drift.
+  // Hand-maintained mirror of @farthershore/contracts RUNTIME_TOKEN_CAPABILITIES
+  // (`runtime.ts`). Bound to that source by the SET-EQUALITY + ORDER assertions
+  // in `deny-taxonomy-drift.test.ts` (test-only contracts devDep) — NOT by the
+  // generated runtime-contract.ts, which mirrors only RUNTIME_ERROR_CODES.
+  // `drift_report` is the opt-in capability for reporting route drift.
   "drift_report"
 ];
 var RUNTIME_HEADER_NAMES = {
@@ -346,11 +444,17 @@ var runtimeTokenKind2 = runtimeTokenKind;
 var FartherShoreError = class extends Error {
   code;
   status;
-  constructor(code, message, status) {
+  /** Present only when this error is a self-minted plan-limit deny (rare; the
+   *  backend usually relays the gateway's descriptor-bearing deny instead). */
+  limitDescriptor;
+  constructor(code, message, status, limitDescriptor) {
     super(message);
     this.name = "FartherShoreError";
     this.code = code;
     this.status = status ?? statusForCode(code);
+    if (limitDescriptor !== void 0) {
+      this.limitDescriptor = limitDescriptor;
+    }
   }
 };
 function statusForCode(code) {
@@ -1233,7 +1337,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.3.0".length > 0 ? "0.3.0" : "0.0.0-dev";
+var SDK_VERSION = "0.8.0".length > 0 ? "0.8.0" : "0.0.0-dev";
+var CONTRACTS_FP = "af8995b9467842b6".length > 0 ? "af8995b9467842b6" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1470,75 +1575,6 @@ function readProcessEnv() {
   return maybeProcess?.env ?? {};
 }
 
-// src/generated/runtime-contract.ts
-var RUNTIME_BODY_HASH_CONTRACT = {
-  algorithm: "SHA-256",
-  encoding: "hex-lower",
-  source: "raw-request-bytes",
-  emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-  maxBodyBytes: 10485760,
-  streamingExemptToken: "STREAM",
-  streamingExemptContentTypes: [
-    "text/event-stream",
-    "application/octet-stream",
-    "multipart/form-data"
-  ],
-  overMaxStatus: 413
-};
-var RUNTIME_ERROR_CODES = {
-  missingSignature: "missing_signature",
-  malformedSignature: "malformed_signature",
-  unknownKeyId: "unknown_key_id",
-  jwksUnavailable: "jwks_unavailable",
-  badSignature: "bad_signature",
-  bodyHashMismatch: "body_hash_mismatch",
-  routeMismatch: "route_mismatch",
-  clockSkew: "clock_skew",
-  expiredSignature: "expired_signature",
-  replayedNonce: "replayed_nonce",
-  bodyTooLarge: "body_too_large",
-  environmentMismatch: "environment_mismatch",
-  missingToken: "missing_token",
-  invalidToken: "invalid_token"
-};
-var RUNTIME_RESPONSE_METERING_CONTRACT = {
-  headers: {
-    payload: "x-fs-metering",
-    signature: "x-fs-metering-sig",
-    token: "x-fs-metering-token"
-  },
-  token: {
-    environmentVariable: "FS_RUNTIME_TOKEN",
-    presentation: "x-fs-metering-token",
-    storage: "sha256-hash-only"
-  },
-  signature: {
-    algorithm: "HMAC-SHA256",
-    encoding: "base64url",
-    input: "payload-json",
-    secret: "presented-runtime-token"
-  },
-  payload: {
-    method: "string",
-    path: "string",
-    rawDimsUnits: "Record<string, number>",
-    measureContext: "Record<string, unknown>?",
-    creditUnitsConsumed: "Record<string, number>?"
-  },
-  errors: {
-    missingToken: "missing_token",
-    invalidMeterKey: "invalid_meter_key",
-    invalidMeterValue: "invalid_meter_value"
-  },
-  httpAdapter: {
-    input: "Request",
-    output: "Response",
-    networkCalls: false,
-    preserves: ["body", "headers", "status", "statusText"],
-    gatewayStripsInternalHeaders: true
-  }
-};
-
 // src/adapters/express.ts
 var STREAMING_CONTENT_TYPES = new Set(
   RUNTIME_BODY_HASH_CONTRACT.streamingExemptContentTypes
@@ -1770,6 +1806,7 @@ export {
   REDACTED_TOKEN,
   RUNTIME_CLOCK_SKEW_SECONDS,
   RUNTIME_ERROR_CODES,
+  RUNTIME_ERROR_CODE_TO_ERROR_CODE,
   RUNTIME_HEADER_NAMES,
   RUNTIME_REPLAY_WINDOW_SECONDS,
   RUNTIME_TOKEN_CAPABILITIES,
@@ -1786,6 +1823,7 @@ export {
   initFromEnv2 as initFromEnv,
   nodeSpawn,
   reportHealth,
+  runtimeErrorToErrorCode,
   runtimeTokenKind2 as runtimeTokenKind,
   signCanonicalString2 as signCanonicalString,
   statusForCode,

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

@@ -1,12 +1,23 @@
 import type { RuntimeErrorCode } from "../generated/runtime-contract.js";
+import type { LimitDescriptor } from "../runtime-types.js";
 /**
  * A verification / runtime failure with a stable, cross-language `code` and the
  * fail-closed HTTP status the adapter should emit.
+ *
+ * Optionally carries a {@link LimitDescriptor} (`limitDescriptor`) when the
+ * failure is a plan-limit deny the backend chooses to surface itself, so SDKs
+ * can render an upgrade affordance from a backend-minted error. This is OPT-IN
+ * plumbing — the backend normally RELAYS the gateway's deny (which already
+ * carries the descriptor) rather than minting its own, so the field is absent on
+ * every verification/runtime failure. Additive; no behavior change.
  */
 export declare class FartherShoreError extends Error {
     readonly code: RuntimeErrorCode;
     readonly status: number;
-    constructor(code: RuntimeErrorCode, message: string, status?: number);
+    /** Present only when this error is a self-minted plan-limit deny (rare; the
+     *  backend usually relays the gateway's descriptor-bearing deny instead). */
+    readonly limitDescriptor?: LimitDescriptor;
+    constructor(code: RuntimeErrorCode, message: string, status?: number, limitDescriptor?: LimitDescriptor);
 }
 /**
  * Map a runtime error code to its fail-closed HTTP status. Oversized bodies are

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

@@ -41,6 +41,7 @@ export type FartherShoreInitOptions = {
     instanceId?: string;
 };
 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.

package/dist/types/index.d.ts

@@ -13,7 +13,7 @@ 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, } from "./runtime-types.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";
 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";

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

@@ -1,4 +1,53 @@
+import type { RuntimeErrorCode } from "./generated/runtime-contract.js";
 export type { RuntimeErrorCode } from "./generated/runtime-contract.js";
+/**
+ * C-1 — the machine-readable limit descriptor on a limit-deny body. A backend
+ * that surfaces a plan-limit deny carries this so SDKs can render an upgrade
+ * affordance. Structurally identical to the contracts `LimitDescriptor`.
+ */
+export interface LimitDescriptor {
+    /** Stable identifier for the limit hit — a `limitCode` VALUE
+     *  (`quota` | `rate_limit` | `credit` | `resource:<name>`), NOT a wire code. */
+    limitCode: string;
+    /** Metered/resource dimension when known; null otherwise. */
+    dimension: string | null;
+    /** The cap the subscriber is at when known; null otherwise. */
+    currentCapacity: number | null;
+}
+/**
+ * C-1 (BE-1) — the RUNTIME field set of the SDK-local {@link LimitDescriptor}
+ * mirror. `satisfies Record<keyof LimitDescriptor, true>` makes the compiler
+ * reject this if it drifts from the local interface; the drift guard
+ * (`deny-taxonomy-drift.test.ts`) then asserts it deep-equals the canonical
+ * contracts `LIMIT_DESCRIPTOR_FIELDS` at RUNTIME — so a hand-copy that adds or
+ * drops a field fails a test that actually runs. (Contracts-free: this is a
+ * plain local constant, never the published-types path to contracts.) */
+export declare const LIMIT_DESCRIPTOR_FIELDS: {
+    limitCode: true;
+    dimension: true;
+    currentCapacity: true;
+};
+/**
+ * C-2 — the canonical core `ErrorCode` VALUES this backend can map a
+ * `RuntimeErrorCode` onto (the codomain of {@link RUNTIME_ERROR_CODE_TO_ERROR_CODE}).
+ * The full core enum lives in the shared platform contracts; the SDK only needs
+ * 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";
+/**
+ * C-2 — map every canonical {@link RuntimeErrorCode} (wire snake_case value) to
+ * the core `ErrorCode` it belongs to. Total over `RuntimeErrorCode` (the
+ * `Record<RuntimeErrorCode, …>` type makes a missing key a compile error). A
+ * faithful copy of contracts' `RUNTIME_ERROR_CODE_TO_ERROR_CODE`.
+ */
+export declare const RUNTIME_ERROR_CODE_TO_ERROR_CODE: Record<RuntimeErrorCode, RuntimeMappedErrorCode>;
+/**
+ * C-2 — translate a runtime code into the canonical core `ErrorCode`. Returns
+ * `INTERNAL_ERROR` for an unrecognized value (defensive; the map is total over
+ * known codes). Mirrors contracts' `runtimeErrorToErrorCode`.
+ */
+export declare function runtimeErrorToErrorCode(code: string): RuntimeMappedErrorCode;
 export declare const FS_RUNTIME_TOKEN_ENV: "FS_RUNTIME_TOKEN";
 export declare const RUNTIME_TOKEN_PREFIXES: {
     readonly live: "fsrt_live_";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.3.0",
+  "version": "0.8.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",