@openparachute/hub 0.7.0 → 0.7.1

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,18 @@ 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";
 
 export interface SignedRefreshToken {
   /** Opaque token to return to the client. NOT recoverable from the DB. */

package/src/module-manifest.ts

@@ -131,6 +131,45 @@ export interface ModuleAction {
   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 {

package/src/origin-check.ts

@@ -180,10 +180,13 @@ const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
  * mutation under `/admin/*`; keep this list in sync with the dispatch in
  * `hub-server.ts`):
  *
- *   - `POST /admin/connections` + `DELETE /admin/connections/<id>`
- *     (connection provision/teardown — the seam's canonical consumers are
- *     channel's admin page and the hub SPA, both same-origin `fetch()` with
- *     `credentials: "include"`)
+ *   - `POST /admin/connections` + `DELETE /admin/connections/<id>` +
+ *     `POST /admin/connections/<id>/approve`
+ *     (connection provision/teardown/claim-approval — the seam's canonical
+ *     consumers are channel's admin page and the hub SPA, both same-origin
+ *     `fetch()` with `credentials: "include"`. The Bearer-authed
+ *     `/<id>/renew` + `/<id>/claim` siblings pass the belt via the
+ *     Authorization carve-out below.)
  *
  * (The legacy `POST/DELETE /admin/channels` pair was belted here until
  * boundary D1 retired the endpoint — superseded by `/admin/connections`.)

package/src/services-manifest.ts

@@ -71,6 +71,38 @@ function normalizeUiSubUnitStatus(value: string): UiSubUnitStatus | undefined {
   return UI_SUB_UNIT_STATUS_ALIASES[value];
 }
 
+/**
+ * Who may load a UI sub-unit through the hub proxy (H3, surface-runtime
+ * design §12 — fixes parachute-surface#88, where `public` was declared but
+ * never enforced):
+ *
+ *   "public"    — anyone; no hub identity required (chrome strip off — H5).
+ *   "hub-users" — a valid hub session cookie OR a hub-issued Bearer whose
+ *                 scopes satisfy the surface's `scopes_required` (the OR
+ *                 keeps installed PWAs working). THE DEFAULT when absent.
+ *   "operator"  — the first-admin session only.
+ *   "surface"   — the surface backend owns admission END-TO-END; the hub
+ *                 proxy passes every request through (backed surfaces —
+ *                 kit-authenticated via @openparachute/surface-server: hub
+ *                 JWTs / capability links / anon, deny-by-default). Chrome
+ *                 strip off like `public` — capability-link invitees are
+ *                 NOT hub users.
+ *
+ * Enforced at the hub proxy BEFORE forwarding (`src/audience-gate.ts`).
+ * Legacy boolean `public` on the wire is accepted one alias window:
+ * `public: true` → `"public"`, `public: false` → default. Fail-closed: an
+ * unrecognized `audience` value rejects the row (the lenient manifest read
+ * then drops it — unroutable beats accidentally public). Version-skew
+ * corollary: a surface declaring `audience: "surface"` registered against a
+ * hub OLDER than this value's introduction gets its row rejected by that
+ * same fail-closed rule — the mount 404s until the hub is upgraded. The
+ * surface-side meta-schema ships the value with a hub-version requirement
+ * note for exactly this reason.
+ */
+export type UiAudience = "public" | "hub-users" | "operator" | "surface";
+
+const UI_AUDIENCE_VALUES: readonly UiAudience[] = ["public", "hub-users", "operator", "surface"];
+
 /**
  * A sub-unit beneath a module — used today by parachute-app to surface each
  * hosted UI as its own discoverable row under the App module, and the shape
@@ -129,6 +161,20 @@ export interface UiSubUnit {
   oauthClientId?: string;
   /** UI sub-unit lifecycle state. Absent → discovery treats as "active". */
   status?: UiSubUnitStatus;
+  /**
+   * Audience exposure (H3). Absent → "hub-users". The legacy boolean
+   * `public` field is normalized into this on read (true → "public") for
+   * one alias window. See {@link UiAudience}.
+   */
+  audience?: UiAudience;
+  /**
+   * OAuth scopes the UI declares as required (surface-host stamps these from
+   * the surface's meta.json `scopes_required`, e.g. `["vault:*:read"]` —
+   * `*` is a single-segment wildcard). The audience gate's Bearer branch
+   * checks a presented token's scopes against these. Snake_case to match
+   * the wire shape surface already writes.
+   */
+  scopes_required?: string[];
 }
 
 export interface ServiceEntry {
@@ -170,6 +216,16 @@ export interface ServiceEntry {
    *     bridges the gap. Tracked in parachute-scribe (separate issue).
    */
   stripPrefix?: boolean;
+  /**
+   * When `true`, the module's daemon accepts WebSocket upgrades and the hub's
+   * Bun-native upgrade bridge (H1, surface-runtime design) will forward
+   * `Upgrade: websocket` requests on this module's mounts to it. DENY BY
+   * DEFAULT: absent/false means an upgrade request to this mount is refused
+   * (426) without ever reaching the daemon. Modules declare this on their
+   * `.parachute/module.json` (the install-time contract) and carry it onto
+   * their self-registered services.json row; the hub honors either source.
+   */
+  websocket?: boolean;
   /**
    * Sub-units hosted under this module — parachute-app's bag of UIs, and
    * the shape vault is expected to adopt for per-instance metadata in a
@@ -282,6 +338,10 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (stripPrefix !== undefined && typeof stripPrefix !== "boolean") {
     throw new ServicesManifestError(`${where}: "stripPrefix" must be a boolean if present`);
   }
+  const websocket = e.websocket;
+  if (websocket !== undefined && typeof websocket !== "boolean") {
+    throw new ServicesManifestError(`${where}: "websocket" must be a boolean if present`);
+  }
   const uis = e.uis;
   const validatedUis = validateUis(uis, where);
   const validatedStartError = validateStartError(e.lastStartError, where);
@@ -291,6 +351,7 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (publicExposure !== undefined) entry.publicExposure = publicExposure as PublicExposure;
   if (installDir !== undefined) entry.installDir = installDir;
   if (stripPrefix !== undefined) entry.stripPrefix = stripPrefix;
+  if (websocket !== undefined) entry.websocket = websocket;
   if (validatedUis !== undefined) entry.uis = validatedUis;
   if (validatedStartError !== undefined) entry.lastStartError = validatedStartError;
   return entry;
@@ -405,12 +466,48 @@ function validateUiSubUnit(raw: unknown, where: string): UiSubUnit {
     }
     normalizedStatus = norm;
   }
+  // Audience (H3). Explicit `audience` wins; the legacy boolean `public` is
+  // accepted as an alias for one release window (true → "public"; false →
+  // the default, i.e. no field). FAIL-CLOSED on malformed values: throwing
+  // here makes the lenient manifest read drop the whole row — an unroutable
+  // surface beats one that silently falls open to the wrong audience.
+  let audience: UiAudience | undefined;
+  if (u.audience !== undefined) {
+    if (
+      typeof u.audience !== "string" ||
+      !(UI_AUDIENCE_VALUES as readonly string[]).includes(u.audience)
+    ) {
+      throw new ServicesManifestError(
+        `${where}: "audience" must be "public" | "hub-users" | "operator" | "surface" if present (got ${JSON.stringify(u.audience)})`,
+      );
+    }
+    audience = u.audience as UiAudience;
+  } else if (u.public !== undefined) {
+    if (typeof u.public !== "boolean") {
+      throw new ServicesManifestError(`${where}: legacy "public" must be a boolean if present`);
+    }
+    if (u.public) audience = "public";
+  }
+  let scopesRequired: string[] | undefined;
+  if (u.scopes_required !== undefined) {
+    if (
+      !Array.isArray(u.scopes_required) ||
+      u.scopes_required.some((s) => typeof s !== "string" || s.length === 0)
+    ) {
+      throw new ServicesManifestError(
+        `${where}: "scopes_required" must be an array of non-empty strings if present`,
+      );
+    }
+    scopesRequired = u.scopes_required as string[];
+  }
   const out: UiSubUnit = { displayName, path };
   if (tagline !== undefined) out.tagline = tagline;
   if (iconUrl !== undefined) out.iconUrl = iconUrl;
   if (version !== undefined) out.version = version;
   if (oauthClientId !== undefined) out.oauthClientId = oauthClientId;
   if (normalizedStatus !== undefined) out.status = normalizedStatus;
+  if (audience !== undefined) out.audience = audience;
+  if (scopesRequired !== undefined) out.scopes_required = scopesRequired;
   return out;
 }