From ad2f7b7d040367f4f8505fd5f02091cb98637d12 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Thu, 26 Feb 2026 19:32:42 -0800 Subject: [PATCH] feat(companion): enforce checksum verification in generated launcher --- README.md | 2 ++ docs/api/PROTOCOL.md | 2 +- .../GATEWAY_SESSIONS_AND_QUEUE.md | 1 + docs/operations/COMPANION_RELEASE_BUNDLE.md | 5 ++++ docs/plans/state.json | 20 ++++++++++++++-- src/companion/releaseBundle.test.ts | 1 + src/companion/releaseBundle.ts | 23 +++++++++++++++++++ 7 files changed, 51 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 89bfa9a..41a3696 100644 --- a/README.md +++ b/README.md @@ -1748,6 +1748,8 @@ Minimal companion CLI: - `flynn companion --export-release-bundle ./dist/companion-macos --signing-key ./keys/release-private.pem --signing-key-id team-k1` also writes `CHECKSUMS.sha256.sig` for signed verification workflows. - `flynn companion --platform ios --export-shell-template ./dist/companion-ios-template` writes a platform-native starter template directory (`companion.bootstrap.json`, native starter file, `README.md`) and exits. - `flynn companion --verify-release-bundle ./dist/companion-macos --verify-signing-key ./keys/release-public.pem --verify-signing-key-id team-k1 --require-signature` verifies checksums and signature metadata before install. + +`run-companion.sh` verifies bundle checksums (`CHECKSUMS.sha256`) before launching `flynn companion`. - `flynn companion --once --platform ios --app-version 1.2.3 --device-name "iPhone" --status-text ready --battery-pct 84 --power-source battery` sends richer initial node status metadata. - `flynn companion --once --latitude 37.3349 --longitude -122.009 --location-source gps` bootstraps node location metadata. - `flynn companion --once --platform android --push-token ` (or `--platform ios --push-token `) registers push routing metadata during bootstrap. diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md index a70c97b..16303ef 100644 --- a/docs/api/PROTOCOL.md +++ b/docs/api/PROTOCOL.md @@ -1863,6 +1863,6 @@ For more implementation details, see: - Companion runtime client helper: `src/companion/runtimeClient.ts` (node + system + `canvas.*` typed RPC wrappers, optional `autoConnect`/`autoReconnect`, optional reconnect state replay, `sendAgentMessage` handoff helper, connection event subscriptions) - Platform companion wrappers: `src/companion/platformClients.ts` - Companion bootstrap manifest helper: `src/companion/bootstrapManifest.ts` (typed packaging manifest contract used by `flynn companion --export-bootstrap`, including optional initial status/location/push payloads) -- Companion release bundle helper: `src/companion/releaseBundle.ts` (writes bootstrap JSON + launcher script + README + `CHECKSUMS.sha256`; optional `CHECKSUMS.sha256.sig` when a signing key is provided) +- Companion release bundle helper: `src/companion/releaseBundle.ts` (writes bootstrap JSON + launcher script + README + `CHECKSUMS.sha256`; optional `CHECKSUMS.sha256.sig` when a signing key is provided. Launcher performs checksum verification before exec.) - Companion release bundle verifier: `src/companion/releaseVerify.ts` (validates `CHECKSUMS.sha256` and optional signature metadata against a provided public key) - Companion shell template helper: `src/companion/shellTemplate.ts` (writes platform-native starter template files for `macos`, `ios`, and `android` shell scaffolding) diff --git a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md index 1a65da1..7ea16bb 100644 --- a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md +++ b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md @@ -22,6 +22,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`. - Companion `node.*` registration is per WebSocket connection; reconnects must re-register capabilities before invoking node RPC methods (or use runtime-client reconnect state replay to re-register/status/location/push automatically). - Companion packaging/bootstrap can be generated offline via `flynn companion --export-bootstrap `, which emits resolved gateway/node/runtime settings without opening a WebSocket session. - Companion release artifacts can be generated via `flynn companion --export-release-bundle `, producing bootstrap JSON + launcher + README + `CHECKSUMS.sha256` for installable shell distribution workflows. +- Generated launchers validate `CHECKSUMS.sha256` before invoking `flynn companion`, reducing accidental tampered-bundle launches. - Companion release-bundle exports can optionally be signed (`--signing-key`, `--signing-key-id`) to emit `CHECKSUMS.sha256.sig` for distribution trust verification. - Companion release bundles can be verified before install via `flynn companion --verify-release-bundle ` with optional signature-key checks. - Companion platform starter scaffolds can be generated via `flynn companion --export-shell-template ` for macOS/iOS/Android reference app bootstrapping. diff --git a/docs/operations/COMPANION_RELEASE_BUNDLE.md b/docs/operations/COMPANION_RELEASE_BUNDLE.md index 5fcb2f1..a80ba19 100644 --- a/docs/operations/COMPANION_RELEASE_BUNDLE.md +++ b/docs/operations/COMPANION_RELEASE_BUNDLE.md @@ -84,6 +84,11 @@ flynn companion \ ./run-companion.sh ``` +Launcher behavior: + +- verifies `CHECKSUMS.sha256` before invoking `flynn companion` +- aborts launch on checksum mismatch or missing checksum tooling + Optional handoff smoke test: ```bash diff --git a/docs/plans/state.json b/docs/plans/state.json index a7a5fe7..5ec862d 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -7075,6 +7075,22 @@ "docs/plans/state.json" ], "test_status": "pnpm test:run src/companion/releaseVerify.test.ts src/cli/companion.test.ts src/companion/releaseBundle.test.ts + pnpm typecheck passing" + }, + "personal-assistant-productization-phase1-companion-launcher-integrity-gate": { + "status": "completed", + "date": "2026-02-27", + "updated": "2026-02-27", + "summary": "Hardened companion release launcher behavior: generated `run-companion.sh` now validates `CHECKSUMS.sha256` before executing `flynn companion`, failing closed on mismatch or missing checksum tooling.", + "files_modified": [ + "src/companion/releaseBundle.ts", + "src/companion/releaseBundle.test.ts", + "README.md", + "docs/api/PROTOCOL.md", + "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md", + "docs/operations/COMPANION_RELEASE_BUNDLE.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/companion/releaseBundle.test.ts + pnpm typecheck passing" } }, "overall_progress": { @@ -7093,7 +7109,7 @@ "tier2_completion": "4/4 (100%) — inbound webhooks, vector memory search, Dockerfile, heartbeat monitor", "tier3_completion": "5/5 (100%) — lane queue, credential redaction, web UI token dashboard, xAI (Grok) provider, Voyage AI embeddings", "tier4_completion": "4/4 (100%) — gateway lock, shell completion, Tailscale Serve/Funnel, DM pairing codes", - "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls + platform templates + signed/verified artifacts) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts + checksum manifests + optional signatures + verification mode), companion install/verification runbook, platform starter shell templates for macOS/iOS/Android, and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on production-grade companion app binaries and distribution automation hardening.", + "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls + platform templates + signed/verified artifacts + launcher integrity gate) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts + checksum manifests + optional signatures + verification mode + checksum-gated launcher), companion install/verification runbook, platform starter shell templates for macOS/iOS/Android, and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on production-grade companion app binaries and distribution automation hardening.", "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done", "dashboard_observability": "completed — service health graphs + core service log viewer added to web UI via observability RPCs and bounded backend sampling", "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram", @@ -7126,7 +7142,7 @@ "deeper_surfaces_phase3_companion_canvas_voice": "completed — companion reconnect resilience (auto-reconnect with backoff, pending-wait cancellation on disconnect), canvas artifact persistence (SQLite-backed store, daemon-restart durability), voice TTS fallback coverage (text-only reply on TTS failure, no dropped responses)", "deeper_surfaces_phase4_rollout": "completed — phase 4 rollout and operator readiness plan documented: canary rollout plan by feature flag/surface, explicit rollback playbook, operator docs and architecture/protocol docs synchronized", "post_phase_test_fixes": "completed — fixed 4 test failures introduced by phases 1-3: iOS/Android push listNodes (missing publishHeartbeat before platform-filtered query), server.test agent.send (run_state events now precede done; added sendAndWaitForDone helper), httpBody 413 (req.destroy() closed socket before response could be sent; replaced with Connection: close header on 413 responses)", - "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export, release-bundle artifact generation, checksum manifests, optional signature emission, verification mode, platform starter shell-template generation, and an install/verification runbook, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: production-ready companion app surfaces and distribution automation polish.", + "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export, release-bundle artifact generation, checksum manifests, optional signature emission, verification mode, checksum-gated launchers, platform starter shell-template generation, and an install/verification runbook, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: production-ready companion app surfaces and distribution automation polish.", "subagents_support": "completed — subagent phases 1-3 shipped with `subagent.spawn/send/list/cancel/delete/summary`, per-child queue mode (`followup|interrupt`), budgets (`max_turns`, `max_total_tokens`, `turn_timeout_ms`), tool-profile overrides, trace-linked audit events, `/subagents` inspection commands, and focused regression tests." }, "soul_md_and_cron_create": { diff --git a/src/companion/releaseBundle.test.ts b/src/companion/releaseBundle.test.ts index 1ae5d0f..9681586 100644 --- a/src/companion/releaseBundle.test.ts +++ b/src/companion/releaseBundle.test.ts @@ -59,6 +59,7 @@ describe('writeCompanionReleaseBundle', () => { expect(launcherRaw).toContain('exec flynn'); expect(launcherRaw).toContain('--push-token'); expect(launcherRaw).toContain('--latitude'); + expect(launcherRaw).toContain('sha256sum --check CHECKSUMS.sha256'); expect(readmeRaw).toContain('Flynn Companion Release Bundle'); expect(checksumsRaw).toContain('companion.bootstrap.json'); expect(checksumsRaw).toContain('run-companion.sh'); diff --git a/src/companion/releaseBundle.ts b/src/companion/releaseBundle.ts index c06704b..ba07b3b 100644 --- a/src/companion/releaseBundle.ts +++ b/src/companion/releaseBundle.ts @@ -101,6 +101,29 @@ function createLauncherScript(manifest: CompanionBootstrapManifest): string { set -euo pipefail # Generated by Flynn companion release-bundle export. +bundle_dir="$(cd -- "$(dirname -- "\${BASH_SOURCE[0]}")" && pwd)" +checksums_file="\${bundle_dir}/CHECKSUMS.sha256" +if [[ ! -f "\${checksums_file}" ]]; then + echo "Missing CHECKSUMS.sha256 in \${bundle_dir}" >&2 + exit 1 +fi +if command -v sha256sum >/dev/null 2>&1; then + (cd "\${bundle_dir}" && sha256sum --check CHECKSUMS.sha256) +elif command -v shasum >/dev/null 2>&1; then + while IFS= read -r line; do + [[ -z "\${line}" ]] && continue + expected="\${line%% *}" + file="\${line##* }" + actual="$(shasum -a 256 "\${bundle_dir}/\${file}" | awk '{print $1}')" + if [[ "\${actual}" != "\${expected}" ]]; then + echo "Checksum mismatch for \${file}" >&2 + exit 1 + fi + done <"\${checksums_file}" +else + echo "Neither sha256sum nor shasum is available for checksum verification" >&2 + exit 1 +fi exec flynn ${quotedArgs} \"$@\" `; }