Register externally provisioned recovery credentials and adopt existing vaults

[tvanreenen]

Purpose and review boundary

The recovery foundation defines what a token-anchored snapshot means, but a user still needs to bind an externally provisioned credential to a reviewed vault state without silently activating partial setup. This PR adds internal read-only token binding, registration preparation/completion, and explicit adoption of an existing profile-2 vault. It targets codex/recovery-foundations (#69); the format and history verifier are dependencies, not repeated changes in this diff. Ordinary operations continue in #71 and lifecycle changes in #72.

The application does not administer the YubiKey. Credential creation, PIN/PUK and management-key maintenance, and public anchor installation stay in owner-run vendor tools. That boundary avoids coupling Key to a hardware writer and respects the owner's concern about application-controlled credential changes. It also means the external write is not an application-owned atomic transaction: vendor import is not claimed to preserve a prior object automatically. Product instructions and physical qualification remain necessary.

Token and registration boundaries

The token reader binds public observations to an exact credential and bounded read-session lifecycle. The scoped agreement adapter checks the selected handle and public key, limits a scope to one use, and excludes concurrent pending workers. Reported metadata must satisfy the configured PIN/touch ALWAYS policies and generated-origin requirement. These are checks on reported metadata, not attestation or proof that a physical device enforced those policies.

Registration constructs a candidate from authenticated source authority and an exact reviewed recipient, preserves existing coverage, and prepares the public anchor for external installation. Completion re-observes the selected credential/anchor and verifies possession before activation. Local ownership pins the exact preparation; encrypted durable preparation files allow resume without generating new approval, signing again, or persisting plaintext or raw vault keys.

The internal registration service owns prepare/resume/finish under the vault mutation boundary. It independently checks source snapshots, checkpoints, token bindings and pending work around approvals. Publication is manifest-last and local trust advances only after verification/readback. A lost reply, interrupted write, failed checkpoint update or cleanup failure is reconciled against the exact prior operation, not inferred from an arbitrary provider file. Already committed repair authenticates current authority and does not require obsolete entry ciphertext.

Existing-vault adoption

Adoption is an explicit signed profile-2 to profile-3 transition. Its builder and independent validator compare the complete source/candidate snapshots. The service retains exact source and ownership guards, encrypted preparations, manifest-last publication, checkpoint/session ordering, and current-only committed reconciliation. A shared bounded exact-transition repository and snapshot validator keep these checks consistent with registration.

Provider preparations are not local authorization, and registration/adoption intents cannot be resumed as ordinary transactions. Shared local intent/ownership changes are included because they enforce those distinct operation kinds. The source-level old-client refusal check covers profile dispatch; it is not a claim about an installed released binary.

Verification and limitations

• Independent boundary rerun at dfc34f0: swift test --no-parallel --filter 'PIV|V3EpochSigningKey|V3Recovery' passed 223 tests in 16 suites, compiling and exercising this exact layer separately from the final stacked tree.

• The ledger records a complete serial Debug pass at this boundary: 1,040 KeyCore tests in 92 suites and six canonical-JSON tests. The affected Release regression passed 350 tests in 25 suites; this was not a full Release run.

• The unsigned universal Preview app, CLI and helper built, and bundle isolation plus CLI help/completion checks passed. Local stores, native callbacks and confirmation failures in the service tests are software fixtures; filesystem and cryptographic publication are exercised directly.

• Tests cover registration/adoption interruption phases, exact preparation and pending ownership, source/checkpoint changes, conflicting manifests, cancellation, projected limits, unavailable files, containment and committed-state reconciliation.

The normal shipping helper/CLI does not call these components. Ordinary profile-3 writes, reciprocal service barriers, product status/confirmation, native Keychain/token qualification, restore orchestration and independent backup-token acceptance remain outside this layer. Later PRs implement several of those software dependencies, but do not make this PR alone a supported end-to-end workflow. No token administration, real-vault adoption or installed-product change is performed here. REC-807/REC-808 and adoption acceptance remain in progress.