@farthershore/backend 0.1.0

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

@@ -0,0 +1,191 @@
+export declare const RUNTIME_CONTRACT_VERSION: 1;
+export declare const RUNTIME_TOKEN_ENV: "FS_RUNTIME_TOKEN";
+export declare const RUNTIME_TOKEN_CONTRACT: {
+    readonly environmentVariable: "FS_RUNTIME_TOKEN";
+    readonly prefixes: {
+        readonly live: "fsrt_live_";
+        readonly test: "fsrt_test_";
+    };
+    readonly opaque: true;
+    readonly storage: "sha256-hash-only";
+    readonly lastFour: true;
+    readonly capabilities: readonly ["gateway_verification", "metering", "health", "tunnel"];
+};
+export declare const RUNTIME_BOOTSTRAP_CONTRACT: {
+    readonly method: "POST";
+    readonly path: "/v1/runtime/bootstrap";
+    readonly authorization: "Bearer fsrt_...";
+    readonly request: {
+        readonly instanceId: "string?";
+        readonly sdkVersion: "string?";
+        readonly sdkLanguage: "string?";
+    };
+    readonly response: {
+        readonly product: {
+            readonly id: "string";
+            readonly slug: "string";
+        };
+        readonly backend: {
+            readonly id: "string";
+            readonly slug: "string";
+            readonly name: "string";
+        };
+        readonly environment: {
+            readonly id: "string?";
+            readonly kind: "live | test";
+        };
+        readonly capabilities: "string[]";
+        readonly verification: {
+            readonly required: "boolean";
+            readonly jwksUrl: "string";
+            readonly clockSkewSeconds: "number";
+            readonly replayWindowSeconds: "number";
+            readonly headerNames: "object";
+        };
+        readonly metering: {
+            readonly enabled: "boolean";
+            readonly endpoint: "string";
+            readonly credential: "string";
+            readonly allowedMeters: "string[]";
+            readonly allowedRoutes: "string[]";
+            readonly perEventMax: "number";
+        };
+        readonly transport: {
+            readonly mode: "public_origin | mtls | cloudflare_tunnel";
+            readonly runner: "managed_cloudflared | sidecar | null";
+            readonly originUrl: "string?";
+            readonly originHostname: "string?";
+            readonly localTarget: "string?";
+            readonly cloudflared: "object?";
+        };
+        readonly routes: "object[]";
+        readonly policyVersion: "string";
+        readonly refreshAfterSeconds: "number";
+    };
+};
+export declare const RUNTIME_SIGNING_CONTRACT: {
+    readonly algorithm: "Ed25519";
+    readonly encoding: "base64url";
+    readonly keyMaterial: "service-jwt-jwks";
+    readonly canonicalString: {
+        readonly description: "Byte-exact, language-neutral serialization of the signed claim set. Fields are emitted in the FIXED order below, one per line, each as `name:value`, joined by a single newline (\\n, U+000A). NO trailing newline. The serialization depends on neither JSON key ordering nor any Node.js Buffer/serialization detail — only UTF-8 byte encoding of the field values. Empty/absent values are emitted as the empty string after the colon. Go/Python/Java/Rust reproduce this identically.";
+        readonly fieldSeparator: "\n";
+        readonly keyValueSeparator: ":";
+        readonly trailingNewline: false;
+        readonly fieldEncoding: "utf-8";
+        readonly fields: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "product-id", "backend-id", "route-id", "policy-version"];
+        readonly fieldRules: {
+            readonly method: "Uppercased HTTP method (e.g. GET, POST).";
+            readonly path: "Request path, percent-encoded as received, no host, no query string. Always begins with '/'.";
+            readonly query: "Canonical query string: parse pairs, sort by (name, then value) using byte (code-unit) order, re-join name=value pairs with '&'. Names and values are NOT re-encoded (passed through as received). Empty string when there is no query.";
+            readonly "body-hash": "Lowercase hex SHA-256 of the RAW request body bytes. For an empty body, the SHA-256 of zero bytes (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Streaming-exempt requests use the literal token 'STREAM'.";
+            readonly "request-id": "Opaque unique request id minted by the gateway (also the replay-cache nonce).";
+            readonly timestamp: "Integer Unix epoch seconds (UTC) at signing time, as a base-10 string with no padding.";
+            readonly "product-id": "Product id the request is routed to.";
+            readonly "backend-id": "Backend id the route binds to.";
+            readonly "route-id": "Resolved route id; empty string if the route is unresolved.";
+            readonly "policy-version": "Tenant artifact / policy version the gateway signed under.";
+        };
+    };
+};
+/**
+ * Ordered list of fields in the canonical signing string. The order here is
+ * load-bearing and identical across all language SDKs.
+ */
+export declare const RUNTIME_CANONICAL_FIELDS: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "product-id", "backend-id", "route-id", "policy-version"];
+export declare const RUNTIME_BODY_HASH_CONTRACT: {
+    readonly algorithm: "SHA-256";
+    readonly encoding: "hex-lower";
+    readonly source: "raw-request-bytes";
+    readonly emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+    readonly maxBodyBytes: 10485760;
+    readonly streamingExemptToken: "STREAM";
+    readonly streamingExemptContentTypes: readonly ["text/event-stream", "application/octet-stream", "multipart/form-data"];
+    readonly overMaxStatus: 413;
+};
+export declare const RUNTIME_HEADERS: {
+    readonly signature: "x-fs-signature";
+    readonly keyId: "x-fs-key-id";
+    readonly requestId: "x-fs-request-id";
+    readonly timestamp: "x-fs-timestamp";
+    readonly productId: "x-fs-product-id";
+    readonly backendId: "x-fs-backend-id";
+    readonly routeId: "x-fs-route-id";
+    readonly policyVersion: "x-fs-policy-version";
+    readonly bodyHash: "x-fs-body-hash";
+};
+export declare const RUNTIME_REPLAY_CONTRACT: {
+    readonly windowSeconds: 300;
+    readonly clockSkewSeconds: 5;
+    readonly nonce: "x-fs-request-id";
+    readonly nonceCache: "bounded-lru";
+    readonly policy: "fail-closed";
+};
+export declare const RUNTIME_ERROR_CODES: {
+    readonly missingSignature: "missing_signature";
+    readonly malformedSignature: "malformed_signature";
+    readonly unknownKeyId: "unknown_key_id";
+    readonly jwksUnavailable: "jwks_unavailable";
+    readonly badSignature: "bad_signature";
+    readonly bodyHashMismatch: "body_hash_mismatch";
+    readonly routeMismatch: "route_mismatch";
+    readonly clockSkew: "clock_skew";
+    readonly expiredSignature: "expired_signature";
+    readonly replayedNonce: "replayed_nonce";
+    readonly bodyTooLarge: "body_too_large";
+    readonly environmentMismatch: "environment_mismatch";
+    readonly missingToken: "missing_token";
+    readonly invalidToken: "invalid_token";
+};
+export type RuntimeErrorCode = (typeof RUNTIME_ERROR_CODES)[keyof typeof RUNTIME_ERROR_CODES];
+export declare const RUNTIME_METERING_CONTRACT: {
+    readonly endpoint: "/v1/metering/events";
+    readonly method: "POST";
+    readonly credential: "reusable-bearer";
+    readonly event: {
+        readonly event_id: "string";
+        readonly product_id: "string";
+        readonly backend_id: "string";
+        readonly route_id: "string?";
+        readonly request_id: "string?";
+        readonly meter: "string";
+        readonly qty: "number";
+        readonly timestamp: "string";
+    };
+    readonly idempotencyKey: "event_id";
+    readonly delivery: "at-least-once";
+    readonly billingOnly: true;
+    readonly realtimeEnforced: false;
+    readonly trustModel: "backend-reported values are NOT cryptographically attested; a buggy or compromised backend can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
+};
+export declare const RUNTIME_HEALTH_CONTRACT: {
+    readonly endpoint: "/v1/runtime/health";
+    readonly method: "POST";
+    readonly request: {
+        readonly instanceId: "string?";
+        readonly status: "starting | ready | degraded | stopping";
+    };
+    readonly readinessStates: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
+    readonly checks: readonly ["runtime_token_valid", "bootstrapped", "tunnel_running", "signed_request_2xx", "unsigned_request_401", "stale_signature_401", "wrong_route_401", "metering_observed"];
+    readonly report: {
+        readonly runtimeToken: "boolean";
+        readonly bootstrap: "boolean";
+        readonly tunnel: "string?";
+        readonly verification: "boolean";
+        readonly metering: "boolean";
+    };
+};
+export declare const RUNTIME_TRANSPORT_CONTRACT: {
+    readonly modes: {
+        readonly public_origin: "Gateway fetches the builder's public origin URL; the SDK middleware fail-closed-verifies every request. Provisions zero Cloudflare objects. Standard tier; also the dev path.";
+        readonly mtls: "Gateway presents a Farther-Shore-issued platform-wide client cert; the builder's ingress requires + verifies it. Channel-level mutual auth; provisions zero Cloudflare objects. Standard-plus / self-hosted tier.";
+        readonly cloudflare_tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The only Production-secure tier. Consumes Cloudflare tunnel/route slots.";
+    };
+    readonly runners: {
+        readonly managed_cloudflared: "fs.start() supervises cloudflared as a child process (default DX).";
+        readonly sidecar: "Vanilla cloudflare/cloudflared container beside the app (production / non-Node).";
+    };
+    readonly channelTrust: readonly ["mtls", "cloudflare_tunnel"];
+    readonly requestTrust: "x-fs-signature";
+    readonly invariant: "Channel trust (mtls/tunnel) and request trust (the X-FS-* signature) are distinct layers; both always apply. CF-Access-* headers are transport-layer only and are IGNORED by the SDK.";
+};

