Skip to content

AskKeyDevices: reserve kind 14 and remove the approver code - #357

Merged
sudoHG merged 3 commits into
mainfrom
sudoHG/busy-curie-80be44
Nov 16, 2026
Merged

sudoHG merged 3 commits into
mainfrom
sudoHG/busy-curie-80be44

Conversation

@sudoHG

@sudoHG sudoHG commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Closes #343

Summary

Removes the approver code, its code proof and the approver confirmation (kind 14) from AskKeyDevices, as ADR 0014's #336 amendment (decision 2, Retired, Implementation tasks → 3) specifies, with every use left in the apps and tests.

  • MessageKind drops kind 14 and documents it as reserved. A record of kind 14 is refused as unknownKind from its plaintext kind, before decryption; an inner message of kind 14 inside a record of a known kind is refused when the inner layout is parsed (malformed). Both are exactly what kind 15 gets, in the messenger and in the stateless verifier the notification extension uses.
  • Removed: ApproverCode (file deleted), ApproverConfirmation, ApprovalMessage.confirmation, DeviceMessageSealer.sealApproverConfirmation, the AskKey approver confirmation v1 and AskKey approver code v1 domain labels, and PairedDeviceChange.setApprover. VerifiedApprovalMessage.requestDigest is now non-optional, since it was nil only for a confirmation.
  • The .confirmation arms go from the Mac coordinator, the iPhone app and FakeDeviceServices; comments name kinds 10–13. The Vault's flag rule is unchanged: the flag is accepted only in an add pairing authorized for an iOS card, and any change to a stored entry's flag is refused.

Diff stat

34 files changed, 244 insertions(+), 374 deletions(-): 14 files in Sources/ (one deleted; the Broker file is a comment), 12 test files in Tests/, 6 files in iOS/ (one extension comment, the rest tests and handler arms), one paragraph of ADR 0014 and one sentence of README.

Tests

  • swift build: passed.
  • swift test --filter "AskKeyDevicesTests|AskKeyAppTests|AskKeyVaultTests": AskKeyDevicesTests 219 passed / 0 failed; AskKeyVaultTests 579 executed, 17 skipped, 0 failed; AskKeyAppTests 853 executed, 1 skipped, 0 failed. Against main, AskKeyDevicesTests drops from 221 to 219: three code and confirmation tests (testCodeProofAndConfirmationStatement, testApproverCodeEntryAndRedaction, testConfirmationNotSignedByTheApprovalKeyOverItsStatementIsRefused) are removed and testKind14IsRefusedLikeAnyUnknownKind is added. After the review fixes, AskKeyDevicesTests was rerun: 219 passed / 0 failed. Vault and App counts are unchanged.
  • bash scripts/build-ios.sh test: iPhone kit 163 passed / 0 failed, notification extension 44 passed / 0 failed, 88 screens rendered.

