@farthershore/backend 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,4 +1,188 @@
 import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/reflect/route-canon.ts
+import { createHash } from "node:crypto";
+function normalizeSegment(seg) {
+  if (seg === "**") return "{rest}";
+  if (seg === "*") return "{splat}";
+  if (seg.startsWith(":")) return `{${seg.slice(1)}}`;
+  if (seg.startsWith("[") && seg.endsWith("]")) return `{${seg.slice(1, -1)}}`;
+  return seg;
+}
+function normalizePath(path) {
+  if (path === "/" || path === "") return "/";
+  const lead = path.startsWith("/");
+  const out = path.split("/").filter((s) => s.length > 0).map(normalizeSegment).join("/");
+  return lead ? `/${out}` : out;
+}
+function pathSpecificity(path) {
+  return path.split("/").filter(
+    (s) => s.length > 0 && !s.startsWith("{") && s !== "*" && s !== "**"
+  ).length;
+}
+function canonicalSort(routes) {
+  return [...routes].sort(
+    (a, b) => pathSpecificity(b.path) - pathSpecificity(a.path) || a.method.localeCompare(b.method) || a.path.localeCompare(b.path)
+  );
+}
+function surfaceHash(routes) {
+  const canonical = canonicalSort(routes).map(
+    (r) => `${r.method.toUpperCase()} ${r.path}`
+  );
+  const h = createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+  return `sha256:${h}`;
+}
+var init_route_canon = __esm({
+  "src/reflect/route-canon.ts"() {
+    "use strict";
+  }
+});
+
+// src/reflect/index.ts
+var reflect_exports = {};
+__export(reflect_exports, {
+  reflectRoutes: () => reflectRoutes,
+  reflectRoutesDetailed: () => reflectRoutesDetailed
+});
+function methodsOf(route) {
+  const out = /* @__PURE__ */ new Set();
+  if (route.methods) {
+    for (const [m, on] of Object.entries(route.methods))
+      if (on) out.add(m.toUpperCase());
+  }
+  for (const s of route.stack ?? []) {
+    if (typeof s.method === "string") out.add(s.method.toUpperCase());
+  }
+  return [...out].filter((m) => VALID_METHODS.has(m));
+}
+function rootStack(app) {
+  const a = app;
+  return a?.router?.stack ?? a?._router?.stack;
+}
+function prefixFromRegexp(re) {
+  if (!re) return void 0;
+  let s = re.source;
+  if (s === "^\\/?$" || s === "^\\/") return "";
+  s = s.replace(/^\^/, "").replace(/\\\/\?\(\?=\\\/\|\$\)$/, "").replace(/\(\?=\\\/\|\$\)$/, "").replace(/\\\/\?$/, "").replace(/\$$/, "");
+  s = s.replace(/\\\//g, "/");
+  if (/[()?:*+\[\]|]/.test(s)) return void 0;
+  return s.startsWith("/") ? s : `/${s}`;
+}
+function walk(stack, prefix, out, counters) {
+  for (const layer of stack) {
+    if (layer.route && typeof layer.route.path === "string") {
+      const path = normalizePath(`${prefix}${layer.route.path}`);
+      for (const method of methodsOf(layer.route)) {
+        out.push({ method, path });
+      }
+    } else if (layer.handle?.stack && Array.isArray(layer.handle.stack)) {
+      const sub = prefixFromRegexp(layer.regexp);
+      if (sub === void 0 && layer.name === "router") {
+        counters.unreflectable += layer.handle.stack.filter(
+          (l) => l.route
+        ).length;
+        continue;
+      }
+      walk(layer.handle.stack, `${prefix}${sub ?? ""}`, out, counters);
+    }
+  }
+}
+function reflectRoutesDetailed(app, _opts) {
+  const stack = rootStack(app);
+  if (!stack) return { routes: [], unreflectable: 0 };
+  const raw = [];
+  const counters = { unreflectable: 0 };
+  walk(stack, "", raw, counters);
+  const seen = /* @__PURE__ */ new Set();
+  const routes = [];
+  for (const r of raw) {
+    if (r.method === "HEAD") continue;
+    const key2 = `${r.method} ${r.path}`;
+    if (seen.has(key2)) continue;
+    seen.add(key2);
+    routes.push(r);
+  }
+  return { routes, unreflectable: counters.unreflectable };
+}
+function reflectRoutes(app, opts) {
+  return reflectRoutesDetailed(app, opts).routes;
+}
+var VALID_METHODS;
+var init_reflect = __esm({
+  "src/reflect/index.ts"() {
+    "use strict";
+    init_route_canon();
+    VALID_METHODS = /* @__PURE__ */ new Set([
+      "GET",
+      "POST",
+      "PUT",
+      "PATCH",
+      "DELETE",
+      "OPTIONS"
+    ]);
+  }
+});
+
+// src/reflect/reconcile.ts
+var reconcile_exports = {};
+__export(reconcile_exports, {
+  reconcileOnStartup: () => reconcileOnStartup
+});
+function key(r) {
+  return `${r.method.toUpperCase()} ${r.path}`;
+}
+async function reconcileOnStartup(args) {
+  const { reflected, bootstrap, report } = args;
+  const reflectedHash = surfaceHash(reflected);
+  const lockVersion = bootstrap.lock?.lockVersion ?? 0;
+  const inSync = bootstrap.lock?.surfaceHash === reflectedHash;
+  const result = {
+    inSync,
+    reportedDrift: false,
+    confirmedRouteIds: []
+  };
+  const servedKeys = new Set(reflected.map(key));
+  const confirmedRouteIds = (bootstrap.routes ?? []).filter(
+    (r) => r.pending === true && servedKeys.has(key(r)) && typeof r.id === "string"
+  ).map((r) => r.id);
+  try {
+    if (confirmedRouteIds.length > 0) {
+      await report.confirmServed({
+        backendId: bootstrap.backendId,
+        lockVersion,
+        servedRouteIds: confirmedRouteIds
+      });
+      result.confirmedRouteIds = confirmedRouteIds;
+    }
+    if (!inSync) {
+      await report.reportDrift({
+        backendId: bootstrap.backendId,
+        lockVersion,
+        reflectedSurfaceHash: reflectedHash,
+        routes: reflected.map((r) => ({ method: r.method, path: r.path }))
+      });
+      result.reportedDrift = true;
+    }
+  } catch (err) {
+    result.reportError = err instanceof Error ? err.message : String(err);
+  }
+  return result;
+}
+var init_reconcile = __esm({
+  "src/reflect/reconcile.ts"() {
+    "use strict";
+    init_route_canon();
+  }
+});
 
 // src/runtime-types.ts
 var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
@@ -10,7 +194,10 @@ var RUNTIME_TOKEN_CAPABILITIES = [
   "gateway_verification",
   "metering",
   "health",
-  "tunnel"
+  "tunnel",
+  // Mirror of @farthershore/contracts RUNTIME_TOKEN_CAPABILITIES — kept in
+  // lockstep (golden-vector test). Opt-in capability for reporting route drift.
+  "drift_report"
 ];
 var RUNTIME_HEADER_NAMES = {
   signature: "x-fs-signature",
@@ -117,13 +304,13 @@ async function importEd25519PublicKey(jwk) {
   return crypto.subtle.importKey("jwk", { ...jwk, alg: void 0 }, { name: ED25519_ALGORITHM }, false, ["verify"]);
 }
 async function signCanonicalString(canonical, privateJwk) {
-  const key = await importEd25519PrivateKey(privateJwk);
-  const sig = await crypto.subtle.sign(ED25519_ALGORITHM, key, new TextEncoder().encode(canonical));
+  const key2 = await importEd25519PrivateKey(privateJwk);
+  const sig = await crypto.subtle.sign(ED25519_ALGORITHM, key2, new TextEncoder().encode(canonical));
   return base64UrlEncode(new Uint8Array(sig));
 }
 async function verifyCanonicalSignature(canonical, signatureB64Url, publicJwk) {
-  const key = await importEd25519PublicKey(publicJwk);
-  return crypto.subtle.verify(ED25519_ALGORITHM, key, base64UrlDecode(signatureB64Url), new TextEncoder().encode(canonical));
+  const key2 = await importEd25519PublicKey(publicJwk);
+  return crypto.subtle.verify(ED25519_ALGORITHM, key2, base64UrlDecode(signatureB64Url), new TextEncoder().encode(canonical));
 }
 function toHex(bytes) {
   let out = "";
@@ -345,10 +532,10 @@ var JwksClient = class {
       );
     }
     await this.refresh();
-    const key = this.keysByKid.get(kid);
-    if (key) {
+    const key2 = this.keysByKid.get(kid);
+    if (key2) {
       this.negativeKids.delete(kid);
-      return key;
+      return key2;
     }
     this.rememberMissingKid(kid);
     throw new FartherShoreError(
@@ -402,8 +589,8 @@ var JwksClient = class {
       return;
     }
     const next = /* @__PURE__ */ new Map();
-    for (const key of doc.keys ?? []) {
-      if (typeof key.kid === "string") next.set(key.kid, key);
+    for (const key2 of doc.keys ?? []) {
+      if (typeof key2.kid === "string") next.set(key2.kid, key2);
     }
     this.keysByKid = next;
     this.fetchedAt = this.now();
@@ -1032,12 +1219,12 @@ function headerGetter(headers) {
     return (name) => h.get(name) ?? void 0;
   }
   const lower = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(
+  for (const [key2, value] of Object.entries(
     headers
   )) {
     if (value === void 0) continue;
     lower.set(
-      key.toLowerCase(),
+      key2.toLowerCase(),
       Array.isArray(value) ? value[0] ?? "" : value
     );
   }
@@ -1046,7 +1233,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.2.0".length > 0 ? "0.2.0" : "0.0.0-dev";
+var SDK_VERSION = "0.3.0".length > 0 ? "0.3.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1117,6 +1304,60 @@ var FartherShore = class {
     this.bootstrapped = true;
     return config;
   }
+  /**
+   * Boot-time route reconciliation (call once, before `listen()`). Reflects the
+   * app's real route surface, diffs it against the declared lock from bootstrap,
+   * REPORTS drift to the platform, and CONFIRMS the declared `pending` routes
+   * this replica serves. Fail-OPEN: never throws / never blocks boot.
+   *
+   * The reflection code is dynamically imported so it stays OFF the per-request
+   * verification hot path (the runtime stays route-unaware there). The report is
+   * an OUTBOUND backend→core call (same channel as bootstrap/metering), so it
+   * works for every transport (public_origin / mTLS / cloudflare_tunnel).
+   *
+   * Returns the reconcile result (or null if reflection is unavailable / boot
+   * reporting failed). v1 reflects Express; `app` omitted → no-op.
+   */
+  async ready(app) {
+    try {
+      const config = await this.ensureBootstrapped();
+      if (app === void 0) return null;
+      const [{ reflectRoutes: reflectRoutes2 }, { reconcileOnStartup: reconcileOnStartup2 }] = await Promise.all([
+        Promise.resolve().then(() => (init_reflect(), reflect_exports)),
+        Promise.resolve().then(() => (init_reconcile(), reconcile_exports))
+      ]);
+      return await reconcileOnStartup2({
+        reflected: reflectRoutes2(app),
+        bootstrap: {
+          backendId: config.backend.id,
+          lock: config.lock,
+          routes: config.routes
+        },
+        report: this.buildReportSink()
+      });
+    } catch {
+      return null;
+    }
+  }
+  /** Outbound report sink for `ready()` — runtime-token-authed POSTs to core. */
+  buildReportSink() {
+    const post = async (path, body) => {
+      const base = this.coreUrl.replace(/\/$/, "");
+      const res = await this.fetchImpl(`${base}${path}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.runtimeToken}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) throw new Error(`runtime report ${path} -> ${res.status}`);
+    };
+    return {
+      reportDrift: (report) => post("/v1/runtime/drift", report),
+      confirmServed: (confirm) => post("/v1/runtime/health", confirm)
+    };
+  }
   /**
    * Framework-neutral verification primitive. Fail-closed: throws a typed
    * FartherShoreError on any verification failure. Returns the verified context.
@@ -1471,12 +1712,12 @@ function resolveToken(options) {
   }
   return token;
 }
-function processEnv(key) {
+function processEnv(key2) {
   const maybeProcess = globalThis.process;
-  return maybeProcess?.env?.[key];
+  return maybeProcess?.env?.[key2];
 }
 async function signPayload(payload, token) {
-  const key = await crypto.subtle.importKey(
+  const key2 = await crypto.subtle.importKey(
     "raw",
     new TextEncoder().encode(token),
     { name: "HMAC", hash: "SHA-256" },
@@ -1485,7 +1726,7 @@ async function signPayload(payload, token) {
   );
   const signature = await crypto.subtle.sign(
     "HMAC",
-    key,
+    key2,
     new TextEncoder().encode(payload)
   );
   return base64url(new Uint8Array(signature));

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

@@ -1,4 +1,5 @@
 import { type RuntimeBootstrapResponse, type RuntimeHealthReport } from "../runtime-types.js";
+import type { ReconcileResult } from "../reflect/reconcile.js";
 import { type MeterOptions } from "./metering.js";
 import { type SpawnFn } from "./tunnel.js";
 import { type FartherShoreRequestContext, type VerifyRequestInput } from "./verifyRequest.js";
@@ -62,6 +63,23 @@ export declare class FartherShore {
     constructor(options?: FartherShoreInitOptions);
     /** Ensure bootstrap config is loaded; build the JWKS + metering clients. */
     ensureBootstrapped(): Promise<RuntimeBootstrapResponse>;
+    /**
+     * Boot-time route reconciliation (call once, before `listen()`). Reflects the
+     * app's real route surface, diffs it against the declared lock from bootstrap,
+     * REPORTS drift to the platform, and CONFIRMS the declared `pending` routes
+     * this replica serves. Fail-OPEN: never throws / never blocks boot.
+     *
+     * The reflection code is dynamically imported so it stays OFF the per-request
+     * verification hot path (the runtime stays route-unaware there). The report is
+     * an OUTBOUND backend→core call (same channel as bootstrap/metering), so it
+     * works for every transport (public_origin / mTLS / cloudflare_tunnel).
+     *
+     * Returns the reconcile result (or null if reflection is unavailable / boot
+     * reporting failed). v1 reflects Express; `app` omitted → no-op.
+     */
+    ready(app?: unknown): Promise<ReconcileResult | null>;
+    /** Outbound report sink for `ready()` — runtime-token-authed POSTs to core. */
+    private buildReportSink;
     /**
      * Framework-neutral verification primitive. Fail-closed: throws a typed
      * FartherShoreError on any verification failure. Returns the verified context.

package/dist/types/reflect/index.d.ts

@@ -0,0 +1,16 @@
+import type { ReflectedRoute } from "./route-canon.js";
+export interface ReflectResult {
+    routes: ReflectedRoute[];
+    /** Count of sub-mounted routes that couldn't be reflected (Express-5 mount). */
+    unreflectable: number;
+}
+export interface ReflectOptions {
+    framework?: "express";
+}
+/** Reflect with diagnostics. Use `reflectRoutes` for just the canonical list. */
+export declare function reflectRoutesDetailed(app: unknown, _opts?: ReflectOptions): ReflectResult;
+/**
+ * Reflect the routes an Express app serves into the canonical `ReflectedRoute[]`.
+ * Deduped, HEAD-suppressed, canonical paths (`:id`→`{id}`).
+ */
+export declare function reflectRoutes(app: unknown, opts?: ReflectOptions): ReflectedRoute[];

package/dist/types/reflect/reconcile.d.ts

@@ -0,0 +1,42 @@
+import { type ReflectedRoute, type DriftReport, type PendingConfirm } from "./route-canon.js";
+/** The slice of the bootstrap response reconciliation needs. */
+export interface StartupBootstrap {
+    backendId: string;
+    lock?: {
+        surfaceHash: string;
+        lockVersion: number;
+    };
+    routes?: Array<{
+        id?: string;
+        method: string;
+        path: string;
+        pending?: boolean;
+    }>;
+}
+/** Where reconciliation sends its outbound reports (DI for tests + transport). */
+export interface ReportSink {
+    /** PR-opening drift report → `POST /v1/runtime/drift`. */
+    reportDrift(report: DriftReport): Promise<void> | void;
+    /** Confirm served pending routes → rides `/v1/runtime/health`. */
+    confirmServed(confirm: PendingConfirm): Promise<void> | void;
+}
+export interface ReconcileResult {
+    /** Reflected surface matched the declared lock. */
+    inSync: boolean;
+    /** A drift report was sent. */
+    reportedDrift: boolean;
+    /** Route ids confirmed served (pending → clearable). */
+    confirmedRouteIds: string[];
+    /** A report sink call failed (swallowed — boot never blocks on it). */
+    reportError?: string;
+}
+/**
+ * Reconcile the reflected surface against the declared lock at startup.
+ * Idempotent + multi-replica-safe (all replicas compute the same hash; confirm
+ * carries `lockVersion` for the server's optimistic-concurrency check).
+ */
+export declare function reconcileOnStartup(args: {
+    reflected: readonly ReflectedRoute[];
+    bootstrap: StartupBootstrap;
+    report: ReportSink;
+}): Promise<ReconcileResult>;

package/dist/types/reflect/route-canon.d.ts

@@ -0,0 +1,20 @@
+/** A reflected route — method + canonical path. Mirrors contracts ReflectedRoute. */
+export interface ReflectedRoute {
+    method: string;
+    path: string;
+}
+/** Backend → core drift report. Mirrors contracts DriftReport. */
+export interface DriftReport {
+    backendId: string;
+    lockVersion: number;
+    reflectedSurfaceHash: string;
+    routes: ReflectedRoute[];
+}
+/** Backend → core pending confirmation. Mirrors contracts PendingConfirm. */
+export interface PendingConfirm {
+    backendId: string;
+    lockVersion: number;
+    servedRouteIds: string[];
+}
+export declare function normalizePath(path: string): string;
+export declare function surfaceHash(routes: readonly ReflectedRoute[]): string;

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

@@ -5,7 +5,7 @@ export declare const RUNTIME_TOKEN_PREFIXES: {
     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 declare const RUNTIME_TOKEN_CAPABILITIES: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];
 export type RuntimeTokenCapability = (typeof RUNTIME_TOKEN_CAPABILITIES)[number];
 export declare const RUNTIME_HEADER_NAMES: {
     readonly signature: "x-fs-signature";
@@ -93,6 +93,14 @@ export type RuntimeRouteDescriptor = {
     method: string;
     path: string;
     backendId: string;
+    /** Declared-but-not-yet-confirmed-served route. `fs.ready()` confirms the ones
+     *  this replica actually serves so core can clear the flag and publish. */
+    pending?: boolean;
+};
+/** The declared route-surface lock the backend reconciles against at startup. */
+export type RuntimeLockDescriptor = {
+    surfaceHash: string;
+    lockVersion: number;
 };
 export type RuntimeBootstrapResponse = {
     product: {
@@ -113,6 +121,9 @@ export type RuntimeBootstrapResponse = {
     metering: RuntimeMeteringConfig;
     transport: RuntimeTransportConfig;
     routes: RuntimeRouteDescriptor[];
+    /** Reflected route-surface lock (surfaceHash + version). Present once core
+     *  serves it; `fs.ready()` diffs the reflected surface against it. */
+    lock?: RuntimeLockDescriptor;
     policyVersion: string;
     refreshAfterSeconds: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, health, and lifecycle from FS_RUNTIME_TOKEN",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,10 @@
       "types": "./dist/types/adapters/express.d.ts",
       "import": "./dist/adapters/express.js"
     },
+    "./reflect": {
+      "types": "./dist/types/reflect/index.d.ts",
+      "import": "./dist/reflect/index.js"
+    },
     "./runtime": {
       "types": "./dist/types/generated/runtime-contract.d.ts",
       "import": "./dist/generated/runtime-contract.js"