@farthershore/backend 0.12.0 → 0.13.0

package/dist/index.js

@@ -1583,7 +1583,7 @@ 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 SDK_VERSION = "0.13.0".length > 0 ? "0.13.0" : "0.0.0-dev";
 var CONTRACTS_FP = "220bea90107ed396".length > 0 ? "220bea90107ed396" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
@@ -1906,6 +1906,10 @@ function headerValue(headers, name) {
 // 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;
@@ -1939,19 +1943,60 @@ async function withUsage(request, response, usage, options = {}) {
   return reporter.wrap(response);
 }
 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);
+  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
+    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;
@@ -1971,7 +2016,7 @@ function buildPayload(request, usage, options, wrapOptions) {
     ...operationKey ? { operationKey: assertIdentifier(operationKey) } : {},
     ...usagePolicyId ? { usagePolicyId: assertIdentifier(usagePolicyId) } : {}
   };
-  return JSON.stringify(payload);
+  return payload;
 }
 function sortUsage(usage) {
   return Object.fromEntries(
@@ -2013,16 +2058,6 @@ function assertIdentifier(value) {
   }
   return value;
 }
-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`
-    );
-  }
-  return token;
-}
 function processEnv(key2) {
   const maybeProcess = globalThis.process;
   return maybeProcess?.env?.[key2];
@@ -2050,10 +2085,753 @@ function base64url(bytes) {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
+// 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"
+};
+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 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;
+}
+
+// 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 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) {
+        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,
+    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/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()
+    });
+  }
+  /** 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 } : {}
+  );
+  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 }));
+    }
+  });
+  __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) };
+}
+
 // 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;
@@ -2093,6 +2871,7 @@ export {
   buildCanonicalSigningString2 as buildCanonicalSigningString,
   buildHealthReport,
   canonicalizeQuery2 as canonicalizeQuery,
+  computeMeteringHeaders,
   createExpressMiddleware,
   createUsage,
   fartherShore,