@farthershore/backend 0.19.0 → 0.21.0

package/dist/internal/index.js

@@ -0,0 +1,587 @@
+import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+
+// src/generated/runtime-contract.ts
+var RUNTIME_RESPONSE_METERING_CONTRACT = {
+  headers: {
+    payload: "x-fs-metering",
+    signature: "x-fs-metering-sig",
+    token: "x-fs-metering-token"
+  },
+  token: {
+    environmentVariable: "FS_RUNTIME_TOKEN",
+    presentation: "x-fs-metering-token",
+    storage: "sha256-hash-only"
+  },
+  signature: {
+    algorithm: "HMAC-SHA256",
+    encoding: "base64url",
+    input: "payload-json",
+    secret: "presented-runtime-token"
+  },
+  payload: {
+    method: "string",
+    path: "string",
+    rawDimsUnits: "Record<string, number>?",
+    measureContext: "Record<string, unknown>?",
+    creditUnitsConsumed: "Record<string, number>?",
+    measurementsVersion: "1?",
+    measurements: "Array<{ meter: string; values: Record<string, number>; dims?: Record<string, string> }>?",
+    quote: "{ currency: string; amountNanos: string }?"
+  },
+  errors: {
+    missingToken: "missing_token",
+    invalidMeterKey: "invalid_meter_key",
+    invalidMeterValue: "invalid_meter_value",
+    invalidQuote: "invalid_quote"
+  },
+  httpAdapter: {
+    input: "Request",
+    output: "Response",
+    networkCalls: false,
+    preserves: ["body", "headers", "status", "statusText"],
+    gatewayStripsInternalHeaders: true
+  }
+};
+
+// 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;
+  }
+};
+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/core/report.ts
+var MEASUREMENTS_VERSION = 1;
+var KEY_RE = /^[a-z0-9_]{1,64}$/;
+var DIMENSION_VALUE_RE = /^[\w.:-]{1,128}$/;
+var CURRENCY_RE = /^[A-Za-z]{3}$/;
+var DECIMAL_INTEGER_RE = /^\d{1,30}$/;
+function createReportFn(channels) {
+  let stampedMeasurements = [];
+  let stampedQuote;
+  let inBandTail = Promise.resolve();
+  let postStreamFinalized = false;
+  let pendingPostStreamBatch = null;
+  const deliverPostStream = async (reported, quote) => {
+    if (pendingPostStreamBatch) {
+      if (!quotesEqual(pendingPostStreamBatch.quote, quote)) {
+        return {
+          ok: false,
+          transport: "post_stream",
+          reason: "quote conflicts with this request's pending post-stream batch: one served request carries one quote across all measurements"
+        };
+      }
+      if (reported.some(
+        (measurement) => !dimsEqual(
+          pendingPostStreamBatch.measurements[0]?.dims,
+          measurement.dims
+        )
+      )) {
+        return {
+          ok: false,
+          transport: "post_stream",
+          reason: "dims conflict with this request's pending post-stream batch: the request receipt rates under ONE dims tuple"
+        };
+      }
+      pendingPostStreamBatch.measurements.push(...reported);
+      return pendingPostStreamBatch.flush;
+    }
+    if (postStreamFinalized) {
+      return {
+        ok: false,
+        transport: "post_stream",
+        reason: "the served request already used its post-stream callback; report multiple meters in ONE call \u2014 ctx.report([a, b]) \u2014 or before the flush"
+      };
+    }
+    if (stampedMeasurements.length > 0) {
+      return {
+        ok: false,
+        transport: "post_stream",
+        reason: "this request already reported in-band; every report on one request must share the stamped aggregate (same quote, before the response is sent)"
+      };
+    }
+    postStreamFinalized = true;
+    const batch = {
+      measurements: [...reported],
+      quote,
+      flush: void 0
+    };
+    batch.flush = new Promise((resolve) => setTimeout(resolve, 0)).then(
+      async () => {
+        pendingPostStreamBatch = null;
+        const result = await channels.postStream({
+          measurements: batch.measurements,
+          ...batch.quote ? { quote: batch.quote } : {}
+        });
+        return result.ok ? { ok: true, transport: "post_stream" } : {
+          ok: false,
+          transport: "post_stream",
+          reason: result.reason ?? "post-stream delivery failed"
+        };
+      }
+    );
+    pendingPostStreamBatch = batch;
+    return batch.flush;
+  };
+  const tryInBand = (reported, quote) => {
+    const run = inBandTail.then(async () => {
+      const sink = channels.responseSink;
+      if (!sink || !channels.request || !sink.canStampHeaders()) return null;
+      if (postStreamFinalized) return null;
+      if (!quotesEqual(stampedQuote, quote) && stampedMeasurements.length > 0) {
+        return null;
+      }
+      if (stampedMeasurements.length > 0 && reported.some(
+        (measurement) => !dimsEqual(stampedMeasurements[0].dims, measurement.dims)
+      )) {
+        return null;
+      }
+      const measurements = [...stampedMeasurements, ...reported];
+      const payload = buildInBandPayload(channels.request, measurements, quote);
+      const headers = await channels.computeHeaders(payload);
+      if (Object.keys(headers).length === 0 || !sink.canStampHeaders()) {
+        return null;
+      }
+      sink.stampHeaders(headers);
+      stampedMeasurements = measurements;
+      stampedQuote = quote;
+      return { ok: true, transport: "in_band" };
+    });
+    inBandTail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  };
+  return async (input) => {
+    const inputs = Array.isArray(input) ? input : [input];
+    if (inputs.length === 0) {
+      throw new MeteringError(
+        RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+        "report([]) is empty: a batched report needs at least one measurement"
+      );
+    }
+    const measurements = inputs.map((entry) => validateMeasurement(entry));
+    for (const measurement of measurements) {
+      if (!dimsEqual(measurements[0].dims, measurement.dims)) {
+        throw new MeteringError(
+          RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
+          "a batched report carries ONE dims tuple: the request receipt rates under (route, dims), so mixed dims are unratable \u2014 report each dims tuple on its own request"
+        );
+      }
+    }
+    let quote;
+    for (const entry of inputs) {
+      if (entry.quote === void 0) continue;
+      const validated = validateQuote(entry.quote);
+      if (quote === void 0) {
+        quote = validated;
+      } else if (!quotesEqual(quote, validated)) {
+        throw new MeteringError(
+          RESPONSE_METERING_ERROR_CODES.invalidQuote,
+          "a batched report carries ONE quote: two entries supplied different quotes"
+        );
+      }
+    }
+    const inBand = await tryInBand(measurements, quote);
+    if (inBand) return inBand;
+    return deliverPostStream(measurements, quote);
+  };
+}
+function rawDimsUnitsOf(measurement) {
+  let total = 0;
+  for (const value of Object.values(measurement.values)) total += value;
+  return { [measurement.meter]: total };
+}
+function buildInBandPayload(request, measurements, quote) {
+  const rawDimsUnits = {};
+  for (const measurement of measurements) {
+    for (const [meter, units] of Object.entries(rawDimsUnitsOf(measurement))) {
+      rawDimsUnits[meter] = (rawDimsUnits[meter] ?? 0) + units;
+    }
+  }
+  return {
+    method: request.method.toUpperCase(),
+    path: request.path,
+    rawDimsUnits,
+    measurementsVersion: MEASUREMENTS_VERSION,
+    measurements,
+    ...quote ? { quote } : {}
+  };
+}
+function dimsEqual(left, right) {
+  const l = Object.entries(left ?? {}).sort(([a], [b]) => a < b ? -1 : 1);
+  const r = Object.entries(right ?? {}).sort(([a], [b]) => a < b ? -1 : 1);
+  if (l.length !== r.length) return false;
+  return l.every(([k, v], i) => r[i][0] === k && r[i][1] === v);
+}
+function quotesEqual(left, right) {
+  return left === right || left !== void 0 && right !== void 0 && left.currency === right.currency && left.amountNanos === right.amountNanos;
+}
+function validateMeasurement(input) {
+  if (!input || typeof input !== "object") {
+    throw invalidKey("report() requires a { meter, values } object");
+  }
+  const meter = assertKey(input.meter, "meter");
+  const values = assertValues(input.values);
+  const dims = input.dims === void 0 ? void 0 : assertDims(input.dims);
+  return {
+    meter,
+    values,
+    ...dims && Object.keys(dims).length > 0 ? { dims } : {}
+  };
+}
+function validateQuote(quote) {
+  if (!quote || typeof quote !== "object" || Array.isArray(quote)) {
+    throw invalidQuote(
+      "quote must be an object of the form { currency, amountNanos }"
+    );
+  }
+  const { currency, amountNanos } = quote;
+  if (typeof currency !== "string" || !CURRENCY_RE.test(currency)) {
+    throw invalidQuote("quote.currency must be a 3-letter currency code");
+  }
+  return {
+    currency: currency.toLowerCase(),
+    amountNanos: assertAmountNanos(amountNanos)
+  };
+}
+function assertAmountNanos(value) {
+  if (typeof value === "bigint") {
+    if (value < 0n) throw negativeAmountNanos();
+    return value.toString();
+  }
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) {
+      throw invalidQuote(
+        "quote.amountNanos must be a safe integer number of nanodollars (pass a string or bigint for larger amounts)"
+      );
+    }
+    if (value < 0) throw negativeAmountNanos();
+    return String(value);
+  }
+  if (typeof value === "string") {
+    if (/^-/.test(value)) throw negativeAmountNanos();
+    if (DECIMAL_INTEGER_RE.test(value)) return value;
+  }
+  throw invalidQuote(
+    "quote.amountNanos must be a non-negative integer number of nanodollars"
+  );
+}
+function negativeAmountNanos() {
+  return invalidQuote(
+    "quote.amountNanos must be non-negative: a quote is a proposed rate, never a credit \u2014 refunds are platform operations"
+  );
+}
+function assertValues(values) {
+  if (!values || typeof values !== "object" || Array.isArray(values)) {
+    throw invalidKey("report() requires a values object");
+  }
+  const entries = Object.entries(values).sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  );
+  if (entries.length === 0) {
+    throw invalidKey("report() requires at least one measure in values");
+  }
+  const out = {};
+  for (const [measure, value] of entries) {
+    assertKey(measure, "measure");
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+      throw new MeteringError(
+        RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
+        `values.${measure} must be a non-negative safe integer`
+      );
+    }
+    out[measure] = value;
+  }
+  return out;
+}
+function assertDims(dims) {
+  if (!dims || typeof dims !== "object" || Array.isArray(dims)) {
+    throw invalidKey("report() dims must be an object of dimension selectors");
+  }
+  const entries = Object.entries(dims).sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  );
+  const out = {};
+  for (const [dimension, value] of entries) {
+    assertKey(dimension, "dimension");
+    if (typeof value !== "string" || !DIMENSION_VALUE_RE.test(value)) {
+      throw invalidKey(
+        `dims.${dimension} must be a 1-128 character selector value`
+      );
+    }
+    out[dimension] = value;
+  }
+  return out;
+}
+function assertKey(value, label) {
+  if (typeof value !== "string" || !KEY_RE.test(value)) {
+    throw invalidKey(
+      `${label} key ${JSON.stringify(value)} must be 1-64 lowercase alphanumeric characters or underscores`
+    );
+  }
+  return value;
+}
+function invalidKey(message) {
+  return new MeteringError(
+    RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+    message
+  );
+}
+function invalidQuote(message) {
+  return new MeteringError(RESPONSE_METERING_ERROR_CODES.invalidQuote, message);
+}
+
+// src/core/deadline.ts
+var DEADLINE_MS = {
+  /** Boot-blocking; generous because it runs once and gates startup. */
+  bootstrap: 1e4,
+  /** On the inbound verification path — must not hold a request open. */
+  jwks: 5e3,
+  /** Background economic report, retried by the caller. */
+  metering: 1e4,
+  /** Background attested usage callback. */
+  postStreamUsage: 1e4,
+  /** Best-effort heartbeat; never blocks anything. */
+  health: 5e3,
+  /** Boot-time route drift report; fail-open at the caller. */
+  report: 1e4
+};
+var DeadlineExceededError = class extends Error {
+  operation;
+  constructor(operation, timeoutMs) {
+    super(`${operation} exceeded its ${timeoutMs}ms deadline`);
+    this.name = "TimeoutError";
+    this.operation = operation;
+  }
+};
+async function fetchWithDeadline(fetchImpl, input, init, operation, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEADLINE_MS[operation];
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const signal = options.callerSignal ? AbortSignal.any([options.callerSignal, timeout]) : timeout;
+  try {
+    return await fetchImpl(input, { ...init, signal });
+  } catch (cause) {
+    if (options.callerSignal?.aborted) throw cause;
+    if (timeout.aborted) throw new DeadlineExceededError(operation, timeoutMs);
+    throw cause;
+  }
+}
+
+// src/core/post-stream-usage.ts
+var METER_KEY_RE = /^[a-z0-9_]{1,64}$/;
+var PostStreamUsageClient = class {
+  config;
+  endpoint;
+  fetchImpl;
+  newNonce;
+  logger;
+  sleep;
+  retryDelaysMs;
+  maxRetryDelayMs;
+  constructor(options) {
+    this.config = options.config;
+    this.endpoint = resolveEndpoint(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];
+    this.maxRetryDelayMs = options.maxRetryDelayMs ?? 1e4;
+  }
+  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(),
+        // The token's `allowedMeters` scope is enforced on BOTH lanes
+        // independently (P0-1): `meters` is the flat METER-keyed projection
+        // (the billed lane), so its keys must be in scope regardless of
+        // whether the measurement lane is also present; `measurements[].meter`
+        // is scoped in validateMeasurements below.
+        meters: validateAndSortUsage(input.meters, "meters", this.config, true),
+        ...input.creditUnitsConsumed ? {
+          creditUnitsConsumed: validateAndSortUsage(
+            input.creditUnitsConsumed,
+            "creditUnitsConsumed",
+            this.config,
+            false
+          )
+        } : {},
+        ...input.measureContext ? { measureContext: input.measureContext } : {},
+        // Key ORDER is load-bearing: core recomputes the HMAC over
+        // JSON.stringify(unsigned) rebuilt in its zod schema's field order, so
+        // these additive fields must sit in the same position on both sides.
+        ...input.measurementsVersion !== void 0 ? { measurementsVersion: input.measurementsVersion } : {},
+        ...input.measurements ? { measurements: this.validateMeasurements(input.measurements) } : {},
+        ...input.quote ? { quote: input.quote } : {}
+      };
+      const signature = await signPayload(
+        JSON.stringify(unsigned),
+        this.config.credential
+      );
+      const event = { ...unsigned, signature };
+      const body = JSON.stringify(event);
+      const headerSignature = await signPayload(body, this.config.credential);
+      for (let attempt = 0; ; attempt += 1) {
+        let response;
+        try {
+          response = await fetchWithDeadline(
+            this.fetchImpl,
+            this.endpoint,
+            {
+              method: "POST",
+              headers: {
+                authorization: `Bearer ${this.config.credential}`,
+                "content-type": "application/json",
+                accept: "application/json",
+                [RUNTIME_RESPONSE_METERING_CONTRACT.headers.signature]: headerSignature
+              },
+              body
+            },
+            "postStreamUsage"
+          );
+        } catch (cause) {
+          const delayMs2 = this.retryDelayForAttempt(attempt, null);
+          if (delayMs2 === null) throw cause;
+          await this.sleep(delayMs2);
+          continue;
+        }
+        if (response.ok) return { ok: true };
+        const requestNotFound = await isPostStreamRequestNotFound(response);
+        const retryable = requestNotFound || isRetryableStatus(response.status);
+        const delayMs = this.retryDelayForAttempt(
+          attempt,
+          retryAfterMs(response.headers)
+        );
+        if (!retryable || delayMs === null) {
+          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 };
+    }
+  }
+  /** Enforce the token's meter scope + per-event bounds on the measurement lane. */
+  validateMeasurements(measurements) {
+    const allowed = this.config.allowedMeters;
+    for (const measurement of measurements) {
+      if (allowed.length > 0 && !allowed.includes(measurement.meter)) {
+        throw new Error(
+          `meter '${measurement.meter}' is not in the token's allowedMeters`
+        );
+      }
+      for (const [measure, value] of Object.entries(measurement.values)) {
+        if (this.config.perEventMax > 0 && value > this.config.perEventMax) {
+          throw new Error(
+            `measure '${measure}' value ${value} exceeds the per-event max ${this.config.perEventMax}`
+          );
+        }
+      }
+    }
+    return measurements;
+  }
+  retryDelayForAttempt(attempt, retryAfterMs2) {
+    const fallback = this.retryDelaysMs[attempt];
+    if (fallback === void 0) return null;
+    if (retryAfterMs2 === null) return fallback;
+    return Math.min(retryAfterMs2, this.maxRetryDelayMs);
+  }
+};
+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 isRetryableStatus(status) {
+  return status === 429 || status >= 500 && status <= 599;
+}
+function retryAfterMs(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const dateMs = Date.parse(raw);
+  if (!Number.isFinite(dateMs)) return null;
+  return Math.max(0, dateMs - Date.now());
+}
+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_RE.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 resolveEndpoint(endpoint, coreUrl) {
+  if (/^https?:\/\//.test(endpoint)) return endpoint;
+  if (!coreUrl) return endpoint;
+  return `${coreUrl.replace(/\/+$/, "")}${endpoint}`;
+}
+export {
+  PostStreamUsageClient,
+  createReportFn,
+  rawDimsUnitsOf
+};