@openparachute/hub 0.5.1 → 0.5.7

package/src/port-assign.ts

@@ -1,23 +1,32 @@
-import { parseEnvFile, upsertEnvLine, writeEnvFile } from "./env-file.ts";
 import { CANONICAL_PORT_MAX, CANONICAL_PORT_MIN, PORT_RESERVATIONS } from "./service-spec.ts";
 
 /**
- * The CLI is the port authority for Parachute services. At install time it
- * picks a port for each service, writes `PORT=<port>` into the service's
- * `~/.parachute/<svc>/.env`, and reflects the chosen port in services.json.
- * Services keep a compiled-in fallback (e.g. vault → 1940) so a stand-alone
- * `bun run` still works, but the CLI's PORT env var wins on installs it
- * manages.
+ * The hub is the port authority for Parachute services. At install time it
+ * picks a port for each service and reflects the chosen port in
+ * `services.json`. That manifest is the single source of truth at boot
+ * (parachute-scribe#41 / parachute-agent#146 / parachute-agent#148): each
+ * service reads `services.json` first and only falls through to lower-tier
+ * sources (its own config, the bare `PORT` env, the compiled-in canonical
+ * default) when the manifest doesn't pin a port. So writing PORT into the
+ * service's `.env` is no longer load-bearing — services.json wins.
+ *
+ * Pre-hub#206, install also wrote `PORT=<port>` into `~/.parachute/<svc>/.env`
+ * and preserved any pre-existing value across re-installs ("operator-edited
+ * port survives upgrade"). Post-#206 (option A from the design discussion):
+ * we stop writing PORT to `.env` entirely. The duplicate state was at best
+ * dead weight and at worst a source of drift — operators editing
+ * `services.json` would get re-stamped by a stale `.env` PORT on the next
+ * `parachute install`. Existing `.env` PORT lines stay where they are
+ * (harmless — service-side resolvePort reads services.json first; the bare
+ * PORT env tier is the lowest priority).
  *
  * Why up-front assignment instead of detect-on-collision-at-boot:
  *   - Two services racing to bind the same port produces an opaque "address in
- *     use" deep inside one of them. Assigning at install lets the CLI keep
+ *     use" deep inside one of them. Assigning at install lets the hub keep
  *     a single coherent picture of who owns what.
  *   - The hub's reverse-proxy targets are computed from services.json. If a
  *     service silently falls back to a different port at runtime, the hub
  *     proxies to a dead port and the user sees a 502 with no explanation.
- *   - Re-installs stay idempotent: the existing `PORT=` in .env wins, so a
- *     user who edited their port keeps it across upgrades.
  */
 
 export type AssignmentSource = "canonical" | "fallback-in-range" | "fallback-out-of-range";
