Skip to content

Make a paired iPhone an approver - #353

Merged
sudoHG merged 4 commits into
mainfrom
sudoHG/pairing-makes-approver-6cc9a4
Nov 15, 2026
Merged

sudoHG merged 4 commits into
mainfrom
sudoHG/pairing-makes-approver-6cc9a4

Conversation

@sudoHG

@sudoHG sudoHG commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Summary

Implements ADR 0014 → "Amendment: pairing makes an iPhone an approver (#336)" → Implementation tasks → 1. Closes #341.

  • Pairing rule (AskKeyDevices). PairingSession.entry(pairedAt:) sets the approval flag when the initiator's card says macOS and the responder's says iOS, on both sides; .add stores the entry's flag as given. Pairing layouts, labels and vectors are unchanged.
  • Vault. A flag is accepted only in the add that pairing authorized, for an iOS card (approverNotAuthorized otherwise); any change to a stored entry's flag is refused. authorizeDeviceApprover, endDeviceApproverAuthorization and the approver authorization in VaultDeviceState are removed.
  • Mac coordinator. pairingAdded(_:) adds a new pairing ID alone as soon as the coordinator sees the paired phase; reconcileActiveApprovers(with:) adds every flagged entry missing from the set at each list read while the services are ready and the account is available. Both use activateStoredApprovers(only:). The confirmation state machine, its polling, disableApprover, ApproverConfirmationState, ApproverAttempt and the code's log events are gone; a kind 14 message is refused as unexpectedKind.
  • Mac UI. The switch, the approver sheet and its system authentication (approveDevice) are removed. The pairing sheet, the Devices row, Remove's confirmation and the pairing reason carry the decision 5 statements. On the iPhone, the code screen, the Face ID reason and the confirmed and paired states do too.
  • Required flow. testApproveAgentRequestsTurnsOnWithTheCodeTypedOnTheIPhone is replaced by testPairedIPhoneApprovesAgentRequestsUntilRemoved: pair, check the row's approval text, Remove, confirm, check the row is gone. Still 18 flows.

Statements for wording review

