@farthershore/backend 0.14.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # @farthershore/backend
 
-The runtime SDK for your own backend. When you run a software product on Farther
+The runtime SDK for your own backend. When you run a software business on Farther
 Shore with a bring-your-own-backend, the platform's edge gateway sits in front of
 your service. This package lets your backend **trust the gateway** (verify that
 each request really came from it) and **report usage** back for metering and
@@ -8,11 +8,11 @@ billing — from a single token, `FS_RUNTIME_TOKEN`.
 
 Install one package, set one environment variable, and you get fail-closed
 gateway-to-upstream request verification, response-bound usage reporting, and
-graceful lifecycle (health + shutdown). Everything else — your product, backend,
+graceful lifecycle (health + shutdown). Everything else — your business, backend,
 and environment ids, the verification keys, and the metering endpoint — is
 fetched automatically from the token at startup.
 
-> **Status: `0.14.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.15.0`.** Pre-1.0: minor releases may include breaking changes, so
 > pin this package to an exact version (or a patch-only range) and upgrade
 > deliberately.
 
@@ -76,7 +76,7 @@ process.on("SIGTERM", () => void fs.shutdown());
 ## What `initFromEnv()` derives
 
 You configure exactly one thing: `FS_RUNTIME_TOKEN` (mint it for your backend
-with the Farther Shore CLI or dashboard). Everything else — product / backend /
+with the Farther Shore CLI or dashboard). Everything else — business / backend /
 environment ids, the JWKS url used to verify signatures, the metering endpoint
 and credential, and verification settings — is fetched from the platform at
 startup and cached in memory. The token is validated eagerly, so a
