@farthershore/backend 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.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.18.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

@@ -1918,7 +1918,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.18.0".length > 0 ? "0.18.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2276,15 +2276,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

@@ -2149,7 +2149,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.18.0".length > 0 ? "0.18.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2502,15 +2502,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.17.0",
+  "version": "0.18.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",
@@ -39,8 +39,8 @@
   "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-darwin-arm64": "0.0.0",
+    "@farthershore/cloudflared-darwin-x64": "0.0.0"
   },
   "peerDependencies": {
     "express": "^4.0.0 || ^5.0.0"