package/dist/types/index.d.ts

@@ -0,0 +1,34 @@
+import { FartherShore, type FartherShoreInitOptions } from "./core/runtime.js";
+import { type ExpressMiddleware, type MiddlewareOptions } from "./adapters/express.js";
+export { FartherShore } from "./core/runtime.js";
+export type { FartherShoreInitOptions } from "./core/runtime.js";
+export { FartherShoreError, statusForCode } from "./core/errors.js";
+export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
+export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
+export { NonceCache, type NonceCacheOptions } from "./core/nonceCache.js";
+export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";
+export { MeteringClient, type MeteringClientOptions, type MeterOptions, } from "./core/metering.js";
+export { buildHealthReport, reportHealth, type HealthSnapshot, type HealthStatus, type HeartbeatOptions, } from "./core/health.js";
+export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
+export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";
+export type { FartherShoreTunnelOptions } from "./core/runtime.js";
+export { createExpressMiddleware, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type MiddlewareOptions, } from "./adapters/express.js";
+export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_CAPABILITIES, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenCapability, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, } from "./runtime-types.js";
+export { RUNTIME_ERROR_CODES } from "./generated/runtime-contract.js";
+export { hashBody, buildCanonicalSigningString, canonicalizeQuery, signCanonicalString, verifyCanonicalSignature, runtimeTokenKind, } from "./runtime-signing.js";
+export { createUsage, withUsage, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, } from "./legacy/metering.js";
+/**
+ * The conceptual public entrypoint. `fartherShore.initFromEnv()` mirrors the
+ * language-neutral spec. The returned instance is augmented with `middleware()`
+ * (the Express adapter) bound to itself.
+ */
+export type FartherShoreInstance = FartherShore & {
+    /** Express middleware: fail-closed verify → req.fartherShore. */
+    middleware(options?: MiddlewareOptions): ExpressMiddleware;
+};
+export declare const fartherShore: {
+    /** Derive everything from FS_RUNTIME_TOKEN via bootstrap. */
+    initFromEnv(options?: FartherShoreInitOptions): FartherShoreInstance;
+};
+/** Convenience: top-level initFromEnv mirroring fartherShore.initFromEnv(). */
+export declare function initFromEnv(options?: FartherShoreInitOptions): FartherShoreInstance;

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

