feat(notify): add dormant diagnostics credential and pairing foundation

[psimaker]

What & why

Adds the dormant M3 helper credential and pairing foundation after merged M2. The implementation follows the fixed Decision 022 protocol suite while leaving every installed helper and app product path disconnected.

Decision 022 remains unchanged and does not authorize runtime use. This pull request adds no listener, endpoint registration, environment option, installer path, product command, app flow, namespace, probe, Relay call, Syncthing client, deployment, release, or rollout.

Component(s)

• go bridge / Syncthing
• ios tests only
• notify internal core
• architecture documentation
• production configuration or packaging

Dormant boundary

• notify/main.go, Docker configuration, installers, bridge code, and app product sources are unchanged.
• No code opens the credential store or constructs the pairing manager from a product entry point.
• The fixed pairing path exists only as an internal protocol constant; no HTTP client or server uses it.
• Swift coverage is confined to VaultSyncTests.
• No app Keychain service or app credential is implemented.
• Pairing creates no namespace and sets no upload, download, or roundtrip evidence.
• Trigger v1 and Cloud Relay v1 bytes and behavior remain unchanged.
• Windows credential storage fails closed because a diagnostics-specific DACL has not been audited.

Implementation

• Bounded RFC 8949 deterministic-CBOR encoder and decoder with canonical re-encoding.
• Exact Decision 022 message registries, signature domains, signer roles, digest chains, HMAC construction, and message types 0 through 24.
• Ed25519 application/helper signatures, separate P-256 TLS identity, TLS 1.3 SPKI pinning, exact key and binding derivations, and unpadded base64url QR envelopes.
• Dedicated helper state directory with 0700 directory and 0600 file modes on supported Unix systems.
• Atomic temp-file, file sync, rename, and directory sync persistence with process and file locking.
• Symlink, hardlink, ownership, mode, format, trailing-input, and state-integrity rejection.
• Stable homeserver and folder bindings, one pending pairing per folder, four pending helper-wide, and eight installations per folder.
• Pending, finalize, receipt, activate, abort, terminal replay, expiry, and first-request race handling.
• App-key, helper-key, and TLS-pin rotation; signed and local revocation; bounded replay; nonce reuse rejection; whole-state recovery; state-loss isolation; and downgrade preservation.
• No automatic discovery, trust adoption, backup, state creation, or pairing attempt.

Cross-language contract

• A committed fixture contains deterministic bytes for every message type from 0 through 24.
• Go regenerates the complete fixture and checks the exact Decision 022 domains and schemas.
• CryptoKit decodes and re-encodes each byte string, selects the required signer field, verifies every signature, and rejects a mutated signed body.
• The normative bootstrap HMAC vector remains byte-exact.

Local verification

• cd notify && go test ./... -count=1 — passed in 19.636 seconds
• cd notify && go vet ./... — passed
• cd notify && go test -race ./... -count=1 — passed in 26.363 seconds
• cd notify && test -z "$(gofmt -l .)" — passed
• CBOR fuzzing for 10 seconds — passed, 566,456 executions after corpus setup
• pairing decoder fuzzing for 10 seconds — passed, 1,822 executions after corpus setup
• govulncheck v1.6.0 ./... — no vulnerabilities found
• Linux amd64 test compilation — passed
• Windows amd64 test compilation — passed with credential storage intentionally unavailable
• full iOS simulator suite with code signing disabled — 356 tests in 56 suites passed
• Go bridge tests — passed in 58.451 seconds
• Go bridge vulnerability scan — no called vulnerabilities
• design-token lint — passed
• localization parity — 758 identical keys across en/de/es/zh-Hans
• installer dry-run smoke tests — passed without privileged or mutating commands
• git diff --check origin/main...HEAD — passed
• local shellcheck — unavailable on this host; required CI remains authoritative
• local PowerShell parse check — unavailable on this host; required CI remains authoritative
• Linux/NAS/Docker/macOS/Windows packaging and ACL matrix — not claimed
• independent human security and product review — not claimed
• CodeRabbit content review — no actionable comments; 0 review threads
• GitHub Actions PR checks — all required checks passed at exact head 91299437df3d680dc5a13375d30889d045dcb8c4

No signing, archive, Device test, production service call, deployment, helper release, tag, submission, or publication was performed.

Security and privacy review

• The bootstrap secret remains memory-only and is cleared when consumed or expired.
• App private keys are never accepted by or persisted in the helper store.
• The state store contains only the explicitly permitted helper keys, opaque bindings, public authorization material, epochs, bounded replay records, revocation tombstones, and rate state.
• Runtime code emits no pairing log, telemetry, crash annotation, or support-bundle field.
• Cloud Relay receives no pairing, capability, credential, binding, digest, correlation, result, or cleanup data.
• Test fixtures contain deterministic synthetic values only.
• Static scanner warnings were manually adjudicated: pinned TLS intentionally trusts only the QR-delivered SPKI pin; length and CBOR narrowing conversions are explicitly bounded; fixture bytes are deterministic synthetic test values.
• State and protocol input are bounded and fail closed on unknown versions, suites, fields, signer roles, epochs, nonces, transitions, or malformed encoding.
• PRIVACY.md is unchanged because no runtime credential or pairing transport exists; it remains a prerequisite before either is introduced.
• Decision 024 is byte-identical to origin/main.

