@openparachute/hub 0.5.7 → 0.5.10-rc.2

package/src/operator-token.ts

@@ -12,30 +12,116 @@
  * Browser apps follow the OAuth flow and never touch this file. Service
  * accounts (cron jobs, oncall scripts) read it; that's the whole point.
  *
- * Rotation: cheap. `parachute auth rotate-operator` mints a fresh token
- * and overwrites the file. The previous token is *not* revoked at the
- * issuer — the hub doesn't track operator-token jtis — so a leaked file
- * stays valid until its 1-year TTL elapses. Treat operator.token like an
- * SSH private key.
+ * Lifetime: 90 days by default (was 365d through 0.5.7). The opportunistic
+ * auto-rotation helper `useOperatorTokenWithAutoRotate` re-mints any
+ * within-7d-of-expiry token in-place, so an operator who runs the CLI at
+ * least weekly never sees an expiry surprise. Fully expired tokens fail
+ * with an explicit re-auth message — auto-rotating from a dead token would
+ * defeat the lifetime cap (security: forces a manual re-auth touch).
+ *
+ * Operator-token jtis are tracked in the hub `tokens` registry as of
+ * hub#212 Phase 1 (created_via='operator_mint'); per-jti revocation is
+ * enforced via validateAccessToken's row.revokedAt check. A leaked file
+ * still stays valid until either its TTL elapses or the operator
+ * explicitly revokes the jti — treat operator.token like an SSH private
+ * key.
  */
 import type { Database } from "bun:sqlite";
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { configDir } from "./config.ts";
-import { signAccessToken } from "./jwt-sign.ts";
+import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
 
 export const OPERATOR_TOKEN_FILENAME = "operator.token";
-export const OPERATOR_TOKEN_TTL_SECONDS = 365 * 24 * 60 * 60;
+/** Default operator-token lifetime — 90 days, was 365d through 0.5.7 (#213). */
+export const OPERATOR_TOKEN_TTL_SECONDS = 90 * 24 * 60 * 60;
+/**
+ * Auto-rotation threshold. When a CLI flow validates an operator token whose
+ * remaining lifetime is less than this, it silently re-mints with the same
+ * scope-set + a fresh full TTL. 7 days picked so a once-a-week operator
+ * never sees expiry; longer would let stale tokens accumulate, shorter
+ * would re-mint too often.
+ */
+export const OPERATOR_TOKEN_AUTO_ROTATE_THRESHOLD_SECONDS = 7 * 24 * 60 * 60;
 export const OPERATOR_TOKEN_AUDIENCE = "operator";
 export const OPERATOR_TOKEN_CLIENT_ID = "parachute-hub";
