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

package/src/rate-limit.ts

@@ -1,7 +1,12 @@
 /**
  * Rate-limit primitives for hub auth-surface endpoints.
  *
- * Two limiters today (one floor each — neither is the primary defense):
+ * Each limiter is a floor, not the primary defense. Two are highlighted below
+ * for their contrasting threat models; the rest (`/login/2fa`, vault-token
+ * mint, public signup) are documented at their `export const` definitions.
+ * The public-signup limiter is the deliberate OUTLIER — generous, not tight —
+ * because its endpoint is meant to be redeemed by a room of people sharing one
+ * egress IP (see `SIGNUP_MAX_ATTEMPTS`).
  *
  *   - `/login` (per-IP, hub#187 / hub#188): 5 attempts / 15 min.
  *     Lands as a floor under brute-force after hub#187 collapsed the
@@ -109,6 +114,27 @@ export const VAULT_TOKEN_MINT_WINDOW_MS = 10 * 60 * 1000;
  * minutes is generous for a human and still chokes a stolen-cookie flood.
  */
 export const VAULT_TOKEN_MINT_MAX_ATTEMPTS = 10;
+/**
+ * `POST /account/setup/<token>` (public invite redemption / signup) window
+ * length: 15 minutes — same window as `/login`, but a MUCH larger cap (below)
+ * because the threat model is the opposite. A public multi-use signup link is
+ * meant to be redeemed by a ROOM OF PEOPLE, and a demo room shares ONE NAT'd
+ * egress IP — so a per-IP `/login`-sized cap (5/15min) would 429 the ~6th
+ * legitimate signer. This bucket is deliberately generous so a shared egress
+ * IP comfortably handles a cohort, while still being a floor against an
+ * attacker scripting account creation against an open link (the invite's
+ * own `max_uses` + expiry are the primary bound; this is the abuse floor).
+ * Separate bucket from `/login` so a signup flurry never burns the login
+ * window, and vice-versa.
+ */
+export const SIGNUP_WINDOW_MS = 15 * 60 * 1000;
+/**
+ * `POST /account/setup/<token>` attempts allowed per IP per window. 60 is
+ * comfortably above a single demo room behind one NAT (and well above any
+ * legitimate human's retries) while still capping a scripted-abuse rate to
+ * ~4/min sustained. The 61st attempt within the window is denied.
+ */
+export const SIGNUP_MAX_ATTEMPTS = 60;
 /** Sentinel for the IP-extraction priority chain when nothing parsed. */
 export const UNKNOWN_IP_SENTINEL = "unknown";
 
@@ -246,6 +272,16 @@ export const vaultTokenMintRateLimiter = new RateLimiter(
   VAULT_TOKEN_MINT_WINDOW_MS,
 );
 
+/**
+ * `POST /account/setup/<token>` rate limiter — per-IP, 60 attempts / 15 min
+ * (public invite redemption / signup). DELIBERATELY generous: a public
+ * multi-use signup link is redeemed by a room of people sharing one NAT'd
+ * egress IP, so a `/login`-sized cap would 429 legitimate signers mid-demo.
+ * Separate bucket from `/login` so the two never share a window. The invite's
+ * own `max_uses` + expiry are the primary bound; this is the abuse floor.
+ */
+export const signupRateLimiter = new RateLimiter(SIGNUP_MAX_ATTEMPTS, SIGNUP_WINDOW_MS);
+
 /**
  * Backwards-compat shim for hub#188's call sites: the original
  * top-level `checkAndRecord` was the login limiter. New code should
@@ -266,6 +302,7 @@ export function __resetForTests(): void {
   changePasswordRateLimiter.reset();
   totpRateLimiter.reset();
   vaultTokenMintRateLimiter.reset();
+  signupRateLimiter.reset();
 }
 
 /**

package/src/users.ts

@@ -34,6 +34,15 @@ export interface User {
    * as `users.password_changed INTEGER 0|1` (added in migration v8).
    */
   passwordChanged: boolean;