Where English 简体中文
Mac sheet, before the QR code The iPhone you pair can approve agents' requests to use credentials on this Mac. Pair only your own iPhone. 配对的 iPhone 可以审批 Agent 使用这台 Mac 上凭证的请求。只配对你自己的 iPhone。
Mac sheet, code matched (iOS peer) The code matches. If you confirm, “%@” can approve agents' requests to use credentials on this Mac, with Face ID or Touch ID. Ask Key then asks for system authentication. 配对码正确。确认后,“%@”可以用面容 ID 或触控 ID 审批 Agent 使用这台 Mac 上凭证的请求。接下来请旨会要求系统验证。
Mac sheet, what a request sends (reused, approved in #313) Sent to this iPhone, encrypted: the agent's name, the credential's name, the command and folder, and the names the credential is delivered as. Never a credential value. 会加密发到这台 iPhone 的内容:Agent、凭证名称、命令、目录和交出的名称,绝不包括凭证的值。
Mac system authentication reason Pair an iPhone that can approve Agent requests 确认配对一台可以审批 Agent 请求的 iPhone
Mac sheet, paired (iOS peer) This Mac and “%@” are paired. The iPhone can now approve agents' requests to use credentials on this Mac. Ask Key sent a delivery check; until the iPhone answers, it shows as “Not reached yet”. 这台 Mac 已与“%@”配对,这台 iPhone 现在可以审批 Agent 使用这台 Mac 上凭证的请求。请旨已发送送达检查,在这台 iPhone 回应之前,它会显示为“还没联系上”。
Devices row, flagged iPhone Can approve agent requests. 可以审批 Agent 请求。
Devices row, iPhone without the flag Can't approve agent requests. To let it approve, remove it and pair again. 不能审批 Agent 请求。要让它审批,请移除后重新配对。
Remove's confirmation, flagged iPhone “%@” stops approving agent requests at once, and the requests sent to it close. Ask Key tries to tell the iPhone so it can remove this Mac. If it still lists this Mac, remove this Mac on that iPhone too. “%@”将立即停止审批 Agent 请求,已发给它的请求随即关闭。请旨会尝试通知这台 iPhone 移除这台 Mac;如果它仍列出这台 Mac,请在那台 iPhone 上手动移除。
iPhone code screen, before Confirm Pairing Confirming lets this iPhone approve agents' requests to use credentials on “%@”. Each request shows the agent, the credential, the command and folder, and the names it's delivered as, never a credential value. Allowing always needs Face ID or Touch ID. 确认后,这台 iPhone 可以审批 Agent 使用“%@”上凭证的请求。每个请求会显示 Agent、凭证、命令、目录和交出的名称,绝不包括凭证的值。允许时始终需要面容 ID 或触控 ID。
iPhone Face ID reason Pair with “%@” to approve its agent requests 与“%@”配对,以审批它的 Agent 请求
iPhone confirmed Confirmed on this iPhone. Enter the code on your Mac to finish pairing. Agent requests from that Mac will then appear in Ask Key. 已在这台 iPhone 上确认。请在 Mac 上输入配对码以完成配对,之后那台 Mac 上 Agent 的请求会出现在请旨里。
iPhone paired This iPhone and “%@” are paired. Agent requests from that Mac will appear in Ask Key. Allowing always needs Face ID or Touch ID. 这台 iPhone 已与“%@”配对。那台 Mac 上 Agent 的请求会出现在请旨里。允许时始终需要面容 ID 或触控 ID。

Glossary: the Chinese UI term for Approver is now 可以审批 Agent 请求, pending the same approval.

Renders

  • Mac, from RemoteApprovalRenderTests (CI artifact askkey-remote-approval-renders, 30 PNGs, en and zh): 01-devices-iphone-approves, 02-devices-iphone-cannot-approve (flagged and unflagged rows together), 03-devices-remove-confirmation, 04-pairing-qr-code, 05-pairing-waiting, 06-pairing-code-entry, 07-pairing-code-accepted, 08-pairing-authenticating, 09-pairing-waiting-for-iphone, 10-pairing-paired, plus the unchanged 11–15.
  • Mac, real management window (makeWindow with SettingsView(navigation:) as ensureManagementWindow builds it, and apply(to:)), scrolled to Devices: 16-en-settings-window-devices, 16-zh-settings-window-devices. Rendered locally only (REMOTE_APPROVAL_WINDOW_RENDERS=1), because a programmatic scroll draws an empty column on the CI runner (184335b).
  • Desktop captures (CI artifact askkey-basic-ui-evidence): 42-en-devices-pairing-paired, 43-en-devices-remove-confirmation, 44-zh-devices-pairing-paired, 45-zh-devices-remove-confirmation.
  • iPhone, from ScreenRenderTests (CI artifact askkey-ios-screens): 06-pairing-code, 07-pairing-face-id-cancelled, 08-pairing-confirmed, 10-pairing-paired, in en and zh-Hans.

Every render is checked for more than eight colors.

Diff stat

git diff --stat origin/main: 50 files changed, 1112 insertions(+), 1995 deletions(-).

Tests

Local, on 0852c91 (head, after both review rounds):

  • swift build: passed.
  • swift test --filter "AskKeyDevicesTests|AskKeyVaultTests|AskKeyAppTests": AskKeyDevicesTests 221 passed (main 216); AskKeyVaultTests 579 passed, 17 skipped (main 581: the approver-authorization tests went, the write-rule tests are new); AskKeyAppTests 836 passed, 1 skipped, 0 failed (main about 847: 20 approver-sheet and confirmation tests deleted, 11 RemoteApprovalPairingTests added). On f5ec3be, AgentClientConnectionExecutionTests.testFailedConcurrentCursorConnectionDoesNotUndoSuccessfulConnection failed once in a combined run and passed alone; it is a timing test unrelated to this change.
  • bash scripts/build-ios.sh test (on f5ec3be; no iPhone file changed since): AskKeyiOSKitTests 137 passed (main 136, +1), AskKeyiOSNotificationServiceTests 44 passed, 86 screens rendered.
  • basic-ui-flows (desktop E2E) runs in CI only, as AGENTS.md requires.

Checks

  • python3 scripts/check_hygiene.py: passed (size, test-support, debug, local-path, non-ascii-name, multica and cjk all 0).
  • python3 scripts/check_module_deps.py: passed.
  • Every changed Swift file is under 600 lines (largest: DeviceCoordinator.swift, 570).

Deviations and questions

  1. Requests pending before the first pairing. reconcileRemoteRequests() now runs without device services, and stopRemoteApproval() keeps pending requests as staying-on-Mac markers instead of dropping them. Without this, a request created before the Mac had an identity was first seen after the first pairing and sent to the new iPhone, against "a request that was not eligible then ... stays on the Mac ... which includes every request pending while the first iPhone pairs".
  2. Removal that races a reconciliation. deviceWillBeRemoved records the pairing ID in revokedApprovers, and neither pairingAdded nor reconciliation adds it again. Between the removal hook and the list write, a list read still sees the entry; without this it could join the set again until the Vault's write removed it.
  3. Mac statements follow the peer's declared platform. The code-matched and paired statements show only for a peer whose card says iOS, which is when the add carries the flag; another platform gets the previous text. The authentication reason is one fixed key in the action catalog, so it always names an iPhone.
  4. iPhone tests of the retiring approver flow. ApproverTests and the two "without the flag" tests in ApprovalRequestTests now rewrite the Mac's entry without the flag first (storeWithoutApprovalFlag, default initializer), as a pre-Amend ADR 0014: pairing an iPhone makes it an approver #336 entry. iPhone: retire Approve Requests from This Mac and Stop Approving #342 removes those flows.
  5. Kind 14 test helper. SimulatedPairingPhone.confirmApprover(typing:for:) became sendRetiredApproverConfirmation(to:), used by testARetiredApproverConfirmationIsRefusedAsAnUnexpectedKind. AskKeyDevices: reserve kind 14 and remove the approver code #343 removes it with kind 14. The .confirmation arms, ApproverCode, setApprover and their AskKeyDevices tests stay for AskKeyDevices: reserve kind 14 and remove the approver code #343.
  6. Desktop captures. The Devices captures are now 16 (en 42–43, zh 44–45 replace 42–47); docs/testing.md lists them.
  7. ScreenRenderTests unchanged. Its pairing screens 06, 07, 08 and 10 already show the new statement.
  8. Review fixes beyond the task list (cross review, two rounds): the full reload of the active-approver set after a suspension also skips pairing IDs whose removal began; the Vault treats an entry as stored only when its card matches too, so a write cannot swap the card under a flag; a failed rollback of an add whose session ended is retried from advanceTimers() (DeviceMessenger); and the coordinator tracks pending requests against the set before every addition, so a request whose Broker notification has not arrived stays on the Mac. The review summary follows in a comment.

@luoji-bot

luoji-bot Bot commented Nov 15, 2026

Copy link
Copy Markdown

Cross adversarial review

GPT-6 Astra (xhigh) and Opus 5.5 (xhigh) reviewed this change read-only, two rounds each, at f5ec3be. In round 2 they swapped reports and also reviewed the round 1 fix diff (d06df0b). Neither reported a P0 or P1 in either round. Both checked the same things:

  • the flag is set only by a pairing-authorized iOS add, on both sides;
  • the Vault refuses every other flag write;
  • nothing reachable remains of the approver code on the Mac;
  • the decision 5 statements are present in both languages.

Fixed

Finding Rated Fix Test
Reloading the active-approver set after an account suspension re-added a pairing ID whose removal had begun (write failed or pending). Astra P2; Opus P3 d06df0b: the full reload skips pairing IDs in revokedApprovers, as the per-entry paths already did. testAReloadAfterAnAccountChangeSkipsAPairingWhoseRemovalBegan
The Vault matched a stored entry by device ID and pairing ID only, so a write could swap the card (and the approval key) under a granted flag. Opus P3; Astra agreed d06df0b: an entry counts as stored only when its card matches too, so a swap is an add that needs the pairing authorization and an iOS card. testAWriteCannotSwapTheCardOfAFlaggedEntry
If the rollback of an add whose session ended (Cancel during the write) failed, the flagged entry stayed and came back as an approver at the next launch. Opus P2, P3 in round 2; Astra P2 0852c91: the messenger keeps a failed rollback and retries it from advanceTimers() until it commits. testAFailedRollbackOfAFlaggedAddIsRetriedUntilItCommits
Eligibility was taken when the Broker's notification reached the coordinator. That can be after the first iPhone joined, or never, when the Broker merges notifications. Astra P2; Opus P3 0852c91: before every addition to the set, the coordinator tracks all pending requests against the set as it was. testARequestNotSeenYetWhenTheFirstIPhoneJoinsStaysOnTheMac

Declined

  • Row text while a failed removal is pending (both, P3). After the hook, the iPhone is out of the set while the row still says it can approve. The section already shows "That didn't work. Try again.", and Remove again settles it. A pending-removal row state would be new UI for a rare keychain write failure.
  • Keeping a revocation across a relaunch when a removal the person started keeps failing (both). The retried rollback covers a cancelled pairing within the process. A failed removal is reported, and the entry stays listed and flagged, which matches storage.
  • Recording eligibility inside the Broker at request creation (both, as the complete fix for the notification delay). After 0852c91, only microseconds remain between the reconciliation and the addition. Eligibility also depends on App state (device services, iCloud account) that AskKeyBroker cannot see under ADR 0014's module edges.

The review directories are deleted.

Pairing a macOS initiator with an iOS responder now writes the approval
flag in the add on both sides (ADR 0014, amendment of #336). The Vault
accepts the flag only in an add that pairing authorized for an iOS card
and refuses any change to a stored entry's flag; the approver
authorization is gone.

The Mac adds a newly paired iPhone alone to the Broker's active-approver
set as soon as it learns of the add, and adds any flagged entry missing
from the set at every list read with the services ready and the account
available. A pairing ID whose removal began never joins the set again.
Requests pending before the first pairing stay on the Mac.

The approval switch, the approver sheet, its system authentication,
disableApprover and the confirmation state machine are removed; Remove is
how approval stops. The Mac pairing sheet says before the QR code, and
again before system authentication with what a request sends, that the
iPhone will approve agent requests; the Devices row says whether an
iPhone approves. The iPhone's code screen, Face ID reason and paired
state say the same.

The required flow that clicked the switch is replaced by one that checks
the row's approval text and removes the iPhone (still 18 flows).

Closes #341
Review fixes for #341. Reloading the active-approver set after a
suspension now skips a pairing ID whose removal began, as the per-entry
paths already did, so a removal whose write failed or is pending cannot
come back after an account change. The Vault treats an entry as stored
only when its card matches too, so a write cannot swap the card, and with
it the approval key, under a flag that pairing granted.
Second-round review fixes for #341. When the add of a session that ended
during the write cannot be removed, the messenger keeps the rollback and
retries it from advanceTimers() until it commits, so a cancelled pairing
does not leave a flagged entry behind for the next launch. Before adding
an approver to the active-approver set, the coordinator tracks every
pending request against the set as it was, so a request whose Broker
notification has not arrived yet stays on the Mac.
#340's test pairs a second Mac and expects its request to be refused as
from a Mac without the approval flag. Pairing now sets the flag (#336),
so the test rewrites that entry as a pre-#336 pairing first.
@sudoHG
sudoHG force-pushed the sudoHG/pairing-makes-approver-6cc9a4 branch from 0852c91 to ab63a24 Compare November 15, 2026 14:42
@luoji-bot

luoji-bot Bot commented Nov 15, 2026

Copy link
Copy Markdown

Rebased onto main 650bf0a (after #340 and #352). The new head ab63a24 adds one test fix: #340's testARequestFromAMacWithoutTheApprovalFlagShowsUnavailable now stores that Mac without the flag first. Local results: Devices 221/0, Vault 579/0 (17 skipped), App 836/0 (1 skipped), iOS kit 163/0, extension 44/0, 92 screens.

@sudoHG
sudoHG merged commit 3a735ec into main Nov 15, 2026
4 checks passed
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.

Pairing makes the iPhone an approver: AskKeyDevices, Vault, Mac App and the iPhone's pairing statements

1 participant