@farthershore/backend 0.1.0

package/dist/index.js

@@ -0,0 +1,1496 @@
+import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+
+// src/runtime-types.ts
+var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
+var RUNTIME_TOKEN_PREFIXES = {
+  live: "fsrt_live_",
+  test: "fsrt_test_"
+};
+var RUNTIME_TOKEN_CAPABILITIES = [
+  "gateway_verification",
+  "metering",
+  "health",
+  "tunnel"
+];
+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_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 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 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 key = await importEd25519PrivateKey(privateJwk);
+  const sig = await crypto.subtle.sign(ED25519_ALGORITHM, key, new TextEncoder().encode(canonical));
+  return base64UrlEncode(new Uint8Array(sig));
+}
+async function verifyCanonicalSignature(canonical, signatureB64Url, publicJwk) {
+  const key = await importEd25519PublicKey(publicJwk);
+  return crypto.subtle.verify(ED25519_ALGORITHM, key, 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 canonicalizeQuery2 = canonicalizeQuery;
+var buildCanonicalSigningString2 = buildCanonicalSigningString;
+var signCanonicalString2 = signCanonicalString;
+var verifyCanonicalSignature2 = verifyCanonicalSignature;
+var runtimeTokenKind2 = runtimeTokenKind;
+
+// src/core/errors.ts
+var FartherShoreError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.name = "FartherShoreError";
+    this.code = code;
+    this.status = status ?? statusForCode(code);
+  }
+};
+function statusForCode(code) {
+  return code === "body_too_large" ? 413 : 401;
+}
+
+// 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/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 key = this.keysByKid.get(kid);
+    if (key) {
+      this.negativeKids.delete(kid);
+      return key;
+    }
+    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 key of doc.keys ?? []) {
+      if (typeof key.kid === "string") next.set(key.kid, key);
+    }
+    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/core/metering.ts
+var METER_KEY_RE = /^[a-z0-9_]{1,64}$/;
+var DEFAULT_MAX_RETRIES = 3;
+var MeteringClient = class {
+  config;
+  endpoint;
+  productId;
+  backendId;
+  fetchImpl;
+  maxRetries;
+  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.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 (options.routeId && this.config.allowedRoutes.length > 0 && !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) {
+      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 (response.status >= 400 && response.status < 500 && response.status !== 429) {
+          return true;
+        }
+      } catch {
+      }
+    }
+    return false;
+  }
+};
+function resolveEndpoint(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";
+var REDACTED_TOKEN = "***REDACTED***";
+var CLOUDFLARED_RUN_ARGS = [
+  "tunnel",
+  "--no-autoupdate",
+  "run",
+  "--token"
+];
+var DEFAULT_BINARY_CANDIDATES = [
+  "cloudflared",
+  "/usr/local/bin/cloudflared",
+  "/usr/bin/cloudflared",
+  "/opt/cloudflared/cloudflared"
+];
+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;
+  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.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. Explicit `binaryPath` wins; otherwise
+   * the injected locator runs (Linux-first). Missing ⇒ a clear, redacted error.
+   */
+  resolveBinary() {
+    if (this.binaryPath) return this.binaryPath;
+    const located = this.locateBinary();
+    if (located) return located;
+    throw new Error(
+      "cloudflared binary not found \u2014 install it in the image, supply binaryPath, or run the sidecar runner instead. (Linux container is the V1 supported target.)"
+    );
+  }
+  /** 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 defaultLocateBinary() {
+  return DEFAULT_BINARY_CANDIDATES[0] ?? DEFAULT_BINARY;
+}
+
+// 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)"
+    );
+  }
+  return {
+    requestId,
+    productId: signedProductId,
+    backendId: signedBackendId,
+    routeId: signedRouteId,
+    policyVersion,
+    timestamp,
+    bodyHash: computedBodyHash
+  };
+}
+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 [key, value] of Object.entries(
+    headers
+  )) {
+    if (value === void 0) continue;
+    lower.set(
+      key.toLowerCase(),
+      Array.isArray(value) ? value[0] ?? "" : value
+    );
+  }
+  return (name) => lower.get(name.toLowerCase());
+}
+
+// src/core/runtime.ts
+var DEFAULT_CORE_URL = "https://api.farthershore.com";
+var SDK_VERSION = "0.1.0";
+var FartherShore = class {
+  bootstrapClient;
+  fetchImpl;
+  verificationEnabled;
+  meteringEnabledOverride;
+  runtimeToken;
+  coreUrl;
+  instanceId;
+  tunnelOptions;
+  nonceCache = new NonceCache();
+  shutdownManager = new ShutdownManager();
+  jwks = null;
+  meteringClient = 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.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.bootstrapped = true;
+    return config;
+  }
+  /**
+   * 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));
+    return 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
+    });
+  }
+  /** 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 managed runner. For a `cloudflare_tunnel` backend whose runner is
+   * `managed_cloudflared`, this supervises `cloudflared` as a child process
+   * (spawned via the injected/default spawner) using the tunnel token from
+   * bootstrap. For every other transport (`public_origin`, `mtls`, 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 !== "cloudflare_tunnel" || transport.runner !== "managed_cloudflared") {
+      return;
+    }
+    const tunnelToken = transport.cloudflared?.tunnelToken;
+    if (!tunnelToken) {
+      if (this.tunnelOptions.failClosed) {
+        throw new FartherShoreError(
+          "invalid_token",
+          "managed 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);
+  }
+  /** 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 managed-cloudflared supervisor (Slice 3). Null until
+      // fs.start() launches a managed 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 ?? {};
+}
+
+// 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"
+};
+
+// 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/generated/metering-contract.ts
+var METERING_HEADERS = {
+  payload: "x-fs-metering",
+  signature: "x-fs-metering-sig",
+  token: "x-fs-metering-token"
+};
+var METERING_TOKEN_ENV = "FARTHERSHORE_METERING_TOKEN";
+var METERING_ERROR_CODES = {
+  missingToken: "missing_token",
+  invalidMeterKey: "invalid_meter_key",
+  invalidMeterValue: "invalid_meter_value"
+};
+
+// src/legacy/metering.ts
+var METERING_PAYLOAD_HEADER = METERING_HEADERS.payload;
+var METERING_SIGNATURE_HEADER = METERING_HEADERS.signature;
+var METERING_TOKEN_HEADER = METERING_HEADERS.token;
+var DEFAULT_TOKEN_ENV = METERING_TOKEN_ENV;
+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) {
+      return signResponse(request, response, usage, options);
+    }
+  };
+  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) {
+  const token = resolveToken(options);
+  const payload = buildPayload(request, usage);
+  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 buildPayload(request, usage) {
+  const url = new URL(request.url);
+  const payload = {
+    method: request.method.toUpperCase(),
+    path: url.pathname,
+    rawDimsUnits: sortUsage(usage)
+  };
+  return JSON.stringify(payload);
+}
+function sortUsage(usage) {
+  return Object.fromEntries(
+    Object.entries(usage).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+  );
+}
+function assertMeterKey(meter) {
+  if (!/^[a-z0-9_]{1,64}$/.test(meter)) {
+    throw new MeteringError(
+      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(
+      METERING_ERROR_CODES.invalidMeterValue,
+      `meter "${meter}" value must be a non-negative finite number`
+    );
+  }
+  return value;
+}
+function resolveToken(options) {
+  const token = options.token ?? options.env?.[DEFAULT_TOKEN_ENV] ?? processEnv(DEFAULT_TOKEN_ENV);
+  if (!token) {
+    throw new MeteringError(
+      METERING_ERROR_CODES.missingToken,
+      `${DEFAULT_TOKEN_ENV} is required to sign Farther Shore metering reports`
+    );
+  }
+  return token;
+}
+function processEnv(key) {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env?.[key];
+}
+async function signPayload(payload, token) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(token),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    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/index.ts
+var fartherShore = {
+  /** Derive everything from FS_RUNTIME_TOKEN via bootstrap. */
+  initFromEnv(options = {}) {
+    const fs = initFromEnv(options);
+    fs.middleware = (mwOptions) => createExpressMiddleware(fs, mwOptions);
+    return fs;
+  }
+};
+function initFromEnv2(options = {}) {
+  return fartherShore.initFromEnv(options);
+}
+export {
+  BootstrapClient,
+  CloudflaredSupervisor,
+  DEFAULT_TOKEN_ENV,
+  EMPTY_BODY_SHA256,
+  FS_RUNTIME_TOKEN_ENV,
+  FartherShore,
+  FartherShoreError,
+  JwksClient,
+  MAX_BODY_BYTES,
+  METERING_PAYLOAD_HEADER,
+  METERING_SIGNATURE_HEADER,
+  METERING_TOKEN_HEADER,
+  MeteringClient,
+  MeteringError,
+  NonceCache,
+  REDACTED_TOKEN,
+  RUNTIME_CLOCK_SKEW_SECONDS,
+  RUNTIME_ERROR_CODES,
+  RUNTIME_HEADER_NAMES,
+  RUNTIME_REPLAY_WINDOW_SECONDS,
+  RUNTIME_TOKEN_CAPABILITIES,
+  RUNTIME_TOKEN_PREFIXES,
+  STREAMING_EXEMPT_BODY_HASH,
+  ShutdownManager,
+  buildCanonicalSigningString2 as buildCanonicalSigningString,
+  buildHealthReport,
+  canonicalizeQuery2 as canonicalizeQuery,
+  createExpressMiddleware,
+  createUsage,
+  fartherShore,
+  hashBody2 as hashBody,
+  initFromEnv2 as initFromEnv,
+  nodeSpawn,
+  reportHealth,
+  runtimeTokenKind2 as runtimeTokenKind,
+  signCanonicalString2 as signCanonicalString,
+  statusForCode,
+  verifyCanonicalSignature2 as verifyCanonicalSignature,
+  verifyRequest,
+  withUsage
+};