+  /**
+   * Contactable email captured at signup (migration v15, B2). The username
+   * is the login + URL identity ([a-z0-9_-]); email is the SEPARATE contact
+   * field the operator sees + uses to reach a signup. `null` for every
+   * account created before email capture (wizard admin, env-seeded admin,
+   * pre-named friend invites that didn't collect one). Not unique at the
+   * schema level — see migration v15.
+   */
+  email: string | null;
   /**
    * The vault instance names this user has access to (multi-user Phase 2
    * PR 2 — many-to-many via the `user_vaults` table; design
@@ -81,6 +90,7 @@ interface Row {
   created_at: string;
   updated_at: string;
   password_changed: number;
+  email: string | null;
 }
 
 /**
@@ -126,6 +136,7 @@ function rowToUser(r: Row, assignedVaults: string[]): User {
     createdAt: r.created_at,
     updatedAt: r.updated_at,
     passwordChanged: r.password_changed === 1,
+    email: r.email ?? null,
     assignedVaults,
   };
 }
@@ -232,6 +243,15 @@ export interface CreateUserOpts {
    * each name against `services.json` before passing through.
    */
   assignedVaults?: string[];
+  /**
+   * Contactable email to store on the new account (migration v15, B2).
+   * Default `null` — the wizard/env-seeded admin paths and pre-named
+   * friend invites that don't collect email omit it. The public-signup
+   * redeem path passes the validated email so the operator can reach the
+   * signup. Validation (format) is the caller's responsibility
+   * (`validateEmail`); this just persists what it's given.
+   */
+  email?: string | null;
   /**
    * The `user_vaults.role` to write for every entry in `assignedVaults`.
    * Default `'write'` (= owner; `vaultVerbsForRole('write')` grants the
@@ -268,6 +288,7 @@ export async function createUser(
   const passwordHash = await argonHash(password);
   const stamp = (opts.now?.() ?? new Date()).toISOString();
   const passwordChanged = opts.passwordChanged === true ? 1 : 0;
+  const email = opts.email ?? null;
   // De-dupe + preserve insert order so the returned array matches what
   // `getUserById` would load right after (which sorts by created_at +
   // vault_name). Empty array is "no vaults" — admin posture or a non-
@@ -284,9 +305,9 @@ export async function createUser(
     db.transaction(() => {
       db.prepare(
         `INSERT INTO users
-           (id, username, password_hash, created_at, updated_at, password_changed)
-         VALUES (?, ?, ?, ?, ?, ?)`,
-      ).run(id, username, passwordHash, stamp, stamp, passwordChanged);
+           (id, username, password_hash, created_at, updated_at, password_changed, email)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      ).run(id, username, passwordHash, stamp, stamp, passwordChanged, email);
       if (assignedVaults.length > 0) {
         const role = opts.role ?? "write";
         const insertVault = db.prepare(
@@ -315,6 +336,7 @@ export async function createUser(
     createdAt: stamp,
     updatedAt: stamp,
     passwordChanged: passwordChanged === 1,
+    email,
     assignedVaults,
   };
 }
@@ -749,3 +771,40 @@ export function validatePassword(password: string): ValidatePasswordResult {
   }
   return { valid: true };
 }
+
+/**
+ * Email validation (migration v15, B2 — public-signup email capture).
+ *
+ * Deliberately PERMISSIVE: a single `local@domain.tld` shape check, not a
+ * full RFC 5322 parser. The goal is "the operator can plausibly reach this
+ * person," not RFC compliance — over-strict regexes reject valid real-world
+ * addresses (plus-tags, subdomains, long TLDs) and add no security. We require:
+ *   * exactly one `@`,
+ *   * a non-empty local part with no whitespace,
+ *   * a domain with at least one `.` and a 2+ char final label,
+ *   * no whitespace anywhere, and an overall length ceiling (254, the SMTP
+ *     practical max) so a megabyte string can't be stored.
+ *
+ * The address is lowercased + trimmed before the check and returned in that
+ * canonical form. Same discriminated-union shape as the other validators so
+ * the API/redeem edge can surface the reason.
+ */
+export const EMAIL_MAX_LEN = 254;
+
+// One @, no whitespace, a dotted domain ending in a 2+ char label.
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@.]{2,}$/;
+
+export type ValidateEmailResult =
+  | { valid: true; email: string }
+  | { valid: false; reason: "format" | "length" };
+
+export function validateEmail(raw: string): ValidateEmailResult {
+  const email = raw.trim().toLowerCase();
+  if (email.length === 0 || email.length > EMAIL_MAX_LEN) {
+    return { valid: false, reason: "length" };
+  }
+  if (!EMAIL_REGEX.test(email)) {
+    return { valid: false, reason: "format" };
+  }
+  return { valid: true, email };
+}

package/src/vault-caps.ts

