design(id): identity, login & delegation — simplicity-first key custody, security-code recovery, and pseudo-login identities #5684

Summary

Design how a person actually gets into id: identity creation, everyday login, key custody, recovery, and delegation — with simplicity-first as a hard requirement, not a preference.

The native object in id is a brand-new ID in the iroh style: an identity rooted in a keypair, not in an account row on someone's server. Everything in this issue is about reconciling that fact with a login experience ordinary people already understand — and being honest, in writing, about which reconciliations are cryptographically real and which are theatre.

Extends #2804 (issuer key rotation and compromise recovery): rotation/recovery for issuers is one custody story; this issue is the user-facing custody, login, and delegation story for everyone.

Relates to: #2804.

Hard requirements

1. Simplicity-first. If a design step would confuse a non-technical user, the design is wrong, not the user. Every flow below must be walkable by someone who has only ever used "Sign in with Google" or a username/password form.
2. Login UX indistinguishable from ordinary logins. The user sees Google sign-in, username/password, or OIDC — familiar buttons, familiar forms. Key material, signing, and delegation happen behind that surface; the user is never asked to understand them to get in.
3. Honesty about custody. For every variant, state plainly who can sign as the user, who can lock the user out, and who can recover the account — including when the answer is "nobody can."

The native identity

• A brand-new ID (iroh-style): identity = a keypair; the public key (or its hash) is the identifier; there is no central registry that mints or can revoke it.
• What creating an ID means at setup: key generation, where the key first exists, and the first signed artefacts (see signed-hash construction below).
• How this ID relates to existing concepts in the system: worlds, capability grants, issuers (id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804), and names / human-readable handles layered over the raw ID.

Key-custody variants to design

(a) Service holds the key

• The service generates / stores the user's key and signs on their behalf after ordinary authentication.
• State the trust honestly: the service can act as the user; compromise of the service is compromise of the identity; what mitigations exist (HSM/KMS, signing audit logs, user-visible activity) and what they cannot fix.
• Who this variant is for (convenience-first users) and how a user later migrates OUT of it to a self-held key — is migration a key change, a new ID, or a rotation the system already supports (link id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 mechanics)?

(b) User holds the real key elsewhere; the authorizer only authenticates

• The real key lives with the user — e.g. in Google Drive, or in a file the user keeps — and the login service / authorizer only authenticates the person and never possesses the key.
• Flow design: login (Google / OIDC / password) unlocks or fetches the key client-side; signing happens client-side; the authorizer's role is authentication and possibly challenge issuance, never custody.
• Failure modes: key file lost, Drive access lost, key used from a new device, key passphrase forgotten. Which of these are recoverable and through what?
• Threat model: what a malicious or compromised authorizer can and cannot do in this variant (it can deny login; can it do more?).

(c) Recovery via 10 security codes

• At setup the user is issued 10 security codes; some threshold / use model (design it: any one code? a quorum? single-use each?) lets the holder recover access.
• Stated plainly, in the design and in the eventual UX copy: if all codes are lost (and no other recovery path was set up), nobody can unlock the account. Not support, not the service, not the developers. The identity is unrecoverable. The design must include how this is communicated at setup so it is a real informed choice, not fine print.
• Code storage guidance, code format (entropy, grouping, printability), regeneration (does regenerating invalidate the old set? how is regeneration itself authorised?), and interaction with variants (a) and (b).

(d) Delegation via pseudo-login identities

