@farthershore/backend 0.12.0 → 0.14.0

package/dist/index.js

@@ -899,6 +899,300 @@ function resolveEndpoint(endpoint, coreUrl) {
   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;
+var MeteringError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "MeteringError";
+    this.code = code;
+  }
+};
+function createUsage(request, options = {}) {
+  const usage = {};
+  const reporter = {
+    report(meter, value) {
+      usage[assertMeterKey(meter)] = assertMeterValue(meter, value);
+      return reporter;
+    },
+    async wrap(response, wrapOptions = {}) {
+      return signResponse(request, response, usage, options, wrapOptions);
+    }
+  };
+  return reporter;
+}
+async function withUsage(request, response, usage, options = {}) {
+  const reporter = createUsage(request, options);
+  for (const [meter, value] of Object.entries(usage)) {
+    reporter.report(meter, value);
+  }
+  return reporter.wrap(response);
+}
+async function signResponse(request, response, usage, options, wrapOptions) {
+  const payload = buildPayload(request, usage, options, wrapOptions);
+  const requestId = request.headers.get("x-fs-request-id") ?? void 0;
+  const headers = await computeMeteringHeaders(payload, {
+    ...options.token !== void 0 ? { token: options.token } : {},
+    ...options.env !== void 0 ? { env: options.env } : {},
+    ...requestId ? { requestId } : {},
+    onSkip: () => {
+    }
+  });
+  if (Object.keys(headers).length === 0) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.missingToken,
+      `${DEFAULT_TOKEN_ENV} is required to sign Farther Shore metering reports`
+    );
+  }
+  const merged = new Headers(response.headers);
+  for (const [name, value] of Object.entries(headers)) merged.set(name, value);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: merged
+  });
+}
+async function computeMeteringHeaders(payload, options = {}) {
+  try {
+    const token = resolveTokenSoft(options);
+    if (!token) {
+      skip(`${DEFAULT_TOKEN_ENV} is not set`, options);
+      return {};
+    }
+    const json2 = JSON.stringify(payload);
+    const signature = await signPayload(json2, token);
+    devMeteringHooks?.record?.(payload, options.requestId);
+    return {
+      [METERING_PAYLOAD_HEADER]: json2,
+      [METERING_SIGNATURE_HEADER]: signature,
+      [METERING_TOKEN_HEADER]: token
+    };
+  } catch (error) {
+    skip(error instanceof Error ? error.message : String(error), options);
+    return {};
+  }
+}
+function skip(reason, options) {
+  if (options.onSkip) {
+    options.onSkip(reason);
+  } else {
+    console.warn(`metering headers skipped: ${reason}`);
+  }
+  devMeteringHooks?.onSkip?.(reason, options.requestId);
+}
+function resolveTokenSoft(options) {
+  return options.token ?? options.env?.[DEFAULT_TOKEN_ENV] ?? processEnv(DEFAULT_TOKEN_ENV) ?? devMeteringHooks?.fallbackToken?.();
+}
+function buildPayload(request, usage, options, wrapOptions) {
+  const url = new URL(request.url);
+  const measureContext = wrapOptions.measureContext ?? options.measureContext;
+  const creditUnitsConsumed = wrapOptions.creditUnitsConsumed ?? options.creditUnitsConsumed;
+  const operationKey = wrapOptions.operationKey ?? options.operationKey;
+  const usagePolicyId = wrapOptions.usagePolicyId ?? options.usagePolicyId;
+  const payload = {
+    method: request.method.toUpperCase(),
+    path: url.pathname,
+    rawDimsUnits: sortUsage(usage),
+    ...measureContext ? { measureContext } : {},
+    ...creditUnitsConsumed ? {
+      creditUnitsConsumed: sortUsage(
+        validateUsageMap(creditUnitsConsumed, "creditUnitsConsumed")
+      )
+    } : {},
+    ...operationKey ? { operationKey: assertIdentifier(operationKey) } : {},
+    ...usagePolicyId ? { usagePolicyId: assertIdentifier(usagePolicyId) } : {}
+  };
+  return payload;
+}
+function sortUsage(usage) {
+  return Object.fromEntries(
+    Object.entries(usage).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+  );
+}
+function validateUsageMap(usage, label) {
+  return Object.fromEntries(
+    Object.entries(usage).map(([meter, value]) => [
+      assertMeterKey(meter),
+      assertMeterValue(`${label}.${meter}`, value)
+    ])
+  );
+}
+function assertMeterKey(meter) {
+  if (!/^[a-z0-9_]{1,64}$/.test(meter)) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+      `meter key "${meter}" must be lowercase alphanumeric with underscores`
+    );
+  }
+  return meter;
+}
+function assertMeterValue(meter, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
+      `meter "${meter}" value must be a non-negative finite number`
+    );
+  }
+  return value;
+}
+function assertIdentifier(value) {
+  if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(value)) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+      `operation and usage policy identifiers must be 1-128 URL-safe characters`
+    );
+  }
+  return value;
+}
+function processEnv(key2) {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env?.[key2];
+}
+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;
@@ -1583,8 +1877,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.12.0".length > 0 ? "0.12.0" : "0.0.0-dev";
-var CONTRACTS_FP = "220bea90107ed396".length > 0 ? "220bea90107ed396" : "0000000000000000";
+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;
@@ -1602,6 +1896,7 @@ var FartherShore = class {
   shutdownManager = new ShutdownManager();
   jwks = null;
   meteringClient = null;
+  postStreamUsageClient = null;
   tunnel = null;
   bootstrapped = false;
   constructor(options = {}) {
@@ -1657,6 +1952,11 @@ var FartherShore = class {
         coreUrl: this.coreUrl,
         fetchImpl: this.fetchImpl
       });
+      this.postStreamUsageClient = new PostStreamUsageClient({
+        config: config.metering,
+        coreUrl: this.coreUrl,
+        fetchImpl: this.fetchImpl
+      });
     }
     this.bootstrapped = true;
     return config;