@@ -0,0 +1,20 @@
+import { type MeteringErrorCode } from "../generated/metering-contract.js";
+export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
+export declare const METERING_SIGNATURE_HEADER: "x-fs-metering-sig";
+export declare const METERING_TOKEN_HEADER: "x-fs-metering-token";
+export declare const DEFAULT_TOKEN_ENV: "FARTHERSHORE_METERING_TOKEN";
+export type UsageMap = Record<string, number>;
+export type MeteringOptions = {
+    token?: string;
+    env?: Record<string, string | undefined>;
+};
+export type UsageReporter = {
+    report(meter: string, value: number): UsageReporter;
+    wrap(response: Response): Promise<Response>;
+};
+export declare class MeteringError extends Error {
+    readonly code: MeteringErrorCode;
+    constructor(code: MeteringErrorCode, message: string);
+}
+export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
+export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;

package/dist/types/runtime-signing.d.ts

@@ -0,0 +1,25 @@
+import type { CanonicalSigningInput, RuntimeTokenKind } from "./runtime-types.js";
+/** Lowercase-hex SHA-256 of the RAW request bytes. Never re-serialized JSON. */
+export declare const hashBody: (body: Uint8Array) => Promise<string>;
+/**
+ * Normalize a query string into the canonical form: split into name=value
+ * pairs on '&', sort by (name, then value) using byte (code-unit) order, and
+ * re-join with '&'. Pass-through (no re-encoding) so all SDKs agree on bytes.
+ * An empty input yields an empty string.
+ */
+export declare const canonicalizeQuery: (query: string) => string;
+/**
+ * Build the byte-exact canonical signing string. This is the cross-language
+ * gate: every SDK MUST produce identical output for identical inputs, with NO
+ * dependence on JSON key order or Node Buffer serialization.
+ */
+export declare const buildCanonicalSigningString: (input: CanonicalSigningInput) => string;
+/** Sign the canonical string with an Ed25519 private JWK → base64url signature. */
+export declare const signCanonicalString: (canonical: string, privateJwk: JsonWebKey) => Promise<string>;
+/** Verify a base64url Ed25519 signature over the canonical string. */
+export declare const verifyCanonicalSignature: (canonical: string, signatureB64Url: string, publicJwk: JsonWebKey) => Promise<boolean>;
+/**
+ * Classify a presented runtime token by prefix without trusting its body.
+ * Returns the environment kind, or `null` when the prefix is not recognized.
+ */
+export declare const runtimeTokenKind: (token: string) => RuntimeTokenKind | null;

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

