@farthershore/backend 0.1.0

package/dist/types/adapters/express.d.ts

@@ -0,0 +1,37 @@
+import type { FartherShore } from "../core/runtime.js";
+import type { FartherShoreRequestContext } from "../core/verifyRequest.js";
+/** Minimal Express-shaped types so we don't hard-depend on @types/express. */
+export type ExpressRequestLike = {
+    method: string;
+    /** Original URL incl. query, e.g. "/v1/x?a=1". */
+    originalUrl?: string;
+    url?: string;
+    path?: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** Raw body bytes if captured by an upstream raw parser. */
+    rawBody?: Buffer | Uint8Array;
+    body?: unknown;
+    fartherShore?: FartherShoreRequestContext;
+};
+export type ExpressResponseLike = {
+    status(code: number): ExpressResponseLike;
+    json(body: unknown): unknown;
+    setHeader(name: string, value: string): void;
+};
+export type ExpressNext = (err?: unknown) => void;
+export type ExpressMiddleware = (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNext) => void;
+export type MiddlewareOptions = {
+    /**
+     * When true (default), a request is verified only if verification is REQUIRED
+     * by bootstrap. While verificationRequired=false (pre-keystone) the middleware
+     * passes requests through WITHOUT attaching a context — matching the deploy
+     * order where the signer is not yet live. Set `always: true` to verify
+     * regardless (the readiness harness / strict deployments).
+     */
+    always?: boolean;
+};
+/**
+ * Build the Express middleware. Captures raw body bytes, calls verifyRequest,
+ * and fail-closes on any error.
+ */
+export declare function createExpressMiddleware(fs: FartherShore, options?: MiddlewareOptions): ExpressMiddleware;

package/dist/types/core/bootstrap.d.ts

@@ -0,0 +1,40 @@
+import { type RuntimeBootstrapRequest, type RuntimeBootstrapResponse } from "../runtime-types.js";
+/** Where to reach core's bootstrap endpoint. Derived from the token's coreUrl. */
+export type BootstrapClientOptions = {
+    runtimeToken: string;
+    /** Core base URL, e.g. https://api.farthershore.com. */
+    coreUrl: string;
+    /** Optional bootstrap request metadata. */
+    request?: RuntimeBootstrapRequest;
+    /** Injectable fetch (tests). */
+    fetchImpl?: typeof fetch;
+    /** Injectable clock in ms (tests). */
+    now?: () => number;
+    /** Minimum seconds between refreshes regardless of server hint. */
+    minRefreshSeconds?: number;
+};
+/**
+ * Caches the bootstrap response and refreshes it lazily. `get()` returns the
+ * cached value when fresh, otherwise refreshes (single-flight).
+ */
+export declare class BootstrapClient {
+    private readonly runtimeToken;
+    private readonly endpoint;
+    private readonly request;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly minRefreshSeconds;
+    private cached;
+    private fetchedAt;
+    private refreshAfterMs;
+    private inflight;
+    constructor(options: BootstrapClientOptions);
+    /** Cached config when fresh; otherwise refreshes. */
+    get(): Promise<RuntimeBootstrapResponse>;
+    /** Force a network refresh (single-flight). */
+    refresh(): Promise<RuntimeBootstrapResponse>;
+    /** Last cached value without triggering a refresh (null until bootstrapped). */
+    peek(): RuntimeBootstrapResponse | null;
+    private isStale;
+    private doBootstrap;
+}

package/dist/types/core/errors.d.ts

@@ -0,0 +1,15 @@
+import type { RuntimeErrorCode } from "../generated/runtime-contract.js";
+/**
+ * A verification / runtime failure with a stable, cross-language `code` and the
+ * fail-closed HTTP status the adapter should emit.
+ */
+export declare class FartherShoreError extends Error {
+    readonly code: RuntimeErrorCode;
+    readonly status: number;
+    constructor(code: RuntimeErrorCode, message: string, status?: number);
+}
+/**
+ * Map a runtime error code to its fail-closed HTTP status. Oversized bodies are
+ * the only non-401 (413); all other verification failures are 401.
+ */
+export declare function statusForCode(code: RuntimeErrorCode): number;

