@openparachute/hub 0.7.3-rc.2 → 0.7.3-rc.4

package/src/api-invites.ts

@@ -15,6 +15,18 @@
  *
  * Wire shape is snake_case (matches `/api/users`). An invite's raw token
  * NEVER appears in a GET/list response — only in the POST-create `url`.
+ *
+ * v15 (DEMO-PREP Workstream B) extends POST /api/invites with `max_uses`
+ * (multi-use public-signup links, default 1 = single-use) and
+ * `vault_cap_bytes` (per-vault storage cap stamped at provision, B4). A
+ * multi-use PROVISIONING link with no explicit `vault_cap_bytes` auto-defaults
+ * to ~1 GB (DEFAULT_VAULT_CAP_BYTES) so a public link never provisions
+ * uncapped by omission; single-use friends links stay uncapped unless opted
+ * in. The list/create wire shape gains `max_uses`, `used_count`, `email`
+ * (latest redeemer, B2), and `vault_cap_bytes`. `expires_in` already bounded
+ * the link lifetime (B1's expiry). A multi-use link can't pre-name a username
+ * or pin a single new vault name (every seat past the first would collide —
+ * rejected at mint).
  */
 import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
@@ -32,6 +44,7 @@ import {
   usernameReservedByPendingInvite,
 } from "./invites.ts";
 import { getUserByUsernameCI, validateUsername } from "./users.ts";
+import { DEFAULT_VAULT_CAP_BYTES } from "./vault-caps.ts";
 import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 import { listVaultNamesFromPath } from "./vault-names.ts";
 
@@ -47,6 +60,18 @@ export interface ApiInvitesDeps {
 const ALLOWED_ROLES = new Set(["read", "write"]);
 /** Cap an invite TTL so a typo can't mint a ~forever link. 90 days. */
 const MAX_INVITE_TTL_SECONDS = 90 * 24 * 60 * 60;
+/**
+ * Cap `max_uses` (v15) so a typo can't mint a runaway public-signup link on a
+ * shared box. 1000 is comfortably above any demo cohort while still bounding
+ * the abuse surface. The DEMO-PREP shared box uses small values (tens of seats).
+ */
+const MAX_INVITE_USES = 1000;
+/**
+ * Ceiling on a per-vault cap an invite may carry (v15, B4). 100 GiB — far
+ * above the ~1 GB default, but bounds a fat-finger that would make the cap
+ * meaningless on a shared box. The minimum is 1 byte (a positive integer).
+ */
+const MAX_VAULT_CAP_BYTES = 100 * 1024 * 1024 * 1024;
 
 interface InviteWireShape {
   /** sha256 hash — the stable id for list/revoke. NOT the raw token. */
@@ -57,6 +82,14 @@ interface InviteWireShape {
   role: string;
   provision_vault: boolean;
   default_mirror: string | null;
+  /** v15 — how many accounts this link may create (1 = single-use). */
+  max_uses: number;
+  /** v15 — how many it has created so far. */
+  used_count: number;
+  /** v15 — most-recent redeemer's email (B2), or null. */
+  email: string | null;
+  /** v15 — per-vault storage cap to stamp at provision (B4), or null (uncapped). */
+  vault_cap_bytes: number | null;
   expires_at: string;
   used_at: string | null;
   redeemed_user_id: string | null;
@@ -73,6 +106,10 @@ function toWire(invite: Invite, status: InviteStatus): InviteWireShape {
     role: invite.role,
     provision_vault: invite.provisionVault,
     default_mirror: invite.defaultMirror,
+    max_uses: invite.maxUses,
+    used_count: invite.usedCount,
+    email: invite.email,
+    vault_cap_bytes: invite.vaultCapBytes,
     expires_at: invite.expiresAt,
     used_at: invite.usedAt,
     redeemed_user_id: invite.redeemedUserId,
@@ -100,6 +137,10 @@ interface CreateInviteBody {
   provisionVault: boolean;
   defaultMirror: string | null;
   expiresInSeconds: number;
+  /** v15 — how many accounts the link may create (default 1 = single-use). */
+  maxUses: number;
+  /** v15 — per-vault storage cap (bytes) to stamp at provision, or null (uncapped). */
+  vaultCapBytes: number | null;
 }
 
 interface ParseErr {
@@ -283,9 +324,71 @@ async function parseCreateBody(
     expiresInSeconds = Math.floor(rawExpiry);
   }
 
+  // max_uses — v15. Default 1 (single-use, the legacy shape). A positive
+  // integer ≤ MAX_INVITE_USES. >1 = a multi-use public-signup link.
+  let maxUses = 1;
+  const rawMaxUses =
+    Object.hasOwn(obj, "max_uses") && obj.max_uses !== undefined
+      ? obj.max_uses
+      : Object.hasOwn(obj, "maxUses") && obj.maxUses !== undefined
+        ? obj.maxUses
+        : undefined;
+  if (rawMaxUses !== undefined && rawMaxUses !== null) {
+    if (
+      typeof rawMaxUses !== "number" ||
+      !Number.isInteger(rawMaxUses) ||
+      rawMaxUses < 1 ||
+      rawMaxUses > MAX_INVITE_USES
+    ) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: `"max_uses" must be an integer between 1 and ${MAX_INVITE_USES}`,
+      };
+    }
+    maxUses = rawMaxUses;
+  }
+
+  // vault_cap_bytes — v15, B4. Optional per-vault storage cap stamped at
+  // provision. null/omitted = uncapped (legacy). A positive integer
+  // ≤ MAX_VAULT_CAP_BYTES.
+  let vaultCapBytes: number | null = null;
+  const rawCap =
+    Object.hasOwn(obj, "vault_cap_bytes") && obj.vault_cap_bytes !== undefined
+      ? obj.vault_cap_bytes
+      : Object.hasOwn(obj, "vaultCapBytes") && obj.vaultCapBytes !== undefined
+        ? obj.vaultCapBytes
+        : undefined;
+  if (rawCap !== undefined && rawCap !== null) {
+    if (
+      typeof rawCap !== "number" ||
+      !Number.isInteger(rawCap) ||
+      rawCap < 1 ||
+      rawCap > MAX_VAULT_CAP_BYTES
+    ) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: `"vault_cap_bytes" must be a positive integer ≤ ${MAX_VAULT_CAP_BYTES} (100 GiB)`,
+      };
+    }
+    vaultCapBytes = rawCap;
+  }
+
   return {
     ok: true,
-    body: { vaultName, username, role, provisionVault, defaultMirror, expiresInSeconds },
+    body: {
+      vaultName,
+      username,
+      role,
+      provisionVault,
+      defaultMirror,
+      expiresInSeconds,
+      maxUses,
+      vaultCapBytes,
+    },
   };
 }
 
@@ -303,8 +406,16 @@ 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, username, role, provisionVault, defaultMirror, expiresInSeconds } =
-    parsed.body;
+  const {
+    vaultName,
+    username,
+    role,
+    provisionVault,
+    defaultMirror,
+    expiresInSeconds,
+    maxUses,
+    vaultCapBytes,
+  } = parsed.body;
   const now = (deps.now ?? (() => new Date()))();
 
   // Shape gates over the three supported invite shapes:
