@farthershore/backend 0.19.0 → 0.21.0

package/dist/adapters/express.js

@@ -24,6 +24,7 @@ function statusForCode(code) {
 }
 
 // src/core/permissions.ts
+var WILDCARD = "*";
 var FartherShorePermissionError = class extends Error {
   code = "permission_denied";
   status = 403;
@@ -35,6 +36,31 @@ var FartherShorePermissionError = class extends Error {
     this.requiredPermission = requiredPermission;
   }
 };
+function permissionSatisfies(required, granted) {
+  if (granted === void 0) return true;
+  if (granted.includes(WILDCARD)) return true;
+  if (granted.includes(required)) return true;
+  const idx = required.indexOf(":");
+  if (idx > 0 && idx < required.length - 1) {
+    const subject = required.slice(0, idx);
+    if (subject !== WILDCARD && granted.includes(`${subject}:${WILDCARD}`))
+      return true;
+    if (required.slice(idx + 1) === WILDCARD && subject !== WILDCARD) {
+      const prefix = `${subject}:`;
+      return granted.some((permission) => permission.startsWith(prefix));
+    }
+  }
+  return false;
+}
+function hasPermission(ctx, key) {
+  if (ctx.permissions === void 0) return false;
+  return permissionSatisfies(key, ctx.permissions);
+}
+function requirePermission(ctx, key) {
+  if (!hasPermission(ctx, key)) {
+    throw new FartherShorePermissionError(key);
+  }
+}
 
 // src/generated/runtime-contract.ts
 var RUNTIME_BODY_HASH_CONTRACT = {
@@ -73,14 +99,17 @@ async function runMiddleware(fs, options, req, res, next) {
     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
-    });
+    const ctx = await fs.verifyRequest(
+      {
+        method: req.method,
+        path,
+        query,
+        headers: req.headers,
+        body,
+        streamingExempt
+      },
+      { responseSink: expressResponseSink(res) }
+    );
     req.fartherShore = ctx;
     stripFartherShoreHeaders(req);
     next();
@@ -88,6 +117,16 @@ async function runMiddleware(fs, options, req, res, next) {
     fail(res, error, options, req);
   }
 }
+function expressResponseSink(res) {
+  return {
+    canStampHeaders: () => res.headersSent !== true,
+    stampHeaders: (headers) => {
+      for (const [name, value] of Object.entries(headers)) {
+        res.setHeader(name, value);
+      }
+    }
+  };
+}
 function fail(res, error, options, req) {
   const code = error instanceof FartherShoreError ? error.code : "bad_signature";
   const status = error instanceof FartherShoreError ? error.status : 401;
@@ -128,7 +167,12 @@ function stripFartherShoreHeaders(req) {
     withRaw.rawHeaders = cleaned;
   }
 }
-function createExpressHandler(handler) {
+function createExpressHandler(optionsOrHandler, maybeHandler) {
+  const options = typeof optionsOrHandler === "function" ? {} : optionsOrHandler;
+  const handler = typeof optionsOrHandler === "function" ? optionsOrHandler : maybeHandler;
+  if (typeof handler !== "function") {
+    throw new TypeError("fs.handler(options, cb) requires a handler callback");
+  }
   return (req, res, next) => {
     const ctx = req.fartherShore;
     if (!ctx) {
@@ -139,10 +183,22 @@ function createExpressHandler(handler) {
       res.status(401).json({ error: "principal_required" });
       return;
     }
+    if (!ctx.signedContext) {
+      res.status(401).json({ error: "context_unverified" });
+      return;
+    }
     const verified = ctx;
-    void Promise.resolve().then(
-      () => handler(verified, req, res, next)
-    ).catch((error) => failHandler(res, next, error));
+    void Promise.resolve().then(() => {
+      if (options.permission !== void 0) {
+        requirePermission(verified, options.permission);
+      }
+      return handler(
+        verified,
+        req,
+        res,
+        next
+      );
+    }).catch((error) => failHandler(res, next, error));
   };
 }
 function failHandler(res, next, error) {

package/dist/generated/runtime-contract.js

@@ -1,154 +1,6 @@
 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: "direct | tunnel",
-      runner: "embedded | 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",
-      "business-id",
-      "backend-id",
-      "route-id",
-      "policy-version",
-      "context-hash"
-    ],
-    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: "The request's query string bytes VERBATIM, after the caller has stripped the URL's single leading '?' delimiter. Use the RAW wire query exactly as received \u2014 NO sorting, NO filtering, NO re-stripping a leading '?', NO dropping empty pairs, NO re-encoding. The signature binds to the exact query bytes: any reorder, added/removed/relocated pair, or re-encoding changes the bytes and MUST fail verification. Every SDK verifier MUST read the raw wire query (never a re-parsed/re-serialized form, which could reorder or re-encode and would then fail legitimate requests). Any normalization (sorting by name or value, dropping/moving empty pairs, re-stripping '?') is FORBIDDEN \u2014 each collapses distinct wire queries under one signature. 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.",
-      "business-id": "Business 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.",
-      "context-hash": "Lowercase hex SHA-256 of the presented X-Fs-Context JWT string (identity-context binding). For a request with no signed context, the SHA-256 of the empty string (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Binds the identity context into the request signature so one verification covers both."
-    }
-  }
-};
-var RUNTIME_CANONICAL_FIELDS = [
-  "method",
-  "path",
-  "query",
-  "body-hash",
-  "request-id",
-  "timestamp",
-  "business-id",
-  "backend-id",
-  "route-id",
-  "policy-version",
-  "context-hash"
-];
-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",
-  businessId: "x-fs-business-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",
@@ -169,40 +21,19 @@ var RUNTIME_ERROR_CODES = {
   serviceSubjectRequired: "service_subject_required",
   surfaceNotAllowed: "surface_not_allowed"
 };