@@ -0,0 +1,137 @@
+export type { RuntimeErrorCode } from "./generated/runtime-contract.js";
+export declare const FS_RUNTIME_TOKEN_ENV: "FS_RUNTIME_TOKEN";
+export declare const RUNTIME_TOKEN_PREFIXES: {
+    readonly live: "fsrt_live_";
+    readonly test: "fsrt_test_";
+};
+export type RuntimeTokenKind = keyof typeof RUNTIME_TOKEN_PREFIXES;
+export declare const RUNTIME_TOKEN_CAPABILITIES: readonly ["gateway_verification", "metering", "health", "tunnel"];
+export type RuntimeTokenCapability = (typeof RUNTIME_TOKEN_CAPABILITIES)[number];
+export declare const RUNTIME_HEADER_NAMES: {
+    readonly signature: "x-fs-signature";
+    readonly keyId: "x-fs-key-id";
+    readonly requestId: "x-fs-request-id";
+    readonly timestamp: "x-fs-timestamp";
+    readonly productId: "x-fs-product-id";
+    readonly backendId: "x-fs-backend-id";
+    readonly routeId: "x-fs-route-id";
+    readonly policyVersion: "x-fs-policy-version";
+    readonly bodyHash: "x-fs-body-hash";
+};
+export type RuntimeHeaderName = (typeof RUNTIME_HEADER_NAMES)[keyof typeof RUNTIME_HEADER_NAMES];
+/** Mirrors SERVICE_JWT_CLOCK_SKEW_SECONDS — the per-request signer reuses the
+ * same Ed25519/JWKS infra so the skew allowance is kept identical. */
+export declare const RUNTIME_CLOCK_SKEW_SECONDS = 5;
+export declare const RUNTIME_REPLAY_WINDOW_SECONDS = 300;
+/** SHA-256 of zero bytes — the canonical empty-body hash. */
+export declare const EMPTY_BODY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/** Sentinel emitted into the canonical string when a request is body-hash
+ * exempt (streaming). Raw-byte hashing is otherwise mandatory. */
+export declare const STREAMING_EXEMPT_BODY_HASH = "STREAM";
+/** Max raw-body bytes the gateway/SDK will hash before returning 413. */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * The signed claim set. Field VALUES are language-neutral strings/integers;
+ * the canonical serialization (in runtime-signing.ts) pins the wire bytes.
+ */
+export type CanonicalSigningInput = {
+    /** HTTP method; canonicalized to upper-case. */
+    method: string;
+    /** Request path (no host, no query). */
+    path: string;
+    /** Raw query string (without leading '?'), or "" when absent. */
+    query: string;
+    /** Lowercase-hex SHA-256 of the raw body, EMPTY_BODY_SHA256, or "STREAM". */
+    bodyHash: string;
+    /** Gateway-minted request id (also the replay nonce). */
+    requestId: string;
+    /** Unix epoch seconds at signing time. */
+    timestamp: number;
+    productId: string;
+    backendId: string;
+    /** Resolved route id; "" when unresolved. */
+    routeId: string;
+    policyVersion: string;
+};
+export type RuntimeEnvironmentKind = RuntimeTokenKind;
+export type TransportMode = "public_origin" | "mtls" | "cloudflare_tunnel";
+export type TransportRunner = "managed_cloudflared" | "sidecar";
+export type RuntimeBootstrapRequest = {
+    instanceId?: string;
+    sdkVersion?: string;
+    sdkLanguage?: string;
+};
+export type RuntimeVerificationConfig = {
+    required: boolean;
+    jwksUrl: string;
+    clockSkewSeconds: number;
+    replayWindowSeconds: number;
+    headerNames: typeof RUNTIME_HEADER_NAMES;
+};
+export type RuntimeMeteringConfig = {
+    enabled: boolean;
+    endpoint: string;
+    credential: string;
+    allowedMeters: string[];
+    allowedRoutes: string[];
+    perEventMax: number;
+};
+export type RuntimeTransportConfig = {
+    mode: TransportMode;
+    runner: TransportRunner | null;
+    originUrl?: string;
+    originHostname?: string;
+    localTarget?: string;
+    cloudflared?: {
+        tunnelToken: string;
+        version: string;
+    };
+    mtlsClientCertRef?: string;
+};
+export type RuntimeRouteDescriptor = {
+    id: string;
+    method: string;
+    path: string;
+    backendId: string;
+};
+export type RuntimeBootstrapResponse = {
+    product: {
+        id: string;
+        slug: string;
+    };
+    backend: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    environment: {
+        id: string | null;
+        kind: RuntimeEnvironmentKind;
+    };
+    capabilities: RuntimeTokenCapability[];
+    verification: RuntimeVerificationConfig;
+    metering: RuntimeMeteringConfig;
+    transport: RuntimeTransportConfig;
+    routes: RuntimeRouteDescriptor[];
+    policyVersion: string;
+    refreshAfterSeconds: number;
+};
+export type RuntimeMeteringEvent = {
+    event_id: string;
+    product_id: string;
+    backend_id: string;
+    route_id?: string;
+    request_id?: string;
+    meter: string;
+    qty: number;
+    timestamp: string;
+};
+export declare const RUNTIME_READINESS_STATES: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
+export type RuntimeReadinessState = (typeof RUNTIME_READINESS_STATES)[number];
+export type RuntimeHealthReport = {
+    runtimeToken: boolean;
+    bootstrap: boolean;
+    tunnel: string | null;
+    verification: boolean;
+    metering: boolean;
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@farthershore/backend",
+  "version": "0.1.0",
+  "description": "Farther Shore backend SDK: secure BYO-backend runtime — fail-closed gateway request verification, metering, health, and lifecycle, all derived from FS_RUNTIME_TOKEN",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/types/adapters/express.d.ts",
+      "import": "./dist/adapters/express.js"
+    },
+    "./runtime": {
+      "types": "./dist/types/generated/runtime-contract.d.ts",
+      "import": "./dist/generated/runtime-contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "esbuild": "^0.27.7",
+    "eslint": "^9.39.4",
+    "eslint-plugin-sonarjs": "^4.0.3",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^4.1.6",
+    "@farthershore/contracts": "0.61.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc --noEmit && node scripts/build.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "pack:check": "node scripts/check-pack.mjs"
+  }
+}