@@ -0,0 +1,109 @@
+/**
+ * Per-vault storage caps (migration v15, DEMO-PREP-2026-06-25 Workstream B,
+ * task B4). A vault provisioned through a capped signup link gets a row in
+ * the `vault_caps` table recording its byte ceiling. This module is the
+ * read/write seam over that table.
+ *
+ * Split of responsibility, on purpose:
+ *   - THIS PR (B1/B2/B4) PERSISTS the cap at provision time — nothing more.
+ *     The public-signup flow stamps a row here when it provisions a vault.
+ *   - A SEPARATE Phase-2 PR (B3, parachute-vault + hub wiring) READS this
+ *     row and ENFORCES it at upload time (4xx over cap). The brief is
+ *     explicit: "at minimum store the cap so the later PR can read + enforce
+ *     it." So `getVaultCapBytes` exists for that future reader; this PR only
+ *     calls `setVaultCap`.
+ *
+ * Keyed by `vault_name` — the same instance-name space used across
+ * services.json / `user_vaults` / `invites.vault_name`. No FK to a vaults
+ * table (there isn't one — vault names resolve through services.json, the
+ * established hub pattern). A vault with NO row is "uncapped," which is what
+ * the Phase-2 reader treats every pre-existing / admin-provisioned vault as.
+ */
+import type { Database } from "bun:sqlite";
+
+/**
+ * Default per-vault cap stamped by the public-signup flow when an invite
+ * carries no explicit cap but the flow wants one: ~1 GB (DEMO-PREP decision
+ * "1 GB per vault, configurable"). 1 GiB = 1024^3 bytes.
+ */
+export const DEFAULT_VAULT_CAP_BYTES = 1024 * 1024 * 1024;
+
+export interface VaultCap {
+  vaultName: string;
+  capBytes: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface Row {
+  vault_name: string;
+  cap_bytes: number;
+  created_at: string;
+  updated_at: string;
+}
+
+function rowToCap(r: Row): VaultCap {
+  return {
+    vaultName: r.vault_name,
+    capBytes: r.cap_bytes,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  };
+}
+
+/**
+ * Persist (or update) a vault's storage cap. Upsert on `vault_name`: a
+ * re-provision (or a future admin edit) overwrites the cap and bumps
+ * `updated_at` while preserving the original `created_at`. `capBytes` must
+ * be a positive integer — callers validate before reaching here; this
+ * floors to an int defensively.
+ */
+export function setVaultCap(
+  db: Database,
+  vaultName: string,
+  capBytes: number,
+  now: Date = new Date(),
+): VaultCap {
+  const stamp = now.toISOString();
+  const bytes = Math.floor(capBytes);
+  db.prepare(
+    `INSERT INTO vault_caps (vault_name, cap_bytes, created_at, updated_at)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(vault_name) DO UPDATE SET
+       cap_bytes = excluded.cap_bytes,
+       updated_at = excluded.updated_at`,
+  ).run(vaultName, bytes, stamp, stamp);
+  // Re-read so the returned createdAt reflects the preserved original on an
+  // update (excluded.created_at is NOT written on conflict).
+  const cap = getVaultCap(db, vaultName);
+  // The row was just written, so it always exists; the non-null assertion
+  // is safe but we fall back defensively rather than throw.
+  return cap ?? { vaultName, capBytes: bytes, createdAt: stamp, updatedAt: stamp };
+}
+
+/** Read a vault's cap, or `null` when the vault has no cap row (uncapped). */
+export function getVaultCap(db: Database, vaultName: string): VaultCap | null {
+  const row = db
+    .query<Row, [string]>("SELECT * FROM vault_caps WHERE vault_name = ?")
+    .get(vaultName);
+  return row ? rowToCap(row) : null;
+}
+
+/**
+ * Convenience for the Phase-2 enforcement reader: the cap in bytes, or
+ * `null` (uncapped) when no row exists. Thin wrapper over {@link getVaultCap}.
+ */
+export function getVaultCapBytes(db: Database, vaultName: string): number | null {
+  return getVaultCap(db, vaultName)?.capBytes ?? null;
+}
+
+/**
+ * Vault-delete cascade hook (parity with the other per-vault identity
+ * artifacts swept in admin-vaults.ts `handleDeleteVault`): drop the cap row
+ * when its vault is deleted so a re-created same-name vault doesn't inherit a
+ * stale cap. Exact `=` match, no pattern. Returns rows deleted (0 or 1).
+ */
+export function removeVaultCap(db: Database, vaultName: string): number {
+  const res = db.prepare("DELETE FROM vault_caps WHERE vault_name = ?").run(vaultName);
+  return Number(res.changes);
+}