57 lines
4.0 KiB
Markdown
57 lines
4.0 KiB
Markdown
# Package Verification and Inspection Implementation Plan
|
|
|
|
> **For agentic workers:** Execute with test-driven-development; package worker and local inspection work have disjoint write scopes. No commits, production connections, or deployment writes.
|
|
|
|
**Goal:** Add read-only package verification and a factual local prerequisite report to deployctl.
|
|
|
|
**Architecture:** A shared bounded strict JSON decoder supports nested typed arrays. An immutable package verifier returns verified manifest and file bytes, never executes templates. A local probe reports OS/architecture and tool/runtime presence, with unperformed checks explicitly marked unknown.
|
|
|
|
**Tech Stack:** Go standard library. Existing local Windows and Ubuntu WSL test runtimes.
|
|
|
|
**Spec:** docs/2026-09-25-complete-optimization-proposal.md sections 5, 7, 12, 14.
|
|
|
|
## Boundaries and integration
|
|
|
|
- Parent owns internal/wire, internal/inspect, internal/cli, docs and CLI tests.
|
|
- Package worker owns only internal/appbundle; requirements are in package-verifier-brief.md beside this plan.
|
|
- Package code consumes `wire.Decode(reader io.Reader, target any, limit int64) error`.
|
|
- CLI consumes `appbundle.Verify(directory, expectedDigest string) (Verified, error)`; Verified has Manifest, Files map[string][]byte, Digest string. CLI never prints file bodies.
|
|
- Local inspect is not full host acceptance; Docker daemon, Compose, firewall, DNS, permissions and port availability remain explicitly unverified.
|
|
- Expected digest must come from a trusted channel. Matching it does not establish publisher identity on its own.
|
|
|
|
## Task 1: Shared strict wire decoder
|
|
|
|
- [x] Move strict JSON decoder from internal/cli to internal/wire, keeping all CLI tests passing.
|
|
- [x] Add failing tests for nested array unknown/missing/case-alias fields and null elements, duplicate keys and input limit.
|
|
- [x] Extend recursive validation through typed slices and reject invalid UTF-8. Preserve canonical UTC timestamp policy.
|
|
- [x] Test the API `wire.Decode(strings.NewReader(input), &value, 1024)` using real JSON.
|
|
|
|
## Task 2: Application package verifier
|
|
|
|
- [x] Worker implements bounded manifest validation, pinned multi-component images, exact file inventory, SHA-256 content checks and path/symlink rejection using tests first.
|
|
- [x] Parent reviews written code and runs all tests, including Linux symlink cases.
|
|
- [x] Independent review checks all file access and integrity boundaries.
|
|
|
|
## Task 3: Read-only inspection and CLI
|
|
|
|
- [x] internal/inspect provides `Collect() Report` and a testable filesystem probe. Report includes OS, architecture, Linux support, systemd runtime presence and Docker client presence, with explicit unchecked prerequisites.
|
|
- [x] Missing or inaccessible files produce missing/unknown observations, never false success. No shell commands, network, credentials or environment changes.
|
|
- [x] CLI `inspect` emits observations with deploymentReady=false.
|
|
- [x] CLI `verify-package` accepts `{directory, expectedDigest}`, emits manifest, digest, file count and executable=false; rejects invalid input with redacted diagnostics.
|
|
- [x] Add actual CLI tests for new commands and unsupported writes.
|
|
|
|
## Verification
|
|
|
|
- [x] Windows go test/vet, CLI smoke; Linux full tests, race check and build.
|
|
- [x] Record separate implemented, unverified and not-yet-supported capabilities.
|
|
|
|
## Execution notes
|
|
|
|
Task 1 + Task 2 share only the Decode interface; Task 2 must not modify it. Task 3 consumes their exports without exposing package bytes. Directory paths are accepted only for read-only local verification. Files remain subject to trusted staging ownership; future execution must use the verified snapshot rather than reopening mutable package files.
|
|
|
|
Independent review found an alternate Docker path omitted when the primary path
|
|
was invalid or inaccessible. Three failing regression cases reproduced it before
|
|
the fix. Fallback now prefers presence, then uncertainty, invalidity and absence.
|
|
Focused re-review found no remaining issues. Final Windows and Linux checks passed;
|
|
see implementation-status.md for the initial non-reproduced Linux compiler error.
|