@openparachute/hub 0.5.2 → 0.5.7

package/src/oauth-ui.ts

@@ -97,6 +97,33 @@ export interface ErrorViewProps {
   status: number;
 }
 
+/**
+ * Props for the "App not yet approved" view rendered when an unapproved
+ * client lands on `/oauth/authorize`. When `session` is true the operator is
+ * authenticated to this hub from the browser making the request, so we render
+ * an inline approve form (closes #208). When false we fall back to the
+ * pre-#208 CLI-only message.
+ */
+export interface ApprovePendingViewProps {
+  /** Display name to show — falls back to client_id when no name was supplied at DCR. */
+  clientName: string;
+  clientId: string;
+  redirectUris: string[];
+  /** Scopes parsed from the original `/oauth/authorize?scope=` query param. */
+  requestedScopes: string[];
+  /**
+   * When set, render the inline approve form. The form posts to
+   * `/oauth/authorize/approve` with the CSRF token + a `return_to` URL the
+   * server will redirect to after the approve commits — the original
+   * `/oauth/authorize?...` URL so the OAuth flow re-enters with the now-
+   * approved client and lands on the consent screen.
+   */
+  approveForm?: {
+    csrfToken: string;
+    returnTo: string;
+  };
+}
+
 export function renderLogin(props: LoginViewProps): string {
   const { params, errorMessage, csrfToken } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
@@ -204,6 +231,79 @@ function renderVaultPicker(picker: VaultPicker): string {
         </section>`;
 }
 
+/**
+ * "App not yet approved" page (#74). When the request carries a valid
+ * operator session (#208), render the inline approve form so one click lands
+ * the client as `approved` and re-enters the OAuth flow at consent. Without
+ * a session, fall back to the original CLI-only message — anyone hitting
+ * /oauth/authorize unauthenticated to the hub itself can't be trusted to
+ * approve a DCR client from the browser, so they need to drop to a terminal
+ * and run `parachute auth approve-client <id>`.
+ *
+ * The CLI fallback hint is shown in BOTH branches: a button-equipped operator
+ * may still want the CLI invocation handy (different machine, scriptable
+ * context). The button is the easy path; the CLI is always-available.
+ */
+export function renderApprovePending(props: ApprovePendingViewProps): string {
+  const { clientName, clientId, redirectUris, requestedScopes, approveForm } = props;
+  const redirectList = redirectUris.map((u) => `<li><code>${escapeHtml(u)}</code></li>`).join("");
+  const scopeRows =
+    requestedScopes.length === 0
+      ? `<li class="scope scope-empty">No scopes requested — the app gets a session token only.</li>`
+      : requestedScopes.map(renderScopeRow).join("\n");
+  const formSection = approveForm
+    ? `
+      <form method="POST" action="/oauth/authorize/approve" class="auth-form approve-form">
+        ${renderCsrfHiddenInput(approveForm.csrfToken)}
+        <input type="hidden" name="client_id" value="${escapeHtml(clientId)}" />
+        <input type="hidden" name="return_to" value="${escapeHtml(approveForm.returnTo)}" />
+        <button type="submit" class="btn btn-primary">Approve and continue</button>
+      </form>
+      <p class="approve-cli-hint">
+        Or run <code>parachute auth approve-client ${escapeHtml(clientId)}</code> from a terminal.
+      </p>`
+    : `
+      <p class="approve-cli-hint">
+        Ask the operator to run <code>parachute auth approve-client ${escapeHtml(clientId)}</code>
+        from a terminal, then try again.
+      </p>`;
+  const body = `
+    <div class="card">
+      <div class="card-header">
+        <div class="brand">
+          <span class="brand-mark">⌬</span>
+          <span class="brand-name">Parachute</span>
+        </div>
+        <h1>App not yet approved</h1>
+        <p class="subtitle">
+          ${escapeHtml(clientName)} is registered with this hub but hasn't been approved yet.
+          Review the details below before approving.
+        </p>
+      </div>
+      <section class="approve-meta">
+        <h2 class="scopes-title">Application</h2>
+        <p class="approve-meta-row">
+          <span class="approve-meta-label">name</span>
+          <code class="approve-meta-value">${escapeHtml(clientName)}</code>
+        </p>
+        <p class="approve-meta-row">
+          <span class="approve-meta-label">client_id</span>
+          <code class="approve-meta-value">${escapeHtml(clientId)}</code>
+        </p>
+        <div class="approve-meta-row approve-meta-row-block">
+          <span class="approve-meta-label">redirect_uris</span>
+          <ul class="approve-redirect-list">${redirectList}</ul>
+        </div>
+      </section>
+      <section class="scopes">
+        <h2 class="scopes-title">Permissions requested</h2>
+        <ul class="scope-list">${scopeRows}</ul>
+      </section>
+      ${formSection}
+    </div>`;
+  return baseDocument("App not yet approved", body);
+}
+
 export function renderError(props: ErrorViewProps): string {
   const body = `
     <div class="card">
@@ -542,6 +642,73 @@ const STYLES = `
   .vault-picker-empty .picker-help { color: ${PALETTE.danger}; }
   .vault-picker-empty .picker-help code { color: ${PALETTE.fg}; }
 
+  .approve-meta {
+    margin: 0 0 1.25rem;
+    padding: 0.75rem 0.85rem;
+    border: 1px solid ${PALETTE.borderLight};
+    border-radius: 6px;
+    background: ${PALETTE.bgSoft};
+  }
+  .approve-meta .scopes-title { margin-bottom: 0.5rem; }
+  .approve-meta-row {
+    margin: 0 0 0.4rem;
+    display: flex;
+    gap: 0.5rem;
+    align-items: baseline;
+    flex-wrap: wrap;
+  }
+  .approve-meta-row:last-child { margin-bottom: 0; }
+  .approve-meta-row-block { flex-direction: column; gap: 0.25rem; }
+  .approve-meta-label {
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    font-size: 0.7rem;
+    color: ${PALETTE.fgDim};
+  }
+  .approve-meta-value {
+    font-family: ${FONT_MONO};
+    font-size: 0.82rem;
+    background: ${PALETTE.cardBg};
+    padding: 0.1rem 0.4rem;
+    border-radius: 4px;
+    color: ${PALETTE.fg};
+    word-break: break-all;
+  }
+  .approve-redirect-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+  }
+  .approve-redirect-list li code {
+    font-family: ${FONT_MONO};
+    font-size: 0.82rem;
+    background: ${PALETTE.cardBg};
+    padding: 0.1rem 0.4rem;
+    border-radius: 4px;
+    color: ${PALETTE.fg};
+    word-break: break-all;
+  }
+  .approve-form { gap: 0; }
+  .approve-cli-hint {
+    margin-top: 1rem;
+    padding-top: 0.85rem;
+    border-top: 1px solid ${PALETTE.borderLight};
+    color: ${PALETTE.fgMuted};
+    font-size: 0.85rem;
+  }
+  .approve-cli-hint code {
+    font-family: ${FONT_MONO};
+    font-size: 0.8rem;
+    background: ${PALETTE.bgSoft};
+    padding: 0.1rem 0.4rem;
+    border-radius: 4px;
+    color: ${PALETTE.fg};
+    word-break: break-all;
+  }
+
   .badge {
     display: inline-block;
     font-size: 0.7rem;

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
@@ -384,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,
@@ -409,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

@@ -134,6 +134,57 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   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`);
@@ -142,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 {
@@ -222,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;
+}