@farthershore/backend 0.10.0 → 0.11.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.10.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.11.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/generated/runtime-contract.js

@@ -160,7 +160,8 @@ var RUNTIME_ERROR_CODES = {
   bodyTooLarge: "body_too_large",
   environmentMismatch: "environment_mismatch",
   missingToken: "missing_token",
-  invalidToken: "invalid_token"
+  invalidToken: "invalid_token",
+  contextUnverified: "context_unverified"
 };
 var RUNTIME_METERING_CONTRACT = {
   endpoint: "/v1/metering/events",

package/dist/index.js

@@ -214,7 +214,8 @@ var RUNTIME_ERROR_CODES = {
   bodyTooLarge: "body_too_large",
   environmentMismatch: "environment_mismatch",
   missingToken: "missing_token",
-  invalidToken: "invalid_token"
+  invalidToken: "invalid_token",
+  contextUnverified: "context_unverified"
 };
 var RUNTIME_RESPONSE_METERING_CONTRACT = {
   headers: {
@@ -259,6 +260,8 @@ var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
   // Credential / token presentation faults → UNAUTHORIZED (401).
   [RUNTIME_ERROR_CODES.missingToken]: "UNAUTHORIZED",
   [RUNTIME_ERROR_CODES.invalidToken]: "UNAUTHORIZED",
+  // UA-6 — fail-closed signed-context requirement (mirrors contracts).
+  [RUNTIME_ERROR_CODES.contextUnverified]: "UNAUTHORIZED",
   // Signature / key faults → UNAUTHORIZED (401, fail-closed verification).
   [RUNTIME_ERROR_CODES.missingSignature]: "UNAUTHORIZED",
   [RUNTIME_ERROR_CODES.malformedSignature]: "UNAUTHORIZED",
@@ -1299,8 +1302,19 @@ function permissionGrants(permissions, key2) {
   if (permissions.includes(WILDCARD)) return true;
   return permissions.includes(key2);
 }
+function permissionSatisfies(required, granted) {
+  if (granted === void 0) return true;
+  if (granted.includes(WILDCARD)) return true;
+  if (granted.includes(required)) return true;
+  const idx = required.indexOf(":");
+  if (idx > 0 && idx < required.length - 1) {
+    const subject = required.slice(0, idx);
+    if (granted.includes(`${subject}:${WILDCARD}`)) return true;
+  }
+  return false;
+}
 function hasPermission(ctx, key2) {
-  return permissionGrants(ctx.permissions, key2);
+  return permissionSatisfies(key2, ctx.permissions);
 }
 function requirePermission(ctx, key2) {
   if (!hasPermission(ctx, key2)) {
@@ -1309,6 +1323,78 @@ function requirePermission(ctx, key2) {
 }
 var IDENTITY_HEADER_NAMES = RUNTIME_IDENTITY_HEADER_NAMES;
 
+// src/core/verifyContext.ts
+var EXPECTED_JWT_ALG = "HS256";
+function base64urlDecode(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - padded.length % 4) % 4));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+async function importHmacKey(secret) {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+}
+async function verifyContext(token, secrets) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [header, payload, signature] = parts;
+  let headerJson = null;
+  try {
+    headerJson = JSON.parse(
+      new TextDecoder().decode(base64urlDecode(header))
+    );
+  } catch {
+    return null;
+  }
+  if (headerJson?.alg !== EXPECTED_JWT_ALG) return null;
+  const signingInput = new TextEncoder().encode(`${header}.${payload}`);
+  let signatureBytes;
+  try {
+    signatureBytes = base64urlDecode(signature);
+  } catch {
+    return null;
+  }
+  let verified = false;
+  for (const secret of secrets) {
+    try {
+      const key2 = await importHmacKey(secret);
+      if (await crypto.subtle.verify(
+        "HMAC",
+        key2,
+        signatureBytes,
+        signingInput
+      )) {
+        verified = true;
+        break;
+      }
+    } catch {
+    }
+  }
+  if (!verified) return null;
+  try {
+    const parsed = JSON.parse(
+      new TextDecoder().decode(base64urlDecode(payload))
+    );
+    if (typeof parsed !== "object" || parsed === null) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function contextRequiredError(reason) {
+  return new FartherShoreError(
+    "context_unverified",
+    `X-Fs-Context ${reason} (contextVerification is "required")`
+  );
+}
+
 // src/core/verifyRequest.ts
 async function verifyRequest(input, deps) {
   const h = headerGetter(input.headers);
@@ -1416,10 +1502,29 @@ async function verifyRequest(input, deps) {
       "x-fs-request-id has already been seen (replay)"
     );
   }
-  const permissions = parsePermissionHeader(
-    h(RUNTIME_IDENTITY_HEADER_NAMES.permissions)
-  );
-  const roles = parsePermissionHeader(h(RUNTIME_IDENTITY_HEADER_NAMES.roles));
+  let permissions;
+  let roles;
+  let signedContext = null;
+  if (deps.contextSecrets && deps.contextSecrets.length > 0) {
+    const token = h("x-fs-context");
+    if (token) {
+      signedContext = await verifyContext(token, deps.contextSecrets);
+      if (signedContext === null && deps.contextVerification === "required") {
+        throw contextRequiredError("failed verification");
+      }
+    } else if (deps.contextVerification === "required") {
+      throw contextRequiredError("header is missing");
+    }
+  }
+  if (signedContext) {
+    permissions = signedContext.permissions;
+    roles = signedContext.roles;
+  } else {
+    permissions = parsePermissionHeader(
+      h(RUNTIME_IDENTITY_HEADER_NAMES.permissions)
+    );
+    roles = parsePermissionHeader(h(RUNTIME_IDENTITY_HEADER_NAMES.roles));
+  }
   return {
     requestId,
     productId: signedProductId,
@@ -1429,7 +1534,8 @@ async function verifyRequest(input, deps) {
     timestamp,
     bodyHash: computedBodyHash,
     ...permissions !== void 0 ? { permissions } : {},
-    ...roles !== void 0 ? { roles } : {}
+    ...roles !== void 0 ? { roles } : {},
+    ...signedContext ? { signedContext } : {}
   };
 }
 async function computeBodyHash(input) {
@@ -1464,8 +1570,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.10.0".length > 0 ? "0.10.0" : "0.0.0-dev";
-var CONTRACTS_FP = "5ac9937372d11da5".length > 0 ? "5ac9937372d11da5" : "0000000000000000";
+var SDK_VERSION = "0.11.0".length > 0 ? "0.11.0" : "0.0.0-dev";
+var CONTRACTS_FP = "aae5b92b294c8968".length > 0 ? "aae5b92b294c8968" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1967,6 +2073,7 @@ export {
   nodeSpawn,
   parsePermissionHeader,
   permissionGrants,
+  permissionSatisfies,
   reportHealth,
   requirePermission,
   runtimeErrorToErrorCode,
@@ -1974,6 +2081,7 @@ export {
   signCanonicalString2 as signCanonicalString,
   statusForCode,
   verifyCanonicalSignature2 as verifyCanonicalSignature,
+  verifyContext,
   verifyRequest,
   withUsage
 };

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

@@ -34,6 +34,20 @@ export declare function parsePermissionHeader(raw: string | null | undefined): s
  * shared primitive only covers the defined-array rule.
  */
 export declare function permissionGrants(permissions: readonly string[] | undefined, key: string): boolean;
+/**
+ * Whether the granted `permissions` satisfy the required `key` under the
+ * 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).
+ *
+ * FAITHFUL COPY of the canonical `permissionSatisfies` in
+ * `@farthershore/contracts` (`authz/verbs.ts`); the published bundle is
+ * contracts-free, so `permissions-parity.test.ts` asserts agreement over a
+ * shared golden table (with the backend's grace rule tested separately).
+ */
+export declare function permissionSatisfies(required: string, granted: readonly string[] | undefined): boolean;
 /** The subset of a verified context these helpers read. */
 export interface PermissionCarrier {
     permissions?: readonly string[];
@@ -42,7 +56,8 @@ export interface PermissionCarrier {
  * 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.
+ * constraint is the security boundary for route-level access. Uses the unified
+ * {@link permissionSatisfies} rule (`*` / `<subject>:*` / exact).
  */
 export declare function hasPermission(ctx: PermissionCarrier, key: string): boolean;
 /**

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

@@ -0,0 +1,33 @@
+import { FartherShoreError } from "./errors.js";
+/** The signed context payload (claim-format cv=1). */
+export type FartherShoreSignedContext = {
+    /** Claim-format version. This SDK understands cv 1 (and legacy tokens
+     *  without cv, which predate UA-6 and carry no permissions). */
+    cv?: number;
+    orgId: string;
+    actor: {
+        type: string;
+        id: string | null;
+    };
+    productId: string;
+    compiledPlanId: string;
+    subscriptionId: string;
+    subscriberId: string;
+    environmentId: string | null;
+    subjectKey: string;
+    /** UA-6 — the unified-authz permission claim (absent when unminted). */
+    permissions?: string[];
+    /** UA-6 — the bound role keys (absent when unminted). */
+    roles?: string[];
+};
+/**
+ * Verify an `X-Fs-Context` token against one or more HS256 secrets (try-all
+ * for keyring rotation). Returns the typed payload on success, `null` on any
+ * failure (malformed, wrong alg, bad signature, unparseable payload) — the
+ * caller decides whether absence/invalidity is fatal (`required`) or falls
+ * back to the transitional unsigned headers (`preferred`).
+ */
+export declare function verifyContext(token: string, secrets: readonly string[]): Promise<FartherShoreSignedContext | null>;
+/** Thrown by verifyRequest when `contextVerification: "required"` and the
+ *  signed context is missing or fails verification. */
+export declare function contextRequiredError(reason: string): FartherShoreError;

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

@@ -1,3 +1,4 @@
+import { type FartherShoreSignedContext } from "./verifyContext.js";
 import type { JwksClient } from "./jwks.js";
 import type { NonceCache } from "./nonceCache.js";
 /** Per-request input. `headers` keys are matched case-insensitively. */
@@ -40,6 +41,10 @@ export type FartherShoreRequestContext = {
      * Read via {@link hasPermission} / {@link requirePermission}.
      */
     permissions?: string[];
+    /** UA-6 — the VERIFIED signed context payload, when context secrets are
+     *  configured and the X-Fs-Context token verified. Its permissions/roles
+     *  populated the fields above (signed-preferred). */
+    signedContext?: FartherShoreSignedContext;
     /** Managed-RBAC role keys the acting user holds (display/audit only). */
     roles?: string[];
 };
@@ -60,5 +65,19 @@ export type VerifyRequestDeps = {
     replayWindowSeconds?: number;
     /** Injectable clock (seconds since epoch). */
     nowSeconds?: () => number;
+    /**
+     * UA-6 — HS256 secret(s) for verifying the gateway's SIGNED `X-Fs-Context`
+     * claim (multiple = keyring rotation, try-all). When provided, a VERIFIED
+     * context's `permissions`/`roles` claims are preferred over the
+     * transitional unsigned identity headers.
+     */
+    contextSecrets?: readonly string[];
+    /**
+     * UA-6 — `"preferred"` (default): a missing/unverifiable signed context
+     * falls back to the unsigned headers. `"required"`: missing or invalid
+     * signed context REJECTS the request (fail-closed) — set this once your
+     * gateway config has context signing enabled.
+     */
+    contextVerification?: "preferred" | "required";
 };
 export declare function verifyRequest(input: VerifyRequestInput, deps: VerifyRequestDeps): Promise<FartherShoreRequestContext>;

package/dist/types/generated/runtime-contract.d.ts

@@ -136,6 +136,7 @@ export declare const RUNTIME_ERROR_CODES: {
     readonly environmentMismatch: "environment_mismatch";
     readonly missingToken: "missing_token";
     readonly invalidToken: "invalid_token";
+    readonly contextUnverified: "context_unverified";
 };
 export type RuntimeErrorCode = (typeof RUNTIME_ERROR_CODES)[keyof typeof RUNTIME_ERROR_CODES];
 export declare const RUNTIME_METERING_CONTRACT: {

package/dist/types/index.d.ts

@@ -4,7 +4,9 @@ export { FartherShore } from "./core/runtime.js";
 export type { FartherShoreInitOptions } from "./core/runtime.js";
 export { FartherShoreError, statusForCode } from "./core/errors.js";
 export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
-export { hasPermission, requirePermission, permissionGrants, parsePermissionHeader, FartherShorePermissionError, IDENTITY_HEADER_NAMES, type PermissionCarrier, } from "./core/permissions.js";
+export { verifyContext } from "./core/verifyContext.js";
+export type { FartherShoreSignedContext } from "./core/verifyContext.js";
+export { hasPermission, requirePermission, permissionGrants, permissionSatisfies, parsePermissionHeader, FartherShorePermissionError, IDENTITY_HEADER_NAMES, type PermissionCarrier, } from "./core/permissions.js";
 export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions } from "./core/nonceCache.js";
 export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -33,9 +33,9 @@
   },
   "optionalDependencies": {
     "@farthershore/cloudflared-linux-x64": "0.0.0",
-    "@farthershore/cloudflared-darwin-arm64": "0.0.0",
+    "@farthershore/cloudflared-linux-arm64": "0.0.0",
     "@farthershore/cloudflared-darwin-x64": "0.0.0",
-    "@farthershore/cloudflared-linux-arm64": "0.0.0"
+    "@farthershore/cloudflared-darwin-arm64": "0.0.0"
   },
   "peerDependencies": {
     "express": "^4.0.0 || ^5.0.0"