@farthershore/backend 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# 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.17.0]
+
+### Changed — BREAKING
+
+- `RUNTIME_TOKEN_CAPABILITIES` is renamed `RUNTIME_TOKEN_OPERATIONS`, and the
+  type `RuntimeTokenCapability` is renamed `RuntimeTokenOperation`. The values
+  are operations, not capabilities, and the old names contradicted the runtime
+  contract they mirror. Update imports; no behaviour change.
+
+### Added
+
+- `credentialKind()` and `isPortalSession()` — route-surface credential-kind
+  derivation from the signed principal. No new claim is required; both are
+  derived from what the gateway already signs.
+
+## [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

@@ -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.15.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.17.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

@@ -18,9 +18,24 @@ var FartherShoreError = class extends Error {
   }
 };
 function statusForCode(code) {
-  return code === "body_too_large" ? 413 : 401;
+  if (code === "body_too_large") return 413;
+  if (code === "surface_not_allowed") return 403;
+  return 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 +63,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 +82,7 @@ async function runMiddleware(fs, options, req, res, next) {
       streamingExempt
     });
     req.fartherShore = ctx;
+    stripFartherShoreHeaders(req);
     next();
   } catch (error) {
     fail(res, error);
@@ -77,6 +95,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 +166,6 @@ function headerValue(headers, name) {
   return value;
 }
 export {
+  createExpressHandler,
   createExpressMiddleware
 };

package/dist/generated/runtime-contract.js

@@ -86,19 +86,21 @@ var RUNTIME_SIGNING_CONTRACT = {
       "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.",
       "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."
     }
   }
 };
@@ -112,7 +114,8 @@ var RUNTIME_CANONICAL_FIELDS = [
   "business-id",
   "backend-id",
   "route-id",
-  "policy-version"
+  "policy-version",
+  "context-hash"
 ];
 var RUNTIME_BODY_HASH_CONTRACT = {
   algorithm: "SHA-256",
@@ -161,7 +164,10 @@ 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",
+  surfaceNotAllowed: "surface_not_allowed"
 };
 var RUNTIME_METERING_CONTRACT = {
   endpoint: "/v1/metering/events",