@farthershore/backend 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog — @farthershore/backend
+
+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.16.0]
+
+Consumer-principal runtime. Every verified request now carries a typed
+principal, request verification binds the signed context into the signature, and
+the verified context is the **single, guaranteed, non-optional** source of
+identity — verification is strict by default and inbound `x-fs-*` headers are
+stripped before a handler runs.
+
+### Breaking
+
+- The Ed25519 request-signature canonical string now includes `context-hash`
+  (SHA-256 of the signed `X-Fs-Context`) as a bound field. The platform gateway
+  signs with it, so a backend on an older SDK verifies against the previous
+  canonical string and **rejects every request**. Upgrade this SDK in lockstep
+  with the platform deploy; a mismatch fails loud with a generic `bad_signature`
+  rejection (the recomputed canonical string no longer matches the signature),
+  not silently.
+- `verifyContext` accepts context-token version `cv: 2` only (RFC-9068/8693-style
+  `sub` / `client_id` / `act` claims); `cv: 1` tokens are rejected.
+- `verifyRequest` is fail-closed: the `contextVerification` option and the
+  unsigned `x-fs-permissions` / `x-fs-roles` header fallback are removed. A
+  presented `X-Fs-Context` that is malformed or not `cv: 2` is a `401`.
+- **`ctx.principal` is derived from the Ed25519-vouched context — no HS256
+  context secret required.** The `X-Fs-Context` token's SHA-256 is bound into the
+  verified request signature, so once the request signature checks out the token
+  content is gateway-vouched and the principal is produced regardless of whether
+  a context secret is configured (with request signing on by default, that means
+  every identity-bearing request resolves a principal). The `contextSecrets` /
+  `FS_CONTEXT_SECRETS` HS256 keyring is now **optional defense-in-depth**: when
+  configured, a presented token must ALSO pass HS256 or the request is a `401`;
+  when unset, the request-signature binding is sufficient. A request the gateway
+  signed with no context is a legitimate identity-less request (no principal),
+  not a rejection.
+- **`fs.middleware()` is STRICT BY DEFAULT.** The `always` option now defaults to
+  `true`: every request is verified fail-closed and its verified context becomes
+  a **guaranteed, non-optional** presence on `req.fartherShore`. The old
+  pre-keystone default (pass through until bootstrap requires verification) is
+  gone — pass `always: false` to explicitly defer to bootstrap's
+  `verification.required` flag (an advanced escape hatch for a backend that
+  consumes no identity).
+- **Identity is single-sourced from the verified context.** After verification,
+  the middleware **STRIPS every inbound `x-fs-*` header** from the request
+  (`req.headers` and `req.rawHeaders`) before the handler runs, so a spoofable
+  plaintext identity/metering header (e.g. a direct caller's `x-fs-org-id` /
+  `x-fs-actor-*` / `x-fs-permissions`) is physically unreadable by a handler —
+  the verified `req.fartherShore` context is the only identity that remains.
+
+### Added
+
+- `ctx.principal` — the verified consumer principal
+  (`{ org, subject: member | service }`) on every request context.
+- `requireMember(ctx)` / `requireService(ctx)` — narrow-or-throw helpers for
+  subject-gated handlers.
+- `fs.handler((ctx, req, res) => …)` / `createExpressHandler` — wrap a route
+  handler so it runs only with a GUARANTEED verified context: `ctx` is a
+  non-optional `FartherShoreRequestContext` (read `ctx.principal` /
+  `requireMember(ctx)` with no optional-chaining), else it fails closed with a
+  `401`. A thrown `FartherShoreError` / `FartherShorePermissionError` is mapped
+  to its typed status.
+- `MeteringOptions.requestId` — thread the verified `ctx.requestId` into
+  `withUsage()` / `createUsage()`. The inbound `x-fs-request-id` header is now
+  stripped, so pass the verified id explicitly for dev-mode usage association.

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

@@ -21,6 +21,19 @@ function statusForCode(code) {
   return code === "body_too_large" ? 413 : 401;
 }
 
