feat(node): invitation links — a code bound to no account until redeemed

New invite kind "link": member of one group, once, never operator, not
spendable by an active member, capped at 20 per group, cancellable by
handle. Signed ops invite_link_create / invite_cancel, loopback routes,
and the known-device join path now accepts a link code. Adds the plan,
docs/invite-links.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 361 insertions, 0 deletions

diff --git a/docs/invite-links.md b/docs/invite-links.md
new file mode 100644
index 0000000..fc8cca8
--- /dev/null
+++ b/docs/invite-links.md
@@ -0,0 +1,361 @@
+# Invitation links — plan
+
+> **Status: plan, partly built.** Written 2026-09-23 against MNP 3.3 / packages 0.15.0.
+> Built so far (§7): the remembered e-mail choice (step 1), the signed challenge
+> (step 2, MNP 3.4) and the node half of links (step 3). The rest is not true of
+> the code yet. When it lands, the design statements move
+> into `MESHBAY_DESIGN.md` (§3.4, §7.3, §13) and `MESHBAY_NODE_PROTOCOL.md` (§6, §8,
+> §10.4), and this file keeps only what a synthesis cannot carry, as `transfers-v1.md`
+> does.
+
+## 1. What is asked
+
+An operator sends somebody **one link**. Whoever receives it can open it before
+having an account, register, and land in the group with the invitation code entered
+for them. It must work across several situations (§6), without regressing anything
+and without weakening the admission model of §3.4.
+
+Decisions taken with the project owner before writing this:
+
+| Question | Decision |
+|---|---|
+| Binding | **Bearer code at the node, bound to a verified e-mail address at the hub** |
+| Mail sent by the hub | **Offered on both invitation boxes**, as a checkbox under the text field, **checked by default and remembered per account** (§3.8). Checked, the hub sees the code or the link, which is a documented trade-off rather than a defect (§5) |
+| Mail quota for links | **10 link mails per inviting account per day**, on top of the existing bounds. Ordinary invitations keep their current limits |
+| CLI | **Yes** — `meshbay-node member invite --link`, alongside the interface |
+| Desktop client | **Paste the link into the application**; no OS protocol handler |
+
+## 2. Why it cannot just be "put the code in a URL"
+
+Three facts about today's model decide the shape:
+
+1. **A code is bound to a `user_id` when it is created** (`roster.create_invite`,
+   `consume_invite` checks `invite["user_id"] != user_id`). Somebody with no account
+   has no `user_id`, so no code can exist for them.
+2. **Reaching the node needs hub membership.** Signaling is refused unless caller and
+   node share an active group (H6, AV24), and `/v1/groups/{id}/nodes` answers members
+   only (AV25). Today the invitation registers the invitee's membership when the code
+   is created — again, by account.
+3. **The code is sent in the pre-proof window, to a node that has not proved who it
+   is** (`MESHBAY_NODE_PROTOCOL.md` §6.5). `node_pk` in the challenge is unverified
+   until the ack, and `join_request` goes before the ack. Whoever answers signaling
+   receives the code in the clear (inside DTLS).
+   Today that costs little, because the code only works for one account. **A bearer code
+   changes that**, and so does a group with two hosting nodes: the code typed today
+   goes to whichever node answers first, which may be **another operator's machine**.
+
+So a link needs two secrets with two jobs, and the node has to authenticate itself
+before the code goes out.
+
+## 3. Design
+
+### 3.1 Two halves, as everywhere else
+
+| Half | Secret | Who checks it | What it grants |
+|---|---|---|---|
+| **Hub ticket** | 128-bit random `t`, stored as `sha256(t)` | the hub, **plus** the redeeming account's verified e-mail blind index must equal the one the inviter named | hub membership = the right to *reach* the node. Nothing about keys (§7.1) |
+| **Node code** | the existing 40-bit code, stored as `sha256(code)` | the issuing node only | pinning + the group key, exactly as today |
+
+The hub never receives the code, and the node never learns the e-mail address. A hub
+membership obtained without the code gets `not_authorized_for_group`, as it does today.
+
+### 3.2 The link
+
+```
+https://<hub>/#/invite?v=1&g=<group_id>&t=<ticket>&n=<node_pk_b64url>&c=<CODE>
+```
+
+- **Everything after `#` is never sent in an HTTP request**. It does not reach Caddy
+  logs, hub logs, `Referer`, or the service worker. The SPA reads it, stores it
+  (§3.6), and **immediately rewrites the address to `#/invite`** with
+  `history.replaceState`.
+- `g` lets the client check that the group the hub answers is the group the inviter
+  meant.
+- `n` is **the issuing node's public key**. The code exists on that node only, so the
+  client sends it to that node and to no other (fixes fact 3, and the multi-host leak).
+- No e-mail address in the link.
+
+### 3.3 The node authenticates before the code leaves (MNP 3.4, additive)
+
+`handshake_challenge` gains `sig = Ed25519(sk_node, C)` where
+
+```
+C = "meshbay:mnp:challenge:v1" || LP(group_id) || LP(nonce_c) || LP(nonce_s) || LP(binding)
+```
+
+`binding` is the same channel binding as §6.4, already known when the challenge is
+sent (both DTLS fingerprints are in the SDP). `nonce_c` makes it fresh, and `binding`
+means it cannot be relayed.
+
+Client rule, **by the peer's answer and not by version** (§5.6): when the client holds
+a link code for this group, it sends `join_request` only if the challenge has a `sig`
+that verifies under `n` from the link. Otherwise it refuses with a stated reason:
+"this invitation was issued by another machine" or "this node is too old for
+invitation links". Nothing changes for code typed by hand or for recognised
+devices. An old node cannot have issued a link code, so refusing it loses nothing.
+
+The code goes in `meshbay_common/handshake.py` (one implementation, both transports:
+**QUIC must stay at parity**) and in `transport.js`. A parity test covers the transcript
+in Python and JS, the same way `test_bundle_kdf_parity.py` covers the KDF.
+
+**What it buys, per the §2 convention:** for a link join, an active hub that hijacks
+signaling no longer receives the code on a **native** client. **Browser: unchanged**
+— T3, the hub serves the page that reads the fragment. That is the same exposure as
+today's typed code, and no worse.
+
+### 3.4 Node: link invitations in the roster
+
+- `invites` gains `kind TEXT NOT NULL DEFAULT 'account'` (values `account` | `link`)
+  and `invite_id TEXT` (random, non-secret handle for cancelling). The migration is an
+  `ALTER TABLE ADD COLUMN`, as `username` was.
+  **`user_id = ''` never means "anyone" on its own** (the AV1 lesson: an empty value
+  must not mean "unspecified"). Only `kind = 'link'` makes a row bearer, and every
+  query that matches by `user_id` also filters on `kind`: `drop_invites`,
+  `consume_invite`, the pending-invite check in `_do_join_request`, and `member list`.
+- `consume_invite` for a `link` row requires all of:
+  `role == member`, `group_id != ''`, `group_id == session group`, not used, not
+  expired, **caller has no member row in that group**. An existing member cannot spend
+  someone else's link. The call then sets `used_at` **and** `user_id` in one `UPDATE
+  … WHERE used_at IS NULL`, so single use still holds under a race.
+  A link row can **never** carry `role = operator`, and `pair_operator` is untouched.
+- `_do_join_request`: the "device known" branch also accepts a link code. The case is
+  a person already pinned on this node through another group, which is common. Today
+  that branch only looks for bound invites.
+- New signed op **`invite_link_create`** (`adminop.py`), subject `link:<group_id>`,
+  so the transcript names the outcome (H5). A new op instead of overloading
+  `invite_create`, whose subject is an invitee id. **`invite_cancel`** takes subject
+  `<invite_id>`. Both are operator-only, like `invite_create`, and both are audited.
+- `ops.create_link_invite` / `ops.cancel_invite`: one implementation behind MNP,
+  loopback and CLI (§5.4).
+- Ceiling (AV lens): **20 unredeemed link invitations per group**. The refusal says
+  so.
+- Audit: `invite_link_create`, `invite_cancel`, and `join_pinned … via=link`.
+
+### 3.5 Hub: tickets
+
+New table `group_invite_links`: `id`, `group_id` → groups, `created_by` → users,
+`ticket_hash` (unique), `email_hash` (the existing HMAC blind index), `email_masked`
+(`al***@ex***.com`, for the owner's list), `node_invite_id`, `created_at`,
+`expires_at`, `redeemed_by`, `redeemed_at`. Alembic migration with `sa.func.now()`.
+`test_migrations_reach_head` has to pass. `purge.py` finds it from the schema; a test
+confirms it on group deletion **and** on account deletion.
+
+| Route | Auth | Rule |
+|---|---|---|
+| `POST /v1/groups/{id}/invite-links` `{email, expires_at, node_invite_id}` | `get_current_user` + `group.admin_id == current_user.id` (the node token for the CLI, same guard as `add_group_member`) | group active, not `open`; ≤ 20 outstanding per group; rate-limited; expiry clamped to ≤ 30 days; **same answer whether or not an account holds that address** (M1). Returns `t` once |
+| `GET /v1/groups/{id}/invite-links` | owner | outstanding and redeemed links, masked e-mail |
+| `DELETE /v1/groups/{id}/invite-links/{link_id}` | owner | deletes the ticket |
+| `POST /v1/invite-links/preview` `{ticket}` | `require_user_scope` | if valid **and** `caller.email_hash == row.email_hash` **and** caller active → `{group_id, group_name, inviter}`. Wrong account → `403 invite_other_account`, which names no address. Otherwise one uniform `404` |
+| `POST /v1/invite-links/redeem` `{ticket}` | `require_user_scope` | same checks → `GroupMember` row + `redeemed_by`. **Idempotent for the same account** (a second tab, or a reload). Refused for anyone else once redeemed. One notification to the owner: "X joined through your link" |
+
+No route is added to the unauthenticated surface. `POST …/invite-links` takes
+`send_email: bool`; mail is §3.8.
+
+Binding is checked **at redemption**, against the account's current verified address.
+An address change already requires verifying the new address (`users.py`), so it
+cannot be spoofed.
+
+### 3.6 Client
+
+- **`#/invite` page** (`invite-page.js`). It parses the fragment, validates the
+  shape of each field, stores `{g, t, n, c, exp}` in **`sessionStorage`**, then
+  calls `replaceState`. Why `sessionStorage`: it survives a reload in the middle of
+  registration and dies with the tab. Why not `localStorage`: that is shared across
+  tabs and outlives them. The page never renders the code.
+- **Not signed in** → "You have been invited to a group on this hub", then *Create an
+  account* / *Sign in*. It shows no group name, since that would be information for an
+  unauthenticated reader.
+- **After registration** (form → recovery key → e-mail code → done → sign in) and
+  **after any sign-in**: if an invitation is pending, `LoginPage` goes to `#/invite`
+  instead of `/`.
+- **Signed in** → `preview`, then an **explicit confirmation**: "*inviter* invites you
+  to *group* — Join / Ignore". The code is entered for them; the click stays theirs,
+  because otherwise a link becomes a way to add anyone to any group without asking.
+  Then `redeem`, then check `group_id == g`, then `#/group/<g>`.
+- **`GroupPage`**: a pending invitation for this group:
+  (1) narrows the candidate nodes to the one whose key is `n`;
+  (2) passes the code to `connect` as `pendingJoinCode` does today;
+  (3) is cleared on `ok`, `code_invalid`, expiry, sign-out and "Ignore". It is **kept**
+  on a network failure, node offline, `unknown_device` (device linking comes first)
+  or a passphrase prompt.
+- **Members tab** (paired operator). A second box, **"Invite by link"**, goes directly
+  under the existing **"Invite member"** box, with the same layout: an e-mail field and
+  a *Create link* button. Under the field sits the same checkbox as in the box above
+  (§3.8). The result shows the link with *Copy* (and `navigator.share` where it
+  exists).
+  ```
+  INVITE MEMBER
+  [ username               ] [Invite]
+  ☑ Send the invitation by e-mail (may land in spam)
+
+  INVITE BY LINK
+  [ e-mail address         ] [Create link]
+  ☑ Send the invitation by e-mail (may land in spam)
+     → link + [Copy]
+     Pending links: al***@ex***.com · expires 30/09 · [Cancel]
+  ``` It also lists outstanding links, with a cancel action that does
+  both halves, **node first, then hub, and reports a refusal without skipping the
+  other half** (the member-removal lesson).
+- **Desktop client / paste**: a "Join with an invitation link" field on the home page
+  (browser and application). It accepts the whole link and **refuses a link whose
+  origin is not `platform.hubBase()`**, so a ticket is never sent to another hub.
+- `test_hub_address_seam.py`, `test_no_native_dialogs_in_the_spa.py`,
+  `test_hook_ordering.py`, `test_spa_ordering.py` and `test_locales.py` all apply.
+  New strings go in **all ten** catalogues.
+
+### 3.7 CLI
+
+```
+meshbay-node member invite --link --email alice@example.org --group "Family Photos"
+```
+
+This runs `ops.create_link_invite` and then the hub ticket through the node token
+(hub first, as `create_invite` does, so a failure leaves no orphaned code). It prints
+the link and writes it to `invite-link` beside `invite-code` (`write_code_file`).
+`member list` shows unredeemed links as such, not as a truncated empty `user_id`.
+`test_cli_dispatch.py` covers the new flag.
+
+### 3.8 Mail sent by the hub
+
+**The checkbox.** It sits under the text field in both boxes, reads *"Send the invitation
+by e-mail (may land in spam)"*, and is **checked by default**. It is **remembered per
+account** through `/v1/users/me/preferences`, under one key, `invite_email`, which
+both boxes share. That key is added to `ALLOWED_PREF_KEYS`, a closed namespace (AV11).
+It is remembered server-side rather than in `localStorage` so that it follows the
+account from browser to desktop client. It is read once when the Members tab opens,
+and written when it is toggled.
+
+**Invite member (existing).** Unchecked → `invite-notify` is not called, so the hub
+never sees the code. Checked → today's behaviour, **unchanged**: same endpoint, same
+20/hour per IP limit, same `invite` purpose.
+
+**Invite by link (new).** Checked → the hub mails the link to the address the inviter
+typed, which is the address the ticket is bound to. There is therefore no second
+address, and none that the inviter could choose separately. The mail's content is
+fixed: the subject comes from the group row and the inviter's username, and nothing
+in the text comes from the request (AV8). The link is built by the client, then
+**validated by the hub before it is sent**: it must have the hub's own origin, the
+exact shape of §3.2, and the same `g`/`t` as the ticket just created. A hub-signed
+mail must not become a way to send an arbitrary URL.
+
+**Bounds**, all enforced through `mail.reserve`, with none of the existing ones
+changed:
+
+| Bound | Value | Why |
+|---|---|---|
+| Per inviting account | **10 link mails / day** (`mail_quota` row `invite_link:<user_id>`, one-day window), clamped setting `mail.invite_link_daily_cap` beside the others | the recipient has **no account**: this is the only mail door besides registration that reaches an address the hub has no relationship with, and registration is open. A per-IP bound limits a caller, not the number of strangers mailed (AV10) |
+| Per recipient | existing: 10/day, 120 s cooldown | unchanged |
+| Instance | existing: hourly budget | the new purpose **`invite_link`** is added to the closed list (AV13) and **is not** a recovery purpose, so it cannot spend the share reserved for passphrase resets |
+| Creating a ticket | existing ≤ 20 outstanding per group | a ticket with no mail costs nothing to anyone else |
+
+A refused mail does **not** cancel the link: the answer says `email_status: refused`
+and the interface says "share the link yourself". The link is already shown.
+
+## 4. What this changes in the security model — to write in `MESHBAY_DESIGN.md`
+
+| Claim | Before | With a link |
+|---|---|---|
+| The code never reaches the hub | ✅ if the box is **unchecked**. Checked: the hub receives it (`invite-notify`) | ✅ if the box is **unchecked** (fragment only; browser: T3). Checked: the hub writes the mail and so holds the whole link |
+| A leaked code is useless to another account | ✅ bound to the account | ⚠️ **the node code is bearer**. What restricts *who reaches the node* is the hub ticket bound to a verified address. Leaking the link to a messaging provider is therefore not enough: you also need the mailbox |
+| Active hub | can already be the invitee (forged token + code if it sees it) | **unchanged**. It can create an account with the address it verifies itself, redeem, forge. Honest wording: the e-mail binding holds against **third parties**, not against the hub |
+| Signaling hijack at first contact | receives the code | **closed for a link on a native client** (§3.3). Browser: T3 |
+| Multi-host group | the code may go to another operator's node | **closed for a link** (`n`) |
+| Hub metadata | who is a member of what | **+ "owner X invited address Y into group Z"** (blind index + masked form) until expiry/deletion. The creation request carries the address in the clear over TLS to the hub |
+
+Residual risks, stated rather than hidden:
+
+- Addresses are compared **case-insensitively and nothing more**. `+alias` and dots
+  are not folded, so the person has to register with exactly the address that was
+  given. The error message says so.
+- An account created before e-mail verification existed may hold an address nobody
+  verified. An account whose `status` is not `active` is refused.
+- The browser's local history may have recorded the full URL before `replaceState`.
+  That exposes it to a local attacker only, and the code is single-use and short-lived.
+- A **group member** who obtains the link cannot spend it (§3.4, "caller has no
+  member row"). An account that received hub membership some other way and has not
+  been pinned could. That is narrow, audited, and visible to the owner, who sees who
+  redeemed.
+
+New labels for §13 (numbered at write time), e.g. `AV29`: "A link invitation is
+capped per group, on the node **and** on the hub". And an admission rule: "A bearer
+code is sent only to a node that has proved the key the link names".
+
+## 5. Mail sent by the hub: a stated trade-off, no longer a silent one
+
+**`invite-notify` hands the hub the code in the clear**, and the link mail does the
+same with the link. It is kept, **as an option the inviter sees**, because a mail that
+arrives without anyone copying anything is worth more to most groups than the property
+it costs. Written honestly:
+
+- Checked, **an active hub can join in the invitee's place**. It holds the code, and
+  for a link the ticket as well. It still has to go through the address binding, which
+  it controls, because it is the one that verifies addresses.
+- Unchecked, the property of §3.4 holds exactly as written.
+- `MESHBAY_DESIGN.md` §3.4 (property 2 and the "adopted" line) and `USERGUIDE.md`
+  §4 ("The code never passes through the hub") gain the same qualification: **"unless
+  you ask the hub to send it by e-mail"**. The USERGUIDE gets one sentence next to the
+  checkbox: for a group where it matters, uncheck it and send the link yourself.
+
+This replaces the §15.3 entry planned earlier: a choice stated in the interface and in
+the documentation is not an open defect.
+
+## 6. Scenarios to hold (each becomes a test or a manual check)
+
+| # | Situation | Expected |
+|---|---|---|
+| S1 | No account, opens the link | invitation page → register → recovery → e-mail code → sign in → confirmation → group open, files visible |
+| S2 | Has an account, signed out | sign in → confirmation → group |
+| S3 | Already signed in, right account | confirmation → group |
+| S4 | Signed in as **another** account | `invite_other_account`, suggests signing out; invitation kept |
+| S5 | Registers with another address | same, and the message mentions aliases |
+| S6 | Link expired / cancelled / already used by someone else | "invitation no longer valid, ask for a new one"; storage cleared |
+| S7 | Reload or tab closed between steps | reload: resumes (`sessionStorage`). Tab closed: reopening the link works (idempotent redeem) |
+| S8 | Node offline after redeem | group in the sidebar, "offline"; code kept; joins when it comes back |
+| S9 | Already pinned on this node through **another group** | "device known" branch → the link is accepted |
+| S10 | Account known on the node, **new browser** | `unknown_device` → device linking, then the link |
+| S11 | Browser without `bundleKey` (device sign-in) | passphrase prompt, code kept |
+| S12 | Already a member of the group | nothing spent, the group opens |
+| S13 | Group hosted by two nodes | the code goes to `n` only; the other node never sees it |
+| S14 | Old node (no challenge `sig`) | stated refusal, code not sent |
+| S15 | Desktop, pasted link | same flow; link from another hub refused |
+| S16 | Owner cancels before use | node + hub; the link answers S6 |
+| S17 | Owner removes the member after joining | existing removal flow, unchanged |
+| S18 | Open group (`join_policy = open`) | "invite by link" is not offered, as with the code today |
+| S19 | Node with no paired operator | same message as today for invitations |
+| S20 | Sign-out with an invitation pending | storage cleared |
+| S21 | Box unchecked, then the page is reopened (or another browser, or the desktop) | still unchecked, in both boxes |
+| S22 | 11th link mail of the day | link created and shown, `email_status: refused`, "share it yourself"; ordinary invitations unaffected |
+| S23 | Box unchecked | no call to `invite-notify` / no mail; a test checks that the hub never received the code |
+| S24 | Link mail with a forged URL (other origin, other ticket) | refused by the hub, no mail sent |
+
+## 7. Order of work — one commit per step, suite green between each
+
+0. **Baseline**: suite counts per package (hub, node, common) before touching
+   anything, with the known pre-existing browser failures noted.
+1. `feat(hub):` the remembered **"Send by e-mail"** checkbox on the existing *Invite
+   member* box (`invite_email` preference, i18n ×10), plus the §3.4 / USERGUIDE wording
+   of §5. Standalone, and it changes nothing when the box stays checked.
+2. `feat(common,node):` challenge signature, MNP **3.4** (MINOR, floor unchanged),
+   both transports, py↔js parity, client verification when `sig` is present. Worth
+   having without links: it is the precondition for everything else.
+3. `feat(node):` `kind`/`invite_id`, `consume_invite`, join branches,
+   `invite_link_create`/`invite_cancel`, ops, loopback, ceiling, audit, `member list`.
+   Tests: node roster + join + races + regressions (bound invite, operator pairing,
+   `drop_invites` on an empty `user_id`).
+4. `feat(hub):` table + migration + routes + purge + notification + **link mail**
+   (`invite_link` purpose, per-account daily cap, URL validation). Tests: two accounts
+   (`test_availability_between_members.py`), uniform responses, clamps, idempotency,
+   the 11th mail refused while the other purposes still send, `invite_link` unable to
+   spend the recovery reserve.
+5. `feat(hub):` SPA — `invite-page.js`, login/register routing, `GroupPage`,
+   Members tab, paste field, i18n ×10. Source-reading tests: **no `hubFetch` carries
+   `c`**, `replaceState` called before any `await`, storage cleared on sign-out. A
+   **harness probe driving the real flow** in a browser against a local hub and node
+   (S1, S4, S13): only launching it proves the ordering.
+6. `feat(node):` CLI `--link`.
+7. `docs:` `MESHBAY_DESIGN.md` §3.4 / §5.6 / §7.3 / §13 / §15, `MESHBAY_NODE_PROTOCOL.md`
+   §6.5 / §8 / §10.4 / §13 / appendices, `USERGUIDE.md` §4 and §7, and this file
+   reduced to what the synthesis does not carry.
+
+Deployment: node before SPA. A node on 3.4 signs, and nothing yet requires it; an SPA
+that offers the link without a 3.4 node gets the stated refusal from step 2.