@crewhaus/federation-discovery 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/federation-discovery",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Federation peer lookup: DNS SRV + .well-known/crewhaus.json with TTL caching (Section 34)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/federation-discovery"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/federation-discovery#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  FederationDiscoveryError,
+  type PeerRecord,
+  type SrvResolver,
+  type WellKnownFetcher,
+  createDiscovery,
+  discoverDeployment,
+} from "./index";
+
+const HEX64 = "a".repeat(64);
+
+const goodPayload = {
+  endpoint: "https://federation.deployment-b.example",
+  version: "crewhaus.federation.v1",
+  supportedShapes: ["cli", "crew"],
+  publicKeyFingerprint: HEX64,
+};
+
+function fetcherReturning(payload: unknown, status = 200): WellKnownFetcher {
+  return async () => ({ status, body: JSON.stringify(payload) });
+}
+
+describe("createDiscovery — happy path (T2)", () => {
+  test("falls back to .well-known when no SRV configured", async () => {
+    const d = createDiscovery({ wellKnownFetcher: fetcherReturning(goodPayload) });
+    const rec = await d.discover("deployment-b.example");
+    expect(rec.endpoint).toBe("https://federation.deployment-b.example");
+    expect(rec.version).toBe("crewhaus.federation.v1");
+    expect(rec.supportedShapes).toEqual(["cli", "crew"]);
+    expect(rec.publicKeyFingerprint).toBe(HEX64);
+  });
+
+  test("SRV-then-.well-known: SRV returns target, then well-known is fetched against that endpoint", async () => {
+    const srv: SrvResolver = async () => ({
+      records: [{ priority: 10, weight: 5, port: 8443, name: "fed.deployment-b.example" }],
+      ttl: 60,
+    });
+    const seenUrls: string[] = [];
+    const fetcher: WellKnownFetcher = async (url) => {
+      seenUrls.push(url);
+      return { status: 200, body: JSON.stringify(goodPayload) };
+    };
+    const d = createDiscovery({
+      srvDomain: "internal.crewhaus",
+      srvResolver: srv,
+      wellKnownFetcher: fetcher,
+    });
+    const rec = await d.discover("deployment-b");
+    expect(seenUrls[0]).toBe("https://fed.deployment-b.example:8443/.well-known/crewhaus.json");
+    // SRV is the source of truth for the endpoint, so the discovered
+    // record's endpoint is the SRV-derived URL, not the well-known body's.
+    expect(rec.endpoint).toBe("https://fed.deployment-b.example:8443");
+    expect(rec.publicKeyFingerprint).toBe(HEX64);
+  });
+
+  test("SRV miss → falls through to direct .well-known fetch", async () => {
+    const srv: SrvResolver = async () => {
+      throw new Error("ENOTFOUND");
+    };
+    const d = createDiscovery({
+      srvDomain: "internal.crewhaus",
+      srvResolver: srv,
+      wellKnownFetcher: fetcherReturning(goodPayload),
+    });
+    const rec = await d.discover("deployment-b.example");
+    expect(rec.endpoint).toBe(goodPayload.endpoint);
+  });
+});
+
+describe("createDiscovery — failure modes (T8)", () => {
+  test("rejects malformed deployment id", async () => {
+    const d = createDiscovery({ wellKnownFetcher: fetcherReturning(goodPayload) });
+    await expect(d.discover("../bad")).rejects.toThrow(/invalid deployment id/);
+    await expect(d.discover("")).rejects.toThrow(/non-empty/);
+  });
+
+  test("rejects non-200 .well-known", async () => {
+    const d = createDiscovery({
+      wellKnownFetcher: async () => ({ status: 503, body: "" }),
+    });
+    await expect(d.discover("deployment-b.example")).rejects.toThrow(/returned 503/);
+  });
+
+  test("rejects malformed JSON", async () => {
+    const d = createDiscovery({
+      wellKnownFetcher: async () => ({ status: 200, body: "not json{" }),
+    });
+    await expect(d.discover("deployment-b.example")).rejects.toThrow(/invalid JSON/);
+  });
+
+  test("rejects http:// endpoint (https only)", async () => {
+    const d = createDiscovery({
+      wellKnownFetcher: fetcherReturning({
+        ...goodPayload,
+        endpoint: "http://insecure.example",
+      }),
+    });
+    await expect(d.discover("deployment-b.example")).rejects.toThrow(/must be https/);
+  });
+
+  test("rejects malformed publicKeyFingerprint", async () => {
+    const d = createDiscovery({
+      wellKnownFetcher: fetcherReturning({
+        ...goodPayload,
+        publicKeyFingerprint: "abc",
+      }),
+    });
+    await expect(d.discover("deployment-b.example")).rejects.toThrow(
+      /publicKeyFingerprint must be 64-char hex/,
+    );
+  });
+
+  test("rejects record missing endpoint+version", async () => {
+    const d = createDiscovery({
+      wellKnownFetcher: fetcherReturning({ publicKeyFingerprint: HEX64 }),
+    });
+    await expect(d.discover("deployment-b.example")).rejects.toThrow(
+      /endpoint\+version are required/,
+    );
+  });
+});
+
+describe("createDiscovery — caching (T9 property-style)", () => {
+  test("hits the cache before TTL expiry", async () => {
+    let calls = 0;
+    const fetcher: WellKnownFetcher = async () => {
+      calls++;
+      return { status: 200, body: JSON.stringify(goodPayload) };
+    };
+    const d = createDiscovery({ wellKnownFetcher: fetcher });
+    await d.discover("deployment-b.example");
+    await d.discover("deployment-b.example");
+    await d.discover("deployment-b.example");
+    expect(calls).toBe(1);
+  });
+
+  test("re-fetches after TTL expires", async () => {
+    let now = 1000;
+    let calls = 0;
+    const fetcher: WellKnownFetcher = async () => {
+      calls++;
+      return { status: 200, body: JSON.stringify(goodPayload) };
+    };
+    const d = createDiscovery({ wellKnownFetcher: fetcher, now: () => now });
+    await d.discover("deployment-b.example");
+    expect(calls).toBe(1);
+    now += 5_000;
+    await d.discover("deployment-b.example");
+    expect(calls).toBe(1); // still in TTL
+    now += 60_000;
+    await d.discover("deployment-b.example");
+    expect(calls).toBe(2); // TTL expired
+  });
+
+  test("negative cache: failed lookup short-circuits within negativeTtlMs", async () => {
+    let now = 0;
+    let calls = 0;
+    const fetcher: WellKnownFetcher = async () => {
+      calls++;
+      return { status: 503, body: "" };
+    };
+    const d = createDiscovery({
+      wellKnownFetcher: fetcher,
+      now: () => now,
+      negativeTtlMs: 5_000,
+    });
+    await expect(d.discover("deployment-b.example")).rejects.toThrow();
+    now += 1_000;
+    await expect(d.discover("deployment-b.example")).rejects.toThrow(/cached negative/);
+    expect(calls).toBe(1);
+    now += 5_000;
+    await expect(d.discover("deployment-b.example")).rejects.toThrow(/returned 503/);
+    expect(calls).toBe(2);
+  });
+
+  test("reset() clears the cache", async () => {
+    let calls = 0;
+    const fetcher: WellKnownFetcher = async () => {
+      calls++;
+      return { status: 200, body: JSON.stringify(goodPayload) };
+    };
+    const d = createDiscovery({ wellKnownFetcher: fetcher });
+    await d.discover("deployment-b.example");
+    expect(calls).toBe(1);
+    d.reset();
+    await d.discover("deployment-b.example");
+    expect(calls).toBe(2);
+  });
+
+  test("cacheStats reports current entries", async () => {
+    const d = createDiscovery({ wellKnownFetcher: fetcherReturning(goodPayload) });
+    await d.discover("deployment-b.example");
+    await d.discover("deployment-c.example");
+    expect(d.cacheStats().entries).toBe(2);
+  });
+});
+
+describe("discoverDeployment top-level helper", () => {
+  test("returns the resolved record", async () => {
+    const rec: PeerRecord = await discoverDeployment("deployment-b.example", {
+      wellKnownFetcher: fetcherReturning(goodPayload),
+    });
+    expect(rec).toEqual({
+      endpoint: goodPayload.endpoint,
+      version: "crewhaus.federation.v1",
+      supportedShapes: goodPayload.supportedShapes,
+      publicKeyFingerprint: HEX64,
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,258 @@
+/**
+ * @crewhaus/federation-discovery — Section 34
+ *
+ * Peer lookup for federation. Two methods:
+ *
+ *   1. DNS SRV — `_crewhaus._tcp.<deployment>.<domain>` returns a list
+ *      of `<weight, priority, port, target>` records. The first record
+ *      (sorted by priority then weight) wins.
+ *
+ *   2. `.well-known/crewhaus.json` — `https://<deployment>/.well-known/crewhaus.json`
+ *      returns a JSON object describing the peer's endpoint, supported
+ *      shapes, and public-key fingerprint.
+ *
+ * The discovered record is cached with TTL = SRV TTL (when available)
+ * or 60s for `.well-known`. Negative results are cached too (10s) so a
+ * misconfigured peer doesn't trigger DNS storms.
+ *
+ * Both lookups are pluggable via injected resolvers — production uses
+ * `node:dns/promises.resolveSrv` and `globalThis.fetch`, tests pass
+ * fake implementations.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export class FederationDiscoveryError extends CrewhausError {
+  override readonly name = "FederationDiscoveryError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export type PeerRecord = {
+  /** Discovered HTTPS endpoint, e.g. https://federation.deployment-b.example */
+  readonly endpoint: string;
+  /** Federation protocol version the peer speaks. */
+  readonly version: string;
+  /** Target shapes the peer's roles can serve. */
+  readonly supportedShapes: readonly string[];
+  /** SHA256 fingerprint (hex, no separators) of the peer's leaf cert. */
+  readonly publicKeyFingerprint: string;
+};
+
+export type SrvRecord = {
+  readonly priority: number;
+  readonly weight: number;
+  readonly port: number;
+  readonly name: string;
+};
+
+export type SrvResolver = (name: string) => Promise<{
+  readonly records: readonly SrvRecord[];
+  readonly ttl: number;
+}>;
+
+export type WellKnownFetcher = (url: string) => Promise<{
+  readonly status: number;
+  readonly body: string;
+}>;
+
+export type DiscoveryConfig = {
+  readonly srvDomain?: string;
+  readonly srvResolver?: SrvResolver;
+  readonly wellKnownFetcher?: WellKnownFetcher;
+  readonly now?: () => number;
+  /** Cache TTL for negative-result lookups. Default 10s. */
+  readonly negativeTtlMs?: number;
+  /**
+   * Allow `http://localhost:*` / `http://127.0.0.1:*` endpoints. Default
+   * false (production deployments must use HTTPS). Used by tests to
+   * stand up in-process Bun.serve fixtures without TLS.
+   */
+  readonly allowInsecureLocalhost?: boolean;
+};
+
+export type Discovery = {
+  discover(deployment: string): Promise<PeerRecord>;
+  /** Inspect cache state — used by ops + tests. */
+  cacheStats(): {
+    entries: number;
+    expirations: ReadonlyArray<{ deployment: string; expiresAt: number }>;
+  };
+  reset(): void;
+};
+
+type CacheEntry =
+  | { readonly kind: "hit"; readonly record: PeerRecord; readonly expiresAt: number }
+  | { readonly kind: "miss"; readonly expiresAt: number };
+
+export function createDiscovery(config: DiscoveryConfig = {}): Discovery {
+  const cache = new Map<string, CacheEntry>();
+  const now = config.now ?? (() => Date.now());
+  const negativeTtlMs = config.negativeTtlMs ?? 10_000;
+
+  return {
+    async discover(deployment: string): Promise<PeerRecord> {
+      assertDeployment(deployment);
+      const cached = cache.get(deployment);
+      if (cached !== undefined) {
+        if (cached.expiresAt > now()) {
+          if (cached.kind === "hit") return cached.record;
+          throw new FederationDiscoveryError(`peer ${deployment} unreachable (cached negative)`);
+        }
+        cache.delete(deployment);
+      }
+
+      try {
+        const record = await lookup(deployment, config);
+        cache.set(deployment, { kind: "hit", record, expiresAt: now() + recordTtl(record) });
+        return record;
+      } catch (cause) {
+        cache.set(deployment, { kind: "miss", expiresAt: now() + negativeTtlMs });
+        if (cause instanceof FederationDiscoveryError) throw cause;
+        throw new FederationDiscoveryError(
+          `peer discovery failed for ${deployment}: ${(cause as Error).message}`,
+          cause,
+        );
+      }
+    },
+
+    cacheStats() {
+      const entries = Array.from(cache.entries()).map(([deployment, e]) => ({
+        deployment,
+        expiresAt: e.expiresAt,
+      }));
+      return { entries: cache.size, expirations: entries };
+    },
+
+    reset() {
+      cache.clear();
+    },
+  };
+}
+
+const DEFAULT_RECORD_TTL_MS = 60_000;
+
+function recordTtl(_record: PeerRecord): number {
+  return DEFAULT_RECORD_TTL_MS;
+}
+
+function assertDeployment(deployment: string): void {
+  if (typeof deployment !== "string" || !deployment.length) {
+    throw new FederationDiscoveryError("deployment id must be a non-empty string");
+  }
+  // Block obvious DNS injection attempts; allow standard domain shape.
+  if (!/^[a-zA-Z0-9.-]+$/.test(deployment)) {
+    throw new FederationDiscoveryError(`invalid deployment id: ${deployment}`);
+  }
+}
+
+async function lookup(deployment: string, config: DiscoveryConfig): Promise<PeerRecord> {
+  // Prefer SRV when a srvDomain is configured + a resolver is available.
+  if (config.srvDomain && config.srvResolver) {
+    const srvName = `_crewhaus._tcp.${deployment}.${config.srvDomain}`;
+    try {
+      const { records } = await config.srvResolver(srvName);
+      const sorted = [...records].sort((a, b) => a.priority - b.priority || b.weight - a.weight);
+      const head = sorted[0];
+      if (head !== undefined) {
+        const endpoint = `https://${head.name}:${head.port}`;
+        // Even with an SRV hit, we still call .well-known to get the full
+        // record (supportedShapes + fingerprint). SRV alone doesn't carry
+        // public-key info.
+        const wellKnown = await fetchWellKnown(endpoint, config);
+        return { ...wellKnown, endpoint };
+      }
+    } catch (cause) {
+      // Fall through to .well-known below — SRV is a hint, not the source of truth.
+      void cause;
+    }
+  }
+
+  // .well-known fallback
+  const url = `https://${deployment}/.well-known/crewhaus.json`;
+  return fetchWellKnown(url, config);
+}
+
+async function fetchWellKnown(baseOrUrl: string, config: DiscoveryConfig): Promise<PeerRecord> {
+  const fetcher = config.wellKnownFetcher ?? defaultFetcher;
+  const url = baseOrUrl.endsWith("/.well-known/crewhaus.json")
+    ? baseOrUrl
+    : `${baseOrUrl}/.well-known/crewhaus.json`;
+  const { status, body } = await fetcher(url);
+  if (status !== 200) {
+    throw new FederationDiscoveryError(`well-known fetch returned ${status} for ${url}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (cause) {
+    throw new FederationDiscoveryError(`well-known returned invalid JSON for ${url}`, cause);
+  }
+  return parsePeerRecord(parsed, url, {
+    allowInsecureLocalhost: config.allowInsecureLocalhost === true,
+  });
+}
+
+function parsePeerRecord(
+  raw: unknown,
+  source: string,
+  opts: { allowInsecureLocalhost: boolean } = { allowInsecureLocalhost: false },
+): PeerRecord {
+  if (typeof raw !== "object" || raw === null) {
+    throw new FederationDiscoveryError(`peer record at ${source} is not an object`);
+  }
+  const r = raw as Record<string, unknown>;
+  const endpoint = typeof r["endpoint"] === "string" ? r["endpoint"] : "";
+  const version = typeof r["version"] === "string" ? r["version"] : "";
+  const supportedShapesRaw = r["supportedShapes"] ?? r["supported_shapes"];
+  const supportedShapes = Array.isArray(supportedShapesRaw)
+    ? (supportedShapesRaw.filter((s) => typeof s === "string") as string[])
+    : [];
+  const publicKeyFingerprint =
+    typeof r["publicKeyFingerprint"] === "string"
+      ? r["publicKeyFingerprint"]
+      : typeof r["public_key_fingerprint"] === "string"
+        ? r["public_key_fingerprint"]
+        : "";
+  if (!endpoint || !version) {
+    throw new FederationDiscoveryError(`peer record at ${source}: endpoint+version are required`);
+  }
+  if (!/^https:\/\//.test(endpoint)) {
+    if (
+      !opts.allowInsecureLocalhost ||
+      !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/.test(endpoint)
+    ) {
+      throw new FederationDiscoveryError(
+        `peer record at ${source}: endpoint must be https:// (got ${endpoint})`,
+      );
+    }
+  }
+  if (!/^[0-9a-f]{64}$/i.test(publicKeyFingerprint)) {
+    throw new FederationDiscoveryError(
+      `peer record at ${source}: publicKeyFingerprint must be 64-char hex (got ${publicKeyFingerprint.length} chars)`,
+    );
+  }
+  return {
+    endpoint,
+    version,
+    supportedShapes,
+    publicKeyFingerprint: publicKeyFingerprint.toLowerCase(),
+  };
+}
+
+const defaultFetcher: WellKnownFetcher = async (url) => {
+  const res = await fetch(url, { method: "GET", headers: { Accept: "application/json" } });
+  return { status: res.status, body: await res.text() };
+};
+
+/**
+ * `crewhaus federation discover <deployment>` CLI helper. Returns the
+ * resolved record as JSON for ops piping/jq.
+ */
+export async function discoverDeployment(
+  deployment: string,
+  config: DiscoveryConfig = {},
+): Promise<PeerRecord> {
+  const d = createDiscovery(config);
+  return d.discover(deployment);
+}