@openparachute/hub 0.7.0 → 0.7.2-rc.1

package/src/api-admin-lock.ts

@@ -0,0 +1,335 @@
+/**
+ * Admin screen-lock management API (hub admin-lock feature).
+ *
+ * All endpoints are session-cookie-gated to the first admin — the same gate
+ * the admin-token mints use (`isFirstAdmin`). These manage the lock itself, so
+ * they are NOT behind the lock gate (you must be able to unlock + set the PIN
+ * even when the surface is locked).
+ *
+ *   GET  /api/admin-lock           → status { configured, locked, idle_seconds, unlock_seconds_remaining }
+ *   POST /api/admin-lock/set       → set the FIRST PIN (no PIN configured yet)
+ *   POST /api/admin-lock/change    → rotate PIN (requires current PIN or unlocked session)
+ *   POST /api/admin-lock/remove    → turn the feature OFF (requires current PIN or unlocked session)
+ *   POST /api/admin-lock/unlock    → verify PIN, open an unlock window
+ *   POST /api/admin-lock/lock      → "Lock now" — drop the session's unlock window
+ *   POST /api/admin-lock/heartbeat → slide the idle window forward on activity
+ *
+ * The chicken-and-egg: setting the FIRST PIN is an authenticated admin action
+ * (logged-in session, no PIN yet → allowed). Once a PIN exists, change/remove
+ * require proving knowledge of the current PIN OR an already-unlocked session
+ * (the operator just unlocked, so they hold the PIN — re-typing would be
+ * friction). Setting over an existing PIN is rejected (use change).
+ *
+ * State-changing POSTs additionally require a CSRF token (`__csrf`) — these
+ * are JSON endpoints on the same origin as the cookie, and SameSite=Lax alone
+ * doesn't stop same-site CSRF (see src/csrf.ts). The SPA sources the token
+ * from `/api/me`.
+ */
+import type { Database } from "bun:sqlite";
+import {
+  clampIdleSeconds,
+  clearPin,
+  getIdleSeconds,
+  isLockConfigured,
+  isSessionUnlocked,
+  lockSession,
+  recordUnlock,
+  refreshActivity,
+  setIdleSeconds,
+  setPin,
+  unlockLimiter,
+  unlockSecondsRemaining,
+  validatePin,
+  verifyPin,
+} from "./admin-lock.ts";
+import { verifyCsrfToken } from "./csrf.ts";
+import { findSession, parseSessionCookie } from "./sessions.ts";
+import { isFirstAdmin } from "./users.ts";
+
+export interface AdminLockDeps {
+  db: Database;
+  /** Injectable clock for tests. */
+  now?: () => Date;
+}
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+function err(status: number, error: string, description: string): Response {
+  return json(status, { error, error_description: description });
+}
+
+/**
+ * Resolve the first-admin session for this request, or an error Response.
+ * Mirrors the gate the token-mint endpoints apply, so the lock-management
+ * surface has the same audience.
+ */
+function requireAdminSession(
+  db: Database,
+  req: Request,
+): { ok: true; sessionId: string; userId: string } | { ok: false; res: Response } {
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(db, sid) : null;
+  if (!session || !sid) {
+    return {
+      ok: false,
+      res: err(401, "unauthenticated", "no admin session — sign in at /login first"),
+    };
+  }
+  if (!isFirstAdmin(db, session.userId)) {
+    return {
+      ok: false,
+      res: err(
+        403,
+        "not_admin",
+        "admin lock management is restricted to the hub admin — your account home is at /account/",
+      ),
+    };
+  }
+  return { ok: true, sessionId: sid, userId: session.userId };
+}
+
+async function readJsonBody(req: Request): Promise<Record<string, unknown>> {
+  try {
+    const body = (await req.json()) as unknown;
+    return body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function checkCsrf(req: Request, body: Record<string, unknown>): boolean {
+  const token = typeof body.__csrf === "string" ? body.__csrf : null;
+  return verifyCsrfToken(req, token);
+}
+
+/**
+ * The lock-management router. `subpath` is the path AFTER `/api/admin-lock`
+ * (e.g. "" for status, "/unlock", "/set"). The hub-server dispatcher slices it.
+ */
+export async function handleAdminLock(
+  req: Request,
+  subpath: string,
+  deps: AdminLockDeps,
+): Promise<Response> {
+  const { db } = deps;
+  const now = deps.now ?? (() => new Date());
+
+  // GET status (no body, no CSRF — read-only).
+  if (subpath === "" || subpath === "/") {
+    if (req.method !== "GET") return err(405, "method_not_allowed", "use GET");
+    const gate = requireAdminSession(db, req);
+    if (!gate.ok) return gate.res;
+    const configured = isLockConfigured(db);
+    const nowMs = now().getTime();
+    const locked = configured && !isSessionUnlocked(gate.sessionId, nowMs);
+    return json(200, {
+      configured,
+      locked,
+      idle_seconds: getIdleSeconds(db),
+      unlock_seconds_remaining: configured ? unlockSecondsRemaining(gate.sessionId, nowMs) : 0,
+    });
+  }
+
+  // Everything below is a POST.
+  if (req.method !== "POST") return err(405, "method_not_allowed", "use POST");
+  const gate = requireAdminSession(db, req);
+  if (!gate.ok) return gate.res;
+  const body = await readJsonBody(req);
+  if (!checkCsrf(req, body)) {
+    return err(403, "csrf_failed", "missing or invalid CSRF token");
+  }
+
+  switch (subpath) {
+    case "/set":
+      return handleSet(db, gate.sessionId, body);
+    case "/change":
+      return handleChange(db, gate.sessionId, body, now);
+    case "/remove":
+      return handleRemove(db, gate.sessionId, body, now);
+    case "/unlock":
+      return handleUnlock(db, gate.sessionId, gate.userId, body, now);
+    case "/lock":
+      lockSession(gate.sessionId);
+      return json(200, { locked: true });
+    case "/heartbeat":
+      // Slide the idle window forward if (and only if) currently unlocked.
+      refreshActivity(gate.sessionId, getIdleSeconds(db), now().getTime());
+      return json(200, {
+        locked: isLockConfigured(db) && !isSessionUnlocked(gate.sessionId, now().getTime()),
+        unlock_seconds_remaining: unlockSecondsRemaining(gate.sessionId, now().getTime()),
+      });
+    default:
+      return err(404, "not_found", `no admin-lock route at /api/admin-lock${subpath}`);
+  }
+}
+
+/** Optional idle-seconds override from a request body field. Clamped; undefined when absent/invalid. */
+function readIdleSeconds(body: Record<string, unknown>): number | undefined {
+  const raw = body.idle_seconds;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return undefined;
+  return clampIdleSeconds(raw);
+}
+
+async function handleSet(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+): Promise<Response> {
+  // Setting the FIRST PIN — refuse if one already exists (use /change).
+  if (isLockConfigured(db)) {
+    return err(409, "already_configured", "a PIN is already set — use /api/admin-lock/change");
+  }
+  const pin = typeof body.pin === "string" ? body.pin : "";
+  if (!validatePin(pin).valid) {
+    return err(400, "invalid_pin", "PIN must be 4–12 digits");
+  }
+  const idle = readIdleSeconds(body);
+  if (idle !== undefined) setIdleSeconds(db, idle);
+  await setPin(db, pin);
+  // Setting the PIN immediately opens an unlock window for this session — the
+  // operator who just typed it isn't locked out of their own current session.
+  recordUnlock(sessionId, getIdleSeconds(db));
+  return json(201, { configured: true, locked: false, idle_seconds: getIdleSeconds(db) });
+}
+
+async function handleChange(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<Response> {
+  if (!isLockConfigured(db)) {
+    return err(409, "not_configured", "no PIN is set — use /api/admin-lock/set");
+  }
+  const newPin = typeof body.new_pin === "string" ? body.new_pin : "";
+  if (!validatePin(newPin).valid) {
+    return err(400, "invalid_pin", "new PIN must be 4–12 digits");
+  }
+  // Authorize the change: an already-unlocked session OR a correct current PIN.
+  const authorized = await authorizeMutation(db, sessionId, body, now);
+  if (!authorized.ok) return authorized.res;
+  const idle = readIdleSeconds(body);
+  if (idle !== undefined) setIdleSeconds(db, idle);
+  await setPin(db, newPin);
+  // Re-open the unlock window for this session under the new PIN.
+  recordUnlock(sessionId, getIdleSeconds(db), now().getTime());
+  return json(200, { configured: true, locked: false, idle_seconds: getIdleSeconds(db) });
+}
+
+async function handleRemove(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<Response> {
+  if (!isLockConfigured(db)) {
+    // Idempotent — already off.
+    return json(200, { configured: false, locked: false });
+  }
+  const authorized = await authorizeMutation(db, sessionId, body, now);
+  if (!authorized.ok) return authorized.res;
+  clearPin(db);
+  // Feature is off now — drop any unlock window (it no longer means anything).
+  lockSession(sessionId);
+  return json(200, { configured: false, locked: false });
+}
+
+/**
+ * Shared authorization for change/remove: succeed when the session is already
+ * unlocked, OR a correct `current_pin` is supplied. The current-PIN path runs
+ * through the same brute-force limiter as /unlock.
+ */
+async function authorizeMutation(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<{ ok: true } | { ok: false; res: Response }> {
+  if (isSessionUnlocked(sessionId, now().getTime())) return { ok: true };
+  const currentPin = typeof body.current_pin === "string" ? body.current_pin : "";
+  if (!currentPin) {
+    return {
+      ok: false,
+      res: err(
+        401,
+        "pin_required",
+        "this session is locked — supply current_pin (or unlock first)",
+      ),
+    };
+  }
+  // Rate-limit BEFORE the argon2id verify (a stolen cookie shouldn't grind).
+  const rl = unlockLimiter.checkAndRecord(sessionId, now());
+  if (!rl.allowed) {
+    return {
+      ok: false,
+      res: new Response(
+        JSON.stringify({
+          error: "too_many_attempts",
+          error_description: `too many PIN attempts — retry in ${rl.retryAfterSeconds}s`,
+        }),
+        {
+          status: 429,
+          headers: {
+            "content-type": "application/json",
+            "cache-control": "no-store",
+            "retry-after": String(rl.retryAfterSeconds ?? 60),
+          },
+        },
+      ),
+    };
+  }
+  const ok = await verifyPin(db, currentPin);
+  if (!ok) return { ok: false, res: err(401, "wrong_pin", "incorrect PIN") };
+  return { ok: true };
+}
+
+async function handleUnlock(
+  db: Database,
+  sessionId: string,
+  _userId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<Response> {
+  if (!isLockConfigured(db)) {
+    // No PIN → nothing to unlock; treat as already-open so the SPA proceeds.
+    return json(200, { unlocked: true, configured: false, idle_seconds: getIdleSeconds(db) });
+  }
+  const pin = typeof body.pin === "string" ? body.pin : "";
+  // Rate-limit BEFORE the argon2id verify — keyed by session (the session
+  // already identifies the actor; a stolen cookie shouldn't get fresh buckets
+  // across IPs). The denied attempt still counts toward the bucket so a wrong
+  // PIN can't be retried infinitely.
+  const rl = unlockLimiter.checkAndRecord(sessionId, now());
+  if (!rl.allowed) {
+    return new Response(
+      JSON.stringify({
+        error: "too_many_attempts",
+        error_description: `too many PIN attempts — retry in ${rl.retryAfterSeconds}s`,
+      }),
+      {
+        status: 429,
+        headers: {
+          "content-type": "application/json",
+          "cache-control": "no-store",
+          "retry-after": String(rl.retryAfterSeconds ?? 60),
+        },
+      },
+    );
+  }
+  const ok = await verifyPin(db, pin);
+  if (!ok) {
+    return err(401, "wrong_pin", "incorrect PIN");
+  }
+  recordUnlock(sessionId, getIdleSeconds(db), now().getTime());
+  return json(200, {
+    unlocked: true,
+    configured: true,
+    idle_seconds: getIdleSeconds(db),
+    unlock_seconds_remaining: unlockSecondsRemaining(sessionId, now().getTime()),
+  });
+}

package/src/api-invites.ts

@@ -19,6 +19,7 @@
 import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
+import { SERVICES_MANIFEST_PATH } from "./config.ts";
 import {
   DEFAULT_INVITE_TTL_SECONDS,
   type Invite,
@@ -28,8 +29,11 @@ import {
   issueInvite,
   listInvites,
   revokeInvite,
+  usernameReservedByPendingInvite,
 } from "./invites.ts";
+import { getUserByUsernameCI, validateUsername } from "./users.ts";
 import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
+import { listVaultNamesFromPath } from "./vault-names.ts";
 
 export interface ApiInvitesDeps {
   db: Database;
@@ -49,6 +53,7 @@ interface InviteWireShape {
   id: string;
   status: InviteStatus;
   vault_name: string | null;
+  username: string | null;
   role: string;
   provision_vault: boolean;
   default_mirror: string | null;
@@ -64,6 +69,7 @@ function toWire(invite: Invite, status: InviteStatus): InviteWireShape {
     id: invite.tokenHash,
     status,
     vault_name: invite.vaultName,
+    username: invite.username,
     role: invite.role,
     provision_vault: invite.provisionVault,
     default_mirror: invite.defaultMirror,
@@ -89,6 +95,7 @@ function redeemUrl(issuer: string, rawToken: string): string {
 
 interface CreateInviteBody {
   vaultName: string | null;
+  username: string | null;
   role: string;
   provisionVault: boolean;
   defaultMirror: string | null;
@@ -162,6 +169,37 @@ async function parseCreateBody(
     vaultName = rawVault;
   }
 
+  // username — optional. null/omitted = redeemer picks their own. Validated
+  // with the SAME vocabulary as /api/users (charset + length + reserved).
+  let username: string | null = null;
+  const rawUsername =
+    Object.hasOwn(obj, "username") && obj.username !== undefined ? obj.username : undefined;
+  if (rawUsername !== undefined && rawUsername !== null) {
+    if (typeof rawUsername !== "string" || rawUsername.length === 0) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: '"username" must be a non-empty string or null',
+      };
+    }
+    const u = validateUsername(rawUsername);
+    if (!u.valid) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_username",
+        description:
+          u.reason === "length"
+            ? "username must be 2-32 characters long"
+            : u.reason === "reserved"
+              ? "username is reserved (admin, root, system, setup, parachute, hub)"
+              : "username must contain only lowercase letters, digits, hyphens, and underscores ([a-z0-9_-])",
+      };
+    }
+    username = u.name;
+  }
+
   // role — default 'write' (owner).
   let role = "write";
   const rawRole = obj.role;
@@ -245,7 +283,10 @@ async function parseCreateBody(
     expiresInSeconds = Math.floor(rawExpiry);
   }
 
-  return { ok: true, body: { vaultName, role, provisionVault, defaultMirror, expiresInSeconds } };
+  return {
+    ok: true,
+    body: { vaultName, username, role, provisionVault, defaultMirror, expiresInSeconds },
+  };
 }
 
 /** POST /api/invites — create an invite, return the single-emit URL + token. */
@@ -262,33 +303,72 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
   }
   const parsed = await parseCreateBody(req);
   if (!parsed.ok) return jsonError(parsed.status, parsed.error, parsed.description);
-  const { vaultName, role, provisionVault, defaultMirror, expiresInSeconds } = parsed.body;
+  const { vaultName, username, role, provisionVault, defaultMirror, expiresInSeconds } =
+    parsed.body;
+  const now = (deps.now ?? (() => new Date()))();
 
-  // SECURITY: a pinned vault_name with provision_vault=false would assign the
-  // redeeming user to a PRE-EXISTING vault as owner-admin — a cross-tenant
-  // breach, since the owner-vs-shared role split isn't built. Shared-vault
-  // invites aren't supported yet, so reject this combination outright (defense
-  // in depth — the redeem path rejects it too). The supported shapes are:
-  // provision_vault=true (+ optional pinned name → provisions THAT name), or
-  // provision_vault=false with NO name (account-only, assignedVaults=[]).
-  if (vaultName !== null && !provisionVault) {
+  // Shape gates over the three supported invite shapes:
+  //
+  //   1. provision_vault=true (+ optional pinned NEW name) — redemption
+  //      provisions a fresh vault for the redeemer. Role must be 'write':
+  //      the redeemer is the vault's ONLY user, so a read-only sole user
+  //      would leave the new vault permanently un-writable.
+  //   2. provision_vault=false + vault_name — SHARED-VAULT invite: redemption
+  //      assigns the redeemer to the admin's EXISTING vault at `role` ('read'
+  //      or 'write'). The vault must exist NOW (services.json) — pinning a
+  //      nonexistent name is a typo, not a future reservation. Issuing is
+  //      host:admin-gated, the same authority that can already assign any
+  //      user to any vault via POST /api/users — the invite only packages
+  //      that assignment as a deliverable link. The vault-delete cascade
+  //      (`revokeInvitesForVault`) revokes pending shared invites when the
+  //      pinned vault is deleted, and the redeem path re-checks existence.
+  //   3. provision_vault=false with NO name — account-only (assignedVaults=[]).
+  if (provisionVault && role !== "write") {
     return jsonError(
       400,
       "invalid_request",
-      "shared-vault invites (provision_vault=false with a vault_name) aren't supported yet — omit vault_name for an account-only invite, or set provision_vault=true to provision a new vault",
+      'a provisioned vault\'s sole user must hold write — use role "write", or share an existing vault (provision_vault=false + vault_name) for read-only access',
     );
   }
+  if (vaultName !== null && !provisionVault) {
+    const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
+    const known = new Set(listVaultNamesFromPath(manifestPath));
+    if (!known.has(vaultName)) {
+      return jsonError(
+        400,
+        "vault_not_found",
+        `vault "${vaultName}" is not registered on this hub — shared-vault invites must name an existing vault`,
+      );
+    }
+  }
+
+  // Pre-named username: catch collisions at MINT time (the redeem-time check
+  // stays authoritative, but an enforced name that's already taken makes the
+  // link dead-on-arrival — fail fast for the admin instead).
+  if (username !== null) {
+    if (getUserByUsernameCI(deps.db, username) !== null) {
+      return jsonError(409, "username_taken", `username "${username}" is already in use`);
+    }
+    if (usernameReservedByPendingInvite(deps.db, username, now)) {
+      return jsonError(
+        409,
+        "username_reserved",
+        `username "${username}" is already reserved by another pending invite — revoke that invite first or pick a different name`,
+      );
+    }
+  }
 
   const issued = issueInvite(deps.db, {
     createdBy: authUserId,
     vaultName,
+    username,
     role,
     provisionVault,
     defaultMirror,
     expiresInSeconds,
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });
-  const status = inviteStatus(issued.invite, (deps.now ?? (() => new Date()))());
+  const status = inviteStatus(issued.invite, now);
   return new Response(
     JSON.stringify({
       invite: toWire(issued.invite, status),

package/src/api-modules-ops.ts

@@ -286,8 +286,9 @@ interface PathMatch {
  * for — but the gate is now "is this a KNOWN module" (`isKnownModuleShort`:
  * KNOWN_MODULES ∪ FIRST_PARTY_FALLBACKS), NOT the old `CURATED_MODULES`
  * whitelist (2026-06-09 modular-UI architecture, P2). This is what makes
- * `POST /api/modules/channel/install` resolve — channel was discoverable +
- * running yet un-installable because it sat outside the whitelist.
+ * `POST /api/modules/agent/install` resolve — the agent module (then named
+ * channel) was discoverable + running yet un-installable because it sat
+ * outside the whitelist.
  *
  * The hub (`hub`) and genuinely third-party services.json rows still fall
  * through to undefined: there's no install package to act on.

package/src/api-modules.ts

@@ -53,8 +53,8 @@ import {
   shortNameForManifest,
 } from "./service-spec.ts";
 // `FIRST_PARTY_FALLBACKS` and `KNOWN_MODULES` are both consulted by
-// `lookupModule` below — the former for notes/channel (vendored manifests
-// still required) and the latter for vault/scribe/runner (post-FALLBACK
+// `lookupModule` below — the former for notes (vendored manifest still
+// required) and the latter for vault/scribe/runner/agent (post-FALLBACK
 // retirement, hub#310). The local helper hides the split from the rest of
 // this file. `discoverableShorts` enumerates their UNION — the
 // self-registration-driven discovery surface that replaced the old
@@ -267,14 +267,14 @@ interface ModuleWireShape {
    * `.parachute/module.json` `configUiUrl`, joined against its mount path the
    * same way `management_url` resolves `managementUrl`/`uiUrl`. Drives the
    * Modules page's consistent **Configure** action — clicking lands the
-   * operator on the module's own config UI (channel `/channel/admin`, scribe
+   * operator on the module's own config UI (agent `/agent/admin`, scribe
    * `/scribe/admin`, …), which mints its admin Bearer from the hub's
-   * cookie-gated `/admin/module-token/<short>` (or `/admin/channel-token`).
+   * cookie-gated `/admin/module-token/<short>` (or `/admin/agent-token`).
    *
    * Null when the module hasn't declared `configUiUrl` — the SPA omits the
    * Configure action for that module rather than rendering a dead button.
    * Distinct from `management_url`: a module may declare one, both, or
-   * neither. Channel declares `configUiUrl: "/channel/admin"` + `uiUrl`;
+   * neither. Agent declares `configUiUrl: "/agent/admin"` + `uiUrl`;
    * vault declares `managementUrl` (its admin SPA is the config surface).
    */
   config_ui_url: string | null;
@@ -493,8 +493,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
         );
         if (resolvedManagement !== undefined) managementUrlByShort.set(short, resolvedManagement);
         // The config surface resolves with the SAME rule. A module may declare
-        // `configUiUrl` independently of `managementUrl` — channel ships
-        // `configUiUrl: "/channel/admin"` (single-instance, origin-absolute)
+        // `configUiUrl` independently of `managementUrl` — agent ships
+        // `configUiUrl: "/agent/admin"` (single-instance, origin-absolute)
         // alongside a separate `uiUrl`.
         const resolvedConfig = resolveModuleUrl(m.configUiUrl, value.mountPath, short);
         if (resolvedConfig !== undefined) configUiUrlByShort.set(short, resolvedConfig);
@@ -744,8 +744,8 @@ let warnedLegacyVaultAdminCandidate = false;
  *   - `undefined` candidate → `undefined` (the module didn't declare it).
  *   - Absolute http(s) URL → returned verbatim (off-origin escape hatch).
  *   - Leading-`/` path → ORIGIN-ABSOLUTE, returned verbatim. Single-instance
- *     modules (surface, scribe, runner, channel) declare their full hub-origin
- *     path this way (`/surface/admin/`, `/scribe/admin`, `/channel/admin`);
+ *     modules (surface, scribe, runner, agent) declare their full hub-origin
+ *     path this way (`/surface/admin/`, `/scribe/admin`, `/agent/admin`);
  *     vault's daemon-level surface is `/vault/admin/`.
  *   - Relative path (no leading slash) → MOUNT-JOINED: the per-instance form
  *     (`admin/` on a `/vault/default` mount → `/vault/default/admin/`). With