@@ -72,8 +81,6 @@ export function assignPort(
 }
 
 export interface AssignServicePortOpts {
-  /** Path to the service's `.env` file. */
-  readonly envPath: string;
   /** Canonical default for this service, or undefined for third-party. */
   readonly canonical?: number;
   /** Ports we already know to be taken. */
@@ -82,41 +89,27 @@ export interface AssignServicePortOpts {
 
 export interface AssignServicePortResult {
   readonly port: number;
-  /** "preserved" when an existing PORT in .env was kept; otherwise the
-   *  source from `assignPort`. */
-  readonly source: "preserved" | AssignmentSource;
-  /** True when we wrote PORT into .env on this call. */
-  readonly written: boolean;
+  readonly source: AssignmentSource;
   /** Warning to surface to the user, if any. */
   readonly warning?: string;
 }
 
 /**
- * Reconcile a service's PORT with its `.env`. Idempotent:
- *   - If PORT is already set in .env, preserve it (`source: "preserved"`).
- *     Re-installs and user-edited ports survive across upgrades.
- *   - Otherwise call `assignPort` and write `PORT=<port>` into .env.
+ * Assign a port for a service at install time.
  *
- * Reads only the value of PORT from .env; everything else is round-tripped
- * untouched via `parseEnvFile` / `upsertEnvLine` / `writeEnvFile`.
+ * As of hub#206 this is a thin wrapper over `assignPort`: services.json is
+ * the source of truth for service ports (parachute-scribe#41 /
+ * parachute-agent#146 / parachute-agent#148 / parachute-patterns#45), so the
+ * install path no longer touches the service's `.env`. The wrapper still
+ * exists to give the install path a stable seam — `collectOccupiedPorts`
+ * feeds into the same shape regardless of how the underlying picker
+ * evolves — and to keep the warning return path centralized.
  */
 export function assignServicePort(opts: AssignServicePortOpts): AssignServicePortResult {
-  const env = parseEnvFile(opts.envPath);
-  const existing = env.values.PORT;
-  if (existing !== undefined && /^[1-9]\d{0,4}$/.test(existing)) {
-    const port = Number(existing);
-    if (port > 0 && port < 65536) {
-      return { port, source: "preserved", written: false };
-    }
-  }
-
   const assignment = assignPort(opts.canonical, opts.occupied);
-  const nextLines = upsertEnvLine(env.lines, "PORT", String(assignment.port));
-  writeEnvFile(opts.envPath, nextLines);
   const result: AssignServicePortResult = {
     port: assignment.port,
     source: assignment.source,
-    written: true,
   };
   if (assignment.warning) {
     return { ...result, warning: assignment.warning };

package/src/rate-limit.ts

@@ -0,0 +1,163 @@
+/**
+ * Per-IP rate-limit on `POST /admin/login`. Lands as a floor under brute-force
+ * after hub#187 collapsed the public-reach matrix: with a cloudflare tunnel
+ * up, `/admin/login` is now reachable from the open internet, and 2FA (#186)
+ * is the next PR rather than this one. A 5-attempts-per-15-minute bucket per
+ * IP is the standard login-form floor; it's not the primary defense, just the
+ * one that turns "infinite credential grinding" into "rotate IPs".
+ *
+ * Shape: sliding window. Each key keeps the last N attempt timestamps; on a
+ * new attempt we prune anything older than the window, count what remains,
+ * decide allow / deny, and (on allow) append the current timestamp. Sliding
+ * gives an exact `Retry-After` (seconds until the *oldest* in-window
+ * timestamp falls off) rather than the rough next-refill of a token bucket.
+ *
+ * Storage: process-local `Map`. Persistence isn't worth a SQLite write per
+ * attempt — process restart is itself a defense (the attacker loses all
+ * progress against any one bucket). Memory is bounded by an opportunistic
+ * sweep of empty buckets every time we touch the map, so an attacker
+ * cycling through IPs can't grow the map without also leaving timestamps in
+ * each.
+ *
+ * Auth-stage independence: callers MUST gate via `checkAndRecord` *before*
+ * the credential check. A 2FA (or password) failure should count toward the
+ * same bucket as a wrong password — an attacker who knows the password
+ * shouldn't get unlimited grinding against backup codes.
+ *
+ * Layer-independent: the limiter applies on every layer (loopback included).
+ * A buggy script hammering loopback gets 429'd just like a public attacker.
+ * The one wrinkle is `tailscale serve` proxying from `127.0.0.1`, so all
+ * tailnet logins share the loopback bucket — acceptable because tailnet is
+ * authed at the network layer and brute-force isn't the threat model there.
+ *
+ * Testable: inject the clock via `now` so the tests can advance time
+ * deterministically without `setTimeout`. Module-level state is exported via
+ * `__resetForTests` so the test file can reset between cases without
+ * recreating the module.
+ */
+
+/** Window length: 15 minutes. */
+export const WINDOW_MS = 15 * 60 * 1000;
+/** Attempts allowed per window. 6th attempt within the window is denied. */
+export const MAX_ATTEMPTS = 5;
+/** Sentinel for the IP-extraction priority chain when nothing parsed. */
+export const UNKNOWN_IP_SENTINEL = "unknown";
+
+export interface RateLimitResult {
+  /** True if the attempt is admitted; caller proceeds to credential check. */
+  allowed: boolean;
+  /**
+   * Seconds until the bucket reset (oldest in-window timestamp falls off).
+   * Only set when `allowed` is false. Always >= 1: the deny branch only
+   * fires when the oldest in-window timestamp is strictly inside the
+   * window, so `Math.ceil(positiveMs / 1000) >= 1` naturally. The
+   * `Math.max(1, ...)` clamp inside `checkAndRecord` is a defense-in-depth
+   * floor in case the filter logic is ever loosened.
+   */
+  retryAfterSeconds?: number;
+}
+
+/**
+ * Module-level state. `Map<key, attemptsTimestampsMs[]>`. Each array holds
+ * raw `Date.now()`-style millisecond timestamps for in-window attempts.
+ */
+const buckets: Map<string, number[]> = new Map();
+
+/**
+ * Record an attempt and return whether it's admitted. `key` is typically a
+ * client IP from `clientIpFromRequest`. `now` is injected for testability;
+ * production callers pass `new Date()`.
+ *
+ * Behavior:
+ *   - Prune timestamps older than `now - WINDOW_MS`.
+ *   - If remaining count >= MAX_ATTEMPTS, deny with `retryAfterSeconds`
+ *     pointing at the oldest in-window timestamp's age-out moment. The
+ *     denied attempt is NOT recorded — we don't want a flood of denials
+ *     pushing the reset further into the future. The window stays anchored
+ *     to the actual 5 admitted attempts.
+ *   - Otherwise admit, append the current timestamp, return allowed.
+ */
+export function checkAndRecord(key: string, now: Date): RateLimitResult {
+  const cutoff = now.getTime() - WINDOW_MS;
+  const existing = buckets.get(key) ?? [];
+  // Drop anything that fell out of the window. Mutating a copy keeps the
+  // semantics clear: `pruned` is always the in-window slice.
+  const pruned = existing.filter((t) => t > cutoff);
+
+  if (pruned.length >= MAX_ATTEMPTS) {
+    // Reset moment = oldest in-window attempt + WINDOW_MS. `pruned[0]` is
+    // the oldest because timestamps are appended in order. Subtract `now`
+    // for seconds-until-reset. The unclamped value is provably >= 1 in this
+    // branch (see below), but `Math.max(1, ...)` stays as a defense-in-depth
+    // floor so Retry-After never reads 0 if the filter logic is ever
+    // loosened. Reasoning: the deny branch requires `pruned.length >=
+    // MAX_ATTEMPTS`, which implies every entry survived the `t > cutoff`
+    // filter, i.e. `pruned[0] > now - WINDOW_MS` strictly, i.e. `resetAtMs -
+    // now > 0` strictly, i.e. `Math.ceil(positive / 1000) >= 1`.
+    const resetAtMs = (pruned[0] ?? now.getTime()) + WINDOW_MS;
+    const retryAfterSeconds = Math.max(1, Math.ceil((resetAtMs - now.getTime()) / 1000));
+    // Denied attempt: the bucket is still full (>= MAX_ATTEMPTS in-window
+    // entries), so unconditionally re-store the pruned slice. Persisting the
+    // prune keeps stale entries from leaking forward past their window. We
+    // do NOT delete here — that branch is structurally unreachable in deny
+    // because deny requires a non-empty `pruned`.
+    buckets.set(key, pruned);
+    return { allowed: false, retryAfterSeconds };
+  }
+
+  pruned.push(now.getTime());
+  buckets.set(key, pruned);
+  return { allowed: true };
+}
+
+/**
+ * Test-only escape hatch. Production code never calls this; the test file
+ * uses it between cases so module-level state doesn't leak across tests.
+ */
+export function __resetForTests(): void {
+  buckets.clear();
+}
+
+/**
+ * Extract the client IP from request headers, in priority order:
+ *   1. `CF-Connecting-IP` — cloudflared sets this on every forwarded request,
+ *      and it's the actual client IP (not the cloudflare edge). This is the
+ *      authoritative source on cloudflare-fronted hubs.
+ *   2. `X-Forwarded-For` first hop — defensive fallback for any non-cloudflare
+ *      proxy fronting hub. The first comma-separated value is the original
+ *      client; later values are intermediate proxies.
+ *   3. `Forwarded` (RFC 7239) — not parsed; covered by the comment in the
+ *      issue's IP-priority list as deferred. `X-Forwarded-For` covers the
+ *      operator-deploy reality (every common reverse proxy sets it).
+ *   4. Fall through to `UNKNOWN_IP_SENTINEL`. Hub binds `127.0.0.1`, so the
+ *      "request remote addr" case the spec mentions doesn't materialize at
+ *      this layer (Bun's `requestIP` is on `Server`, not `Request`, and
+ *      everything reaching here is either loopback or proxy-injected). The
+ *      sentinel ensures the limiter always has a key — all sentinel
+ *      requests share one bucket, which is the intended bound for
+ *      direct-loopback callers (curl from the same host).
+ *
+ * Returns a trimmed string. Empty / whitespace-only header values are
+ * treated as absent.
+ */
+export function clientIpFromRequest(req: Request): string {
+  const cfConnectingIp = trimOrNull(req.headers.get("cf-connecting-ip"));
+  if (cfConnectingIp) return cfConnectingIp;
+
+  const xff = req.headers.get("x-forwarded-for");
+  if (xff) {
+    // First hop only. RFC 7239 / X-Forwarded-For convention is
+    // `client, proxy1, proxy2`; the leftmost entry is the original client.
+    const first = xff.split(",")[0];
+    const trimmed = trimOrNull(first ?? "");
+    if (trimmed) return trimmed;
+  }
+
+  return UNKNOWN_IP_SENTINEL;
+}
+
+function trimOrNull(s: string | null | undefined): string | null {
+  if (s == null) return null;
+  const t = s.trim();
+  return t.length > 0 ? t : null;
+}

package/src/service-spec.ts

@@ -19,20 +19,29 @@ import type { ServiceEntry } from "./services-manifest.ts";
  * (see hub-control.ts) — if something else is on 1939 we fail loudly rather
  * than walking up into a service's slot.
  *
- * **CLI is the port authority.** `parachute install <svc>` picks the port at
- * install time and writes `PORT=<port>` into `~/.parachute/<svc>/.env`.
- * lifecycle.start merges that .env into the spawn env, so the next daemon
- * boot binds the port the CLI assigned. Algorithm (see port-assign.ts):
+ * **Hub is the port authority.** `parachute install <svc>` picks the port
+ * at install time and reflects it in `services.json`. Algorithm (see
+ * port-assign.ts):
  *
  *   1. Prefer the canonical slot (`spec.seedEntry().port`).
  *   2. On collision, walk the unassigned range (1944–1949 today).
  *   3. Range exhausted: assign past 1949 with a warning.
  *
- * Idempotent: an existing `PORT=` in .env wins, so re-installs and
- * operator-edited ports survive across upgrades. Services keep their
- * compiled-in fallbacks (vault → 1940 etc.) so a stand-alone `bun run`
- * still works without a CLI-managed .env, but the CLI's PORT wins on any
- * install it manages.
+ * `services.json` is the single source of truth at boot: each service
+ * follows a 4-tier resolvePort ladder (services.json → service config →
+ * bare PORT env → compiled-in canonical default), per parachute-scribe#41,
+ * parachute-agent#146, parachute-agent#148, and parachute-patterns#45.
+ * Pre-hub#206 the install path also wrote `PORT=<port>` into the service's
+ * `~/.parachute/<svc>/.env`; post-#206 it doesn't — services.json wins,
+ * the duplicate `.env` PORT was at best dead weight and at worst a source
+ * of drift on re-install (a stale `.env` PORT would re-stamp services.json
+ * even after an operator had fixed it).
+ *
+ * Operator override is now "edit services.json" (or `parachute config`
+ * once that lands), not "edit `.env`". Pre-#206 stale `.env` PORT lines on
+ * existing operator machines stay where they are — harmless, since the
+ * boot-time ladder reads services.json before falling through to the bare
+ * PORT env tier — and future installs no longer touch them.
  *
  * **No speculative reservations.** Future first-party modules claim a slot
  * the moment they ship, not before — pre-reservation for unbuilt things has
@@ -199,6 +208,7 @@ export function seedEntryFromManifest(manifest: ModuleManifest): ServiceEntry {
   };
   if (manifest.displayName !== undefined) entry.displayName = manifest.displayName;
   if (manifest.tagline !== undefined) entry.tagline = manifest.tagline;
+  if (manifest.stripPrefix !== undefined) entry.stripPrefix = manifest.stripPrefix;
   return entry;
 }
 
@@ -319,6 +329,13 @@ const SCRIBE_FALLBACK: FirstPartyFallback = {
     paths: ["/scribe"],
     health: "/scribe/health",
     startCmd: ["parachute-scribe", "serve"],
+    // Scribe's HTTP routes are bare (`/health`, `/v1/...`), unlike notes /
+    // agent which strip the mount themselves. Until scribe ships a `--mount`
+    // flag (tracked upstream in parachute-scribe), the hub strips the
+    // `/scribe` prefix before forwarding so a request to
+    // `hub:1939/scribe/v1/audio/transcriptions` reaches scribe as
+    // `/v1/audio/transcriptions`.
+    stripPrefix: true,
   },
   extras: {
     // No auth gate today. Scribe's launch PR adds optional SCRIBE_AUTH_TOKEN;
@@ -376,10 +393,20 @@ export const FIRST_PARTY_FALLBACKS: Record<string, FirstPartyFallback> = {
 /**
  * Effective publicExposure for a service, given what's on its services.json
  * entry. Explicit wins. If absent, derive from the spec: known api/tool
- * services without declared auth fall back to "auth-required" (treated as
- * loopback at launch); everything else defaults to "allowed" — so vault,
- * notes, channel and unknown third-party services continue to be exposed
- * without needing to opt in.
+ * services without declared auth fall back to "auth-required"; everything
+ * else defaults to "allowed" — so vault, notes, channel and unknown
+ * third-party services continue to be exposed without needing to opt in.
+ *
+ * Layer behavior (post-#187 layer-aware proxy):
+ *   "allowed"        — reaches all layers (loopback / tailnet / public);
+ *                      service self-gates if it has any auth.
+ *   "loopback"       — hub layer-gates; tailnet/public requests 404 at
+ *                      proxyToService / proxyToVault before reaching the
+ *                      service.
+ *   "auth-required"  — reaches all layers; service self-gates. Same gate
+ *                      behavior as "allowed" today; the field documents
+ *                      operator/UI intent ("requires auth before exposing")
+ *                      separately from the loopback hard-block.
  */
 export function effectivePublicExposure(
   entry: ServiceEntry,
@@ -401,6 +428,32 @@ export function knownServices(): string[] {
   return Object.keys(FIRST_PARTY_FALLBACKS);
 }
 
+/**
+ * Canonical port assignment for a known short name, or `undefined` for
+ * third-party services we don't have a fallback for. Drives the
+ * canonical-port drift warning in `parachute status` (hub#195) — when an
+ * entry's actual port doesn't match the canonical, we surface it without
+ * blocking. Operators may have intentionally moved a service off canonical
+ * (e.g. to dodge a third-party clash), so the drift is a warning, not an
+ * error.
+ *
+ * Known gap (intentional, tracked separately): multi-vault instance rows
+ * (`parachute-vault-default`, `parachute-vault-techne`, etc.) don't match
+ * any `manifestName` in `FIRST_PARTY_FALLBACKS` — only the canonical
+ * `parachute-vault` does — so `shortNameForManifest` returns undefined and
+ * drift warnings never fire for them. That's tolerable: multi-vault is the
+ * deliberate exception in the duplicate-port gate (one process, N mounts,
+ * one port), and no operator-actionable drift signal is well-defined when
+ * N rows share a port. Documented here so the gap doesn't read as an
+ * oversight; revisit if a clean drift shape for multi-vault emerges.
+ */
+export function canonicalPortForManifest(manifestName: string): number | undefined {
+  const short = shortNameForManifest(manifestName);
+  if (short === undefined) return undefined;
+  const fb = FIRST_PARTY_FALLBACKS[short];
+  return fb?.manifest.port;
+}
+
 /**
  * Resolve the runtime spec for a known short name. Returns undefined for
  * unknown names; third-party modules installed via `module.json` resolve

package/src/services-manifest.ts

@@ -45,6 +45,22 @@ export interface ServiceEntry {
    * can use clean relative paths in their `startCmd`.
    */
   installDir?: string;
+  /**
+   * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
+   * before forwarding so the backend sees a bare path (e.g. `/health` rather
+   * than `/scribe/health`). Default `false` keeps the prefix intact, which
+   * matches what notes / agent / vault expect today.
+   *
+   * Per-module rather than uniform because conventions differ:
+   *   - notes-serve.ts strips internally via `--mount`; expects the prefix.
+   *   - parachute-agent reads PARACHUTE_AGENT_WEB_MOUNT and strips itself.
+   *   - parachute-vault routes by `/vault/<name>/...` and expects the prefix.
+   *   - parachute-scribe serves bare paths (`/health`, `/v1/...`); the proxy
+   *     must strip. Eventually scribe should accept its own `--mount` flag
+   *     and join the always-prefixed convention; until then this opt-in
+   *     bridges the gap. Tracked in parachute-scribe (separate issue).
+   */
+  stripPrefix?: boolean;
 }
 
 export interface ServicesManifest {
@@ -105,14 +121,70 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (installDir !== undefined && (typeof installDir !== "string" || installDir.length === 0)) {
     throw new ServicesManifestError(`${where}: "installDir" must be a non-empty string if present`);
   }
+  const stripPrefix = e.stripPrefix;
+  if (stripPrefix !== undefined && typeof stripPrefix !== "boolean") {
+    throw new ServicesManifestError(`${where}: "stripPrefix" must be a boolean if present`);
+  }
   const entry: ServiceEntry = { name, port, paths: paths as string[], health, version };
   if (displayName !== undefined) entry.displayName = displayName;
   if (tagline !== undefined) entry.tagline = tagline;
   if (publicExposure !== undefined) entry.publicExposure = publicExposure as PublicExposure;
   if (installDir !== undefined) entry.installDir = installDir;
+  if (stripPrefix !== undefined) entry.stripPrefix = stripPrefix;
   return entry;
 }
 
+/**
+ * Vault is a multi-instance service: one parachute-vault process serves
+ * every vault on a single port at distinct mount paths (`/vault/default`,
+ * `/vault/techne`, …). Every multi-vault row carries a `parachute-vault*`
+ * name. Sharing a port between vault rows is intentional and not a
+ * collision; sharing a port between two non-vault services (or between a
+ * vault and a non-vault) is.
+ *
+ * Inlined rather than imported from `well-known.ts` to keep the parser
+ * self-contained — well-known.ts already imports from this file.
+ */
+function isVaultName(name: string): boolean {
+  return name === "parachute-vault" || name.startsWith("parachute-vault-");
+}
+
+/**
+ * Reject manifests where two distinct services share a port. Without this
+ * gate, both services land in services.json, the OS lets only one bind,
+ * and the hub reverse-proxy quietly routes everyone to whichever service
+ * won the race. That's exactly how parachute-hub#195 (scribe + agent both
+ * at 1944) produced a silent /agent → scribe miswire. The underlying
+ * overwrite bugs are fixed in parachute-scribe#41 + parachute-agent#146;
+ * this is the hub-side gate so the same class can't recur silently.
+ *
+ * Multi-vault is the deliberate exception: one parachute-vault process
+ * serves N vault instances on a single port at distinct mount paths, so
+ * multiple `parachute-vault*` rows sharing a port is intentional, not a
+ * collision. The check fires only when the conflicting names aren't
+ * both vault rows.
+ *
+ * Pulled out of `validateManifest` so the write side (`upsertService`) can
+ * apply the same gate after merging without re-validating every entry's
+ * shape — the merged manifest's entries are already typed `ServiceEntry`,
+ * but a duplicate-port collision is a property of the merged set, not of
+ * any individual entry. Read-side path runs this after `validateEntry`
+ * across the array; write-side path runs this on the post-merge entries.
+ * Both surface the same `ServicesManifestError` shape.
+ */
+function assertNoDuplicatePorts(entries: ServiceEntry[], where: string): void {
+  const portsSeen = new Map<number, string>();
+  for (const entry of entries) {
+    const prev = portsSeen.get(entry.port);
+    if (prev !== undefined && !(isVaultName(prev) && isVaultName(entry.name))) {
+      throw new ServicesManifestError(
+        `${where}: duplicate port ${entry.port} — claimed by both "${prev}" and "${entry.name}". Edit services.json to give each service a unique port.`,
+      );
+    }
+    if (prev === undefined) portsSeen.set(entry.port, entry.name);
+  }
+}
+
 function validateManifest(raw: unknown, where: string): ServicesManifest {
   if (!raw || typeof raw !== "object") {
     throw new ServicesManifestError(`${where}: root must be an object`);
@@ -121,9 +193,9 @@ function validateManifest(raw: unknown, where: string): ServicesManifest {
   if (!Array.isArray(services)) {
     throw new ServicesManifestError(`${where}: "services" must be an array`);
   }
-  return {
-    services: services.map((s, i) => validateEntry(s, `${where} services[${i}]`)),
-  };
+  const entries = services.map((s, i) => validateEntry(s, `${where} services[${i}]`));
+  assertNoDuplicatePorts(entries, where);
+  return { services: entries };
 }
 
 export function readManifest(path: string = SERVICES_MANIFEST_PATH): ServicesManifest {
@@ -201,6 +273,14 @@ export function upsertService(
   } else {
     current.services.push(entry);
   }
+  // Symmetric port-collision gate (closes hub#205). Read-time validation
+  // (`validateManifest` → `assertNoDuplicatePorts`) catches duplicates the
+  // next time `services.json` is read, but without this write-side check the
+  // bad state lives on disk for that window. A buggy service boot calling
+  // `upsertService({ name: "agent", port: 1944 })` while scribe is already
+  // at 1944 would otherwise succeed and corrupt the manifest. Same
+  // multi-vault carve-out as the read path.
+  assertNoDuplicatePorts(current.services, path);
   writeManifest(current, path);
   return current;
 }

package/src/sessions.ts

@@ -113,3 +113,22 @@ export function parseSessionCookie(cookieHeader: string | null): string | null {
   }
   return null;
 }
+
+/**
+ * Returns the active (un-expired) session for this request, or null. The
+ * canonical "is the operator logged in to this hub?" check — combines
+ * `parseSessionCookie` + `findSession` (which already enforces expiry) so
+ * callers don't repeat the parse+find+null-check dance.
+ *
+ * Caller decides what to do on null — admin pages redirect to
+ * `/admin/login?next=<path>`, OAuth's DCR endpoint falls through to
+ * status=`pending` (closes #199).
+ */
+export function findActiveSession(
+  db: Database,
+  req: Request,
+  now: () => Date = () => new Date(),
+): Session | null {
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  return sid ? findSession(db, sid, now) : null;
+}