@farthershore/backend 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @farthershore/backend
+
+The secure BYO-backend runtime SDK. Install one package, set one token
+(`FS_RUNTIME_TOKEN`), and Farther Shore protects (signs every gateway→backend
+request; the SDK verifies and rejects anything not from Farther Shore) and meters
+your backend.
+
+## Install
+
+```sh
+npm install @farthershore/backend
+```
+
+## Quick start (Express)
+
+```ts
+import { fartherShore } from "@farthershore/backend";
+
+const fs = fartherShore.initFromEnv(); // derives everything from FS_RUNTIME_TOKEN
+
+app.use(fs.middleware()); // fail-closed verify → req.fartherShore
+
+app.post("/v1/runs", async (req, res) => {
+  const result = await runWorkflow(req.body);
+  await fs.meter("tokens", result.tokensUsed, {
+    requestId: req.fartherShore.requestId,
+  });
+  res.json(result);
+});
+
+app.listen(3000);
+process.on("SIGTERM", () => void fs.shutdown());
+```
+
+## What `initFromEnv()` derives
+
+The builder configures exactly one thing: `FS_RUNTIME_TOKEN`. Everything else —
+product/backend/environment ids, the JWKS url, the metering endpoint and
+credential, verification config, transport — is fetched from
+`POST /v1/runtime/bootstrap` and cached in memory (refreshed lazily).
+
+## Verification (fail-closed, always)
+
+`fs.middleware()` (Express) and the framework-neutral
+`fs.verifyRequest({ method, path, query, headers, body })` recompute the
+[canonical signing string](../../docs/superpowers/specs/backend-runtime-spec.md)
+from the actual request and verify the gateway's Ed25519 signature against a
+JWKS-resolved public key. The plaintext `X-FS-*` headers are **untrusted** —
+identity comes only from a signature whose claims match the real request.
+
+Every failure (missing / malformed / bad-signature / stale / clock-skew /
+wrong-route / body-hash-mismatch / replayed-nonce / unknown-kid /
+jwks-unavailable) returns a typed `FartherShoreError` → **HTTP 401** (413 for
+oversized bodies). There is no fail-open branch.
+
+## Metering (billing-only)
+
+`fs.meter(meter, qty, { requestId, routeId })` enqueues an idempotent event and
+POSTs it to `/v1/metering/events` with a reusable bearer credential. Delivery is
+at-least-once; the `event_id` idempotency key keeps core's ingest safe. Values
+are tallied/billed post-cycle, not real-time enforced.
+
+## Migrating from `@farthershore/metering`
+
+`@farthershore/metering` is now a deprecated re-export shim of this package and
+will be removed after the metering cutover. Replace the import; for new code,
+prefer `fs.meter("tokens", n)` over the response-header signer.
+
+The signing primitives and contract constants are re-exported from
+`@farthershore/contracts/runtime`, the language-neutral source of truth every
+SDK (TypeScript first; Go/Python/Java/Rust later) implements.

package/dist/adapters/express.js

@@ -0,0 +1,101 @@
+import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+
+// 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/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
+};
+
+// 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;
+}
+export {
+  createExpressMiddleware
+};

package/dist/generated/runtime-contract.js

