eden/docs/design-records/t05-dataset-consent.md

T05 design record: dataset authorization and incremental consent

Status: local prototype implementation; not a production-readiness or public-launch approval.

Primary decision

An application user has exactly one primary linked character. The primary is the only character that can authenticate the site while signed out. Additional linked characters are data-only and cannot authenticate signed out. While authenticated, the user can designate any currently active linked character as the primary; the old primary is demoted in the same Convex transaction.

The active authenticated application session is sufficient to link another character. The callback binds to that initiating session and revalidates it again in the persistence transaction. A character ID supplied by a browser is only a server-resolved selector. A verified owner continuity claim is per character and never groups EVE characters into an account.

Consent and authority

• Capability definitions select required scopes. The application route combines those with only server-allowlisted scopes already granted to the selected linked character when upgrading/reconnecting.
• OAuth state is one-time and records intent (initial_login, link_character, upgrade_dataset, or reconnect), capability, requested/preserved scopes, target character and initiating session hash.
• The verified provider grant, not the requested scope list, is persisted as authority. Scalar and array scp claims are normalized by SSO verification. Reduced grants are accepted but block/invalidate affected datasets and remove old asset generations from reads.
• Character records carry role, authorization status, grant revision, credential version and authorization epoch. Dataset statuses carry their own status and matching fences. Local cancellation revokes authority, clears active asset generations, removes credentials and quarantines character jobs where present.
• Owner mismatch never transfers data. The old character is quarantined, credentials and active data access are fenced, and future jobs are quarantined. Full transfer-to-new-owner recovery is explicitly deferred.

Session replacement is performed transactionally with login persistence where possible: the initiating session is revoked as the new session is inserted. OAuth code consumption remains one-time, and callback failures never blindly replay a code.

Prototype data policy and deferrals

This repository is pre-production and has no users beyond the operator's test character. Schema/model changes are development-only: when local data makes a change costly, wipe/reseed it rather than adding earliest-character migration, lazy-normalization or retention-compatibility machinery. The first linked character is created primary directly; no legacy migration workflow is implemented.

The local prototype keeps essential correctness/security boundaries: server-derived authorization, tenant isolation, scope allowlists, one-time OAuth, no token leakage, fail-closed owner checks, dataset/read fencing and safe fixed callback errors. It intentionally defers T01 production evidence and full lifecycle work: CI/deployed artifact proof, browser failure injection, restore/migration rollback rehearsals, retention/GC, public quotas/admission, production session/orphan recovery policy, remote revocation outbox, unlink/delete, and complete transfer recovery. T06 typed transport and T07 durable worker transport are not implemented here. Production migration, retention, rollback and public-launch gates remain mandatory after prototype approval and before P.