Plan: Remote token issuance (invite flow)

Status: draft, recorded 2026-07-16 (Fritz + Claude). Details the roadmap's "Remote Token Issuance: PLANNED" section; the decision between the two options below should land as an ADR before implementation.

One-line

Let a server owner onboard a new person or device to a remote soul or standalone world without SSH and without hand-carrying a long-lived raw token.

The problem

The goal is a low-barrier remote knowledge base. The onboarding chain today:

1. Server on a VPS: install.sh. Fine.
2. Mint a token: SSH to the host, demarkus-token generate. Friction.
3. Deliver the raw token to the user: chat/email paste of a long-lived secret. The weak link.
4. /soul-join mark://host --token <TOKEN>. Fine.

/soul-join consumes a token but cannot mint one (the server's tokens.toml is not local to the plugin). The broker solves issuance for k8s universes (Phase 6.3: OIDC, mints scoped tokens, writes hashes to Secrets) but is far too heavy for a personal or small-team standalone server. The gap is the middle tier: one owner, a few collaborators or devices, no k8s, no OIDC.

Shared shape: one-shot invites

Both options use the same primitive. An invite is a short-lived, single-use code that redeems for a freshly minted scoped capability token:

• Owner creates an invite with a label, path globs, ops, and a TTL (default minutes, not days).
• New user redeems it once: /soul-join mark://host --invite <code>. The join flow receives the raw token, writes it to the 0600 token file as today, and the invite burns.
• Expired or already-redeemed codes fail closed. Every create and redeem is audit-logged with labels.
• Nothing secret in transit outlives the TTL; the raw token is generated at redemption and travels once, over the QUIC session doing the redeem.

The options differ only in where invite creation runs.

Option A: invite minted on the host (offline, zero core change)

demarkus-token invite is a new subcommand beside generate: writes a pending-invite row (hashed code, scope, expiry) to tokens.toml; the server's existing file watcher hot-reloads it. Redemption is the only new server surface: a redeem operation that exchanges a valid code for a new token, appends the token hash, and marks the invite spent.

• Pro: invite creation stays offline, matching the current trust model exactly (only someone with shell access to tokens.toml can create credentials).
• Pro: smallest possible server delta (redeem only).
• Con: the owner still SSHes per invite. The handoff is fixed (short-lived code instead of long-lived secret) but the barrier is only half-removed. For the person running one server for themselves plus a phone and a laptop, step 2 friction remains.

Option B: invite minted over the protocol (capability delegation)

Tokens gain an invite op. A token holding it can create invites over the wire, from any joined client, constrained by attenuation: an invite may only grant a subset of what the inviting token holds (paths within its globs, ops within its set, never invite itself unless explicitly re-granted). The owner never SSHes after install:

1. install.sh mints the owner token at install time and prints it once (the plugin's local-soul flow already does exactly this pattern).
2. Owner joins from their own machine with the owner token.
3. Owner runs demarkus invite -paths "/team/*" -ops publish -ttl 15m mark://host, gets a short code.
4. New user redeems via /soul-join --invite.

This makes issuance itself a capability, which is the natural extension of the existing model: delegation with attenuation is the classic capability pattern, no accounts and no identity provider.

• Pro: actually delivers low barrier; the whole lifecycle runs over the protocol.
• Pro: composes with the plugin cleanly (a /soul-invite command needs nothing but the joined MCP server).
• Con: breaks the standing constraint that the core server never writes its own tokens file. The server learns invite-create and invite-redeem operations and appends to tokens.toml (or a sibling invites file). Contained (append-only pending rows, existing audit log, existing hot-reload) but it is a real expansion of the write surface on a component deliberately kept out of the issuance business.
• Con: incompatible with the read-only chroot deployment by construction. Acceptable: that mode is explicitly single-publisher, and invites there fall back to Option A's offline path or plain generate.
• Con: a stolen owner token now mints credentials, not just content. Mitigations: attenuation cap, TTL ceiling on invites, invite op never granted by default, audit rows for every create/redeem, revocation unchanged (drop the label, reload).

What both options require regardless

• Redeem surface on the server (the one unavoidable core change): a verb or well-known endpoint that runs pre-auth (the redeemer has no token yet), rate-limited like everything else, constant-time code compare, hashed codes at rest.
• tokens.toml schema addition for pending invites (hashed code, scope, expiry, spent marker) that old servers ignore gracefully.
• /soul-join --invite in the plugin, plus CLI parity (demarkus join --invite or equivalent).
• Docs: the security page's threat model gains an invites section.

Comparison

Recommendation

B, scoped tightly: invite op, attenuation enforced, redeem pre-auth endpoint, append-only writes, audit everything. A is not a stepping stone to B (its offline-create path survives inside B unchanged, since demarkus-token invite on the host is just create with a local writer), so building A first costs nothing but delivers little. The deciding question for the ADR: is "the server never writes credentials" a load-bearing security property or an artifact of history? The read-only mode already answers how to keep the hard-line posture available: run that mode and issuance stays fully offline.

Open questions

• Redeem transport: new protocol verb (spec change, CC0 protocol surface) vs a well-known reserved path handled outside the verb table. A verb is honest; a magic path is expedient.
• Should redeemed tokens be able to carry invite at all (transitive delegation), or is one level of delegation the ceiling?
• Invite code shape: short human-typeable code vs full URL (mark://host/.well-known/invite/<code>), QR for phones.
• Broker relationship: does the broker's minting core eventually reuse this (invite as the broker's non-OIDC fallback), or do they stay parallel?
• Rate limiting and lockout on redeem attempts (code brute force) beyond the existing per-IP limiter.