package/dist/types/core/health.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeHealthReport } from "../runtime-types.js";
+export type HealthStatus = "starting" | "ready" | "degraded" | "stopping";
+export type HealthSnapshot = {
+    runtimeToken: boolean;
+    bootstrap: boolean;
+    tunnel: string | null;
+    verification: boolean;
+    metering: boolean;
+};
+/** Build the fs.health() report from the current snapshot. */
+export declare function buildHealthReport(snapshot: HealthSnapshot): RuntimeHealthReport;
+export type HeartbeatOptions = {
+    runtimeToken: string;
+    coreUrl: string;
+    status: HealthStatus;
+    instanceId?: string;
+    fetchImpl?: typeof fetch;
+};
+/**
+ * POST a heartbeat to core. Best-effort: resolves false on any failure rather
+ * than throwing (tunnel/health failure ≠ verification — must not crash the app).
+ */
+export declare function reportHealth(options: HeartbeatOptions): Promise<boolean>;

package/dist/types/core/jwks.d.ts

@@ -0,0 +1,48 @@
+export type Jwk = JsonWebKey & {
+    kid?: string;
+};
+export type JwksClientOptions = {
+    jwksUrl: string;
+    /** Injectable fetch (tests). Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** How long a successful fetch stays fresh before a background refresh. */
+    cacheTtlMs?: number;
+    /** How long an unknown-kid result is negatively cached (avoids hammering). */
+    negativeCacheMs?: number;
+    /** Injectable clock (tests). */
+    now?: () => number;
+};
+/**
+ * Caching JWKS client. Holds the last successful key set indefinitely as a
+ * warm fallback (stale-while-revalidate) and only fails closed when it has
+ * NEVER successfully fetched (cold cache).
+ */
+export declare class JwksClient {
+    private readonly jwksUrl;
+    private readonly fetchImpl;
+    private readonly cacheTtlMs;
+    private readonly negativeCacheMs;
+    private readonly now;
+    private keysByKid;
+    private fetchedAt;
+    private hasFetchedOnce;
+    private inflight;
+    private readonly negativeKids;
+    constructor(options: JwksClientOptions);
+    /**
+     * Resolve a public JWK for `kid`, fail-closed. Throws FartherShoreError with
+     * `jwks_unavailable` (cold cache + fetch failed) or `unknown_key_id`.
+     */
+    getKey(kid: string): Promise<Jwk>;
+    /** Record a confirmed-missing kid, evicting the oldest if at capacity. */
+    private rememberMissingKid;
+    private isStale;
+    /** Single-flight refresh: concurrent callers share one fetch. */
+    private refresh;
+    private doFetch;
+    /**
+     * Stale-while-revalidate: with a warm cache, swallow the refresh failure and
+     * keep serving the last-known keys. With a COLD cache, fail closed.
+     */
+    private failOnColdCache;
+}

package/dist/types/core/metering.d.ts

@@ -0,0 +1,49 @@
+import type { RuntimeMeteringConfig } from "../runtime-types.js";
+export type MeterOptions = {
+    requestId?: string;
+    routeId?: string;
+    /** Override event_id (idempotency key). Defaults to a random uuid. */
+    eventId?: string;
+    /** Override the timestamp (ISO-8601). Defaults to now. */
+    timestamp?: string;
+};
+export type MeteringClientOptions = {
+    config: RuntimeMeteringConfig;
+    productId: string;
+    backendId: string;
+    /** Core base URL when the config endpoint is a relative path. */
+    coreUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** Max retry attempts per flush before re-buffering. */
+    maxRetries?: number;
+    /** Injectable id generator (tests). */
+    newId?: () => string;
+    now?: () => Date;
+};
+/**
+ * Buffers + flushes metering events. `meter()` validates and enqueues; `flush()`
+ * drains the buffer (re-buffering on failure for at-least-once delivery).
+ */
+export declare class MeteringClient {
+    private readonly config;
+    private readonly endpoint;
+    private readonly productId;
+    private readonly backendId;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly newId;
+    private readonly now;
+    private readonly buffer;
+    constructor(options: MeteringClientOptions);
+    /**
+     * 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).
+     */
+    meter(meter: string, qty: number, options?: MeterOptions): Promise<void>;
+    /** Drain the buffer. Events that fail all retries stay buffered (at-least-once). */
+    flush(): Promise<void>;
+    /** Buffered-but-unsent count (observability/tests). */
+    get pending(): number;
+    private sendWithRetry;
+}