@@ -330,6 +441,42 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
       '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',
     );
   }
+
+  // Multi-use coherence gates (v15). A link that creates many accounts can't:
+  //   - pre-name a username (one name can't be reused across redeemers), or
+  //   - pin a single NEW vault name (every redeemer would collide on it —
+  //     the redeem path's freshly-created invariant rejects the 2nd onward).
+  // Either combination would make every seat past the first dead-on-arrival,
+  // so reject at mint. (A multi-use SHARED-vault invite — provision_vault=false
+  // + an existing vault_name — IS coherent: many users joining one vault; it's
+  // not blocked here.)
+  if (maxUses > 1) {
+    if (username !== null) {
+      return jsonError(
+        400,
+        "invalid_request",
+        "a multi-use link (max_uses > 1) can't pre-name a username — one username can't be shared across signups. Omit \"username\".",
+      );
+    }
+    if (provisionVault && vaultName !== null) {
+      return jsonError(
+        400,
+        "invalid_request",
+        'a multi-use provisioning link (max_uses > 1) can\'t pin a single vault name — every signup would collide on it. Omit "vault_name" so each signup names their own vault.',
+      );
+    }
+  }
+
+  // A per-vault cap only applies to a vault THIS link provisions. Pinning a
+  // cap on a non-provisioning invite (account-only or shared-existing-vault)
+  // has nothing to stamp — reject the contradiction at mint.
+  if (vaultCapBytes !== null && !provisionVault) {
+    return jsonError(
+      400,
+      "invalid_request",
+      '"vault_cap_bytes" only applies to a provisioning invite (provision_vault=true) — a non-provisioning link has no vault to cap',
+    );
+  }
   if (vaultName !== null && !provisionVault) {
     const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
     const known = new Set(listVaultNamesFromPath(manifestPath));
@@ -358,6 +505,17 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
     }
   }
 
