Skip to content

docs: plan passkey recovery, trusted-device introductions, and attestation (coven#788) - #877

Draft
CompleteDotTech wants to merge 1 commit into
OpenCoven:mainfrom
CompleteDotTech:agent/issue-788-plan-passkey-recovery-trusted-device-introductions
Draft

docs: plan passkey recovery, trusted-device introductions, and attestation (coven#788)#877
CompleteDotTech wants to merge 1 commit into
OpenCoven:mainfrom
CompleteDotTech:agent/issue-788-plan-passkey-recovery-trusted-device-introductions

Conversation

@CompleteDotTech

Copy link
Copy Markdown
Member

Summary

  • Adds docs/design/mobile-recovery-and-introduction-plan.md — the #788 plan and implementation contract for trusted-device introductions, passkey recovery, and optional attestation, sitting under the accepted #784 mobile trust architecture and slotted to delivery-plan PR 7 ("Recovery and trusted-device introduction" in docs/architecture/mobile-device-pairing-delivery-plan.md).
  • Defines five new protocol objects at object version 1 with diagnostic JSON Schemas and TypeScript reference types: IntroductionRequest, IntroductionApproval, RecoveryPolicy, RecoveryEvent, AttestationClaim — plus their domain-separation labels for the registry in spec/device-pairing/v1/domain-separation.md (the implementation PR lands the schemas as files under spec/device-pairing/v2/ and registers the objects in a v2 conformance manifest).
  • Specifies the introduction transcript binding (endpoint public key, requested scopes, nonce, expiry, human-readable device context, grant template), the mandatory fresh step-up on every approving device, the introduction state machine, and the anti-substitution/replay properties.
  • Recommends the 1-vs-N-of-M policy: one fresh-step-up trusted device suffices for standard enrollment; RecoveryPolicy.introductionPolicy.rootMinApprovals (default 2, distinct approvers) gates root-level classes (identity.admin, devices.enroll|revoke, exports).
  • Defines passkey usage boundaries: allowed uses (optional account sign-in, recovery authentication, remote-enrollment authorization, installation approval as an extra factor, cross-platform browser/native login) and hard prohibitions (never the sole familiar/root key, never proof of one physical device, never a globally reused identifier, never the only recovery path).
  • Defines recovery as a first-class protocol: factor-combination matrix (passkey/account, recovery key, another trusted device, N-of-M, owner root credential), explicit ceremonies that keep recovering access (access_restored, rotatesIdentity: false) separate from replacing/rotating identity (identity_rotated, rotatesIdentity: true, revocation_epoch bump), and append-only RecoveryEvent audit records matching the audit.rs stream discipline.
  • Specifies optional platform attestation as assurance attributes (unattested_device, verified_official_app, verified_hardware_key — reusing the v1 grant-restriction enum from spec/device-pairing/v1/device-grant.schema.json) mapped from Apple App Attest / Android hardware key attestation / Play integrity signals, with owner-policy gating and full protocol participation for self-built, self-hosted, and dev builds.
  • Documents why a compromised relay or account service alone cannot mint device authority; threat-model deltas; acceptance-criteria mapping; implementation staging (7a–7d) with merge gates.
  • Cross-links the plan from docs/design/mobile-device-trust.md (#788 row of the issue-to-delivery mapping).
  • Every current-state claim cites existing code paths (crates/coven-cli/src/mobile_memory/*.rs, crates/coven-relay/src/ws.rs, crates/coven-cli/src/familiar_identity.rs, spec/device-pairing/v1/*).

No product code changes — specification artifacts only; nothing in the diff can weaken v1 privacy, replay, revocation, canonicalization, or audit guarantees.

Issue

Refs #788 (parent #784; builds on #786, #787).

Closes #788 is intentionally not used even though this is an upstream PR: the delivery plan's merge policy states plan issues close only when their acceptance criteria are demonstrated, not merely scaffolded, and #788 remains the umbrella for the implementation stages sequenced in the plan (§11).

Test plan

  • python3 scripts/check-secrets.py — clean locally
  • python3 scripts/check-coven-privacy.py --staged — clean locally (2 files)
  • All 7 embedded JSON blocks parse as valid JSON; the two golden examples were validated against their schemas (required fields, enums, base64url patterns) with a local node script
  • Targeted structural review of schema/example consistency (required/additionalProperties/enum/pattern checks)
  • cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace --locked — deferred to CI; no Rust or TypeScript code is touched (docs-only diff)
  • Docs-only diff, so CI's classifier (scripts/classify-ci-changes.py) should set docs_only and skip the Rust/npm jobs.

Vehicle note: opened in the fork CompleteDotTech/coven as the CI vehicle — this token cannot write to OpenCoven/coven. Re-target upstream once write access is restored. Refs #788.


Recreated upstream from [https://github.com/CompleteDotTech/pull/18], preserving source head 53894b95b5dec2c02dddfae87cc636fa8a14dd25 and branch agent/issue-788-plan-passkey-recovery-trusted-device-introductions.

…ation (coven#788)

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-788-plan-passkey-recovery-trusted-device-introductions branch from cc40048 to f0198cd Compare August 30, 2026 19:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant