@openparachute/hub 0.7.0 → 0.7.2-rc.1

package/src/hub-settings.ts

@@ -28,13 +28,14 @@ import type { Database } from "bun:sqlite";
 export type HubSettingKey =
   | "setup_expose_mode"
   | "pending_first_client_auto_approve_until"
-  // hub#272: auto-minted operator token surfaced once on the wizard's
-  // done screen. Single-use — the done-step renderer reads + deletes the
-  // row so a subsequent GET (page refresh, back button) doesn't re-show
-  // the secret. Lives in hub_settings rather than tokens because it's a
-  // wizard-flow ephemeral, not a persistent issued credential — the
-  // mintOperatorToken call still records the jti in the `tokens`
-  // registry, so revocation works as usual.
+  // hub#272: DEPRECATED 2026-06-23 (Austen's report). Used to hold an
+  // auto-minted operator token surfaced once on the wizard's done screen
+  // so the MCP command could pre-fill a `--header "Authorization: Bearer
+  // <token>"` flag. The auto-mint was removed when vault went OAuth-
+  // default (parachute-vault #491) — nothing writes this row anymore.
+  // The key is retained so the done-step GET can defensively clear any
+  // stale row a pre-upgrade hub left behind (it never renders the value).
+  // Drop the member once no live hub_settings tables carry the row.
   | "setup_minted_token"
   // hub#267: the typed vault name. Persisted at vault POST time so the
   // done step can render the operator's choice in the MCP URL +
@@ -91,7 +92,21 @@ export type HubSettingKey =
   // the deprecation window. Stored as the literal string "true" /
   // "false"; any other value parses as "redirect on" (the migration
   // default — operators must opt out, not opt in).
-  | "notes_redirect_disabled";
+  | "notes_redirect_disabled"
+  // Admin-UI screen-lock PIN (hub admin-lock feature). The argon2id hash of
+  // the operator's lock PIN. Absent row = lock feature OFF (today's behavior
+  // exactly — the admin UI is gated only by the password-login session). When
+  // set, the admin token-mint chokepoints refuse to mint while the operator's
+  // session is "locked" (no fresh unlock, or idle-expired). NEVER plaintext;
+  // the hash sits at the same operator-local trust boundary as the password
+  // hashes + signing keys already in hub.db (see migration v11's note on
+  // at-rest encryption). The "unlocked-until" state is per-session + in-memory
+  // (admin-lock.ts) — never persisted, never in the cookie.
+  | "admin_lock_pin_hash"
+  // Idle timeout for the admin screen-lock, in seconds. Optional override of
+  // the built-in default (DEFAULT_ADMIN_LOCK_IDLE_SECONDS). Stored as a
+  // stringified integer; absent / unparseable falls back to the default.
+  | "admin_lock_idle_seconds";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 

package/src/invites.ts

@@ -19,6 +19,24 @@
  * the createUser-then-stamp ordering so a createUser failure leaves the
  * invite re-usable.
  *
+ * Two invite shapes carry that authorization (plus the account-only shape):
+ *   - provision_vault=1 — redemption provisions a NEW vault (optionally
+ *     pre-named via `vault_name`) and assigns the redeemer at `role`
+ *     (always 'write': the sole user of a fresh vault must hold write).
+ *   - provision_vault=0 + vault_name — a SHARED-VAULT invite: redemption
+ *     assigns the redeemer to the admin's EXISTING vault at `role`
+ *     ('read' or 'write'). Issuing is host:admin-gated — the same
+ *     authority that can already assign any user to any vault via
+ *     `POST /api/users` / `PATCH /api/users/:id/vaults` — so the invite
+ *     is a delivery mechanism for an admin-authorized assignment, not an
+ *     escalation. The read-only role is enforced end-to-end: every mint
+ *     path caps to `vaultVerbsForRole` (users.ts) and the vault's
+ *     scope-guard refuses writes for a `vault:<name>:read` token.
+ *
+ * An invite may also pre-name the redeemer's USERNAME (`username` column,
+ * v13): the redemption form shows it read-only and the redeem handler
+ * enforces it. NULL = redeemer picks their own.
+ *
  * Single-use is enforced by stamping `used_at` on redemption — a replay
  * attempt sees the row with `used_at` set and `redeemInvite` throws
  * `InviteUsedError`. Revocation is a separate `revoked_at` stamp the admin