+// src/core/permissions.ts
+var FartherShorePermissionError = class extends Error {
+  code = "permission_denied";
+  status = 403;
+  /** The permission key that was required but not held. */
+  requiredPermission;
+  constructor(requiredPermission, message) {
+    super(message ?? `missing required permission: ${requiredPermission}`);
+    this.name = "FartherShorePermissionError";
+    this.requiredPermission = requiredPermission;
+  }
+};
+
 // src/generated/runtime-contract.ts
 var RUNTIME_BODY_HASH_CONTRACT = {
   algorithm: "SHA-256",
@@ -48,7 +61,9 @@ function createExpressMiddleware(fs, options = {}) {
 }
 async function runMiddleware(fs, options, req, res, next) {
   try {
-    if (!options.always && !await fs.verificationRequired()) {
+    const strict = options.always ?? true;
+    if (!strict && !await fs.verificationRequired()) {
+      stripFartherShoreHeaders(req);
       next();
       return;
     }
@@ -65,6 +80,7 @@ async function runMiddleware(fs, options, req, res, next) {
       streamingExempt
     });
     req.fartherShore = ctx;
+    stripFartherShoreHeaders(req);
     next();
   } catch (error) {
     fail(res, error);
@@ -77,6 +93,51 @@ function fail(res, error) {
   }
   res.status(401).json({ error: "bad_signature" });
 }
+function stripFartherShoreHeaders(req) {
+  const headers = req.headers;
+  for (const name of Object.keys(headers)) {
+    if (name.toLowerCase().startsWith("x-fs-")) {
+      delete headers[name];
+    }
+  }
+  const withRaw = req;
+  const raw = withRaw.rawHeaders;
+  if (Array.isArray(raw)) {
+    const cleaned = [];
+    for (let i = 0; i < raw.length; i += 2) {
+      const key = raw[i];
+      const value = raw[i + 1];
+      if (typeof key !== "string" || value === void 0) continue;
+      if (key.toLowerCase().startsWith("x-fs-")) continue;
+      cleaned.push(key, value);
+    }
+    withRaw.rawHeaders = cleaned;
+  }
+}
+function createExpressHandler(handler) {
+  return (req, res, next) => {
+    const ctx = req.fartherShore;
+    if (!ctx) {
+      res.status(401).json({ error: "context_unverified" });
+      return;
+    }
+    if (!ctx.principal) {
+      res.status(401).json({ error: "principal_required" });
+      return;
+    }
+    const verified = ctx;
+    void Promise.resolve().then(
+      () => handler(verified, req, res, next)
+    ).catch((error) => failHandler(res, next, error));
+  };
+}
+function failHandler(res, next, error) {
+  if (error instanceof FartherShoreError || error instanceof FartherShorePermissionError) {
+    res.status(error.status).json({ error: error.code });
+    return;
+  }
+  next(error);
+}
 function splitUrl(req) {
   const raw = req.originalUrl ?? req.url ?? req.path ?? "/";
   const qIndex = raw.indexOf("?");
@@ -103,5 +164,6 @@ function headerValue(headers, name) {
   return value;
 }
 export {
+  createExpressHandler,
   createExpressMiddleware
 };

package/dist/generated/runtime-contract.js

@@ -83,22 +83,24 @@ var RUNTIME_SIGNING_CONTRACT = {
       "body-hash",
       "request-id",
       "timestamp",
-      "product-id",
+      "business-id",
       "backend-id",
       "route-id",
-      "policy-version"
+      "policy-version",
+      "context-hash"
     ],
     fieldRules: {
       method: "Uppercased HTTP method (e.g. GET, POST).",
       path: "Request path, percent-encoded as received, no host, no query string. Always begins with '/'.",
-      query: "Canonical query string: parse pairs, sort by (name, then value) using byte (code-unit) order, re-join name=value pairs with '&'. Names and values are NOT re-encoded (passed through as received). Empty string when there is no query.",
+      query: "The request's query string bytes VERBATIM, after the caller has stripped the URL's single leading '?' delimiter. Use the RAW wire query exactly as received \u2014 NO sorting, NO filtering, NO re-stripping a leading '?', NO dropping empty pairs, NO re-encoding. The signature binds to the exact query bytes: any reorder, added/removed/relocated pair, or re-encoding changes the bytes and MUST fail verification. Every SDK verifier MUST read the raw wire query (never a re-parsed/re-serialized form, which could reorder or re-encode and would then fail legitimate requests). Any normalization (sorting by name or value, dropping/moving empty pairs, re-stripping '?') is FORBIDDEN \u2014 each collapses distinct wire queries under one signature. Empty string when there is no query.",
       "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."
+      "policy-version": "Tenant artifact / policy version the gateway signed under.",
+      "context-hash": "Lowercase hex SHA-256 of the presented X-Fs-Context JWT string (identity-context binding). For a request with no signed context, the SHA-256 of the empty string (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Binds the identity context into the request signature so one verification covers both."
     }
   }
 };
@@ -109,10 +111,11 @@ var RUNTIME_CANONICAL_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
-  "policy-version"
+  "policy-version",
+  "context-hash"
 ];
 var RUNTIME_BODY_HASH_CONTRACT = {
   algorithm: "SHA-256",
@@ -133,7 +136,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",
@@ -161,7 +164,9 @@ var RUNTIME_ERROR_CODES = {
   environmentMismatch: "environment_mismatch",
   missingToken: "missing_token",
   invalidToken: "invalid_token",
-  contextUnverified: "context_unverified"
+  contextUnverified: "context_unverified",
+  memberSubjectRequired: "member_subject_required",
+  serviceSubjectRequired: "service_subject_required"
 };
 var RUNTIME_METERING_CONTRACT = {
   endpoint: "/v1/metering/events",
@@ -169,7 +174,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?",