@@ -126,11 +126,11 @@ export async function POST(request: Request) {
 
 - `measureContext` is free-form pricing/analytics context persisted with the
   usage event.
-- `creditUnitsConsumed` is a numeric map for credit-wallet style products; keys
+- `creditUnitsConsumed` is a numeric map for credit-wallet style businesses; keys
   and values are validated locally before signing.
 
 The meter keys you report (e.g. `tokens_used`) must match meters declared in your
-product. Request-count style limits are enforced by the gateway and need no
+business. Request-count style limits are enforced by the gateway and need no
 backend code.
 
 ## Async / background usage

package/dist/generated/runtime-contract.js

@@ -83,7 +83,7 @@ var RUNTIME_SIGNING_CONTRACT = {
       "body-hash",
       "request-id",
       "timestamp",
-      "product-id",
+      "business-id",
       "backend-id",
       "route-id",
       "policy-version"
@@ -95,7 +95,7 @@ var RUNTIME_SIGNING_CONTRACT = {
       "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'.",
       "request-id": "Opaque unique request id minted by the gateway (also the replay-cache nonce).",
       timestamp: "Integer Unix epoch seconds (UTC) at signing time, as a base-10 string with no padding.",
-      "product-id": "Product id the request is routed to.",
+      "business-id": "Business id the request is routed to.",
       "backend-id": "Backend id the route binds to.",
       "route-id": "Resolved route id; empty string if the route is unresolved.",
       "policy-version": "Tenant artifact / policy version the gateway signed under."
@@ -109,7 +109,7 @@ var RUNTIME_CANONICAL_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
   "policy-version"
@@ -133,7 +133,7 @@ var RUNTIME_HEADERS = {
   keyId: "x-fs-key-id",
   requestId: "x-fs-request-id",
   timestamp: "x-fs-timestamp",
-  productId: "x-fs-product-id",
+  businessId: "x-fs-business-id",
   backendId: "x-fs-backend-id",
   routeId: "x-fs-route-id",
   policyVersion: "x-fs-policy-version",
@@ -169,7 +169,7 @@ var RUNTIME_METERING_CONTRACT = {
   credential: "reusable-bearer",
   event: {
     event_id: "string",
-    product_id: "string",
+    business_id: "string",
     backend_id: "string",
     route_id: "string?",
     request_id: "string?",

package/dist/index.js

@@ -306,7 +306,7 @@ var RUNTIME_HEADER_NAMES = {
   keyId: "x-fs-key-id",
   requestId: "x-fs-request-id",
   timestamp: "x-fs-timestamp",
-  productId: "x-fs-product-id",
+  businessId: "x-fs-business-id",
   backendId: "x-fs-backend-id",
   routeId: "x-fs-route-id",
   policyVersion: "x-fs-policy-version",
@@ -358,7 +358,7 @@ var CANONICAL_SIGNING_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
   "policy-version"
@@ -395,7 +395,7 @@ function buildCanonicalSigningString(input) {
     "body-hash": input.bodyHash,
     "request-id": input.requestId,
     timestamp: String(input.timestamp),
-    "product-id": input.productId,
+    "business-id": input.businessId,
     "backend-id": input.backendId,
     "route-id": input.routeId,
     "policy-version": input.policyVersion
@@ -761,7 +761,7 @@ var DEFAULT_MAX_RETRIES = 3;
 var MeteringClient = class {
   config;
   endpoint;
-  productId;
+  businessId;
   backendId;
   fetchImpl;
   maxRetries;
@@ -775,7 +775,7 @@ var MeteringClient = class {
   constructor(options) {
     this.config = options.config;
     this.endpoint = resolveEndpoint(options.config.endpoint, options.coreUrl);
-    this.productId = options.productId;
+    this.businessId = options.businessId;
     this.backendId = options.backendId;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -838,13 +838,14 @@ var MeteringClient = class {
     }
     const event = {
       event_id: options.eventId ?? this.newId(),
-      product_id: this.productId,
+      business_id: this.businessId,
       backend_id: this.backendId,
       meter,
       qty,
       timestamp: options.timestamp ?? this.now().toISOString(),
       ...options.routeId ? { route_id: options.routeId } : {},
-      ...options.requestId ? { request_id: options.requestId } : {}
+      ...options.requestId ? { request_id: options.requestId } : {},
+      ...options.subscriptionId ? { subscription_id: options.subscriptionId } : {}
     };
     this.buffer.push(event);
     await this.flush();
@@ -1705,12 +1706,12 @@ async function verifyRequest(input, deps) {
   const kid = h(RUNTIME_HEADER_NAMES.keyId);
   const requestId = h(RUNTIME_HEADER_NAMES.requestId);
   const timestampRaw = h(RUNTIME_HEADER_NAMES.timestamp);
-  const signedProductId = h(RUNTIME_HEADER_NAMES.productId);
+  const signedBusinessId = h(RUNTIME_HEADER_NAMES.businessId);
   const signedBackendId = h(RUNTIME_HEADER_NAMES.backendId);
   const signedRouteId = h(RUNTIME_HEADER_NAMES.routeId) ?? "";
   const policyVersion = h(RUNTIME_HEADER_NAMES.policyVersion);
   const signedBodyHash = h(RUNTIME_HEADER_NAMES.bodyHash);
-  if (!kid || !requestId || !timestampRaw || !signedProductId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
+  if (!kid || !requestId || !timestampRaw || !signedBusinessId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
     throw new FartherShoreError(
       "malformed_signature",
       "request is missing one or more required x-fs-* headers"
@@ -1746,10 +1747,10 @@ async function verifyRequest(input, deps) {
       "recomputed body hash does not match the signed x-fs-body-hash"
     );
   }
-  if (deps.productId !== void 0 && signedProductId !== deps.productId) {
+  if (deps.businessId !== void 0 && signedBusinessId !== deps.businessId) {
     throw new FartherShoreError(
       "route_mismatch",
-      "signed product-id does not match this backend's product"
+      "signed business-id does not match this backend's business"
     );
   }
   if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
@@ -1771,7 +1772,7 @@ async function verifyRequest(input, deps) {
     bodyHash: computedBodyHash,
     requestId,
     timestamp,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion
@@ -1811,10 +1812,10 @@ async function verifyRequest(input, deps) {
       if (signedContext === null && deps.contextVerification === "required") {
         throw contextRequiredError("failed verification");
       }
-      if (signedContext && signedContext.productId !== signedProductId) {
+      if (signedContext && signedContext.productId !== signedBusinessId) {
         throw new FartherShoreError(
           "context_unverified",
-          "X-Fs-Context was minted for a different product than the signed request"
+          "X-Fs-Context was minted for a different business than the signed request"
         );
       }
     } else if (deps.contextVerification === "required") {
@@ -1834,7 +1835,7 @@ async function verifyRequest(input, deps) {
   }
   return {
     requestId,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion,
@@ -1877,8 +1878,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.14.0".length > 0 ? "0.14.0" : "0.0.0-dev";
-var CONTRACTS_FP = "1feb5a4a80b447ad".length > 0 ? "1feb5a4a80b447ad" : "0000000000000000";
+var SDK_VERSION = "0.15.0".length > 0 ? "0.15.0" : "0.0.0-dev";
+var CONTRACTS_FP = "4b6a36b4cb1f0b68".length > 0 ? "4b6a36b4cb1f0b68" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1947,7 +1948,7 @@ var FartherShore = class {
     if (!this.meteringClient && config.metering.enabled) {
       this.meteringClient = new MeteringClient({
         config: config.metering,
-        productId: config.product.id,
+        businessId: config.business.id,
         backendId: config.backend.id,
         coreUrl: this.coreUrl,
         fetchImpl: this.fetchImpl
@@ -2031,7 +2032,7 @@ var FartherShore = class {
     const context = await verifyRequest(input, {
       jwks: this.jwks,
       nonceCache: this.nonceCache,
-      productId: config.product.id,
+      businessId: config.business.id,
       backendId: config.backend.id,
       knownRouteIds,
       clockSkewSeconds: config.verification.clockSkewSeconds,
@@ -2261,7 +2262,7 @@ async function makeSignedRequest(spec = {}) {
     bodyHash,
     requestId: spec.requestId ?? `req_${cryptoRandom()}`,
     timestamp: spec.timestamp ?? Math.floor(Date.now() / 1e3),
-    productId: spec.productId ?? "prod_test",
+    businessId: spec.businessId ?? "biz_test",
     backendId: spec.backendId ?? "be_test",
     routeId: spec.routeId ?? "route_test",
     policyVersion: spec.policyVersion ?? "pv_1"
@@ -2273,7 +2274,7 @@ async function makeSignedRequest(spec = {}) {
     [RUNTIME_HEADER_NAMES.keyId]: kid,
     [RUNTIME_HEADER_NAMES.requestId]: claim.requestId,
     [RUNTIME_HEADER_NAMES.timestamp]: String(claim.timestamp),
-    [RUNTIME_HEADER_NAMES.productId]: claim.productId,
+    [RUNTIME_HEADER_NAMES.businessId]: claim.businessId,
     [RUNTIME_HEADER_NAMES.backendId]: claim.backendId,
     [RUNTIME_HEADER_NAMES.routeId]: claim.routeId,
     [RUNTIME_HEADER_NAMES.policyVersion]: claim.policyVersion,
@@ -2374,13 +2375,13 @@ function mergeHeaders(initHeaders, signedHeaders) {
   }
   return headers;
 }
-function buildContextClaim(persona, productId) {
+function buildContextClaim(persona, businessId) {
   return {
     orgId: persona.orgId ?? "org_dev",
     actor: persona.actor ?? { type: "user", id: `user_${persona.name}` },
-    // Product binding: the signed context productId MUST equal the signed
-    // request productId or verifyRequest rejects it as tamper evidence.
-    productId,
+    // Business binding: the retained signed-context productId claim MUST equal
+    // the signed request businessId or verifyRequest rejects it as tamper evidence.
+    productId: businessId,
     compiledPlanId: persona.compiledPlanId ?? "plan_dev",
     subscriptionId: persona.subscriptionId ?? "sub_dev",
     subscriberId: persona.subscriberId ?? "subscriber_dev",
@@ -2408,7 +2409,7 @@ function createPersonaClient(ctx) {
       query: spec.query ?? "",
       body: spec.body ?? null,
       streamingExempt: spec.streamingExempt ?? false,
-      productId: ctx.productId,
+      businessId: ctx.businessId,
       backendId: ctx.backendId,
       routeId: spec.routeId ?? "",
       privateJwk: ctx.keys.privateJwk,
@@ -2418,7 +2419,7 @@ function createPersonaClient(ctx) {
     });
     const headers = { ...signed.headers };
     if (!persona.anonymous) {
-      const claim = buildContextClaim(persona, ctx.productId);
+      const claim = buildContextClaim(persona, ctx.businessId);
       headers["x-fs-context"] = await signContextToken(
         claim,
         ctx.contextSecret,
@@ -2491,12 +2492,12 @@ var DEV_CORE_URL = "https://dev-gateway.farthershore.local";
 var DEV_JWKS_URL = `${DEV_CORE_URL}/.well-known/jwks.json`;
 var DEV_METERING_ENDPOINT = `${DEV_CORE_URL}/v1/metering/events`;
 function createDevGateway(options) {
-  const productId = options.productId ?? "prod_dev";
+  const businessId = options.businessId ?? "biz_dev";
   const backendId = options.backendId ?? "be_dev";
   const meterEvents = [];
   const reportUsageEvents = [];
   const bootstrap = {
-    product: { id: productId, slug: options.productSlug ?? "dev-product" },
+    business: { id: businessId, slug: options.businessSlug ?? "dev-business" },
     backend: {
       id: backendId,
       slug: options.backendSlug ?? "dev-backend",
@@ -2566,7 +2567,7 @@ function createDevGateway(options) {
     bootstrap,
     meterEvents,
     reportUsageEvents,
-    productId,
+    businessId,
     backendId,
     jwksUrl: DEV_JWKS_URL
   };
@@ -2768,7 +2769,7 @@ function createDevRuntime(options) {
   const gateway = createDevGateway({
     mode,
     keys,
-    ...options.productId ? { productId: options.productId } : {},
+    ...options.businessId ? { businessId: options.businessId } : {},
     ...options.backendId ? { backendId: options.backendId } : {},
     ...options.routes ? { routeIds: options.routes } : {},
     onMeterEvent: (event) => {
@@ -2797,7 +2798,7 @@ function createDevRuntime(options) {
   const personas = buildPersonaMap(options.personas);
   const personaClient = createPersonaClient({
     keys,
-    productId: gateway.productId,
+    businessId: gateway.businessId,
     backendId: gateway.backendId,
     contextSecret: keys.contextSecret,
     contextKid: keys.contextKid,
@@ -2927,7 +2928,7 @@ function createDevRuntimeFromEnv(env = readProcessEnv3()) {
     version: 1,
     mode,
     keys,
-    productId: runtime.gateway.productId,
+    businessId: runtime.gateway.businessId,
     backendId: runtime.gateway.backendId,
     personas: mapToRecord(runtime.personas)
   };
@@ -2940,7 +2941,7 @@ function printBanner(mode, runtime, tracePath) {
     "============================================================",
     "  \u26A0  FARTHER SHORE DEV MODE ACTIVE \u2014 NOT FOR PRODUCTION",
     `     mode:      ${mode.toUpperCase()}`,
-    `     product:   ${runtime.gateway.productId}`,
+    `     business:  ${runtime.gateway.businessId}`,
     `     backend:   ${runtime.gateway.backendId}`,
     `     personas:  ${[...runtime.personas.keys()].join(", ")}`,
     `     usage log: ${USAGE_JSONL_PATH}`,

package/dist/testing/index.js

@@ -294,7 +294,7 @@ var RUNTIME_HEADER_NAMES = {
   keyId: "x-fs-key-id",
   requestId: "x-fs-request-id",
   timestamp: "x-fs-timestamp",
-  productId: "x-fs-product-id",
+  businessId: "x-fs-business-id",
   backendId: "x-fs-backend-id",
   routeId: "x-fs-route-id",
   policyVersion: "x-fs-policy-version",
@@ -346,7 +346,7 @@ var CANONICAL_SIGNING_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
   "policy-version"
@@ -383,7 +383,7 @@ function buildCanonicalSigningString(input) {
     "body-hash": input.bodyHash,
     "request-id": input.requestId,
     timestamp: String(input.timestamp),
-    "product-id": input.productId,
+    "business-id": input.businessId,
     "backend-id": input.backendId,
     "route-id": input.routeId,
     "policy-version": input.policyVersion
@@ -608,7 +608,7 @@ async function makeSignedRequest(spec = {}) {
     bodyHash,
     requestId: spec.requestId ?? `req_${cryptoRandom()}`,
     timestamp: spec.timestamp ?? Math.floor(Date.now() / 1e3),
-    productId: spec.productId ?? "prod_test",
+    businessId: spec.businessId ?? "biz_test",
     backendId: spec.backendId ?? "be_test",
     routeId: spec.routeId ?? "route_test",
     policyVersion: spec.policyVersion ?? "pv_1"
@@ -620,7 +620,7 @@ async function makeSignedRequest(spec = {}) {
     [RUNTIME_HEADER_NAMES.keyId]: kid,
     [RUNTIME_HEADER_NAMES.requestId]: claim.requestId,
     [RUNTIME_HEADER_NAMES.timestamp]: String(claim.timestamp),
-    [RUNTIME_HEADER_NAMES.productId]: claim.productId,
+    [RUNTIME_HEADER_NAMES.businessId]: claim.businessId,
     [RUNTIME_HEADER_NAMES.backendId]: claim.backendId,
     [RUNTIME_HEADER_NAMES.routeId]: claim.routeId,
     [RUNTIME_HEADER_NAMES.policyVersion]: claim.policyVersion,
@@ -742,13 +742,13 @@ function mergeHeaders(initHeaders, signedHeaders) {
   }
   return headers;
 }
-function buildContextClaim(persona, productId) {
+function buildContextClaim(persona, businessId) {
   return {
     orgId: persona.orgId ?? "org_dev",
     actor: persona.actor ?? { type: "user", id: `user_${persona.name}` },
-    // Product binding: the signed context productId MUST equal the signed
-    // request productId or verifyRequest rejects it as tamper evidence.
-    productId,
+    // Business binding: the retained signed-context productId claim MUST equal
+    // the signed request businessId or verifyRequest rejects it as tamper evidence.
+    productId: businessId,
     compiledPlanId: persona.compiledPlanId ?? "plan_dev",
     subscriptionId: persona.subscriptionId ?? "sub_dev",
     subscriberId: persona.subscriberId ?? "subscriber_dev",
@@ -776,7 +776,7 @@ function createPersonaClient(ctx) {
       query: spec.query ?? "",
       body: spec.body ?? null,
       streamingExempt: spec.streamingExempt ?? false,
-      productId: ctx.productId,
+      businessId: ctx.businessId,
       backendId: ctx.backendId,
       routeId: spec.routeId ?? "",
       privateJwk: ctx.keys.privateJwk,
@@ -786,7 +786,7 @@ function createPersonaClient(ctx) {
     });
     const headers = { ...signed.headers };
     if (!persona.anonymous) {
-      const claim = buildContextClaim(persona, ctx.productId);
+      const claim = buildContextClaim(persona, ctx.businessId);
       headers["x-fs-context"] = await signContextToken(
         claim,
         ctx.contextSecret,
@@ -861,12 +861,12 @@ var DEV_CORE_URL = "https://dev-gateway.farthershore.local";
 var DEV_JWKS_URL = `${DEV_CORE_URL}/.well-known/jwks.json`;
 var DEV_METERING_ENDPOINT = `${DEV_CORE_URL}/v1/metering/events`;
 function createDevGateway(options) {
-  const productId = options.productId ?? "prod_dev";
+  const businessId = options.businessId ?? "biz_dev";
   const backendId = options.backendId ?? "be_dev";
   const meterEvents = [];
   const reportUsageEvents = [];
   const bootstrap = {
-    product: { id: productId, slug: options.productSlug ?? "dev-product" },
+    business: { id: businessId, slug: options.businessSlug ?? "dev-business" },
     backend: {
       id: backendId,
       slug: options.backendSlug ?? "dev-backend",
@@ -936,7 +936,7 @@ function createDevGateway(options) {
     bootstrap,
     meterEvents,
     reportUsageEvents,
-    productId,
+    businessId,
     backendId,
     jwksUrl: DEV_JWKS_URL
   };
@@ -1136,7 +1136,7 @@ var DEFAULT_MAX_RETRIES = 3;
 var MeteringClient = class {
   config;
   endpoint;
-  productId;
+  businessId;
   backendId;
   fetchImpl;
   maxRetries;
@@ -1150,7 +1150,7 @@ var MeteringClient = class {
   constructor(options) {
     this.config = options.config;
     this.endpoint = resolveEndpoint(options.config.endpoint, options.coreUrl);
-    this.productId = options.productId;
+    this.businessId = options.businessId;
     this.backendId = options.backendId;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -1213,13 +1213,14 @@ var MeteringClient = class {
     }
     const event = {
       event_id: options.eventId ?? this.newId(),
-      product_id: this.productId,
+      business_id: this.businessId,
       backend_id: this.backendId,
       meter,
       qty,
       timestamp: options.timestamp ?? this.now().toISOString(),
       ...options.routeId ? { route_id: options.routeId } : {},
-      ...options.requestId ? { request_id: options.requestId } : {}
+      ...options.requestId ? { request_id: options.requestId } : {},
+      ...options.subscriptionId ? { subscription_id: options.subscriptionId } : {}
     };
     this.buffer.push(event);
     await this.flush();
@@ -1926,12 +1927,12 @@ async function verifyRequest(input, deps) {
   const kid = h(RUNTIME_HEADER_NAMES.keyId);
   const requestId = h(RUNTIME_HEADER_NAMES.requestId);
   const timestampRaw = h(RUNTIME_HEADER_NAMES.timestamp);
-  const signedProductId = h(RUNTIME_HEADER_NAMES.productId);
+  const signedBusinessId = h(RUNTIME_HEADER_NAMES.businessId);
   const signedBackendId = h(RUNTIME_HEADER_NAMES.backendId);
   const signedRouteId = h(RUNTIME_HEADER_NAMES.routeId) ?? "";
   const policyVersion = h(RUNTIME_HEADER_NAMES.policyVersion);
   const signedBodyHash = h(RUNTIME_HEADER_NAMES.bodyHash);
-  if (!kid || !requestId || !timestampRaw || !signedProductId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
+  if (!kid || !requestId || !timestampRaw || !signedBusinessId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
     throw new FartherShoreError(
       "malformed_signature",
       "request is missing one or more required x-fs-* headers"
@@ -1967,10 +1968,10 @@ async function verifyRequest(input, deps) {
       "recomputed body hash does not match the signed x-fs-body-hash"
     );
   }
-  if (deps.productId !== void 0 && signedProductId !== deps.productId) {
+  if (deps.businessId !== void 0 && signedBusinessId !== deps.businessId) {
     throw new FartherShoreError(
       "route_mismatch",
-      "signed product-id does not match this backend's product"
+      "signed business-id does not match this backend's business"
     );
   }
   if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
@@ -1992,7 +1993,7 @@ async function verifyRequest(input, deps) {
     bodyHash: computedBodyHash,
     requestId,
     timestamp,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion
@@ -2032,10 +2033,10 @@ async function verifyRequest(input, deps) {
       if (signedContext === null && deps.contextVerification === "required") {
         throw contextRequiredError("failed verification");
       }
-      if (signedContext && signedContext.productId !== signedProductId) {
+      if (signedContext && signedContext.productId !== signedBusinessId) {
         throw new FartherShoreError(
           "context_unverified",
-          "X-Fs-Context was minted for a different product than the signed request"
+          "X-Fs-Context was minted for a different business than the signed request"
         );
       }
     } else if (deps.contextVerification === "required") {
@@ -2055,7 +2056,7 @@ async function verifyRequest(input, deps) {
   }
   return {
     requestId,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion,
@@ -2098,8 +2099,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.14.0".length > 0 ? "0.14.0" : "0.0.0-dev";
-var CONTRACTS_FP = "1feb5a4a80b447ad".length > 0 ? "1feb5a4a80b447ad" : "0000000000000000";
+var SDK_VERSION = "0.15.0".length > 0 ? "0.15.0" : "0.0.0-dev";
+var CONTRACTS_FP = "4b6a36b4cb1f0b68".length > 0 ? "4b6a36b4cb1f0b68" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2168,7 +2169,7 @@ var FartherShore = class {
     if (!this.meteringClient && config.metering.enabled) {
       this.meteringClient = new MeteringClient({
         config: config.metering,
-        productId: config.product.id,
+        businessId: config.business.id,
         backendId: config.backend.id,
         coreUrl: this.coreUrl,
         fetchImpl: this.fetchImpl
@@ -2252,7 +2253,7 @@ var FartherShore = class {
     const context = await verifyRequest(input, {
       jwks: this.jwks,
       nonceCache: this.nonceCache,
-      productId: config.product.id,
+      businessId: config.business.id,
       backendId: config.backend.id,
       knownRouteIds,
       clockSkewSeconds: config.verification.clockSkewSeconds,
@@ -2623,7 +2624,7 @@ function personaClientFromKeysFile(path = DEFAULT_KEYS_FILE, options = {}) {
   const file = readDevKeysFile(path);
   const client = createPersonaClient({
     keys: file.keys,
-    productId: file.productId,
+    businessId: file.businessId,
     backendId: file.backendId,
     contextSecret: file.keys.contextSecret,
     contextKid: file.keys.contextKid,
@@ -2650,7 +2651,7 @@ function createDevRuntime(options) {
   const gateway = createDevGateway({
     mode,
     keys,
-    ...options.productId ? { productId: options.productId } : {},
+    ...options.businessId ? { businessId: options.businessId } : {},
     ...options.backendId ? { backendId: options.backendId } : {},
     ...options.routes ? { routeIds: options.routes } : {},
     onMeterEvent: (event) => {
@@ -2679,7 +2680,7 @@ function createDevRuntime(options) {
   const personas = buildPersonaMap(options.personas);
   const personaClient = createPersonaClient({
     keys,
-    productId: gateway.productId,
+    businessId: gateway.businessId,
     backendId: gateway.backendId,
     contextSecret: keys.contextSecret,
     contextKid: keys.contextKid,
@@ -2809,7 +2810,7 @@ function createDevRuntimeFromEnv(env = readProcessEnv3()) {
     version: 1,
     mode,
     keys,
-    productId: runtime.gateway.productId,
+    businessId: runtime.gateway.businessId,
     backendId: runtime.gateway.backendId,
     personas: mapToRecord(runtime.personas)
   };
@@ -2822,7 +2823,7 @@ function printBanner(mode, runtime, tracePath) {
     "============================================================",
     "  \u26A0  FARTHER SHORE DEV MODE ACTIVE \u2014 NOT FOR PRODUCTION",
     `     mode:      ${mode.toUpperCase()}`,
-    `     product:   ${runtime.gateway.productId}`,
+    `     business:  ${runtime.gateway.businessId}`,
     `     backend:   ${runtime.gateway.backendId}`,
     `     personas:  ${[...runtime.personas.keys()].join(", ")}`,
     `     usage log: ${USAGE_JSONL_PATH}`,

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

@@ -2,6 +2,12 @@ import type { RuntimeMeteringConfig } from "../runtime-types.js";
 export type MeterOptions = {
     requestId?: string;
     routeId?: string;
+    /** Subscription to attribute the usage to (billing identity). Pass the
+     *  verified request context's `signedContext.subscriptionId` when metering
+     *  inside a request handler. Without it (and without `requestId`, which core
+     *  can resolve back to the served gateway request), core persists the event
+     *  UNBILLED and flags it unattributable. */
+    subscriptionId?: string;
     /** Override event_id (idempotency key). Defaults to a random uuid. */
     eventId?: string;
     /** Override the timestamp (ISO-8601). Defaults to now. */
@@ -9,7 +15,7 @@ export type MeterOptions = {
 };
 export type MeteringClientOptions = {
     config: RuntimeMeteringConfig;
-    productId: string;
+    businessId: string;
     backendId: string;
     /** Core base URL when the config endpoint is a relative path. */
     coreUrl?: string;
@@ -36,7 +42,7 @@ export type MeteringClientOptions = {
 export declare class MeteringClient {
     private readonly config;
     private readonly endpoint;
-    private readonly productId;
+    private readonly businessId;
     private readonly backendId;
     private readonly fetchImpl;
     private readonly maxRetries;

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

@@ -45,7 +45,7 @@ export type FartherShoreInitOptions = {
      * `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 product's `contextTokenSecret`, which signs `fsc_` INGRESS tokens
+     * 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
@@ -54,8 +54,8 @@ export type FartherShoreInitOptions = {
      *
      * 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-product context
-     * forgery). The distribution mechanism — per-product derived keys or an
+     * 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

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

@@ -23,7 +23,7 @@ export type HeadersLike = Headers | Record<string, string | string[] | undefined
 /** The verified request context attached to req.fartherShore. */
 export type FartherShoreRequestContext = {
     requestId: string;
-    productId: string;
+    businessId: string;
     backendId: string;
     routeId: string;
     policyVersion: string;
@@ -55,8 +55,8 @@ export type FartherShoreRequestContext = {
 export type VerifyRequestDeps = {
     jwks: JwksClient;
     nonceCache: NonceCache;
-    /** Expected product id (from bootstrap). When set, must match the signed claim. */
-    productId?: string;
+    /** Expected business id (from bootstrap). When set, must match the signed claim. */
+    businessId?: string;
     /** Expected backend id (from bootstrap). When set, must match. */
     backendId?: string;
     /**

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

@@ -73,7 +73,7 @@ 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", "product-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"];
         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 '/'.";
@@ -81,7 +81,7 @@ export declare const RUNTIME_SIGNING_CONTRACT: {
             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.";
-            readonly "product-id": "Product id the request is routed to.";
+            readonly "business-id": "Business id the request is routed to.";
             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.";
@@ -92,7 +92,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", "product-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"];
 export declare const RUNTIME_BODY_HASH_CONTRACT: {
     readonly algorithm: "SHA-256";
     readonly encoding: "hex-lower";
@@ -108,7 +108,7 @@ export declare const RUNTIME_HEADERS: {
     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";
@@ -145,7 +145,7 @@ export declare const RUNTIME_METERING_CONTRACT: {
     readonly credential: "reusable-bearer";
     readonly event: {
         readonly event_id: "string";
-        readonly product_id: "string";
+        readonly business_id: "string";
         readonly backend_id: "string";
         readonly route_id: "string?";
         readonly request_id: "string?";

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

@@ -126,7 +126,7 @@ 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";
@@ -166,7 +166,7 @@ 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;
@@ -221,7 +221,7 @@ export type RuntimeLockDescriptor = {
     lockVersion: number;
 };
 export type RuntimeBootstrapResponse = {
-    product: {
+    business: {
         id: string;
         slug: string;
     };
@@ -247,10 +247,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

@@ -24,7 +24,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.14.0",
+  "version": "0.15.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",
@@ -37,8 +37,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-linux-arm64": "0.0.0",
     "@farthershore/cloudflared-darwin-x64": "0.0.0"
   },
   "peerDependencies": {