-var RUNTIME_METERING_CONTRACT = {
-  endpoint: "/v1/metering/events",
-  method: "POST",
-  credential: "reusable-bearer",
-  event: {
-    event_id: "string",
-    business_id: "string",
-    backend_id: "string",
-    route_id: "string?",
-    request_id: "string?",
-    requestId: "string?",
-    subscriptionId: "string",
-    nonce: "string?",
-    meter: "string",
-    qty: "number",
-    timestamp: "string"
-  },
-  postStreamEvent: {
-    requestId: "string",
-    subscriptionId: "string?",
-    nonce: "string",
-    meters: "Record<string, number>",
-    creditUnitsConsumed: "Record<string, number>?",
-    measureContext: "Record<string, unknown>?",
-    signature: "string"
-  },
-  idempotencyKey: "event_id",
-  delivery: "at-least-once",
-  billingOnly: true,
-  realtimeEnforced: false,
-  postStreamBillingOnly: true,
-  postStreamRealtimeEnforced: false,
-  postStreamTrustModel: "HMAC-attested and bound to one served postStreamBilling gateway request. Core writes one billable UsageEvent using the served plan and time. The callback never mutates Durable Object enforcement windows.",
-  trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream 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_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_RESPONSE_METERING_CONTRACT = {
   headers: {
@@ -224,14 +55,18 @@ var RUNTIME_RESPONSE_METERING_CONTRACT = {
   payload: {
     method: "string",
     path: "string",
-    rawDimsUnits: "Record<string, number>",
+    rawDimsUnits: "Record<string, number>?",
     measureContext: "Record<string, unknown>?",
-    creditUnitsConsumed: "Record<string, number>?"
+    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"
+    invalidMeterValue: "invalid_meter_value",
+    invalidQuote: "invalid_quote"
   },
   httpAdapter: {
     input: "Request",
@@ -241,58 +76,8 @@ var RUNTIME_RESPONSE_METERING_CONTRACT = {
     gatewayStripsInternalHeaders: true
   }
 };
-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: {
-    direct: "Gateway fetches the builder's public origin URL; the SDK middleware fail-closed-verifies every request via Ed25519 request signing. Provisions zero Cloudflare objects. Available on all tiers; also the dev path.",
-    tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The Production-secure tier. Consumes Cloudflare tunnel/route slots."
-  },
-  runners: {
-    embedded: "fs.start() supervises cloudflared as a child process (default DX).",
-    sidecar: "Vanilla cloudflare/cloudflared container beside the app (production / non-Node)."
-  },
-  channelTrust: ["tunnel"],
-  requestTrust: "x-fs-signature",
-  invariant: "Channel trust (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_RESPONSE_METERING_CONTRACT,
-  RUNTIME_SIGNING_CONTRACT,
-  RUNTIME_TOKEN_CONTRACT,
-  RUNTIME_TOKEN_ENV,
-  RUNTIME_TRANSPORT_CONTRACT
+  RUNTIME_RESPONSE_METERING_CONTRACT
 };