+  // Auto-apply the ~1 GB default cap to a PUBLIC-SIGNUP (multi-use,
+  // provisioning) link when the admin didn't set one explicitly — the
+  // DEMO-PREP decision is "1 GB per vault, configurable," so a multi-use
+  // signup link on a shared box should never provision UNcapped by omission.
+  // An explicit cap (any value, validated above) is honored as-is; a
+  // single-use friends link stays uncapped unless the admin opts in.
+  const effectiveVaultCapBytes =
+    vaultCapBytes === null && maxUses > 1 && provisionVault
+      ? DEFAULT_VAULT_CAP_BYTES
+      : vaultCapBytes;
+
   const issued = issueInvite(deps.db, {
     createdBy: authUserId,
     vaultName,
@@ -366,6 +524,8 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
     provisionVault,
     defaultMirror,
     expiresInSeconds,
+    maxUses,
+    vaultCapBytes: effectiveVaultCapBytes,
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });
   const status = inviteStatus(issued.invite, now);

package/src/api-users.ts

@@ -88,6 +88,8 @@ export interface UserWireShape {
   id: string;
   username: string;
   password_changed: boolean;
+  /** Contactable email captured at signup (v15, B2), or null. Visible to admin. */
+  email: string | null;
   assigned_vaults: string[];
   created_at: string;
 }
@@ -97,6 +99,7 @@ function toWire(u: User): UserWireShape {
     id: u.id,
     username: u.username,
     password_changed: u.passwordChanged,
+    email: u.email,
     assigned_vaults: [...u.assignedVaults],
     created_at: u.createdAt,
   };

package/src/hub-db.ts