• A pseudo-login identity is its own ID — a real, separate identity in the system — that is used to log in and act day-to-day.
• Ownership forms to design: the pseudo-login ID may be owned by the user (the user's real key controls / can revoke it), owned by nobody, or derived randomly from the login (e.g. deterministically or freshly from the authentication event, with no controlling key at all).
• The pseudo-login signs a challenge to authenticate, and holds a scoped "do-as" delegation: a grant authorising it to act as the user, within stated scope (which worlds, which capabilities, what expiry, revocable how).
• The user's real key never performs the activity. Day-to-day actions are signed by the pseudo-login identity under delegation. Consequences to design through:
  • Raw activity view: the underlying record shows the pseudo-login identity acted, under delegation from the user — provenance is visible in the raw view even if the friendly UI renders it as the user.
  • Revocation: killing a compromised pseudo-login (lost phone, leaked session) without touching the real identity; how fast revocation propagates; what happens to actions already taken.
  • Scope creep: delegation scope must be least-privilege by default and legible to the user ("this login can do X in worlds Y until Z").
  • Multiple pseudo-logins: one per device / per login method, each independently revocable — design the user's management view for these.
• Nobody-owned / login-derived pseudo-logins: what revokes them if no key controls them? Session lifetime, server-side session records, and the honest statement of what "identity" means when nobody holds a key.

The investigation: can login work with NO key custody?

This issue must answer, with cryptographic reasoning and not hand-waving:

• Can OIDC work with no party holding the user's key? I.e. the OIDC provider authenticates, the user holds (or derives) their key, and no server ever possesses it. What does the client need, where does signing happen, and what does the relying party actually verify?
• Can username/password work with the authorizer holding none of the key? Consider password-derived keys (and their entropy problem), PAKE-style protocols, and what the server stores. State the brute-force exposure when a password-derived key meets a stolen verifier / stolen encrypted key blob.
• For each login method × custody combination, classify: proven-feasible (known construction, can cite how it works), feasible-with-caveats (works if specific conditions hold — name them), or speculative (no established construction found; say what is missing).

The signed-hash construction (required topic)

• At setup, the user signs a hash (of what, exactly — a setup statement, a recovery commitment, a delegation root?). Later acceptance comes from verifying a signature against the established public key / signed artefact, not from any party's custody of the private key.
• Design what is signed, what is stored, who stores it, and the verification flow at login / recovery / delegation time.
• Show where this construction is what makes variants (b) and (d) possible, and where it does not help (e.g. it cannot recover a key that no longer exists anywhere).

Flows to specify end-to-end

1. First-time setup via Google sign-in, for each custody variant the variant allows.
2. First-time setup via username/password.
3. Everyday login on a new device.
4. Recovery with a security code (variant c), including the all-codes-lost dead end and its exact user-facing wording.
5. Creating, viewing, scoping, and revoking a pseudo-login delegation (variant d).
6. Migrating between custody variants (at minimum a→b and any→a), or an explicit statement of which migrations are impossible and why.
7. Issuer / privileged identities: how this composes with id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 rotation and compromise recovery rather than inventing a parallel mechanism.

Non-goals

• Implementing any variant (this is design + feasibility investigation; implementation is follow-on work).
• Replacing id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 — issuer rotation/recovery mechanics are inputs, not to be re-designed here.
• Social recovery / guardian models, hardware keys / passkeys as a primary topic (note where they slot in if trivial, but do not expand scope to design them fully).
• Username / handle naming and squatting policy (layered over IDs; separate concern — flag dependencies only).

Acceptance criteria for the design deliverable

• A design document covering the native ID, all four custody/delegation variants (a–d), and the seven flows above, linked from this issue.
• A feasibility matrix: login method (Google / OIDC / username-password) × custody variant, each cell classified proven-feasible / feasible-with-caveats / speculative, with the construction or the blocker named.
• The signed-hash construction specified: what is signed at setup, what is stored where, and the verification flows that rely on it.
• For every variant, a plain-language "who can sign as you / lock you out / recover you" statement suitable for user-facing copy — including the all-codes-lost statement for variant (c) verbatim.
• Delegation model for pseudo-login identities: ownership forms, scope, expiry, revocation, and raw-view provenance.
• Follow-on design tickets filed from the Decomposition sketch (or the sketch revised with reasons).

Decomposition sketch

Follow-on design tickets to be filed from this issue (indicative; revise during the work):

1. Design: native ID creation & setup ceremony — key generation, first signatures, and the signed-hash setup artefact.
2. Investigation: keyless-custody login feasibility — OIDC and username/password with no authorizer key custody; the feasibility matrix and constructions.
3. Design: service-held keys (variant a) — custody architecture, signing audit, and migration out to self-custody.
4. Design: user-held keys (variant b) — Drive / file storage, client-side unlock, new-device and lost-key flows.
5. Design: 10 security codes recovery (variant c) — code model, thresholds, regeneration, and the unrecoverable-state UX.
6. Design: pseudo-login identities & scoped do-as delegation (variant d) — ownership forms, challenge signing, scope/expiry/revocation, raw-view provenance.
7. Design: identity management UX — custody-variant migration, delegation management view, and plain-language custody disclosures.

Open questions

• For variant (b), is Google Drive (or any third-party file store) an acceptable key home for non-technical users, or does file-based custody fail the simplicity requirement in practice — and what evidence settles that?
• Password-derived keys: is the entropy problem disqualifying for username/password with no server custody, or do PAKE / hardened-KDF constructions make it feasible-with-caveats?
• Pseudo-login identities owned by nobody: if revocation is purely server-side session state, in what sense is the delegation still a cryptographic artefact — and does that weaken the raw-provenance guarantee?
• How many pseudo-logins will a typical user accumulate, and at what number does the management view itself break the simplicity requirement?
• Should variant (a) exist at all, given it concentrates compromise risk — or is refusing it simply excluding the users who need it most?
• What threshold for the 10 codes (any-one vs quorum) balances "lost codes" against "stolen code" — and can the user choose?
• Does the signed-hash setup artefact create a permanent linkage / fingerprinting surface across services, and if so how is it mitigated?

Extension of #2804. Framing per Drew: keen priority, with simplicity-first as a hard requirement and login UX indistinguishable from ordinary logins.