@farthershore/backend 0.9.0 → 0.11.0

package/README.md

@@ -1,12 +1,20 @@
 # @farthershore/backend
 
-Runtime metering and gateway-verification SDK for builder upstreams. Install one
-package, set one token (`FS_RUNTIME_TOKEN`), and Farther Shore handles signed
-gateway-to-upstream request verification plus response-bound usage reporting.
-
-> **Status: `0.8.2`.** Versions independently from
-> `@farthershore/farthershore-js` and `@farthershore/business`. Pre-1.0: minor
-> bumps may break, so pin this package exactly or use a patch-only range.
+The runtime SDK for your own backend. When you run a software product 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
+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,
+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
+> pin this package to an exact version (or a patch-only range) and upgrade
+> deliberately.
 
 ## Install
 
@@ -14,7 +22,10 @@ gateway-to-upstream request verification plus response-bound usage reporting.
 npm install @farthershore/backend
 ```
 
-## Quick start (Fetch-compatible handlers)
+Requires Node 22+. The Express adapter has an optional `express` peer dependency
+(v4 or v5); the core verification primitive is framework-neutral.
+
+## Quick start (any Fetch-compatible handler)
 
 ```ts
 import { fartherShore, withUsage } from "@farthershore/backend";
@@ -25,6 +36,8 @@ export async function POST(request: Request) {
   const url = new URL(request.url);
   const body = new Uint8Array(await request.clone().arrayBuffer());
 
+  // Fail-closed: throws a FartherShoreError if the request is not a genuine,
+  // unmodified request signed by the gateway.
   await fs.verifyRequest({
     method: request.method,
     path: url.pathname,
@@ -34,13 +47,15 @@ export async function POST(request: Request) {
   });
 
   const result = await runWorkflow(await request.json());
+
+  // Report usage on the way out — no extra network call.
   return withUsage(request, Response.json(result), {
     tokens_used: result.tokensUsed,
   });
 }
 ```
 
-## Express verification
+## Quick start (Express)
 
 ```ts
 import { fartherShore } from "@farthershore/backend";
@@ -60,31 +75,37 @@ process.on("SIGTERM", () => void fs.shutdown());
 
 ## What `initFromEnv()` derives
 
-The builder configures exactly one thing: `FS_RUNTIME_TOKEN`. Everything else —
-product/upstream/environment ids, the JWKS url, the metering endpoint and
-credential, verification config, transport — is fetched from
-`POST /v1/runtime/bootstrap` and cached in memory (refreshed lazily).
+You configure exactly one thing: `FS_RUNTIME_TOKEN` (mint it for your backend
+with the Farther Shore CLI or dashboard). Everything else — product / 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
+missing or malformed token fails fast.
 
-## Verification (fail-closed, always)
+You can override the core URL via `FS_CORE_URL` (or pass options to
+`initFromEnv()`), but in normal use no other configuration is needed.
+
+## Request verification (fail-closed, always)
 
 `fs.middleware()` (Express) and the framework-neutral
-`fs.verifyRequest({ method, path, query, headers, body })` recompute the
-[canonical signing string](../../docs/superpowers/specs/metering-runtime-spec.md)
-from the actual request and verify the gateway's Ed25519 signature against a
-JWKS-resolved public key. The plaintext `X-FS-*` headers are **untrusted** —
-identity comes only from a signature whose claims match the real request.
+`fs.verifyRequest({ method, path, query, headers, body })` recompute a canonical
+signing string from the actual request and verify the gateway's Ed25519 signature
+against a JWKS-resolved public key. The plaintext `X-FS-*` headers are
+**untrusted** — identity comes only from a signature whose claims match the real
+request, so a forged or replayed request cannot impersonate the gateway.
 
 Every failure (missing / malformed / bad-signature / stale / clock-skew /
-wrong-route / body-hash-mismatch / replayed-nonce / unknown-kid /
-jwks-unavailable) returns a typed `FartherShoreError` → **HTTP 401** (413 for
-oversized bodies). There is no fail-open branch.
+wrong-route / body-hash-mismatch / replayed-nonce / unknown-key /
+keys-unavailable) throws a typed `FartherShoreError` that maps to **HTTP 401**
+(413 for oversized bodies). There is no fail-open path.
 
-## Response-bound metering
+## Response-bound usage reporting
 
