@farthershore/backend 0.11.0 → 0.12.0

package/README.md

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

@@ -1314,6 +1314,9 @@ function permissionSatisfies(required, granted) {
   return false;
 }
 function hasPermission(ctx, key2) {
+  if (ctx.permissions === void 0) {
+    return ctx.signedContext !== void 0;
+  }
   return permissionSatisfies(key2, ctx.permissions);
 }
 function requirePermission(ctx, key2) {
@@ -1505,16 +1508,26 @@ async function verifyRequest(input, deps) {
   let permissions;
   let roles;
   let signedContext = null;
-  if (deps.contextSecrets && deps.contextSecrets.length > 0) {
+  const contextSecrets = deps.contextSecrets ?? [];
+  const hasContextKeyring = contextSecrets.length > 0;
+  if (hasContextKeyring) {
     const token = h("x-fs-context");
     if (token) {
-      signedContext = await verifyContext(token, deps.contextSecrets);
+      signedContext = await verifyContext(token, contextSecrets);
       if (signedContext === null && deps.contextVerification === "required") {
         throw contextRequiredError("failed verification");
       }
+      if (signedContext && signedContext.productId !== signedProductId) {
+        throw new FartherShoreError(
+          "context_unverified",
+          "X-Fs-Context was minted for a different product than the signed request"
+        );
+      }
     } else if (deps.contextVerification === "required") {
       throw contextRequiredError("header is missing");
     }
+  } else if (deps.contextVerification === "required") {
+    throw contextRequiredError("keyring is empty");
   }
   if (signedContext) {
     permissions = signedContext.permissions;
@@ -1570,8 +1583,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.11.0".length > 0 ? "0.11.0" : "0.0.0-dev";
-var CONTRACTS_FP = "aae5b92b294c8968".length > 0 ? "aae5b92b294c8968" : "0000000000000000";
+var SDK_VERSION = "0.12.0".length > 0 ? "0.12.0" : "0.0.0-dev";
+var CONTRACTS_FP = "220bea90107ed396".length > 0 ? "220bea90107ed396" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1581,6 +1594,10 @@ var FartherShore = class {
   coreUrl;
   instanceId;
   tunnelOptions;
+  /** FAR-723 — HS256 secret(s) for verifying the signed X-Fs-Context claim. */
+  contextSecrets;
+  /** FAR-723 — "preferred" (fallback to unsigned) | "required" (fail-closed). */
+  contextVerification;
   nonceCache = new NonceCache();
   shutdownManager = new ShutdownManager();
   jwks = null;
@@ -1598,6 +1615,8 @@ var FartherShore = class {
     this.meteringEnabledOverride = options.metering?.enabled ?? true;
     this.tunnelOptions = options.tunnel ?? {};
     this.instanceId = options.instanceId;
+    this.contextSecrets = options.contextSecrets ?? parseContextSecrets(env.FS_CONTEXT_SECRETS);
+    this.contextVerification = options.contextVerification ?? (env.FS_CONTEXT_VERIFICATION === "required" ? "required" : "preferred");
     this.bootstrapClient = new BootstrapClient({
       runtimeToken,
       coreUrl,
@@ -1716,7 +1735,13 @@ var FartherShore = class {
       backendId: config.backend.id,
       knownRouteIds,
       clockSkewSeconds: config.verification.clockSkewSeconds,
-      replayWindowSeconds: config.verification.replayWindowSeconds
+      replayWindowSeconds: config.verification.replayWindowSeconds,
+      // FAR-723 — a VERIFIED signed X-Fs-Context is the preferred (or
+      // required) identity source. Required mode must also fail closed when the
+      // keyring is empty; preferred mode preserves the transitional unsigned
+      // fallback until the backend-v* publish gate removes it.
+      contextSecrets: this.contextSecrets,
+      contextVerification: this.contextVerification
     });
   }
   /** Whether verification is required (bootstrap × opt-out). */
@@ -1807,6 +1832,10 @@ function readProcessEnv() {
   const maybeProcess = globalThis.process;
   return maybeProcess?.env ?? {};
 }
+function parseContextSecrets(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
 
 // src/adapters/express.ts
 var STREAMING_CONTENT_TYPES = new Set(

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

@@ -1,3 +1,4 @@
+import type { FartherShoreSignedContext } from "./verifyContext.js";
 /**
  * Thrown by {@link requirePermission} when the acting user lacks a permission.
  * Distinct from {@link FartherShoreError} (which models signing/verification
@@ -13,25 +14,26 @@ export declare class FartherShorePermissionError extends Error {
 }
 /**
  * Parse the comma-joined `x-fs-permissions` header into a permission list.
- * Returns `undefined` when the header is absent (full-access grace) and `[]`
- * for a present-but-empty header (deny-all — an authenticated user with no
- * grants). Whitespace-trimmed; empty segments dropped.
+ * Returns `undefined` when the header is absent (no permission source ⇒
+ * carrier-level DENY under FAR-723) and `[]` for a present-but-empty header
+ * (deny-all — an authenticated user with no grants). Whitespace-trimmed; empty
+ * segments dropped.
  */
 export declare function parsePermissionHeader(raw: string | null | undefined): string[] | undefined;
 /**
- * Pure grant check. `undefined` permissions (no header) grant everything —
- * this backend SDK's LOCAL policy, parity with the edge treating an absent
- * claim as `["*"]`. Over a DEFINED array the rule is the shared core primitive:
- * a `"*"` entry grants everything, otherwise the key must be an exact member.
+ * Pure grant check — a FAITHFUL COPY of the canonical `permissionGrants` in
+ * `@farthershore/contracts` (`rbac.ts`). Over a DEFINED array: a `"*"` entry
+ * grants everything, otherwise the key must be an exact member. Its
+ * `undefined → true` codomain is the PRIMITIVE's contract (kept byte-identical
+ * to contracts for parity); it is NOT the SDK's carrier policy. Under FAR-723
+ * the carrier gate {@link hasPermission} DENIES an absent permission set before
+ * this primitive is consulted, so absence never grants at the boundary.
  *
- * The defined-array branch is a FAITHFUL COPY of the canonical
- * `permissionGrants` in `@farthershore/contracts` (`rbac.ts`) — the published
- * SDK surface must stay contracts-free, so it can't import it. A TEST-ONLY
- * parity guard (`permissions-parity.test.ts`, which CAN import contracts as a
- * devDependency) asserts this copy agrees with the canonical primitive across a
- * shared golden vector table, so the copy can't silently drift. The
- * `undefined → grant-all` grace is documented here as the SDK's own policy; the
- * shared primitive only covers the defined-array rule.
+ * The published SDK surface must stay contracts-free, so it can't import the
+ * canonical primitive. A TEST-ONLY parity guard (`permissions-parity.test.ts`,
+ * which CAN import contracts as a devDependency) asserts this copy agrees with
+ * the canonical primitive across a shared golden vector table, so the copy
+ * can't silently drift.
  */
 export declare function permissionGrants(permissions: readonly string[] | undefined, key: string): boolean;
 /**
@@ -39,8 +41,11 @@ export declare function permissionGrants(permissions: readonly string[] | undefi
  * unified grammar: `"*"` (global), `"<subject>:*"` (subject wildcard), or the
  * EXACT key. NO verb-class widening (class forms are expanded to concrete verbs
  * server-side at save time). Superset of {@link permissionGrants} — it adds the
- * `<subject>:*` rung — and keeps the backend SDK's `undefined → grant-all`
- * grace (absent `x-fs-permissions` header ⇒ full access, today's behavior).
+ * `<subject>:*` rung. NOTE: the `granted === undefined → true` codomain here is
+ * the PRIMITIVE's contract (kept byte-identical to contracts for parity); it is
+ * NOT the SDK's carrier policy. Callers gate through {@link hasPermission},
+ * which under FAR-723 DENIES an absent permission set before ever reaching this
+ * primitive — so absence never grants at the carrier level.
  *
  * FAITHFUL COPY of the canonical `permissionSatisfies` in
  * `@farthershore/contracts` (`authz/verbs.ts`); the published bundle is
@@ -51,13 +56,26 @@ export declare function permissionSatisfies(required: string, granted: readonly
 /** The subset of a verified context these helpers read. */
 export interface PermissionCarrier {
     permissions?: readonly string[];
+    /** The verified X-Fs-Context claims, when the request carried a valid token. */
+    signedContext?: FartherShoreSignedContext;
 }
 /**
  * True when the acting user holds `key`. Call only with a verified request
  * context ({@link parsePermissionHeader} output lives on `context.permissions`).
  * NOTE: this is a convenience for in-handler gating; the edge `permission`
- * constraint is the security boundary for route-level access. Uses the unified
- * {@link permissionSatisfies} rule (`*` / `<subject>:*` / exact).
+ * constraint is the security boundary for route-level access.
+ *
+ * FAR-723 FAIL-CLOSED: an ABSENT permission set (`ctx.permissions === undefined`)
+ * DENIES — the reverse of the former grant-all grace — UNLESS the request
+ * carried a cryptographically VERIFIED context token that simply omits the
+ * `perms` claim. Core deliberately mints ORG-actor (and unidentified-user-actor)
+ * `fsc_` tokens with no `perms` claim — RBAC never applies to them, and the edge
+ * `permission` constraint treats a verified claimless token as full access. The
+ * carrier mirrors the edge: verified-but-claimless ⇒ grant; no verified context
+ * AND no permission set ⇒ no trusted permission source ⇒ deny. A DEFINED array
+ * uses the unified {@link permissionSatisfies} rule (`*` / `<subject>:*` /
+ * exact), so an explicit `["*"]` (org OWNER / RBAC-disabled) still grants
+ * everything and `[]` denies.
  */
 export declare function hasPermission(ctx: PermissionCarrier, key: string): boolean;
 /**

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

@@ -39,6 +39,38 @@ export type FartherShoreInitOptions = {
     tunnel?: FartherShoreTunnelOptions;
     /** SDK metadata forwarded to bootstrap. */
     instanceId?: string;
+    /**
+     * FAR-723 / UA-6 — HS256 secret(s) for verifying the gateway's SIGNED
+     * `X-Fs-Context` claim. These are the GATEWAY CONTEXT-SIGNING keyring values
+     * (`CONTEXT_SIGNING_KEYS_JSON` — the keys `forward-upstream` stamps the
+     * header with; supply every live key during rotation — try-all). They are
+     * NOT the product's `contextTokenSecret`, which signs `fsc_` INGRESS tokens
+     * verified BY the gateway — setting that here would reject every valid
+     * gateway request in `"required"` mode. When present, a VERIFIED context's
+     * `permissions`/`roles` claims are the AUTHORITATIVE identity source
+     * (preferred over the transitional unsigned `x-fs-permissions`/`x-fs-roles`
+     * headers). Defaults to `FS_CONTEXT_SECRETS` (comma-separated) from the env.
+     *
+     * NOTE (core-side dependency, FAR-723 publish gate): no bootstrap field
+     * carries these keys yet, and handing the raw platform keyring to builder
+     * backends is NOT the end-state (it would allow cross-product context
+     * forgery). The distribution mechanism — per-product derived keys or an
+     * asymmetric context signature verified via JWKS like the request
+     * signature — is decided at the FAR-723 gate before the headers retire;
+     * until then this option (or `FS_CONTEXT_SECRETS`) is the manual wiring for
+     * platform-operated deployments.
+     */
+    contextSecrets?: readonly string[];
+    /**
+     * FAR-723 / UA-6 — `"preferred"` (default): a missing/unverifiable signed
+     * context falls back to the transitional unsigned headers.
+     * `"required"`: a missing or invalid signed context REJECTS the request
+     * (fail-closed), including when the context-secret keyring is empty or
+     * unconfigured. Defaults to `FS_CONTEXT_VERIFICATION` from the env, else
+     * `"preferred"`. The unsigned fallback is transitional and is removed after
+     * the backend-v* publish gate.
+     */
+    contextVerification?: "preferred" | "required";
 };
 export declare const SDK_VERSION: string;
 export declare const CONTRACTS_FP: string;
@@ -55,6 +87,10 @@ export declare class FartherShore {
     private readonly coreUrl;
     private readonly instanceId?;
     private readonly tunnelOptions;
+    /** FAR-723 — HS256 secret(s) for verifying the signed X-Fs-Context claim. */
+    private readonly contextSecrets;
+    /** FAR-723 — "preferred" (fallback to unsigned) | "required" (fail-closed). */
+    private readonly contextVerification;
     private readonly nonceCache;
     private readonly shutdownManager;
     private jwks;

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

@@ -34,11 +34,12 @@ export type FartherShoreRequestContext = {
     meters?: string[];
     features?: Record<string, unknown>;
     /**
-     * Managed-RBAC permissions the gateway resolved for the acting user, from
-     * the UNSIGNED `x-fs-permissions` identity header (trusted transitively on a
-     * verified request — see permissions.ts). `undefined` when the header is
-     * absent (full-access grace); `[]` for an authenticated user with no grants.
-     * Read via {@link hasPermission} / {@link requirePermission}.
+     * Managed-RBAC permissions the gateway resolved for the acting user —
+     * preferred from the VERIFIED signed `X-Fs-Context` claim, else the UNSIGNED
+     * `x-fs-permissions` identity header (both trusted transitively on a verified
+     * request — see permissions.ts). `undefined` when NO permission source was
+     * present ⇒ FAR-723 carrier-level DENY; `[]` for an authenticated user with
+     * no grants. Read via {@link hasPermission} / {@link requirePermission}.
      */
     permissions?: string[];
     /** UA-6 — the VERIFIED signed context payload, when context secrets are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.11.0",
+  "version": "0.12.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",
@@ -34,8 +34,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"
@@ -53,7 +53,7 @@
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.59.0",
     "vitest": "^4.1.6",
-    "@farthershore/contracts": "0.61.1"
+    "@farthershore/contracts": "0.62.0"
   },
   "engines": {
     "node": ">=22"