@farthershore/backend 0.15.0 → 0.17.0

package/dist/index.js

@@ -215,7 +215,10 @@ var RUNTIME_ERROR_CODES = {
   environmentMismatch: "environment_mismatch",
   missingToken: "missing_token",
   invalidToken: "invalid_token",
-  contextUnverified: "context_unverified"
+  contextUnverified: "context_unverified",
+  memberSubjectRequired: "member_subject_required",
+  serviceSubjectRequired: "service_subject_required",
+  surfaceNotAllowed: "surface_not_allowed"
 };
 var RUNTIME_RESPONSE_METERING_CONTRACT = {
   headers: {
@@ -279,7 +282,12 @@ 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",
+  // A visible route whose surface set excludes the caller → 403.
+  [RUNTIME_ERROR_CODES.surfaceNotAllowed]: "FORBIDDEN"
 };
 function runtimeErrorToErrorCode(code) {
   return RUNTIME_ERROR_CODE_TO_ERROR_CODE[code] ?? "INTERNAL_ERROR";
@@ -289,16 +297,16 @@ var RUNTIME_TOKEN_PREFIXES = {
   live: "fsrt_live_",
   test: "fsrt_test_"
 };
-var RUNTIME_TOKEN_CAPABILITIES = [
+var RUNTIME_TOKEN_OPERATIONS = [
   "gateway_verification",
   "metering",
   "health",
   "tunnel",
-  // Hand-maintained mirror of @farthershore/contracts RUNTIME_TOKEN_CAPABILITIES
+  // Hand-maintained mirror of @farthershore/contracts RUNTIME_TOKEN_OPERATIONS
   // (`runtime.ts`). Bound to that source by the SET-EQUALITY + ORDER assertions
   // in `deny-taxonomy-drift.test.ts` (test-only contracts devDep) — NOT by the
   // generated runtime-contract.ts, which mirrors only RUNTIME_ERROR_CODES.
-  // `drift_report` is the opt-in capability for reporting route drift.
+  // `drift_report` is the opt-in operation for reporting route drift.
   "drift_report"
 ];
 var RUNTIME_HEADER_NAMES = {
@@ -312,10 +320,6 @@ 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";
@@ -361,31 +365,16 @@ var CANONICAL_SIGNING_FIELDS = [
   "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 = {
@@ -398,10 +387,14 @@ function buildCanonicalSigningString(input) {
     "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"]);
@@ -444,6 +437,7 @@ function base64UrlDecode(value) {
 var hashBody2 = hashBody;
 var canonicalizeQuery2 = canonicalizeQuery;
 var buildCanonicalSigningString2 = buildCanonicalSigningString;
+var hashContextToken2 = hashContextToken;
 var signCanonicalString2 = signCanonicalString;
 var verifyCanonicalSignature2 = verifyCanonicalSignature;
 var runtimeTokenKind2 = runtimeTokenKind;
@@ -466,7 +460,9 @@ var FartherShoreError = class extends Error {
   }
 };
 function statusForCode(code) {
-  return code === "body_too_large" ? 413 : 401;
+  if (code === "body_too_large") return 413;
+  if (code === "surface_not_allowed") return 403;
+  return 401;
 }
 
 // src/core/bootstrap.ts
@@ -941,7 +937,7 @@ async function withUsage(request, response, usage, options = {}) {
 }
 async function signResponse(request, response, usage, options, wrapOptions) {
   const payload = buildPayload(request, usage, options, wrapOptions);
-  const requestId = request.headers.get("x-fs-request-id") ?? void 0;
+  const requestId = options.requestId ?? request.headers.get("x-fs-request-id") ?? void 0;
   const headers = await computeMeteringHeaders(payload, {
     ...options.token !== void 0 ? { token: options.token } : {},
     ...options.env !== void 0 ? { env: options.env } : {},
@@ -1195,8 +1191,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;
@@ -1220,7 +1216,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;
   }
@@ -1234,13 +1230,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
@@ -1575,53 +1564,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 permissionGrants(permissions, key2) {
-  if (permissions === void 0) return true;
-  if (permissions.includes(WILDCARD)) return true;
-  return permissions.includes(key2);
+function isNonEmptyTrimmed(value) {
+  return typeof value === "string" && value.trim().length > 0;
 }
-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 normalizeIdentityId(value) {
+  return value.trim();
 }
-function hasPermission(ctx, key2) {
-  if (ctx.permissions === void 0) {
-    return ctx.signedContext !== void 0;
-  }
-  return permissionSatisfies(key2, ctx.permissions);
+function isNonEmptyStringArray(value) {
+  return Array.isArray(value) && value.every((item) => isNonEmptyTrimmed(item));
 }
-function requirePermission(ctx, key2) {
-  if (!hasPermission(ctx, key2)) {
-    throw new FartherShorePermissionError(key2);
+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" } };
 }
-var IDENTITY_HEADER_NAMES = RUNTIME_IDENTITY_HEADER_NAMES;
 
 // 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, "/");
@@ -1661,6 +1679,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(
@@ -1676,11 +1695,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;
@@ -1689,7 +1717,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`
   );
 }
 
@@ -1765,6 +1793,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,
@@ -1775,7 +1804,13 @@ async function verifyRequest(input, deps) {
     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);
@@ -1794,44 +1829,28 @@ 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 !== signedBusinessId) {
-        throw new FartherShoreError(
-          "context_unverified",
-          "X-Fs-Context was minted for a different business 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,
@@ -1841,11 +1860,32 @@ async function verifyRequest(input, deps) {
     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;
@@ -1878,8 +1918,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.15.0".length > 0 ? "0.15.0" : "0.0.0-dev";
-var CONTRACTS_FP = "4b6a36b4cb1f0b68".length > 0 ? "4b6a36b4cb1f0b68" : "0000000000000000";
+var SDK_VERSION = "0.17.0".length > 0 ? "0.17.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1889,11 +1928,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;
@@ -1911,8 +1948,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,
@@ -2037,12 +2074,10 @@ var FartherShore = class {
       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,
@@ -2169,6 +2204,45 @@ 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 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) {
+  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
@@ -2180,7 +2254,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;
     }
@@ -2197,6 +2273,7 @@ async function runMiddleware(fs, options, req, res, next) {
       streamingExempt
     });
     req.fartherShore = ctx;
+    stripFartherShoreHeaders(req);
     next();
   } catch (error) {
     fail(res, error);
@@ -2209,6 +2286,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("?");
@@ -2235,6 +2357,42 @@ function headerValue(headers, name) {
   return value;
 }
 
+// src/core/subject.ts
+var MEMBER_SUBJECT_REQUIRED = RUNTIME_ERROR_CODES.memberSubjectRequired;
+var SERVICE_SUBJECT_REQUIRED = RUNTIME_ERROR_CODES.serviceSubjectRequired;
+function requireMember(ctx) {
+  const subject = ctx.principal?.subject;
+  if (!subject || subject.kind !== "member") {
+    throw new FartherShoreError(
+      MEMBER_SUBJECT_REQUIRED,
+      "this operation requires a member subject (a user session or a personal key)",
+      403
+    );
+  }
+  return subject;
+}
+function requireService(ctx) {
+  const subject = ctx.principal?.subject;
+  if (!subject || subject.kind !== "service") {
+    throw new FartherShoreError(
+      SERVICE_SUBJECT_REQUIRED,
+      "this operation requires a service subject (an org-owned service-account key)",
+      403
+    );
+  }
+  return subject;
+}
+function credentialKind(ctx) {
+  const subject = ctx.principal?.subject;
+  if (!subject) return void 0;
+  if (subject.kind === "service") return "api_key";
+  return subject.via === "session" ? "portal_session" : "api_key";
+}
+function isPortalSession(ctx) {
+  const kind = credentialKind(ctx);
+  return kind === void 0 ? void 0 : kind === "portal_session";
+}
+
 // src/testing/signers.ts
 import { generateKeyPairSync, randomBytes } from "node:crypto";
 var TEST_KID = "fs-runtime-test-2026";
@@ -2265,7 +2423,10 @@ async function makeSignedRequest(spec = {}) {
     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);
@@ -2278,7 +2439,8 @@ async function makeSignedRequest(spec = {}) {
     [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 },
@@ -2296,7 +2458,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",
@@ -2376,12 +2538,15 @@ function mergeHeaders(initHeaders, signedHeaders) {
   return headers;
 }
 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}` },
-    // Business binding: the retained signed-context productId claim MUST equal
-    // the signed request businessId or verifyRequest rejects it as tamper evidence.
-    productId: businessId,
+    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",
@@ -2403,6 +2568,11 @@ 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 ?? "/",
@@ -2414,19 +2584,11 @@ function createPersonaClient(ctx) {
       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.businessId);
-      headers["x-fs-context"] = await signContextToken(
-        claim,
-        ctx.contextSecret,
-        ctx.contextKid
-      );
-    }
-    return headers;
+    return { ...signed.headers };
   }
   function asPersona(name) {
     const persona = resolve(name);
@@ -2504,7 +2666,7 @@ function createDevGateway(options) {
       name: "Dev Backend"
     },
     environment: { id: null, kind: "test" },
-    capabilities: ["gateway_verification", "metering", "health"],
+    operations: ["gateway_verification", "metering", "health"],
     verification: {
       required: options.mode === "simulated",
       jwksUrl: DEV_JWKS_URL,
@@ -2810,8 +2972,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 = {
@@ -2837,7 +3000,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);
@@ -2876,6 +3040,7 @@ function createDevRuntime(options) {
     };
   }
   fs.middleware = middleware;
+  fs.handler = createExpressHandler;
   const devRuntime = {
     fs,
     asPersona: (name) => personaClient.asPersona(name),
@@ -3003,6 +3168,7 @@ var fartherShore = {
     }
     const fs = initFromEnv(options);
     fs.middleware = (mwOptions) => createExpressMiddleware(fs, mwOptions);
+    fs.handler = createExpressHandler;
     return fs;
   }
 };
@@ -3018,7 +3184,6 @@ export {
   FartherShore,
   FartherShoreError,
   FartherShorePermissionError,
-  IDENTITY_HEADER_NAMES,
   JwksClient,
   MAX_BODY_BYTES,
   METERING_PAYLOAD_HEADER,
@@ -3034,7 +3199,7 @@ export {
   RUNTIME_ERROR_CODE_TO_ERROR_CODE,
   RUNTIME_HEADER_NAMES,
   RUNTIME_REPLAY_WINDOW_SECONDS,
-  RUNTIME_TOKEN_CAPABILITIES,
+  RUNTIME_TOKEN_OPERATIONS,
   RUNTIME_TOKEN_PREFIXES,
   STREAMING_EXEMPT_BODY_HASH,
   ShutdownManager,
@@ -3042,18 +3207,24 @@ export {
   buildHealthReport,
   canonicalizeQuery2 as canonicalizeQuery,
   computeMeteringHeaders,
+  createExpressHandler,
   createExpressMiddleware,
   createUsage,
+  credentialKind,
+  decodeContextClaims,
   fartherShore,
   hasPermission,
   hashBody2 as hashBody,
   initFromEnv2 as initFromEnv,
+  isPortalSession,
   nodeSpawn,
-  parsePermissionHeader,
   permissionGrants,
   permissionSatisfies,
+  principalFromContextClaims2 as principalFromContextClaims,
   reportHealth,
+  requireMember,
   requirePermission,
+  requireService,
   runtimeErrorToErrorCode,
   runtimeTokenKind2 as runtimeTokenKind,
   signCanonicalString2 as signCanonicalString,