-Use `withUsage()` or `createUsage()` when usage is known while returning a
-gateway-handled response. These helpers make no network call. They sign dynamic
-usage into internal response headers, and the gateway verifies, settles, and
-strips those headers before the subscriber receives the response.
+Use `withUsage()` (or the builder-style `createUsage()`) when you know the usage
+for a request while you are returning the response. These helpers make **no
+network call** — they sign the usage into internal response headers, and the
+gateway verifies, settles, and strips those headers before your subscriber sees
+the response.
 
 ```ts
 import { withUsage } from "@farthershore/backend";
@@ -103,27 +124,48 @@ 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 and values are validated locally before signing. The gateway accepts actual
-request-bound usage only from the `x-fs-metering` response-header contract signed
-with `FS_RUNTIME_TOKEN`; retired `x-fs-usage` actual-report headers are stripped
-and ignored.
+- `measureContext` is free-form pricing/analytics context persisted with the
+  usage event.
+- `creditUnitsConsumed` is a numeric map for credit-wallet style products; 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
+backend code.
+
+## Async / background usage
+
+Use `fs.meter(meter, qty, { requestId, routeId })` only for usage that is **not**
+tied to a gateway response — background jobs, deferred billing, batch work. It
+enqueues an idempotent event and POSTs it to the platform's metering endpoint.
+Delivery is at-least-once; the event idempotency key keeps ingestion safe.
+Background usage is tallied and billed after the cycle, not enforced in
+real time.
+
+## Lifecycle
+
+- `fs.health()` returns the current local health report (token present, bootstrap
+  loaded, verification + metering status).
+- `fs.shutdown()` flushes any buffered metering and sends a `stopping` heartbeat.
+  Call it on `SIGTERM` / `SIGINT` for graceful shutdown.
 
-## Async/background metering
+## Key exports
 
-Use `fs.meter(meter, qty, { requestId, routeId })` only for async/background
-usage that is not tied to a gateway response. It enqueues an idempotent event and
-POSTs it to `/v1/metering/events` with a reusable bearer credential. Delivery is
-at-least-once; the `event_id` idempotency key keeps core's ingest safe. Values
-are tallied/billed post-cycle, not real-time enforced.
+| Export                               | Purpose                                              |
+| ------------------------------------ | ---------------------------------------------------- |
+| `fartherShore.initFromEnv()`         | Create the runtime instance from `FS_RUNTIME_TOKEN`. |
+| `fs.middleware()`                    | Express fail-closed verify → `req.fartherShore`.     |
+| `fs.verifyRequest({...})`            | Framework-neutral request verification.              |
+| `withUsage()` / `createUsage()`      | Response-bound usage reporting (no network call).    |
+| `fs.meter(meter, qty, opts)`         | Async/background usage event.                        |
+| `fs.health()` / `fs.shutdown()`      | Health report and graceful shutdown.                 |
+| `FartherShoreError`, `MeteringError` | Typed errors.                                        |
 
-The meter key is not hardcoded by the SDK. It must match a dynamic meter declared
-in the product contract, such as `tokens_used` in the Product SDK examples.
+A subpath export, `@farthershore/backend/express`, exposes the Express adapter
+types directly if you prefer to wire the middleware yourself.
 
-Product route defaults such as request counts remain platform-managed and
-require no upstream code.
+## Learn more
 
-The signing primitives and contract constants are re-exported from
-`@farthershore/contracts/runtime`, the language-neutral source of truth every
-SDK (TypeScript first; Go/Python/Java/Rust later) implements.
+- Platform documentation: https://docs.farthershore.com
+- Provisioning a backend and minting a runtime token is done through the Farther
+  Shore CLI or dashboard.

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",
@@ -309,6 +312,10 @@ var RUNTIME_HEADER_NAMES = {
   policyVersion: "x-fs-policy-version",
   bodyHash: "x-fs-body-hash"
 };
+var RUNTIME_IDENTITY_HEADER_NAMES = {
+  permissions: "x-fs-permissions",
+  roles: "x-fs-roles"
+};
 var RUNTIME_CLOCK_SKEW_SECONDS = 5;
 var RUNTIME_REPLAY_WINDOW_SECONDS = 300;
 var EMPTY_BODY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
@@ -1273,6 +1280,121 @@ function resolvePackageBinary(require2, pkg, manifestPath) {
   return `${root}${sep}${normalized}`;
 }
 
+// src/core/permissions.ts
+var WILDCARD = "*";
+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;
+  }
+};
+function parsePermissionHeader(raw) {
+  if (raw === null || raw === void 0) return void 0;
+  return raw.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+}
+function permissionGrants(permissions, key2) {
+  if (permissions === void 0) return true;
+  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 permissionSatisfies(key2, ctx.permissions);
+}
+function requirePermission(ctx, key2) {
+  if (!hasPermission(ctx, key2)) {
+    throw new FartherShorePermissionError(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);
@@ -1380,6 +1502,29 @@ async function verifyRequest(input, deps) {
       "x-fs-request-id has already been seen (replay)"
     );
   }
+  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,
@@ -1387,7 +1532,10 @@ async function verifyRequest(input, deps) {
     routeId: signedRouteId,
     policyVersion,
     timestamp,
-    bodyHash: computedBodyHash
+    bodyHash: computedBodyHash,
+    ...permissions !== void 0 ? { permissions } : {},
+    ...roles !== void 0 ? { roles } : {},
+    ...signedContext ? { signedContext } : {}
   };
 }
 async function computeBodyHash(input) {
@@ -1422,8 +1570,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.9.0".length > 0 ? "0.9.0" : "0.0.0-dev";
-var CONTRACTS_FP = "bd767c2d91739744".length > 0 ? "bd767c2d91739744" : "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;
@@ -1893,6 +2041,8 @@ export {
   FS_RUNTIME_TOKEN_ENV,
   FartherShore,
   FartherShoreError,
+  FartherShorePermissionError,
+  IDENTITY_HEADER_NAMES,
   JwksClient,
   MAX_BODY_BYTES,
   METERING_PAYLOAD_HEADER,
@@ -1917,15 +2067,21 @@ export {
   createExpressMiddleware,
   createUsage,
   fartherShore,
+  hasPermission,
   hashBody2 as hashBody,
   initFromEnv2 as initFromEnv,
   nodeSpawn,
+  parsePermissionHeader,
+  permissionGrants,
+  permissionSatisfies,
   reportHealth,
+  requirePermission,
   runtimeErrorToErrorCode,
   runtimeTokenKind2 as runtimeTokenKind,
   signCanonicalString2 as signCanonicalString,
   statusForCode,
   verifyCanonicalSignature2 as verifyCanonicalSignature,
+  verifyContext,
   verifyRequest,
   withUsage
 };

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

@@ -0,0 +1,72 @@
+/**
+ * Thrown by {@link requirePermission} when the acting user lacks a permission.
+ * Distinct from {@link FartherShoreError} (which models signing/verification
+ * failures) — authorization is a separate concern from request verification,
+ * and its 403 status is not part of the runtime verification contract.
+ */
+export declare class FartherShorePermissionError extends Error {
+    readonly code = "permission_denied";
+    readonly status = 403;
+    /** The permission key that was required but not held. */
+    readonly requiredPermission: string;
+    constructor(requiredPermission: string, message?: string);
+}
+/**
+ * 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.
+ */
+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.
+ *
+ * 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.
+ */
+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[];
+}
+/**
+ * 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).
+ */
+export declare function hasPermission(ctx: PermissionCarrier, key: string): boolean;
+/**
+ * Assert the acting user holds `key`, throwing {@link FartherShorePermissionError}
+ * (403) otherwise. Same trust model as {@link hasPermission}.
+ */
+export declare function requirePermission(ctx: PermissionCarrier, key: string): void;
+/** Re-exported for callers that read the header name directly. */
+export declare const IDENTITY_HEADER_NAMES: {
+    readonly permissions: "x-fs-permissions";
+    readonly roles: "x-fs-roles";
+};

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. */
@@ -32,6 +33,20 @@ export type FartherShoreRequestContext = {
     customerId?: string;
     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}.
+     */
+    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[];
 };
 export type VerifyRequestDeps = {
     jwks: JwksClient;
@@ -50,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,6 +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 { 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/dist/types/runtime-types.d.ts

@@ -133,6 +133,11 @@ export declare const RUNTIME_HEADER_NAMES: {
     readonly bodyHash: "x-fs-body-hash";
 };
 export type RuntimeHeaderName = (typeof RUNTIME_HEADER_NAMES)[keyof typeof RUNTIME_HEADER_NAMES];
+export declare const RUNTIME_IDENTITY_HEADER_NAMES: {
+    readonly permissions: "x-fs-permissions";
+    readonly roles: "x-fs-roles";
+};
+export type RuntimeIdentityHeaderName = (typeof RUNTIME_IDENTITY_HEADER_NAMES)[keyof typeof RUNTIME_IDENTITY_HEADER_NAMES];
 /** Mirrors SERVICE_JWT_CLOCK_SKEW_SECONDS — the per-request signer reuses the
  * same Ed25519/JWKS infra so the skew allowance is kept identical. */
 export declare const RUNTIME_CLOCK_SKEW_SECONDS = 5;

package/package.json

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