@openparachute/hub 0.5.1 → 0.5.7

package/src/__tests__/port-assign.test.ts

@@ -74,103 +74,92 @@ describe("assignPort (pure)", () => {
   });
 });
 
-describe("assignServicePort (.env round-trip)", () => {
-  test("preserves an existing PORT in .env (idempotent re-install)", () => {
+describe("assignServicePort (hub#206 — services.json is authoritative)", () => {
+  // Post-hub#206 assignServicePort is a thin wrapper over assignPort: the
+  // install path no longer touches the service's .env, since services.json
+  // is the single source of truth and the duplicate state caused drift on
+  // re-install. These tests pin the new contract:
+  //   1. The function returns the assigned port + source/warning.
+  //   2. It does not write to .env. Pre-existing .env files are untouched
+  //      (no PORT line added, no PORT line removed, no other lines mutated).
+  //   3. There's no "preserved" source — a stale .env PORT does NOT survive
+  //      a re-install (operators edit services.json now).
+
+  test("returns canonical when free, does not touch .env", () => {
     const { dir, cleanup } = makeTempDir();
     try {
-      const envPath = join(dir, ".env");
-      writeFileSync(envPath, "PORT=1944\nOTHER=keepme\n");
+      const envPath = join(dir, "subdir", ".env");
       const result = assignServicePort({
-        envPath,
         canonical: 1940,
-        // Even though canonical is free, the existing .env wins.
         occupied: [],
       });
-      expect(result.port).toBe(1944);
-      expect(result.source).toBe("preserved");
-      expect(result.written).toBe(false);
-      // File untouched — no rewrite means OTHER stays as-is.
-      const text = readFileSync(envPath, "utf8");
-      expect(text).toContain("PORT=1944");
-      expect(text).toContain("OTHER=keepme");
+      expect(result.port).toBe(1940);
+      expect(result.source).toBe("canonical");
+      expect(result.warning).toBeUndefined();
+      // No .env file gets created — subdir doesn't even exist.
+      expect(existsSync(envPath)).toBe(false);
     } finally {
       cleanup();
     }
   });
 
-  test("writes PORT into a fresh .env when canonical is free", () => {
+  test("does NOT preserve a pre-existing PORT in .env (services.json is authoritative)", () => {
+    // Pre-hub#206 a stale `.env` PORT survived a re-install — operators
+    // editing services.json would get re-stamped by the .env. Post-#206
+    // services.json wins; the .env PORT is ignored at install time and
+    // also at boot (per the 4-tier ladder in scribe/agent).
     const { dir, cleanup } = makeTempDir();
     try {
-      const envPath = join(dir, "subdir", ".env");
+      const envPath = join(dir, ".env");
+      const before = "PORT=1944\nOTHER=keepme\n";
+      writeFileSync(envPath, before);
       const result = assignServicePort({
-        envPath,
         canonical: 1940,
         occupied: [],
       });
+      // We assigned the canonical port, NOT the stale 1944 from .env.
       expect(result.port).toBe(1940);
       expect(result.source).toBe("canonical");
-      expect(result.written).toBe(true);
-      expect(result.warning).toBeUndefined();
-      expect(existsSync(envPath)).toBe(true);
-      expect(readFileSync(envPath, "utf8")).toContain("PORT=1940");
+      // The .env file is bit-for-bit untouched — PORT line and other lines
+      // both stay. (No new PORT line written, no existing PORT rewritten.)
+      const after = readFileSync(envPath, "utf8");
+      expect(after).toBe(before);
     } finally {
       cleanup();
     }
   });
 
-  test("writes a fallback PORT and surfaces the warning when canonical is occupied", () => {
+  test("returns fallback port and warning when canonical is occupied; .env untouched", () => {
     const { dir, cleanup } = makeTempDir();
     try {
       const envPath = join(dir, ".env");
+      // Pre-existing .env with non-PORT content.
+      const before = "FOO=bar\n";
+      writeFileSync(envPath, before);
       const result = assignServicePort({
-        envPath,
         canonical: 1940,
         occupied: [1940],
       });
       expect(result.port).toBe(1944);
       expect(result.source).toBe("fallback-in-range");
-      expect(result.written).toBe(true);
       expect(result.warning).toMatch(/canonical port 1940 is in use/);
-      expect(readFileSync(envPath, "utf8")).toContain("PORT=1944");
-    } finally {
-      cleanup();
-    }
-  });
-
-  test("ignores a non-numeric PORT and assigns a fresh one", () => {
-    const { dir, cleanup } = makeTempDir();
-    try {
-      const envPath = join(dir, ".env");
-      writeFileSync(envPath, "PORT=garbage\n");
-      const result = assignServicePort({
-        envPath,
-        canonical: 1940,
-        occupied: [],
-      });
-      expect(result.port).toBe(1940);
-      expect(result.written).toBe(true);
-      // The garbage value got upserted to a real number.
-      expect(readFileSync(envPath, "utf8")).toContain("PORT=1940");
+      // .env stays bit-for-bit identical.
+      expect(readFileSync(envPath, "utf8")).toBe(before);
     } finally {
       cleanup();
     }
   });
 
-  test("preserves surrounding lines on rewrite", () => {
+  test("third-party (no canonical) gets first reservation slot; no .env created", () => {
     const { dir, cleanup } = makeTempDir();
     try {
       const envPath = join(dir, ".env");
-      writeFileSync(envPath, "FOO=bar\nBAZ=qux\n");
       const result = assignServicePort({
-        envPath,
-        canonical: 1940,
         occupied: [],
       });
-      expect(result.written).toBe(true);
-      const text = readFileSync(envPath, "utf8");
-      expect(text).toContain("FOO=bar");
-      expect(text).toContain("BAZ=qux");
-      expect(text).toContain("PORT=1940");
+      expect(result.port).toBe(1944);
+      expect(result.source).toBe("fallback-in-range");
+      expect(existsSync(envPath)).toBe(false);
     } finally {
       cleanup();
     }

package/src/__tests__/rate-limit.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  MAX_ATTEMPTS,
+  UNKNOWN_IP_SENTINEL,
+  WINDOW_MS,
+  __resetForTests,
+  checkAndRecord,
+  clientIpFromRequest,
+} from "../rate-limit.ts";
+
+afterEach(() => {
+  __resetForTests();
+});
+
+describe("checkAndRecord — bucket fill / drain", () => {
+  test("admits the first MAX_ATTEMPTS attempts; denies the next one with Retry-After", () => {
+    const now = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      const r = checkAndRecord("ip-a", now);
+      expect(r.allowed).toBe(true);
+      expect(r.retryAfterSeconds).toBeUndefined();
+    }
+    const denied = checkAndRecord("ip-a", now);
+    expect(denied.allowed).toBe(false);
+    expect(denied.retryAfterSeconds).toBeDefined();
+    // 5 attempts at the same instant; window length 15 min = 900s. Reset is
+    // exactly WINDOW_MS later, so retry-after === WINDOW_MS / 1000.
+    expect(denied.retryAfterSeconds).toBe(WINDOW_MS / 1000);
+  });
+
+  test("bucket drains: attempt is admitted again once the window passes", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    const stillDenied = checkAndRecord("ip-a", new Date(t0.getTime() + WINDOW_MS - 1000));
+    expect(stillDenied.allowed).toBe(false);
+
+    // Advance past the window — all five timestamps fall off, slot opens.
+    const past = new Date(t0.getTime() + WINDOW_MS + 1000);
+    const allowed = checkAndRecord("ip-a", past);
+    expect(allowed.allowed).toBe(true);
+  });
+
+  test("partial drain: oldest entry falling off opens exactly one slot", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    // Spread 5 attempts 1 minute apart so they fall off the window
+    // individually rather than as a cohort.
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", new Date(t0.getTime() + i * 60_000));
+    }
+    // Right at the 5th-minute mark, all 5 are in window → denied.
+    const denied = checkAndRecord("ip-a", new Date(t0.getTime() + 5 * 60_000));
+    expect(denied.allowed).toBe(false);
+
+    // Step past WINDOW_MS from the *first* attempt (t0) → that one falls
+    // off, so we should be admitted.
+    const partial = new Date(t0.getTime() + WINDOW_MS + 1000);
+    const r = checkAndRecord("ip-a", partial);
+    expect(r.allowed).toBe(true);
+  });
+
+  test("denied attempts do not push the reset further into the future", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    // Five denials over 30 seconds. The reset moment must be anchored to the
+    // 5 admitted attempts at t0, NOT to the latest denial.
+    for (let i = 1; i <= 5; i++) {
+      checkAndRecord("ip-a", new Date(t0.getTime() + i * 6000));
+    }
+    const finalCheck = checkAndRecord("ip-a", new Date(t0.getTime() + 30_000));
+    expect(finalCheck.allowed).toBe(false);
+    // 30 seconds elapsed; expected ~870s remaining. Tolerance ±2s for
+    // ceil-rounding edge.
+    const expected = Math.ceil((WINDOW_MS - 30_000) / 1000);
+    expect(finalCheck.retryAfterSeconds).toBe(expected);
+  });
+
+  test("Retry-After is always at least 1 second at the boundary", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    // Exactly at the moment the oldest attempt would fall off — clamp to 1.
+    const r = checkAndRecord("ip-a", new Date(t0.getTime() + WINDOW_MS));
+    // At exactly WINDOW_MS, the oldest is gone → admitted, not denied.
+    expect(r.allowed).toBe(true);
+  });
+
+  test("Retry-After natural value is always >= 1 in the deny branch (1ms-remaining case)", () => {
+    // The `Math.max(1, ...)` clamp at rate-limit.ts:90 is defense-in-depth:
+    // the deny branch requires `pruned.length >= MAX_ATTEMPTS`, which means
+    // every retained timestamp is strictly inside the window, so
+    // `resetAtMs - now > 0` strictly, so `Math.ceil(positive / 1000) >= 1`.
+    // This test pins that invariant: at `WINDOW_MS - 1ms` after the cohort,
+    // 1ms remains until the oldest falls off → unclamped value is
+    // `Math.ceil(1 / 1000) = 1`, the minimum natural value.
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    const denied = checkAndRecord("ip-a", new Date(t0.getTime() + WINDOW_MS - 1));
+    expect(denied.allowed).toBe(false);
+    expect(denied.retryAfterSeconds).toBe(1);
+  });
+
+  test("Retry-After is >= 1 across every denied step from t0 to the boundary", () => {
+    // Belt-and-suspenders sweep: walk `now` from t0 up to (but not including)
+    // the boundary in 100ms steps and assert every denied response has
+    // `retryAfterSeconds >= 1`. Locks in the "natural value never drops to
+    // zero in the deny branch" invariant the clamp guards.
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    for (let dt = 0; dt < WINDOW_MS; dt += 100) {
+      const r = checkAndRecord("ip-a", new Date(t0.getTime() + dt));
+      expect(r.allowed).toBe(false);
+      expect(r.retryAfterSeconds).toBeDefined();
+      expect(r.retryAfterSeconds as number).toBeGreaterThanOrEqual(1);
+    }
+  });
+});
+
+describe("checkAndRecord — multi-IP independence", () => {
+  test("exhausting one IP's bucket does not affect another IP", () => {
+    const now = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) checkAndRecord("ip-a", now);
+    expect(checkAndRecord("ip-a", now).allowed).toBe(false);
+
+    // Different IP — fresh bucket.
+    expect(checkAndRecord("ip-b", now).allowed).toBe(true);
+    expect(checkAndRecord("ip-c", now).allowed).toBe(true);
+  });
+
+  test("IPv4 / IPv6 / sentinel are all distinct keys", () => {
+    const now = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) checkAndRecord("203.0.113.7", now);
+    expect(checkAndRecord("203.0.113.7", now).allowed).toBe(false);
+    expect(checkAndRecord("2001:db8::42", now).allowed).toBe(true);
+    expect(checkAndRecord(UNKNOWN_IP_SENTINEL, now).allowed).toBe(true);
+  });
+});
+
+describe("clientIpFromRequest — header priority", () => {
+  test("CF-Connecting-IP wins over X-Forwarded-For", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: {
+        "cf-connecting-ip": "203.0.113.7",
+        "x-forwarded-for": "198.51.100.99, 10.0.0.1",
+      },
+    });
+    expect(clientIpFromRequest(req)).toBe("203.0.113.7");
+  });
+
+  test("X-Forwarded-For first hop is used when CF-Connecting-IP is absent", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "x-forwarded-for": "198.51.100.99, 10.0.0.1, 10.0.0.2" },
+    });
+    expect(clientIpFromRequest(req)).toBe("198.51.100.99");
+  });
+
+  test("X-Forwarded-For with whitespace is trimmed", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "x-forwarded-for": "  198.51.100.99  , 10.0.0.1" },
+    });
+    expect(clientIpFromRequest(req)).toBe("198.51.100.99");
+  });
+
+  test("falls through to UNKNOWN_IP_SENTINEL when no headers are set", () => {
+    const req = new Request("http://hub.test/admin/login");
+    expect(clientIpFromRequest(req)).toBe(UNKNOWN_IP_SENTINEL);
+  });
+
+  test("empty / whitespace-only header values are treated as absent", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "cf-connecting-ip": "   ", "x-forwarded-for": "" },
+    });
+    expect(clientIpFromRequest(req)).toBe(UNKNOWN_IP_SENTINEL);
+  });
+
+  test("empty CF-Connecting-IP falls through to X-Forwarded-For first hop", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "cf-connecting-ip": "", "x-forwarded-for": "198.51.100.99" },
+    });
+    expect(clientIpFromRequest(req)).toBe("198.51.100.99");
+  });
+});