@@ -1728,7 +2028,7 @@ var FartherShore = class {
       );
     }
     const knownRouteIds = new Set(config.routes.map((r) => r.id));
-    return verifyRequest(input, {
+    const context = await verifyRequest(input, {
       jwks: this.jwks,
       nonceCache: this.nonceCache,
       productId: config.product.id,
@@ -1743,6 +2043,23 @@ var FartherShore = class {
       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() {
@@ -1803,6 +2120,20 @@ var FartherShore = class {
     }
     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();
@@ -1903,157 +2234,772 @@ function headerValue(headers, name) {
   return value;
 }
 
-// src/response-metering.ts
-var RESPONSE_METERING_HEADERS = RUNTIME_RESPONSE_METERING_CONTRACT.headers;
-var RESPONSE_METERING_ERROR_CODES = RUNTIME_RESPONSE_METERING_CONTRACT.errors;
-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;
-var MeteringError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "MeteringError";
-    this.code = code;
-  }
+// src/testing/signers.ts
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+var TEST_KID = "fs-runtime-test-2026";
+var TEST_PRIVATE_JWK = {
+  kty: "OKP",
+  crv: "Ed25519",
+  d: "nWGxne_9WmC6hEr0kuwsxERJxWl7MmkZcDusAxyuf2A",
+  x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
 };
-function createUsage(request, options = {}) {
-  const usage = {};
-  const reporter = {
-    report(meter, value) {
-      usage[assertMeterKey(meter)] = assertMeterValue(meter, value);
-      return reporter;
-    },
-    async wrap(response, wrapOptions = {}) {
-      return signResponse(request, response, usage, options, wrapOptions);
-    }
+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
   };
-  return reporter;
 }
-async function withUsage(request, response, usage, options = {}) {
-  const reporter = createUsage(request, options);
-  for (const [meter, value] of Object.entries(usage)) {
-    reporter.report(meter, value);
-  }
-  return reporter.wrap(response);
+function base64urlEncodeBytes(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-async function signResponse(request, response, usage, options, wrapOptions) {
-  const token = resolveToken(options);
-  const payload = buildPayload(request, usage, options, wrapOptions);
-  const signature = await signPayload(payload, token);
-  const headers = new Headers(response.headers);
-  headers.set(METERING_PAYLOAD_HEADER, payload);
-  headers.set(METERING_SIGNATURE_HEADER, signature);
-  headers.set(METERING_TOKEN_HEADER, token);
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers
-  });
+function base64urlEncodeJson(value) {
+  return base64urlEncodeBytes(new TextEncoder().encode(JSON.stringify(value)));
 }
-function buildPayload(request, usage, options, wrapOptions) {
-  const url = new URL(request.url);
-  const measureContext = wrapOptions.measureContext ?? options.measureContext;
-  const creditUnitsConsumed = wrapOptions.creditUnitsConsumed ?? options.creditUnitsConsumed;
-  const operationKey = wrapOptions.operationKey ?? options.operationKey;
-  const usagePolicyId = wrapOptions.usagePolicyId ?? options.usagePolicyId;
-  const payload = {
-    method: request.method.toUpperCase(),
-    path: url.pathname,
-    rawDimsUnits: sortUsage(usage),
-    ...measureContext ? { measureContext } : {},
-    ...creditUnitsConsumed ? {
-      creditUnitsConsumed: sortUsage(
-        validateUsageMap(creditUnitsConsumed, "creditUnitsConsumed")
-      )
-    } : {},
-    ...operationKey ? { operationKey: assertIdentifier(operationKey) } : {},
-    ...usagePolicyId ? { usagePolicyId: assertIdentifier(usagePolicyId) } : {}
+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
   };
-  return JSON.stringify(payload);
 }
-function sortUsage(usage) {
-  return Object.fromEntries(
-    Object.entries(usage).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
-  );
+function cryptoRandom() {
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 16);
 }
-function validateUsageMap(usage, label) {
-  return Object.fromEntries(
-    Object.entries(usage).map(([meter, value]) => [
-      assertMeterKey(meter),
-      assertMeterValue(`${label}.${meter}`, value)
-    ])
-  );
+
+// 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 assertMeterKey(meter) {
-  if (!/^[a-z0-9_]{1,64}$/.test(meter)) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
-      `meter key "${meter}" must be lowercase alphanumeric with underscores`
-    );
+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 meter;
+  return headers;
 }
-function assertMeterValue(meter, value) {
-  if (!Number.isFinite(value) || value < 0) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
-      `meter "${meter}" value must be a non-negative finite number`
-    );
+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;
   }
-  return value;
+  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 assertIdentifier(value) {
-  if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(value)) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
-      `operation and usage policy identifiers must be 1-128 URL-safe characters`
+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;
+}
+
+// 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 value;
+  return null;
 }
-function resolveToken(options) {
-  const token = options.token ?? options.env?.[DEFAULT_TOKEN_ENV] ?? processEnv(DEFAULT_TOKEN_ENV);
-  if (!token) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.missingToken,
-      `${DEFAULT_TOKEN_ENV} is required to sign Farther Shore metering reports`
+
+// src/testing/devRuntime.ts
+import { appendFileSync, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+
+// 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);
   }
-  return token;
 }
-function processEnv(key2) {
+function readProcessEnv2() {
   const maybeProcess = globalThis.process;
-  return maybeProcess?.env?.[key2];
+  return maybeProcess?.env ?? {};
 }
-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)
+
+// 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);
+}
+
+// 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 } : {}
   );