@@ -4,7 +4,10 @@
  * issuer — signing keys (v1), users + opaque refresh tokens (v2), OAuth
  * clients + auth-codes + grants + browser sessions (v3), TOTP 2FA
  * enrollment on the users row (v11, hub#473), and one-time invite links
- * (v12, the `invites` table; v13 adds the pre-named `username` column).
+ * (v12, the `invites` table; v13 adds the pre-named `username` column;
+ * v14 adds refresh-token rotation grace; v15 generalizes invites into
+ * multi-use public-signup links + email-as-username + the `vault_caps`
+ * per-vault storage-cap table).
  *
  * Each open() runs `migrate()` to bring the schema up to date. A
  * `schema_version` table records every applied migration so re-opens are
@@ -451,6 +454,110 @@ const MIGRATIONS: readonly Migration[] = [
       ALTER TABLE invites ADD COLUMN username TEXT;
     `,
   },
+  {
+    version: 14,
+    sql: `
+      -- Refresh-token rotation grace window (hub#685). Records the successor
+      -- a refresh-token row rotated INTO, so the refresh handler can tell the
+      -- *immediately-previous* token (the single benign concurrent/retried
+      -- refresh a multi-tab / bfcache / network-retry client legitimately
+      -- presents) apart from a genuine replay of an older ancestor (theft).
+      --
+      -- \`rotated_to\` is the jti of the row minted when this row rotated. NULL
+      -- on every row that has not (yet) rotated: live tokens, revoked-by-
+      -- /oauth/revoke tokens, revoked-by-family-sweep tokens, and every
+      -- pre-v14 row (no backfill — pre-v14 rotations left no successor link,
+      -- so they fall through to the zero-tolerance theft path exactly as
+      -- before; the grace window only ever helps rows minted post-v14).
+      --
+      -- The successor link is the ONLY structural ordering signal we need:
+      -- created_at alone can't distinguish the direct predecessor from an
+      -- older ancestor under burst issuance (ties), and the grace decision is
+      -- security-load-bearing, so it must be exact, not heuristic.
+      ALTER TABLE tokens ADD COLUMN rotated_to TEXT;
+    `,
+  },
+  {
+    version: 15,
+    sql: `
+      -- Multi-use public signup links + email-as-username + per-vault caps
+      -- (DEMO-PREP-2026-06-25 Workstream B: B1 multi-use invite, B2 email
+      -- capture, B4 public signup page; the cap value is persisted now so
+      -- B3's vault-side enforcement — a separate Phase-2 PR — can read it).
+      --
+      -- (1) FOUR columns on \`invites\` generalize the single-use link into a
+      --     multi-use, capped one. Backwards compatible: every pre-v15 invite
+      --     redeems exactly as before because the defaults reproduce the old
+      --     single-use semantics.
+      --
+      --   * max_uses (INTEGER NOT NULL DEFAULT 1) — how many accounts ONE link
+      --     may create. DEFAULT 1 = the historical single-use invite, so every
+      --     pre-v15 row and every default-shaped new row stays single-use. A
+      --     public signup link mints with a higher value (e.g. 25 demo seats).
+      --   * used_count (INTEGER NOT NULL DEFAULT 0) — how many accounts the link
+      --     HAS created. Redeem refuses once used_count >= max_uses. Replaces
+      --     the boolean used_at as the exhaustion signal for multi-use links;
+      --     used_at is RETAINED (stamped on the FIRST redeem) so legacy
+      --     single-use lookups + the admin list's "redeemed" status keep
+      --     working unchanged.
+      --   * email (TEXT, nullable) — the redeemer's email captured at signup
+      --     as the contactable identity (B2). NULL on every pre-v15 invite and
+      --     on admin-issued links that don't collect email; set per-redemption
+      --     for public-signup links. Stored so the operator can reach signups.
+      --     (One link → many signups means one invite row can't hold every
+      --     redeemer's email; this column holds the MOST-RECENT redeemer's
+      --     email for a single-use link, and the per-account email lives on the
+      --     users row — see (3). For multi-use the canonical per-user email is
+      --     users.email.)
+      --   * vault_cap_bytes (INTEGER, nullable) — the per-vault storage cap to
+      --     STAMP onto each vault this link provisions (B4). NULL on every
+      --     pre-v15 invite + admin-issued links that don't set a cap (those
+      --     provision uncapped, the historical behavior); set to ~1 GB on a
+      --     public-signup link so each provisioned vault gets a vault_caps row
+      --     for the Phase-2 enforcement PR to read. The cap travels on the
+      --     invite (not a server-wide default) so different links can carry
+      --     different caps.
+      --
+      -- (2) ONE column on \`users\`: email-as-contactable-identity (B2). The
+      --     username stays the login + URL identity ([a-z0-9_-]); email is the
+      --     separate contact field the operator sees + uses to reach a signup.
+      --     Nullable: every pre-v15 account (wizard admin, env-seeded admin,
+      --     pre-named friend invites) predates email capture and keeps NULL.
+      --     NOT UNIQUE — two people behind one shared mailbox, or an operator
+      --     re-using their address across test accounts, shouldn't be blocked
+      --     at the schema. Validation (format) happens at the API/redeem edge.
+      --
+      -- (3) NEW \`vault_caps\` table — the per-vault storage cap, persisted at
+      --     provision time (B4: "persist a per-vault cap value at provision
+      --     time EVEN THOUGH vault-side enforcement lands in a separate
+      --     Phase-2 PR — at minimum store the cap so the later PR can read +
+      --     enforce it"). Keyed by vault_name (the same instance-name space
+      --     used across services.json / user_vaults / invites.vault_name; no
+      --     FK — vault names resolve through services.json, not a DB row, the
+      --     established pattern). cap_bytes is the byte ceiling (default
+      --     ~1 GB stamped by the public-signup flow), guarded by a
+      --     CHECK (cap_bytes > 0) so a direct DB write can't seed a 0/negative
+      --     cap the Phase-2 reader would misinterpret. No backfill — existing
+      --     vaults have no cap row, which the Phase-2 enforcement reads as
+      --     "uncapped" (only vaults provisioned through a capped signup get a
+      --     row).
+      ALTER TABLE invites ADD COLUMN max_uses INTEGER NOT NULL DEFAULT 1;
+      ALTER TABLE invites ADD COLUMN used_count INTEGER NOT NULL DEFAULT 0;
+      ALTER TABLE invites ADD COLUMN email TEXT;
+      ALTER TABLE invites ADD COLUMN vault_cap_bytes INTEGER;
+      ALTER TABLE users ADD COLUMN email TEXT;
+      CREATE TABLE vault_caps (
+        vault_name TEXT PRIMARY KEY,
+        -- CHECK (cap_bytes > 0): guard against a 0/negative cap from a direct
+        -- DB write making the Phase-2 enforcement reader treat the vault as
+        -- "0-byte ceiling" (everything over cap) or nonsense. The mint + redeem
+        -- paths already validate positivity; this is the at-rest backstop.
+        cap_bytes INTEGER NOT NULL CHECK (cap_bytes > 0),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {