oficina / docs Public

Draft identity linking that preserves existing Docs ownership

Paul Campbell pushed by paul@keymail.dev 1 month ago 5dc526fc4c77bae68981423a583ec8d97b94b680 parent 87662f5

1 file changed, +19 −0

implementation/home-account-link.md +19 −0

CI cancelled — superseded by a newer push — run details

diff --git a/implementation/home-account-link.md b/implementation/home-account-link.md

new file mode 100644

index 0000000..6621b9e

--- /dev/null

+++ b/implementation/home-account-link.md

@@ -0,0 +1,19 @@

+# Connect existing Docs accounts to Home

+Status: draft by Codex, 2026-09-08. Not approved for implementation. Prerequisite for the user's accepted common app entry and team selection flow, not a substitute for the full two-team acceptance. Existing Docs production base87662f5 owns documents through people.id; legacy sessions and address grants use verified email. Home exchange is merged0dc863c and enabled on isolated previews. Fresh-assertion design is in Home branch feat/home-fresh-assertion, discussion21.

+Preserve existing people.id, every OwnerID, grants, content encoding and encryption key. No assertion carries email; no lookup guesses that an opaque Home subject corresponds to an email; no fake email is created. Standalone deployments keep local authentication under Docs design §8.1. Suite authentication is explicitly configured and refuses partial issuer/key/consumer configuration at startup.

+Use the reviewed shared handoff module for exact issuer/audience verification, browser pending state and replay consumption. Extract the existing Home purpose-bound sealing implementation into a shared package before reuse rather than writing another crypto adapter or using the content-encryption key for navigation. This extraction needs separate compatibility tests and review. Configuration must use CARLOS-compatible base64 settings learned from the Home deployment.

+An additive identity-link table records exact issuer, opaque subject and existing person_id. Unique constraints cover both (issuer, subject) and (issuer, person_id). A link is created only after fresh authentication of both identities and an explicit same-origin confirmation POST. Concurrent identical requests are idempotent; conflicting links fail without replacing either row. No unlink or reassignment in this stage. Linking itself grants no new team standing or document permission.

+A completed Home exchange first produces a short-lived, sealed pending identity proof in this browser, rather than immediately replacing any existing Docs session. The proof contains verified subject, issuer, actual auth_time and expiry, never the raw assertion. The shared consumer consumes the assertion before creating that proof. An unlinked user then verifies their existing Docs account using local authentication; confirmation requires both actual authentication times within five minutes and not in the future. A stale Home proof requests fresh authentication from Home. A stale local session uses the existing fresh-session gate. A new ordinary session is not fresh evidence when its original AuthTime is old.

+The confirmation page must clearly identify the local Docs account being connected. A fresh POST binds the proof to that authenticated local person in one transaction and consumes the pending proof. An already signed-in different account never gets silently replaced. Preserve the intended safe local resource path in bounded sealed browser state; default missing or malformed paths to the app root. Do not use query parameters or plaintext cookies for identity proof, raw assertions or resource paths. Local signin callback returns to the confirmation continuation only while a valid pending link exists; preserve normal signin otherwise.

+Subsequent assertions resolve a linked Home subject to the existing local person. Existing address-grant evaluation can use that person's already verified local address, without disclosing it to Home. Admission must still apply the current roster or existing explicit grants; successful identity verification is not membership. Removal or stale roster state must invalidate standing on existing sessions, not just at sign-in. Membership implementation remains a required companion stage before general suite launch.

+New Home-only users require a separately reviewed identity-model migration. The current people.email column is NOT NULL and unique, so empty strings or invented addresses cannot provide that migration. Do not claim all-team readiness by proving only legacy account linking. Any replacement principal model must preserve old IDs and prove forward/rollback behavior without overlapping legacy and new identity allocation.

+Acceptance for linking: two local accounts and two Home subjects; successful explicit double-auth link preserves IDs and each user's owned/shared documents; stale/future proof refusal; cross-account session mix-up refusal; unique-link races; no replay after successful or failed completion; real local magic-link callback continuation; tampered/duplicate/missing cookies; hostile return paths; signed-in local account conflict; no raw assertions/proofs/paths in DB/WAL/logs; unchanged content compatibility and standalone signin. Demonstrate a meaningful failing mutation. Full Docs gate, independent Fable review and two isolated team browser runs precede common-host production cutover. Production host aliases and deep links remain unchanged until the existing instance has a verified team alias and explicit compatibility routing.