-export const OPERATOR_TOKEN_SCOPES = [
-  "hub:admin",
-  "parachute:host:admin",
-  "vault:admin",
-  "scribe:admin",
-  "channel:send",
+
+/**
+ * Named scope-sets a `parachute auth rotate-operator` invocation can choose
+ * via `--scope-set`. Each set encodes the minimum scopes required for that
+ * operator-flow's API surface; `admin` is the back-compat superset and
+ * stays the default.
+ *
+ * Per-command gating rolls out incrementally:
+ *   - Auth surfaces (hub#221 `revoke-token`, hub#222 `mint-token`) gate on
+ *     `parachute:host:auth` — both `admin` and `auth` scope-sets carry it.
+ *   - Other CLI commands (`install`, `start`, `expose`, etc.) still accept
+ *     any token with `hub:admin` and don't yet check the narrower scopes;
+ *     a future follow-up wires per-command enforcement so a `start`-set
+ *     token can only lifecycle-manage, not install. Until then,
+ *     `--scope-set` is a tool the cautious operator can opt into without
+ *     breaking anyone.
+ *
+ * The fine-grained `parachute:host:install/start/expose/auth/vault` scopes
+ * are operator-only (non-requestable via public OAuth), like
+ * `parachute:host:admin` — registered in `scope-explanations.ts`.
+ */
+export type OperatorScopeSet = "install" | "start" | "expose" | "auth" | "vault" | "admin";
+
+export const OPERATOR_TOKEN_SCOPE_SET_NAMES: readonly OperatorScopeSet[] = [
+  "install",
+  "start",
+  "expose",
+  "auth",
+  "vault",
+  "admin",
 ];
 
+/**
+ * Scopes embedded for each named set. `admin` preserves the pre-#213
+ * `OPERATOR_TOKEN_SCOPES` set verbatim plus the new fine-grained host
+ * scopes (which `admin` is a superset of by definition).
+ */
+export const OPERATOR_TOKEN_SCOPE_SETS: Readonly<Record<OperatorScopeSet, readonly string[]>> = {
+  install: ["parachute:host:install", "vault:read"],
+  start: ["parachute:host:start"],
+  expose: ["parachute:host:expose"],
+  auth: ["parachute:host:auth"],
+  vault: ["parachute:host:vault"],
+  admin: [
+    "hub:admin",
+    "parachute:host:admin",
+    "parachute:host:install",
+    "parachute:host:start",
+    "parachute:host:expose",
+    "parachute:host:auth",
+    "parachute:host:vault",
+    "vault:admin",
+    "scribe:admin",
+    "channel:send",
+  ],
+};
+
+/**
+ * Pre-#213 export: the broad "admin" scope-set as a flat array. Kept for
+ * back-compat with callers (e.g. existing tests) that imported the constant
+ * directly. New callers should use `OPERATOR_TOKEN_SCOPE_SETS.admin`.
+ */
+export const OPERATOR_TOKEN_SCOPES = OPERATOR_TOKEN_SCOPE_SETS.admin;
+
+/** Custom JWT claim that records which scope-set this operator token was minted under. */
+export const OPERATOR_TOKEN_SCOPE_SET_CLAIM = "pa_scope_set";
+
+/** Default scope-set when none is specified. Preserves pre-#213 behavior. */
+export const OPERATOR_TOKEN_DEFAULT_SCOPE_SET: OperatorScopeSet = "admin";
+
+export function isOperatorScopeSet(value: unknown): value is OperatorScopeSet {
+  return (
+    typeof value === "string" &&
+    (OPERATOR_TOKEN_SCOPE_SET_NAMES as readonly string[]).includes(value)
+  );
+}
+
 export function operatorTokenPath(dir: string = configDir()): string {
   return join(dir, OPERATOR_TOKEN_FILENAME);
 }
@@ -54,23 +140,47 @@ export interface MintOperatorTokenOpts {
   jti?: string;
   /** Override the audience claim. Defaults to "operator". */
   audience?: string;
+  /** Which named scope-set to mint under. Defaults to "admin" (pre-#213 behavior). */
+  scopeSet?: OperatorScopeSet;
+  /** Override the lifetime. Tests pin this; production uses the default. */
+  ttlSeconds?: number;
 }
 
 export async function mintOperatorToken(
   db: Database,
   userId: string,
   opts: MintOperatorTokenOpts,
-): Promise<{ token: string; jti: string; expiresAt: string }> {
-  return signAccessToken(db, {
+): Promise<{ token: string; jti: string; expiresAt: string; scopeSet: OperatorScopeSet }> {
+  const scopeSet = opts.scopeSet ?? OPERATOR_TOKEN_DEFAULT_SCOPE_SET;
+  const scopes = [...OPERATOR_TOKEN_SCOPE_SETS[scopeSet]];
+  const minted = await signAccessToken(db, {
     sub: userId,
-    scopes: OPERATOR_TOKEN_SCOPES,
+    scopes,
     audience: opts.audience ?? OPERATOR_TOKEN_AUDIENCE,
     clientId: OPERATOR_TOKEN_CLIENT_ID,
     issuer: opts.issuer,
-    ttlSeconds: OPERATOR_TOKEN_TTL_SECONDS,
+    ttlSeconds: opts.ttlSeconds ?? OPERATOR_TOKEN_TTL_SECONDS,
+    extraClaims: { [OPERATOR_TOKEN_SCOPE_SET_CLAIM]: scopeSet },
     ...(opts.jti !== undefined ? { jti: opts.jti } : {}),
     ...(opts.now !== undefined ? { now: opts.now } : {}),
   });
+  // Register every operator-mint with the unified token registry (hub#212
+  // Phase 1). Per design: operator-mint rows have user_id NULL; the
+  // subject column carries the canonical "operator" identity string.
+  // (Storing user_id here would require an FK-valid users row, which the
+  // operator-mint path doesn't always have access to in test fixtures —
+  // and conceptually the operator is a role, not a hub user.) Powers the
+  // revocation list endpoint.
+  recordTokenMint(db, {
+    jti: minted.jti,
+    createdVia: "operator_mint",
+    subject: "operator",
+    clientId: OPERATOR_TOKEN_CLIENT_ID,
+    scopes,
+    expiresAt: minted.expiresAt,
+    ...(opts.now !== undefined ? { now: opts.now } : {}),
+  });
+  return { ...minted, scopeSet };
 }
 
 /**
@@ -86,6 +196,10 @@ export async function writeOperatorTokenFile(
   const path = operatorTokenPath(dir);
   const tmp = `${path}.tmp`;
   await fs.writeFile(tmp, `${token}\n`, { mode: 0o600 });
+  // Defense-in-depth: if the file already existed with looser permissions,
+  // some platforms (Linux, macOS) preserve the prior inode's mode rather
+  // than honoring the create-mode hint on rename. Force 0600 explicitly.
+  await fs.chmod(tmp, 0o600);
   await fs.rename(tmp, path);
   return path;
 }
@@ -94,11 +208,19 @@ export async function writeOperatorTokenFile(
  * Reads the operator token file, trims trailing whitespace. Returns null
  * if the file doesn't exist (caller decides whether that's an error). Any
  * other read error propagates.
+ *
+ * On read, checks file permissions. If the file is group- or world-readable
+ * (mode bits 0o077 set), logs a warning but does NOT fail the read — a
+ * read-only failure here would lock operators out of every CLI command,
+ * with no in-CLI way to recover. The warning + remediation hint
+ * (`chmod 0600 <path>`) lets the operator self-correct without losing
+ * access. New writes via `writeOperatorTokenFile` are always 0600.
  */
 export async function readOperatorTokenFile(dir: string = configDir()): Promise<string | null> {
   const path = operatorTokenPath(dir);
   try {
     const buf = await fs.readFile(path, "utf8");
+    await warnIfWorldReadable(path);
     const trimmed = buf.trim();
     return trimmed.length > 0 ? trimmed : null;
   } catch (err) {
@@ -107,16 +229,35 @@ export async function readOperatorTokenFile(dir: string = configDir()): Promise<
   }
 }
 
+async function warnIfWorldReadable(path: string): Promise<void> {
+  try {
+    const stat = await fs.stat(path);
+    const looseBits = stat.mode & 0o077;
+    if (looseBits !== 0) {
+      const mode = (stat.mode & 0o777).toString(8).padStart(4, "0");
+      console.error(
+        `parachute: operator token file at ${path} has mode ${mode} (group/other can read it). Run \`chmod 0600 ${path}\` to lock it down.`,
+      );
+    }
+  } catch {
+    // If stat fails (file vanished between read and stat, or platform
+    // doesn't expose mode bits), skip the warning — the read already
+    // succeeded, and this is defense-in-depth, not a hard gate.
+  }
+}
+
 export interface IssueOperatorTokenResult {
   token: string;
   jti: string;
   expiresAt: string;
   path: string;
+  scopeSet: OperatorScopeSet;
 }
 
 /**
  * Mint + write in one call. Used by `parachute auth set-password` (after
- * password set) and `parachute auth rotate-operator`.
+ * password set), `parachute auth rotate-operator`, and the auto-rotation
+ * path inside `useOperatorTokenWithAutoRotate`.
  */
 export async function issueOperatorToken(
   db: Database,
@@ -127,3 +268,193 @@ export async function issueOperatorToken(
   const path = await writeOperatorTokenFile(minted.token, opts.dir);
   return { ...minted, path };
 }
+
+export class OperatorTokenExpiredError extends Error {
+  override name = "OperatorTokenExpiredError";
+}
+
+export interface UseOperatorTokenOpts {
+  /** Hub origin used as `iss` validator. Required. */
+  issuer: string;
+  /** configDir override (where operator.token lives). Defaults to `configDir()`. */
+  configDir?: string;
+  /**
+   * Override the rotation clock. Tests pin this; production uses
+   * `() => new Date()`.
+   */
+  now?: () => Date;
+}
+
+/**
+ * Disambiguated outcome of `useOperatorTokenWithAutoRotate`. The prior
+ * surface (boolean `refreshed`) conflated three operationally distinct
+ * cases under a single `false` value: (a) token is fresh, no rotation
+ * needed; (b) within rotation window but rotation skipped due to
+ * privilege guard; (c) within rotation window but rotation skipped due
+ * to missing sub claim. This shape surfaces each case so future
+ * rotation telemetry / admin UI can branch on them. See hub#216 for the
+ * motivation; hub#212 Phase 2 is the natural consumer.
+ *
+ * - `fresh` — remaining lifetime above the auto-rotation threshold;
+ *   the token on disk was returned as-is. The healthy steady state.
+ * - `rotated` — rotation fired; the on-disk token was overwritten.
+ *   `rotated` companion field on `UsedOperatorToken` carries the new
+ *   path / scopeSet / expiry.
+ * - `skipped` — within rotation window, but rotation was deliberately
+ *   not performed. `reason` distinguishes:
+ *     - `aud-mismatch`: the on-disk JWT carries a non-operator audience.
+ *       This is the privilege-escalation guard (a hand-stashed scope-narrow
+ *       JWT must not be silently upgraded). See operator-token.ts line ~360.
+ *     - `no-sub`: the on-disk JWT lacks a `sub` claim, so the helper can't
+ *       safely re-mint (don't know who the token belongs to). Surfaced via
+ *       the caller's downstream invalid-token error path.
+ *     - `no-scope-set`: the on-disk JWT carries `aud: operator` but lacks
+ *       (or has an unrecognized) `pa_scope_set` claim. Refusing to rotate
+ *       here is hub#224's hardening: the prior behaviour fell back to the
+ *       default scope-set (admin) on rotation, which silently widened a
+ *       narrow-scope token of unknown provenance. Legitimately-issued
+ *       operator tokens always carry a recognized `pa_scope_set` (set by
+ *       `issueOperatorToken`); a token without it is either a hand-crafted
+ *       JWT (don't widen) or a pre-#213 legacy token (operator should
+ *       explicitly `parachute auth rotate-operator` to recover).
+ */
+export type RotationStatus =
+  | { kind: "fresh" }
+  | { kind: "rotated" }
+  | { kind: "skipped"; reason: "aud-mismatch" | "no-sub" | "no-scope-set" };
+
+export interface UsedOperatorToken {
+  /** The operator token plaintext to present as bearer. After auto-rotation, this is the freshly-minted token. */
+  token: string;
+  /** Validated payload of `token` (post-rotation if a rotation occurred). */
+  payload: Awaited<ReturnType<typeof validateAccessToken>>["payload"];
+  /** Set when this call rotated the on-disk token. The new path on disk. */
+  rotated?: { path: string; scopeSet: OperatorScopeSet; expiresAt: string };
+  /**
+   * Disambiguated rotation outcome. See {@link RotationStatus}. Callers that
+   * only need "did the token rotate?" can check `status.kind === "rotated"`
+   * or the presence of the `rotated` companion field (equivalent). Future
+   * telemetry / admin UI can branch on `skipped.reason` to surface why a
+   * rotation didn't fire.
+   */
+  status: RotationStatus;
+}
+
+/**
+ * The canonical "use the operator token in a CLI flow" helper. Reads
+ * `~/.parachute/operator.token`, validates against `db` + `issuer`, and:
+ *
+ *   - If the token has fully expired: throws `OperatorTokenExpiredError`
+ *     with an actionable message. Does NOT auto-rotate from a dead token —
+ *     auto-rotating an expired token would defeat the lifetime cap.
+ *   - If the remaining lifetime is below the auto-rotate threshold (7d):
+ *     re-mints under the same scope-set, writes back to disk, and returns
+ *     the new token. Operator never sees an expiry surprise as long as
+ *     they exercise the CLI at least weekly.
+ *   - Otherwise: returns the original token + payload.
+ *
+ * Callers receive the (possibly fresh) token to present onward. The
+ * scope-set is preserved across rotations via the `pa_scope_set` claim;
+ * tokens that lack a recognized `pa_scope_set` claim are NOT auto-rotated
+ * (hub#224 hardening — the prior fallback to the default scope-set
+ * silently widened narrow-scope tokens of unknown provenance). Operators
+ * holding a legacy token without the claim should `parachute auth
+ * rotate-operator` to recover.
+ *
+ * ## Test-author note (hub#224)
+ *
+ * Tests that stash a JWT at `~/.parachute/operator.token` to exercise
+ * downstream gate-check behaviour need to side-step auto-rotation, or
+ * the helper will silently swap the test's narrow token for a fresh
+ * admin one before the gate runs. Two safe shapes:
+ *
+ *   1. **Long TTL.** Mint with `ttlSeconds: 30 * 24 * 60 * 60` (30d) so
+ *      `remaining > OPERATOR_TOKEN_AUTO_ROTATE_THRESHOLD_SECONDS` and the
+ *      helper returns the token as-is (`status.kind === "fresh"`). This
+ *      is the pattern in `bootstrapWithOperatorScopes` (hub#222 tests).
+ *   2. **Non-operator audience.** Sign with `audience: "scribe"` (or any
+ *      non-`"operator"` value) so the line ~398 guard fires
+ *      (`status.kind === "skipped"`, `reason: "aud-mismatch"`). This is
+ *      the pattern in the pre-#222 narrow-rejection test.
+ *
+ * `aud: "operator"` + short TTL + recognized `pa_scope_set` is the
+ * auto-rotation path. `aud: "operator"` + short TTL + missing/invalid
+ * `pa_scope_set` lands on the no-scope-set skip (hub#224). Either way,
+ * if you're seeing a "narrow token magically became admin," check
+ * the test's `audience` + TTL first.
+ */
+export async function useOperatorTokenWithAutoRotate(
+  db: Database,
+  opts: UseOperatorTokenOpts,
+): Promise<UsedOperatorToken | null> {
+  const dir = opts.configDir ?? configDir();
+  const token = await readOperatorTokenFile(dir);
+  if (!token) return null;
+  const now = opts.now ?? (() => new Date());
+
+  // Validation failures (signature mismatch, wrong issuer, missing kid,
+  // expired-by-jose) bubble out for the caller to render the right message.
+  const validated = await validateAccessToken(db, token, opts.issuer);
+  const { payload } = validated;
+
+  const exp = typeof payload.exp === "number" ? payload.exp : 0;
+  const nowSec = Math.floor(now().getTime() / 1000);
+  const remaining = exp - nowSec;
+
+  // jose's verify will reject expired tokens before we get here, so this
+  // branch is defensive; callers that catch validateAccessToken errors and
+  // re-call this with a hand-rolled payload would land here.
+  if (remaining <= 0) {
+    throw new OperatorTokenExpiredError(
+      "your operator token has expired; run `parachute auth rotate-operator` to re-mint",
+    );
+  }
+
+  if (remaining > OPERATOR_TOKEN_AUTO_ROTATE_THRESHOLD_SECONDS) {
+    return { token, payload, status: { kind: "fresh" } };
+  }
+
+  // Within rotation window — but only auto-rotate if this is genuinely an
+  // operator token. The audience check is the privilege-escalation guard:
+  // an arbitrary scope-narrow JWT (aud: "scribe", "vault", …) hand-stashed
+  // at ~/.parachute/operator.token must NOT be silently upgraded to a full
+  // operator token by the hub. Legitimate operator-tokens minted via
+  // `set-password` / `rotate-operator` carry `aud: "operator"`.
+  if (payload.aud !== OPERATOR_TOKEN_AUDIENCE) {
+    return { token, payload, status: { kind: "skipped", reason: "aud-mismatch" } };
+  }
+
+  // Re-mint preserving scope-set.
+  const sub = typeof payload.sub === "string" ? payload.sub : null;
+  if (!sub) {
+    // No sub claim — can't safely auto-rotate (don't know who the token
+    // belongs to). Return as-is; the caller will likely surface this as an
+    // invalid-token error downstream.
+    return { token, payload, status: { kind: "skipped", reason: "no-sub" } };
+  }
+  // Refuse to auto-rotate without a recognized scope-set claim. The prior
+  // behaviour fell back to OPERATOR_TOKEN_DEFAULT_SCOPE_SET (admin), which
+  // silently widened a narrow `aud: "operator"` token of unknown provenance
+  // — hand-crafted or pre-#213 legacy. hub#224's hardening: a missing or
+  // invalid `pa_scope_set` means "I don't know what scope to re-mint under,"
+  // so don't re-mint at all. The operator can recover via an explicit
+  // `parachute auth rotate-operator` (which always sets the claim).
+  const claimedSet = payload[OPERATOR_TOKEN_SCOPE_SET_CLAIM];
+  if (!isOperatorScopeSet(claimedSet)) {
+    return { token, payload, status: { kind: "skipped", reason: "no-scope-set" } };
+  }
+  const scopeSet: OperatorScopeSet = claimedSet;
+  const issued = await issueOperatorToken(db, sub, {
+    dir,
+    issuer: opts.issuer,
+    scopeSet,
+    now: opts.now,
+  });
+  const reValidated = await validateAccessToken(db, issued.token, opts.issuer);
+  return {
+    token: issued.token,
+    payload: reValidated.payload,
+    rotated: { path: issued.path, scopeSet: issued.scopeSet, expiresAt: issued.expiresAt },
+    status: { kind: "rotated" },
+  };
+}

package/src/origin-check.ts

@@ -0,0 +1,127 @@
+/**
+ * Same-origin defense for cookie-based POST endpoints. The function is the
+ * server-side belt for `SameSite=Lax` cookies: a cookie-bearing POST coming
+ * from anywhere other than the hub's own origin gets rejected here so a
+ * stolen-cookie + forged-form attack can't ride the session.
+ *
+ * The check used to compare strictly against `deps.issuer` (the configured
+ * OAuth issuer URL). That's correct only on a single-origin hub. Real
+ * self-hosted setups have multiple legitimate origins:
+ *
+ *   - Loopback (`http://localhost:1939`, `http://127.0.0.1:1939`) — what
+ *     the operator hits when running everything on their box.
+ *   - Tailnet hostname (e.g. `https://parachute.taildf9ce2.ts.net`) — what
+ *     they hit from a remote device on the tailnet.
+ *   - Funnel hostname (when public-funnel is up).
+ *   - Custom domain (when an operator wires a cname).
+ *
+ * The strict `issuer === origin` check rejected legitimate operator paths
+ * from any of the non-issuer origins (closes #245). We now match against
+ * the SET of origins hub is bound to. Real third-party origins still get
+ * rejected; legitimate operator paths from any bound origin work.
+ *
+ * Header-stripped fallback (also closes #245): Tailscale Serve and some
+ * reverse proxies don't always forward Origin/Referer on POSTs. When both
+ * are absent, we fall back to the Host header. Host is browser-controlled
+ * but reflects "what the operator's browser thought it was talking to";
+ * matching it against a bound origin is weaker than Origin/Referer but
+ * preserves the same-origin signal in the proxy-stripped legitimate-flow
+ * case. CSRF + session gates upstream are the real auth defense — this is
+ * a belt for browser flows where the legitimate Origin/Referer got dropped.
+ */
+
+/**
+ * Build the bound-origin set from the hub's configuration. Returns
+ * canonical "scheme://host:port" strings (no trailing slash). The set is
+ * order-independent; consumers compare exact-equal against parsed Origin
+ * URLs.
+ *
+ *   - `issuer`: the configured OAuth issuer URL, always included.
+ *   - `loopbackPort`: the hub's local listen port; both `localhost` and
+ *     `127.0.0.1` aliases are included for that port.
+ *   - `exposeHubOrigin`: the `hubOrigin` from `expose-state.json` if set;
+ *     typically equal to `issuer` post-`parachute expose`, but kept as an
+ *     independent input so a tailnet bring-up after hub start is reflected
+ *     without restart.
+ *
+ * Malformed inputs are dropped silently — the function returns whatever it
+ * could parse. Callers should always include the issuer as a baseline so
+ * an empty parse-result is never the whole story.
+ */
+export function buildHubBoundOrigins(opts: {
+  issuer: string;
+  loopbackPort?: number;
+  exposeHubOrigin?: string;
+}): readonly string[] {
+  const set = new Set<string>();
+  const add = (raw: string | undefined) => {
+    if (!raw) return;
+    try {
+      const u = new URL(raw);
+      set.add(u.origin);
+    } catch {
+      // Malformed URL — skip.
+    }
+  };
+  add(opts.issuer);
+  add(opts.exposeHubOrigin);
+  if (typeof opts.loopbackPort === "number" && Number.isInteger(opts.loopbackPort)) {
+    set.add(`http://localhost:${opts.loopbackPort}`);
+    set.add(`http://127.0.0.1:${opts.loopbackPort}`);
+  }
+  return Array.from(set);
+}
+
+/**
+ * True when the request's Origin/Referer (or Host as fallback) matches any
+ * of the hub-bound origins. The check has three tiers in priority order:
+ *
+ *   1. `Origin` header — the canonical CSRF signal per Fetch standard.
+ *   2. `Referer` header — fallback when Origin is absent (rare but spec).
+ *   3. `Host` header — last-resort match when both above are stripped
+ *      (proxy-mangling case). Compares against the host:port of each bound
+ *      origin (not the scheme), since the proxy may have terminated TLS
+ *      and the Host header reflects the operator's address bar regardless
+ *      of how the request reached us.
+ *
+ * Empty `boundOrigins` always returns false — defense fails closed when no
+ * origin info is configured.
+ */
+export function isSameOriginRequest(req: Request, boundOrigins: readonly string[]): boolean {
+  if (boundOrigins.length === 0) return false;
+  const boundOriginSet = new Set(boundOrigins);
+
+  const origin = req.headers.get("origin");
+  if (origin) {
+    try {
+      return boundOriginSet.has(new URL(origin).origin);
+    } catch {
+      return false;
+    }
+  }
+  const referer = req.headers.get("referer");
+  if (referer) {
+    try {
+      return boundOriginSet.has(new URL(referer).origin);
+    } catch {
+      return false;
+    }
+  }
+  const host = req.headers.get("host");
+  if (host) {
+    // Build the set of acceptable host:port strings from the bound origins.
+    // Match on `host:port` only, scheme-agnostic — the Host header doesn't
+    // carry scheme, and a proxy may have terminated TLS upstream.
+    const boundHosts = new Set<string>();
+    for (const origin of boundOrigins) {
+      try {
+        const u = new URL(origin);
+        boundHosts.add(u.host); // includes port if non-default
+      } catch {
+        // Skip malformed.
+      }
+    }
+    return boundHosts.has(host);
+  }
+  return false;
+}

package/src/rate-limit.ts

@@ -1,11 +1,14 @@
 /**
- * Per-IP rate-limit on `POST /admin/login`. Lands as a floor under brute-force
+ * Per-IP rate-limit on `POST /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)
+ * up, `/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".
  *
+ * (Endpoint was `/admin/login` pre-rename; bucket logic is path-agnostic so
+ * the rename was a comment-only change here.)
+ *
  * 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

package/src/scope-explanations.ts

@@ -66,6 +66,30 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
       "Provision and manage vaults across this host (create new vaults, configure cross-vault settings).",
     level: "admin",
   },
+  // Fine-grained host scopes (#213) — the `parachute auth rotate-operator
+  // --scope-set <set>` vocabulary. Each is a narrowing of `parachute:host:admin`:
+  // an operator who wants a tighter token mints with one of these and uses
+  // it in place of the broad operator.token. Operator-only (non-requestable).
+  "parachute:host:install": {
+    label: "Install or upgrade Parachute modules on this host.",
+    level: "admin",
+  },
+  "parachute:host:start": {
+    label: "Lifecycle Parachute modules on this host (start, stop, restart, status).",
+    level: "admin",
+  },
+  "parachute:host:expose": {
+    label: "Bring tailnet or public exposure layers up and down on this host.",
+    level: "admin",
+  },
+  "parachute:host:auth": {
+    label: "Mint hub-issued tokens and manage user accounts on this host.",
+    level: "admin",
+  },
+  "parachute:host:vault": {
+    label: "Administer vaults on this host (create, configure, delete).",
+    level: "admin",
+  },
 };
 
 /**
@@ -83,7 +107,7 @@ export const FIRST_PARTY_SCOPES = Object.keys(SCOPE_EXPLANATIONS).sort();
  *   - `parachute auth rotate-operator` writes the long-lived operator token
  *     (`~/.parachute/operator.token`, mode 0600) for service accounts.
  *   - `GET /admin/host-admin-token` exchanges a valid `parachute_hub_session`
- *     cookie (set by `/admin/login` after a password check) for a
+ *     cookie (set by `/login` after a password check) for a
  *     short-lived JWT consumed by the in-tree vault-management SPA.
  *
  * Both surfaces predicate on local-operator identity that the public OAuth
@@ -104,7 +128,14 @@ export const FIRST_PARTY_SCOPES = Object.keys(SCOPE_EXPLANATIONS).sort();
  * intentional: the blast radius of compromised cross-vault admin doesn't
  * justify third-party requestability.
  */
-export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set(["parachute:host:admin"]);
+export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
+  "parachute:host:admin",
+  "parachute:host:install",
+  "parachute:host:start",
+  "parachute:host:expose",
+  "parachute:host:auth",
+  "parachute:host:vault",
+]);
 
 /**
  * Per-vault `vault:<name>:admin` scopes are also non-requestable: they let

package/src/sessions.ts

@@ -121,7 +121,7 @@ export function parseSessionCookie(cookieHeader: string | null): string | null {
  * 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
+ * `/login?next=<path>`, OAuth's DCR endpoint falls through to
  * status=`pending` (closes #199).
  */
 export function findActiveSession(