@farthershore/backend 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to the runtime backend SDK are documented here. This SDK
 versions independently from the frontend and business SDKs. Pre-1.0: minor
 versions may include breaking changes.
 
+## [0.19.0]
+
+### Added
+
+- One runtime token can now serve EVERY environment of a business. Bootstrap
+  reports `backendIds` — every backend the token may serve — and the SDK checks
+  the gateway's signed backend id for MEMBERSHIP of that set instead of equality
+  with a single id.
+
+  A process holds exactly one `FS_RUNTIME_TOKEN`, so an environment-scoped token
+  forced a SEPARATE deployment per environment: pointing a backend at a preview
+  environment meant repointing, and breaking, production. A business-scoped
+  token (`farthershore backend tokens create <biz>`, no `--env`) now serves them
+  all from one deployment; `--env <name>` still pins a token to one environment
+  when you want that guarantee.
+
+  Still fail-closed and still bounded by the business — this widens across
+  ENVIRONMENTS, never across businesses. Additive: an older core omits
+  `backendIds` and the single-id equality check still applies.
+
 ## [0.18.0]
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ graceful lifecycle (health + shutdown). Everything else — your business, backe
 and environment ids, the verification keys, and the metering endpoint — is
 fetched automatically from the token at startup.
 
-> **Status: `0.18.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.19.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.
 

package/dist/index.js

@@ -1781,7 +1781,14 @@ async function verifyRequest(input, deps) {
       "signed business-id does not match this backend's business"
     );
   }
-  if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
+  if (deps.backendIds !== void 0 && deps.backendIds.size > 0) {
+    if (!deps.backendIds.has(signedBackendId)) {
+      throw new FartherShoreError(
+        "route_mismatch",
+        "signed backend-id is not one this deployment serves"
+      );
+    }
+  } else if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
     throw new FartherShoreError(
       "route_mismatch",
       "signed backend-id does not match this backend"
@@ -1918,7 +1925,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.18.0".length > 0 ? "0.18.0" : "0.0.0-dev";
+var SDK_VERSION = "0.19.0".length > 0 ? "0.19.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2066,11 +2073,13 @@ var FartherShore = class {
       );
     }
     const knownRouteIds = new Set(config.routes.map((r) => r.id));
+    const backendIds = config.backendIds?.length ? new Set(config.backendIds) : void 0;
     const context = await verifyRequest(input, {
       jwks: this.jwks,
       nonceCache: this.nonceCache,
       businessId: config.business.id,
       backendId: config.backend.id,
+      ...backendIds ? { backendIds } : {},
       knownRouteIds,
       clockSkewSeconds: config.verification.clockSkewSeconds,
       replayWindowSeconds: config.verification.replayWindowSeconds,

package/dist/testing/index.js

@@ -2012,7 +2012,14 @@ async function verifyRequest(input, deps) {
       "signed business-id does not match this backend's business"
     );
   }
-  if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
+  if (deps.backendIds !== void 0 && deps.backendIds.size > 0) {
+    if (!deps.backendIds.has(signedBackendId)) {
+      throw new FartherShoreError(
+        "route_mismatch",
+        "signed backend-id is not one this deployment serves"
+      );
+    }
+  } else if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
     throw new FartherShoreError(
       "route_mismatch",
       "signed backend-id does not match this backend"
@@ -2149,7 +2156,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.18.0".length > 0 ? "0.18.0" : "0.0.0-dev";
+var SDK_VERSION = "0.19.0".length > 0 ? "0.19.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2297,11 +2304,13 @@ var FartherShore = class {
       );
     }
     const knownRouteIds = new Set(config.routes.map((r) => r.id));
+    const backendIds = config.backendIds?.length ? new Set(config.backendIds) : void 0;
     const context = await verifyRequest(input, {
       jwks: this.jwks,
       nonceCache: this.nonceCache,
       businessId: config.business.id,
       backendId: config.backend.id,
+      ...backendIds ? { backendIds } : {},
       knownRouteIds,
       clockSkewSeconds: config.verification.clockSkewSeconds,
       replayWindowSeconds: config.verification.replayWindowSeconds,

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

@@ -68,8 +68,21 @@ export type VerifyRequestDeps = {
     nonceCache: NonceStore;
     /** Expected business id (from bootstrap). When set, must match the signed claim. */
     businessId?: string;
-    /** Expected backend id (from bootstrap). When set, must match. */
+    /** Expected backend id (from bootstrap). When set, must match — unless
+     *  `backendIds` is provided, which supersedes it with a membership check. */
     backendId?: string;
+    /**
+     * Every backend id this deployment may serve (from bootstrap), across all of
+     * the business's environments. When provided, the signed backend id must be a
+     * MEMBER of this set — superseding the single-id equality check above.
+     *
+     * A process holds exactly one `FS_RUNTIME_TOKEN`, so pinning to one backend id
+     * forced a separate deployment per environment: serving a preview env meant
+     * repointing (and breaking) production. A business-scoped token serves them
+     * all from one deployment. Still fail-closed, still bound to this business —
+     * just no longer bound to a single environment.
+     */
+    backendIds?: ReadonlySet<string>;
     /**
      * Set of route ids this backend serves (from bootstrap). When provided AND
      * the signed route-id is non-empty, the signed route must be a member —

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

@@ -233,6 +233,21 @@ export type RuntimeBootstrapResponse = {
         slug: string;
         name: string;
     };
+    /**
+     * Every backend id this token may serve, across ALL of the business's
+     * environments — `backend.id` is always a member.
+     *
+     * One deployment holds exactly one `FS_RUNTIME_TOKEN`, so an
+     * environment-scoped token forced a SEPARATE deployment per environment:
+     * serving a preview env meant repointing (and breaking) production. A
+     * business-scoped token serves every environment from one deployment, and the
+     * SDK checks the gateway's signed backend id for MEMBERSHIP of this set
+     * rather than equality with a single id.
+     *
+     * Optional and additive: an older core omits it and the SDK falls back to the
+     * single-id equality check.
+     */
+    backendIds?: string[];
     environment: {
         id: string | null;
         kind: RuntimeEnvironmentKind;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.18.0",
+  "version": "0.19.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 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@farthershore/cloudflared-linux-x64": "0.0.0",
     "@farthershore/cloudflared-linux-arm64": "0.0.0",
+    "@farthershore/cloudflared-linux-x64": "0.0.0",
     "@farthershore/cloudflared-darwin-arm64": "0.0.0",
     "@farthershore/cloudflared-darwin-x64": "0.0.0"
   },