@farthershore/backend 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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
+
+- `createExpressMiddleware` accepts `onVerificationError`, called when
+  verification REJECTS a request with the diagnostic detail the response body
+  deliberately withholds (`{ code, message, status, method, path }`).
+
+  The wire body stays `{ error: <code> }` — several distinct causes share one
+  code (`route_mismatch` covers a business mismatch, a backend mismatch, AND an
+  unserved route id) and the specifics must not leak to an unauthenticated
+  caller. Previously they were discarded entirely, leaving the operator no way
+  to tell which cause fired even in their own logs. Defaults to a one-line
+  `console.warn`; pass a function to route it into a structured logger, or
+  `() => {}` to silence it. A throwing reporter cannot turn a 401 into a 500.
+
 ## [0.17.0]
 
 ### Changed — BREAKING

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.17.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/adapters/express.js

@@ -85,15 +85,27 @@ async function runMiddleware(fs, options, req, res, next) {
     stripFartherShoreHeaders(req);
     next();
   } catch (error) {
-    fail(res, error);
+    fail(res, error, options, req);
   }
 }
-function fail(res, error) {
-  if (error instanceof FartherShoreError) {
-    res.status(error.status).json({ error: error.code });
-    return;
+function fail(res, error, options, req) {
+  const code = error instanceof FartherShoreError ? error.code : "bad_signature";
+  const status = error instanceof FartherShoreError ? error.status : 401;
+  const message = error instanceof Error && error.message ? error.message : code;
+  const report = options.onVerificationError ?? ((d) => {
+    console.warn(`[farthershore] request rejected (${d.code}): ${d.message}`);
+  });
+  try {
+    report({
+      code,
+      message,
+      status,
+      method: req.method ?? "",
+      path: req.url ?? ""
+    });
+  } catch {
   }
-  res.status(401).json({ error: "bad_signature" });
+  res.status(status).json({ error: code });
 }
 function stripFartherShoreHeaders(req) {
   const headers = req.headers;

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.17.0".length > 0 ? "0.17.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,
@@ -2276,15 +2285,27 @@ async function runMiddleware(fs, options, req, res, next) {
     stripFartherShoreHeaders(req);
     next();
   } catch (error) {
-    fail(res, error);
+    fail(res, error, options, req);
   }
 }
-function fail(res, error) {
-  if (error instanceof FartherShoreError) {
-    res.status(error.status).json({ error: error.code });
-    return;
+function fail(res, error, options, req) {
+  const code = error instanceof FartherShoreError ? error.code : "bad_signature";
+  const status = error instanceof FartherShoreError ? error.status : 401;
+  const message = error instanceof Error && error.message ? error.message : code;
+  const report = options.onVerificationError ?? ((d) => {
+    console.warn(`[farthershore] request rejected (${d.code}): ${d.message}`);
+  });
+  try {
+    report({
+      code,
+      message,
+      status,
+      method: req.method ?? "",
+      path: req.url ?? ""
+    });
+  } catch {
   }
-  res.status(401).json({ error: "bad_signature" });
+  res.status(status).json({ error: code });
 }
 function stripFartherShoreHeaders(req) {
   const headers = req.headers;

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.17.0".length > 0 ? "0.17.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,
@@ -2502,15 +2511,27 @@ async function runMiddleware(fs, options, req, res, next) {
     stripFartherShoreHeaders(req);
     next();
   } catch (error) {
-    fail(res, error);
+    fail(res, error, options, req);
   }
 }
-function fail(res, error) {
-  if (error instanceof FartherShoreError) {
-    res.status(error.status).json({ error: error.code });
-    return;
+function fail(res, error, options, req) {
+  const code = error instanceof FartherShoreError ? error.code : "bad_signature";
+  const status = error instanceof FartherShoreError ? error.status : 401;
+  const message = error instanceof Error && error.message ? error.message : code;
+  const report = options.onVerificationError ?? ((d) => {
+    console.warn(`[farthershore] request rejected (${d.code}): ${d.message}`);
+  });
+  try {
+    report({
+      code,
+      message,
+      status,
+      method: req.method ?? "",
+      path: req.url ?? ""
+    });
+  } catch {
   }
-  res.status(401).json({ error: "bad_signature" });
+  res.status(status).json({ error: code });
 }
 function stripFartherShoreHeaders(req) {
   const headers = req.headers;

package/dist/types/adapters/express.d.ts

@@ -36,6 +36,27 @@ export type MiddlewareOptions = {
      * consumes no identity; the secure default is strict.
      */
     always?: boolean;
+    /**
+     * Called when verification REJECTS a request, with the diagnostic detail that
+     * is deliberately withheld from the response body.
+     *
+     * The wire response is only `{ error: <code> }` — several distinct causes
+     * share one code (`route_mismatch` covers a business mismatch, a backend
+     * mismatch, AND an unserved route id), and the specifics must not leak to an
+     * unauthenticated caller. But discarding them entirely leaves the operator
+     * with no way to tell which cause fired, in their OWN logs, for their OWN
+     * server. That is what this hook restores.
+     *
+     * Defaults to a one-line `console.warn`. Pass a function to route it into a
+     * structured logger, or `() => {}` to silence it.
+     */
+    onVerificationError?: (detail: {
+        code: string;
+        message: string;
+        status: number;
+        method: string;
+        path: string;
+    }) => void;
 };
 /**
  * A verified request context whose {@link ConsumerPrincipal} is GUARANTEED

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.17.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,10 +37,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@farthershore/cloudflared-linux-x64": "0.0.0",
     "@farthershore/cloudflared-linux-arm64": "0.0.0",
-    "@farthershore/cloudflared-darwin-x64": "0.0.0",
-    "@farthershore/cloudflared-darwin-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"
   },
   "peerDependencies": {
     "express": "^4.0.0 || ^5.0.0"