@farthershore/backend 0.12.0 → 0.14.0

package/dist/testing/index.js

@@ -0,0 +1,2906 @@
+import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/reflect/route-canon.ts
+import { createHash } from "node:crypto";
+function normalizeSegment(seg) {
+  if (seg === "**") return "{__fs_rest}";
+  if (seg === "*") return "{splat}";
+  if (seg.startsWith(":")) return `{${seg.slice(1)}}`;
+  if (seg.startsWith("[") && seg.endsWith("]")) return `{${seg.slice(1, -1)}}`;
+  return seg;
+}
+function normalizePath(path) {
+  if (path === "/" || path === "") return "/";
+  const lead = path.startsWith("/");
+  const out = path.split("/").filter((s) => s.length > 0).map(normalizeSegment).join("/");
+  return lead ? `/${out}` : out;
+}
+function pathSpecificity(path) {
+  return path.split("/").filter(
+    (s) => s.length > 0 && !s.startsWith("{") && s !== "*" && s !== "**"
+  ).length;
+}
+function canonicalSort(routes) {
+  return [...routes].sort(
+    (a, b) => pathSpecificity(b.path) - pathSpecificity(a.path) || a.method.localeCompare(b.method) || a.path.localeCompare(b.path)
+  );
+}
+function surfaceHash(routes) {
+  const canonical = canonicalSort(routes).map(
+    (r) => `${r.method.toUpperCase()} ${r.path}`
+  );
+  const h = createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+  return `sha256:${h}`;
+}
+var init_route_canon = __esm({
+  "src/reflect/route-canon.ts"() {
+    "use strict";
+  }
+});
+
+// src/reflect/index.ts
+var reflect_exports = {};
+__export(reflect_exports, {
+  reflectRoutes: () => reflectRoutes,
+  reflectRoutesDetailed: () => reflectRoutesDetailed
+});
+function methodsOf(route) {
+  const out = /* @__PURE__ */ new Set();
+  if (route.methods) {
+    for (const [m, on] of Object.entries(route.methods))
+      if (on) out.add(m.toUpperCase());
+  }
+  for (const s of route.stack ?? []) {
+    if (typeof s.method === "string") out.add(s.method.toUpperCase());
+  }
+  if (out.has("GET")) out.delete("HEAD");
+  return [...out].filter((m) => VALID_METHODS.has(m));
+}
+function rootStack(app) {
+  const a = app;
+  return a?.router?.stack ?? a?._router?.stack;
+}
+function prefixFromRegexp(re) {
+  if (!re) return void 0;
+  let s = re.source;
+  if (s === "^\\/?$" || s === "^\\/") return "";
+  s = s.replace(/^\^/, "").replace(/\\\/\?\(\?=\\\/\|\$\)$/, "").replace(/\(\?=\\\/\|\$\)$/, "").replace(/\\\/\?$/, "").replace(/\$$/, "");
+  s = s.replace(/\\\//g, "/");
+  if (/[()?:*+\[\]|]/.test(s)) return void 0;
+  return s.startsWith("/") ? s : `/${s}`;
+}
+function walk(stack, prefix, out, counters) {
+  for (const layer of stack) {
+    if (layer.route && typeof layer.route.path === "string") {
+      const path = normalizePath(`${prefix}${layer.route.path}`);
+      for (const method of methodsOf(layer.route)) {
+        out.push({ method, path });
+      }
+    } else if (layer.handle?.stack && Array.isArray(layer.handle.stack)) {
+      const sub = prefixFromRegexp(layer.regexp);
+      if (sub === void 0 && layer.name === "router") {
+        counters.unreflectable += layer.handle.stack.filter(
+          (l) => l.route
+        ).length;
+        continue;
+      }
+      walk(layer.handle.stack, `${prefix}${sub ?? ""}`, out, counters);
+    }
+  }
+}
+function reflectRoutesDetailed(app, _opts) {
+  const stack = rootStack(app);
+  if (!stack) return { routes: [], unreflectable: 0 };
+  const raw = [];
+  const counters = { unreflectable: 0 };
+  walk(stack, "", raw, counters);
+  const seen = /* @__PURE__ */ new Set();
+  const routes = [];
+  for (const r of raw) {
+    const key2 = `${r.method} ${r.path}`;
+    if (seen.has(key2)) continue;
+    seen.add(key2);
+    routes.push(r);
+  }
+  return { routes, unreflectable: counters.unreflectable };
+}
+function reflectRoutes(app, opts) {
+  return reflectRoutesDetailed(app, opts).routes;
+}
+var VALID_METHODS;
+var init_reflect = __esm({
+  "src/reflect/index.ts"() {
+    "use strict";
+    init_route_canon();
+    VALID_METHODS = /* @__PURE__ */ new Set([
+      "GET",
+      "HEAD",
+      "POST",
+      "PUT",
+      "PATCH",
+      "DELETE",
+      "OPTIONS"
+    ]);
+  }
+});
+
+// src/reflect/reconcile.ts
+var reconcile_exports = {};
+__export(reconcile_exports, {
+  reconcileOnStartup: () => reconcileOnStartup
+});
+function key(r) {
+  return `${r.method.toUpperCase()} ${r.path}`;
+}
+async function reconcileOnStartup(args) {
+  const { reflected, bootstrap, report } = args;
+  const reflectedHash = surfaceHash(reflected);
+  const lockVersion = bootstrap.lock?.lockVersion ?? 0;
+  const inSync = bootstrap.lock?.surfaceHash === reflectedHash;
+  const result = {
+    inSync,
+    reportedDrift: false,
+    confirmedRouteIds: []
+  };
+  const servedKeys = new Set(reflected.map(key));
+  const confirmedRouteIds = (bootstrap.routes ?? []).filter(
+    (r) => r.pending === true && servedKeys.has(key(r)) && typeof r.id === "string"
+  ).map((r) => r.id);
+  try {
+    if (confirmedRouteIds.length > 0) {
+      await report.confirmServed({
+        backendId: bootstrap.backendId,
+        lockVersion,
+        servedRouteIds: confirmedRouteIds
+      });
+      result.confirmedRouteIds = confirmedRouteIds;
+    }
+    if (!inSync) {
+      await report.reportDrift({
+        backendId: bootstrap.backendId,
+        lockVersion,
+        reflectedSurfaceHash: reflectedHash,
+        routes: reflected.map((r) => ({ method: r.method, path: r.path }))
+      });
+      result.reportedDrift = true;
+    }
+  } catch (err) {
+    result.reportError = err instanceof Error ? err.message : String(err);
+  }
+  return result;
+}
+var init_reconcile = __esm({
+  "src/reflect/reconcile.ts"() {
+    "use strict";
+    init_route_canon();
+  }
+});
+
+// src/testing/signers.ts
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+
+// src/generated/runtime-contract.ts
+var RUNTIME_BODY_HASH_CONTRACT = {
+  algorithm: "SHA-256",
+  encoding: "hex-lower",
+  source: "raw-request-bytes",
+  emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  maxBodyBytes: 10485760,
+  streamingExemptToken: "STREAM",
+  streamingExemptContentTypes: [
+    "text/event-stream",
+    "application/octet-stream",
+    "multipart/form-data"
+  ],
+  overMaxStatus: 413
+};
+var RUNTIME_ERROR_CODES = {
+  missingSignature: "missing_signature",
+  malformedSignature: "malformed_signature",
+  unknownKeyId: "unknown_key_id",
+  jwksUnavailable: "jwks_unavailable",
+  badSignature: "bad_signature",
+  bodyHashMismatch: "body_hash_mismatch",
+  routeMismatch: "route_mismatch",
+  clockSkew: "clock_skew",
+  expiredSignature: "expired_signature",
+  replayedNonce: "replayed_nonce",
+  bodyTooLarge: "body_too_large",
+  environmentMismatch: "environment_mismatch",
+  missingToken: "missing_token",
+  invalidToken: "invalid_token",
+  contextUnverified: "context_unverified"
+};
+var RUNTIME_RESPONSE_METERING_CONTRACT = {
+  headers: {
+    payload: "x-fs-metering",
+    signature: "x-fs-metering-sig",
+    token: "x-fs-metering-token"
+  },
+  token: {
+    environmentVariable: "FS_RUNTIME_TOKEN",
+    presentation: "x-fs-metering-token",
+    storage: "sha256-hash-only"
+  },
+  signature: {
+    algorithm: "HMAC-SHA256",
+    encoding: "base64url",
+    input: "payload-json",
+    secret: "presented-runtime-token"
+  },
+  payload: {
+    method: "string",
+    path: "string",
+    rawDimsUnits: "Record<string, number>",
+    measureContext: "Record<string, unknown>?",
+    creditUnitsConsumed: "Record<string, number>?"
+  },
+  errors: {
+    missingToken: "missing_token",
+    invalidMeterKey: "invalid_meter_key",
+    invalidMeterValue: "invalid_meter_value"
+  },
+  httpAdapter: {
+    input: "Request",
+    output: "Response",
+    networkCalls: false,
+    preserves: ["body", "headers", "status", "statusText"],
+    gatewayStripsInternalHeaders: true
+  }
+};
+
+// src/runtime-types.ts
+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",
+  [RUNTIME_ERROR_CODES.unknownKeyId]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.badSignature]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.expiredSignature]: "UNAUTHORIZED",
+  // Replay / freshness faults → UNAUTHORIZED (401).
+  [RUNTIME_ERROR_CODES.clockSkew]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.replayedNonce]: "UNAUTHORIZED",
+  // Request/route binding faults → UNAUTHORIZED (401, fail-closed).
+  [RUNTIME_ERROR_CODES.bodyHashMismatch]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.routeMismatch]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.environmentMismatch]: "UNAUTHORIZED",
+  // JWKS fetch unavailable — dependency fault (still 401 to the client), but
+  // 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"
+};
+var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
+var RUNTIME_TOKEN_PREFIXES = {
+  live: "fsrt_live_",
+  test: "fsrt_test_"
+};
+var RUNTIME_HEADER_NAMES = {
+  signature: "x-fs-signature",
+  keyId: "x-fs-key-id",
+  requestId: "x-fs-request-id",
+  timestamp: "x-fs-timestamp",
+  productId: "x-fs-product-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";
+var STREAMING_EXEMPT_BODY_HASH = "STREAM";
+var MAX_BODY_BYTES = 10 * 1024 * 1024;
+
+// ../contracts/dist/runtime.js
+var FS_RUNTIME_TOKEN_ENV2 = "FS_RUNTIME_TOKEN";
+var RUNTIME_TOKEN_PREFIXES2 = {
+  live: "fsrt_live_",
+  test: "fsrt_test_"
+};
+function runtimeTokenKind(token) {
+  if (token.startsWith(RUNTIME_TOKEN_PREFIXES2.live))
+    return "live";
+  if (token.startsWith(RUNTIME_TOKEN_PREFIXES2.test))
+    return "test";
+  return null;
+}
+var RESPONSE_METERING_HEADER_NAMES = {
+  payload: "x-fs-metering",
+  signature: "x-fs-metering-sig",
+  token: "x-fs-metering-token"
+};
+var RESPONSE_METERING_TOKEN_CONTRACT = {
+  environmentVariable: FS_RUNTIME_TOKEN_ENV2,
+  presentation: RESPONSE_METERING_HEADER_NAMES.token,
+  storage: "sha256-hash-only"
+};
+var MAX_BODY_BYTES2 = 10 * 1024 * 1024;
+async function hashBody(body) {
+  const bytes = new Uint8Array(body);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return toHex(new Uint8Array(digest));
+}
+var CANONICAL_SIGNING_FIELDS = [
+  "method",
+  "path",
+  "query",
+  "body-hash",
+  "request-id",
+  "timestamp",
+  "product-id",
+  "backend-id",
+  "route-id",
+  "policy-version"
+];
+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("&");
+}
+function buildCanonicalSigningString(input) {
+  const values = {
+    method: input.method.toUpperCase(),
+    path: input.path,
+    query: canonicalizeQuery(input.query),
+    "body-hash": input.bodyHash,
+    "request-id": input.requestId,
+    timestamp: String(input.timestamp),
+    "product-id": input.productId,
+    "backend-id": input.backendId,
+    "route-id": input.routeId,
+    "policy-version": input.policyVersion
+  };
+  return CANONICAL_SIGNING_FIELDS.map((field) => `${field}${CANONICAL_KV_SEPARATOR}${values[field]}`).join(CANONICAL_FIELD_SEPARATOR);
+}
+var ED25519_ALGORITHM = "Ed25519";
+async function importEd25519PrivateKey(jwk) {
+  return crypto.subtle.importKey("jwk", { ...jwk, alg: void 0 }, { name: ED25519_ALGORITHM }, false, ["sign"]);
+}
+async function importEd25519PublicKey(jwk) {
+  return crypto.subtle.importKey("jwk", { ...jwk, alg: void 0 }, { name: ED25519_ALGORITHM }, false, ["verify"]);
+}
+async function signCanonicalString(canonical, privateJwk) {
+  const key2 = await importEd25519PrivateKey(privateJwk);
+  const sig = await crypto.subtle.sign(ED25519_ALGORITHM, key2, new TextEncoder().encode(canonical));
+  return base64UrlEncode(new Uint8Array(sig));
+}
+async function verifyCanonicalSignature(canonical, signatureB64Url, publicJwk) {
+  const key2 = await importEd25519PublicKey(publicJwk);
+  return crypto.subtle.verify(ED25519_ALGORITHM, key2, base64UrlDecode(signatureB64Url), new TextEncoder().encode(canonical));
+}
+function toHex(bytes) {
+  let out = "";
+  for (const b of bytes)
+    out += b.toString(16).padStart(2, "0");
+  return out;
+}
+function base64UrlEncode(bytes) {
+  let binary = "";
+  for (const b of bytes)
+    binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(value) {
+  const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1)
+    bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+
+// src/runtime-signing.ts
+var hashBody2 = hashBody;
+var buildCanonicalSigningString2 = buildCanonicalSigningString;
+var signCanonicalString2 = signCanonicalString;
+var verifyCanonicalSignature2 = verifyCanonicalSignature;
+var runtimeTokenKind2 = runtimeTokenKind;
+
+// src/core/errors.ts
+var FartherShoreError = class extends Error {
+  code;
+  status;
+  /** Present only when this error is a self-minted plan-limit deny (rare; the
+   *  backend usually relays the gateway's descriptor-bearing deny instead). */
+  limitDescriptor;
+  constructor(code, message, status, limitDescriptor) {
+    super(message);
+    this.name = "FartherShoreError";
+    this.code = code;
+    this.status = status ?? statusForCode(code);
+    if (limitDescriptor !== void 0) {
+      this.limitDescriptor = limitDescriptor;
+    }
+  }
+};
+function statusForCode(code) {
+  return code === "body_too_large" ? 413 : 401;
+}
+
+// src/core/jwks.ts
+var DEFAULT_CACHE_TTL_MS = 5 * 6e4;
+var DEFAULT_NEGATIVE_CACHE_MS = 3e4;
+var MAX_NEGATIVE_KIDS = 1e3;
+var JwksClient = class {
+  jwksUrl;
+  fetchImpl;
+  cacheTtlMs;
+  negativeCacheMs;
+  now;
+  keysByKid = /* @__PURE__ */ new Map();
+  fetchedAt = 0;
+  hasFetchedOnce = false;
+  inflight = null;
+  negativeKids = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.jwksUrl = options.jwksUrl;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    this.negativeCacheMs = options.negativeCacheMs ?? DEFAULT_NEGATIVE_CACHE_MS;
+    this.now = options.now ?? (() => Date.now());
+  }
+  /**
+   * Resolve a public JWK for `kid`, fail-closed. Throws FartherShoreError with
+   * `jwks_unavailable` (cold cache + fetch failed) or `unknown_key_id`.
+   */
+  async getKey(kid) {
+    const cached = this.keysByKid.get(kid);
+    if (cached && !this.isStale()) return cached;
+    const negAt = this.negativeKids.get(kid);
+    if (negAt !== void 0 && this.now() - negAt < this.negativeCacheMs) {
+      const warm = this.keysByKid.get(kid);
+      if (warm) return warm;
+      throw new FartherShoreError(
+        "unknown_key_id",
+        `signing key '${kid}' is not present in the JWKS`
+      );
+    }
+    await this.refresh();
+    const key2 = this.keysByKid.get(kid);
+    if (key2) {
+      this.negativeKids.delete(kid);
+      return key2;
+    }
+    this.rememberMissingKid(kid);
+    throw new FartherShoreError(
+      "unknown_key_id",
+      `signing key '${kid}' is not present in the JWKS`
+    );
+  }
+  /** Record a confirmed-missing kid, evicting the oldest if at capacity. */
+  rememberMissingKid(kid) {
+    if (!this.negativeKids.has(kid)) {
+      while (this.negativeKids.size >= MAX_NEGATIVE_KIDS) {
+        const oldest = this.negativeKids.keys().next().value;
+        if (oldest === void 0) break;
+        this.negativeKids.delete(oldest);
+      }
+    }
+    this.negativeKids.set(kid, this.now());
+  }
+  isStale() {
+    return this.now() - this.fetchedAt >= this.cacheTtlMs;
+  }
+  /** Single-flight refresh: concurrent callers share one fetch. */
+  async refresh() {
+    if (this.inflight) return this.inflight;
+    this.inflight = this.doFetch().finally(() => {
+      this.inflight = null;
+    });
+    return this.inflight;
+  }
+  async doFetch() {
+    let response;
+    try {
+      response = await this.fetchImpl(this.jwksUrl, {
+        headers: { accept: "application/json" }
+      });
+    } catch (cause) {
+      this.failOnColdCache(cause);
+      return;
+    }
+    if (!response.ok) {
+      this.failOnColdCache(
+        new Error(`JWKS endpoint returned HTTP ${response.status}`)
+      );
+      return;
+    }
+    let doc;
+    try {
+      doc = await response.json();
+    } catch (cause) {
+      this.failOnColdCache(cause);
+      return;
+    }
+    const next = /* @__PURE__ */ new Map();
+    for (const key2 of doc.keys ?? []) {
+      if (typeof key2.kid === "string") next.set(key2.kid, key2);
+    }
+    this.keysByKid = next;
+    this.fetchedAt = this.now();
+    this.hasFetchedOnce = true;
+    this.negativeKids.clear();
+  }
+  /**
+   * Stale-while-revalidate: with a warm cache, swallow the refresh failure and
+   * keep serving the last-known keys. With a COLD cache, fail closed.
+   */
+  failOnColdCache(cause) {
+    if (this.hasFetchedOnce) return;
+    throw new FartherShoreError(
+      "jwks_unavailable",
+      `JWKS unavailable on a cold cache: ${stringifyCause(cause)}`
+    );
+  }
+};
+function stringifyCause(cause) {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+
+// src/testing/signers.ts
+var TEST_KID = "fs-runtime-test-2026";
+var TEST_PRIVATE_JWK = {
+  kty: "OKP",
+  crv: "Ed25519",
+  d: "nWGxne_9WmC6hEr0kuwsxERJxWl7MmkZcDusAxyuf2A",
+  x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
+};
+var TEST_PUBLIC_JWK = {
+  kty: "OKP",
+  crv: "Ed25519",
+  x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
+};
+var TEST_CONTEXT_SECRET = "fs-dev-context-secret-2026";
+var TEST_CONTEXT_KID = "fs-context-test-2026";
+async function makeSignedRequest(spec = {}) {
+  const method = spec.method ?? "POST";
+  const path = spec.path ?? "/v1/chat/completions";
+  const query = spec.query ?? "";
+  const body = spec.body ?? null;
+  const streamingExempt = spec.streamingExempt ?? false;
+  const privateJwk = spec.privateJwk ?? TEST_PRIVATE_JWK;
+  const kid = spec.kid ?? TEST_KID;
+  const bodyHash = streamingExempt ? "STREAM" : body && body.byteLength > 0 ? await hashBody2(body) : EMPTY_BODY_SHA256;
+  const claim = {
+    method,
+    path,
+    query,
+    bodyHash,
+    requestId: spec.requestId ?? `req_${cryptoRandom()}`,
+    timestamp: spec.timestamp ?? Math.floor(Date.now() / 1e3),
+    productId: spec.productId ?? "prod_test",
+    backendId: spec.backendId ?? "be_test",
+    routeId: spec.routeId ?? "route_test",
+    policyVersion: spec.policyVersion ?? "pv_1"
+  };
+  const canonical = buildCanonicalSigningString2(claim);
+  const signature = await signCanonicalString2(canonical, privateJwk);
+  const headers = {
+    [RUNTIME_HEADER_NAMES.signature]: signature,
+    [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.backendId]: claim.backendId,
+    [RUNTIME_HEADER_NAMES.routeId]: claim.routeId,
+    [RUNTIME_HEADER_NAMES.policyVersion]: claim.policyVersion,
+    [RUNTIME_HEADER_NAMES.bodyHash]: claim.bodyHash
+  };
+  return {
+    input: { method, path, query, body, streamingExempt },
+    claim,
+    headers
+  };
+}
+function memoryJwks(keys = [
+  { ...TEST_PUBLIC_JWK, kid: TEST_KID }
+]) {
+  const fetchImpl = () => Promise.resolve(
+    new Response(JSON.stringify({ keys }), {
+      status: 200,
+      headers: { "content-type": "application/json" }
+    })
+  );
+  return new JwksClient({
+    jwksUrl: "https://core.test/.well-known/jwks.json",
+    fetchImpl
+  });
+}
+function unreachableJwks() {
+  const fetchImpl = () => Promise.reject(new Error("network down"));
+  return new JwksClient({
+    jwksUrl: "https://core.test/.well-known/jwks.json",
+    fetchImpl
+  });
+}
+function base64urlEncodeBytes(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlEncodeJson(value) {
+  return base64urlEncodeBytes(new TextEncoder().encode(JSON.stringify(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 signingInput = `${header}.${payload}`;
+  const key2 = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key2,
+    new TextEncoder().encode(signingInput)
+  );
+  return `${signingInput}.${base64urlEncodeBytes(new Uint8Array(signature))}`;
+}
+function generateDevSignerKeys() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const privateJwk = privateKey.export({ format: "jwk" });
+  const publicJwk = publicKey.export({ format: "jwk" });
+  const kid = `fs-dev-${randomBytes(6).toString("hex")}`;
+  const contextKid = `fs-dev-ctx-${randomBytes(6).toString("hex")}`;
+  const contextSecret = randomBytes(32).toString("base64url");
+  const runtimeToken = `${RUNTIME_TOKEN_PREFIXES.test}${randomBytes(24).toString("base64url")}`;
+  return {
+    kid,
+    privateJwk,
+    publicJwk,
+    contextKid,
+    contextSecret,
+    runtimeToken
+  };
+}
+function cryptoRandom() {
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+}
+
+// src/testing/personas.ts
+function definePersona(def) {
+  return def;
+}
+var DEFAULT_PERSONAS = {
+  owner: definePersona({
+    name: "owner",
+    permissions: ["*"],
+    roles: ["owner"],
+    subjectKey: "owner"
+  }),
+  admin: definePersona({
+    name: "admin",
+    permissions: ["*"],
+    roles: ["admin"],
+    subjectKey: "admin"
+  }),
+  member: definePersona({
+    name: "member",
+    permissions: [],
+    roles: ["member"],
+    subjectKey: "member"
+  }),
+  anonymous: definePersona({ name: "anonymous", anonymous: true })
+};
+function normalizeBody(body) {
+  if (body === null || body === void 0) return null;
+  if (typeof body === "string") return new TextEncoder().encode(body);
+  if (body instanceof Uint8Array) return body;
+  if (body instanceof ArrayBuffer) return new Uint8Array(body);
+  return null;
+}
+function normalizeMethod(method) {
+  return (method ?? "GET").toUpperCase();
+}
+function mergeHeaders(initHeaders, signedHeaders) {
+  const headers = new Headers(initHeaders);
+  for (const [name, value] of Object.entries(signedHeaders)) {
+    headers.set(name, value);
+  }
+  return headers;
+}
+function buildContextClaim(persona, productId) {
+  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,
+    compiledPlanId: persona.compiledPlanId ?? "plan_dev",
+    subscriptionId: persona.subscriptionId ?? "sub_dev",
+    subscriberId: persona.subscriberId ?? "subscriber_dev",
+    environmentId: persona.environmentId ?? null,
+    subjectKey: persona.subjectKey ?? persona.name,
+    ...persona.permissions !== void 0 ? { permissions: persona.permissions } : {},
+    ...persona.roles !== void 0 ? { roles: persona.roles } : {}
+  };
+}
+function createPersonaClient(ctx) {
+  function resolve(name) {
+    const persona = ctx.personas.get(name);
+    if (!persona) {
+      throw new Error(
+        `unknown persona "${name}" (known: ${[...ctx.personas.keys()].join(", ")})`
+      );
+    }
+    return persona;
+  }
+  async function buildHeaders(persona, spec) {
+    const method = normalizeMethod(spec.method);
+    const signed = await makeSignedRequest({
+      method,
+      path: spec.path ?? "/",
+      query: spec.query ?? "",
+      body: spec.body ?? null,
+      streamingExempt: spec.streamingExempt ?? false,
+      productId: ctx.productId,
+      backendId: ctx.backendId,
+      routeId: spec.routeId ?? "",
+      privateJwk: ctx.keys.privateJwk,
+      kid: ctx.keys.kid,
+      ...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;
+  }
+  function asPersona(name) {
+    const persona = resolve(name);
+    return {
+      persona: name,
+      headers: (spec = {}) => buildHeaders(persona, spec),
+      async fetch(url, init = {}) {
+        const parsed = new URL(url);
+        const method = normalizeMethod(init.method);
+        const headers = await buildHeaders(persona, {
+          method,
+          path: parsed.pathname,
+          query: parsed.search.replace(/^\?/, ""),
+          body: normalizeBody(init.body)
+        });
+        const doFetch = ctx.fetchImpl ?? globalThis.fetch;
+        return doFetch(url, {
+          ...init,
+          method,
+          headers: mergeHeaders(init.headers, headers)
+        });
+      },
+      async inject(req, spec = {}) {
+        const rawUrl = spec.path ?? req.url ?? req.path ?? "/";
+        const qIndex = rawUrl.indexOf("?");
+        const path = qIndex === -1 ? rawUrl : rawUrl.slice(0, qIndex);
+        const query = spec.query ?? (qIndex === -1 ? "" : rawUrl.slice(qIndex + 1));
+        const method = normalizeMethod(spec.method ?? req.method);
+        const headers = await buildHeaders(persona, {
+          method,
+          path,
+          query,
+          body: spec.body ?? null,
+          ...spec.streamingExempt !== void 0 ? { streamingExempt: spec.streamingExempt } : {},
+          ...spec.routeId ? { routeId: spec.routeId } : {}
+        });
+        for (const [field, value] of Object.entries(headers)) {
+          req.set(field, value);
+        }
+        return req;
+      }
+    };
+  }
+  return { asPersona, personas: ctx.personas };
+}
+function buildPersonaMap(overrides) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [name, def] of Object.entries(DEFAULT_PERSONAS)) {
+    map.set(name, def);
+  }
+  if (Array.isArray(overrides)) {
+    for (const def of overrides) map.set(def.name, def);
+  } else if (overrides) {
+    for (const [name, def] of Object.entries(overrides)) {
+      map.set(name, { ...def, name });
+    }
+  }
+  return map;
+}
+var CONTEXT_HEADER_NAME = "x-fs-context";
+var SIGNED_HEADER_NAMES = RUNTIME_HEADER_NAMES;
+
+// src/testing/devGateway.ts
+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 backendId = options.backendId ?? "be_dev";
+  const meterEvents = [];
+  const reportUsageEvents = [];
+  const bootstrap = {
+    product: { id: productId, slug: options.productSlug ?? "dev-product" },
+    backend: {
+      id: backendId,
+      slug: options.backendSlug ?? "dev-backend",
+      name: "Dev Backend"
+    },
+    environment: { id: null, kind: "test" },
+    capabilities: ["gateway_verification", "metering", "health"],
+    verification: {
+      required: options.mode === "simulated",
+      jwksUrl: DEV_JWKS_URL,
+      clockSkewSeconds: 5,
+      replayWindowSeconds: 300,
+      headerNames: RUNTIME_HEADER_NAMES
+    },
+    metering: {
+      enabled: true,
+      endpoint: DEV_METERING_ENDPOINT,
+      credential: options.keys.runtimeToken,
+      allowedMeters: [],
+      allowedRoutes: [],
+      perEventMax: 0
+    },
+    transport: { mode: "direct", runner: null },
+    routes: (options.routeIds ?? []).map((id) => ({
+      id,
+      method: "POST",
+      path: `/${id}`,
+      backendId
+    })),
+    policyVersion: "pv_dev",
+    refreshAfterSeconds: 3600
+  };
+  const jwksDoc = {
+    keys: [{ ...options.keys.publicJwk, kid: options.keys.kid }]
+  };
+  const fetchImpl = async (input, init) => {
+    const url = String(
+      typeof input === "string" || input instanceof URL ? input : input.url
+    );
+    if (url.includes("/v1/runtime/bootstrap")) {
+      return json(bootstrap);
+    }
+    if (url.includes("/.well-known/jwks.json") || url.includes("jwks")) {
+      return json(jwksDoc);
+    }
+    if (url.includes("/v1/metering/events")) {
+      const event = await readJsonBody(init, input);
+      if (event && "meters" in event) {
+        reportUsageEvents.push(event);
+        options.onReportUsage?.(event);
+      } else if (event) {
+        meterEvents.push(event);
+        options.onMeterEvent?.(event);
+      }
+      return json({ ok: true });
+    }
+    if (url.includes("/v1/runtime/health") || url.includes("/v1/runtime/drift")) {
+      return json({ ok: true });
+    }
+    return new Response(JSON.stringify({ error: "not_found" }), {
+      status: 404,
+      headers: { "content-type": "application/json" }
+    });
+  };
+  return {
+    fetchImpl,
+    bootstrap,
+    meterEvents,
+    reportUsageEvents,
+    productId,
+    backendId,
+    jwksUrl: DEV_JWKS_URL
+  };
+}
+function json(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" }
+  });
+}
+async function readJsonBody(init, input) {
+  try {
+    if (init?.body && typeof init.body === "string") {
+      return JSON.parse(init.body);
+    }
+    if (input instanceof Request) {
+      return await input.clone().json();
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+// src/testing/devRuntime.ts
+import { appendFileSync, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+
+// src/core/bootstrap.ts
+var BOOTSTRAP_PATH = "/v1/runtime/bootstrap";
+var DEFAULT_MIN_REFRESH_SECONDS = 30;
+var BootstrapClient = class {
+  runtimeToken;
+  endpoint;
+  request;
+  fetchImpl;
+  now;
+  minRefreshSeconds;
+  cached = null;
+  fetchedAt = 0;
+  refreshAfterMs = 0;
+  inflight = null;
+  constructor(options) {
+    if (!options.runtimeToken) {
+      throw new FartherShoreError(
+        "missing_token",
+        `${FS_RUNTIME_TOKEN_ENV} is required to bootstrap the Farther Shore backend SDK`
+      );
+    }
+    if (runtimeTokenKind2(options.runtimeToken) === null) {
+      throw new FartherShoreError(
+        "invalid_token",
+        `${FS_RUNTIME_TOKEN_ENV} must start with fsrt_live_ or fsrt_test_`
+      );
+    }
+    this.runtimeToken = options.runtimeToken;
+    this.endpoint = joinUrl(options.coreUrl, BOOTSTRAP_PATH);
+    this.request = options.request ?? {};
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.now = options.now ?? (() => Date.now());
+    this.minRefreshSeconds = options.minRefreshSeconds ?? DEFAULT_MIN_REFRESH_SECONDS;
+  }
+  /** Cached config when fresh; otherwise refreshes. */
+  async get() {
+    if (this.cached && !this.isStale()) return this.cached;
+    return this.refresh();
+  }
+  /** Force a network refresh (single-flight). */
+  async refresh() {
+    if (this.inflight) return this.inflight;
+    this.inflight = this.doBootstrap().finally(() => {
+      this.inflight = null;
+    });
+    return this.inflight;
+  }
+  /** Last cached value without triggering a refresh (null until bootstrapped). */
+  peek() {
+    return this.cached;
+  }
+  isStale() {
+    return this.now() - this.fetchedAt >= this.refreshAfterMs;
+  }
+  async doBootstrap() {
+    let response;
+    try {
+      response = await this.fetchImpl(this.endpoint, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${this.runtimeToken}`,
+          "content-type": "application/json",
+          accept: "application/json"
+        },
+        body: JSON.stringify(this.request)
+      });
+    } catch (cause) {
+      if (this.cached) return this.cached;
+      throw new FartherShoreError(
+        "jwks_unavailable",
+        `bootstrap request failed: ${stringify(cause)}`
+      );
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new FartherShoreError(
+        "invalid_token",
+        `${FS_RUNTIME_TOKEN_ENV} was rejected by core (HTTP ${response.status})`
+      );
+    }
+    if (!response.ok) {
+      if (this.cached) return this.cached;
+      throw new FartherShoreError(
+        "jwks_unavailable",
+        `bootstrap returned HTTP ${response.status}`
+      );
+    }
+    const body = await response.json();
+    this.cached = body;
+    this.fetchedAt = this.now();
+    const refreshSeconds = Math.max(
+      this.minRefreshSeconds,
+      body.refreshAfterSeconds || this.minRefreshSeconds
+    );
+    this.refreshAfterMs = refreshSeconds * 1e3;
+    return body;
+  }
+};
+function joinUrl(base, path) {
+  return `${base.replace(/\/+$/, "")}${path}`;
+}
+function stringify(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+// src/core/health.ts
+function buildHealthReport(snapshot) {
+  return {
+    runtimeToken: snapshot.runtimeToken,
+    bootstrap: snapshot.bootstrap,
+    tunnel: snapshot.tunnel,
+    verification: snapshot.verification,
+    metering: snapshot.metering
+  };
+}
+var HEALTH_PATH = "/v1/runtime/health";
+async function reportHealth(options) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const endpoint = `${options.coreUrl.replace(/\/+$/, "")}${HEALTH_PATH}`;
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${options.runtimeToken}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        status: options.status,
+        ...options.instanceId ? { instanceId: options.instanceId } : {}
+      })
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+// src/core/backoff.ts
+function computeBackoff(attempt, options) {
+  const { baseMs, maxMs, jitter = "equal", random = Math.random } = options;
+  const exponent = Math.max(0, attempt - 1);
+  const cap = Math.min(baseMs * 2 ** exponent, maxMs);
+  switch (jitter) {
+    case "none":
+      return cap;
+    case "full":
+      return random() * cap;
+    case "equal":
+    default:
+      return cap / 2 + random() * (cap / 2);
+  }
+}
+
+// src/core/metering.ts
+var METER_KEY_RE = /^[a-z0-9_]{1,64}$/;
+var DEFAULT_BASE_DELAY_MS = 200;
+var DEFAULT_MAX_DELAY_MS = 1e4;
+function isTransientStatus(status) {
+  return status === 429 || status >= 500;
+}
+function retryAfterMs(headers) {
+  const raw = headers.get("retry-after");
+  if (raw === null) return null;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) return null;
+  const secs = Number(trimmed);
+  return Number.isFinite(secs) ? secs * 1e3 : null;
+}
+var DEFAULT_MAX_RETRIES = 3;
+var MeteringClient = class {
+  config;
+  endpoint;
+  productId;
+  backendId;
+  fetchImpl;
+  maxRetries;
+  baseDelayMs;
+  maxDelayMs;
+  sleep;
+  random;
+  newId;
+  now;
+  buffer = [];
+  constructor(options) {
+    this.config = options.config;
+    this.endpoint = resolveEndpoint(options.config.endpoint, options.coreUrl);
+    this.productId = options.productId;
+    this.backendId = options.backendId;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    this.maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.random = options.random ?? Math.random;
+    this.newId = options.newId ?? (() => crypto.randomUUID());
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  /**
+   * Record `qty` of `meter`. Enforces meter-key shape, non-negative finite qty,
+   * the bootstrap allowedMeters/allowedRoutes scope, and the per-event sanity
+   * max, then enqueues and flushes (best-effort; failures stay buffered).
+   */
+  async meter(meter, qty, options = {}) {
+    if (!this.config.enabled) {
+      throw new FartherShoreError(
+        "invalid_token",
+        "metering is not enabled for this runtime token"
+      );
+    }
+    if (!METER_KEY_RE.test(meter)) {
+      throw new FartherShoreError(
+        "invalid_token",
+        `meter key '${meter}' must be lowercase alphanumeric with underscores`
+      );
+    }
+    if (!Number.isFinite(qty) || qty < 0) {
+      throw new FartherShoreError(
+        "invalid_token",
+        `meter '${meter}' qty must be a non-negative finite number`
+      );
+    }
+    if (this.config.allowedMeters.length > 0 && !this.config.allowedMeters.includes(meter)) {
+      throw new FartherShoreError(
+        "invalid_token",
+        `meter '${meter}' is not in the token's allowedMeters`
+      );
+    }
+    if (this.config.allowedRoutes.length > 0) {
+      if (!options.routeId) {
+        throw new FartherShoreError(
+          "invalid_token",
+          "routeId is required because this runtime token is route-scoped"
+        );
+      }
+      if (!this.config.allowedRoutes.includes(options.routeId)) {
+        throw new FartherShoreError(
+          "invalid_token",
+          `route '${options.routeId}' is not in the token's allowedRoutes`
+        );
+      }
+    }
+    if (this.config.perEventMax > 0 && qty > this.config.perEventMax) {
+      throw new FartherShoreError(
+        "invalid_token",
+        `meter '${meter}' qty ${qty} exceeds the per-event max ${this.config.perEventMax}`
+      );
+    }
+    const event = {
+      event_id: options.eventId ?? this.newId(),
+      product_id: this.productId,
+      backend_id: this.backendId,
+      meter,
+      qty,
+      timestamp: options.timestamp ?? this.now().toISOString(),
+      ...options.routeId ? { route_id: options.routeId } : {},
+      ...options.requestId ? { request_id: options.requestId } : {}
+    };
+    this.buffer.push(event);
+    await this.flush();
+  }
+  /** Drain the buffer. Events that fail all retries stay buffered (at-least-once). */
+  async flush() {
+    const pending = this.buffer.splice(0, this.buffer.length);
+    const stillPending = [];
+    for (const event of pending) {
+      const sent = await this.sendWithRetry(event);
+      if (!sent) stillPending.push(event);
+    }
+    if (stillPending.length > 0) this.buffer.unshift(...stillPending);
+  }
+  /** Buffered-but-unsent count (observability/tests). */
+  get pending() {
+    return this.buffer.length;
+  }
+  async sendWithRetry(event) {
+    for (let attempt = 0; attempt < this.maxRetries; attempt += 1) {
+      let retryAfter = null;
+      try {
+        const response = await this.fetchImpl(this.endpoint, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${this.config.credential}`,
+            "content-type": "application/json",
+            accept: "application/json"
+          },
+          body: JSON.stringify(event)
+        });
+        if (response.ok) return true;
+        if (!isTransientStatus(response.status)) return false;
+        retryAfter = retryAfterMs(response.headers);
+      } catch {
+      }
+      const isLast = attempt === this.maxRetries - 1;
+      if (isLast) break;
+      const delay = retryAfter !== null ? Math.min(retryAfter, this.maxDelayMs) : computeBackoff(attempt + 1, {
+        baseMs: this.baseDelayMs,
+        maxMs: this.maxDelayMs,
+        random: this.random
+      });
+      await this.sleep(delay);
+    }
+    return false;
+  }
+};
+function resolveEndpoint(endpoint, coreUrl) {
+  if (/^https?:\/\//.test(endpoint)) return endpoint;
+  if (!coreUrl) return endpoint;
+  return `${coreUrl.replace(/\/+$/, "")}${endpoint}`;
+}
+
+// src/response-metering.ts
+var RESPONSE_METERING_HEADERS = RUNTIME_RESPONSE_METERING_CONTRACT.headers;
+var RESPONSE_METERING_ERROR_CODES = RUNTIME_RESPONSE_METERING_CONTRACT.errors;
+var devMeteringHooks = null;
+function __setDevMeteringHooks(hooks) {
+  devMeteringHooks = hooks;
+}
+var METERING_PAYLOAD_HEADER = RESPONSE_METERING_HEADERS.payload;
+var METERING_SIGNATURE_HEADER = RESPONSE_METERING_HEADERS.signature;
+var METERING_TOKEN_HEADER = RESPONSE_METERING_HEADERS.token;
+var DEFAULT_TOKEN_ENV = RUNTIME_RESPONSE_METERING_CONTRACT.token.environmentVariable;
+async function signPayload(payload, token) {
+  const key2 = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(token),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key2,
+    new TextEncoder().encode(payload)
+  );
+  return base64url(new Uint8Array(signature));
+}
+function base64url(bytes) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// src/core/post-stream-usage.ts
+var METER_KEY_RE2 = /^[a-z0-9_]{1,64}$/;
+var PostStreamUsageClient = class {
+  config;
+  endpoint;
+  fetchImpl;
+  newNonce;
+  logger;
+  sleep;
+  retryDelaysMs;
+  constructor(options) {
+    this.config = options.config;
+    this.endpoint = resolveEndpoint2(options.config.endpoint, options.coreUrl);
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.newNonce = options.newNonce ?? (() => crypto.randomUUID());
+    this.logger = options.logger ?? ((message) => console.warn(message));
+    this.sleep = options.sleep ?? sleep;
+    this.retryDelaysMs = options.retryDelaysMs ?? [100, 250, 500];
+  }
+  async reportUsage(input) {
+    try {
+      if (!this.config.enabled) throw new Error("metering is not enabled");
+      if (!input.requestId) throw new Error("requestId is required");
+      if (!input.subscriptionId) throw new Error("subscriptionId is required");
+      const unsigned = {
+        requestId: input.requestId,
+        subscriptionId: input.subscriptionId,
+        nonce: this.newNonce(),
+        meters: validateAndSortUsage(input.meters, "meters", this.config, true),
+        ...input.creditUnitsConsumed ? {
+          creditUnitsConsumed: validateAndSortUsage(
+            input.creditUnitsConsumed,
+            "creditUnitsConsumed",
+            this.config,
+            false
+          )
+        } : {},
+        ...input.measureContext ? { measureContext: input.measureContext } : {}
+      };
+      const signature = await signPayload(
+        JSON.stringify(unsigned),
+        this.config.credential
+      );
+      const event = { ...unsigned, signature };
+      const body = JSON.stringify(event);
+      for (let attempt = 0; ; attempt += 1) {
+        const response = await this.fetchImpl(this.endpoint, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${this.config.credential}`,
+            "content-type": "application/json",
+            accept: "application/json"
+          },
+          body
+        });
+        if (response.ok) return { ok: true };
+        const requestNotFound = await isPostStreamRequestNotFound(response);
+        const delayMs = this.retryDelaysMs[attempt];
+        if (!requestNotFound || delayMs === void 0) {
+          throw new Error(`metering endpoint returned ${response.status}`);
+        }
+        await this.sleep(delayMs);
+      }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.logger(`post-stream usage report skipped: ${reason}`);
+      return { ok: false, reason };
+    }
+  }
+};
+async function isPostStreamRequestNotFound(response) {
+  if (response.status !== 422) return false;
+  try {
+    const body = await response.json();
+    return body.error?.code === "post_stream_request_not_found";
+  } catch {
+    return false;
+  }
+}
+function sleep(delayMs) {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function validateAndSortUsage(usage, label, config, enforceMeterScope) {
+  const entries = Object.entries(usage).sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  );
+  for (const [meter, qty] of entries) {
+    if (!METER_KEY_RE2.test(meter)) {
+      throw new Error(
+        `${label} key '${meter}' must be lowercase alphanumeric with underscores`
+      );
+    }
+    if (!Number.isFinite(qty) || qty < 0) {
+      throw new Error(`${label}.${meter} must be a non-negative finite number`);
+    }
+    if (enforceMeterScope && config.allowedMeters.length > 0 && !config.allowedMeters.includes(meter)) {
+      throw new Error(`meter '${meter}' is not in the token's allowedMeters`);
+    }
+    if (enforceMeterScope && config.perEventMax > 0 && qty > config.perEventMax) {
+      throw new Error(
+        `meter '${meter}' qty ${qty} exceeds the per-event max ${config.perEventMax}`
+      );
+    }
+  }
+  return Object.fromEntries(entries);
+}
+function resolveEndpoint2(endpoint, coreUrl) {
+  if (/^https?:\/\//.test(endpoint)) return endpoint;
+  if (!coreUrl) return endpoint;
+  return `${coreUrl.replace(/\/+$/, "")}${endpoint}`;
+}
+
+// src/core/nonceCache.ts
+var DEFAULT_MAX_ENTRIES = 1e5;
+var DEFAULT_TTL_MS = 6e5;
+var NonceCache = class {
+  maxEntries;
+  ttlMs;
+  now;
+  // insertion-ordered Map ⇒ first key is the oldest (LRU eviction).
+  seen = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.now = options.now ?? (() => Date.now());
+  }
+  /**
+   * @returns true if `id` was already seen (a REPLAY); false on first sight
+   * (the id is then remembered).
+   */
+  checkAndRemember(id) {
+    const at = this.now();
+    const previous = this.seen.get(id);
+    if (previous !== void 0) {
+      if (at - previous < this.ttlMs) return true;
+      this.seen.delete(id);
+    }
+    this.evictExpired(at);
+    this.evictOverflow();
+    this.seen.set(id, at);
+    return false;
+  }
+  /** Number of retained nonces (test/observability hook). */
+  get size() {
+    return this.seen.size;
+  }
+  evictExpired(at) {
+    for (const [id, ts] of this.seen) {
+      if (at - ts < this.ttlMs) break;
+      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
+var ShutdownManager = class {
+  hooks = [];
+  done = false;
+  register(hook) {
+    this.hooks.push(hook);
+  }
+  get isShutDown() {
+    return this.done;
+  }
+  /** Run all hooks in reverse order, isolating failures. Idempotent. */
+  async shutdown() {
+    if (this.done) return;
+    this.done = true;
+    for (let i = this.hooks.length - 1; i >= 0; i -= 1) {
+      try {
+        await this.hooks[i]();
+      } catch {
+      }
+    }
+  }
+};
+
+// src/core/tunnel.ts
+import { spawn as nodeChildSpawn } from "node:child_process";
+import { createRequire } from "node:module";
+var REDACTED_TOKEN = "***REDACTED***";
+var CLOUDFLARED_RUN_ARGS = [
+  "tunnel",
+  "--no-autoupdate",
+  "run",
+  "--token"
+];
+var CLOUDFLARED_BINARY_PACKAGES = {
+  "linux-x64": "@farthershore/cloudflared-linux-x64",
+  "linux-arm64": "@farthershore/cloudflared-linux-arm64",
+  "darwin-arm64": "@farthershore/cloudflared-darwin-arm64",
+  "darwin-x64": "@farthershore/cloudflared-darwin-x64"
+};
+var DEFAULT_BASE_BACKOFF_MS = 1e3;
+var DEFAULT_MAX_BACKOFF_MS = 6e4;
+var DEFAULT_BINARY = "cloudflared";
+var MAX_LOG_LINE_BYTES = 64 * 1024;
+var CloudflaredSupervisor = class {
+  tunnelToken;
+  spawn;
+  binaryPath;
+  locateBinary;
+  logger;
+  onError;
+  failClosed;
+  baseBackoffMs;
+  maxBackoffMs;
+  backoffJitter;
+  random;
+  setTimeoutFn;
+  clearTimeoutFn;
+  childEnv;
+  child = null;
+  state = "stopped";
+  restarts = 0;
+  consecutiveFailures = 0;
+  lastError = null;
+  intentionalStop = false;
+  restartTimer = null;
+  signalsBound = false;
+  signalHandler = () => {
+    void this.shutdown();
+  };
+  constructor(options) {
+    if (!options.tunnelToken) {
+      throw new Error("CloudflaredSupervisor requires a tunnel token");
+    }
+    this.tunnelToken = options.tunnelToken;
+    this.spawn = options.spawn;
+    this.binaryPath = options.binaryPath;
+    this.locateBinary = options.locateBinary ?? (() => defaultLocateBinary());
+    this.logger = options.logger ?? ((line) => console.error(line));
+    this.onError = options.onError;
+    this.failClosed = options.failClosed ?? false;
+    this.baseBackoffMs = options.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS;
+    this.maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+    this.backoffJitter = options.backoffJitter ?? "equal";
+    this.random = options.random ?? Math.random;
+    this.setTimeoutFn = options.setTimeoutFn ?? ((cb, ms) => setTimeout(cb, ms));
+    this.clearTimeoutFn = options.clearTimeoutFn ?? ((h) => clearTimeout(h));
+    this.childEnv = options.childEnv;
+  }
+  /**
+   * Resolve the binary, spawn the child, wire log piping + exit handling, and
+   * bind SIGTERM/SIGINT. Fail-open by default (resolves; error in `status()`);
+   * fail-closed when configured (rejects).
+   *
+   * Async by contract: the public lifecycle API (and a future binary
+   * download/health-probe step) is Promise-returning even when today's body is
+   * synchronous, so callers can always `await fs.start()`.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async start() {
+    this.intentionalStop = false;
+    this.bindSignals();
+    try {
+      this.spawnChild();
+    } catch (error) {
+      this.handleStartFailure(error);
+    }
+  }
+  /**
+   * Intentional graceful stop: cancel any pending restart, signal the child
+   * (SIGTERM), unbind signals, and mark the supervisor stopped. Any exit that
+   * the kill provokes will NOT trigger a restart. Async by lifecycle contract.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async shutdown() {
+    this.intentionalStop = true;
+    if (this.restartTimer !== null) {
+      this.clearTimeoutFn(this.restartTimer);
+      this.restartTimer = null;
+    }
+    this.unbindSignals();
+    const child = this.child;
+    this.child = null;
+    this.state = "stopped";
+    if (child) {
+      try {
+        child.kill("SIGTERM");
+      } catch (error) {
+        this.recordError(error);
+      }
+    }
+  }
+  /** Token-free status snapshot for diagnostics / health. */
+  status() {
+    return {
+      state: this.state,
+      pid: this.child?.pid ?? null,
+      restarts: this.restarts,
+      lastError: this.lastError
+    };
+  }
+  /** Compact health string for `fs.health().tunnel`. */
+  healthString() {
+    return this.state;
+  }
+  // --- internals ------------------------------------------------------------
+  spawnChild() {
+    this.state = "starting";
+    const command = this.resolveBinary();
+    const args = [...CLOUDFLARED_RUN_ARGS, this.tunnelToken];
+    const child = this.spawn(
+      command,
+      args,
+      this.childEnv ? { env: this.childEnv } : void 0
+    );
+    this.child = child;
+    this.state = "running";
+    this.pipeLogs(child);
+    child.on("exit", (code, signal) => this.handleExit(code, signal));
+  }
+  /**
+   * Resolve the cloudflared binary path. Order:
+   *   1. an installed `@farthershore/cloudflared-<platform>` optional-dependency
+   *      matching process.platform+arch (the injected locator), then
+   *   2. an explicit `binaryPath` supplied by the host, then
+   *   3. the bare `cloudflared` name on PATH (resolved at spawn time).
+   *
+   * On an unsupported arch (no optional dep, no binaryPath) AND no usable PATH
+   * fallback, this raises a clear, redacted error pointing at the sidecar — it
+   * NEVER downloads a binary at runtime. (Cross-platform binary management is the
+   * optional-dep packages' job, populated at publish time.)
+   */
+  resolveBinary() {
+    const located = this.locateBinary();
+    if (located) return located;
+    if (this.binaryPath) return this.binaryPath;
+    if (currentBinaryPackageName() !== null) return DEFAULT_BINARY;
+    throw new Error(
+      "cloudflared binary not found for this platform/arch \u2014 install an @farthershore/cloudflared-<platform> package, supply binaryPath, or run the sidecar runner instead (no binary is downloaded at runtime)."
+    );
+  }
+  /** Pipe stdout/stderr to the logger with the tunnel token redacted. */
+  pipeLogs(child) {
+    child.stdout?.on("data", this.makeLineSink());
+    child.stderr?.on("data", this.makeLineSink());
+  }
+  /**
+   * Build a per-stream `data` handler that BUFFERS partial lines across chunks
+   * before redacting. The OS can deliver a single log line in two `data` events
+   * with the boundary mid-token; redacting each chunk independently would let
+   * the two token halves slip through. Buffering until a newline reassembles
+   * the full line (a token never contains a newline), so redaction always sees
+   * the whole token. A trailing partial is held for the next chunk, or flushed
+   * if it grows past a safety cap (cloudflared is line-oriented, so this is a
+   * belt-and-suspenders guard against unbounded buffer growth).
+   */
+  makeLineSink() {
+    let buffer = "";
+    return (chunk) => {
+      buffer += chunkToString(chunk);
+      if (buffer.length > MAX_LOG_LINE_BYTES) {
+        this.emitLogLine(buffer);
+        buffer = "";
+        return;
+      }
+      const parts = buffer.split("\n");
+      buffer = parts.pop() ?? "";
+      for (const part of parts) {
+        this.emitLogLine(part.replace(/\r$/, ""));
+      }
+    };
+  }
+  emitLogLine(line) {
+    if (line.length === 0) return;
+    this.logger(this.redact(line));
+  }
+  /** Replace every occurrence of the tunnel token with the sentinel. */
+  redact(text) {
+    if (this.tunnelToken.length === 0) return text;
+    return text.split(this.tunnelToken).join(REDACTED_TOKEN);
+  }
+  handleExit(code, _signal) {
+    this.child = null;
+    if (this.intentionalStop) {
+      this.state = "stopped";
+      return;
+    }
+    this.consecutiveFailures += 1;
+    this.lastError = this.redact(
+      `cloudflared exited unexpectedly (code=${String(code)})`
+    );
+    this.state = "restarting";
+    this.scheduleRestart();
+  }
+  scheduleRestart() {
+    const delay = this.backoffDelay();
+    this.restartTimer = this.setTimeoutFn(() => {
+      this.restartTimer = null;
+      if (this.intentionalStop) return;
+      this.restarts += 1;
+      try {
+        this.spawnChild();
+      } catch (error) {
+        this.recordError(error);
+        this.consecutiveFailures += 1;
+        this.state = "restarting";
+        this.scheduleRestart();
+      }
+    }, delay);
+  }
+  backoffDelay() {
+    const exponent = Math.max(0, this.consecutiveFailures - 1);
+    const raw = this.baseBackoffMs * 2 ** exponent;
+    return Math.min(raw, this.maxBackoffMs);
+  }
+  handleStartFailure(error) {
+    this.recordError(error);
+    this.state = "error";
+    this.child = null;
+    if (this.failClosed) {
+      throw new Error(this.lastError ?? "cloudflared failed to start");
+    }
+  }
+  recordError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const redacted = this.redact(message);
+    this.lastError = redacted;
+    if (this.onError) {
+      this.onError(new Error(redacted));
+    }
+  }
+  bindSignals() {
+    if (this.signalsBound) return;
+    const proc = nodeProcess();
+    if (!proc) return;
+    proc.on("SIGTERM", this.signalHandler);
+    proc.on("SIGINT", this.signalHandler);
+    this.signalsBound = true;
+  }
+  unbindSignals() {
+    if (!this.signalsBound) return;
+    const proc = nodeProcess();
+    if (proc) {
+      proc.removeListener("SIGTERM", this.signalHandler);
+      proc.removeListener("SIGINT", this.signalHandler);
+    }
+    this.signalsBound = false;
+  }
+};
+function nodeSpawn() {
+  return (command, args, options) => nodeChildSpawn(command, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options?.env ? { env: options.env } : {}
+  });
+}
+var LOG_DECODER = new TextDecoder("utf-8");
+function chunkToString(chunk) {
+  if (typeof chunk === "string") return chunk;
+  if (chunk instanceof Uint8Array) {
+    return LOG_DECODER.decode(chunk);
+  }
+  return "";
+}
+function nodeProcess() {
+  const proc = globalThis.process;
+  return proc && typeof proc.on === "function" ? proc : null;
+}
+function currentBinaryPackageName() {
+  const proc = globalThis.process;
+  if (!proc?.platform || !proc.arch) return null;
+  return CLOUDFLARED_BINARY_PACKAGES[`${proc.platform}-${proc.arch}`] ?? null;
+}
+function defaultLocateBinary() {
+  const pkg = currentBinaryPackageName();
+  if (!pkg) return null;
+  try {
+    const require2 = createRequire(import.meta.url);
+    const manifestPath = require2.resolve(`${pkg}/package.json`);
+    return resolvePackageBinary(require2, pkg, manifestPath);
+  } catch {
+    return null;
+  }
+}
+function resolvePackageBinary(require2, pkg, manifestPath) {
+  const sep = manifestPath.includes("\\") ? "\\" : "/";
+  const root = manifestPath.slice(0, manifestPath.lastIndexOf(sep));
+  const manifest = require2(manifestPath);
+  const binField = manifest.bin;
+  const relative = typeof binField === "string" ? binField : binField?.cloudflared ?? `bin${sep}cloudflared`;
+  const normalized = relative.replace(/^\.[\\/]/, "");
+  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 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 ctx.signedContext !== void 0;
+  }
+  return permissionSatisfies(key2, ctx.permissions);
+}
+function requirePermission(ctx, key2) {
+  if (!hasPermission(ctx, key2)) {
+    throw new FartherShorePermissionError(key2);
+  }
+}
+
+// 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);
+  const signature = h(RUNTIME_HEADER_NAMES.signature);
+  if (!signature) {
+    throw new FartherShoreError(
+      "missing_signature",
+      "request is missing the x-fs-signature header"
+    );
+  }
+  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 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) {
+    throw new FartherShoreError(
+      "malformed_signature",
+      "request is missing one or more required x-fs-* headers"
+    );
+  }
+  const timestamp = Number(timestampRaw);
+  if (!Number.isInteger(timestamp)) {
+    throw new FartherShoreError(
+      "malformed_signature",
+      "x-fs-timestamp is not an integer"
+    );
+  }
+  const skew = deps.clockSkewSeconds ?? RUNTIME_CLOCK_SKEW_SECONDS;
+  const window = deps.replayWindowSeconds ?? RUNTIME_REPLAY_WINDOW_SECONDS;
+  const now = (deps.nowSeconds ?? (() => Math.floor(Date.now() / 1e3)))();
+  const delta = now - timestamp;
+  if (Math.abs(delta) > window) {
+    if (Math.abs(delta) <= window + skew) {
+      throw new FartherShoreError(
+        "clock_skew",
+        "x-fs-timestamp is outside the replay window but within clock-skew tolerance"
+      );
+    }
+    throw new FartherShoreError(
+      "expired_signature",
+      "x-fs-timestamp is outside the replay window"
+    );
+  }
+  const computedBodyHash = await computeBodyHash(input);
+  if (signedBodyHash !== computedBodyHash) {
+    throw new FartherShoreError(
+      "body_hash_mismatch",
+      "recomputed body hash does not match the signed x-fs-body-hash"
+    );
+  }
+  if (deps.productId !== void 0 && signedProductId !== deps.productId) {
+    throw new FartherShoreError(
+      "route_mismatch",
+      "signed product-id does not match this backend's product"
+    );
+  }
+  if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
+    throw new FartherShoreError(
+      "route_mismatch",
+      "signed backend-id does not match this backend"
+    );
+  }
+  if (deps.knownRouteIds !== void 0 && signedRouteId !== "" && !deps.knownRouteIds.has(signedRouteId)) {
+    throw new FartherShoreError(
+      "route_mismatch",
+      "signed route-id is not served by this backend"
+    );
+  }
+  const canonicalInput = {
+    method: input.method,
+    path: input.path,
+    query: input.query ?? "",
+    bodyHash: computedBodyHash,
+    requestId,
+    timestamp,
+    productId: signedProductId,
+    backendId: signedBackendId,
+    routeId: signedRouteId,
+    policyVersion
+  };
+  const canonical = buildCanonicalSigningString2(canonicalInput);
+  const publicJwk = await deps.jwks.getKey(kid);
+  let ok = false;
+  try {
+    ok = await verifyCanonicalSignature2(canonical, signature, publicJwk);
+  } catch {
+    throw new FartherShoreError(
+      "malformed_signature",
+      "x-fs-signature could not be decoded or verified"
+    );
+  }
+  if (!ok) {
+    throw new FartherShoreError(
+      "bad_signature",
+      "Ed25519 signature verification failed"
+    );
+  }
+  if (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");
+  }
+  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,
+    backendId: signedBackendId,
+    routeId: signedRouteId,
+    policyVersion,
+    timestamp,
+    bodyHash: computedBodyHash,
+    ...permissions !== void 0 ? { permissions } : {},
+    ...roles !== void 0 ? { roles } : {},
+    ...signedContext ? { signedContext } : {}
+  };
+}
+async function computeBodyHash(input) {
+  if (input.streamingExempt) return STREAMING_EXEMPT_BODY_HASH;
+  const body = input.body;
+  if (!body || body.byteLength === 0) return EMPTY_BODY_SHA256;
+  if (body.byteLength > MAX_BODY_BYTES) {
+    throw new FartherShoreError(
+      "body_too_large",
+      `request body exceeds the ${MAX_BODY_BYTES}-byte limit`
+    );
+  }
+  return hashBody2(body);
+}
+function headerGetter(headers) {
+  if (typeof headers.get === "function") {
+    const h = headers;
+    return (name) => h.get(name) ?? void 0;
+  }
+  const lower = /* @__PURE__ */ new Map();
+  for (const [key2, value] of Object.entries(
+    headers
+  )) {
+    if (value === void 0) continue;
+    lower.set(
+      key2.toLowerCase(),
+      Array.isArray(value) ? value[0] ?? "" : value
+    );
+  }
+  return (name) => lower.get(name.toLowerCase());
+}
+
+// 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 FartherShore = class {
+  bootstrapClient;
+  fetchImpl;
+  verificationEnabled;
+  meteringEnabledOverride;
+  runtimeToken;
+  coreUrl;
+  instanceId;
+  tunnelOptions;
+  /** FAR-723 — HS256 secret(s) for verifying the signed X-Fs-Context claim. */
+  contextSecrets;
+  /** FAR-723 — "preferred" (fallback to unsigned) | "required" (fail-closed). */
+  contextVerification;
+  nonceCache = new NonceCache();
+  shutdownManager = new ShutdownManager();
+  jwks = null;
+  meteringClient = null;
+  postStreamUsageClient = null;
+  tunnel = null;
+  bootstrapped = false;
+  constructor(options = {}) {
+    const env = options.env ?? readProcessEnv();
+    const runtimeToken = options.runtimeToken ?? env[FS_RUNTIME_TOKEN_ENV] ?? "";
+    const coreUrl = options.coreUrl ?? env.FS_CORE_URL ?? env.FARTHERSHORE_CORE_URL ?? DEFAULT_CORE_URL;
+    this.runtimeToken = runtimeToken;
+    this.coreUrl = coreUrl;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.verificationEnabled = options.verification?.enabled ?? true;
+    this.meteringEnabledOverride = options.metering?.enabled ?? true;
+    this.tunnelOptions = options.tunnel ?? {};
+    this.instanceId = options.instanceId;
+    this.contextSecrets = options.contextSecrets ?? parseContextSecrets(env.FS_CONTEXT_SECRETS);
+    this.contextVerification = options.contextVerification ?? (env.FS_CONTEXT_VERIFICATION === "required" ? "required" : "preferred");
+    this.bootstrapClient = new BootstrapClient({
+      runtimeToken,
+      coreUrl,
+      fetchImpl: this.fetchImpl,
+      request: {
+        sdkVersion: SDK_VERSION,
+        sdkLanguage: "typescript",
+        ...options.instanceId ? { instanceId: options.instanceId } : {}
+      }
+    });
+    this.shutdownManager.register(async () => {
+      await this.meteringClient?.flush();
+    });
+    this.shutdownManager.register(async () => {
+      await reportHealth({
+        runtimeToken: this.runtimeToken,
+        coreUrl: this.coreUrl,
+        status: "stopping",
+        instanceId: this.instanceId,
+        fetchImpl: this.fetchImpl
+      });
+    });
+  }
+  /** Ensure bootstrap config is loaded; build the JWKS + metering clients. */
+  async ensureBootstrapped() {
+    const config = await this.bootstrapClient.get();
+    if (!this.jwks) {
+      this.jwks = new JwksClient({
+        jwksUrl: config.verification.jwksUrl,
+        fetchImpl: this.fetchImpl
+      });
+    }
+    if (!this.meteringClient && config.metering.enabled) {
+      this.meteringClient = new MeteringClient({
+        config: config.metering,
+        productId: config.product.id,
+        backendId: config.backend.id,
+        coreUrl: this.coreUrl,
+        fetchImpl: this.fetchImpl
+      });
+      this.postStreamUsageClient = new PostStreamUsageClient({
+        config: config.metering,
+        coreUrl: this.coreUrl,
+        fetchImpl: this.fetchImpl
+      });
+    }
+    this.bootstrapped = true;
+    return config;
+  }
+  /**
+   * Boot-time route reconciliation (call once, before `listen()`). Reflects the
+   * app's real route surface, diffs it against the declared lock from bootstrap,
+   * REPORTS drift to the platform, and CONFIRMS the declared `pending` routes
+   * this replica serves. Fail-OPEN: never throws / never blocks boot.
+   *
+   * The reflection code is dynamically imported so it stays OFF the per-request
+   * verification hot path (the runtime stays route-unaware there). The report is
+   * an OUTBOUND backend→core call (same channel as bootstrap/metering), so it
+   * works for every transport (direct / tunnel).
+   *
+   * Returns the reconcile result (or null if reflection is unavailable / boot
+   * reporting failed). v1 reflects Express; `app` omitted → no-op.
+   */
+  async ready(app) {
+    try {
+      const config = await this.ensureBootstrapped();
+      if (app === void 0) return null;
+      const [{ reflectRoutes: reflectRoutes2 }, { reconcileOnStartup: reconcileOnStartup2 }] = await Promise.all([
+        Promise.resolve().then(() => (init_reflect(), reflect_exports)),
+        Promise.resolve().then(() => (init_reconcile(), reconcile_exports))
+      ]);
+      return await reconcileOnStartup2({
+        reflected: reflectRoutes2(app),
+        bootstrap: {
+          backendId: config.backend.id,
+          lock: config.lock,
+          routes: config.routes
+        },
+        report: this.buildReportSink()
+      });
+    } catch {
+      return null;
+    }
+  }
+  /** Outbound report sink for `ready()` — runtime-token-authed POSTs to core. */
+  buildReportSink() {
+    const post = async (path, body) => {
+      const base = this.coreUrl.replace(/\/$/, "");
+      const res = await this.fetchImpl(`${base}${path}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.runtimeToken}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) throw new Error(`runtime report ${path} -> ${res.status}`);
+    };
+    return {
+      reportDrift: (report) => post("/v1/runtime/drift", report),
+      confirmServed: (confirm) => post("/v1/runtime/health", confirm)
+    };
+  }
+  /**
+   * Framework-neutral verification primitive. Fail-closed: throws a typed
+   * FartherShoreError on any verification failure. Returns the verified context.
+   */
+  async verifyRequest(input) {
+    const config = await this.ensureBootstrapped();
+    if (!this.jwks) {
+      throw new FartherShoreError(
+        "jwks_unavailable",
+        "JWKS client is not initialized"
+      );
+    }
+    const knownRouteIds = new Set(config.routes.map((r) => r.id));
+    const context = await verifyRequest(input, {
+      jwks: this.jwks,
+      nonceCache: this.nonceCache,
+      productId: config.product.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
+    });
+    return {
+      ...context,
+      reportUsage: (report) => {
+        const subscriptionId = report.subscriptionId ?? context.signedContext?.subscriptionId;
+        if (!subscriptionId) {
+          return Promise.resolve({
+            ok: false,
+            reason: "subscriptionId is required"
+          });
+        }
+        return this.reportUsage({
+          ...report,
+          requestId: report.requestId ?? context.requestId,
+          subscriptionId
+        });
+      }
+    };
+  }
+  /** Whether verification is required (bootstrap × opt-out). */
+  async verificationRequired() {
+    if (!this.verificationEnabled) return false;
+    const config = await this.ensureBootstrapped();
+    return config.verification.required;
+  }
+  /**
+   * Start the embedded runner. For a `tunnel` backend whose runner is
+   * `embedded`, this supervises `cloudflared` as a child process
+   * (spawned via the injected/default spawner) using the tunnel token from
+   * bootstrap. For every other transport (`direct`, or the `sidecar` runner)
+   * it is a no-op — there is no SDK-managed process to run.
+   *
+   * Fail-open by default: a tunnel that cannot start does NOT crash the host app
+   * (request verification stays fail-closed regardless — a different axis).
+   */
+  async start() {
+    if (this.tunnelOptions.enabled === false) return;
+    const config = await this.ensureBootstrapped();
+    const transport = config.transport;
+    if (transport.mode !== "tunnel" || transport.runner !== "embedded") {
+      return;
+    }
+    const tunnelToken = transport.cloudflared?.tunnelToken;
+    if (!tunnelToken) {
+      if (this.tunnelOptions.failClosed) {
+        throw new FartherShoreError(
+          "invalid_token",
+          "embedded cloudflared runner requires a tunnel token from bootstrap"
+        );
+      }
+      return;
+    }
+    if (this.tunnel) return;
+    const supervisor = new CloudflaredSupervisor({
+      tunnelToken,
+      spawn: this.tunnelOptions.spawn ?? nodeSpawn(),
+      ...this.tunnelOptions.binaryPath ? { binaryPath: this.tunnelOptions.binaryPath } : {},
+      ...this.tunnelOptions.logger ? { logger: this.tunnelOptions.logger } : {},
+      failClosed: this.tunnelOptions.failClosed ?? false
+    });
+    this.tunnel = supervisor;
+    this.shutdownManager.register(async () => {
+      await supervisor.shutdown();
+    });
+    await supervisor.start();
+  }
+  /** Record metering usage (billing-only). */
+  async meter(meter, qty, options = {}) {
+    await this.ensureBootstrapped();
+    if (!this.meteringEnabledOverride) return;
+    if (!this.meteringClient) {
+      throw new FartherShoreError(
+        "invalid_token",
+        "metering is not enabled for this runtime token"
+      );
+    }
+    await this.meteringClient.meter(meter, qty, options);
+  }
+  /** Best-effort attested post-stream usage callback. Never rejects. */
+  async reportUsage(input) {
+    try {
+      await this.ensureBootstrapped();
+      if (!this.meteringEnabledOverride || !this.postStreamUsageClient) {
+        return { ok: false, reason: "metering is not enabled" };
+      }
+      return await this.postStreamUsageClient.reportUsage(input);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      console.warn(`post-stream usage report skipped: ${reason}`);
+      return { ok: false, reason };
+    }
+  }
+  /** Current local health report. */
+  health() {
+    const config = this.bootstrapClient.peek();
+    return buildHealthReport({
+      runtimeToken: this.runtimeToken.length > 0,
+      bootstrap: this.bootstrapped && config !== null,
+      // Populated by the embedded-cloudflared supervisor (Slice 3). Null until
+      // fs.start() launches an embedded tunnel; otherwise the supervisor state.
+      tunnel: this.tunnel ? this.tunnel.healthString() : null,
+      verification: this.verificationEnabled && config !== null,
+      metering: this.meteringClient !== null
+    });
+  }
+  /** Graceful shutdown: flush metering + send a stopping heartbeat. */
+  async shutdown() {
+    await this.shutdownManager.shutdown();
+  }
+  /** Register an additional shutdown hook (e.g. the cloudflared supervisor). */
+  onShutdown(hook) {
+    this.shutdownManager.register(hook);
+  }
+};
+function initFromEnv(options = {}) {
+  return new FartherShore(options);
+}
+function readProcessEnv() {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env ?? {};
+}
+function parseContextSecrets(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// src/adapters/express.ts
+var STREAMING_CONTENT_TYPES = new Set(
+  RUNTIME_BODY_HASH_CONTRACT.streamingExemptContentTypes
+);
+function createExpressMiddleware(fs, options = {}) {
+  return (req, res, next) => {
+    void runMiddleware(fs, options, req, res, next);
+  };
+}
+async function runMiddleware(fs, options, req, res, next) {
+  try {
+    if (!options.always && !await fs.verificationRequired()) {
+      next();
+      return;
+    }
+    const { path, query } = splitUrl(req);
+    const contentType = headerValue(req.headers, "content-type");
+    const streamingExempt = isStreamingExempt(contentType);
+    const body = streamingExempt ? null : extractRawBody(req);
+    const ctx = await fs.verifyRequest({
+      method: req.method,
+      path,
+      query,
+      headers: req.headers,
+      body,
+      streamingExempt
+    });
+    req.fartherShore = ctx;
+    next();
+  } catch (error) {
+    fail(res, error);
+  }
+}
+function fail(res, error) {
+  if (error instanceof FartherShoreError) {
+    res.status(error.status).json({ error: error.code });
+    return;
+  }
+  res.status(401).json({ error: "bad_signature" });
+}
+function splitUrl(req) {
+  const raw = req.originalUrl ?? req.url ?? req.path ?? "/";
+  const qIndex = raw.indexOf("?");
+  if (qIndex === -1) return { path: raw, query: "" };
+  return { path: raw.slice(0, qIndex), query: raw.slice(qIndex + 1) };
+}
+function isStreamingExempt(contentType) {
+  if (!contentType) return false;
+  const base = contentType.split(";")[0].trim().toLowerCase();
+  return STREAMING_CONTENT_TYPES.has(base);
+}
+function extractRawBody(req) {
+  const raw = req.rawBody;
+  if (raw) return raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+  const body = req.body;
+  if (body === void 0 || body === null) return null;
+  if (typeof body === "string") return new TextEncoder().encode(body);
+  if (body instanceof Uint8Array) return body;
+  return new Uint8Array(0);
+}
+function headerValue(headers, name) {
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+
+// src/testing/prodGuard.ts
+function isProductionEnv(env = readProcessEnv2()) {
+  return (env.NODE_ENV ?? "").trim().toLowerCase() === "production";
+}
+var DevModeInProductionError = class extends Error {
+  constructor(context) {
+    super(
+      `Farther Shore dev mode (${context}) is disabled in this process: NODE_ENV=production. Dev mode mints ephemeral signing keys and signed identity and must never run in production.`
+    );
+    this.name = "DevModeInProductionError";
+  }
+};
+function assertNotProduction(context, env = readProcessEnv2()) {
+  if (isProductionEnv(env)) {
+    throw new DevModeInProductionError(context);
+  }
+}
+function readProcessEnv2() {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env ?? {};
+}
+
+// src/testing/usageSink.ts
+var DevUsageSink = class {
+  events = [];
+  /** Record a signed response-metering payload (withUsage / computeMeteringHeaders). */
+  recordResponse(payload, requestId) {
+    const raw = payload.rawDimsUnits;
+    const meters = raw && typeof raw === "object" ? raw : {};
+    this.events.push({
+      source: "response",
+      meters: { ...meters },
+      payload,
+      ...requestId ? { requestId } : {},
+      at: Date.now()
+    });
+  }
+  /** Record a background `fs.meter()` event captured by the dev gateway. */
+  recordMeterEvent(event) {
+    this.events.push({
+      source: "meter",
+      meters: { [event.meter]: event.qty },
+      event,
+      ...event.request_id ? { requestId: event.request_id } : {},
+      at: Date.now()
+    });
+  }
+  /** Record an attested post-stream report captured by the dev gateway. */
+  recordReportUsage(event) {
+    this.events.push({
+      source: "reportUsage",
+      meters: { ...event.meters },
+      event,
+      requestId: event.requestId,
+      at: Date.now()
+    });
+  }
+  /** Total quantity per meter key across every recorded event. */
+  byMeter() {
+    const out = {};
+    for (const evt of this.events) {
+      for (const [meter, qty] of Object.entries(evt.meters)) {
+        out[meter] = (out[meter] ?? 0) + qty;
+      }
+    }
+    return out;
+  }
+  /** Clear all recorded usage. */
+  reset() {
+    this.events.length = 0;
+  }
+};
+
+// src/testing/traceSink.ts
+function redactValue(input) {
+  return input.replace(/fsrt_(?:live|test)_[A-Za-z0-9_-]+/g, "fsrt_[redacted]").replace(/fsk_[A-Za-z0-9_-]+/g, "fsk_[redacted]").replace(/fsc_[A-Za-z0-9_-]+/g, "fsc_[redacted]").replace(/[Bb]earer\s+[A-Za-z0-9._-]+/g, "Bearer [redacted]");
+}
+var DevTraceSink = class {
+  traces = /* @__PURE__ */ new Map();
+  flushed = /* @__PURE__ */ new Set();
+  appendLine;
+  constructor(options = {}) {
+    this.appendLine = options.appendLine;
+  }
+  ensure(requestId, mode) {
+    let trace = this.traces.get(requestId);
+    if (!trace) {
+      trace = { requestId, mode, authz: [], metering: [] };
+      this.traces.set(requestId, trace);
+    }
+    return trace;
+  }
+  /** Record how a request's signature/context verification resolved. */
+  recordVerification(requestId, mode, outcome, fields = {}) {
+    const trace = this.ensure(requestId, mode);
+    if (fields.method) trace.method = fields.method;
+    if (fields.path) trace.path = fields.path;
+    if (fields.persona) trace.persona = fields.persona;
+    trace.verification = {
+      outcome,
+      ...fields.reason ? { reason: redactValue(fields.reason) } : {}
+    };
+  }
+  /** Record a single hasPermission / requirePermission decision. */
+  recordAuthz(requestId, mode, entry) {
+    const trace = this.ensure(requestId, mode);
+    trace.authz.push({
+      permission: entry.permission,
+      decision: entry.decision,
+      ...entry.reason ? { reason: redactValue(entry.reason) } : {}
+    });
+  }
+  /** Record usage reported for this request. */
+  recordMetering(requestId, mode, entry) {
+    const trace = this.ensure(requestId, mode);
+    trace.metering.push(entry);
+  }
+  /** Record the final response status and flush the trace as one JSONL line. */
+  recordResponse(requestId, mode, status) {
+    const trace = this.ensure(requestId, mode);
+    trace.response = { status };
+    this.flush(requestId);
+  }
+  /**
+   * Append a trace's current state as one JSONL line (if a sink is wired).
+   * Flushes at most ONCE per request id, so wrapping several response methods
+   * (status/json/end) never produces duplicate JSONL lines.
+   */
+  flush(requestId) {
+    if (this.flushed.has(requestId)) return;
+    const trace = this.traces.get(requestId);
+    if (trace && this.appendLine) {
+      this.appendLine(JSON.stringify(trace));
+      this.flushed.add(requestId);
+    }
+  }
+  /** The accumulated trace for a request id, or `undefined`. */
+  forRequest(requestId) {
+    return this.traces.get(requestId);
+  }
+  /** Every accumulated trace (insertion order). */
+  all() {
+    return [...this.traces.values()];
+  }
+  /** Clear all traces. */
+  reset() {
+    this.traces.clear();
+    this.flushed.clear();
+  }
+};
+
+// src/testing/keysFile.ts
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+var DEFAULT_KEYS_FILE = ".farthershore/dev-keys.json";
+function writeDevKeysFile(path, contents) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(contents, null, 2), { mode: 384 });
+  chmodSync(path, 384);
+}
+function readDevKeysFile(path = DEFAULT_KEYS_FILE) {
+  const raw = readFileSync(path, "utf8");
+  return JSON.parse(raw);
+}
+function personaClientFromKeysFile(path = DEFAULT_KEYS_FILE, options = {}) {
+  const file = readDevKeysFile(path);
+  const client = createPersonaClient({
+    keys: file.keys,
+    productId: file.productId,
+    backendId: file.backendId,
+    contextSecret: file.keys.contextSecret,
+    contextKid: file.keys.contextKid,
+    personas: buildPersonaMap(file.personas),
+    mode: file.mode,
+    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
+  });
+  return {
+    asPersona: (name) => client.asPersona(name),
+    personas: client.personas,
+    file
+  };
+}
+
+// src/testing/devRuntime.ts
+function createDevRuntime(options) {
+  assertNotProduction("createDevRuntime", options.env);
+  const mode = options.mode;
+  const keys = options.keys ?? generateDevSignerKeys();
+  const usage = new DevUsageSink();
+  const trace = new DevTraceSink(
+    options.traceJsonl ? { appendLine: options.traceJsonl } : {}
+  );
+  const gateway = createDevGateway({
+    mode,
+    keys,
+    ...options.productId ? { productId: options.productId } : {},
+    ...options.backendId ? { backendId: options.backendId } : {},
+    ...options.routes ? { routeIds: options.routes } : {},
+    onMeterEvent: (event) => {
+      usage.recordMeterEvent(event);
+      options.usageJsonl?.(JSON.stringify({ source: "meter", event }));
+    },
+    onReportUsage: (event) => {
+      usage.recordReportUsage(event);
+      options.usageJsonl?.(JSON.stringify({ source: "reportUsage", event }));
+    }
+  });
+  __setDevMeteringHooks({
+    fallbackToken: () => keys.runtimeToken,
+    record: (payload, requestId) => {
+      usage.recordResponse(payload, requestId);
+      options.usageJsonl?.(JSON.stringify({ source: "response", payload }));
+      if (requestId) {
+        const raw = payload.rawDimsUnits;
+        trace.recordMetering(requestId, mode, {
+          meters: raw && typeof raw === "object" ? raw : {},
+          source: "response"
+        });
+      }
+    }
+  });
+  const personas = buildPersonaMap(options.personas);
+  const personaClient = createPersonaClient({
+    keys,
+    productId: gateway.productId,
+    backendId: gateway.backendId,
+    contextSecret: keys.contextSecret,
+    contextKid: keys.contextKid,
+    personas,
+    mode,
+    ...options.appFetch ? { fetchImpl: options.appFetch } : {}
+  });
+  const fs = initFromEnv({
+    runtimeToken: keys.runtimeToken,
+    coreUrl: DEV_CORE_URL,
+    fetchImpl: gateway.fetchImpl,
+    contextSecrets: [keys.contextSecret],
+    contextVerification: mode === "simulated" ? "required" : "preferred",
+    env: {}
+  });
+  const tracedAuthz = {
+    hasPermission(ctx, key2) {
+      const decision = hasPermission(ctx, key2);
+      recordDecision(ctx, key2, decision);
+      return decision;
+    },
+    requirePermission(ctx, key2) {
+      const decision = hasPermission(ctx, key2);
+      recordDecision(ctx, key2, decision);
+      if (!decision) throw new FartherShorePermissionError(key2);
+      requirePermission(ctx, key2);
+    }
+  };
+  function recordDecision(ctx, key2, decision) {
+    const requestId = ctx.requestId ?? "unknown";
+    const subject = ctx.signedContext?.subjectKey ?? "unknown";
+    trace.recordAuthz(requestId, mode, {
+      permission: key2,
+      decision: decision ? "allow" : "deny",
+      ...decision ? {} : { reason: `permission_denied: ${key2} (subject=${subject})` }
+    });
+  }
+  function middleware(mwOptions) {
+    const inner = createExpressMiddleware(fs, mwOptions);
+    return (req, res, next) => {
+      const requestId = headerValue2(req.headers, "x-fs-request-id") ?? "unknown";
+      const { path } = splitUrl2(req);
+      const method = req.method;
+      let nextCalled = false;
+      let lastStatus = 200;
+      const origStatus = res.status.bind(res);
+      res.status = (code) => {
+        lastStatus = code;
+        return origStatus(code);
+      };
+      const origJson = res.json.bind(res);
+      res.json = (body) => {
+        if (!nextCalled) {
+          const reason = typeof body === "object" && body !== null && "error" in body ? String(body.error) : void 0;
+          trace.recordVerification(requestId, mode, "rejected", {
+            method,
+            path,
+            ...reason ? { reason } : {}
+          });
+        }
+        trace.recordResponse(requestId, mode, lastStatus);
+        return origJson(body);
+      };
+      const wrappedNext = (err) => {
+        nextCalled = true;
+        trace.recordVerification(
+          requestId,
+          mode,
+          mode === "simulated" ? "verified" : "passthrough",
+          { method, path }
+        );
+        next(err);
+      };
+      inner(req, res, wrappedNext);
+    };
+  }
+  fs.middleware = middleware;
+  const devRuntime = {
+    fs,
+    asPersona: (name) => personaClient.asPersona(name),
+    usage,
+    trace,
+    gateway,
+    keys,
+    personas,
+    mode,
+    bootstrap: gateway.bootstrap,
+    authz: tracedAuthz,
+    middleware,
+    reset() {
+      usage.reset();
+      trace.reset();
+      gateway.meterEvents.length = 0;
+    }
+  };
+  fs.dev = devRuntime;
+  return devRuntime;
+}
+var USAGE_JSONL_PATH = ".farthershore/dev-usage.jsonl";
+var TRACE_JSONL_DEFAULT = ".farthershore/dev-trace.jsonl";
+var PERSONAS_FILE = "fs.dev.personas.json";
+function devModeFromEnv(env) {
+  const raw = (env.FS_DEV_MODE ?? "").trim().toLowerCase();
+  if (raw === "passthrough" || raw === "simulated") return raw;
+  return null;
+}
+function createDevRuntimeFromEnv(env = readProcessEnv3()) {
+  const mode = devModeFromEnv(env);
+  if (!mode) {
+    throw new Error(
+      "createDevRuntimeFromEnv called without FS_DEV_MODE=passthrough|simulated"
+    );
+  }
+  assertNotProduction("FS_DEV_MODE", env);
+  const keys = generateDevSignerKeys();
+  const personas = loadPersonasFile();
+  const tracePath = env.FS_DEV_TRACE?.trim() || TRACE_JSONL_DEFAULT;
+  const runtime = createDevRuntime({
+    mode,
+    ...personas ? { personas } : {},
+    keys,
+    env,
+    usageJsonl: (line) => appendJsonl(USAGE_JSONL_PATH, line),
+    traceJsonl: (line) => appendJsonl(tracePath, line)
+  });
+  const keysFile = {
+    version: 1,
+    mode,
+    keys,
+    productId: runtime.gateway.productId,
+    backendId: runtime.gateway.backendId,
+    personas: mapToRecord(runtime.personas)
+  };
+  writeDevKeysFile(DEFAULT_KEYS_FILE, keysFile);
+  printBanner(mode, runtime, tracePath);
+  return runtime.fs;
+}
+function printBanner(mode, runtime, tracePath) {
+  const lines = [
+    "============================================================",
+    "  \u26A0  FARTHER SHORE DEV MODE ACTIVE \u2014 NOT FOR PRODUCTION",
+    `     mode:      ${mode.toUpperCase()}`,
+    `     product:   ${runtime.gateway.productId}`,
+    `     backend:   ${runtime.gateway.backendId}`,
+    `     personas:  ${[...runtime.personas.keys()].join(", ")}`,
+    `     usage log: ${USAGE_JSONL_PATH}`,
+    `     trace log: ${tracePath}`,
+    `     dev keys:  ${DEFAULT_KEYS_FILE} (mode 600, ephemeral)`,
+    mode === "simulated" ? "     verification REQUIRED \u2014 requests must carry a signed persona." : "     verification OFF (passthrough) \u2014 middleware passes through.",
+    "============================================================"
+  ];
+  console.warn(lines.join("\n"));
+}
+function loadPersonasFile() {
+  if (!existsSync(PERSONAS_FILE)) return void 0;
+  try {
+    return JSON.parse(readFileSync2(PERSONAS_FILE, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function appendJsonl(path, line) {
+  try {
+    mkdirSync2(dirname2(path), { recursive: true });
+    appendFileSync(path, `${line}
+`);
+  } catch {
+  }
+}
+function mapToRecord(map) {
+  const out = {};
+  for (const [name, def] of map) out[name] = def;
+  return out;
+}
+function readProcessEnv3() {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env ?? {};
+}
+function headerValue2(headers, name) {
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+function splitUrl2(req) {
+  const raw = req.originalUrl ?? req.url ?? req.path ?? "/";
+  const qIndex = raw.indexOf("?");
+  if (qIndex === -1) return { path: raw, query: "" };
+  return { path: raw.slice(0, qIndex), query: raw.slice(qIndex + 1) };
+}
+export {
+  CONTEXT_HEADER_NAME,
+  DEFAULT_KEYS_FILE,
+  DEFAULT_PERSONAS,
+  DEV_CORE_URL,
+  DEV_JWKS_URL,
+  DEV_METERING_ENDPOINT,
+  DevModeInProductionError,
+  DevTraceSink,
+  DevUsageSink,
+  SIGNED_HEADER_NAMES,
+  TEST_CONTEXT_KID,
+  TEST_CONTEXT_SECRET,
+  TEST_KID,
+  TEST_PRIVATE_JWK,
+  TEST_PUBLIC_JWK,
+  assertNotProduction,
+  buildPersonaMap,
+  createDevGateway,
+  createDevRuntime,
+  createDevRuntimeFromEnv,
+  createPersonaClient,
+  definePersona,
+  devModeFromEnv,
+  generateDevSignerKeys,
+  isProductionEnv,
+  makeSignedRequest,
+  memoryJwks,
+  personaClientFromKeysFile,
+  readDevKeysFile,
+  redactValue,
+  signContextToken,
+  unreachableJwks,
+  writeDevKeysFile
+};