package/dist/types/core/nonceCache.d.ts

@@ -0,0 +1,29 @@
+export type NonceCacheOptions = {
+    /** Max distinct nonces retained. Oldest are evicted first. */
+    maxEntries?: number;
+    /** TTL after which a nonce is forgotten (≥ replay window + skew). */
+    ttlMs?: number;
+    /** Injectable clock (tests). */
+    now?: () => number;
+};
+/**
+ * Bounded nonce cache. `checkAndRemember(id)` returns false (and records the id)
+ * the first time it sees an id, and true (replay) on any subsequent sighting
+ * while the id is still retained.
+ */
+export declare class NonceCache {
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly seen;
+    constructor(options?: NonceCacheOptions);
+    /**
+     * @returns true if `id` was already seen (a REPLAY); false on first sight
+     * (the id is then remembered).
+     */
+    checkAndRemember(id: string): boolean;
+    /** Number of retained nonces (test/observability hook). */
+    get size(): number;
+    private evictExpired;
+    private evictOverflow;
+}

package/dist/types/core/runtime.d.ts

@@ -0,0 +1,96 @@
+import { type RuntimeBootstrapResponse, type RuntimeHealthReport } from "../runtime-types.js";
+import { type MeterOptions } from "./metering.js";
+import { type SpawnFn } from "./tunnel.js";
+import { type FartherShoreRequestContext, type VerifyRequestInput } from "./verifyRequest.js";
+/** Advanced opt-in tunnel config. The managed runner is the default DX. */
+export type FartherShoreTunnelOptions = {
+    /** Opt out of the managed cloudflared runner (e.g. sidecar mode). */
+    enabled?: boolean;
+    /** Injected spawner (tests/non-default hosts). Defaults to node:child_process. */
+    spawn?: SpawnFn;
+    /** Explicit cloudflared binary path. */
+    binaryPath?: string;
+    /** Crash the host app if the tunnel cannot start. Default: fail-open. */
+    failClosed?: boolean;
+    /** Log sink for redacted cloudflared output. */
+    logger?: (line: string) => void;
+};
+export type FartherShoreInitOptions = {
+    /** Explicit runtime token. Defaults to process.env.FS_RUNTIME_TOKEN. */
+    runtimeToken?: string;
+    /**
+     * Core base URL. Defaults to FS_CORE_URL / FARTHERSHORE_CORE_URL or
+     * https://api.farthershore.com.
+     */
+    coreUrl?: string;
+    /** Env map (tests). Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** Injectable fetch (tests). */
+    fetchImpl?: typeof fetch;
+    /** Optional advanced opt-outs (default: everything on). */
+    verification?: {
+        enabled?: boolean;
+    };
+    metering?: {
+        enabled?: boolean;
+    };
+    /** Managed-cloudflared runner config (advanced opt-in; default DX is on). */
+    tunnel?: FartherShoreTunnelOptions;
+    /** SDK metadata forwarded to bootstrap. */
+    instanceId?: string;
+};
+/**
+ * The runtime instance. Lazily bootstraps; holds the JWKS client, nonce cache,
+ * metering buffer, and shutdown hooks.
+ */
+export declare class FartherShore {
+    private readonly bootstrapClient;
+    private readonly fetchImpl;
+    private readonly verificationEnabled;
+    private readonly meteringEnabledOverride;
+    private readonly runtimeToken;
+    private readonly coreUrl;
+    private readonly instanceId?;
+    private readonly tunnelOptions;
+    private readonly nonceCache;
+    private readonly shutdownManager;
+    private jwks;
+    private meteringClient;
+    private tunnel;
+    private bootstrapped;
+    constructor(options?: FartherShoreInitOptions);
+    /** Ensure bootstrap config is loaded; build the JWKS + metering clients. */
+    ensureBootstrapped(): Promise<RuntimeBootstrapResponse>;
+    /**
+     * Framework-neutral verification primitive. Fail-closed: throws a typed
+     * FartherShoreError on any verification failure. Returns the verified context.
+     */
+    verifyRequest(input: VerifyRequestInput): Promise<FartherShoreRequestContext>;
+    /** Whether verification is required (bootstrap × opt-out). */
+    verificationRequired(): Promise<boolean>;
+    /**
+     * 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).
+     */
+    start(): Promise<void>;
+    /** Record metering usage (billing-only). */
+    meter(meter: string, qty: number, options?: MeterOptions): Promise<void>;
+    /** Current local health report. */
+    health(): RuntimeHealthReport;
+    /** Graceful shutdown: flush metering + send a stopping heartbeat. */
+    shutdown(): Promise<void>;
+    /** Register an additional shutdown hook (e.g. the cloudflared supervisor). */
+    onShutdown(hook: () => Promise<void> | void): void;
+}
+/**
+ * Construct a FartherShore instance from the environment. Derives EVERYTHING
+ * from FS_RUNTIME_TOKEN; throws missing_token / invalid_token eagerly if the
+ * token is absent or mis-prefixed.
+ */
+export declare function initFromEnv(options?: FartherShoreInitOptions): FartherShore;

