@farthershore/backend 0.14.0 → 0.16.0

package/dist/testing/index.js

@@ -218,7 +218,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_RESPONSE_METERING_CONTRACT = {
   headers: {
@@ -282,7 +284,10 @@ var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
   // the canonical code keeps the "dependency down" semantic for callers.
   [RUNTIME_ERROR_CODES.jwksUnavailable]: "SERVICE_UNAVAILABLE",
   // The single non-401 (413) — oversized request body.
-  [RUNTIME_ERROR_CODES.bodyTooLarge]: "VALIDATION_ERROR"
+  [RUNTIME_ERROR_CODES.bodyTooLarge]: "VALIDATION_ERROR",
+  // Consumer-principal wave — route subject-requirement faults → FORBIDDEN (403).
+  [RUNTIME_ERROR_CODES.memberSubjectRequired]: "FORBIDDEN",
+  [RUNTIME_ERROR_CODES.serviceSubjectRequired]: "FORBIDDEN"
 };
 var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
 var RUNTIME_TOKEN_PREFIXES = {
@@ -294,16 +299,12 @@ var RUNTIME_HEADER_NAMES = {
   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",
   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";
@@ -346,34 +347,19 @@ var CANONICAL_SIGNING_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
-  "policy-version"
+  "policy-version",
+  // Consumer-principal wave (D3) — the trailing identity-context binding line.
+  // MUST stay last so pre-binding verifiers that stop at `policy-version`
+  // fail loud on a bound request rather than silently accepting a prefix.
+  "context-hash"
 ];
 var CANONICAL_FIELD_SEPARATOR = "\n";
 var CANONICAL_KV_SEPARATOR = ":";
 function canonicalizeQuery(query) {
-  const raw = query.startsWith("?") ? query.slice(1) : query;
-  if (raw === "")
-    return "";
-  const pairs = raw.split("&").filter((p) => p.length > 0);
-  pairs.sort((a, b) => {
-    const [an, ...arest] = a.split("=");
-    const [bn, ...brest] = b.split("=");
-    if (an < bn)
-      return -1;
-    if (an > bn)
-      return 1;
-    const av = arest.join("=");
-    const bv = brest.join("=");
-    if (av < bv)
-      return -1;
-    if (av > bv)
-      return 1;
-    return 0;
-  });
-  return pairs.join("&");
+  return query;
 }
 function buildCanonicalSigningString(input) {
   const values = {
@@ -383,13 +369,17 @@ function buildCanonicalSigningString(input) {
     "body-hash": input.bodyHash,
     "request-id": input.requestId,
     timestamp: String(input.timestamp),
-    "product-id": input.productId,
+    "business-id": input.businessId,
     "backend-id": input.backendId,
     "route-id": input.routeId,
-    "policy-version": input.policyVersion
+    "policy-version": input.policyVersion,
+    "context-hash": input.contextHash
   };
   return CANONICAL_SIGNING_FIELDS.map((field) => `${field}${CANONICAL_KV_SEPARATOR}${values[field]}`).join(CANONICAL_FIELD_SEPARATOR);
 }
+function hashContextToken(token) {
+  return hashBody(new TextEncoder().encode(token ?? ""));
+}
 var ED25519_ALGORITHM = "Ed25519";
 async function importEd25519PrivateKey(jwk) {
   return crypto.subtle.importKey("jwk", { ...jwk, alg: void 0 }, { name: ED25519_ALGORITHM }, false, ["sign"]);
@@ -431,6 +421,7 @@ function base64UrlDecode(value) {
 // src/runtime-signing.ts
 var hashBody2 = hashBody;
 var buildCanonicalSigningString2 = buildCanonicalSigningString;
+var hashContextToken2 = hashContextToken;
 var signCanonicalString2 = signCanonicalString;
 var verifyCanonicalSignature2 = verifyCanonicalSignature;
 var runtimeTokenKind2 = runtimeTokenKind;
@@ -608,10 +599,13 @@ async function makeSignedRequest(spec = {}) {
     bodyHash,
     requestId: spec.requestId ?? `req_${cryptoRandom()}`,
     timestamp: spec.timestamp ?? Math.floor(Date.now() / 1e3),
-    productId: spec.productId ?? "prod_test",
+    businessId: spec.businessId ?? "biz_test",
     backendId: spec.backendId ?? "be_test",
     routeId: spec.routeId ?? "route_test",
-    policyVersion: spec.policyVersion ?? "pv_1"
+    policyVersion: spec.policyVersion ?? "pv_1",
+    // Consumer-principal wave (D3): bind the X-Fs-Context hash into the
+    // canonical string (empty context → SHA-256 of the empty string).
+    contextHash: await hashContextToken2(spec.contextToken)
   };
   const canonical = buildCanonicalSigningString2(claim);
   const signature = await signCanonicalString2(canonical, privateJwk);
@@ -620,11 +614,12 @@ async function makeSignedRequest(spec = {}) {
     [RUNTIME_HEADER_NAMES.keyId]: kid,
     [RUNTIME_HEADER_NAMES.requestId]: claim.requestId,
     [RUNTIME_HEADER_NAMES.timestamp]: String(claim.timestamp),
-    [RUNTIME_HEADER_NAMES.productId]: claim.productId,
+    [RUNTIME_HEADER_NAMES.businessId]: claim.businessId,
     [RUNTIME_HEADER_NAMES.backendId]: claim.backendId,
     [RUNTIME_HEADER_NAMES.routeId]: claim.routeId,
     [RUNTIME_HEADER_NAMES.policyVersion]: claim.policyVersion,
-    [RUNTIME_HEADER_NAMES.bodyHash]: claim.bodyHash
+    [RUNTIME_HEADER_NAMES.bodyHash]: claim.bodyHash,
+    ...spec.contextToken ? { "x-fs-context": spec.contextToken } : {}
   };
   return {
     input: { method, path, query, body, streamingExempt },
@@ -663,7 +658,7 @@ function base64urlEncodeJson(value) {
 }
 async function signContextToken(claim, secret = TEST_CONTEXT_SECRET, kid = TEST_CONTEXT_KID) {
   const header = base64urlEncodeJson({ alg: "HS256", typ: "JWT", kid });
-  const payload = base64urlEncodeJson({ cv: 1, ...claim });
+  const payload = base64urlEncodeJson({ ...claim });
   const signingInput = `${header}.${payload}`;
   const key2 = await crypto.subtle.importKey(
     "raw",
@@ -742,13 +737,16 @@ function mergeHeaders(initHeaders, signedHeaders) {
   }
   return headers;
 }
-function buildContextClaim(persona, productId) {
+function buildContextClaim(persona, businessId) {
+  const memberId = persona.actor?.id ?? `user_${persona.name}`;
   return {
-    orgId: persona.orgId ?? "org_dev",
-    actor: persona.actor ?? { type: "user", id: `user_${persona.name}` },
-    // Product binding: the signed context productId MUST equal the signed
-    // request productId or verifyRequest rejects it as tamper evidence.
-    productId,
+    cv: 2,
+    sub: memberId,
+    subjectKind: "member",
+    org: persona.orgId ?? "org_dev",
+    // Business binding: the signed-context businessId claim MUST equal the
+    // signed request businessId or verifyRequest rejects it as tamper evidence.
+    businessId,
     compiledPlanId: persona.compiledPlanId ?? "plan_dev",
     subscriptionId: persona.subscriptionId ?? "sub_dev",
     subscriberId: persona.subscriberId ?? "subscriber_dev",
@@ -770,30 +768,27 @@ function createPersonaClient(ctx) {
   }
   async function buildHeaders(persona, spec) {
     const method = normalizeMethod(spec.method);
+    const contextToken = persona.anonymous ? void 0 : await signContextToken(
+      buildContextClaim(persona, ctx.businessId),
+      ctx.contextSecret,
+      ctx.contextKid
+    );
     const signed = await makeSignedRequest({
       method,
       path: spec.path ?? "/",
       query: spec.query ?? "",
       body: spec.body ?? null,
       streamingExempt: spec.streamingExempt ?? false,
-      productId: ctx.productId,
+      businessId: ctx.businessId,
       backendId: ctx.backendId,
       routeId: spec.routeId ?? "",
       privateJwk: ctx.keys.privateJwk,
       kid: ctx.keys.kid,
+      ...contextToken ? { contextToken } : {},
       ...spec.requestId ? { requestId: spec.requestId } : {},
       ...spec.timestamp !== void 0 ? { timestamp: spec.timestamp } : {}
     });
-    const headers = { ...signed.headers };
-    if (!persona.anonymous) {
-      const claim = buildContextClaim(persona, ctx.productId);
-      headers["x-fs-context"] = await signContextToken(
-        claim,
-        ctx.contextSecret,
-        ctx.contextKid
-      );
-    }
-    return headers;
+    return { ...signed.headers };
   }
   function asPersona(name) {
     const persona = resolve(name);
@@ -861,12 +856,12 @@ var DEV_CORE_URL = "https://dev-gateway.farthershore.local";
 var DEV_JWKS_URL = `${DEV_CORE_URL}/.well-known/jwks.json`;
 var DEV_METERING_ENDPOINT = `${DEV_CORE_URL}/v1/metering/events`;
 function createDevGateway(options) {
-  const productId = options.productId ?? "prod_dev";
+  const businessId = options.businessId ?? "biz_dev";
   const backendId = options.backendId ?? "be_dev";
   const meterEvents = [];
   const reportUsageEvents = [];
   const bootstrap = {
-    product: { id: productId, slug: options.productSlug ?? "dev-product" },
+    business: { id: businessId, slug: options.businessSlug ?? "dev-business" },
     backend: {
       id: backendId,
       slug: options.backendSlug ?? "dev-backend",
@@ -936,7 +931,7 @@ function createDevGateway(options) {
     bootstrap,
     meterEvents,
     reportUsageEvents,
-    productId,
+    businessId,
     backendId,
     jwksUrl: DEV_JWKS_URL
   };
@@ -1136,7 +1131,7 @@ var DEFAULT_MAX_RETRIES = 3;
 var MeteringClient = class {
   config;
   endpoint;
-  productId;
+  businessId;
   backendId;
   fetchImpl;
   maxRetries;
@@ -1150,7 +1145,7 @@ var MeteringClient = class {
   constructor(options) {
     this.config = options.config;
     this.endpoint = resolveEndpoint(options.config.endpoint, options.coreUrl);
-    this.productId = options.productId;
+    this.businessId = options.businessId;
     this.backendId = options.backendId;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -1213,13 +1208,14 @@ var MeteringClient = class {
     }
     const event = {
       event_id: options.eventId ?? this.newId(),
-      product_id: this.productId,
+      business_id: this.businessId,
       backend_id: this.backendId,
       meter,
       qty,
       timestamp: options.timestamp ?? this.now().toISOString(),
       ...options.routeId ? { route_id: options.routeId } : {},
-      ...options.requestId ? { request_id: options.requestId } : {}
+      ...options.requestId ? { request_id: options.requestId } : {},
+      ...options.subscriptionId ? { subscription_id: options.subscriptionId } : {}
     };
     this.buffer.push(event);
     await this.flush();
@@ -1421,8 +1417,8 @@ function resolveEndpoint2(endpoint, coreUrl) {
 }
 
 // src/core/nonceCache.ts
-var DEFAULT_MAX_ENTRIES = 1e5;
-var DEFAULT_TTL_MS = 6e5;
+var DEFAULT_MAX_ENTRIES = 25e4;
+var DEFAULT_TTL_MS = (RUNTIME_REPLAY_WINDOW_SECONDS + RUNTIME_CLOCK_SKEW_SECONDS) * 1e3;
 var NonceCache = class {
   maxEntries;
   ttlMs;
@@ -1446,7 +1442,7 @@ var NonceCache = class {
       this.seen.delete(id);
     }
     this.evictExpired(at);
-    this.evictOverflow();
+    if (this.seen.size >= this.maxEntries) return true;
     this.seen.set(id, at);
     return false;
   }
@@ -1460,13 +1456,6 @@ var NonceCache = class {
       this.seen.delete(id);
     }
   }
-  evictOverflow() {
-    while (this.seen.size >= this.maxEntries) {
-      const oldest = this.seen.keys().next().value;
-      if (oldest === void 0) break;
-      this.seen.delete(oldest);
-    }
-  }
 };
 
 // src/core/shutdown.ts
@@ -1801,47 +1790,82 @@ 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);
+// ../contracts/dist/authz/principal.js
+var SUBJECT_KINDS = ["member", "service"];
+function isSubjectKind(value) {
+  return typeof value === "string" && SUBJECT_KINDS.includes(value);
 }
-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 isNonEmptyTrimmed(value) {
+  return typeof value === "string" && value.trim().length > 0;
 }
-function hasPermission(ctx, key2) {
-  if (ctx.permissions === void 0) {
-    return ctx.signedContext !== void 0;
-  }
-  return permissionSatisfies(key2, ctx.permissions);
+function normalizeIdentityId(value) {
+  return value.trim();
 }
-function requirePermission(ctx, key2) {
-  if (!hasPermission(ctx, key2)) {
-    throw new FartherShorePermissionError(key2);
+function isNonEmptyStringArray(value) {
+  return Array.isArray(value) && value.every((item) => isNonEmptyTrimmed(item));
+}
+function principalFromContextClaims(claims) {
+  if (typeof claims !== "object" || claims === null)
+    return null;
+  const { sub, org: orgId, businessId, subjectKind } = claims;
+  if (!isNonEmptyTrimmed(sub) || !isNonEmptyTrimmed(orgId) || !isNonEmptyTrimmed(businessId)) {
+    return null;
   }
+  if (!isSubjectKind(subjectKind))
+    return null;
+  if (claims.permissions !== void 0 && !isNonEmptyStringArray(claims.permissions)) {
+    return null;
+  }
+  if (claims.roles !== void 0 && !isNonEmptyStringArray(claims.roles)) {
+    return null;
+  }
+  const clientId = claims.client_id;
+  const actSub = claims.act?.sub;
+  if (isNonEmptyTrimmed(clientId) && isNonEmptyTrimmed(actSub) && normalizeIdentityId(clientId) !== normalizeIdentityId(actSub)) {
+    return null;
+  }
+  const org = { id: normalizeIdentityId(orgId) };
+  if (subjectKind === "service") {
+    const explicitServiceAccountId = claims.serviceAccountId;
+    if (isNonEmptyTrimmed(explicitServiceAccountId) && normalizeIdentityId(explicitServiceAccountId) !== normalizeIdentityId(sub)) {
+      return null;
+    }
+    const serviceAccountId = normalizeIdentityId(explicitServiceAccountId ?? sub);
+    const keyIdSource = clientId ?? actSub ?? sub;
+    if (!isNonEmptyTrimmed(serviceAccountId) || !isNonEmptyTrimmed(keyIdSource)) {
+      return null;
+    }
+    return {
+      org,
+      subject: {
+        kind: "service",
+        serviceAccountId,
+        keyId: normalizeIdentityId(keyIdSource)
+      }
+    };
+  }
+  const memberId = normalizeIdentityId(sub);
+  const act = claims.act;
+  if (act !== void 0 && act !== null) {
+    if (typeof act !== "object" || !isNonEmptyTrimmed(act.sub))
+      return null;
+    return {
+      org,
+      subject: {
+        kind: "member",
+        memberId,
+        via: "api_key",
+        keyId: normalizeIdentityId(act.sub)
+      }
+    };
+  }
+  return { org, subject: { kind: "member", memberId, via: "session" } };
 }
 
 // src/core/verifyContext.ts
+function principalFromContextClaims2(claims) {
+  return principalFromContextClaims(claims);
+}
 var EXPECTED_JWT_ALG = "HS256";
 function base64urlDecode(value) {
   const padded = value.replace(/-/g, "+").replace(/_/g, "/");
@@ -1881,6 +1905,7 @@ async function verifyContext(token, secrets) {
   }
   let verified = false;
   for (const secret of secrets) {
+    if (secret.trim().length === 0) continue;
     try {
       const key2 = await importHmacKey(secret);
       if (await crypto.subtle.verify(
@@ -1896,11 +1921,20 @@ async function verifyContext(token, secrets) {
     }
   }
   if (!verified) return null;
+  return parseContextPayload(payload);
+}
+function decodeContextClaims(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  return parseContextPayload(parts[1]);
+}
+function parseContextPayload(payload) {
   try {
     const parsed = JSON.parse(
       new TextDecoder().decode(base64urlDecode(payload))
     );
     if (typeof parsed !== "object" || parsed === null) return null;
+    if (parsed.cv !== 2) return null;
     return parsed;
   } catch {
     return null;
@@ -1909,7 +1943,7 @@ async function verifyContext(token, secrets) {
 function contextRequiredError(reason) {
   return new FartherShoreError(
     "context_unverified",
-    `X-Fs-Context ${reason} (contextVerification is "required")`
+    `X-Fs-Context ${reason} \u2014 signed context is required whenever context secrets are configured`
   );
 }
 
@@ -1926,12 +1960,12 @@ async function verifyRequest(input, deps) {
   const kid = h(RUNTIME_HEADER_NAMES.keyId);
   const requestId = h(RUNTIME_HEADER_NAMES.requestId);
   const timestampRaw = h(RUNTIME_HEADER_NAMES.timestamp);
-  const signedProductId = h(RUNTIME_HEADER_NAMES.productId);
+  const signedBusinessId = h(RUNTIME_HEADER_NAMES.businessId);
   const signedBackendId = h(RUNTIME_HEADER_NAMES.backendId);
   const signedRouteId = h(RUNTIME_HEADER_NAMES.routeId) ?? "";
   const policyVersion = h(RUNTIME_HEADER_NAMES.policyVersion);
   const signedBodyHash = h(RUNTIME_HEADER_NAMES.bodyHash);
-  if (!kid || !requestId || !timestampRaw || !signedProductId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
+  if (!kid || !requestId || !timestampRaw || !signedBusinessId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
     throw new FartherShoreError(
       "malformed_signature",
       "request is missing one or more required x-fs-* headers"
@@ -1967,10 +2001,10 @@ async function verifyRequest(input, deps) {
       "recomputed body hash does not match the signed x-fs-body-hash"
     );
   }
-  if (deps.productId !== void 0 && signedProductId !== deps.productId) {
+  if (deps.businessId !== void 0 && signedBusinessId !== deps.businessId) {
     throw new FartherShoreError(
       "route_mismatch",
-      "signed product-id does not match this backend's product"
+      "signed business-id does not match this backend's business"
     );
   }
   if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
@@ -1985,6 +2019,7 @@ async function verifyRequest(input, deps) {
       "signed route-id is not served by this backend"
     );
   }
+  const contextToken = h("x-fs-context") ?? null;
   const canonicalInput = {
     method: input.method,
     path: input.path,
@@ -1992,10 +2027,16 @@ async function verifyRequest(input, deps) {
     bodyHash: computedBodyHash,
     requestId,
     timestamp,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
-    policyVersion
+    policyVersion,
+    // Consumer-principal wave (D3): bind the presented X-Fs-Context hash into
+    // the canonical string in exact lockstep with the gateway signer. A missing
+    // context hashes the empty string, so an identity-less request still
+    // verifies (it is rejected later by the fail-closed context gate when
+    // secrets exist).
+    contextHash: await hashContextToken2(contextToken)
   };
   const canonical = buildCanonicalSigningString2(canonicalInput);
   const publicJwk = await deps.jwks.getKey(kid);
@@ -2014,58 +2055,63 @@ async function verifyRequest(input, deps) {
       "Ed25519 signature verification failed"
     );
   }
-  if (deps.nonceCache.checkAndRemember(requestId)) {
+  if (await deps.nonceCache.checkAndRemember(requestId)) {
     throw new FartherShoreError(
       "replayed_nonce",
       "x-fs-request-id has already been seen (replay)"
     );
   }
-  let permissions;
-  let roles;
-  let signedContext = null;
-  const contextSecrets = deps.contextSecrets ?? [];
-  const hasContextKeyring = contextSecrets.length > 0;
-  if (hasContextKeyring) {
-    const token = h("x-fs-context");
-    if (token) {
-      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");
-  }
+  const signedContext = await resolveSignedContext(
+    contextToken,
+    deps.contextSecrets ?? [],
+    signedBusinessId
+  );
+  const permissions = signedContext?.permissions;
+  const roles = signedContext?.roles;
+  let principal;
   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));
+    const derived = principalFromContextClaims2(signedContext);
+    if (derived === null) {
+      throw contextRequiredError(
+        "carried an invalid or incomplete consumer principal"
+      );
+    }
+    principal = derived;
   }
   return {
     requestId,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion,
     timestamp,
     bodyHash: computedBodyHash,
+    ...principal ? { principal } : {},
     ...permissions !== void 0 ? { permissions } : {},
     ...roles !== void 0 ? { roles } : {},
     ...signedContext ? { signedContext } : {}
   };
 }
+async function resolveSignedContext(contextToken, contextSecrets, signedBusinessId) {
+  if (!contextToken) return null;
+  const signedContext = decodeContextClaims(contextToken);
+  if (signedContext === null) {
+    throw contextRequiredError("payload could not be parsed as a cv=2 claim");
+  }
+  if (contextSecrets.length > 0) {
+    const hmacVerified = await verifyContext(contextToken, contextSecrets);
+    if (hmacVerified === null) {
+      throw contextRequiredError("failed HS256 verification");
+    }
+  }
+  if (signedContext.businessId !== signedBusinessId) {
+    throw new FartherShoreError(
+      "context_unverified",
+      "X-Fs-Context was minted for a different business than the signed request"
+    );
+  }
+  return signedContext;
+}
 async function computeBodyHash(input) {
   if (input.streamingExempt) return STREAMING_EXEMPT_BODY_HASH;
   const body = input.body;
@@ -2098,8 +2144,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.14.0".length > 0 ? "0.14.0" : "0.0.0-dev";
-var CONTRACTS_FP = "1feb5a4a80b447ad".length > 0 ? "1feb5a4a80b447ad" : "0000000000000000";
+var SDK_VERSION = "0.16.0".length > 0 ? "0.16.0" : "0.0.0-dev";
+var CONTRACTS_FP = "c3961d4ea07ff178".length > 0 ? "c3961d4ea07ff178" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2109,11 +2155,9 @@ var FartherShore = class {
   coreUrl;
   instanceId;
   tunnelOptions;
-  /** FAR-723 — HS256 secret(s) for verifying the signed X-Fs-Context claim. */
+  /** OPTIONAL HS256 secret(s) — defense-in-depth over the cv=2 X-Fs-Context. */
   contextSecrets;
-  /** FAR-723 — "preferred" (fallback to unsigned) | "required" (fail-closed). */
-  contextVerification;
-  nonceCache = new NonceCache();
+  nonceCache;
   shutdownManager = new ShutdownManager();
   jwks = null;
   meteringClient = null;
@@ -2131,8 +2175,8 @@ var FartherShore = class {
     this.meteringEnabledOverride = options.metering?.enabled ?? true;
     this.tunnelOptions = options.tunnel ?? {};
     this.instanceId = options.instanceId;
+    this.nonceCache = options.nonceStore ?? new NonceCache();
     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,
@@ -2168,7 +2212,7 @@ var FartherShore = class {
     if (!this.meteringClient && config.metering.enabled) {
       this.meteringClient = new MeteringClient({
         config: config.metering,
-        productId: config.product.id,
+        businessId: config.business.id,
         backendId: config.backend.id,
         coreUrl: this.coreUrl,
         fetchImpl: this.fetchImpl
@@ -2252,17 +2296,15 @@ var FartherShore = class {
     const context = await verifyRequest(input, {
       jwks: this.jwks,
       nonceCache: this.nonceCache,
-      productId: config.product.id,
+      businessId: config.business.id,
       backendId: config.backend.id,
       knownRouteIds,
       clockSkewSeconds: config.verification.clockSkewSeconds,
       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
+      // Consumer-principal wave (D3): OPTIONAL defense-in-depth. The principal
+      // is derived from the Ed25519-vouched X-Fs-Context regardless; when these
+      // secrets are set a presented token must ALSO pass HS256.
+      contextSecrets: this.contextSecrets
     });
     return {
       ...context,
@@ -2389,6 +2431,40 @@ function parseContextSecrets(raw) {
   return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 }
 
+// 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 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) {
+  if (ctx.permissions === void 0) return false;
+  return permissionSatisfies(key2, ctx.permissions);
+}
+function requirePermission(ctx, key2) {
+  if (!hasPermission(ctx, key2)) {
+    throw new FartherShorePermissionError(key2);
+  }
+}
+
 // src/adapters/express.ts
 var STREAMING_CONTENT_TYPES = new Set(
   RUNTIME_BODY_HASH_CONTRACT.streamingExemptContentTypes
@@ -2400,7 +2476,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;
     }
@@ -2417,6 +2495,7 @@ async function runMiddleware(fs, options, req, res, next) {
       streamingExempt
     });
     req.fartherShore = ctx;
+    stripFartherShoreHeaders(req);
     next();
   } catch (error) {
     fail(res, error);
@@ -2429,6 +2508,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 key2 = raw[i];
+      const value = raw[i + 1];
+      if (typeof key2 !== "string" || value === void 0) continue;
+      if (key2.toLowerCase().startsWith("x-fs-")) continue;
+      cleaned.push(key2, 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("?");
@@ -2623,7 +2747,7 @@ function personaClientFromKeysFile(path = DEFAULT_KEYS_FILE, options = {}) {
   const file = readDevKeysFile(path);
   const client = createPersonaClient({
     keys: file.keys,
-    productId: file.productId,
+    businessId: file.businessId,
     backendId: file.backendId,
     contextSecret: file.keys.contextSecret,
     contextKid: file.keys.contextKid,
@@ -2650,7 +2774,7 @@ function createDevRuntime(options) {
   const gateway = createDevGateway({
     mode,
     keys,
-    ...options.productId ? { productId: options.productId } : {},
+    ...options.businessId ? { businessId: options.businessId } : {},
     ...options.backendId ? { backendId: options.backendId } : {},
     ...options.routes ? { routeIds: options.routes } : {},
     onMeterEvent: (event) => {
@@ -2679,7 +2803,7 @@ function createDevRuntime(options) {
   const personas = buildPersonaMap(options.personas);
   const personaClient = createPersonaClient({
     keys,
-    productId: gateway.productId,
+    businessId: gateway.businessId,
     backendId: gateway.backendId,
     contextSecret: keys.contextSecret,
     contextKid: keys.contextKid,
@@ -2691,8 +2815,9 @@ function createDevRuntime(options) {
     runtimeToken: keys.runtimeToken,
     coreUrl: DEV_CORE_URL,
     fetchImpl: gateway.fetchImpl,
+    // Consumer-principal wave (D3): signed cv=2 context is fail-closed whenever
+    // contextSecrets are set — no per-mode verification toggle.
     contextSecrets: [keys.contextSecret],
-    contextVerification: mode === "simulated" ? "required" : "preferred",
     env: {}
   });
   const tracedAuthz = {
@@ -2718,7 +2843,8 @@ function createDevRuntime(options) {
     });
   }
   function middleware(mwOptions) {
-    const inner = createExpressMiddleware(fs, mwOptions);
+    const resolved = mode === "passthrough" ? { always: false, ...mwOptions } : mwOptions ?? {};
+    const inner = createExpressMiddleware(fs, resolved);
     return (req, res, next) => {
       const requestId = headerValue2(req.headers, "x-fs-request-id") ?? "unknown";
       const { path } = splitUrl2(req);
@@ -2757,6 +2883,7 @@ function createDevRuntime(options) {
     };
   }
   fs.middleware = middleware;
+  fs.handler = createExpressHandler;
   const devRuntime = {
     fs,
     asPersona: (name) => personaClient.asPersona(name),
@@ -2809,7 +2936,7 @@ function createDevRuntimeFromEnv(env = readProcessEnv3()) {
     version: 1,
     mode,
     keys,
-    productId: runtime.gateway.productId,
+    businessId: runtime.gateway.businessId,
     backendId: runtime.gateway.backendId,
     personas: mapToRecord(runtime.personas)
   };
@@ -2822,7 +2949,7 @@ function printBanner(mode, runtime, tracePath) {
     "============================================================",
     "  \u26A0  FARTHER SHORE DEV MODE ACTIVE \u2014 NOT FOR PRODUCTION",
     `     mode:      ${mode.toUpperCase()}`,
-    `     product:   ${runtime.gateway.productId}`,
+    `     business:  ${runtime.gateway.businessId}`,
     `     backend:   ${runtime.gateway.backendId}`,
     `     personas:  ${[...runtime.personas.keys()].join(", ")}`,
     `     usage log: ${USAGE_JSONL_PATH}`,