@@ -0,0 +1,239 @@
+import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+
+// src/generated/runtime-contract.ts
+var RUNTIME_CONTRACT_VERSION = 1;
+var RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
+var RUNTIME_TOKEN_CONTRACT = {
+  environmentVariable: "FS_RUNTIME_TOKEN",
+  prefixes: {
+    live: "fsrt_live_",
+    test: "fsrt_test_"
+  },
+  opaque: true,
+  storage: "sha256-hash-only",
+  lastFour: true,
+  capabilities: ["gateway_verification", "metering", "health", "tunnel"]
+};
+var RUNTIME_BOOTSTRAP_CONTRACT = {
+  method: "POST",
+  path: "/v1/runtime/bootstrap",
+  authorization: "Bearer fsrt_...",
+  request: {
+    instanceId: "string?",
+    sdkVersion: "string?",
+    sdkLanguage: "string?"
+  },
+  response: {
+    product: {
+      id: "string",
+      slug: "string"
+    },
+    backend: {
+      id: "string",
+      slug: "string",
+      name: "string"
+    },
+    environment: {
+      id: "string?",
+      kind: "live | test"
+    },
+    capabilities: "string[]",
+    verification: {
+      required: "boolean",
+      jwksUrl: "string",
+      clockSkewSeconds: "number",
+      replayWindowSeconds: "number",
+      headerNames: "object"
+    },
+    metering: {
+      enabled: "boolean",
+      endpoint: "string",
+      credential: "string",
+      allowedMeters: "string[]",
+      allowedRoutes: "string[]",
+      perEventMax: "number"
+    },
+    transport: {
+      mode: "public_origin | mtls | cloudflare_tunnel",
+      runner: "managed_cloudflared | sidecar | null",
+      originUrl: "string?",
+      originHostname: "string?",
+      localTarget: "string?",
+      cloudflared: "object?"
+    },
+    routes: "object[]",
+    policyVersion: "string",
+    refreshAfterSeconds: "number"
+  }
+};
+var RUNTIME_SIGNING_CONTRACT = {
+  algorithm: "Ed25519",
+  encoding: "base64url",
+  keyMaterial: "service-jwt-jwks",
+  canonicalString: {
+    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 \u2014 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.",
+    fieldSeparator: "\n",
+    keyValueSeparator: ":",
+    trailingNewline: false,
+    fieldEncoding: "utf-8",
+    fields: [
+      "method",
+      "path",
+      "query",
+      "body-hash",
+      "request-id",
+      "timestamp",
+      "product-id",
+      "backend-id",
+      "route-id",
+      "policy-version"
+    ],
+    fieldRules: {
+      method: "Uppercased HTTP method (e.g. GET, POST).",
+      path: "Request path, percent-encoded as received, no host, no query string. Always begins with '/'.",
+      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.",
+      "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'.",
+      "request-id": "Opaque unique request id minted by the gateway (also the replay-cache nonce).",
+      timestamp: "Integer Unix epoch seconds (UTC) at signing time, as a base-10 string with no padding.",
+      "product-id": "Product id the request is routed to.",
+      "backend-id": "Backend id the route binds to.",
+      "route-id": "Resolved route id; empty string if the route is unresolved.",
+      "policy-version": "Tenant artifact / policy version the gateway signed under."
+    }
+  }
+};
+var RUNTIME_CANONICAL_FIELDS = [
+  "method",
+  "path",
+  "query",
+  "body-hash",
+  "request-id",
+  "timestamp",
+  "product-id",
+  "backend-id",
+  "route-id",
+  "policy-version"
+];
+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_HEADERS = {
+  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_REPLAY_CONTRACT = {
+  windowSeconds: 300,
+  clockSkewSeconds: 5,
+  nonce: "x-fs-request-id",
+  nonceCache: "bounded-lru",
+  policy: "fail-closed"
+};
+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"
+};
+var RUNTIME_METERING_CONTRACT = {
+  endpoint: "/v1/metering/events",
+  method: "POST",
+  credential: "reusable-bearer",
+  event: {
+    event_id: "string",
+    product_id: "string",
+    backend_id: "string",
+    route_id: "string?",
+    request_id: "string?",
+    meter: "string",
+    qty: "number",
+    timestamp: "string"
+  },
+  idempotencyKey: "event_id",
+  delivery: "at-least-once",
+  billingOnly: true,
+  realtimeEnforced: false,
+  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."
+};
+var RUNTIME_HEALTH_CONTRACT = {
+  endpoint: "/v1/runtime/health",
+  method: "POST",
+  request: {
+    instanceId: "string?",
+    status: "starting | ready | degraded | stopping"
+  },
+  readinessStates: ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"],
+  checks: [
+    "runtime_token_valid",
+    "bootstrapped",
+    "tunnel_running",
+    "signed_request_2xx",
+    "unsigned_request_401",
+    "stale_signature_401",
+    "wrong_route_401",
+    "metering_observed"
+  ],
+  report: {
+    runtimeToken: "boolean",
+    bootstrap: "boolean",
+    tunnel: "string?",
+    verification: "boolean",
+    metering: "boolean"
+  }
+};
+var RUNTIME_TRANSPORT_CONTRACT = {
+  modes: {
+    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.",
+    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.",
+    cloudflare_tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The only Production-secure tier. Consumes Cloudflare tunnel/route slots."
+  },
+  runners: {
+    managed_cloudflared: "fs.start() supervises cloudflared as a child process (default DX).",
+    sidecar: "Vanilla cloudflare/cloudflared container beside the app (production / non-Node)."
+  },
+  channelTrust: ["mtls", "cloudflare_tunnel"],
+  requestTrust: "x-fs-signature",
+  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."
+};
+export {
+  RUNTIME_BODY_HASH_CONTRACT,
+  RUNTIME_BOOTSTRAP_CONTRACT,
+  RUNTIME_CANONICAL_FIELDS,
+  RUNTIME_CONTRACT_VERSION,
+  RUNTIME_ERROR_CODES,
+  RUNTIME_HEADERS,
+  RUNTIME_HEALTH_CONTRACT,
+  RUNTIME_METERING_CONTRACT,
+  RUNTIME_REPLAY_CONTRACT,
+  RUNTIME_SIGNING_CONTRACT,
+  RUNTIME_TOKEN_CONTRACT,
+  RUNTIME_TOKEN_ENV,
+  RUNTIME_TRANSPORT_CONTRACT
+};