package/dist/types/core/shutdown.d.ts

@@ -0,0 +1,10 @@
+export type ShutdownHook = () => Promise<void> | void;
+/** LIFO registry of shutdown hooks, each isolated from sibling failures. */
+export declare class ShutdownManager {
+    private readonly hooks;
+    private done;
+    register(hook: ShutdownHook): void;
+    get isShutDown(): boolean;
+    /** Run all hooks in reverse order, isolating failures. Idempotent. */
+    shutdown(): Promise<void>;
+}

package/dist/types/core/tunnel.d.ts

@@ -0,0 +1,159 @@
+import type { EventEmitter } from "node:events";
+/** A line emitter — the subset of a child stdio stream we consume. */
+type StdioStream = Pick<EventEmitter, "on">;
+/**
+ * The minimal child-process surface the supervisor needs. A real
+ * `child_process.ChildProcess` satisfies this; tests pass a fake. We deliberately
+ * do NOT depend on the full ChildProcess type so the spawner stays injectable and
+ * the SDK does not pull a Node-only process model into the language-neutral core.
+ */
+export interface SpawnedTunnelProcess {
+    readonly stdout: StdioStream | null;
+    readonly stderr: StdioStream | null;
+    readonly pid?: number;
+    /** Register the process-exit handler. */
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    /** Signal the child to stop. */
+    kill(signal?: NodeJS.Signals | number): boolean;
+}
+/**
+ * The injected spawner port. In production this is a thin wrapper over
+ * `child_process.spawn`; in tests it is a fake that records argv. It MUST NOT be
+ * passed `local_target` — routing is owned by Cloudflare.
+ */
+export type SpawnFn = (command: string, args: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+}) => SpawnedTunnelProcess;
+/** Supervisor lifecycle states, surfaced through `status()` / `healthString()`. */
+export type TunnelState = "stopped" | "starting" | "running" | "restarting" | "error";
+/** The sentinel substituted for the tunnel token in any logged/serialized text. */
+export declare const REDACTED_TOKEN = "***REDACTED***";
+export type CloudflaredSupervisorOptions = {
+    /**
+     * The Cloudflare tunnel token (transport identity for `cloudflared`). HIGHLY
+     * sensitive: kept in memory, never logged, redacted everywhere. (Distinct from
+     * the runtime token / app identity.)
+     */
+    tunnelToken: string;
+    /** Injected spawner (required; tests pass a fake — never a real process). */
+    spawn: SpawnFn;
+    /**
+     * Explicit binary path. When omitted, `locateBinary` resolves it (Linux-first
+     * candidates). When neither resolves, start fails with a clear error.
+     */
+    binaryPath?: string;
+    /** Injected binary locator. Returns an absolute path or null if not found. */
+    locateBinary?: () => string | null;
+    /** Log sink for redacted cloudflared output. Defaults to console.error. */
+    logger?: (line: string) => void;
+    /** Error-surface callback (fail-open path). Receives a token-redacted error. */
+    onError?: (error: Error) => void;
+    /**
+     * When true, a spawn failure rejects `start()` (the host opted into letting a
+     * tunnel failure stop the app). Default false: tunnel failure ≠ app crash.
+     * (Request *verification* is always fail-closed regardless — different axis.)
+     */
+    failClosed?: boolean;
+    /** Base backoff for the first restart (doubles each consecutive failure). */
+    baseBackoffMs?: number;
+    /** Backoff ceiling. */
+    maxBackoffMs?: number;
+    /** Injectable timer (tests use fake timers / a custom scheduler). */
+    setTimeoutFn?: (cb: () => void, ms: number) => unknown;
+    clearTimeoutFn?: (handle: unknown) => void;
+    /** Process env passed to the child (tunnel token is NOT injected via env). */
+    childEnv?: NodeJS.ProcessEnv;
+};
+/** A read-only snapshot of the supervisor — safe to serialize (token-free). */
+export type TunnelStatus = {
+    state: TunnelState;
+    pid: number | null;
+    restarts: number;
+    /** Token-redacted last error message, if any. */
+    lastError: string | null;
+};
+/**
+ * Supervises a single `cloudflared` child process. One supervisor ⇒ one tunnel
+ * (one backend). Restarts on unexpected exit; stays down after `shutdown()`.
+ */
+export declare class CloudflaredSupervisor {
+    private readonly tunnelToken;
+    private readonly spawn;
+    private readonly binaryPath;
+    private readonly locateBinary;
+    private readonly logger;
+    private readonly onError;
+    private readonly failClosed;
+    private readonly baseBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly childEnv;
+    private child;
+    private state;
+    private restarts;
+    private consecutiveFailures;
+    private lastError;
+    private intentionalStop;
+    private restartTimer;
+    private signalsBound;
+    private readonly signalHandler;
+    constructor(options: CloudflaredSupervisorOptions);
+    /**
+     * 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()`.
+     */
+    start(): Promise<void>;
+    /**
+     * 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.
+     */
+    shutdown(): Promise<void>;
+    /** Token-free status snapshot for diagnostics / health. */
+    status(): TunnelStatus;
+    /** Compact health string for `fs.health().tunnel`. */
+    healthString(): string;
+    private spawnChild;
+    /**
+     * Resolve the cloudflared binary path. Explicit `binaryPath` wins; otherwise
+     * the injected locator runs (Linux-first). Missing ⇒ a clear, redacted error.
+     */
+    private resolveBinary;
+    /** Pipe stdout/stderr to the logger with the tunnel token redacted. */
+    private pipeLogs;
+    /**
+     * 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).
+     */
+    private makeLineSink;
+    private emitLogLine;
+    /** Replace every occurrence of the tunnel token with the sentinel. */
+    private redact;
+    private handleExit;
+    private scheduleRestart;
+    private backoffDelay;
+    private handleStartFailure;
+    private recordError;
+    private bindSignals;
+    private unbindSignals;
+}
+/**
+ * The default production spawner: a thin wrapper over Node's
+ * `child_process.spawn`. Stdio is piped (so logs flow through the redactor); the
+ * tunnel token is passed as an argv item, never via the environment. Tests
+ * always inject their own spawner instead of this.
+ */
+export declare function nodeSpawn(): SpawnFn;
+export {};