New or rewritten tests:

  • ApprovalRefusalTests.testKind14IsRefusedLikeAnyUnknownKind: for kinds 14 and 15, in both directions, a record of that kind sealed with the sender's real keys (as an older build sealed kind 14) and an inner message of that kind inside a kind 12 or 13 record. Each is checked against the stateless verifier, a poll and a named fetch, and is deleted without effect; a valid receipt sealed by the same helper is processed, as a positive control.
  • ApprovalTransportRuleTests.testRoutingAndTamperingRulesApply gains a "reserved kind 14" case for every approval kind.
  • RemoteApprovalPairingTests.testARecordOfTheRetiredKind14IsRefusedAsAnUnknownKind: the Mac logs exactly one unknownKind refusal and the approver keeps its generation.
  • DeviceApproverFlagTests: the flag-change refusals use direct list writes and adds instead of setApprover (stored flag off, stored entry's flag on, the same write under a fresh pairing authorization), and a refused write leaves the Broker set alone.
  • ApprovalFlowTests: the held-message test now holds a kind 13 receipt under the new pairing instead of a confirmation; the round-trip test covers closed messages and receipts.
  • NotificationProcessorTests.testAMacRemovedWhileTheRecordIsFetchedStaysGeneric replaces the stop-approving race: removal is how approval stops now.

Checks

  • python3 scripts/check_hygiene.py: passed (size=0, test-support=0, debug=0, local-path=0, non-ascii-name=0, multica=0, cjk=0).
  • python3 scripts/check_module_deps.py: passed.
  • git grep -e setApprover -e ApproverCode -e ApproverConfirmation -- ':!docs/adr': no matches.
  • Remaining ADR 0014 vectors (binding digests, receipt ID, decision statements, request vectors) are untouched; only the code proof and confirmation statement vectors are removed.

Deviations and questions

  • The literal grep still finds ADR 0014's amendment. Acceptance 3 says none of setApprover, ApproverCode or ApproverConfirmation remains anywhere in the repository. The only matches left are in ADR 0014's Amend ADR 0014: pairing an iPhone makes it an approver #336 amendment: its Retired list (the list change setApprover) and its Implementation tasks (file and type names such as ApproverConfirmationSheet.swift, ApproverConfirmationFlow, ApproverCode.swift). Those sections record what was retired and how, so this PR keeps their text. It changes only the kind table's note, to say how kind 14 is refused now that the library dropped it.
  • An inner message of kind 14 is refused as malformed, not unknownKind. The record's plaintext kind is checked first and gives unknownKind. An inner kind byte this build does not know fails the inner layout parse, which every unknown inner kind has always reported as malformed. The test pins kind 14 to the same point and the same refusal as kind 15 on both paths, so kind 14 is not special-cased. Reporting an unknown inner kind as unknownKind would change the refusal for every unknown kind and was left out of scope.
  • Small edits beyond the listed files, each removing a stale statement: ApprovalClosedOutcome.cancelled no longer says an approver was "turned off"; the extension's NotificationProcessor.swift comment no longer mentions approval being stopped; LocalizationTests renames a local variable that contained ApproverCode; from the cross review, README's notification paragraph and comments in BrokerApprovalStateMachine+Approvers.swift, ActiveApproverSetTests.swift, ApprovalPayloadTests.swift and ApprovalVectorTests.swift no longer describe the retired switch, kinds 11–14 or the code proof's HMAC.

Pairing makes an iPhone an approver (#336), so the approver code, its
code proof and the approver confirmation (kind 14) are gone from the
protocol library, with every remaining use in the apps and tests.

- MessageKind drops kind 14 and documents it as reserved. A record of
  kind 14 is refused as an unknown kind from its plaintext kind, and an
  inner message of kind 14 when its layout is parsed, at the same point
  and with the same refusal as any other unknown kind.
- Remove ApproverCode, ApproverConfirmation, ApprovalMessage.confirmation,
  sealApproverConfirmation, the two domain labels and
  PairedDeviceChange.setApprover. VerifiedApprovalMessage.requestDigest is
  no longer optional, since every remaining kind carries one.
- The Mac coordinator, the iPhone app and the test support lose their
  .confirmation arms; comments name kinds 10-13.
- Tests: drop the code proof and confirmation statement vectors; add a
  kind 14 refusal test (record and inner message, both directions, the
  messenger and the stateless verifier, compared with kind 15); flagged
  entries come from pairing or @testable access; the Vault's flag rule is
  exercised by direct list writes and adds instead of setApprover.
- ADR 0014 states how kind 14 is refused now that the library dropped it.
- The kind 14 refusal test also runs every case through a named fetch
  (refused, deleted, token and list unchanged, handler never called) and
  checks that the raw-kind helper seals a valid receipt the Mac processes.
- MessageKind and ADR 0014 name both refusals: a kind 14 record as an
  unknown kind, an inner message of kind 14 as malformed, as for any kind
  this build does not know.
- Fix comments that still described kinds 11-14, the HMAC of the removed
  code proof, and the Broker's addition after turning approval on.
README's notification paragraph and a Broker test comment still described
turning approval on and a flag write; pairing makes the approver now.
@luoji-bot

luoji-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

Cross adversarial review (GPT-6 Astra xhigh and Opus 5.5 xhigh, read-only, two rounds each; round 1 on 58b8e43, round 2 on 0531749)

Neither reviewer found a P0 or P1 problem in either round. Both confirmed:

  • no path in any target accepts, seals or produces kind 14, the approver code or the code proof;
  • a kind 14 record (unknownKind) and an inner message of kind 14 (malformed) are refused at the same point and with the same refusal as kind 15;
  • the flag is still settable only through the pairing add;
  • no verification was weakened where a branch was removed;
  • every remaining ADR 0014 vector is unchanged byte for byte.

Fixed

    1. Both reviewers (P2): the kind 14 test did not cover the named fetch. Every kind 14/15 case now also runs through fetchNamedMessages, which must refuse it, delete it and leave the token, the list and the handler alone.
    1. Opus (P3):
    • The MessageKind comment and ADR 0014's note under the kinds table now name both refusals.
    • The raw-kind test helper gets a positive control.
    • Stale comments fixed: "Kinds 11–14", the code proof's HMAC, and the Broker's addition after turning approval on.
  • 7efc357. Astra (P3, round 2): README's notification paragraph and a Broker test comment still described turning approval on and a flag write.

Declined

  • Opus (P3, round 2): ADR 0014's implementation-task text says an inner message of kind 14 is "refused as unknown kinds". That is the amendment's original task text, and the kinds-table note now states the precise rule.
  • Astra (P2, both rounds; Opus ranks it a pre-existing P3): Vault+Devices.swift compares the stored flag only when the card is identical too. A write that keeps the device ID and pairing ID but changes the card is treated as an add, and with the management session and that device's pairing authorization it can change the flag. ADR 0014 (Approvers, Vault write rule) refuses any flag change for the same device ID and pairing ID, without that card condition.
    • Opus adds that the Broker generation survives such a card change.
    • Both reviewers agree that PairingSession never produces it, because the pairing ID is derived from both cards, so only a bug in an app-side writer could reach it.
    • The rule comes from Pairing makes the iPhone an approver: AskKeyDevices, Vault, Mac App and the iPhone's pairing statements #341 and this PR does not touch it.
    • Suggested follow-up issue: refuse an add whose pairing ID is already stored with another card, or end the approver's Broker authority when its card changes; and align the Vault comments and testAWriteCannotSwapTheCardOfAFlaggedEntry.

Head 7efc357. Local results: AskKeyDevicesTests 219/0; AskKeyVaultTests 579/0, 17 skipped; AskKeyAppTests 853/0, 1 skipped; iPhone kit 163/0; extension 44/0; hygiene and module checks pass.

@sudoHG
sudoHG merged commit 1b2ca91 into main Nov 16, 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.

AskKeyDevices: reserve kind 14 and remove the approver code

1 participant