aaronrene / knowtation public
docs companion feat/companion-app #4 / 15
aaronrene · 7 days ago · Jun 6, 2026 · Diff

docs(companion): ratify Phase 5 bind gate (sockets/spawn/keychain/download)

Add docs/COMPANION-APP-PHASE-5-BIND-GATE.md — the 🧠 thinking-tier design gate for the first companion phase that performs real I/O. Fixes the contract under which the Phase 5 shell may bind loopback sockets, read the OS keychain, spawn the bundled runtime, and download a model, with each decision argued against an attacker model and defaulting fail-closed.

Decisions (D5.1–D5.8): inference loopback bind (ephemeral, loopback-only, port-secrecy not a control); separate one-shot OAuth redirect listener; minimal device-local keychain adapter (get/set/delete on four accounts, no iCloud sync, no plaintext fallback); hardened spawn (absolute path, no shell, argv, env-scrub, process-group, runtime back-end via UDS 0600 with no authority); dumb HTTPS download wired to Phase 4 integrity accumulator with a first-party out-of-band trust anchor; PID-scoped resource probe that never enumerates other GPU processes; companionAvailable true only when integrity-verified + ready + recent health round-trip; and object-capability segregation enforced by build-blocking architecture/env-scrub tests.

Scope: gate document only, no code. Lifts only the bounded loopback-listener / run-from-source subset of the design gate's "DOES NOT approve" list; packaging, signing, notarization, and auto-update remain Phase 7.

sha256:683f63b336a11fefb83692cbacfa2fe4f5c3b011eef8c4e38b49199f7d858d35 sha
sha256:318515b93ac360aca1898df0968e5dff8c416434a091b5da372ce632745f705a parent
+46 symbols
1 changed · 778 in snapshot files
sha256:b294641872a2c61903b66a5647790c0f6162433cd36da37bdb5e0f4820abaae5 snapshot
+46
symbols added
1
file changed
778
files in snapshot
0
dead code introduced
Semantic Changes 46 symbols
~ docs/COMPANION-APP-PHASE-5-BIND-GATE.md .md 46 symbols added
+ Companion App — Phase 5: Bind Gate (sockets · spawn · keychain · download) section Companion App — Phase 5: Bind Gate (sockets · spawn · keychain · download) L1–605
+ What this gate lifts — and what it deliberately does not section 0. What this gate lifts — and what it deliberately does not L81–102
+ table section table L88–96
+ Adversarial threat model (the bind surface) section 1. Adversarial threat model (the bind surface) L102–124
+ table section table L108–121
+ How Phase 5 discharges the prior phases' deferred obligations section 10. How Phase 5 discharges the prior phases' deferred obligations L540–556
+ table section table L542–550
+ 7-tier test obligations (Phase 5 bind/lifecycle layer) section 11. 7-tier test obligations (Phase 5 bind/lifecycle layer) L556–573
+ table section table L561–570
+ Constraints honored section 12. Constraints honored L573–588
+ Approval table section 13. Approval table L588–605
+ table section table L590–600
+ 1 — Inference loopback socket bind contract section 2. Decision D5.1 — Inference loopback socket bind contract L124–169
+ Decision — OS-assigned ephemeral port, loopback-only, port secrecy is NOT a control section Decision — OS-assigned ephemeral port, loopback-only, port secrecy is NOT a control L137–162
+ Fail-closed section Fail-closed L162–169
+ Verified state section Verified state L129–137
+ 2 — OAuth redirect loopback listener bind section 3. Decision D5.2 — OAuth redirect loopback listener bind L169–212
+ Decision — Separate, short-lived, one-shot ephemeral redirect listener section Decision — Separate, short-lived, one-shot ephemeral redirect listener L183–204
+ Fail-closed section Fail-closed L204–212
+ Verified state section Verified state L174–183
+ 3 — OS-keychain adapter surface section 4. Decision D5.3 — OS-keychain adapter surface L212–266
+ Decision — Exactly `get`/`set`/`delete` on four named accounts; nothing wider; device-local section Decision — Exactly `get`/`set`/`delete` on four named accounts; nothing wider; device-local L224–259
+ Fail-closed section Fail-closed L259–266
+ Verified state section Verified state L217–224
+ 4 — Spawn adapter (process-management surface) section 5. Decision D5.4 — Spawn adapter (process-management surface) L266–333
+ Decision — `spawn` + `kill` + `healthCheck` only; hardened launch; supervised lifetime section Decision — `spawn` + `kill` + `healthCheck` only; hardened launch; supervised lifetime L279–325
+ Fail-closed section Fail-closed L325–333
+ Verified state section Verified state L271–279
+ 5 — Download adapter + Phase 4 integrity wiring section 6. Decision D5.5 — Download adapter + Phase 4 integrity wiring L333–399
+ Decision — Dumb download adapter; accumulator + `finalize()` owned by the orchestrator; trust anchor is a first-party ma section Decision — Dumb download adapter; accumulator + `finalize()` owned by the orchestrator; trust anchor is a first-party ma L348–391
+ Fail-closed section Fail-closed L391–399
+ Verified state section Verified state L339–348
+ 6 — Resource-probe adapter section 7. Decision D5.6 — Resource-probe adapter L399–444
+ Decision — Probe the runtime's own PID; VRAM as aggregate headroom only; never enumerate other processes; no privilege e section Decision — Probe the runtime's own PID; VRAM as aggregate headroom only; never enumerate other processes; no privilege e L410–436
+ Fail-closed section Fail-closed L436–444
+ Verified state section Verified state L404–410
+ 7 — Phase 1 seam activation (companionAvailable) section 8. Decision D5.7 — Phase 1 seam activation (companionAvailable) L444–490
+ Decision — True only when ALL of {integrity-verified ∧ lifecycle `ready` ∧ recent health round-trip} hold; false on any section Decision — True only when ALL of {integrity-verified ∧ lifecycle `ready` ∧ recent health round-trip} hold; false on any L456–483
+ Fail-closed section Fail-closed L483–490
+ Verified state section Verified state L449–456
+ 8 — No-ambient-authority enforcement mechanism section 9. Decision D5.8 — No-ambient-authority enforcement mechanism L490–540
+ Decision — Object-capability segregation, enforced by tests, not convention section Decision — Object-capability segregation, enforced by tests, not convention L502–532
+ Fail-closed section Fail-closed L532–540
+ Verified state section Verified state L495–502
+ Simple summary section Simple summary L32–60
+ Technical summary section Technical summary L60–81
Files Changed
+1
778 in snapshot
+ docs/COMPANION-APP-PHASE-5-BIND-GATE.md .md
Older feat(oauth): implement server-side OAuth C1-C6 for native compan… sha256:318515b93ac360aca1898df0968e5dff8c416434a091b5da372ce632745f705a All commits Newer Implement companion app shell phase 5 sha256:e153fe37739e6625c4875b39ee4bea94c8d20bdb3ff56ce650af0e43f32f3d49

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:683f63b336a11fefb83692cbacfa2fe4f5c3b011eef8c4e38b49199f7d858d35 --body "your comment"