package/dist/types/core/verifyRequest.d.ts

@@ -0,0 +1,54 @@
+import type { JwksClient } from "./jwks.js";
+import type { NonceCache } from "./nonceCache.js";
+/** Per-request input. `headers` keys are matched case-insensitively. */
+export type VerifyRequestInput = {
+    method: string;
+    /** Path only (no host, no query). */
+    path: string;
+    /** Raw query string (with or without leading '?'); "" when absent. */
+    query?: string;
+    headers: HeadersLike;
+    /** Raw request bytes captured pre-parser; null/undefined for empty body. */
+    body?: Uint8Array | null;
+    /**
+     * True when the request is body-hash-exempt (streaming). The signed hash must
+     * then be the STREAM sentinel and the body is not hashed (size cap still
+     * applies upstream).
+     */
+    streamingExempt?: boolean;
+};
+export type HeadersLike = Headers | Record<string, string | string[] | undefined>;
+/** The verified request context attached to req.fartherShore. */
+export type FartherShoreRequestContext = {
+    requestId: string;
+    productId: string;
+    backendId: string;
+    routeId: string;
+    policyVersion: string;
+    timestamp: number;
+    bodyHash: string;
+    /** Filled by the host bootstrap layer (tenant/customer), not by verify. */
+    tenantId?: string;
+    customerId?: string;
+    meters?: string[];
+    features?: Record<string, unknown>;
+};
+export type VerifyRequestDeps = {
+    jwks: JwksClient;
+    nonceCache: NonceCache;
+    /** Expected product id (from bootstrap). When set, must match the signed claim. */
+    productId?: string;
+    /** Expected backend id (from bootstrap). When set, must match. */
+    backendId?: string;
+    /**
+     * Set of route ids this backend serves (from bootstrap). When provided AND
+     * the signed route-id is non-empty, the signed route must be a member —
+     * otherwise route_mismatch.
+     */
+    knownRouteIds?: ReadonlySet<string>;
+    clockSkewSeconds?: number;
+    replayWindowSeconds?: number;
+    /** Injectable clock (seconds since epoch). */
+    nowSeconds?: () => number;
+};
+export declare function verifyRequest(input: VerifyRequestInput, deps: VerifyRequestDeps): Promise<FartherShoreRequestContext>;