@@ -41,6 +59,11 @@ export interface Invite {
   createdBy: string | null;
   /** Pinned vault name, or null when the redeemer names their own vault. */
   vaultName: string | null;
+  /**
+   * Pre-named username the redeemer's account gets (ENFORCED at redeem),
+   * or null when the redeemer picks their own. v13.
+   */
+  username: string | null;
   /** `user_vaults.role` granted on redemption (`'write'` = owner). */
   role: string;
   /** Whether redemption provisions a NEW vault for the redeemer. */
@@ -86,6 +109,7 @@ interface Row {
   token: string;
   created_by: string | null;
   vault_name: string | null;
+  username: string | null;
   role: string;
   provision_vault: number;
   default_mirror: string | null;
@@ -101,6 +125,7 @@ function rowToInvite(r: Row): Invite {
     tokenHash: r.token,
     createdBy: r.created_by,
     vaultName: r.vault_name,
+    username: r.username,
     role: r.role,
     provisionVault: r.provision_vault === 1,
     defaultMirror: r.default_mirror,
@@ -130,6 +155,11 @@ export interface IssueInviteOpts {
   createdBy: string;
   /** Pinned vault name; omit/null to let the redeemer name their own. */
   vaultName?: string | null;
+  /**
+   * Pre-named username (ENFORCED at redeem); omit/null to let the redeemer
+   * pick their own. Caller validates the vocabulary + uniqueness.
+   */
+  username?: string | null;
   /** `user_vaults` role granted on redemption. Default `'write'` (owner). */
   role?: string;
   /** Provision a new vault on redemption. Default `true` (the primary flow). */
@@ -165,18 +195,20 @@ export function issueInvite(db: Database, opts: IssueInviteOpts): IssuedInvite {
   const expiresAt = new Date(now.getTime() + ttl * 1000).toISOString();
   const role = opts.role ?? "write";
   const vaultName = opts.vaultName ?? null;
+  const username = opts.username ?? null;
   const provisionVault = opts.provisionVault ?? true;
   const defaultMirror = opts.defaultMirror ?? null;
 
   db.prepare(
     `INSERT INTO invites
-       (token, created_by, vault_name, role, provision_vault, default_mirror,
+       (token, created_by, vault_name, username, role, provision_vault, default_mirror,
         expires_at, used_at, redeemed_user_id, revoked_at, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, ?)`,
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, ?)`,
   ).run(
     tokenHash,
     opts.createdBy,
     vaultName,
+    username,
     role,
     provisionVault ? 1 : 0,
     defaultMirror,
@@ -190,6 +222,7 @@ export function issueInvite(db: Database, opts: IssueInviteOpts): IssuedInvite {
       tokenHash,
       createdBy: opts.createdBy,
       vaultName,
+      username,
       role,
       provisionVault,
       defaultMirror,
@@ -215,6 +248,40 @@ export function findInviteByHash(db: Database, tokenHash: string): Invite | null
   return row ? rowToInvite(row) : null;
 }
 
+/**
+ * Is `username` already reserved by a PENDING pre-named invite (unredeemed,
+ * unrevoked, not yet expired)? Two pending invites pre-naming the same
+ * username would make the second one un-redeemable (the redeem path's
+ * uniqueness check fails permanently for an enforced name), so mint-time
+ * rejects the collision.
+ *
+ * Exact `=` comparison, deliberately NOT `COLLATE NOCASE` — an asymmetry
+ * with `getUserByUsernameCI` worth naming. The users-table CI lookup is
+ * defense in depth against legacy/hand-edited `users` rows that might carry
+ * mixed case from before the validator pinned lowercase. `invites.username`
+ * has no such legacy: the column is only ever written through the
+ * `validateUsername`-gated mint path (api-invites.ts), so every stored value
+ * is already lowercase, and the value compared against it went through the
+ * same validator. A hand-edited mixed-case invites row wouldn't reserve —
+ * but it also can't redeem: the redeem path re-runs `validateUsername` on
+ * the pre-named value and rejects it (the hand-edited-row backstop in
+ * account-setup.ts).
+ */
+export function usernameReservedByPendingInvite(
+  db: Database,
+  username: string,
+  now: Date = new Date(),
+): boolean {
+  const row = db
+    .query<{ token: string }, [string, string]>(
+      `SELECT token FROM invites
+       WHERE username = ? AND used_at IS NULL AND revoked_at IS NULL AND expires_at > ?
+       LIMIT 1`,
+    )
+    .get(username, now.toISOString());
+  return row !== null;
+}
+
 /** List every invite, newest first, with derived status. */
 export function listInvites(
   db: Database,

package/src/jwt-sign.ts

@@ -141,12 +141,22 @@ export interface SignRefreshTokenOpts {
  * when provisioning a connection (the webhook bearer + the channel reply
  * token). Registered so connection teardown can revoke them
  * (hub-module-boundary charter, registered-mint rule).
+ *
+ * `connection_credential` — standing tag-scoped vault credentials minted by
+ * a `kind: "credential"` connection (H4, surface-runtime design). Registered
+ * for the same reason; renewal revokes the prior jti and registers the new
+ * one, so exactly one live row exists per credential connection.
  */
 export type TokenCreatedVia =
   | "oauth_refresh"
   | "cli_mint"
   | "operator_mint"
-  | "connection_provision";
+  | "connection_provision"
+  | "connection_credential"
+  // Agent-connector grants (Phase 4b-1) — a vault token the hub mints when the
+  // operator approves an agent's `vault:<name>:<verb>` connection grant. Stored
+  // in the agent-grants store; registered here so revoke can drop it.
+  | "agent_grant";
 
 export interface SignedRefreshToken {
   /** Opaque token to return to the client. NOT recoverable from the DB. */

package/src/module-manifest.ts

@@ -124,13 +124,52 @@ export interface ModuleAction {
    * Bearer` (P5). For a `vault-trigger`, this is persisted as the trigger's
    * long-lived `action.auth.bearer` scope — the credential the sink module
    * validates on every callback. Sourced from the action declaration so the
-   * hub never hardcodes a per-module scope. Channel ships `"channel:send"`.
+   * hub never hardcodes a per-module scope. Agent ships `"agent:send"`.
    */
   readonly scope?: string;
   /** Opaque (P1) descriptor of how the hub provisions this action. */
   readonly provision?: unknown;
 }
 
+/**
+ * A standing CREDENTIAL a module declares it can hold (H4, surface-runtime
+ * design / credential connections). Where an action's `scope` is a scope in
+ * the module's OWN namespace (minted for callbacks INTO the module), a
+ * credential declaration asks the hub to mint the module a standing
+ * tag-scoped token on a VAULT — operator-approved via
+ * `POST /admin/connections` with `kind: "credential"`.
+ *
+ * The `scope` field is a TEMPLATE, not a literal: `vault:{vault}:read` or
+ * `vault:{vault}:write` — the `{vault}` placeholder is filled by the
+ * operator's approval (which vault, which tags). Validation enforces the
+ * privilege-escalation guard at declaration time: ONLY the `vault` namespace,
+ * ONLY `read`/`write` verbs — never `admin`, never another module's
+ * namespace. (The POST handler re-checks the same rule, so a manifest read
+ * through a non-validating path can't smuggle a broader template.)
+ */
+export interface ModuleCredential {
+  /** Credential identifier within the module, e.g. `vault`. */
+  readonly key: string;
+  /** Operator-facing label. */
+  readonly title: string;
+  readonly description?: string;
+  /**
+   * Scope template: `vault:{vault}:read` | `vault:{vault}:write`. The
+   * operator approval fills `{vault}` and supplies the tag scope.
+   */
+  readonly scope: string;
+  /**
+   * Daemon-root-relative HTTP endpoint (leading `/`) the hub POSTs the
+   * minted credential to over loopback (like the engine's channel-config
+   * delivery), authenticated with a short-lived `<module>:admin` bearer.
+   * Also receives the best-effort removal payload on teardown.
+   */
+  readonly endpoint: string;
+}
+
+/** The validated shape of a credential scope template. */
+export const CREDENTIAL_SCOPE_TEMPLATE_RE = /^vault:\{vault\}:(read|write)$/;
+
 /**
  * One declared parameter of a {@link ConnectionTemplate} — the operator-chosen
  * blank in the template (e.g. WHICH vault, the channel name).
@@ -271,6 +310,16 @@ export interface ModuleManifest {
    * per-module rationale.
    */
   readonly stripPrefix?: boolean;
+  /**
+   * When `true`, the module's daemon accepts WebSocket upgrades and the hub's
+   * Bun-native upgrade bridge (H1, surface-runtime design) forwards
+   * `Upgrade: websocket` requests on the module's mounts. DENY BY DEFAULT:
+   * absent/false refuses upgrades (426) before they reach the daemon. The
+   * canonical capability declaration; modules also carry it onto their
+   * self-registered services.json row (`ServiceEntry.websocket`), and the hub
+   * honors either source.
+   */
+  readonly websocket?: boolean;
   /**
    * Discovery tier (2026-06-09 modular-UI architecture). When a module
    * declares `focus`, the hub's Modules screen uses it verbatim; otherwise it
@@ -298,6 +347,8 @@ export interface ModuleManifest {
   readonly actions?: readonly ModuleAction[];
   /** Connection presets this module declares — see {@link ConnectionTemplate}. */
   readonly connectionTemplates?: readonly ConnectionTemplate[];
+  /** Standing vault credentials this module can hold — see {@link ModuleCredential} (H4). */
+  readonly credentials?: readonly ModuleCredential[];
 }
 
 export class ModuleManifestError extends Error {
@@ -562,6 +613,7 @@ export function validateModuleManifest(
   const events = asEvents(m.events, where);
   const actions = asActions(m.actions, where, name);
   const connectionTemplates = asConnectionTemplates(m.connectionTemplates, where);
+  const credentials = asCredentials(m.credentials, where);
   let stripPrefix: boolean | undefined;
   if (m.stripPrefix !== undefined) {
     if (typeof m.stripPrefix !== "boolean") {
@@ -569,6 +621,13 @@ export function validateModuleManifest(
     }
     stripPrefix = m.stripPrefix;
   }
+  let websocket: boolean | undefined;
+  if (m.websocket !== undefined) {
+    if (typeof m.websocket !== "boolean") {
+      throw new ModuleManifestError(`${where}: "websocket" must be a boolean if present`);
+    }
+    websocket = m.websocket;
+  }
 
   const out: ModuleManifest = { name, manifestName, port, paths, health };
   if (displayName !== undefined) (out as { displayName?: string }).displayName = displayName;
@@ -590,6 +649,9 @@ export function validateModuleManifest(
   if (stripPrefix !== undefined) {
     (out as { stripPrefix?: boolean }).stripPrefix = stripPrefix;
   }
+  if (websocket !== undefined) {
+    (out as { websocket?: boolean }).websocket = websocket;
+  }
   if (focus !== undefined) (out as { focus?: ModuleFocus }).focus = focus;
   if (configUiUrl !== undefined) (out as { configUiUrl?: string }).configUiUrl = configUiUrl;
   if (adminCapabilities !== undefined) {
@@ -601,9 +663,54 @@ export function validateModuleManifest(
     (out as { connectionTemplates?: readonly ConnectionTemplate[] }).connectionTemplates =
       connectionTemplates;
   }
+  if (credentials !== undefined) {
+    (out as { credentials?: readonly ModuleCredential[] }).credentials = credentials;
+  }
   return out;
 }
 
+/**
+ * Validate the optional `credentials` declaration (H4). The scope template
+ * is the privilege-escalation guard's declaration-time half: ONLY
+ * `vault:{vault}:read` / `vault:{vault}:write` — a module can never declare
+ * its way to `admin`, to a literal vault name (the operator picks the vault
+ * at approval), or to another module's namespace. The POST handler re-checks
+ * the same rule (defense in depth for manifests read through paths that skip
+ * this validator).
+ */
+function asCredentials(v: unknown, where: string): readonly ModuleCredential[] | undefined {
+  if (v === undefined) return undefined;
+  if (!Array.isArray(v)) {
+    throw new ModuleManifestError(`${where}: "credentials" must be an array if present`);
+  }
+  return v.map((raw, i) => {
+    const at = `credentials[${i}]`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new ModuleManifestError(`${where}: "${at}" must be an object`);
+    }
+    const c = raw as Record<string, unknown>;
+    const scope = asString(c.scope, where, `${at}.scope`);
+    if (!CREDENTIAL_SCOPE_TEMPLATE_RE.test(scope)) {
+      throw new ModuleManifestError(
+        `${where}: "${at}.scope" "${scope}" must be "vault:{vault}:read" or "vault:{vault}:write" — credential connections never grant admin or another namespace`,
+      );
+    }
+    const endpoint = asString(c.endpoint, where, `${at}.endpoint`);
+    if (!endpoint.startsWith("/")) {
+      throw new ModuleManifestError(`${where}: "${at}.endpoint" must start with "/"`);
+    }
+    const out: ModuleCredential = {
+      key: asString(c.key, where, `${at}.key`),
+      title: asString(c.title, where, `${at}.title`),
+      scope,
+      endpoint,
+    };
+    const description = asOptionalString(c.description, where, `${at}.description`);
+    if (description !== undefined) (out as { description?: string }).description = description;
+    return out;
+  });
+}
+
 const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental"]);
 
 function asFocus(v: unknown, where: string): ModuleFocus | undefined {
@@ -670,7 +777,7 @@ function asActions(
       // `scope` is minted by the hub into a 90-day webhook bearer presented to
       // THIS module's own endpoint, which validates `aud:<name>` + a scope in
       // its own namespace. A legitimate `action.scope` is therefore always in
-      // the declaring module's namespace (channel.message.deliver → channel:send).
+      // the declaring module's namespace (agent.message.deliver → agent:send).
       // Enforcing `<ns> === name` blocks a malicious module declaring e.g.
       // `vault:default:admin` and tricking the hub into minting a cross-module
       // privilege-escalating token when an operator wires a Connection to it.