-  return base64url(new Uint8Array(signature));
+  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 base64url(bytes) {
-  let binary = "";
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte);
+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;
   }
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+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) };
 }
 
 // src/index.ts
+function readProcessEnv4() {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env ?? {};
+}
 var fartherShore = {
   /** Derive everything from FS_RUNTIME_TOKEN via bootstrap. */
   initFromEnv(options = {}) {
+    const env = options.env ?? readProcessEnv4();
+    if (devModeFromEnv(env)) {
+      return createDevRuntimeFromEnv(env);
+    }
     const fs = initFromEnv(options);
     fs.middleware = (mwOptions) => createExpressMiddleware(fs, mwOptions);
     return fs;
@@ -2080,6 +3026,7 @@ export {
   MeteringClient,
   MeteringError,
   NonceCache,
+  PostStreamUsageClient,
   REDACTED_TOKEN,
   RUNTIME_CLOCK_SKEW_SECONDS,
   RUNTIME_ERROR_CODES,
@@ -2093,6 +3040,7 @@ export {
   buildCanonicalSigningString2 as buildCanonicalSigningString,
   buildHealthReport,
   canonicalizeQuery2 as canonicalizeQuery,
+  computeMeteringHeaders,
   createExpressMiddleware,
   createUsage,
   fartherShore,