package/dist/types/generated/metering-contract.d.ts

@@ -0,0 +1,36 @@
+export declare const METERING_CONTRACT_VERSION: 1;
+export declare const METERING_HEADERS: {
+    readonly payload: "x-fs-metering";
+    readonly signature: "x-fs-metering-sig";
+    readonly token: "x-fs-metering-token";
+};
+export declare const METERING_TOKEN_ENV: "FARTHERSHORE_METERING_TOKEN";
+export declare const METERING_TOKEN_CONTRACT: {
+    readonly environmentVariable: "FARTHERSHORE_METERING_TOKEN";
+    readonly presentation: "x-fs-metering-token";
+    readonly storage: "sha256-hash-only";
+};
+export declare const METERING_SIGNATURE_CONTRACT: {
+    readonly algorithm: "HMAC-SHA256";
+    readonly encoding: "base64url";
+    readonly input: "payload-json";
+    readonly secret: "presented-metering-token";
+};
+export declare const METERING_ERROR_CODES: {
+    readonly missingToken: "missing_token";
+    readonly invalidMeterKey: "invalid_meter_key";
+    readonly invalidMeterValue: "invalid_meter_value";
+};
+export type MeteringErrorCode = (typeof METERING_ERROR_CODES)[keyof typeof METERING_ERROR_CODES];
+export declare const METERING_HTTP_ADAPTER_CONTRACT: {
+    readonly input: "Request";
+    readonly output: "Response";
+    readonly networkCalls: false;
+    readonly preserves: readonly ["body", "headers", "status", "statusText"];
+    readonly gatewayStripsInternalHeaders: true;
+};
+export type MeteringUsagePayload = {
+    method: string;
+    path: string;
+    rawDimsUnits: Record<string, number>;
+};