Define and prove secure single-use iOS invite authentication

[BunsDev]

Outcome

Deliver a reviewable, fail-closed invite-authentication contract for pairing the native iOS companion with a trusted Psyche desktop host, then prove it on a physical device before changing support status.

Control metadata

• Accountable owner: @BunsDev
• Parent outcome: Deliver the Psyche Build iOS internal beta and continuity loop #200 — trustworthy iOS internal beta and continuity
• Hard prerequisite: Extract an atomic iOS host-readiness state machine from PR #193 #241 — atomic host-readiness state machine
• Source implementation: draft PR feat: add secure iOS invite authentication #264
• Priority: P1 after Extract an atomic iOS host-readiness state machine from PR #193 #241
• Risk class: R3 — authority, authentication, protocol, persistence, revocation, and recovery

Why this is separate

Draft PR #264 is valuable source material, but at 32 commits / 37 files it combines desktop invite issuance, protocol fixtures, QR/deep-link presentation, iOS parsing, certificate validation, credential exchange, secure persistence, reconnect, and recovery UI. Those surfaces cannot receive credible authority/security review as one undifferentiated merge and must not bypass #241's atomic readiness gate.

Required protocol contract

• Define host identity, device identity, invite identity, durable credential identity, and their canonical owners.
• Bind every invite to the exact host certificate/identity and intended protocol profile.
• Use bounded expiry, cryptographic randomness, single-use redemption, and atomic consume semantics.
• Prevent replay, concurrent redemption, stale acceptance, superseded-flow acceptance, cross-host use, and downgrade.
• Keep discovery address/QR/deep-link data separate from durable identity and authority.
• Store only the durable exchanged credential; never persist or log the invite secret.
• Define explicit revocation, expiration, wrong-host, secure-store failure, interrupted exchange, and retry semantics.
• Publish structured denial/recovery results without secret-bearing messages.
• Preserve certificate pinning and fail closed on identity mismatch.

Ordered implementation slices

1. Protocol and fixtures: typed invite/redemption records, bounds, replay/expiry vectors, canonical generation, no UI.
2. Desktop issuer/consumer: single-writer issuance and atomic redemption with bounded storage and revocation.
3. iOS credential exchange: parse/validate/redeem/store without exposing workspace state before Extract an atomic iOS host-readiness state machine from PR #193 #241 commits authority.
4. QR/deep-link UX: presentation and recovery only after the protocol core is accepted.
5. Physical acceptance: real Mac/iPhone pairing, interruption, replay, expiry, supersession, restart, revocation, and reconnect.
6. Distribution evidence: repeat the matrix from one immutable TestFlight build under Deliver the Psyche Build iOS internal beta and continuity loop #200.

Each slice must start from current main, have one owning acceptance gate, and preserve rollback. Do not merge the 32-commit source branch as one unit.

Acceptance criteria

• Invite material never appears in logs, accessibility output, screenshots/fixtures, crash reports, process args, support bundles, or persistent app state.
• Exactly one redemption can commit; every concurrent/stale attempt receives a deterministic denial.
• A credential-store failure cannot expose the new host/workspace as authoritative.
• Revocation survives app/host restart and blocks reconnect.
• Manual endpoint fallback and address changes preserve the same host identity.
• Simulator tests cover transition boundaries, but physical evidence is required for the support claim.
• An independent R3 review resolves current findings on every focused PR.
• Deliver the Psyche Build iOS internal beta and continuity loop #200 links immutable build identity and the complete physical evidence matrix.

Non-goals

• Treating a QR code, Bonjour address, or TLS endpoint as durable identity.
• Publishing TestFlight from source/simulator success.
• Merging all of feat: add secure iOS invite authentication #264 merely because its tests pass.
• Coupling this authentication path to future cloud/off-LAN continuity.
• Redefining Familiar, Threads, or Psyche protocol identity in the product repository.

Evidence

Link the protocol decision, focused PRs, generated fixtures, threat model, exact-head CI, security review resolution, physical-device manifest, credential revocation/reconnect proof, and rollback results.

[BunsDev]

Draft PR #323 is refreshed onto current main at 702288aef61f21ba98a7eb87d9088983fa9e4cf2. Final exact-head R3 review found no implementation defects, and required CI is green after rerunning one unrelated simulator UI timeout. The focused protocol/fixture slice remains fail-closed for bounds, replay, expiry, concurrent consume, credential-store failure, and secret persistence.

The PR remains draft. #241 is still open beyond its merged transaction-core slice, and OpenCoven/psyche#12 still owns the unresolved canonical host-identity/compatibility decision. No source, fixture, simulator, or CI result is being treated as physical pairing, revocation/reconnect, or support-state evidence.

[BunsDev]

Slice 1 merged — 2026-09-02

PR #323 merged as 052ed006 from exact reviewed head 5200ff6245a6848e53f0b7a8110b2767b6f57fd4. Slice 1 (protocol and fixtures) is on main: typed invite/redemption records, bounded encoded input rejected before decoding, cryptographic single-use redemption with atomic consume, replay/expiry/attempt-budget denials with fixed non-secret messages, opaque host identity, fail-closed credential_store_unavailable that still consumes the invite, and generated protocol-fixtures/invite-auth/v1/* vectors. Evidence: 37 focused invite-auth tests, 246 fixture/contract tests at the earlier head, exact-head CI, independent review with no findings.

Remaining slices in order: 2 desktop issuer/consumer, 3 iOS credential exchange composed into the #241 readiness machine, 4 QR/deep-link UX, 5 physical acceptance, 6 distribution evidence under #200. Canonical host-identity ownership still waits on OpenCoven/psyche#12. No pairing, revocation/reconnect, or support-state claim follows from this merge.