@openparachute/hub 0.5.13-rc.4 → 0.5.13-rc.40

package/README.md

@@ -2,18 +2,39 @@
 
 `@openparachute/hub` — the local hub for the [Parachute](https://parachute.computer) ecosystem. The `parachute` binary is one of its surfaces.
 
-The hub coordinates the modules running on your machine: it installs them, runs them as background processes, exposes them over Tailscale, serves the discovery document at `/.well-known/parachute.json`, and (soon) issues OAuth tokens. Each module (vault, notes, scribe, channel, …) stays a standalone package; the hub stitches them together.
+The hub coordinates the modules running on your machine: it installs them, runs them as background processes, exposes them over Tailscale, serves the discovery document at `/.well-known/parachute.json`, and (soon) issues OAuth tokens. Each module (vault, app, scribe, …) stays a standalone package; the hub stitches them together.
 
 > Previously published as `@openparachute/cli`. Renamed 2026-04-26 to better reflect the role — see [parachute-patterns/hub-as-issuer](https://github.com/ParachuteComputer/parachute-patterns/blob/main/patterns/hub-as-issuer.md). The `parachute` binary name is unchanged.
 
 ## Install
 
+### Local (Bun)
+
 ```sh
 bun add -g @openparachute/hub
 ```
 
 Prereqs: [Bun](https://bun.sh) 1.3.0 or later. `parachute expose` also requires [Tailscale](https://tailscale.com/download) **1.82 or newer** (installed + `tailscale up` run once); the `expose` path is under active polish for launch, so expect rough edges.
 
+### Hosted (Render)
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/ParachuteComputer/parachute-hub)
+
+One-click Render deploy via the `render.yaml` Blueprint in this repo. Provisions a $7/mo Starter service + 1 GiB persistent disk + auto-deploys from `main`. Comes pre-configured with `PARACHUTE_INSTALL_CHANNEL=latest` so modules you install via the admin SPA (vault, app, scribe, runner) pull stable releases by default.
+
+**Want pre-release / rc modules?** Set `PARACHUTE_INSTALL_CHANNEL=rc` in your Render dashboard env vars (useful for dev/testing against the rc release line).
+
+After deploy completes:
+
+1. Open Render Logs → search for `parachute-bootstrap-` to find your one-time admin setup token (printed in a prominent banner on first boot).
+2. Visit your Render service URL's `/admin/setup` → paste the token → create your admin account.
+3. Set custom domain (optional) → set `PARACHUTE_HUB_ORIGIN` env to match.
+4. Install modules via the admin SPA at `/admin/modules` (or via the wizard).
+
+Operators who want env-var-driven seeding (CI, scripted deploys) can still set `PARACHUTE_INITIAL_ADMIN_USERNAME` + `PARACHUTE_INITIAL_ADMIN_PASSWORD` manually in the Render dashboard — hub honors them when present.
+
+Render's docs on Blueprints: <https://render.com/docs/blueprint-spec>
+
 ## First 5 minutes
 
 ```sh
@@ -160,16 +181,19 @@ Parachute services reserve a block of loopback ports in the canonical range **19
 | 1939 | parachute-hub (internal proxy + static) |
 | 1940 | parachute-vault    |
 | 1941 | parachute-channel  |
-| 1942 | parachute-notes    |
+| 1942 | parachute-notes *(deprecating — see [notes#154](https://github.com/ParachuteComputer/parachute-notes/issues/154); folds into parachute-app at 1946)* |
 | 1943 | parachute-scribe   |
-| 1944–1949 | *unassigned (CLI fallback range)* |
+| 1944 | *parachute-agent (retired 2026-05-20; slot held — see [`parachute-agent/DEPRECATED.md`](https://github.com/ParachuteComputer/parachute-agent/blob/main/DEPRECATED.md))* |
+| 1945 | parachute-runner *(shipped; exploration-tier, not committed-core)* |
+| 1946 | parachute-app *(committed core; UI host, ships Notes as canonical first app)* |
+| 1947–1949 | *unassigned (CLI fallback range)* |
 
 The hub pins 1939 — no fallback. If something else is on 1939 when you run `parachute expose`, the command fails with a pointer to `lsof -iTCP:1939` rather than walking up into another service's slot.
 
 **The CLI is the port authority.** `parachute install <svc>` picks the port at install time and writes `PORT=<port>` into `~/.parachute/<svc>/.env`; lifecycle.start merges that .env into the spawn env so the next daemon boot binds the port the CLI assigned. The algorithm:
 
 1. Prefer the canonical slot (e.g. vault → 1940).
-2. On collision, walk the unassigned range (1944–1949).
+2. On collision, walk the unassigned range (1947–1949).
 3. Range exhausted: assign past 1949 with a warning.
 
 Idempotent: an existing `PORT=` in `~/.parachute/<svc>/.env` wins, so re-installs and operator-edited ports survive across upgrades. Services keep their compiled-in fallbacks (vault → 1940 etc.) so a stand-alone `bun run` still works without a CLI-managed .env.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.13-rc.4",
+  "version": "0.5.13-rc.40",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/admin-clients.test.ts

@@ -115,6 +115,32 @@ describe("handleGetClient", () => {
     expect(body.redirect_uris).toEqual(["https://app.example/cb"]);
     expect(body.scopes).toEqual(["vault:work:read"]);
     expect(typeof body.registered_at).toBe("string");
+    // hub#312 — same_hub surfaced for future SPA badging. Default false
+    // when the test registers via the helper (no operator-auth path).
+    expect(body.same_hub).toBe(false);
+  });
+
+  test("same_hub=true client surfaces same_hub: true in the response (hub#312)", async () => {
+    // The DCR path stamps same_hub=true on operator-authenticated
+    // registrations. Pin that the admin view exposes that flag so future
+    // SPA changes (per-client same-hub badge) can read it directly from
+    // /api/oauth/clients/<id>.
+    const { bearer } = await makeOperatorBearer();
+    const r = registerClient(harness.db, {
+      redirectUris: ["https://app.example/cb"],
+      scopes: ["vault:work:read"],
+      status: "approved",
+      sameHub: true,
+      clientName: "SameHubApp",
+    });
+    const id = r.client.clientId;
+    const res = await handleGetClient(getReq(id, bearer), id, {
+      db: harness.db,
+      issuer: ISSUER,
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.same_hub).toBe(true);
   });
 
   test("returns the row's status after approval (so the SPA can short-circuit re-approve)", async () => {
@@ -272,4 +298,165 @@ describe("handleApproveClient", () => {
     const res = await handleApproveClient(req, id, { db: harness.db, issuer: ISSUER });
     expect(res.status).toBe(405);
   });
+
+  // Workstream D — OAuth resume via `return_to`. The SPA approve page
+  // can pass a hub-relative authorize URL as JSON body; the response
+  // echoes it as `redirect_to` so the SPA can navigate the browser there
+  // and resume the parked OAuth flow. The pre-D no-body shape continues
+  // to work (no `redirect_to` field, share-link dead-end case).
+  describe("workstream D — return_to / redirect_to", () => {
+    function jsonApproveReq(clientId: string, bearer: string, body: unknown): Request {
+      return new Request(`${ISSUER}/api/oauth/clients/${encodeURIComponent(clientId)}/approve`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+      });
+    }
+
+    test("echoes a same-origin /oauth/authorize?... return_to as redirect_to", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const returnTo =
+        "/oauth/authorize?client_id=" +
+        encodeURIComponent(id) +
+        "&response_type=code&scope=vault%3Awork%3Aread";
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: returnTo }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.redirect_to).toBe(returnTo);
+      expect(body.status).toBe("approved");
+      expect(getClient(harness.db, id)?.status).toBe("approved");
+    });
+
+    test("omits redirect_to entirely when return_to is missing (share-link case preserved)", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      // No body — the pre-D shape. The endpoint must continue to work.
+      const res = await handleApproveClient(approveReq(id, bearer), id, {
+        db: harness.db,
+        issuer: ISSUER,
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+      expect(body.status).toBe("approved");
+    });
+
+    test("drops an off-origin return_to (scheme-relative) silently, still approves", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: "//evil.example/oauth/authorize?foo=1" }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      // No redirect_to — server refuses to echo a bad value. The client
+      // is still approved (we don't fail an otherwise-legitimate approve
+      // over a malformed return_to).
+      expect(body).not.toHaveProperty("redirect_to");
+      expect(getClient(harness.db, id)?.status).toBe("approved");
+    });
+
+    test("drops a non-authorize return_to (off-path) silently", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: "/admin/vaults" }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      // `/admin/vaults` is same-origin but isn't a `/oauth/authorize?...`
+      // URL — the server-side gate is "authorize URL only" so the SPA
+      // can't be used as a redirect gadget for arbitrary in-SPA navigation.
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("drops absolute URL return_to silently", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, {
+          return_to: "https://evil.example/oauth/authorize?foo=1",
+        }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("non-JSON body is treated as 'no return_to' (no parser explosion)", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      // text/plain body — pre-D / unknown clients send anything. The
+      // endpoint must NOT throw on parse and must NOT echo a redirect_to.
+      const req = new Request(`${ISSUER}/api/oauth/clients/${id}/approve`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          "content-type": "text/plain",
+        },
+        body: "garbage",
+      });
+      const res = await handleApproveClient(req, id, {
+        db: harness.db,
+        issuer: ISSUER,
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("malformed JSON body is treated as 'no return_to'", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const req = new Request(`${ISSUER}/api/oauth/clients/${id}/approve`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          "content-type": "application/json",
+        },
+        body: "{not json",
+      });
+      const res = await handleApproveClient(req, id, {
+        db: harness.db,
+        issuer: ISSUER,
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("re-approve with return_to echoes redirect_to (idempotent path)", async () => {
+      // The OAuth resume flow can legitimately race: operator opens the
+      // approve link, an automated path approves the same client, then
+      // operator clicks. We still want the redirect to fire so the
+      // operator's flow resumes — not dead-end on already_approved.
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      approveClient(harness.db, id);
+      const returnTo = `/oauth/authorize?client_id=${encodeURIComponent(id)}&response_type=code&scope=vault%3Awork%3Aread`;
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: returnTo }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.already_approved).toBe(true);
+      expect(body.redirect_to).toBe(returnTo);
+    });
+  });
 });

package/src/__tests__/api-account.test.ts

@@ -29,6 +29,11 @@ import {
 } from "../api-account.ts";
 import { CSRF_COOKIE_NAME, CSRF_FIELD_NAME } from "../csrf.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  CHANGE_PASSWORD_MAX_ATTEMPTS,
+  CHANGE_PASSWORD_WINDOW_MS,
+  changePasswordRateLimiter,
+} from "../rate-limit.ts";
 import { SESSION_TTL_MS, buildSessionCookie, createSession } from "../sessions.ts";
 import { createUser, getUserById, verifyPassword } from "../users.ts";
 
@@ -84,6 +89,13 @@ function formBody(values: Record<string, string>): {
 let harness: Harness;
 beforeEach(() => {
   harness = makeHarness();
+  // Per-test rate-limit reset — change-password tests share the
+  // singleton `changePasswordRateLimiter`, and a test that exhausts a
+  // user-id bucket would 429-cascade into the next test if the user-id
+  // happened to collide. Per-harness DB → fresh user-ids, so in practice
+  // there's no collision, but the explicit reset matches `admin-handlers`
+  // discipline and pins the contract.
+  changePasswordRateLimiter.reset();
 });
 afterEach(() => {
   harness.cleanup();
@@ -438,6 +450,161 @@ describe("POST /account/change-password", () => {
     const setCookie = res.headers.get("set-cookie") ?? "";
     expect(setCookie).not.toContain("Max-Age=0");
   });
+
+  // hub#282 — per-user rate-limit on /account/change-password.
+  // CHANGE_PASSWORD_MAX_ATTEMPTS attempts per CHANGE_PASSWORD_WINDOW_MS;
+  // (CHANGE_PASSWORD_MAX_ATTEMPTS+1)th attempt within the window is 429.
+  test("rapid wrong-current_password attempts exhaust the bucket and 429 with Retry-After", async () => {
+    const { cookie } = await sessionCookieFor(harness.db, "newbie", "correct-pw", {
+      passwordChanged: false,
+    });
+    const buildReq = () => {
+      const { body, headers } = formBody({
+        [CSRF_FIELD_NAME]: TEST_CSRF,
+        current_password: "this-is-wrong",
+        new_password: "long-enough-passphrase",
+        new_password_confirm: "long-enough-passphrase",
+      });
+      return new Request("http://hub.test/account/change-password", {
+        method: "POST",
+        headers: { ...headers, cookie },
+        body,
+      });
+    };
+    // First N attempts: wrong current → 401 each (admitted by rate limiter,
+    // failed by argon2id verify).
+    for (let i = 0; i < CHANGE_PASSWORD_MAX_ATTEMPTS; i++) {
+      const r = await handleAccountChangePasswordPost(buildReq(), { db: harness.db });
+      expect(r.status).toBe(401);
+    }
+    // (N+1)th attempt: rate-limit fires before argon2id → 429 + Retry-After.
+    const denied = await handleAccountChangePasswordPost(buildReq(), { db: harness.db });
+    expect(denied.status).toBe(429);
+    const retryAfter = denied.headers.get("retry-after");
+    expect(retryAfter).not.toBeNull();
+    const seconds = Number(retryAfter);
+    expect(seconds).toBeGreaterThan(0);
+    // Window is CHANGE_PASSWORD_WINDOW_MS, so retry-after sits in (0, window].
+    expect(seconds).toBeLessThanOrEqual(CHANGE_PASSWORD_WINDOW_MS / 1000);
+    // Body should re-render the form with the rate-limit message.
+    const html = await denied.text();
+    expect(html).toContain("Too many password-change attempts");
+  });
+
+  test("rate-limit is per-user: two users have independent buckets", async () => {
+    const userA = await sessionCookieFor(harness.db, "user-a", "pw-a", {
+      passwordChanged: false,
+    });
+    const userB = await sessionCookieFor(harness.db, "user-b", "pw-b", {
+      passwordChanged: false,
+      allowMulti: true,
+    });
+    const buildReq = (cookie: string) => {
+      const { body, headers } = formBody({
+        [CSRF_FIELD_NAME]: TEST_CSRF,
+        current_password: "wrong",
+        new_password: "long-enough-passphrase",
+        new_password_confirm: "long-enough-passphrase",
+      });
+      return new Request("http://hub.test/account/change-password", {
+        method: "POST",
+        headers: { ...headers, cookie },
+        body,
+      });
+    };
+    // Exhaust user-a's bucket.
+    for (let i = 0; i < CHANGE_PASSWORD_MAX_ATTEMPTS; i++) {
+      await handleAccountChangePasswordPost(buildReq(userA.cookie), { db: harness.db });
+    }
+    const aDenied = await handleAccountChangePasswordPost(buildReq(userA.cookie), {
+      db: harness.db,
+    });
+    expect(aDenied.status).toBe(429);
+    // user-b's bucket is untouched — first attempt should be admitted
+    // (and reject for wrong current → 401, not 429).
+    const bAttempt = await handleAccountChangePasswordPost(buildReq(userB.cookie), {
+      db: harness.db,
+    });
+    expect(bAttempt.status).toBe(401);
+  });
+
+  test("rate-limit gate fires before argon2id verify (denied request is fast)", async () => {
+    // Pin the "fires before verifyPassword" property with an elapsed-time
+    // floor on the 429 response — argon2id verify would push elapsed
+    // into the hundreds of ms; the 429 path skips it.
+    const { cookie } = await sessionCookieFor(harness.db, "newbie", "correct-pw", {
+      passwordChanged: false,
+    });
+    const buildReq = () => {
+      const { body, headers } = formBody({
+        [CSRF_FIELD_NAME]: TEST_CSRF,
+        current_password: "wrong",
+        new_password: "long-enough-passphrase",
+        new_password_confirm: "long-enough-passphrase",
+      });
+      return new Request("http://hub.test/account/change-password", {
+        method: "POST",
+        headers: { ...headers, cookie },
+        body,
+      });
+    };
+    // Fill the bucket.
+    for (let i = 0; i < CHANGE_PASSWORD_MAX_ATTEMPTS; i++) {
+      await handleAccountChangePasswordPost(buildReq(), { db: harness.db });
+    }
+    // The (N+1)th attempt should 429-and-return without touching argon2id.
+    const t0 = Date.now();
+    const denied = await handleAccountChangePasswordPost(buildReq(), { db: harness.db });
+    const elapsed = Date.now() - t0;
+    expect(denied.status).toBe(429);
+    // 200ms is enough headroom even on a noisy runner; an argon2id verify
+    // would push elapsed into the hundreds of ms.
+    expect(elapsed).toBeLessThan(200);
+  });
+
+  test("CSRF failure does NOT burn a rate-limit slot", async () => {
+    // Gate-order invariant: rate-limit fires *after* CSRF, so a junk
+    // cross-site POST (which would never have a valid CSRF token) doesn't
+    // burn a bucket slot for the victim's session. Pin by sending
+    // (max+1) CSRF-broken requests and then confirming a fresh, valid
+    // attempt is admitted (would-be 401 for wrong current_password, not
+    // 429).
+    const { cookie } = await sessionCookieFor(harness.db, "newbie", "correct-pw", {
+      passwordChanged: false,
+    });
+    const csrfBroken = () => {
+      const { body, headers } = formBody({
+        [CSRF_FIELD_NAME]: "wrong-token",
+        current_password: "wrong",
+        new_password: "long-enough-passphrase",
+        new_password_confirm: "long-enough-passphrase",
+      });
+      return new Request("http://hub.test/account/change-password", {
+        method: "POST",
+        headers: { ...headers, cookie },
+        body,
+      });
+    };
+    for (let i = 0; i < CHANGE_PASSWORD_MAX_ATTEMPTS + 2; i++) {
+      const r = await handleAccountChangePasswordPost(csrfBroken(), { db: harness.db });
+      expect(r.status).toBe(400);
+    }
+    // Now send a CSRF-valid attempt — should NOT be 429 (CSRF-broken
+    // attempts never reached the rate limiter).
+    const { body, headers } = formBody({
+      [CSRF_FIELD_NAME]: TEST_CSRF,
+      current_password: "wrong",
+      new_password: "long-enough-passphrase",
+      new_password_confirm: "long-enough-passphrase",
+    });
+    const valid = new Request("http://hub.test/account/change-password", {
+      method: "POST",
+      headers: { ...headers, cookie },
+      body,
+    });
+    const res = await handleAccountChangePasswordPost(valid, { db: harness.db });
+    expect(res.status).toBe(401);
+  });
 });
 
 describe("markPasswordChanged", () => {