Existing-user and compatibility impact

App / helper combination	Result
Existing app / existing helper	Unchanged Trigger v1, Relay v1, and passive local evidence
Existing app / helper containing M3 code	Identical product behavior; M3 has no entry point
Future pairing client / existing helper	Capability unavailable; no fallback or mutation
App downgrade	No app credential or state exists to migrate
Helper downgrade	Product behavior remains unchanged; no installed M3 state is created
Re-upgrade	Returns to the same dormant internal foundation

There is no schema migration, automatic state creation, automatic pairing, namespace cleanup, or user-facing rollback action. Repository rollback is a normal revert of the three M3 commits.

Release gate

VaultSync 2.0 remains NO-GO.

The strongest implemented proof remains a fresh successful local file ItemFinished apply after cursor, RFC3339-nanosecond time, and stable engine-generation baselines.

• Upload: not implemented or confirmed.
• Controlled download: not implemented or confirmed.
• Roundtrip: not implemented or confirmed.
• Authenticated correlation: pairing primitives exist only in an unreachable internal foundation; no operation is correlated.
• Helper-first rollout and rollback: not proven.
• Namespace, cleanup, backup, and tombstone behavior: not implemented.
• App credentials and pairing: not implemented in product code.
• Helper rotation, revocation, and whole-state recovery: implemented only in the dormant internal model and local tests.

Owner approval was given on 2026-07-13 for the exact head 91299437df3d680dc5a13375d30889d045dcb8c4 before squash merge.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds a dormant Decision 022 diagnostics pairing foundation with canonical CBOR, cryptographic identities, credential persistence, invitation and lifecycle state handling, Go and Swift golden vectors, extensive tests, and explicit safeguards preventing production runtime activation.

Changes

Diagnostics pairing foundation

Layer / File(s)	Summary
CBOR, protocol, and cryptographic contracts notify/diagnostics_cbor.go, notify/diagnostics_pairing_protocol.go, notify/diagnostics_pairing_crypto.go	Adds canonical constrained CBOR, strict pairing schemas, Ed25519 signatures, HMAC bootstrap checks, QR encoding, identity generation, and pinned TLS validation.
Credential persistence and filesystem protection notify/diagnostics_pairing_store.go, notify/diagnostics_pairing_permissions_*	Adds locked atomic credential persistence, strict state validation, deterministic folder bindings, Unix permission checks, and fail-closed Windows stubs.
Invitation and bootstrap pairing flow notify/diagnostics_pairing_manager.go	Adds invitation creation, app-request acceptance, bootstrap transitions, replay handling, rate limits, expiry checks, and signed responses.
Lifecycle rotation and revocation state machine notify/diagnostics_pairing_lifecycle.go	Adds app-key, helper-key, TLS-pin, finalize, abort, and revocation transitions with digest, nonce, epoch, and replay validation.
Go integration and cross-language validation notify/diagnostics_pairing_test.go, notify/diagnostics_pairing_vectors_test.go, ios/VaultSyncTests/*, docs/architecture.md, notify/diagnostics_contract_model_test.go	Adds persistence, concurrency, lifecycle, fuzz, Go/Swift golden-vector tests, pairing fixtures, runtime-carrier safeguards, and documentation that the implementation is not runtime-wired.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• psimaker/vaultsync#102: Adds the related Decision 022 CBOR, cryptographic pairing, lifecycle, manager, credential-store, and golden-vector implementation.

Poem

CBOR maps in ordered flight,
Keys and pins are checked just right.
Pairing sleeps beyond the door,
Golden vectors guard the core.
Go and Swift compare the tune.

🚥 Pre-merge checks | ✅ 7

✅ Passed checks (7 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
No Private Note Leakage	✅ Passed	PASS: Changed files add only local CBOR/state/test code; no logging, analytics, crash-reporting, or network APIs appear, and privacy tests keep sentinels redacted.
Bounded Ios Background Work	✅ Passed	Only Swift change is a test-only diagnostics pairing suite; no BGTask/expiration/cancel APIs or app background code were modified.
Bridge Contract Compatibility	✅ Passed	PR diff touches notify internals and tests only; go/bridge and SyncBridgeService.swift are unchanged, so the bridge contract stays intact.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title uses a conventional-commit style and accurately summarizes the dormant diagnostics credential and pairing foundation added here.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/m3-helper-credentials-pairing

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[psimaker]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.