From 2be420ae806c95e5e921c6d797fe236cf8e19a57 Mon Sep 17 00:00:00 2001 From: Adityaaa <144815351+addydude@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:54:28 +0530 Subject: [PATCH 1/5] docs: prepare M4 requirements and acceptance gates --- CHANGELOG.md | 5 +- CONTRIBUTING.md | 4 +- README.md | 11 +- docs/ARCHITECTURE.md | 10 +- docs/DEVELOPMENT-TOOLS.md | 14 ++- docs/PLAN.md | 39 +++++-- docs/adr/0006-m4-reports-and-bundles.md | 68 ++++++++++++ docs/adr/README.md | 3 +- docs/phases/M3.md | 7 +- docs/phases/M4.md | 136 ++++++++++++++++++++++++ 10 files changed, 274 insertions(+), 23 deletions(-) create mode 100644 docs/adr/0006-m4-reports-and-bundles.md create mode 100644 docs/phases/M4.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e5b83c..90392cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and ### Added +- [M4 preparation](docs/phases/M4.md) and [proposed ADR 0006](docs/adr/0006-m4-reports-and-bundles.md) + for terminal/Markdown reports, versioned bounded bundles, redaction and offline evidence. Documentation + only; M4 remains not started. Current status records merged M3 and successful main CI. - M3 rules ENV007–ENV012: known Docker API incompatibility, explicitly required dependency absence, package-manager/lockfile disagreements, effective Git identity/explicit autocrlf policy, canonical virtualenv/interpreter mismatch and opt-in proxy refusal/no-route evidence. @@ -21,7 +24,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and CLI, cancellation and socket lifecycle regressions. - Accepted [ADR 0005](docs/adr/0005-m3-evidence-and-rule-registry.md), [M3 acceptance requirements](docs/phases/M3.md), [validation evidence](docs/testing/m3-validation.md) - and [development-tool audit](docs/DEVELOPMENT-TOOLS.md). M3 is complete on the feature branch; + and [development-tool audit](docs/DEVELOPMENT-TOOLS.md). M3 is complete and merged through PR #3; [CI 43723839978](https://github.com/Shellghostt/EnvDoctor/actions/runs/43723839978) passed native Windows/Ubuntu/macOS race, tests and builds, plus lint and the vulnerability scan. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d139b3e..9462f76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,8 +9,8 @@ Thanks for taking the time. This document is deliberately short and specific. 2. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - how the pieces fit together. 3. [docs/adr/](docs/adr/) - decisions that have already been argued about. Do not relitigate them without a new ADR. -4. [docs/phases/M3.md](docs/phases/M3.md) and [ADR 0005](docs/adr/0005-m3-evidence-and-rule-registry.md) - - implemented M3 evidence contracts and verified three-OS CI gate. +4. [docs/phases/M4.md](docs/phases/M4.md) - planned reports/bundles, dependency order and acceptance gates; + preserve [M3 evidence contracts](docs/phases/M3.md) and accepted ADR 0005. ADR 0006 remains proposed. 5. [docs/DEVELOPMENT-TOOLS.md](docs/DEVELOPMENT-TOOLS.md) - CodeGraph freshness, static-analysis coverage and profiling appropriate to this repository's runtime. diff --git a/README.md b/README.md index 9af01b7..2568d1b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE) ![Go](https://img.shields.io/badge/go-1.26-00ADD8?logo=go&logoColor=white) -**Status: M3 complete on `feat/m3-implementation`; Windows, Ubuntu and macOS CI passed.** +**Status: M1–M3 complete and merged into main; Windows, Ubuntu and macOS CI passed.** Nine collectors feed twelve rules covering platform, shell, PATH, Python/Node runtime, requested TCP ports, effective Git config, local Docker/API metadata, explicit project dependencies and proxy configuration. Reports are plain text or versioned JSON; `explain` and `rules --json` work offline. @@ -241,16 +241,19 @@ goreleaser build --snapshot --clean ## Roadmap -M3 is **complete on the feature branch, including three-OS CI**. Read the +M3 is **complete and merged** through [PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), with +successful [main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915). Read the [M3 acceptance gates](docs/phases/M3.md), [accepted ADR 0005](docs/adr/0005-m3-evidence-and-rule-registry.md) and [validation record](docs/testing/m3-validation.md) for its contracts and evidence. +The [M4 requirements](docs/phases/M4.md) and [proposed report/bundle ADR](docs/adr/0006-m4-reports-and-bundles.md) +prepare the next phase; M4 implementation has not started. | Milestone | Deliverable | Status | |---|---|---| | M1 | CLI foundation, collector interface, system information | **Done** (v0.1.0) | | M2 | Cross-platform collectors and rules ENV001–ENV006 | **Done (merged)** | -| M3 | Rules ENV007–ENV012, Docker/dependency/proxy evidence, offline registry commands | **Done (feature branch, CI passed)** | -| M4 | Polished terminal output, Markdown export, diagnostic bundles | Not started | +| M3 | Rules ENV007–ENV012, Docker/dependency/proxy evidence, offline registry commands | **Done (merged)** | +| M4 | Polished terminal output, Markdown export, diagnostic bundles | Not started; documents prepared | | M5 | Safe, confirmed automated remediation | Not started | | M6 | Windows, Linux, macOS packaging and signed releases | Not started | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2a76f08..79b0e56 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,6 @@ # EnvDoctor Architecture -**Status: M3 complete on the feature branch; three-OS CI passed.** Nine collectors feed +**Status: M1–M3 complete and merged into main; three-OS CI passed.** Nine collectors feed twelve pure rules and a plain-text/JSON report. Offline metadata commands and generated pages share the same rule registry. Bundles, automatic fixes and interactive output remain planned. The authoritative specification is [PLAN.md](PLAN.md); [ADR 0005](adr/0005-m3-evidence-and-rule-registry.md) @@ -91,3 +91,11 @@ Read [phase requirements](phases/M3.md), [ADR 0005](adr/0005-m3-evidence-and-rul and Linux race suites passed locally; native Windows/Ubuntu/macOS tests and race suites also passed in [M3 CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43723839978). [Development tools](DEVELOPMENT-TOOLS.md) records navigation and runtime-profiling coverage. + +## M4 preparation + +[M4 requirements](phases/M4.md) and [proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare +Bubble Tea/plain/Markdown output and bounded versioned bundles. A separate export policy must remove +identifying/free-text data and expose resulting evidence omissions. Offline bundle diagnosis evaluates +captured facts under the current registry without inspecting the receiving machine. These paths are +planned; existing plain/JSON/fixture contracts remain the implemented behavior. diff --git a/docs/DEVELOPMENT-TOOLS.md b/docs/DEVELOPMENT-TOOLS.md index e8db8f6..e0670fe 100644 --- a/docs/DEVELOPMENT-TOOLS.md +++ b/docs/DEVELOPMENT-TOOLS.md @@ -2,7 +2,8 @@ Initial audit: 2026-11-14; M3 verification refresh: 2026-11-15. These are development aids, not product features or substitutes for tests. -Read [PLAN.md](PLAN.md), the [M3 requirements](phases/M3.md) and accepted [ADRs](adr/) first. +Read [PLAN.md](PLAN.md), the [M4 requirements](phases/M4.md), implemented [M3 contract](phases/M3.md) +and accepted [ADRs](adr/) first. M4 ADR 0006 remains proposed. ## CodeGraph @@ -15,6 +16,9 @@ codegraph status codegraph sync ``` +On 2026-11-17, `codegraph status` reported the existing index up to date against merged M3 source. +No new index or generated source was created for M4 preparation. + For indexed code, use the CodeGraph MCP exploration tool with this repository's absolute `projectPath` and the symbol/flow you need. Read its returned source and callers before edits; use direct source/config searches for areas the graph does not capture. Unresolved references remain, @@ -42,6 +46,13 @@ Profile only when the change or suspected fault justifies it; a documentation ed profile, goroutine counts and local diagnosis timings. Those are bounded Go workload measurements; MemGuard/MAT were not treated as Go runtime gates or evidence of universal leak freedom. +## M4 implementation validation + +Use Go heap/RSS/goroutine measurements for repeated archive read/write, rejection, cancellation and +terminal resize/exit. Bound decompression and report buffers independently; use synthetic captures and +measure cleanup after failures. Terminal dependencies remain Go code, so JS static tools do not replace +these checks. M4 resource/renderer evidence is planned, not measured by this documentation pass. + ## Memory Analyzer The locally installed analyzer is Eclipse MAT 1.17.0, configured with Java 21 and a 4 GiB analyzer heap. @@ -55,4 +66,3 @@ State the branch and commit, read the phase/ADRs, refresh the graph after source the exact failing command, output and minimal synthetic fixture. Keep implementation on a feature branch. A skipped integration test must be reported as skipped, with its missing dependency; it is not a passing check. Preserve local Docker volumes and use disposable databases for migration tests. - diff --git a/docs/PLAN.md b/docs/PLAN.md index 66c4d97..e2974b8 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -12,7 +12,7 @@ depends_on: - No runtime dependencies (single static binary) - Docker (optional, only for testing rules that inspect Docker) created: 2026-11-13 -updated: 2026-11-15 +updated: 2026-11-17 --- # EnvDoctor — Implementation Plan @@ -24,12 +24,16 @@ updated: 2026-11-15 ## 0. Machine context -M2 is complete and merged into `main`. M3 is **complete on `feat/m3-implementation`, including -[three-OS CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43723839978)**. +M1–M3 are complete and merged into `main`. [M3 PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3) +merged at `6cf358138ecd3bedf086f22536a30562fb673e4e`; its +[main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915) passed. [ADR 0005](adr/0005-m3-evidence-and-rule-registry.md) was accepted and committed before implementation. The [M3 requirements](phases/M3.md) define the evidence and acceptance contract; [M3 validation](testing/m3-validation.md) records the final commands and limits. The [development-tool audit](DEVELOPMENT-TOOLS.md) records actual coverage and profiling limits. +M4 is **Not started**. [M4 requirements](phases/M4.md) and +[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare report formats, bundle export/redaction +and offline diagnosis; they do not claim new commands or acceptance results. ```yaml project: EnvDoctor @@ -65,6 +69,7 @@ implemented: not_implemented: - diagnostic rules ENV013-ENV018 + - markdown report export - bubble tea output - diagnostic bundles - fixes and undo @@ -295,6 +300,10 @@ Implemented as of M3: `diagnose`, `version`, offline `explain` and `rules`/`rule `bundle` and `fix` remain planned; see section 0 for the authoritative list. Unknown rule IDs and invalid metadata arguments exit 4; output failures exit 3. +M4 format/plain/bundle-input flags and bundle command semantics are proposed in +[ADR 0006](adr/0006-m4-reports-and-bundles.md). They are not implemented. Bundle export must use a +separate sharing policy; ordinary JSON continues to include effective Git identity. + | Exit code | Meaning | |---|---| | 0 | No findings at or above `warning` | @@ -484,7 +493,7 @@ See [testing/m1-m2-validation.md](testing/m1-m2-validation.md) for commands, mea **Deliverable:** rules ENV007–ENV012, Docker and dependency inspectors, `explain` and `rules --json`. -Status: **Complete on `feat/m3-implementation`, including native Windows/Ubuntu/macOS CI.** +Status: **Complete and merged into main**, including native Windows/Ubuntu/macOS CI. Follow [M3 requirements](phases/M3.md), [ADR 0005](adr/0005-m3-evidence-and-rule-registry.md) and [M3 validation](testing/m3-validation.md) for evidence, tests and limits. @@ -511,12 +520,20 @@ tests and records local measurements without claiming M6 clean-host/release cove **Deliverable:** polished terminal output (Bubble Tea when TTY), Markdown export, `bundle` command. +Status: **Not started; documentation prepared.** Follow [M4 requirements](phases/M4.md) and resolve +[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) before dependent code. Bundle input/export has +its own version/redaction/omission policy; copying the current report is not sufficient. + **Acceptance criteria** - [ ] Non-TTY output is plain text, stable, and contains no ANSI codes -- [ ] `envdoctor bundle` produces a zip under 2 MB containing report, redacted snapshot and tool versions -- [ ] Bundle never contains environment variable values, tokens or usernames (test asserts this) -- [ ] A bundle from another machine can be diagnosed offline with `envdoctor diagnose --from-bundle` +- [ ] TTY/NO_COLOR/redirect/format and Markdown escaping cases preserve reports/exits and terminal cleanup +- [ ] `envdoctor bundle` produces a versioned zip below 2,000,000 compressed bytes with independent entry/decompression limits +- [ ] Allowlisted export removes synthetic raw environment values, tokens and identities from every member/error path +- [ ] Removed evidence is explicitly omitted/inconclusive; saved report verdicts never override validated captured evidence +- [ ] Cross-OS `diagnose --from-bundle` runs no collectors, commands or network and preserves capture/evaluator provenance +- [ ] Corrupt/traversal/bomb/duplicate/version/oversize archives and atomic write failures are tested +- [ ] M1–M3 golden/JSON/registry/probe regressions and native CI pass, with all M4 evidence recorded - [ ] One screenshot in the README, taken from a real run ### M5 — Safe remediation @@ -573,8 +590,8 @@ tests and records local measurements without claiming M6 clean-host/release cove | ENV-023A | Opt-in bounded proxy evidence collector and offline-default regression checks | ENV-005 | M3 | | ENV-022 | Rules ENV007–ENV012 | ENV-020, ENV-021, ENV-023A | M3 | | ENV-023 | Rule registry, `explain`, `rules --json` and docs generation | ENV-022 | M3 | -| ENV-024 | Bubble Tea renderer with plain fallback | ENV-019 | M4 | -| ENV-025 | Bundle writer with redaction tests | ENV-005 | M4 | +| ENV-024 | Bubble Tea/plain selection and escaped Markdown export | ENV-019 | M4 | +| ENV-025 | Versioned bounded bundle writer/reader and allowlisted redaction | ENV-005, ENV-024 | M4 | | ENV-026 | `diagnose --from-bundle` | ENV-025 | M4 | | ENV-027 | Fix planner and dry run | ENV-022 | M5 | | ENV-028 | Fix apply, logging and undo | ENV-027 | M5 | @@ -678,7 +695,7 @@ metadata stays unknown. Optional proxy reachability requires explicit opt-in. | Rule | Pure function from snapshot to findings. Has a permanent id. | | Finding | One diagnosis: severity, evidence, cause, fix. | | Fix | A proposed remediation with explicit safety properties. | -| Bundle | A zip of report, snapshot and logs, safe to share publicly. | +| Bundle | Versioned export of redacted captured evidence/reports under a documented sharing policy. | | Degraded | A collector failed; its rules are skipped, not guessed. | --- @@ -688,5 +705,7 @@ metadata stays unknown. Optional proxy reachability requires explicit opt-in. 1. Read sections 0, 3 and 9. Ten minutes. 2. `make build && ./bin/envdoctor diagnose`; compare what it prints with section 0's `functional` field. 3. Pick the next unchecked item in the current milestone. Rules come with fixtures or they do not come. + M4 requirements are in [phases/M4.md](phases/M4.md); ADR 0006 remains proposed. This preparation + authorizes documents only; implementation needs a later request and accepted export/CLI decisions. 4. Run `make test` — golden fixtures will tell you immediately if a rule change broke another platform. 5. Never add a fix without the safety model. If in doubt, print the command instead of running it. diff --git a/docs/adr/0006-m4-reports-and-bundles.md b/docs/adr/0006-m4-reports-and-bundles.md new file mode 100644 index 0000000..714a6e5 --- /dev/null +++ b/docs/adr/0006-m4-reports-and-bundles.md @@ -0,0 +1,68 @@ +# ADR 0006 — M4 report formats and shareable diagnostic evidence + +- Status: proposed; documentation only +- Date: 2026-11-17 +- Required by: [M4 requirements](../phases/M4.md), ENV-024–ENV-026 +- Would extend: ADRs 0004/0005 with a separate bundle export/offline-input contract + +## Context + +M3 plain/JSON reports and fixture-directory diagnosis are implemented. Report JSON intentionally retains +Git identity; home/credential-URL redaction is not a general sharing scrubber. The PLAN requires zip +bundles below 2 MB without raw environment values, tokens or usernames, yet does not specify a format, +decompression limit or how removed evidence affects pure rules. A saved report is not evidence of the +receiving machine, and bundled suggestions are untrusted strings rather than commands to run. + +## Recommended design, pending acceptance + +1. Use one renderer selection path over the existing report. Propose `--format text|markdown|json`, with + current `--json` retained as an alias and an explicit plain choice for terminal use. JSON/Markdown + never enter Bubble Tea. Default non-TTY output stays plain and stable; dumb terminals/NO_COLOR use + plain fallback. Conflicting explicit formats exit 4 before collection. +2. Add a separate versioned allowlisted export model and redaction policy. Export only bounded diagnostic + facts with identifying/free-text fields sanitized or omitted. Generate every report member from that + export. Preserve omissions as explicit evidence limitations; dependent rules cannot treat redaction + as proof that a setting is missing. Existing ordinary JSON/fixture formats remain compatible. +3. Bundle v1 is a zip with manifest, snapshot, JSON/Markdown reports and normalized tool versions; optional + diagnostics are the tool's own allowlisted structured notices. No arbitrary log files are read. + The manifest records capture/tool/schema/redaction versions and member sizes/digests. It is integrity + metadata, not a machine attestation or authentication mechanism. +4. Publish only complete archives below 2,000,000 compressed bytes, at most eight entries and 8 MiB total + decompressed data. Bound each member and JSON parser separately. Reject overflow rather than truncating + evidence or relaxing the budget. Read expected members directly without filesystem extraction. +5. `--from-bundle` evaluates exported captured evidence under the current registry, records capture and + evaluator versions and exposes omissions. It executes no collectors/commands/network work and cannot + trust a saved verdict. Live-evidence flags and fixture input are mutually exclusive with bundle input. +6. Preserve diagnosis exits 0/1/2/3/4. Propose writer exit 0 for a successfully published archive, storing + the capture's own exit code inside it; usage is 4 and archive/tool/I/O failures are 3. Valid offline + diagnosis can still exit 3 for captured degradation or missing required export evidence. + +## Choices that must be resolved before acceptance + +- Field-by-field export schema for all twelve rules, including Git identities, proxy endpoints, runtime + and dependency paths, errors and rule prerequisites. Decide where opaque local replacements preserve + comparison and where omission requires explicit inconclusive evaluation. +- Report/source metadata and schema-version compatibility, capture-local replacement stability, JSON + duplicate/depth/token/string limits and exact manifest/member schemas. Do not alter fixture v1 silently. +- Per-member limits and supported zip methods/features; bounded directory preflight, size/integrity + validation, archive errors and output replacement behavior on Windows and POSIX. +- Final format/plain flags, TTY stream detection, NO_COLOR precedence, cancellation semantics and the + writer-vs-diagnosis exit distinction. Document current JSON behavior before adding new formats. +- Pinned Bubble Tea/terminal dependencies, Markdown escaping, native terminal test method, and whether + optional structured diagnostics can meet the same export policy. Unsupported log export stays absent. + +## Alternatives considered + +- Zip the current report: retains Git identity and unreviewed free text; does not meet bundle policy. +- Remove fields without omission metadata: can turn a real configuration into a false missing-setting + finding or a falsely healthy result when dependent evidence disappears. +- Extract a supplied zip before diagnosis: introduces path/symlink hazards with no need for extraction. +- Run captured verification commands: lets untrusted bundles execute on the maintainer's machine and + confuses captured evidence with a new observation. Pure offline evaluation is sufficient. + +## Consequences and validation + +ENV-024 explicitly includes Markdown. ENV-025 must implement a strict writer and reader plus an evidence +sharing policy before ENV-026 can reuse them. Size/redaction/abuse/cross-OS fixtures, terminal cleanup, +existing JSON/golden/probe regressions and native CI gates are required by the phase document. +This record remains a proposal and does not authorize edits to accepted ADRs or claim implementation. diff --git a/docs/adr/README.md b/docs/adr/README.md index ff673ea..485d16b 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -8,7 +8,8 @@ Each file records one decision that was expensive to make and would be expensive | [0002](0002-m1-implementation-decisions.md) | M1 implementation decisions | accepted, partly superseded by 0003 and 0005 | | [0003](0003-go-126-floor-and-ci-contract.md) | Go 1.26 floor and CI contract | accepted | | [0004](0004-m2-collectors-and-rules.md) | M2 collectors and rules | accepted, scoped extensions in 0005 | -| [0005](0005-m3-evidence-and-rule-registry.md) | M3 evidence, bounded network opt-in and rule metadata | accepted for the M3 feature branch | +| [0005](0005-m3-evidence-and-rule-registry.md) | M3 evidence, bounded network opt-in and rule metadata | accepted; merged M3 | +| [0006](0006-m4-reports-and-bundles.md) | M4 report formats and shareable diagnostic evidence | proposed; no implementation | New ADRs are numbered sequentially and never edited after acceptance. A changed mind gets a new ADR that supersedes the old one. diff --git a/docs/phases/M3.md b/docs/phases/M3.md index fb64f40..2f4ff1b 100644 --- a/docs/phases/M3.md +++ b/docs/phases/M3.md @@ -1,6 +1,8 @@ # M3 requirements: evidence-based rules and inspectors -Status: **Complete on `feat/m3-implementation`, including native Windows/Ubuntu/macOS CI.** +Status: **Complete and merged into main** through [PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), +2026-11-16. Native Windows/Ubuntu/macOS CI and +[main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915) passed. Prepared 2026-11-14 from merged M2 commit `c7e2c84c730edca814a44580cdfc9abaf630b457`. The [plan](../PLAN.md) defines scope; this is its M3 acceptance contract. @@ -86,7 +88,8 @@ The [M1/M2 record](../testing/m1-m2-validation.md) preserves historical results ## Handoff -ENV-020–ENV-023A and all M3 acceptance gates are verified on the feature branch. The recorded CI run +ENV-020–ENV-023A and all M3 acceptance gates are verified and merged. The recorded feature-branch CI run verifies M3 source at `fbf79dd`, including native macOS execution. Follow [development tools](../DEVELOPMENT-TOOLS.md) and provide the branch, fixture/reproducer, exact command and redacted output for debugging in another editor. +Planned report/bundle work is defined by [M4 requirements](M4.md), with ADR 0006 still proposed. diff --git a/docs/phases/M4.md b/docs/phases/M4.md new file mode 100644 index 0000000..a5db8cc --- /dev/null +++ b/docs/phases/M4.md @@ -0,0 +1,136 @@ +# M4 requirements: terminal reports and diagnostic bundles + +Status: **Not started; documentation prepared 2026-11-17.** No M4 command, renderer or test result is claimed. +Baseline: merged M3 main commit `6cf358138ecd3bedf086f22536a30562fb673e4e`, +[PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), with successful +[main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915). +Read the [plan](../PLAN.md), [architecture](../ARCHITECTURE.md), [M3 requirements](M3.md) and +accepted [ADR 0005](../adr/0005-m3-evidence-and-rule-registry.md). +[ADR 0006](../adr/0006-m4-reports-and-bundles.md) is proposed; resolve its export and CLI choices first. + +## Scope and compatibility + +Implement ENV-024–ENV-026: Bubble Tea with a plain fallback, Markdown export, a redacted bundle writer, +and `diagnose --from-bundle`. Include Markdown rendering explicitly in ENV-024; it currently has no +separate backlog item. Rules ENV013–ENV018, fix/apply/undo and signed packaging remain later milestones. + +Preserve the nine collectors, twelve pure rules, immutable registry, evidence prerequisites, generated +rule pages, schema-v1 fixture support, deterministic finding ordering and existing JSON/exit behavior. +Ordinary `--json` still writes one report document to stdout; diagnostics/progress belong on stderr. +Diagnosis applies no fixes. Default collection remains offline, and proxy probing remains an explicit, +bounded live opt-in. No export or offline input enables a command supplied by a bundle. + +## Renderer contract + +- Interactive output is selected only when the required streams are terminals and terminal capabilities + permit it. Define explicit plain-output/format flags, precedence and invalid combinations in ADR 0006. + A redirect, pipe, `TERM=dumb`, `NO_COLOR` or explicit plain choice must have a documented fallback. +- Non-TTY/default plain output remains stable and contains no ANSI/cursor-control codes. JSON and + Markdown bypass Bubble Tea, even in a terminal. Findings/collector failures retain their exit codes. +- Markdown includes severity, rule ID, evidence, limitations, manual suggestions and verification text + from the same report/registry. Escape hostile labels, pipes, HTML, links and backtick/fence sequences; + never turn captured commands or paths into executable behavior or active content. +- Do not present missing/denied/redacted evidence as a healthy result. Show degraded collectors and + skipped rules alongside findings. Export progress/timings must not corrupt stdout formats. +- Resize, cancellation and output failure must restore terminal state and release timers/goroutines. + An interactive rendering failure must have an explicit failure/fallback path, not discard the report. + +## Bundle format and bounds + +The zip is a versioned sharing format, separate from the existing fixture-directory snapshot contract. +Proposed v1 members are `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json` and +optional structured `diagnostics.json`. A manifest records bundle/schema/tool versions, original capture +time, redaction policy, omitted evidence and member names/sizes/digests. Digests detect corruption; +they do not authenticate the machine or its author. + +Retain the PLAN's under-2-MB requirement: define this as **fewer than 2,000,000 compressed bytes**. +The proposal also limits total uncompressed member bytes to 8 MiB and entries to eight, with documented +per-member, JSON-depth/token and string bounds. Enforce limits before allocation/decompression where +possible and while streaming. A too-large capture fails explicitly; no partial archive or silently +truncated evidence is published. Stage output locally and replace it atomically after successful checks. + +Read archives as data without extraction. Reject unsupported versions/methods, encrypted or ZIP64 input +unless explicitly supported, duplicate/unknown member names, directory/symlink entries, absolute paths, +drive/UNC names, backslash paths and traversal. Bound compressed data, directory metadata, decompressed +bytes and parse work independently. Verify member integrity and required schemas before diagnosis. +Never follow member paths, load a plugin, execute a verification/fix command or fetch a URL from a bundle. + +## Export/redaction policy + +Today's report redaction removes home paths and credential-bearing URLs, but retains effective Git +identity. Copying an existing JSON report is not a sharing policy. Define a separate allowlisted export +model before implementation, including the treatment of each field needed by ENV001–ENV012. + +- Exclude raw environment values, tokens, usernames/emails, hostname, original home paths, process + arguments, project file contents and arbitrary logs. Tool versions may be normalized metadata only. +- Sanitize or omit free text, paths, URL components, errors, notices, hints and report metadata before + writing any member. Build report JSON/Markdown from sanitized evidence, rather than embedding the + original report and relying on a final string-replacement pass. +- Preserve diagnostic distinctions where possible with nonidentifying facts or capture-local opaque + replacements. If removing an identity/path loses required evidence, mark it omitted and skip or report + the dependent rule as inconclusive; absence caused by redaction is not proof of a missing setting. +- Apply the same policy to optional tool diagnostics. `--include-logs` must not collect shell history, + arbitrary files or unstructured command output; specify its allowlisted meaning or leave it unsupported. +- Test synthetic secrets/identities through every exported member, entry name, error path and stdout/ + stderr, including encoded URLs, Windows/Unix paths and degraded collectors. An unsupported field + cannot fall back to raw export. Describe the actual policy and its limits; do not promise universal + secret detection or that every arbitrary future string is safe to publish. + +## Offline diagnosis and CLI behavior + +`diagnose --from-bundle FILE` loads validated exported evidence and evaluates the current builtin registry +without running collectors, git/Docker, PATH tools, project scripts or network probes. Do not inspect +the receiving host to fill capture gaps. Retain original capture time/platform and identify captured +evidence, current evaluator version and omissions. Captured findings are reference data; recomputed +findings come from validated evidence, not the saved report's verdict or instructions. + +Keep `--fixture-dir` unchanged. Define mutual exclusion with `--from-bundle` and live-evidence arguments +(`--port`, `--probe-network`, `--package-manager`). Output/evaluation filters may remain available. +Invalid usage exits 4; malformed/unsupported/bounded-out bundles or I/O failure exit 3. Valid offline +diagnosis uses the existing finding/degraded exit mapping 0/1/2/3, including redaction-related omissions. +The proposed writer exits 0 when it successfully publishes an archive; the captured report retains its +own diagnosis exit code, even if degraded. Settle that new-command distinction before coding. + +## Dependency order + +| Task | Work | Prerequisites | +|---|---|---| +| ENV-024 | Renderer selection, plain fallback, Bubble Tea and Markdown | Accepted format/TTY/exit policy; M3 report/registry | +| ENV-025 | Versioned allowlisted export, bounded zip writer/reader and redaction cases | Accepted bundle schema/security policy; ENV-024 report formats | +| ENV-026 | Offline `--from-bundle`, source/omission reporting and CLI tests | ENV-025; accepted evidence/flag/exit semantics | + +## Acceptance and future evidence + +- [ ] Non-TTY, redirected stdout/stderr, dumb terminals, `NO_COLOR`, explicit plain, JSON and Markdown + combinations have deterministic CLI tests; structured output contains no ANSI/progress contamination. +- [ ] A real interactive run handles narrow width, resize, interrupt and output failure without leaving + the terminal altered or retaining goroutines/timers after exit. +- [ ] Markdown goldens cover every severity, collector errors, omitted evidence, hostile HTML/links, + pipes/backticks and long paths, without changing finding order or severity. +- [ ] Every successful bundle is below 2,000,000 compressed bytes; exact boundary/oversize cases, + atomic output failure and independent decompression/entry/parse limits are tested. +- [ ] The export policy removes synthetic tokens, raw environment values and identities from all members + and diagnostics, including Git identity, errors and optional logs; unknown export fields fail closed. +- [ ] Malformed, corrupt, duplicate, traversal/symlink, compressed-bomb and unsupported-version archives + are rejected without extraction or unbounded memory growth. +- [ ] Windows/Linux/macOS captures can be diagnosed on another OS offline; retained evidence reproduces + applicable results while redacted prerequisites remain explicitly inconclusive. +- [ ] Offline diagnosis executes no collectors/commands/network calls, ignores saved verdict instructions, + distinguishes original capture/evaluator versions and rejects conflicting live-evidence flags. +- [ ] Existing 172 golden cases, M3 JSON/schema/exit, registry generation, purity, probe and race gates pass. +- [ ] Terminal dependencies are pinned/audited; canonical build/test/lint/race/docs gates and + native Windows/Ubuntu/macOS CI pass for the final M4 branch. +- [ ] One README screenshot is captured from the implemented interactive CLI with synthetic identities. +- [ ] The eventual M4 validation record maps every criterion to executed cases, commands, limits and skips. + +Use existing `make test`, `make race`, `make lint`, `make build` and `make check-docs`, with Go 1.26.11. +Native Windows race needs the x64 GCC configuration in [M3 validation](../testing/m3-validation.md). +Add archive/redaction/renderer/CLI cases during implementation; they do not exist by virtue of this plan. +Profile repeated bundle read/write, cancellation and renderer lifecycles with synthetic captures, retaining +the existing diagnosis time/memory budgets. Application checks were not rerun for this preparation. + +## Handoff + +First settle the sharing schema and omissions, then the renderer/CLI flags; add reviewed redaction and +archive abuse fixtures before the writer/reader. Preserve accepted ADRs and generated rule pages. +M4 implementation and publication require a later request; this preparation changes documents only. From 32da338b5bca57f687d9da05a3a1e66afdcc2e5e Mon Sep 17 00:00:00 2001 From: Adityaaa <144815351+addydude@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:38:03 +0530 Subject: [PATCH 2/5] docs(adr): accept M4 report and bundle contracts --- CONTRIBUTING.md | 2 +- docs/ARCHITECTURE.md | 4 +- docs/DEVELOPMENT-TOOLS.md | 2 +- docs/PLAN.md | 20 +-- docs/adr/0006-m4-reports-and-bundles.md | 185 +++++++++++++++++------- docs/adr/README.md | 2 +- docs/phases/M4.md | 14 +- 7 files changed, 151 insertions(+), 78 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9462f76..a72520e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Thanks for taking the time. This document is deliberately short and specific. 3. [docs/adr/](docs/adr/) - decisions that have already been argued about. Do not relitigate them without a new ADR. 4. [docs/phases/M4.md](docs/phases/M4.md) - planned reports/bundles, dependency order and acceptance gates; - preserve [M3 evidence contracts](docs/phases/M3.md) and accepted ADR 0005. ADR 0006 remains proposed. + preserve [M3 evidence contracts](docs/phases/M3.md) and accepted ADRs 0005/0006. 5. [docs/DEVELOPMENT-TOOLS.md](docs/DEVELOPMENT-TOOLS.md) - CodeGraph freshness, static-analysis coverage and profiling appropriate to this repository's runtime. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 79b0e56..4794c19 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -94,8 +94,8 @@ and Linux race suites passed locally; native Windows/Ubuntu/macOS tests and race ## M4 preparation -[M4 requirements](phases/M4.md) and [proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare +[M4 requirements](phases/M4.md) and [accepted ADR 0006](adr/0006-m4-reports-and-bundles.md) define Bubble Tea/plain/Markdown output and bounded versioned bundles. A separate export policy must remove identifying/free-text data and expose resulting evidence omissions. Offline bundle diagnosis evaluates captured facts under the current registry without inspecting the receiving machine. These paths are -planned; existing plain/JSON/fixture contracts remain the implemented behavior. +being implemented on `feat/m4-implementation`; existing plain/JSON/fixture contracts remain compatible. diff --git a/docs/DEVELOPMENT-TOOLS.md b/docs/DEVELOPMENT-TOOLS.md index e0670fe..1fcafe9 100644 --- a/docs/DEVELOPMENT-TOOLS.md +++ b/docs/DEVELOPMENT-TOOLS.md @@ -3,7 +3,7 @@ Initial audit: 2026-11-14; M3 verification refresh: 2026-11-15. These are development aids, not product features or substitutes for tests. Read [PLAN.md](PLAN.md), the [M4 requirements](phases/M4.md), implemented [M3 contract](phases/M3.md) -and accepted [ADRs](adr/) first. M4 ADR 0006 remains proposed. +and accepted [ADRs](adr/) first. M4 ADR 0006 is accepted; implementation evidence is still pending. ## CodeGraph diff --git a/docs/PLAN.md b/docs/PLAN.md index e2974b8..9ae0663 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -12,7 +12,7 @@ depends_on: - No runtime dependencies (single static binary) - Docker (optional, only for testing rules that inspect Docker) created: 2026-11-13 -updated: 2026-11-17 +updated: 2026-11-19 --- # EnvDoctor — Implementation Plan @@ -31,9 +31,9 @@ merged at `6cf358138ecd3bedf086f22536a30562fb673e4e`; its was accepted and committed before implementation. The [M3 requirements](phases/M3.md) define the evidence and acceptance contract; [M3 validation](testing/m3-validation.md) records the final commands and limits. The [development-tool audit](DEVELOPMENT-TOOLS.md) records actual coverage and profiling limits. -M4 is **Not started**. [M4 requirements](phases/M4.md) and -[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) prepare report formats, bundle export/redaction -and offline diagnosis; they do not claim new commands or acceptance results. +M4 is **in progress** on `feat/m4-implementation`, including the published preparation commit `2be420a`. +[M4 requirements](phases/M4.md) and accepted [ADR 0006](adr/0006-m4-reports-and-bundles.md) define +formats, allowlisted bundle export and offline diagnosis. No M4 acceptance result is claimed yet. ```yaml project: EnvDoctor @@ -300,8 +300,8 @@ Implemented as of M3: `diagnose`, `version`, offline `explain` and `rules`/`rule `bundle` and `fix` remain planned; see section 0 for the authoritative list. Unknown rule IDs and invalid metadata arguments exit 4; output failures exit 3. -M4 format/plain/bundle-input flags and bundle command semantics are proposed in -[ADR 0006](adr/0006-m4-reports-and-bundles.md). They are not implemented. Bundle export must use a +M4 format/plain/bundle-input flags and bundle command semantics are accepted in +[ADR 0006](adr/0006-m4-reports-and-bundles.md). Implementation is in progress. Bundle export must use a separate sharing policy; ordinary JSON continues to include effective Git identity. | Exit code | Meaning | @@ -520,8 +520,8 @@ tests and records local measurements without claiming M6 clean-host/release cove **Deliverable:** polished terminal output (Bubble Tea when TTY), Markdown export, `bundle` command. -Status: **Not started; documentation prepared.** Follow [M4 requirements](phases/M4.md) and resolve -[proposed ADR 0006](adr/0006-m4-reports-and-bundles.md) before dependent code. Bundle input/export has +Status: **In progress; ADR 0006 accepted before dependent code.** Follow [M4 requirements](phases/M4.md) and +[accepted ADR 0006](adr/0006-m4-reports-and-bundles.md). Bundle input/export has its own version/redaction/omission policy; copying the current report is not sufficient. **Acceptance criteria** @@ -705,7 +705,7 @@ metadata stays unknown. Optional proxy reachability requires explicit opt-in. 1. Read sections 0, 3 and 9. Ten minutes. 2. `make build && ./bin/envdoctor diagnose`; compare what it prints with section 0's `functional` field. 3. Pick the next unchecked item in the current milestone. Rules come with fixtures or they do not come. - M4 requirements are in [phases/M4.md](phases/M4.md); ADR 0006 remains proposed. This preparation - authorizes documents only; implementation needs a later request and accepted export/CLI decisions. + M4 requirements are in [phases/M4.md](phases/M4.md); ADR 0006 is accepted. Implementation was requested + on 2026-11-19; preserve the accepted export/CLI decisions and verify each acceptance gate. 4. Run `make test` — golden fixtures will tell you immediately if a rule change broke another platform. 5. Never add a fix without the safety model. If in doubt, print the command instead of running it. diff --git a/docs/adr/0006-m4-reports-and-bundles.md b/docs/adr/0006-m4-reports-and-bundles.md index 714a6e5..dedc5b3 100644 --- a/docs/adr/0006-m4-reports-and-bundles.md +++ b/docs/adr/0006-m4-reports-and-bundles.md @@ -1,68 +1,141 @@ # ADR 0006 — M4 report formats and shareable diagnostic evidence -- Status: proposed; documentation only -- Date: 2026-11-17 +- Status: accepted +- Proposed: 2026-11-17; accepted: 2026-11-19 - Required by: [M4 requirements](../phases/M4.md), ENV-024–ENV-026 -- Would extend: ADRs 0004/0005 with a separate bundle export/offline-input contract +- Extends: ADRs 0004/0005 with a separate bundle export/offline-input contract ## Context -M3 plain/JSON reports and fixture-directory diagnosis are implemented. Report JSON intentionally retains -Git identity; home/credential-URL redaction is not a general sharing scrubber. The PLAN requires zip -bundles below 2 MB without raw environment values, tokens or usernames, yet does not specify a format, -decompression limit or how removed evidence affects pure rules. A saved report is not evidence of the -receiving machine, and bundled suggestions are untrusted strings rather than commands to run. - -## Recommended design, pending acceptance - -1. Use one renderer selection path over the existing report. Propose `--format text|markdown|json`, with - current `--json` retained as an alias and an explicit plain choice for terminal use. JSON/Markdown - never enter Bubble Tea. Default non-TTY output stays plain and stable; dumb terminals/NO_COLOR use - plain fallback. Conflicting explicit formats exit 4 before collection. -2. Add a separate versioned allowlisted export model and redaction policy. Export only bounded diagnostic - facts with identifying/free-text fields sanitized or omitted. Generate every report member from that - export. Preserve omissions as explicit evidence limitations; dependent rules cannot treat redaction - as proof that a setting is missing. Existing ordinary JSON/fixture formats remain compatible. -3. Bundle v1 is a zip with manifest, snapshot, JSON/Markdown reports and normalized tool versions; optional - diagnostics are the tool's own allowlisted structured notices. No arbitrary log files are read. - The manifest records capture/tool/schema/redaction versions and member sizes/digests. It is integrity - metadata, not a machine attestation or authentication mechanism. -4. Publish only complete archives below 2,000,000 compressed bytes, at most eight entries and 8 MiB total - decompressed data. Bound each member and JSON parser separately. Reject overflow rather than truncating - evidence or relaxing the budget. Read expected members directly without filesystem extraction. -5. `--from-bundle` evaluates exported captured evidence under the current registry, records capture and - evaluator versions and exposes omissions. It executes no collectors/commands/network work and cannot - trust a saved verdict. Live-evidence flags and fixture input are mutually exclusive with bundle input. -6. Preserve diagnosis exits 0/1/2/3/4. Propose writer exit 0 for a successfully published archive, storing - the capture's own exit code inside it; usage is 4 and archive/tool/I/O failures are 3. Valid offline - diagnosis can still exit 3 for captured degradation or missing required export evidence. - -## Choices that must be resolved before acceptance - -- Field-by-field export schema for all twelve rules, including Git identities, proxy endpoints, runtime - and dependency paths, errors and rule prerequisites. Decide where opaque local replacements preserve - comparison and where omission requires explicit inconclusive evaluation. -- Report/source metadata and schema-version compatibility, capture-local replacement stability, JSON - duplicate/depth/token/string limits and exact manifest/member schemas. Do not alter fixture v1 silently. -- Per-member limits and supported zip methods/features; bounded directory preflight, size/integrity - validation, archive errors and output replacement behavior on Windows and POSIX. -- Final format/plain flags, TTY stream detection, NO_COLOR precedence, cancellation semantics and the - writer-vs-diagnosis exit distinction. Document current JSON behavior before adding new formats. -- Pinned Bubble Tea/terminal dependencies, Markdown escaping, native terminal test method, and whether - optional structured diagnostics can meet the same export policy. Unsupported log export stays absent. +M3 plain/JSON reports and fixture-directory diagnosis are implemented. Ordinary JSON intentionally +retains effective Git identity. Home/credential-URL redaction is not a sharing policy. Bundles must be +smaller than 2 MB, remove identifying/raw data and preserve the meaning of absent diagnostic evidence. +Saved reports are reference data, not verdicts or instructions to execute on another machine. + +## Decision + +Implement ENV-024–ENV-026 below. Preserve collectors, twelve builtin rules, registry pages, fixture-v1 +input, ordinary JSON and diagnosis exits. No command in this phase applies a fix. + +### Formats and terminal lifecycle + +- `diagnose --format text|markdown|json` selects an explicit format. `--json` remains a JSON alias. + `--plain` forces text, as does explicit text. `--json --format json` is compatible; conflicting + formats, plain with JSON/Markdown and unknown formats exit 4 before collection. +- Without an explicit format/plain choice, use Bubble Tea only when stdin, stdout **and stderr** are + terminals, TERM is not `dumb`, and NO_COLOR is not set. Missing TERM on Windows does not preclude a + terminal. Pipes, redirects and non-file test streams fall back to stable plain output. JSON/Markdown + bypass the viewer. Verbose collector timings remain on stderr. +- Pin `github.com/charmbracelet/bubbletea v1.3.10` and `golang.org/x/term v0.48.0`; commit exact + transitive module versions/checksums and audit/review licenses before completion. +- The viewer scrolls the completed report, handles narrow dimensions/resize and uses an alternate screen. + Quit returns the diagnosis exit; interruption/render failure returns 3. Every exit restores terminal + state and prints the plain report. Output errors cancel the viewer and propagate as failures. + No viewer action executes advice, collects evidence or changes a finding. +- Text makes terminal controls visible. Markdown emits repository-owned structure and escapes dynamic + punctuation/controls, including HTML, links, fences and commands/paths. Include severity/ID, evidence, + limitations, manual advice/verification, degraded collectors and skipped prerequisites from the same + report/registry. Missing evidence is not displayed as healthy. + +### Separate sharing snapshot + +Bundle snapshots have a separate version-1 typed allowlist. Convert approved facts into existing pure +engine input; generate JSON/Markdown/versions from that evidence, never from saved finding text. + +| Captured field | Sharing representation and rule effect | +|---|---| +| Timestamp/platform | Original UTC capture time; known OS/architecture, elevation and bounded numeric version metadata. Unknown platform stays absent/degraded. | +| Shell | Known shell-name enum; path removed. Unknown names are unavailable with an omission. | +| PATH | Order/existence/directory/duplicate facts; raw locations become capture-local opaque path tokens. | +| Runtimes | Python/Node names, numeric versions, known manager/resolution enums and active/expected/missing facts. Exact path aliases preserve comparisons; separate normalized environment aliases preserve ENV011 equality under the captured OS. | +| Requested ports/listeners | Port/protocol/state facts; PID/process labels omitted. Ownership detail is unavailable while ENV005 can still detect an occupied requested port. | +| Docker | Installed/local probe/API-range/override facts and numeric versions. Selected context names/endpoint URLs omitted; they never select a connection target. | +| Git | Version, identity-checked and nonempty-name/email **presence booleans**, autocrlf policy and opaque origin markers. Reconstruct fixed presence markers for ENV010; redaction is not an unset identity. | +| Dependencies | Supported tool/library names, present/missing/unknown status, opaque paths/project/requirements markers and allowed Git policy. Keep supported package-manager names/exact versions and known lockfile names. | +| Python environment | Metadata-known and capture-local canonical environment tokens; no receiving-host canonicalization or lookup. | +| Proxies | Known variable/scheme/port/probe facts; original host/URL become capture-local `.invalid` aliases. No userinfo, hostname, path, query or fragment. Offline evaluation never resolves/dials aliases. | +| Failures/timings | Known collector identifier, bounded milliseconds and a fixed unavailable notice. Original errors/stdout/stderr/free-text logs omitted. | +| Report/tool metadata | Fixed tool name and normalized version metadata. Captured findings/advice come from the builtin registry after export, not the original report's free text. | + +Aliases are deterministic in field traversal order and local to a capture; they contain no hash or raw +path/identity. They preserve only the documented equality and are not filesystem locations. Omissions +use fixed field/reason identifiers. Removing required evidence marks that collector unavailable and +skips dependent rules under existing prerequisites. Removing non-prerequisite labels stays visible +without fabricating an error. Unknown/future export fields fail closed; unsupported values are omitted +or rejected rather than copied through. + +No raw environment values, tokens, usernames/emails, hostname, home paths, process arguments, project +contents or arbitrary logs are exported. This is a current-field allowlist, not universal secret +detection. Numeric versions/ports, platform and diagnostic facts still describe the captured setup. + +### Bundle v1 and independent bounds + +Required ZIP members: `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json`. +Optional `diagnostics.json`: `bundle --include-logs` means only allowlisted structured collector +statuses/timings, never shell history, files or command output. Every member uses the sharing policy. + +The manifest identifies bundle/snapshot/report/redaction/tool versions, original capture time and +diagnosis exit, omissions, and every other member's exact size/SHA-256. It excludes its own digest. +Digests detect corruption; they do not authenticate a machine/author. The exported report exposes the +original exit as reference metadata and its recomputed exit, including omitted-prerequisite degradation. + +| Limit | Contract | +|---|---| +| Compressed archive, including directory | Fewer than **2,000,000 bytes** | +| Total decompressed members | At most **8 MiB** | +| Entries | At most eight; exactly five required names plus optional diagnostics | +| Manifest / versions | At most 64 KiB each | +| Snapshot / Markdown | At most 2 MiB each | +| JSON report / diagnostics | At most 3 MiB / 512 KiB | +| JSON work | One document; no duplicate/unknown fields; depth ≤32, tokens ≤200,000, strings ≤4,096 UTF-8 bytes; arrays ≤4,096 elements | +| Evidence collections | PATH ≤1,024; runtimes ≤128; listeners/requested ports ≤1,024; dependencies ≤32; proxies ≤3; errors ≤32; omissions ≤256 | + +Preflight file/directory limits before constructing an unbounded ZIP/JSON graph; enforce actual +streamed decompressed sizes. Accept only Store/Deflate regular entries. Reject encryption, +ZIP64/multi-disk/unsupported flags, extra/comment records, duplicate/unknown or nonliteral names, +directories/symlinks, absolute/drive/UNC/backslash/traversal paths, inconsistent local/central headers, +overlaps, size/digest/CRC mismatches and trailing data. Never extract. Validate required structures and +cross-member capture metadata before evaluation. + +An oversized capture fails explicitly without truncation, partial publication or relaxed limits. +Stage a private temporary file beside the requested destination, finish/sync/close and validate it, +then replace the named regular destination by same-directory rename (Windows replacement API). +Never follow a destination symlink. Failure/cancellation removes only the owned temporary file and +keeps the previous destination. Atomic namespace replacement assumes a supporting local filesystem; +network-filesystem semantics and power-loss durability are not guarantees of this format. + +### Commands, provenance and exits + +- `bundle --output FILE` defaults to `envdoctor-bundle.zip`; `-o` is an alias. Existing capture controls + `--fixture-dir`, `--port`, `--probe-network`, `--package-manager` and optional `--include-logs` apply. + It captures the complete builtin report; format/rule filters do not select archive members. + Successful publication exits 0 and prints bounded status/byte count, even for captured warnings/errors/ + degradation. Capture/archive/cancellation/output/I/O failures exit 3; usage exits 4. +- `diagnose --from-bundle FILE` validates and evaluates sharing evidence using the current builtin registry. + It runs no collectors, PATH/Git/Docker/project commands, home/path inspection or network work. Preserve + capture time/platform, label capture-tool/current-evaluator versions, and expose omissions. Saved + verdicts/suggestions/Markdown are reference members and cannot influence evaluation. +- Bundle input conflicts with fixture input and requested-port/network-probe/package-manager live flags. + Format/component/rule/verbose filters remain available. Fixture behavior, including its existing + requested-port selection, stays unchanged. Invalid combinations fail before I/O. +- Malformed/unsupported/bounded-out/corrupt input and read failures exit 3; usage exits 4. Valid offline + evaluation preserves 0/1/2/3, including 3 for unavailable required evidence. Bundle errors have fixed + reason text and do not interpolate untrusted fields/member names/captured errors. +- Ordinary JSON remains schema v1 with existing fields/values and Git identity. Optional bundle-source + metadata is absent from ordinary runs and documented as a compatible report-schema addition. ## Alternatives considered -- Zip the current report: retains Git identity and unreviewed free text; does not meet bundle policy. -- Remove fields without omission metadata: can turn a real configuration into a false missing-setting - finding or a falsely healthy result when dependent evidence disappears. -- Extract a supplied zip before diagnosis: introduces path/symlink hazards with no need for extraction. -- Run captured verification commands: lets untrusted bundles execute on the maintainer's machine and - confuses captured evidence with a new observation. Pure offline evaluation is sufficient. +- Zip ordinary JSON: retains identity/unreviewed free text and fails the sharing contract. +- Remove paths/identities without presence/equality/omissions: causes false missing-setting or healthy results. +- Extract ZIP or run captured commands: unnecessary filesystem/execution authority; pure evaluation suffices. +- Reuse saved verdicts: loses evaluator provenance and turns untrusted instructions into findings. ## Consequences and validation -ENV-024 explicitly includes Markdown. ENV-025 must implement a strict writer and reader plus an evidence -sharing policy before ENV-026 can reuse them. Size/redaction/abuse/cross-OS fixtures, terminal cleanup, -existing JSON/golden/probe regressions and native CI gates are required by the phase document. -This record remains a proposal and does not authorize edits to accepted ADRs or claim implementation. +Renderer/Markdown cases precede export. Add reviewed redaction/archive-abuse cases before writer/reader +and offline CLI. Verify all original 172 cases, strict schemas, deterministic cross-OS evidence, privacy +across every member/error, exact size boundaries and rejection cleanup. Measure repeated archive/viewer +lifecycles using synthetic captures. Record native terminal/Windows/Ubuntu/macOS CI, dependency/licenses +and a real interactive screenshot separately from cross-builds/model-only tests. Check acceptance boxes +only after named evidence exists. diff --git a/docs/adr/README.md b/docs/adr/README.md index 485d16b..ae1361b 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -9,7 +9,7 @@ Each file records one decision that was expensive to make and would be expensive | [0003](0003-go-126-floor-and-ci-contract.md) | Go 1.26 floor and CI contract | accepted | | [0004](0004-m2-collectors-and-rules.md) | M2 collectors and rules | accepted, scoped extensions in 0005 | | [0005](0005-m3-evidence-and-rule-registry.md) | M3 evidence, bounded network opt-in and rule metadata | accepted; merged M3 | -| [0006](0006-m4-reports-and-bundles.md) | M4 report formats and shareable diagnostic evidence | proposed; no implementation | +| [0006](0006-m4-reports-and-bundles.md) | M4 report formats and shareable diagnostic evidence | accepted; implementation in progress | New ADRs are numbered sequentially and never edited after acceptance. A changed mind gets a new ADR that supersedes the old one. diff --git a/docs/phases/M4.md b/docs/phases/M4.md index a5db8cc..63f2e74 100644 --- a/docs/phases/M4.md +++ b/docs/phases/M4.md @@ -1,12 +1,12 @@ # M4 requirements: terminal reports and diagnostic bundles -Status: **Not started; documentation prepared 2026-11-17.** No M4 command, renderer or test result is claimed. +Status: **In progress on `feat/m4-implementation`, 2026-11-19.** No M4 acceptance result is claimed yet. Baseline: merged M3 main commit `6cf358138ecd3bedf086f22536a30562fb673e4e`, [PR #3](https://github.com/Shellghostt/EnvDoctor/pull/3), with successful [main CI](https://github.com/Shellghostt/EnvDoctor/actions/runs/43802280915). Read the [plan](../PLAN.md), [architecture](../ARCHITECTURE.md), [M3 requirements](M3.md) and accepted [ADR 0005](../adr/0005-m3-evidence-and-rule-registry.md). -[ADR 0006](../adr/0006-m4-reports-and-bundles.md) is proposed; resolve its export and CLI choices first. +[ADR 0006](../adr/0006-m4-reports-and-bundles.md) was accepted before dependent implementation. ## Scope and compatibility @@ -38,13 +38,13 @@ bounded live opt-in. No export or offline input enables a command supplied by a ## Bundle format and bounds The zip is a versioned sharing format, separate from the existing fixture-directory snapshot contract. -Proposed v1 members are `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json` and +Accepted v1 members are `manifest.json`, `snapshot.json`, `report.json`, `report.md`, `versions.json` and optional structured `diagnostics.json`. A manifest records bundle/schema/tool versions, original capture time, redaction policy, omitted evidence and member names/sizes/digests. Digests detect corruption; they do not authenticate the machine or its author. Retain the PLAN's under-2-MB requirement: define this as **fewer than 2,000,000 compressed bytes**. -The proposal also limits total uncompressed member bytes to 8 MiB and entries to eight, with documented +ADR 0006 also limits total uncompressed member bytes to 8 MiB and entries to eight, with documented per-member, JSON-depth/token and string bounds. Enforce limits before allocation/decompression where possible and while streaming. A too-large capture fails explicitly; no partial archive or silently truncated evidence is published. Stage output locally and replace it atomically after successful checks. @@ -88,8 +88,8 @@ Keep `--fixture-dir` unchanged. Define mutual exclusion with `--from-bundle` and (`--port`, `--probe-network`, `--package-manager`). Output/evaluation filters may remain available. Invalid usage exits 4; malformed/unsupported/bounded-out bundles or I/O failure exit 3. Valid offline diagnosis uses the existing finding/degraded exit mapping 0/1/2/3, including redaction-related omissions. -The proposed writer exits 0 when it successfully publishes an archive; the captured report retains its -own diagnosis exit code, even if degraded. Settle that new-command distinction before coding. +The writer exits 0 when it successfully publishes an archive. The original diagnosis exit remains +reference metadata; the exported report records its recomputed exit, including omitted prerequisites. ## Dependency order @@ -133,4 +133,4 @@ the existing diagnosis time/memory budgets. Application checks were not rerun fo First settle the sharing schema and omissions, then the renderer/CLI flags; add reviewed redaction and archive abuse fixtures before the writer/reader. Preserve accepted ADRs and generated rule pages. -M4 implementation and publication require a later request; this preparation changes documents only. +M4 implementation was requested on 2026-11-19. Publication/CI remains separate acceptance work. From c532dc33bd16271fb19298cf600a5dd6b05cceb9 Mon Sep 17 00:00:00 2001 From: Adityaaa <144815351+addydude@users.noreply.github.com> Date: Thu, 19 Nov 2026 04:19:27 +0530 Subject: [PATCH 3/5] feat(m4): add terminal reports and redacted offline bundles --- cmd/envdoctor/main.go | 16 +- docs/images/m4-terminal.jpg | Bin 0 -> 67960 bytes docs/schema/bundle-common-v1.schema.json | 238 +++++++ docs/schema/bundle-diagnostics-v1.schema.json | 46 ++ docs/schema/bundle-manifest-v1.schema.json | 85 +++ docs/schema/bundle-report-v1.schema.json | 37 ++ docs/schema/bundle-snapshot-v1.schema.json | 627 ++++++++++++++++++ docs/schema/bundle-versions-v1.schema.json | 50 ++ docs/schema/diagnose-v1.schema.json | 111 +++- docs/testing/fixtures/m4-viewer/snapshot.json | 21 + go.mod | 21 +- go.sum | 47 +- internal/bundle/archive.go | 385 +++++++++++ internal/bundle/archive_test.go | 326 +++++++++ internal/bundle/compression_test.go | 132 ++++ internal/bundle/export.go | 528 +++++++++++++++ internal/bundle/export_test.go | 161 +++++ internal/bundle/file.go | 130 ++++ internal/bundle/file_test.go | 104 +++ internal/bundle/file_unix.go | 8 + internal/bundle/file_windows.go | 39 ++ internal/bundle/file_windows_test.go | 65 ++ internal/bundle/json.go | 196 ++++++ internal/bundle/model.go | 198 ++++++ internal/bundle/model_coverage.go | 47 ++ internal/bundle/parser_test.go | 65 ++ internal/bundle/roundtrip_test.go | 213 ++++++ internal/bundle/schema_test.go | 129 ++++ internal/bundle/validate.go | 274 ++++++++ internal/cli/bundle.go | 61 ++ internal/cli/cli.go | 84 ++- internal/cli/diagnose.go | 117 +++- internal/cli/m4_test.go | 330 +++++++++ internal/config/config.go | 4 + internal/report/document.go | 16 + internal/report/format.go | 70 ++ internal/report/interactive.go | 230 +++++++ internal/report/interactive_test.go | 167 +++++ internal/report/json.go | 16 +- internal/report/m4_test.go | 144 ++++ internal/report/markdown.go | 155 +++++ internal/report/testdata/markdown-m4.golden | 54 ++ internal/report/text.go | 12 +- tests/terminal/main_windows.go | 150 +++++ 44 files changed, 5853 insertions(+), 56 deletions(-) create mode 100644 docs/images/m4-terminal.jpg create mode 100644 docs/schema/bundle-common-v1.schema.json create mode 100644 docs/schema/bundle-diagnostics-v1.schema.json create mode 100644 docs/schema/bundle-manifest-v1.schema.json create mode 100644 docs/schema/bundle-report-v1.schema.json create mode 100644 docs/schema/bundle-snapshot-v1.schema.json create mode 100644 docs/schema/bundle-versions-v1.schema.json create mode 100644 docs/testing/fixtures/m4-viewer/snapshot.json create mode 100644 internal/bundle/archive.go create mode 100644 internal/bundle/archive_test.go create mode 100644 internal/bundle/compression_test.go create mode 100644 internal/bundle/export.go create mode 100644 internal/bundle/export_test.go create mode 100644 internal/bundle/file.go create mode 100644 internal/bundle/file_test.go create mode 100644 internal/bundle/file_unix.go create mode 100644 internal/bundle/file_windows.go create mode 100644 internal/bundle/file_windows_test.go create mode 100644 internal/bundle/json.go create mode 100644 internal/bundle/model.go create mode 100644 internal/bundle/model_coverage.go create mode 100644 internal/bundle/parser_test.go create mode 100644 internal/bundle/roundtrip_test.go create mode 100644 internal/bundle/schema_test.go create mode 100644 internal/bundle/validate.go create mode 100644 internal/cli/bundle.go create mode 100644 internal/cli/m4_test.go create mode 100644 internal/report/format.go create mode 100644 internal/report/interactive.go create mode 100644 internal/report/interactive_test.go create mode 100644 internal/report/m4_test.go create mode 100644 internal/report/markdown.go create mode 100644 internal/report/testdata/markdown-m4.golden create mode 100644 tests/terminal/main_windows.go diff --git a/cmd/envdoctor/main.go b/cmd/envdoctor/main.go index 3646498..7c21c78 100644 --- a/cmd/envdoctor/main.go +++ b/cmd/envdoctor/main.go @@ -6,7 +6,10 @@ package main import ( + "context" "os" + "os/signal" + "syscall" "github.com/shellghostt/envdoctor/internal/cli" ) @@ -17,10 +20,15 @@ import ( var version = "dev" func main() { + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() os.Exit(cli.Main(os.Args, cli.App{ - Version: version, - Stdout: os.Stdout, - Stderr: os.Stderr, - Getenv: os.Getenv, + Version: version, + Stdin: os.Stdin, + Stdout: os.Stdout, + Stderr: os.Stderr, + Getenv: os.Getenv, + LookupEnv: os.LookupEnv, + Context: ctx, })) } diff --git a/docs/images/m4-terminal.jpg b/docs/images/m4-terminal.jpg new file mode 100644 index 0000000000000000000000000000000000000000..91d20d86e19a0e99e3cf460eed59193a8483d052 GIT binary patch literal 67960 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ⓈEx%>gxaI&>y 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 MaxArchiveBytes-b.Len() { + return 0, ErrBounds + } + return b.buffer.Write(data) +} + +func marshalMember(ctx context.Context, name string, value any) ([]byte, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + data, err := json.Marshal(value) + if err != nil { + return nil, ErrEvidence + } + if len(data) > memberLimits[name] { + return nil, ErrBounds + } + return data, nil +} + +// Build recomputes all report members from the sharing model with the builtin +// engine. It never zips the original document, findings, errors or log text. +func Build(ctx context.Context, original report.Document, opts Options) ([]byte, error) { + snapshot, source, timings, diags, err := export(ctx, original) + if err != nil { + return nil, err + } + if err := validateSnapshot(snapshot); err != nil { + return nil, err + } + evidence := engineSnapshot(snapshot) + findings, err := diagnostic.DefaultEngine().Evaluate(evidence, diagnostic.Filter{}) + if err != nil { + return nil, ErrEvidence + } + doc := report.NewDocument(source.CaptureTool.Version, source.CapturedAt, evidence, findings, timings, len(diagnostic.BuiltinMetadata())) + doc.Source = &source + all := map[string][]byte{} + for _, member := range []struct { + name string + value any + }{{"snapshot.json", snapshot}, {"report.json", doc}, {"versions.json", makeVersions(snapshot, source.CaptureTool)}} { + all[member.name], err = marshalMember(ctx, member.name, member.value) + if err != nil { + return nil, err + } + } + var markdown bytes.Buffer + if err := report.WriteMarkdown(&markdown, doc); err != nil { + return nil, ErrBounds + } + all["report.md"] = markdown.Bytes() + if opts.IncludeLogs { + all["diagnostics.json"], err = marshalMember(ctx, "diagnostics.json", diags) + if err != nil { + return nil, err + } + } + manifest := Manifest{BundleVersion: 1, SnapshotVersion: 1, ReportVersion: 1, RedactionPolicy: Policy, Tool: source.CaptureTool, CapturedAt: source.CapturedAt, CaptureExitCode: source.CaptureExitCode, Omissions: source.Omissions, Members: []Member{}} + names := []string{"manifest.json", "snapshot.json", "report.json", "report.md", "versions.json"} + if opts.IncludeLogs { + names = append(names, "diagnostics.json") + } + total := 0 + for _, name := range names[1:] { + body := all[name] + digest := sha256.Sum256(body) + manifest.Members = append(manifest.Members, Member{Name: name, Size: len(body), SHA256: hex.EncodeToString(digest[:])}) + total += len(body) + } + all["manifest.json"], err = marshalMember(ctx, "manifest.json", manifest) + if err != nil { + return nil, err + } + if total+len(all["manifest.json"]) > MaxUncompressedBytes { + return nil, ErrBounds + } + out := archiveBuffer{ctx: ctx} + w := zip.NewWriter(&out) + for _, name := range names { + header := &zip.FileHeader{Name: name, Method: zip.Deflate} + // No extended timestamp/extra/comment records or platform paths. + header.SetMode(0600) + stream, err := w.CreateHeader(header) + if err != nil { + return nil, err + } + if _, err := stream.Write(all[name]); err != nil { + return nil, err + } + } + if err := w.Close(); err != nil { + return nil, err + } + data := out.Bytes() + if _, err := Read(ctx, data); err != nil { + return nil, err + } + return data, nil +} + +type zipEntry struct { + name string + offset, compressed, uncompressed int + crc uint32 + flags, method uint16 + version, modifiedTime, modifiedDate uint16 +} + +// Preflight the entire directory and every local record BEFORE archive/zip can +// allocate its file graph. Offsets must describe one exact nonoverlapping ZIP, +// without a prefix, trailing records, extras, ZIP64 or another disk. +func preflight(data []byte) ([]zipEntry, error) { + if len(data) >= MaxArchiveBytes { + return nil, ErrBounds + } + if len(data) < 22 { + return nil, ErrInvalid + } + eocd := len(data) - 22 + end := data[eocd:] + u16 := binary.LittleEndian.Uint16 + u32 := binary.LittleEndian.Uint32 + if u32(end) != 0x06054b50 || u16(end[4:]) != 0 || u16(end[6:]) != 0 || u16(end[20:]) != 0 { + return nil, ErrInvalid + } + count := int(u16(end[10:])) + if count > MaxEntries { + return nil, ErrBounds + } + if count < 5 || count != int(u16(end[8:])) { + return nil, ErrInvalid + } + dirSize, dirStart := uint64(u32(end[12:])), uint64(u32(end[16:])) + if dirStart+dirSize != uint64(eocd) || dirStart > uint64(eocd) { + return nil, ErrInvalid + } + position := int(dirStart) + entries := make([]zipEntry, 0, count) + seen := map[string]bool{} + total := 0 + for i := 0; i < count; i++ { + if position > eocd-46 { + return nil, ErrInvalid + } + h := data[position : position+46] + if u32(h) != 0x02014b50 || u16(h[6:]) != 10 && u16(h[6:]) != 20 || u16(h[34:]) != 0 { + return nil, ErrInvalid + } + flags, method := u16(h[8:]), u16(h[10:]) + if flags & ^uint16(0x0808) != 0 || method != zip.Store && method != zip.Deflate { + return nil, ErrInvalid + } + if method == zip.Deflate && u16(h[6:]) != 20 { + return nil, ErrInvalid + } + nameSize, extraSize, commentSize := int(u16(h[28:])), int(u16(h[30:])), int(u16(h[32:])) + if extraSize != 0 || commentSize != 0 || nameSize < 1 || nameSize > 16 || position+46+nameSize > eocd { + return nil, ErrInvalid + } + name := string(data[position+46 : position+46+nameSize]) + limit, ok := memberLimits[name] + if !ok || seen[name] { + return nil, ErrInvalid + } + seen[name] = true + creator := u16(h[4:]) + if creator>>8 != 0 && creator>>8 != 3 { + return nil, ErrInvalid + } + mode := (&zip.FileHeader{Name: name, CreatorVersion: creator, ExternalAttrs: u32(h[38:])}).Mode() + if !mode.IsRegular() { + return nil, ErrInvalid + } + attrs := u32(h[38:]) + if creator>>8 == 0 && attrs>>16 != 0 || creator>>8 == 3 && attrs>>28 != 0 && attrs>>28 != 8 || attrs&0x18 != 0 { + return nil, ErrInvalid + } + compressed, uncompressed, offset := uint64(u32(h[20:])), uint64(u32(h[24:])), uint64(u32(h[42:])) + if uncompressed > uint64(limit) || compressed >= MaxArchiveBytes { + return nil, ErrBounds + } + if method == zip.Store && compressed != uncompressed { + return nil, ErrIntegrity + } + if offset > dirStart || offset+30+uint64(nameSize)+compressed > dirStart { + return nil, ErrInvalid + } + total += int(uncompressed) + if total > MaxUncompressedBytes { + return nil, ErrBounds + } + entries = append(entries, zipEntry{name: name, offset: int(offset), compressed: int(compressed), uncompressed: int(uncompressed), crc: u32(h[16:]), flags: flags, method: method, version: u16(h[6:]), modifiedTime: u16(h[12:]), modifiedDate: u16(h[14:])}) + position += 46 + nameSize + } + if position != eocd { + return nil, ErrInvalid + } + for _, name := range requiredMembers { + if !seen[name] { + return nil, ErrInvalid + } + } + sort.Slice(entries, func(i, j int) bool { return entries[i].offset < entries[j].offset }) + position = 0 + for _, entry := range entries { + if entry.offset != position || position > int(dirStart)-30 { + return nil, ErrInvalid + } + h := data[position : position+30] + if u32(h) != 0x04034b50 || u16(h[4:]) != entry.version || u16(h[6:]) != entry.flags || u16(h[8:]) != entry.method || u16(h[10:]) != entry.modifiedTime || u16(h[12:]) != entry.modifiedDate || int(u16(h[26:])) != len(entry.name) || u16(h[28:]) != 0 { + return nil, ErrInvalid + } + if string(data[position+30:position+30+len(entry.name)]) != entry.name { + return nil, ErrInvalid + } + if entry.flags&8 == 0 { + if u32(h[14:]) != entry.crc || u32(h[18:]) != uint32(entry.compressed) || u32(h[22:]) != uint32(entry.uncompressed) { + return nil, ErrIntegrity + } + } else { + if u32(h[14:]) != 0 && u32(h[14:]) != entry.crc || u32(h[18:]) != 0 && u32(h[18:]) != uint32(entry.compressed) || u32(h[22:]) != 0 && u32(h[22:]) != uint32(entry.uncompressed) { + return nil, ErrIntegrity + } + } + position += 30 + len(entry.name) + entry.compressed + if entry.flags&8 != 0 { + if position > int(dirStart)-12 { + return nil, ErrInvalid + } + if u32(data[position:]) == 0x08074b50 { + position += 4 + } + if position > int(dirStart)-12 { + return nil, ErrInvalid + } + if u32(data[position:]) != entry.crc || u32(data[position+4:]) != uint32(entry.compressed) || u32(data[position+8:]) != uint32(entry.uncompressed) { + return nil, ErrIntegrity + } + position += 12 + } + } + if position != int(dirStart) { + return nil, ErrInvalid + } + return entries, nil +} + +type contextReader struct { + ctx context.Context + input io.Reader +} + +// Implement flate.Reader's byte method so the inflater cannot read ahead and +// hide garbage after a complete Deflate stream inside its compressed extent. +type compressedReader struct { + ctx context.Context + reader *bytes.Reader +} + +func (r compressedReader) Read(p []byte) (int, error) { + if err := r.ctx.Err(); err != nil { + return 0, err + } + return r.reader.Read(p) +} +func (r compressedReader) ReadByte() (byte, error) { + if err := r.ctx.Err(); err != nil { + return 0, err + } + return r.reader.ReadByte() +} + +func (r contextReader) Read(data []byte) (int, error) { + if err := r.ctx.Err(); err != nil { + return 0, err + } + return r.input.Read(data) +} + +// Read validates all archive/reference members but returns only typed evidence +// and provenance. No saved verdict, Markdown, command or URL is returned. +func Read(ctx context.Context, data []byte) (Capture, error) { + if err := ctx.Err(); err != nil { + return Capture{}, err + } + entries, err := preflight(data) + if err != nil { + return Capture{}, err + } + all := make(map[string][]byte, len(entries)) + total := 0 + for _, entry := range entries { + if err := ctx.Err(); err != nil { + return Capture{}, err + } + start := entry.offset + 30 + len(entry.name) + compressed := compressedReader{ctx: ctx, reader: bytes.NewReader(data[start : start+entry.compressed])} + stream := io.NopCloser(io.Reader(compressed)) + if entry.method == zip.Deflate { + stream = flate.NewReader(compressed) + } + body, readErr := io.ReadAll(io.LimitReader(stream, int64(entry.uncompressed)+1)) + closeErr := stream.Close() + if err := ctx.Err(); err != nil { + return Capture{}, err + } + if len(body) > memberLimits[entry.name] || total+len(body) > MaxUncompressedBytes { + return Capture{}, ErrBounds + } + if readErr != nil || closeErr != nil || len(body) != entry.uncompressed || compressed.reader.Len() != 0 || crc32.ChecksumIEEE(body) != entry.crc { + return Capture{}, ErrIntegrity + } + all[entry.name] = body + total += len(body) + } + var manifest Manifest + if !utf8.Valid(all["report.md"]) { + return Capture{}, ErrInvalid + } + if err := decodeJSON(ctx, all["manifest.json"], &manifest); err != nil { + return Capture{}, err + } + if err := validateManifest(manifest, all); err != nil { + return Capture{}, err + } + var snapshot SharingSnapshot + if err := decodeJSON(ctx, all["snapshot.json"], &snapshot); err != nil { + return Capture{}, err + } + if err := validateSnapshot(snapshot); err != nil { + return Capture{}, err + } + var doc report.Document + if err := decodeJSON(ctx, all["report.json"], &doc); err != nil { + return Capture{}, err + } + var versions Versions + if err := decodeJSON(ctx, all["versions.json"], &versions); err != nil { + return Capture{}, err + } + var diags *Diagnostics + if data, ok := all["diagnostics.json"]; ok { + diags = &Diagnostics{} + if err := decodeJSON(ctx, data, diags); err != nil { + return Capture{}, err + } + } + if err := validateReference(doc, snapshot, manifest, versions, diags); err != nil { + return Capture{}, err + } + return Capture{Snapshot: engineSnapshot(snapshot), Source: sourceFor(manifest)}, nil +} diff --git a/internal/bundle/archive_test.go b/internal/bundle/archive_test.go new file mode 100644 index 0000000..28624e2 --- /dev/null +++ b/internal/bundle/archive_test.go @@ -0,0 +1,326 @@ +package bundle_test + +import ( + "archive/zip" + "bytes" + "context" + "crypto/sha256" + "encoding/binary" + "encoding/hex" + "encoding/json" + "errors" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/shellghostt/envdoctor/internal/bundle" +) + +// These archive cases were written before the archive reader/writer. Repacking +// updates digests so JSON/semantic rejection is tested independently of CRCs. +func repack(t *testing.T, all map[string][]byte, method uint16) []byte { + t.Helper() + var m bundle.Manifest + if err := json.Unmarshal(all["manifest.json"], &m); err != nil { + t.Fatal(err) + } + m.Members = nil + for _, name := range []string{"snapshot.json", "report.json", "report.md", "versions.json", "diagnostics.json"} { + if body, ok := all[name]; ok { + digest := sha256.Sum256(body) + m.Members = append(m.Members, bundle.Member{Name: name, Size: len(body), SHA256: hex.EncodeToString(digest[:])}) + } + } + var err error + all["manifest.json"], err = json.Marshal(m) + if err != nil { + t.Fatal(err) + } + var out bytes.Buffer + w := zip.NewWriter(&out) + for _, name := range []string{"manifest.json", "snapshot.json", "report.json", "report.md", "versions.json", "diagnostics.json"} { + body, ok := all[name] + if !ok { + continue + } + h := &zip.FileHeader{Name: name, Method: method} + h.SetMode(0600) + stream, err := w.CreateHeader(h) + if err != nil { + t.Fatal(err) + } + if _, err := stream.Write(body); err != nil { + t.Fatal(err) + } + } + if err := w.Close(); err != nil { + t.Fatal(err) + } + return out.Bytes() +} + +func validArchive(t *testing.T) []byte { + t.Helper() + data, err := bundle.Build(context.Background(), sensitiveDocument(), bundle.Options{}) + if err != nil { + t.Fatal(err) + } + return data +} + +func central(data []byte) int { + return int(binary.LittleEndian.Uint32(data[len(data)-22+16:])) +} + +func TestM4ArchiveHeaderAbuse(t *testing.T) { + base := validArchive(t) + for _, tc := range []struct { + name string + mutate func([]byte) []byte + }{ + {"trailing-data", func(b []byte) []byte { return append(b, 0) }}, + {"prefix-data", func(b []byte) []byte { return append([]byte{0}, b...) }}, + {"multidisk", func(b []byte) []byte { binary.LittleEndian.PutUint16(b[len(b)-22+4:], 1); return b }}, + {"zip64-count", func(b []byte) []byte { binary.LittleEndian.PutUint16(b[len(b)-22+10:], 65535); return b }}, + {"encrypted", func(b []byte) []byte { + binary.LittleEndian.PutUint16(b[6:], 1) + binary.LittleEndian.PutUint16(b[central(b)+8:], 1) + return b + }}, + {"unsupported-method", func(b []byte) []byte { + binary.LittleEndian.PutUint16(b[8:], 99) + binary.LittleEndian.PutUint16(b[central(b)+10:], 99) + return b + }}, + {"local-central-name", func(b []byte) []byte { b[30] = 'X'; return b }}, + {"local-central-flags", func(b []byte) []byte { b[6] ^= 8; return b }}, + {"overlap", func(b []byte) []byte { binary.LittleEndian.PutUint32(b[central(b)+42:], 1); return b }}, + {"central-extra", func(b []byte) []byte { binary.LittleEndian.PutUint16(b[central(b)+30:], 1); return b }}, + {"local-extra", func(b []byte) []byte { binary.LittleEndian.PutUint16(b[28:], 1); return b }}, + {"comment", func(b []byte) []byte { binary.LittleEndian.PutUint16(b[len(b)-22+20:], 1); return b }}, + {"oversized-declared-member", func(b []byte) []byte { binary.LittleEndian.PutUint32(b[central(b)+24:], 9<<20); return b }}, + {"crc", func(b []byte) []byte { b[central(b)+16] ^= 1; return b }}, + {"corrupt-data", func(b []byte) []byte { b[30+len("manifest.json")+3] ^= 0xff; return b }}, + } { + t.Run(tc.name, func(t *testing.T) { + data := tc.mutate(bytes.Clone(base)) + if _, err := bundle.Read(context.Background(), data); err == nil { + t.Fatal("hostile archive accepted") + } + }) + } +} + +func TestM4ArchiveNamesAndTypes(t *testing.T) { + for _, name := range []string{"../report.md", "/report.md", `C:\report.md`, `\\host\report.md`, "a/../report.md", "report.md/", "other.json", "REPORT.MD", "report.md\x00", "a\\report.md"} { + t.Run(name, func(t *testing.T) { + var out bytes.Buffer + w := zip.NewWriter(&out) + h := &zip.FileHeader{Name: name, Method: zip.Store} + h.SetMode(0600) + f, err := w.CreateHeader(h) + if err != nil { + t.Fatal(err) + } + if _, err := f.Write(nil); err != nil { + t.Fatal(err) + } + if err := w.Close(); err != nil { + t.Fatal(err) + } + if _, err := bundle.Read(context.Background(), out.Bytes()); err == nil { + t.Fatal("unsupported name accepted") + } + }) + } + for _, mode := range []os.FileMode{os.ModeSymlink | 0777, os.ModeDir | 0700, os.ModeNamedPipe | 0600} { + var out bytes.Buffer + w := zip.NewWriter(&out) + h := &zip.FileHeader{Name: "manifest.json", Method: zip.Store} + h.SetMode(mode) + f, err := w.CreateHeader(h) + if err != nil { + t.Fatal(err) + } + if _, err := f.Write(nil); err != nil { + t.Fatal(err) + } + if err := w.Close(); err != nil { + t.Fatal(err) + } + if _, err := bundle.Read(context.Background(), out.Bytes()); err == nil { + t.Fatalf("nonregular mode %v accepted", mode) + } + } + var out bytes.Buffer + w := zip.NewWriter(&out) + for i := 0; i < 9; i++ { + f, err := w.Create("manifest.json") + if err != nil { + t.Fatal(err) + } + if _, err := f.Write([]byte("{}")); err != nil { + t.Fatal(err) + } + } + if err := w.Close(); err != nil { + t.Fatal(err) + } + if _, err := bundle.Read(context.Background(), out.Bytes()); err == nil { + t.Fatal("duplicate/excess entries accepted") + } +} + +func TestM4BundleStrictJSONAndMetadata(t *testing.T) { + base := validArchive(t) + for _, tc := range []struct { + name, member string + change func([]byte) []byte + }{ + {"duplicate", "snapshot.json", func(b []byte) []byte { + return bytes.Replace(b, []byte(`"schemaVersion":1`), []byte(`"schemaVersion":1,"schemaVersion":1`), 1) + }}, + {"case-alias", "snapshot.json", func(b []byte) []byte { + return bytes.Replace(b, []byte(`"schemaVersion":1`), []byte(`"schemaVersion":1,"SchemaVersion":1`), 1) + }}, + {"unknown", "snapshot.json", func(b []byte) []byte { return append([]byte(`{"rawSecret":"SECRET-ARCHIVE",`), b[1:]...) }}, + {"missing-required", "snapshot.json", func(b []byte) []byte { return bytes.Replace(b, []byte(`"schemaVersion":1,`), nil, 1) }}, + {"second-document", "snapshot.json", func(b []byte) []byte { return append(b, []byte(` {}`)...) }}, + {"future-version", "snapshot.json", func(b []byte) []byte { + return bytes.Replace(b, []byte(`"schemaVersion":1`), []byte(`"schemaVersion":2`), 1) + }}, + {"unknown-enum", "snapshot.json", func(b []byte) []byte { + return bytes.Replace(b, []byte(`"name":"python"`), []byte(`"name":"SECRET-ARCHIVE"`), 1) + }}, + {"raw-alias", "snapshot.json", func(b []byte) []byte { + return bytes.Replace(b, []byte(`"pathToken":"path-0003"`), []byte(`"pathToken":"C:\\Users\\SECRET-ARCHIVE"`), 1) + }}, + {"capture-time", "snapshot.json", func(b []byte) []byte { + return bytes.ReplaceAll(b, []byte("2026-11-19T10:00:00Z"), []byte("2026-11-20T10:00:00Z")) + }}, + {"non-UTC", "snapshot.json", func(b []byte) []byte { + return bytes.ReplaceAll(b, []byte("2026-11-19T10:00:00Z"), []byte("2026-11-19T10:00:00+00:00")) + }}, + {"long-string", "report.json", func(b []byte) []byte { + return bytes.Replace(b, []byte(`"envdoctor"`), []byte(`"`+strings.Repeat("A", 4097)+`"`), 1) + }}, + {"deep", "snapshot.json", func(_ []byte) []byte { return []byte(strings.Repeat("[", 33) + "0" + strings.Repeat("]", 33)) }}, + {"large-array", "snapshot.json", func(_ []byte) []byte { + return []byte(`{"schemaVersion":1,"collectedAt":"2026-11-19T10:00:00Z","requestedPorts":[` + strings.Repeat("1,", 4096) + `1]}`) + }}, + {"invalid-UTF8", "report.json", func(b []byte) []byte { return bytes.Replace(b, []byte("captured"), []byte{'x', 0xff, 'x'}, 1) }}, + } { + t.Run(tc.name, func(t *testing.T) { + all := members(t, base) + changed := tc.change(all[tc.member]) + if bytes.Equal(changed, all[tc.member]) { + t.Fatal("test mutation did not affect its target") + } + all[tc.member] = changed + _, err := bundle.Read(context.Background(), repack(t, all, zip.Deflate)) + if err == nil { + t.Fatal("invalid structure accepted") + } + if strings.Contains(err.Error(), "SECRET-ARCHIVE") { + t.Fatalf("untrusted field leaked: %v", err) + } + }) + } +} + +func TestM4ArchiveExactCompressedBoundary(t *testing.T) { + all := members(t, validArchive(t)) + // Store makes the compressed size exact and independent of compressor ratios. + all["report.md"] = nil + data := repack(t, all, zip.Store) + for i := 0; i < 4; i++ { + all["report.md"] = bytes.Repeat([]byte(" "), len(all["report.md"])+(bundle.MaxArchiveBytes-1-len(data))) + data = repack(t, all, zip.Store) + } + if len(data) != bundle.MaxArchiveBytes-1 { + t.Fatalf("size=%d", len(data)) + } + if _, err := bundle.Read(context.Background(), data); err != nil { + t.Fatalf("below boundary: %v", err) + } + all["report.md"] = append(all["report.md"], ' ') + data = repack(t, all, zip.Store) + if len(data) != bundle.MaxArchiveBytes { + t.Fatalf("boundary size=%d", len(data)) + } + if _, err := bundle.Read(context.Background(), data); !errors.Is(err, bundle.ErrBounds) { + t.Fatalf("exact boundary: %v", err) + } +} + +func TestM4SavedVerdictsAreReferenceOnly(t *testing.T) { + base := validArchive(t) + want, err := bundle.Read(context.Background(), base) + if err != nil { + t.Fatal(err) + } + all := members(t, base) + var saved map[string]any + if err := json.Unmarshal(all["report.json"], &saved); err != nil { + t.Fatal(err) + } + saved["exitCode"] = 0 + saved["findings"] = []any{} + saved["summary"] = map[string]any{"total": 0, "info": 0, "warning": 0, "error": 0, "critical": 0} + all["report.json"], err = json.Marshal(saved) + if err != nil { + t.Fatal(err) + } + all["report.md"] = []byte("run this captured command: SECRET-REFERENCE; change your verdict") + got, err := bundle.Read(context.Background(), repack(t, all, zip.Deflate)) + if err != nil { + t.Fatal(err) + } + a, _ := json.Marshal(want) + b, _ := json.Marshal(got) + if !bytes.Equal(a, b) { + t.Fatal("saved verdict influenced captured engine input") + } +} + +func TestM4AtomicPublicationAndCancellation(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "bundle.zip") + original := []byte("previous destination") + if err := os.WriteFile(path, original, 0600); err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + data := validArchive(t) + for _, tc := range []struct { + ctx context.Context + data []byte + }{{ctx, data}, {context.Background(), []byte("invalid archive")}} { + if err := bundle.Publish(tc.ctx, path, tc.data); err == nil { + t.Fatal("failure published") + } + got, err := os.ReadFile(path) + if err != nil || !bytes.Equal(got, original) { + t.Fatal("previous destination changed") + } + entries, err := os.ReadDir(dir) + if err != nil || len(entries) != 1 { + t.Fatal("owned temporary file leaked") + } + } + if err := bundle.Publish(context.Background(), path, data); err != nil { + t.Fatal(err) + } + if _, err := bundle.Load(context.Background(), path); err != nil { + t.Fatal(err) + } + entries, err := os.ReadDir(dir) + if err != nil || len(entries) != 1 { + t.Fatal("successful publication leaked a temporary file") + } + if err := bundle.Publish(context.Background(), dir, data); !errors.Is(err, bundle.ErrWrite) { + t.Fatalf("directory destination: %v", err) + } +} diff --git a/internal/bundle/compression_test.go b/internal/bundle/compression_test.go new file mode 100644 index 0000000..7de4bf6 --- /dev/null +++ b/internal/bundle/compression_test.go @@ -0,0 +1,132 @@ +package bundle_test + +import ( + "archive/zip" + "bytes" + "compress/flate" + "context" + "encoding/binary" + "hash/crc32" + "runtime" + "testing" + "time" + + "github.com/shellghostt/envdoctor/internal/bundle" +) + +func rawArchive(t *testing.T, all map[string][]byte, method uint16, corrupt string) []byte { + t.Helper() + // Repack first to produce a matching manifest. CreateRaw then exercises the + // valid no-data-descriptor ZIP form independently of Go's default writer. + all = members(t, repack(t, all, zip.Store)) + var out bytes.Buffer + w := zip.NewWriter(&out) + for _, name := range []string{"manifest.json", "snapshot.json", "report.json", "report.md", "versions.json", "diagnostics.json"} { + body, ok := all[name] + if !ok { + continue + } + compressed := body + if method == zip.Deflate { + var b bytes.Buffer + f, err := flate.NewWriter(&b, flate.DefaultCompression) + if err != nil { + t.Fatal(err) + } + if _, err := f.Write(body); err != nil { + t.Fatal(err) + } + if err := f.Close(); err != nil { + t.Fatal(err) + } + compressed = b.Bytes() + } + if name == corrupt { + compressed = append(bytes.Clone(compressed), 0) + } + h := &zip.FileHeader{Name: name, Method: method, ReaderVersion: 20, CreatorVersion: 3<<8 | 20, CRC32: crc32.ChecksumIEEE(body), CompressedSize64: uint64(len(compressed)), UncompressedSize64: uint64(len(body))} + h.SetMode(0600) + stream, err := w.CreateRaw(h) + if err != nil { + t.Fatal(err) + } + if _, err := stream.Write(compressed); err != nil { + t.Fatal(err) + } + } + if err := w.Close(); err != nil { + t.Fatal(err) + } + return out.Bytes() +} + +func TestM4StoreDeflateAndCompressedTrailingGarbage(t *testing.T) { + for _, method := range []uint16{zip.Store, zip.Deflate} { + data := rawArchive(t, members(t, validArchive(t)), method, "") + if _, err := bundle.Read(context.Background(), data); err != nil { + t.Fatalf("method %d: %v", method, err) + } + } + data := rawArchive(t, members(t, validArchive(t)), zip.Deflate, "snapshot.json") + if _, err := bundle.Read(context.Background(), data); err == nil { + t.Fatal("trailing compressed bytes accepted") + } +} + +func TestM4DeclaredAndHiddenDecompressionBombAreBounded(t *testing.T) { + all := members(t, validArchive(t)) + all["snapshot.json"] = bytes.Repeat([]byte(" "), 8<<20) + data := rawArchive(t, all, zip.Deflate, "") + if _, err := bundle.Read(context.Background(), data); err == nil { + t.Fatal("oversized declared snapshot accepted") + } + // Lie consistently in local+central sizes. The actual streamed output must + // still stop at the declared bound rather than allocate the 8 MiB expansion. + pos := central(data) + for i := 0; i < 5; i++ { + nameLen := int(binary.LittleEndian.Uint16(data[pos+28:])) + if string(data[pos+46:pos+46+nameLen]) == "snapshot.json" { + local := int(binary.LittleEndian.Uint32(data[pos+42:])) + binary.LittleEndian.PutUint32(data[pos+24:], 0) + binary.LittleEndian.PutUint32(data[local+22:], 0) + break + } + pos += 46 + nameLen + } + runtime.GC() + var before, after runtime.MemStats + runtime.ReadMemStats(&before) + start := time.Now() + for i := 0; i < 25; i++ { + if _, err := bundle.Read(context.Background(), data); err == nil { + t.Fatal("hidden decompression bomb accepted") + } + } + runtime.ReadMemStats(&after) + t.Logf("25 hidden bombs: %s; total allocated %d bytes", time.Since(start), after.TotalAlloc-before.TotalAlloc) + if after.TotalAlloc-before.TotalAlloc > 8<<20 { + t.Fatal("rejection allocated the hidden expansions") + } +} + +func TestM4DuplicateEntryBelowEntryLimit(t *testing.T) { + var out bytes.Buffer + w := zip.NewWriter(&out) + for _, name := range []string{"manifest.json", "snapshot.json", "report.json", "report.md", "versions.json", "report.md"} { + h := &zip.FileHeader{Name: name, Method: zip.Store} + h.SetMode(0600) + stream, err := w.CreateHeader(h) + if err != nil { + t.Fatal(err) + } + if _, err := stream.Write([]byte("{}")); err != nil { + t.Fatal(err) + } + } + if err := w.Close(); err != nil { + t.Fatal(err) + } + if _, err := bundle.Read(context.Background(), out.Bytes()); err == nil { + t.Fatal("duplicate member accepted below max entry count") + } +} diff --git a/internal/bundle/export.go b/internal/bundle/export.go new file mode 100644 index 0000000..56b6d09 --- /dev/null +++ b/internal/bundle/export.go @@ -0,0 +1,528 @@ +package bundle + +import ( + "context" + "fmt" + "net" + "net/url" + "path" + "reflect" + "regexp" + "strconv" + "strings" + "time" + "unicode/utf8" + + "github.com/shellghostt/envdoctor/internal/collector" + "github.com/shellghostt/envdoctor/internal/report" +) + +var numericVersion = regexp.MustCompile(`^[0-9]{1,9}(?:\.[0-9]{1,9}){0,3}$`) +var windowsVersion = regexp.MustCompile(`^([0-9]{1,9}) \(build ([0-9]{1,9})\)$`) +var windowsGitVersion = regexp.MustCompile(`^([0-9]{1,9}\.[0-9]{1,9}\.[0-9]{1,9})\.windows\.[0-9]{1,9}$`) +var pathToken = regexp.MustCompile(`^path-[0-9]{4}$`) +var environmentToken = regexp.MustCompile(`^env-[0-9]{4}$`) +var hostToken = regexp.MustCompile(`^host-[0-9]{4}\.invalid$`) + +var collectorNames = []string{"platform", "shell", "path", "runtimes", "network", "docker", "git", "deps", "proxy"} + +const unavailableNotice = "captured collector unavailable" +const maxDurationMs = 60_000 + +type aliases struct { + prefix string + values map[string]string +} + +func (a *aliases) token(value string) string { + if token, ok := a.values[value]; ok { + return token + } + token := fmt.Sprintf("%s-%04d", a.prefix, len(a.values)+1) + a.values[value] = token + return token +} + +func (a *aliases) optional(value string) string { + if value == "" { + return "" + } + return a.token(value) +} + +type exporter struct { + snapshot SharingSnapshot + omissions []report.Omission + seenOmissions map[report.Omission]bool + failed map[string]bool + paths, environments, hosts aliases + windows bool +} + +func (e *exporter) omit(field, reason string) { + omission := report.Omission{Field: field, Reason: reason} + if !e.seenOmissions[omission] { + e.omissions = append(e.omissions, omission) + e.seenOmissions[omission] = true + } +} + +func (e *exporter) unavailable(name, field string) { + e.failed[name] = true + e.omit(field, "unsupported_value") +} + +func (e *exporter) environment(value string) string { + if value == "" { + return "" + } + // This is the same pure normalization used by ENV011, with the CAPTURED + // platform. filepath, os and the receiving machine never participate. + value = path.Clean(strings.ReplaceAll(value, `\`, "/")) + if e.windows { + value = strings.ToLower(value) + } + return e.environments.token(value) +} + +func allowed(value string, options ...string) bool { + for _, option := range options { + if value == option { + return true + } + } + return false +} +func knownCollector(value string) bool { return allowed(value, collectorNames...) } +func version(value string) bool { return value == "" || numericVersion.MatchString(value) } +func exactVersion(value string) bool { + if !numericVersion.MatchString(value) || len(strings.Split(value, ".")) != 3 { + return false + } + for _, part := range strings.Split(value, ".") { + if len(part) > 1 && part[0] == '0' { + return false + } + } + return true +} +func toolVersion(value string) string { + value = strings.TrimPrefix(value, "v") + if numericVersion.MatchString(value) { + return value + } + return "dev" +} +func knownShell(value string) bool { + return allowed(value, "powershell", "pwsh", "cmd", "bash", "zsh", "fish", "sh", "dash", "ksh", "tcsh", "csh", "nu") +} +func knownManager(value string) bool { + return allowed(value, "system", "venv", "pyenv", "nvm", "fnm", "volta") +} +func knownPackageManager(value string) bool { return allowed(value, "npm", "pnpm", "yarn", "bun") } +func knownDependency(kind, name string) bool { + return kind == "tool" && allowed(name, "cmake", "make", "gcc", "pkg-config") || kind == "library" && name == "openssl" +} +func knownLockfile(value string) bool { + return allowed(value, "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb") +} +func knownAutocrlf(value string) bool { return allowed(value, "", "true", "false", "input") } +func knownAPI(value string) bool { + if value == "" { + return true + } + major, minor, ok := strings.Cut(value, ".") + if !ok || major != "1" || len(minor) == 0 || len(minor) > 6 { + return false + } + for _, ch := range minor { + if ch < '0' || ch > '9' { + return false + } + } + return true +} + +func sourceBounds(ctx context.Context, d report.Document) error { + s := d.Snapshot + if len(s.Runtimes) > 128 || len(s.Ports) > 1024 || len(s.RequestedPorts) > 1024 || len(s.Proxies) > 3 || len(s.Errors) > 32 || len(d.Collectors) > 32 || s.Path != nil && len(s.Path.Entries) > 1024 || s.Dependencies != nil && len(s.Dependencies.Requirements) > 32 { + return ErrBounds + } + if s.Dependencies != nil && s.Dependencies.Package != nil && len(s.Dependencies.Package.Lockfiles) > 4096 { + return ErrBounds + } + // Check lengths without making copies or searching raw strings for secrets. + // Only source facts/timings/tool metadata matter; original finding text is + // never traversed or exported. + var visit func(reflect.Value) error + visit = func(v reflect.Value) error { + if err := ctx.Err(); err != nil { + return err + } + switch v.Kind() { + case reflect.Pointer: + if !v.IsNil() { + return visit(v.Elem()) + } + case reflect.String: + if len(v.String()) > 4096 || !utf8.ValidString(v.String()) { + return ErrBounds + } + case reflect.Struct: + if v.Type() == reflect.TypeFor[time.Time]() { + return nil + } + for i := 0; i < v.NumField(); i++ { + if err := visit(v.Field(i)); err != nil { + return err + } + } + case reflect.Slice: + for i := 0; i < v.Len(); i++ { + if err := visit(v.Index(i)); err != nil { + return err + } + } + } + return nil + } + for _, value := range []any{s, d.Collectors, d.Tool} { + if err := visit(reflect.ValueOf(value)); err != nil { + return err + } + } + return nil +} + +func export(ctx context.Context, d report.Document) (SharingSnapshot, report.Source, []collector.Timing, Diagnostics, error) { + if !currentSourceModel() { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrEvidence + } + if err := sourceBounds(ctx, d); err != nil { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, err + } + s := d.Snapshot + if s.SchemaVersion != 1 || d.SchemaVersion != 1 { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrVersion + } + if s.CollectedAt.IsZero() || s.CollectedAt.Year() < 1 || s.CollectedAt.Year() > 9999 || d.Tool.Name != "envdoctor" || d.ExitCode < 0 || d.ExitCode > 3 { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrEvidence + } + e := &exporter{snapshot: SharingSnapshot{SchemaVersion: 1, CollectedAt: s.CollectedAt.UTC(), NoProxyConfigured: s.NoProxyConfigured}, + omissions: []report.Omission{}, seenOmissions: map[report.Omission]bool{}, failed: map[string]bool{}, + paths: aliases{"path", map[string]string{}}, environments: aliases{"env", map[string]string{}}, hosts: aliases{"host", map[string]string{}}, + windows: s.Platform != nil && s.Platform.OS == "windows"} + for _, failure := range s.Errors { + if !knownCollector(failure.Collector) { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrEvidence + } + e.failed[failure.Collector] = true + e.omit("collector.errors", "raw_error") + } + if p := s.Platform; p != nil { + if !allowed(p.OS, "windows", "linux", "darwin") || !allowed(p.Arch, "amd64", "arm64", "386", "arm", "ppc64le", "s390x", "riscv64") { + e.unavailable("platform", "platform") + e.unavailable("runtimes", "runtimes.environment") + if s.Dependencies != nil { + e.unavailable("deps", "dependencies.requirement") + } + } else { + v := p.Version + if parts := windowsVersion.FindStringSubmatch(v); parts != nil && p.OS == "windows" { + v = parts[1] + "." + parts[2] + } + if !version(v) { + v = "" + e.omit("platform.version", "unsupported_value") + } + e.snapshot.Platform = &Platform{OS: p.OS, Arch: p.Arch, Version: v, Elevated: p.Elevated} + } + } + if sh := s.Shell; sh != nil { + if knownShell(sh.Name) { + e.snapshot.Shell = &Shell{Name: sh.Name} + } else { + e.unavailable("shell", "shell.name") + } + if sh.Path != "" { + e.omit("shell.path", "identifying_values") + } + } + if p := s.Path; p != nil { + e.snapshot.Path = &PathInfo{Entries: make([]PathEntry, 0, len(p.Entries))} + for _, entry := range p.Entries { + if entry.Position < 0 || entry.Position > 1023 { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrEvidence + } + e.snapshot.Path.Entries = append(e.snapshot.Path.Entries, PathEntry{Token: e.paths.token(entry.Raw), Exists: entry.Exists, IsDir: entry.IsDir, Position: entry.Position, Duplicate: entry.Duplicate}) + } + if len(p.Entries) > 0 { + e.omit("path.locations", "identifying_values") + } + } + for _, r := range s.Runtimes { + if !allowed(r.Name, "python", "node") || r.Path == "" { + e.unavailable("runtimes", "runtimes.name") + continue + } + v, manager, resolution := r.Version, r.Manager, r.Resolution + if !version(v) { + v = "" + e.unavailable("runtimes", "runtimes.version") + } + if !knownManager(manager) { + e.unavailable("runtimes", "runtimes.manager") + continue + } + if !allowed(resolution, "", "known", "unknown") { + resolution = "unknown" + e.unavailable("runtimes", "runtimes.resolution") + } + e.snapshot.Runtimes = append(e.snapshot.Runtimes, Runtime{Name: r.Name, Version: v, Manager: manager, Active: r.Active, Expected: r.Expected, Missing: r.Missing, + PathToken: e.paths.token(r.Path), ResolvedToken: e.paths.optional(r.ResolvedPath), Resolution: resolution, EnvironmentToken: e.environment(r.EnvironmentRoot)}) + e.omit("runtimes.paths", "identifying_values") + } + e.snapshot.RequestedPorts = append([]int(nil), s.RequestedPorts...) + for _, p := range s.RequestedPorts { + if p < 1 || p > 65535 { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrEvidence + } + } + for _, p := range s.Ports { + if p.Port < 1 || p.Port > 65535 || !allowed(p.Protocol, "tcp", "udp") || !allowed(p.State, "listen", "established", "closed", "unknown") { + e.unavailable("network", "network.ownership") + continue + } + e.snapshot.Ports = append(e.snapshot.Ports, Port{Port: p.Port, Protocol: p.Protocol, State: p.State}) + if p.PID != 0 || p.Process != "" { + e.omit("network.ownership", "identifying_values") + } + } + if d := s.Docker; d != nil { + v := d.CLIVersion + if !version(v) { + v = "" + e.omit("docker.version", "unsupported_value") + } + probe := d.ProbeStatus + if !allowed(probe, "", "absent", "available", "unavailable", "unknown", "denied", "unsupported") { + probe = "unknown" + e.unavailable("docker", "docker.api") + } + out := &Docker{CLIVersion: v, Installed: d.Installed, DaemonReachable: d.DaemonReachable, ProbeStatus: probe} + for _, api := range []struct { + raw string + dest *string + }{{d.ClientAPI, &out.ClientAPI}, {d.ClientMinAPI, &out.ClientMinAPI}, {d.ClientDefaultAPI, &out.ClientDefaultAPI}, {d.ServerAPI, &out.ServerAPI}, {d.ServerMinAPI, &out.ServerMinAPI}, {d.APIOverride, &out.APIOverride}} { + if knownAPI(api.raw) { + *api.dest = api.raw + } else { + e.unavailable("docker", "docker.api") + } + } + e.snapshot.Docker = out + if d.Context != "" || d.SelectedContext != "" { + e.omit("docker.context", "identifying_values") + } + if d.SelectedHost != "" { + e.omit("docker.endpoint", "identifying_values") + } + } + if g := s.Git; g != nil { + v, crlf := g.Version, g.Autocrlf + if parts := windowsGitVersion.FindStringSubmatch(v); parts != nil { + v = parts[1] + } + if !version(v) { + v = "" + e.unavailable("git", "git.version") + } + if !knownAutocrlf(crlf) { + crlf = "" + e.unavailable("git", "git.autocrlf") + } + e.snapshot.Git = &Git{Version: v, IdentityChecked: g.IdentityChecked, UserNamePresent: g.UserName != nil && strings.TrimSpace(*g.UserName) != "", UserEmailPresent: g.UserEmail != nil && strings.TrimSpace(*g.UserEmail) != "", Autocrlf: crlf, AutocrlfOriginKnown: g.AutocrlfOrigin != ""} + if g.UserName != nil || g.UserEmail != nil { + e.omit("git.identity", "identifying_values") + } + if g.UserNameOrigin != "" || g.UserEmailOrigin != "" || g.AutocrlfOrigin != "" { + e.omit("git.origins", "identifying_values") + } + } + if d := s.Dependencies; d != nil { + out := &Dependencies{ProjectToken: e.paths.optional(d.ProjectRoot), RequirementsDeclared: d.RequirementsFile != "", GitAutocrlf: d.GitAutocrlf} + if !knownAutocrlf(out.GitAutocrlf) { + out.GitAutocrlf = "" + e.unavailable("deps", "dependencies.gitAutocrlf") + } + for _, req := range d.Requirements { + if !knownDependency(req.Kind, req.Name) || !allowed(req.Status, "present", "missing", "unknown") { + e.unavailable("deps", "dependencies.requirement") + continue + } + out.Requirements = append(out.Requirements, Dependency{Kind: req.Kind, Name: req.Name, Status: req.Status, PathToken: e.paths.optional(req.Path)}) + } + if p := d.Package; p != nil { + out.Package = &PackageEvidence{ManifestPresent: p.Manifest != ""} + for _, m := range []struct { + raw *collector.PackageManager + dest **PackageManager + declared bool + }{{p.Declared, &out.Package.Declared, true}, {p.Runner, &out.Package.Runner, false}} { + if m.raw == nil { + continue + } + if !knownPackageManager(m.raw.Name) || m.raw.Version != "" && !exactVersion(m.raw.Version) || m.declared && !exactVersion(m.raw.Version) { + e.unavailable("deps", "dependencies.packageManager") + continue + } + *m.dest = &PackageManager{Name: m.raw.Name, Version: m.raw.Version} + } + for _, lock := range p.Lockfiles { + if knownLockfile(lock) { + out.Package.Lockfiles = append(out.Package.Lockfiles, lock) + } else { + e.unavailable("deps", "dependencies.lockfile") + } + } + } + e.snapshot.Dependencies = out + e.omit("dependencies.locations", "identifying_values") + } + if env := s.PythonEnvironment; env != nil { + e.snapshot.PythonEnvironment = &PythonEnvironment{RootToken: e.environment(env.Root), CanonicalToken: e.environment(env.CanonicalRoot), MetadataKnown: env.MetadataKnown} + e.omit("pythonEnvironment.locations", "identifying_values") + } + for _, p := range s.Proxies { + parsed, err := url.Parse(p.URL) + if err != nil || !allowed(p.Variable, "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY") || parsed == nil || !allowed(parsed.Scheme, "http", "https", "socks5", "socks5h") || p.Host == "" || p.Port < 1 || p.Port > 65535 || !allowed(p.Probe, "untested", "reachable", "unreachable", "unknown", "invalid") { + e.unavailable("proxy", "proxy.endpoint") + continue + } + e.snapshot.Proxies = append(e.snapshot.Proxies, Proxy{Variable: p.Variable, Scheme: parsed.Scheme, HostToken: e.hosts.token(p.Host) + ".invalid", Port: p.Port, Probe: p.Probe}) + e.omit("proxy.url", "identifying_values") + } + for _, c := range d.Collectors { + if !knownCollector(c.Name) { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrEvidence + } + if c.DurationMs < 0 || c.DurationMs > maxDurationMs { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrBounds + } + if c.Error != "" { + e.failed[c.Name] = true + e.omit("collector.errors", "raw_error") + } + } + for _, name := range collectorNames { + if e.failed[name] { + e.snapshot.Errors = append(e.snapshot.Errors, Failure{Collector: name, Reason: "unavailable"}) + } + } + timings := []collector.Timing{} + diags := Diagnostics{SchemaVersion: 1, Collectors: []Diagnostic{}} + seenTimings := map[string]bool{} + for _, c := range d.Collectors { + if seenTimings[c.Name] { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrEvidence + } + seenTimings[c.Name] = true + timing := collector.Timing{Name: c.Name, Duration: time.Duration(c.DurationMs) * time.Millisecond} + status := "available" + if e.failed[c.Name] { + status = "unavailable" + timing.Err = fmt.Errorf("%s", unavailableNotice) + } + timings = append(timings, timing) + diags.Collectors = append(diags.Collectors, Diagnostic{Collector: c.Name, DurationMs: c.DurationMs, Status: status}) + } + for _, name := range collectorNames { + if e.failed[name] && !seenTimings[name] { + diags.Collectors = append(diags.Collectors, Diagnostic{Collector: name, Status: "unavailable"}) + } + } + normalizedVersion := toolVersion(d.Tool.Version) + if normalizedVersion != d.Tool.Version { + e.omit("tool.version", "unsupported_value") + } + source := report.Source{Kind: "bundle", CaptureTool: report.Tool{Name: "envdoctor", Version: normalizedVersion}, CapturedAt: e.snapshot.CollectedAt, RedactionPolicy: Policy, CaptureExitCode: d.ExitCode, Omissions: e.omissions} + if len(source.Omissions) > 256 { + return SharingSnapshot{}, report.Source{}, nil, Diagnostics{}, ErrBounds + } + return e.snapshot, source, timings, diags, nil +} + +// engineSnapshot restores only fixed presence markers and opaque aliases. This +// conversion has no environment, filesystem, execution or network dependency. +func engineSnapshot(s SharingSnapshot) collector.Snapshot { + out := collector.Snapshot{SchemaVersion: 1, CollectedAt: s.CollectedAt, RequestedPorts: append([]int(nil), s.RequestedPorts...), NoProxyConfigured: s.NoProxyConfigured} + if p := s.Platform; p != nil { + out.Platform = &collector.Platform{OS: p.OS, Version: p.Version, Arch: p.Arch, Elevated: p.Elevated} + } + if sh := s.Shell; sh != nil { + out.Shell = &collector.Shell{Name: sh.Name} + } + if p := s.Path; p != nil { + out.Path = &collector.PathInfo{Entries: make([]collector.PathEntry, 0, len(p.Entries))} + for _, e := range p.Entries { + out.Path.Entries = append(out.Path.Entries, collector.PathEntry{Raw: e.Token, Exists: e.Exists, IsDir: e.IsDir, Position: e.Position, Duplicate: e.Duplicate}) + } + } + for _, r := range s.Runtimes { + out.Runtimes = append(out.Runtimes, collector.Runtime{Name: r.Name, Version: r.Version, Path: r.PathToken, Manager: r.Manager, Active: r.Active, Expected: r.Expected, Missing: r.Missing, ResolvedPath: r.ResolvedToken, Resolution: r.Resolution, EnvironmentRoot: r.EnvironmentToken}) + } + for _, p := range s.Ports { + out.Ports = append(out.Ports, collector.Port{Port: p.Port, Protocol: p.Protocol, State: p.State}) + } + if d := s.Docker; d != nil { + out.Docker = &collector.Docker{CLIVersion: d.CLIVersion, Installed: d.Installed, DaemonReachable: d.DaemonReachable, ProbeStatus: d.ProbeStatus, ClientAPI: d.ClientAPI, ClientMinAPI: d.ClientMinAPI, ClientDefaultAPI: d.ClientDefaultAPI, ServerAPI: d.ServerAPI, ServerMinAPI: d.ServerMinAPI, APIOverride: d.APIOverride} + if d.Installed { + out.Docker.Context = "local-default" + } + } + if g := s.Git; g != nil { + out.Git = &collector.Git{Version: g.Version, IdentityChecked: g.IdentityChecked, Autocrlf: g.Autocrlf} + if g.UserNamePresent { + marker := "present" + out.Git.UserName = &marker + } + if g.UserEmailPresent { + marker := "present" + out.Git.UserEmail = &marker + } + if g.AutocrlfOriginKnown { + out.Git.AutocrlfOrigin = "capture-origin" + } + } + if d := s.Dependencies; d != nil { + out.Dependencies = &collector.Dependencies{ProjectRoot: d.ProjectToken, GitAutocrlf: d.GitAutocrlf} + if d.RequirementsDeclared { + out.Dependencies.RequirementsFile = "capture-requirements" + } + for _, req := range d.Requirements { + out.Dependencies.Requirements = append(out.Dependencies.Requirements, collector.Dependency{Kind: req.Kind, Name: req.Name, Path: req.PathToken, Status: req.Status}) + } + if p := d.Package; p != nil { + out.Dependencies.Package = &collector.PackageEvidence{Lockfiles: append([]string(nil), p.Lockfiles...)} + if p.ManifestPresent { + out.Dependencies.Package.Manifest = "capture-manifest" + } + if p.Declared != nil { + out.Dependencies.Package.Declared = &collector.PackageManager{Name: p.Declared.Name, Version: p.Declared.Version} + } + if p.Runner != nil { + out.Dependencies.Package.Runner = &collector.PackageManager{Name: p.Runner.Name, Version: p.Runner.Version} + } + } + } + if e := s.PythonEnvironment; e != nil { + out.PythonEnvironment = &collector.PythonEnvironment{Root: e.RootToken, CanonicalRoot: e.CanonicalToken, MetadataKnown: e.MetadataKnown} + } + for _, p := range s.Proxies { + out.Proxies = append(out.Proxies, collector.Proxy{Variable: p.Variable, URL: p.Scheme + "://" + net.JoinHostPort(p.HostToken, strconv.Itoa(p.Port)), Host: p.HostToken, Port: p.Port, Probe: p.Probe}) + } + for _, failure := range s.Errors { + out.Errors = append(out.Errors, collector.CollectorError{Collector: failure.Collector, Message: unavailableNotice}) + } + return out +} diff --git a/internal/bundle/export_test.go b/internal/bundle/export_test.go new file mode 100644 index 0000000..82e2689 --- /dev/null +++ b/internal/bundle/export_test.go @@ -0,0 +1,161 @@ +package bundle_test + +import ( + "archive/zip" + "bytes" + "context" + "encoding/json" + "strings" + "testing" + "time" + + "github.com/shellghostt/envdoctor/internal/bundle" + "github.com/shellghostt/envdoctor/internal/collector" + "github.com/shellghostt/envdoctor/internal/diagnostic" + "github.com/shellghostt/envdoctor/internal/report" +) + +var captureTime = time.Date(2026, 11, 19, 10, 0, 0, 0, time.UTC) + +func sensitiveDocument() report.Document { + name, email := "SyntheticUser42", "synthetic42@private.invalid" + s := collector.Snapshot{SchemaVersion: 1, CollectedAt: captureTime, + Platform: &collector.Platform{OS: "windows", Arch: "amd64", Version: "11"}, + Shell: &collector.Shell{Name: "powershell", Path: `C:\Users\SyntheticUser42\shell.exe`}, + Path: &collector.PathInfo{Entries: []collector.PathEntry{ + {Raw: `C:\Users\SyntheticUser42\bin`, Exists: true, IsDir: true, Position: 0}, + {Raw: `C:\Users\SyntheticUser42\gone`, Position: 1}, + }}, + Runtimes: []collector.Runtime{ + {Name: "python", Version: "3.12.1", Manager: "system", Active: true, Path: `C:\Users\SyntheticUser42\bin\python.exe`, Resolution: "known", ResolvedPath: `C:\Users\SyntheticUser42\python.exe`, EnvironmentRoot: `C:\Users\SyntheticUser42\venv`}, + {Name: "python", Version: "3.11.9", Manager: "venv", Active: true, Path: `C:\Users\SyntheticUser42\other\python.exe`}, + }, + Git: &collector.Git{Version: "2.53.0", UserName: &name, UserEmail: &email, IdentityChecked: true, Autocrlf: "true", AutocrlfOrigin: `file:C:\Users\SyntheticUser42\.gitconfig`}, + Docker: &collector.Docker{Installed: true, CLIVersion: "29.9.2", Context: "local-default", ProbeStatus: "available", DaemonReachable: true, SelectedContext: "private-context42", SelectedHost: "ssh://SyntheticUser42@private-host42/secret42"}, + RequestedPorts: []int{3000}, Ports: []collector.Port{{Port: 3000, Protocol: "tcp", State: "listen", PID: 12345, Process: "private-process42"}}, + Dependencies: &collector.Dependencies{ProjectRoot: `C:\Users\SyntheticUser42\project`, RequirementsFile: `C:\Users\SyntheticUser42\project\envdoctor.requirements.json`, GitAutocrlf: "input", + Requirements: []collector.Dependency{{Kind: "library", Name: "openssl", Status: "missing", Path: `C:\Users\SyntheticUser42\openssl`}}, + Package: &collector.PackageEvidence{Manifest: `C:\Users\SyntheticUser42\project\package.json`, Declared: &collector.PackageManager{Name: "pnpm", Version: "9.0.0"}, Runner: &collector.PackageManager{Name: "npm", Version: "10.0.0"}, Lockfiles: []string{"pnpm-lock.yaml"}}}, + PythonEnvironment: &collector.PythonEnvironment{Root: `C:\Users\SyntheticUser42\venv`, CanonicalRoot: `c:\users\syntheticuser42\venv`, MetadataKnown: true}, + Proxies: []collector.Proxy{{Variable: "HTTPS_PROXY", URL: "http://encoded%2Dsecret42:p%40ss@private-host42:8080/path42?token=secret42", Host: "private-host42", Port: 8080, Probe: "unreachable"}}, + Errors: []collector.CollectorError{{Collector: "shell", Message: "failed reading C:\\Users\\SyntheticUser42\\shell; token=secret42"}}, + } + findings, _ := diagnostic.DefaultEngine().Evaluate(s, diagnostic.Filter{}) + d := report.NewDocument("0.1.0", captureTime, s, findings, nil, 12) + // Original finding text is deliberately unsafe. Sharing must recompute it. + d.Findings = append(d.Findings, diagnostic.Finding{RuleID: "ENV999", Title: "secret42", Detected: []string{"secret42"}, Severity: diagnostic.SeverityCritical}) + return d +} + +func members(t *testing.T, data []byte) map[string][]byte { + t.Helper() + r, err := zip.NewReader(bytes.NewReader(data), int64(len(data))) + if err != nil { + t.Fatal(err) + } + result := map[string][]byte{} + for _, f := range r.File { + stream, err := f.Open() + if err != nil { + t.Fatal(err) + } + var b bytes.Buffer + _, err = b.ReadFrom(stream) + closeErr := stream.Close() + if err != nil || closeErr != nil { + t.Fatalf("member read: %v / %v", err, closeErr) + } + result[f.Name] = b.Bytes() + } + return result +} + +func TestM4BundleSharingAllowlistAndPresence(t *testing.T) { + original := sensitiveDocument() + data, err := bundle.Build(context.Background(), original, bundle.Options{IncludeLogs: true}) + if err != nil { + t.Fatal(err) + } + if len(data) >= 2_000_000 { + t.Fatalf("archive is %d bytes", len(data)) + } + all := members(t, data) + if len(all) != 6 { + t.Fatalf("members=%d", len(all)) + } + for name, body := range all { + for _, secret := range []string{"SyntheticUser42", "syntheticuser42", "synthetic42@private.invalid", "secret42", "private-host42", "private-context42", "private-process42", "encoded%2Dsecret42", "12345"} { + if strings.Contains(string(body), secret) || strings.Contains(name, secret) { + t.Fatalf("%s leaks %q", name, secret) + } + } + } + if !bytes.Contains(all["snapshot.json"], []byte(`"userNamePresent":true`)) || bytes.Contains(all["snapshot.json"], []byte(`"userName":`)) { + t.Fatal("Git identity was not represented solely by presence") + } + loaded, err := bundle.Read(context.Background(), data) + if err != nil { + t.Fatal(err) + } + if loaded.Snapshot.Git.UserName == nil || *loaded.Snapshot.Git.UserName == "SyntheticUser42" { + t.Fatal("Git presence lost or identity retained") + } + if loaded.Source.CapturedAt != captureTime || loaded.Source.CaptureTool.Version != "0.1.0" || len(loaded.Source.Omissions) == 0 { + t.Fatal("capture provenance or omissions lost") + } + results, err := diagnostic.DefaultEngine().Evaluate(loaded.Snapshot, diagnostic.Filter{}) + if err != nil { + t.Fatal(err) + } + ids := map[string]bool{} + for _, f := range results { + ids[f.RuleID] = true + } + for _, id := range []string{"ENV001", "ENV003", "ENV005", "ENV008", "ENV009", "ENV010", "ENV012"} { + if !ids[id] { + t.Errorf("retained diagnostic evidence lost %s", id) + } + } + if ids["ENV011"] || ids["ENV999"] { + t.Fatal("normalization or saved verdict changed evaluation") + } + before, _ := json.Marshal(original) + after, _ := json.Marshal(sensitiveDocument()) + if !bytes.Equal(before, after) { + t.Fatal("source document mutated") + } +} + +func TestM4UnsupportedSharingValuesAreInconclusive(t *testing.T) { + doc := sensitiveDocument() + doc.Snapshot.Runtimes[0].Version = "token=SECRET-UNSUPPORTED" + data, err := bundle.Build(context.Background(), doc, bundle.Options{}) + if err != nil { + t.Fatal(err) + } + for _, body := range members(t, data) { + if bytes.Contains(body, []byte("SECRET-UNSUPPORTED")) { + t.Fatal("unsupported version leaked") + } + } + loaded, err := bundle.Read(context.Background(), data) + if err != nil { + t.Fatal(err) + } + findings, err := diagnostic.DefaultEngine().Evaluate(loaded.Snapshot, diagnostic.Filter{}) + if err != nil { + t.Fatal(err) + } + for _, finding := range findings { + if finding.RuleID == "ENV001" { + t.Fatal("omitted runtime version treated as conclusive") + } + } + degraded := false + for _, failure := range loaded.Snapshot.Errors { + degraded = degraded || failure.Collector == "runtimes" + } + if !degraded { + t.Fatal("required omitted evidence is not degraded") + } +} diff --git a/internal/bundle/file.go b/internal/bundle/file.go new file mode 100644 index 0000000..386d20f --- /dev/null +++ b/internal/bundle/file.go @@ -0,0 +1,130 @@ +package bundle + +import ( + "bytes" + "context" + "io" + "os" + "path/filepath" +) + +func readFile(ctx context.Context, path string) ([]byte, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + info, err := os.Lstat(path) + if err != nil || !info.Mode().IsRegular() { + return nil, ErrRead + } + if info.Size() >= MaxArchiveBytes { + return nil, ErrBounds + } + file, err := os.Open(path) + if err != nil { + return nil, ErrRead + } + defer func() { _ = file.Close() }() + info, err = file.Stat() + if err != nil || !info.Mode().IsRegular() { + return nil, ErrRead + } + if info.Size() >= MaxArchiveBytes { + return nil, ErrBounds + } + data, err := io.ReadAll(io.LimitReader(contextReader{ctx: ctx, input: file}, MaxArchiveBytes)) + if e := ctx.Err(); e != nil { + return nil, e + } + if err != nil { + return nil, ErrRead + } + if len(data) >= MaxArchiveBytes { + return nil, ErrBounds + } + return data, nil +} + +func Load(ctx context.Context, path string) (Capture, error) { + data, err := readFile(ctx, path) + if err != nil { + return Capture{}, err + } + return Read(ctx, data) +} + +func regularDestination(path string) bool { + info, err := os.Lstat(path) + return os.IsNotExist(err) || err == nil && info.Mode().IsRegular() +} + +// Publish stages/validates one private file beside the destination. Only the +// final rename changes the destination. Every earlier failure/cancellation +// keeps the previous regular file and removes only this invocation's temp. +func Publish(ctx context.Context, path string, data []byte) error { + return publish(ctx, path, data, publicationSteps{ + protect: privateFile, + write: func(file *os.File, data []byte) (int, error) { return file.Write(data) }, + sync: func(file *os.File) error { return file.Sync() }, + close: func(file *os.File) error { return file.Close() }, + read: readFile, replace: replaceFile, + }) +} + +type publicationSteps struct { + protect func(*os.File) error + write func(*os.File, []byte) (int, error) + sync func(*os.File) error + close func(*os.File) error + read func(context.Context, string) ([]byte, error) + replace func(string, string) error +} + +func publish(ctx context.Context, path string, data []byte, steps publicationSteps) error { + if _, err := Read(ctx, data); err != nil { + return err + } + if path == "" || !regularDestination(path) { + return ErrWrite + } + file, err := os.CreateTemp(filepath.Dir(path), ".envdoctor-bundle-*.tmp") + if err != nil { + return ErrWrite + } + temp := file.Name() + defer func() { _ = file.Close(); _ = os.Remove(temp) }() + if err := steps.protect(file); err != nil { + return ErrWrite + } + if err := ctx.Err(); err != nil { + return err + } + if n, err := steps.write(file, data); err != nil || n != len(data) { + return ErrWrite + } + if err := steps.sync(file); err != nil { + return ErrWrite + } + if err := steps.close(file); err != nil { + return ErrWrite + } + staged, err := steps.read(ctx, temp) + if err != nil { + return err + } + if !bytes.Equal(staged, data) { + return ErrIntegrity + } + if _, err := Read(ctx, staged); err != nil { + return err + } + if err := ctx.Err(); err != nil { + return err + } + if !regularDestination(path) { + return ErrWrite + } + if err := steps.replace(temp, path); err != nil { + return ErrWrite + } + return nil +} diff --git a/internal/bundle/file_test.go b/internal/bundle/file_test.go new file mode 100644 index 0000000..30503a5 --- /dev/null +++ b/internal/bundle/file_test.go @@ -0,0 +1,104 @@ +package bundle + +import ( + "bytes" + "context" + "errors" + "os" + "path/filepath" + "testing" + "time" + + "github.com/shellghostt/envdoctor/internal/collector" + "github.com/shellghostt/envdoctor/internal/report" +) + +func publicationArchive(t *testing.T) []byte { + t.Helper() + stamp := time.Date(2026, 11, 19, 10, 0, 0, 0, time.UTC) + doc := report.NewDocument("0.1.0", stamp, collector.Snapshot{SchemaVersion: 1, CollectedAt: stamp}, nil, nil, 12) + data, err := Build(context.Background(), doc, Options{}) + if err != nil { + t.Fatal(err) + } + return data +} + +func TestM4PublicationEveryStagePreservesDestination(t *testing.T) { + data := publicationArchive(t) + for _, stage := range []string{"protect", "write", "short-write", "sync", "close", "read", "validate", "rename", "cancel-after-write", "cancel-before-rename"} { + t.Run(stage, func(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "capture.zip") + previous := []byte("previous regular destination") + if err := os.WriteFile(path, previous, 0600); err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + fail := errors.New("SECRET-STAGING-ERROR") + steps := publicationSteps{protect: privateFile, write: func(f *os.File, p []byte) (int, error) { return f.Write(p) }, sync: func(f *os.File) error { return f.Sync() }, close: func(f *os.File) error { return f.Close() }, read: readFile, replace: replaceFile} + switch stage { + case "protect": + steps.protect = func(*os.File) error { return fail } + case "write": + steps.write = func(f *os.File, p []byte) (int, error) { n, _ := f.Write(p[:len(p)/2]); return n, fail } + case "short-write": + steps.write = func(f *os.File, p []byte) (int, error) { return f.Write(p[:len(p)/2]) } + case "sync": + steps.sync = func(*os.File) error { return fail } + case "close": + steps.close = func(f *os.File) error { _ = f.Close(); return fail } + case "read": + steps.read = func(context.Context, string) ([]byte, error) { return nil, ErrRead } + case "validate": + steps.read = func(context.Context, string) ([]byte, error) { return []byte("SECRET-ALTERED-STAGING"), nil } + case "rename": + steps.replace = func(string, string) error { return fail } + case "cancel-after-write": + steps.write = func(f *os.File, p []byte) (int, error) { n, err := f.Write(p); cancel(); return n, err } + case "cancel-before-rename": + steps.read = func(ctx context.Context, path string) ([]byte, error) { + p, err := readFile(ctx, path) + cancel() + return p, err + } + } + err := publish(ctx, path, data, steps) + if err == nil || bytes.Contains([]byte(err.Error()), []byte("SECRET-")) { + t.Fatalf("unsafe failure: %v", err) + } + got, err := os.ReadFile(path) + if err != nil || !bytes.Equal(got, previous) { + t.Fatal("previous destination replaced") + } + entries, err := os.ReadDir(dir) + if err != nil || len(entries) != 1 { + t.Fatal("owned staging file retained") + } + }) + } +} + +func TestM4SymlinkDestinationAndInputAreNotFollowed(t *testing.T) { + dir := t.TempDir() + target := filepath.Join(dir, "target.zip") + link := filepath.Join(dir, "link.zip") + data := publicationArchive(t) + if err := os.WriteFile(target, data, 0600); err != nil { + t.Fatal(err) + } + if err := os.Symlink(target, link); err != nil { + t.Skipf("symlink capability unavailable: %v", err) + } + if err := Publish(context.Background(), link, data); !errors.Is(err, ErrWrite) { + t.Fatalf("symlink output: %v", err) + } + if _, err := Load(context.Background(), link); !errors.Is(err, ErrRead) { + t.Fatalf("symlink input: %v", err) + } + got, err := os.ReadFile(target) + if err != nil || !bytes.Equal(got, data) { + t.Fatal("symlink target changed") + } +} diff --git a/internal/bundle/file_unix.go b/internal/bundle/file_unix.go new file mode 100644 index 0000000..d0441cf --- /dev/null +++ b/internal/bundle/file_unix.go @@ -0,0 +1,8 @@ +//go:build !windows + +package bundle + +import "os" + +func privateFile(file *os.File) error { return file.Chmod(0600) } +func replaceFile(from, to string) error { return os.Rename(from, to) } diff --git a/internal/bundle/file_windows.go b/internal/bundle/file_windows.go new file mode 100644 index 0000000..ec0973e --- /dev/null +++ b/internal/bundle/file_windows.go @@ -0,0 +1,39 @@ +//go:build windows + +package bundle + +import ( + "os" + + "golang.org/x/sys/windows" +) + +func privateFile(file *os.File) error { + user, err := windows.GetCurrentProcessToken().GetTokenUser() + if err != nil { + return err + } + sd, err := windows.SecurityDescriptorFromString("D:P(A;;FA;;;SY)(A;;FA;;;" + user.User.Sid.String() + ")") + if err != nil { + return err + } + dacl, _, err := sd.DACL() + if err != nil { + return err + } + // os.CreateTemp's handle has data access, not WRITE_DAC. The file remains + // open without delete sharing while this API obtains the required access. + return windows.SetNamedSecurityInfo(file.Name(), windows.SE_FILE_OBJECT, windows.DACL_SECURITY_INFORMATION|windows.PROTECTED_DACL_SECURITY_INFORMATION, nil, nil, dacl, nil) +} + +func replaceFile(from, to string) error { + f, err := windows.UTF16PtrFromString(from) + if err != nil { + return err + } + t, err := windows.UTF16PtrFromString(to) + if err != nil { + return err + } + return windows.MoveFileEx(f, t, windows.MOVEFILE_REPLACE_EXISTING|windows.MOVEFILE_WRITE_THROUGH) +} diff --git a/internal/bundle/file_windows_test.go b/internal/bundle/file_windows_test.go new file mode 100644 index 0000000..73164f6 --- /dev/null +++ b/internal/bundle/file_windows_test.go @@ -0,0 +1,65 @@ +//go:build windows + +package bundle + +import ( + "bytes" + "context" + "errors" + "os" + "path/filepath" + "testing" + + "golang.org/x/sys/windows" +) + +func TestM4WindowsAtomicReplaceLockedDestination(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "capture.zip") + previous := []byte("previous regular destination") + if err := os.WriteFile(path, previous, 0600); err != nil { + t.Fatal(err) + } + p, err := windows.UTF16PtrFromString(path) + if err != nil { + t.Fatal(err) + } + h, err := windows.CreateFile(p, windows.GENERIC_READ, windows.FILE_SHARE_READ, nil, windows.OPEN_EXISTING, windows.FILE_ATTRIBUTE_NORMAL, 0) + if err != nil { + t.Fatal(err) + } + defer func() { _ = windows.CloseHandle(h) }() + if err := Publish(context.Background(), path, publicationArchive(t)); !errors.Is(err, ErrWrite) { + t.Fatalf("locked replacement: %v", err) + } + got, err := os.ReadFile(path) + if err != nil || !bytes.Equal(got, previous) { + t.Fatal("locked destination changed") + } + entries, err := os.ReadDir(dir) + if err != nil || len(entries) != 1 { + t.Fatal("locked replacement retained temporary file") + } +} + +func TestM4WindowsPublicationHasPrivateProtectedACL(t *testing.T) { + path := filepath.Join(t.TempDir(), "capture.zip") + if err := Publish(context.Background(), path, publicationArchive(t)); err != nil { + t.Fatal(err) + } + sd, err := windows.GetNamedSecurityInfo(path, windows.SE_FILE_OBJECT, windows.DACL_SECURITY_INFORMATION) + if err != nil { + t.Fatal(err) + } + control, _, err := sd.Control() + if err != nil { + t.Fatal(err) + } + if control&windows.SE_DACL_PROTECTED == 0 { + t.Fatal("staged publication inherited a non-private ACL") + } + dacl, _, err := sd.DACL() + if err != nil || dacl == nil { + t.Fatal("private DACL missing") + } +} diff --git a/internal/bundle/json.go b/internal/bundle/json.go new file mode 100644 index 0000000..68e8754 --- /dev/null +++ b/internal/bundle/json.go @@ -0,0 +1,196 @@ +package bundle + +import ( + "bytes" + "context" + "encoding/json" + "io" + "reflect" + "strconv" + "strings" + "sync" + "time" + "unicode/utf8" +) + +type jsonField struct { + typ reflect.Type + required bool +} + +var jsonFields sync.Map + +func fieldsFor(typ reflect.Type) map[string]jsonField { + if cached, ok := jsonFields.Load(typ); ok { + return cached.(map[string]jsonField) + } + fields := map[string]jsonField{} + for i := 0; i < typ.NumField(); i++ { + field := typ.Field(i) + tag := strings.Split(field.Tag.Get("json"), ",") + if tag[0] == "" || tag[0] == "-" { + continue + } + fields[tag[0]] = jsonField{typ: field.Type, required: !allowed("omitempty", tag[1:]...)} + } + jsonFields.Store(typ, fields) + return fields +} + +type jsonScanner struct { + ctx context.Context + decoder *json.Decoder + tokens int +} + +func (s *jsonScanner) token() (json.Token, error) { + if err := s.ctx.Err(); err != nil { + return nil, err + } + s.tokens++ + if s.tokens > 200_000 { + return nil, ErrBounds + } + t, err := s.decoder.Token() + if err != nil { + return nil, ErrInvalid + } + if value, ok := t.(string); ok && len(value) > 4096 { + return nil, ErrBounds + } + if value, ok := t.(json.Number); ok && len(value) > 32 { + return nil, ErrBounds + } + return t, nil +} + +func (s *jsonScanner) value(typ reflect.Type, depth int) error { + if depth > 32 { + return ErrBounds + } + t, err := s.token() + if err != nil { + return err + } + if typ.Kind() == reflect.Pointer { + // Only the required legacy identity presence markers are nullable. + if t == nil && typ.Elem().Kind() == reflect.String { + return nil + } + typ = typ.Elem() + } + if typ == reflect.TypeFor[time.Time]() { + value, ok := t.(string) + if !ok || !strings.HasSuffix(value, "Z") { + return ErrInvalid + } + parsed, err := time.Parse(time.RFC3339Nano, value) + if err != nil || parsed.IsZero() || parsed.Format(time.RFC3339Nano) != value { + return ErrInvalid + } + return nil + } + switch typ.Kind() { + case reflect.Struct: + if t != json.Delim('{') { + return ErrInvalid + } + fields, seen := fieldsFor(typ), map[string]bool{} + for s.decoder.More() { + key, err := s.token() + if err != nil { + return err + } + name, ok := key.(string) + if !ok || seen[name] { + return ErrInvalid + } + field, ok := fields[name] + if !ok { + return ErrInvalid + } + seen[name] = true + if err := s.value(field.typ, depth+1); err != nil { + return err + } + } + end, err := s.token() + if err != nil { + return err + } + if end != json.Delim('}') { + return ErrInvalid + } + for name, field := range fields { + if field.required && !seen[name] { + return ErrInvalid + } + } + case reflect.Slice: + if t != json.Delim('[') { + return ErrInvalid + } + count := 0 + for s.decoder.More() { + count++ + if count > 4096 { + return ErrBounds + } + if err := s.value(typ.Elem(), depth+1); err != nil { + return err + } + } + end, err := s.token() + if err != nil { + return err + } + if end != json.Delim(']') { + return ErrInvalid + } + case reflect.String: + if _, ok := t.(string); !ok { + return ErrInvalid + } + case reflect.Bool: + if _, ok := t.(bool); !ok { + return ErrInvalid + } + case reflect.Int, reflect.Int64: + number, ok := t.(json.Number) + if !ok { + return ErrInvalid + } + if _, err := strconv.ParseInt(string(number), 10, typ.Bits()); err != nil { + return ErrInvalid + } + default: + return ErrInvalid + } + return nil +} + +// Preflight grammar/work/required fields without constructing an interface{} +// graph. Exact JSON tags also reject encoding/json's case-insensitive aliases. +func decodeJSON(ctx context.Context, data []byte, destination any) error { + if !utf8.Valid(data) { + return ErrInvalid + } + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.UseNumber() + s := jsonScanner{ctx: ctx, decoder: decoder} + if err := s.value(reflect.TypeOf(destination).Elem(), 1); err != nil { + return err + } + if _, err := decoder.Token(); err != io.EOF { + return ErrInvalid + } + if err := ctx.Err(); err != nil { + return err + } + decoder = json.NewDecoder(bytes.NewReader(data)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(destination); err != nil { + return ErrInvalid + } + return nil +} diff --git a/internal/bundle/model.go b/internal/bundle/model.go new file mode 100644 index 0000000..3dfb3b8 --- /dev/null +++ b/internal/bundle/model.go @@ -0,0 +1,198 @@ +// Package bundle implements the separate allowlisted sharing format in ADR 0006. +// Archives are data: no member is extracted, executed or used as a live target. +package bundle + +import ( + "errors" + "time" + + "github.com/shellghostt/envdoctor/internal/collector" + "github.com/shellghostt/envdoctor/internal/report" +) + +const ( + Version = 1 + Policy = "allowlist-v1" + MaxArchiveBytes = 2_000_000 + MaxUncompressedBytes = 8 << 20 + MaxEntries = 8 +) + +var ( + ErrInvalid = errors.New("invalid diagnostic bundle") + ErrBounds = errors.New("diagnostic bundle exceeds a resource limit") + ErrVersion = errors.New("unsupported diagnostic bundle version") + ErrIntegrity = errors.New("diagnostic bundle integrity check failed") + ErrEvidence = errors.New("diagnostic evidence cannot be represented by the sharing policy") + ErrRead = errors.New("cannot read diagnostic bundle") + ErrWrite = errors.New("cannot publish diagnostic bundle") +) + +var memberLimits = map[string]int{ + "manifest.json": 64 << 10, "snapshot.json": 2 << 20, + "report.json": 3 << 20, "report.md": 2 << 20, + "versions.json": 64 << 10, "diagnostics.json": 512 << 10, +} + +var requiredMembers = []string{"manifest.json", "snapshot.json", "report.json", "report.md", "versions.json"} + +type Options struct{ IncludeLogs bool } + +type Member struct { + Name string `json:"name"` + Size int `json:"size"` + SHA256 string `json:"sha256"` +} + +type Manifest struct { + BundleVersion int `json:"bundleVersion"` + SnapshotVersion int `json:"snapshotVersion"` + ReportVersion int `json:"reportVersion"` + RedactionPolicy string `json:"redactionPolicy"` + Tool report.Tool `json:"tool"` + CapturedAt time.Time `json:"capturedAt"` + CaptureExitCode int `json:"captureExitCode"` + Omissions []report.Omission `json:"omissions"` + Members []Member `json:"members"` +} + +// SharingSnapshot is deliberately separate from collector.Snapshot. New raw +// collector fields cannot start appearing in exports through struct copying. +type SharingSnapshot struct { + SchemaVersion int `json:"schemaVersion"` + CollectedAt time.Time `json:"collectedAt"` + Platform *Platform `json:"platform,omitempty"` + Shell *Shell `json:"shell,omitempty"` + Path *PathInfo `json:"path,omitempty"` + Runtimes []Runtime `json:"runtimes,omitempty"` + Ports []Port `json:"ports,omitempty"` + RequestedPorts []int `json:"requestedPorts,omitempty"` + Docker *Docker `json:"docker,omitempty"` + Git *Git `json:"git,omitempty"` + Dependencies *Dependencies `json:"dependencies,omitempty"` + PythonEnvironment *PythonEnvironment `json:"pythonEnvironment,omitempty"` + Proxies []Proxy `json:"proxies,omitempty"` + NoProxyConfigured bool `json:"noProxyConfigured,omitempty"` + Errors []Failure `json:"errors,omitempty"` +} + +type Platform struct { + OS string `json:"os"` + Version string `json:"version"` + Arch string `json:"arch"` + Elevated bool `json:"elevated"` +} +type Shell struct { + Name string `json:"name"` +} +type PathInfo struct { + Entries []PathEntry `json:"entries"` +} +type PathEntry struct { + Token string `json:"token"` + Exists bool `json:"exists"` + IsDir bool `json:"isDir"` + Position int `json:"position"` + Duplicate bool `json:"duplicate"` +} +type Runtime struct { + Name string `json:"name"` + Version string `json:"version"` + PathToken string `json:"pathToken"` + Manager string `json:"manager"` + Active bool `json:"active"` + Expected bool `json:"expected,omitempty"` + Missing bool `json:"missing,omitempty"` + ResolvedToken string `json:"resolvedToken,omitempty"` + Resolution string `json:"resolution,omitempty"` + EnvironmentToken string `json:"environmentToken,omitempty"` +} +type Port struct { + Port int `json:"port"` + Protocol string `json:"protocol"` + State string `json:"state"` +} +type Docker struct { + CLIVersion string `json:"cliVersion"` + Installed bool `json:"installed"` + DaemonReachable bool `json:"daemonReachable"` + ProbeStatus string `json:"probeStatus,omitempty"` + ClientAPI string `json:"clientApi,omitempty"` + ClientMinAPI string `json:"clientMinApi,omitempty"` + ClientDefaultAPI string `json:"clientDefaultApi,omitempty"` + ServerAPI string `json:"serverApi,omitempty"` + ServerMinAPI string `json:"serverMinApi,omitempty"` + APIOverride string `json:"apiOverride,omitempty"` +} +type Git struct { + Version string `json:"version"` + UserNamePresent bool `json:"userNamePresent"` + UserEmailPresent bool `json:"userEmailPresent"` + IdentityChecked bool `json:"identityChecked"` + Autocrlf string `json:"autocrlf"` + AutocrlfOriginKnown bool `json:"autocrlfOriginKnown"` +} +type Dependencies struct { + ProjectToken string `json:"projectToken"` + RequirementsDeclared bool `json:"requirementsDeclared"` + Requirements []Dependency `json:"requirements,omitempty"` + Package *PackageEvidence `json:"package,omitempty"` + GitAutocrlf string `json:"gitAutocrlf,omitempty"` +} +type Dependency struct { + Kind string `json:"kind"` + Name string `json:"name"` + PathToken string `json:"pathToken,omitempty"` + Status string `json:"status"` +} +type PackageManager struct { + Name string `json:"name"` + Version string `json:"version,omitempty"` +} +type PackageEvidence struct { + ManifestPresent bool `json:"manifestPresent"` + Declared *PackageManager `json:"declared,omitempty"` + Runner *PackageManager `json:"runner,omitempty"` + Lockfiles []string `json:"lockfiles,omitempty"` +} +type PythonEnvironment struct { + RootToken string `json:"rootToken"` + CanonicalToken string `json:"canonicalToken,omitempty"` + MetadataKnown bool `json:"metadataKnown"` +} +type Proxy struct { + Variable string `json:"variable"` + Scheme string `json:"scheme"` + HostToken string `json:"hostToken"` + Port int `json:"port"` + Probe string `json:"probe"` +} +type Failure struct { + Collector string `json:"collector"` + Reason string `json:"reason"` +} +type Diagnostic struct { + Collector string `json:"collector"` + DurationMs int64 `json:"durationMs"` + Status string `json:"status"` +} +type Diagnostics struct { + SchemaVersion int `json:"schemaVersion"` + Collectors []Diagnostic `json:"collectors"` +} +type RuntimeVersion struct { + Name string `json:"name"` + Version string `json:"version"` +} +type Versions struct { + SchemaVersion int `json:"schemaVersion"` + Tool report.Tool `json:"tool"` + Runtimes []RuntimeVersion `json:"runtimes"` + Git string `json:"git,omitempty"` + Docker string `json:"docker,omitempty"` +} + +type Capture struct { + Snapshot collector.Snapshot + Source report.Source +} diff --git a/internal/bundle/model_coverage.go b/internal/bundle/model_coverage.go new file mode 100644 index 0000000..8648d07 --- /dev/null +++ b/internal/bundle/model_coverage.go @@ -0,0 +1,47 @@ +package bundle + +import ( + "reflect" + "strings" + "sync" + + "github.com/shellghostt/envdoctor/internal/collector" + "github.com/shellghostt/envdoctor/internal/report" +) + +// A new source-model field requires an explicit sharing decision. Separate +// output types prevent raw copying; this guard also prevents silently ignoring +// a future fact that might be a new prerequisite. Order is intentionally exact. +var currentSourceModel = sync.OnceValue(func() bool { + for typ, names := range map[reflect.Type]string{ + reflect.TypeFor[collector.Snapshot](): "SchemaVersion CollectedAt Platform Shell Path Runtimes Ports RequestedPorts Docker Git Dependencies PythonEnvironment Proxies NoProxyConfigured Errors", + reflect.TypeFor[collector.Platform](): "OS Version Arch Elevated", + reflect.TypeFor[collector.Shell](): "Name Path", + reflect.TypeFor[collector.PathInfo](): "Entries", + reflect.TypeFor[collector.PathEntry](): "Raw Exists IsDir Position Duplicate", + reflect.TypeFor[collector.Runtime](): "Name Version Path Manager Active Expected Missing ResolvedPath Resolution EnvironmentRoot", + reflect.TypeFor[collector.Port](): "Port Protocol State PID Process", + reflect.TypeFor[collector.Docker](): "CLIVersion DaemonReachable Context Installed ProbeStatus ClientAPI ClientMinAPI ClientDefaultAPI ServerAPI ServerMinAPI APIOverride SelectedContext SelectedHost", + reflect.TypeFor[collector.Git](): "Version UserName UserEmail Autocrlf IdentityChecked UserNameOrigin UserEmailOrigin AutocrlfOrigin", + reflect.TypeFor[collector.Dependencies](): "ProjectRoot RequirementsFile Requirements Package GitAutocrlf", + reflect.TypeFor[collector.Dependency](): "Kind Name Path Status", + reflect.TypeFor[collector.PackageManager](): "Name Version", + reflect.TypeFor[collector.PackageEvidence](): "Manifest Declared Runner Lockfiles", + reflect.TypeFor[collector.PythonEnvironment](): "Root CanonicalRoot MetadataKnown", + reflect.TypeFor[collector.Proxy](): "Variable URL Host Port Probe", + reflect.TypeFor[collector.CollectorError](): "Collector Message", + reflect.TypeFor[report.Tool](): "Name Version", + reflect.TypeFor[report.Collector](): "Name DurationMs Error", + } { + fields := strings.Fields(names) + if typ.NumField() != len(fields) { + return false + } + for i, name := range fields { + if typ.Field(i).Name != name { + return false + } + } + } + return true +}) diff --git a/internal/bundle/parser_test.go b/internal/bundle/parser_test.go new file mode 100644 index 0000000..2c706fd --- /dev/null +++ b/internal/bundle/parser_test.go @@ -0,0 +1,65 @@ +package bundle + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "io" + "strings" + "testing" +) + +type deepJSON struct { + Child *deepJSON `json:"child,omitempty"` +} +type tokenJSON struct { + Rows [][]int `json:"rows"` +} +type stringJSON struct { + Value string `json:"value"` +} + +func TestM4JSONIndependentWorkBounds(t *testing.T) { + for _, tc := range []struct { + name string + data []byte + target any + want error + }{ + {"depth", []byte(strings.Repeat(`{"child":`, 32) + `{}` + strings.Repeat(`}`, 32)), &deepJSON{}, ErrBounds}, + {"array", []byte(`{"rows":[[` + strings.Repeat(`1,`, 4096) + `1]]}`), &tokenJSON{}, ErrBounds}, + {"tokens", []byte(`{"rows":[` + strings.Repeat(`[`+strings.Repeat(`1,`, 4095)+`1],`, 50) + `[` + strings.Repeat(`1,`, 4095) + `1]]}`), &tokenJSON{}, ErrBounds}, + {"UTF8-byte-length", []byte(`{"value":"` + strings.Repeat("界", 1366) + `"}`), &stringJSON{}, ErrBounds}, + {"escaped-key-duplicate", []byte(`{"value":"one","\u0076alue":"two"}`), &stringJSON{}, ErrInvalid}, + {"case-alias", []byte(`{"Value":"one"}`), &stringJSON{}, ErrInvalid}, + {"null-required", []byte(`{"value":null}`), &stringJSON{}, ErrInvalid}, + {"missing-required", []byte(`{}`), &stringJSON{}, ErrInvalid}, + } { + t.Run(tc.name, func(t *testing.T) { + if err := decodeJSON(context.Background(), tc.data, tc.target); !errors.Is(err, tc.want) { + t.Fatalf("got=%v want=%v", err, tc.want) + } + }) + } + data, _ := json.Marshal(stringJSON{Value: strings.Repeat("A", 4096)}) + if err := decodeJSON(context.Background(), data, &stringJSON{}); err != nil { + t.Fatalf("exact string boundary: %v", err) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + if err := decodeJSON(ctx, data, &stringJSON{}); !errors.Is(err, context.Canceled) { + t.Fatalf("cancel=%v", err) + } +} + +func TestM4ArchiveBufferCannotBypassSizeGuard(t *testing.T) { + out := &archiveBuffer{ctx: context.Background()} + if _, ok := any(out).(io.ReaderFrom); ok { + t.Fatal("unbounded ReaderFrom exposed") + } + _, err := io.Copy(out, bytes.NewReader(bytes.Repeat([]byte{0}, MaxArchiveBytes))) + if !errors.Is(err, ErrBounds) || out.Len() >= MaxArchiveBytes { + t.Fatalf("guard bypassed: size=%d error=%v", out.Len(), err) + } +} diff --git a/internal/bundle/roundtrip_test.go b/internal/bundle/roundtrip_test.go new file mode 100644 index 0000000..93ed9af --- /dev/null +++ b/internal/bundle/roundtrip_test.go @@ -0,0 +1,213 @@ +package bundle_test + +import ( + "bytes" + "context" + "encoding/json" + "os" + "path/filepath" + "reflect" + "runtime" + "strings" + "testing" + "time" + + "github.com/shellghostt/envdoctor/internal/bundle" + "github.com/shellghostt/envdoctor/internal/diagnostic" + "github.com/shellghostt/envdoctor/internal/report" +) + +func TestM4All172GoldenCapturesRoundTripAcrossOS(t *testing.T) { + dir := filepath.Join("..", "..", "tests", "golden") + files, err := filepath.Glob(filepath.Join(dir, "*.json")) + if err != nil { + t.Fatal(err) + } + if len(files) != 172 { + t.Fatalf("original golden corpus changed: %d", len(files)) + } + osSeen := map[string]bool{} + for _, file := range files { + t.Run(filepath.Base(file), func(t *testing.T) { + raw, err := os.ReadFile(file) + if err != nil { + t.Fatal(err) + } + fixture, err := diagnostic.LoadFixture(bytes.NewReader(raw)) + if err != nil { + t.Fatal(err) + } + s := fixture.Snapshot + if s.Platform != nil { + osSeen[s.Platform.OS] = true + } + findings, err := diagnostic.DefaultEngine().Evaluate(s, diagnostic.Filter{}) + if err != nil { + t.Fatal(err) + } + doc := report.NewDocument("0.1.0", s.CollectedAt, s, findings, nil, 12) + data, err := bundle.Build(context.Background(), doc, bundle.Options{IncludeLogs: true}) + if err != nil { + t.Fatal(err) + } + capture, err := bundle.Read(context.Background(), data) + if err != nil { + t.Fatal(err) + } + got, err := diagnostic.DefaultEngine().Evaluate(capture.Snapshot, diagnostic.Filter{RuleID: fixture.RuleID}) + if err != nil { + t.Fatal(err) + } + metadata, _ := diagnostic.LookupRule(fixture.RuleID) + blocked := false + for _, failure := range capture.Snapshot.Errors { + for _, pre := range metadata.Prerequisites { + blocked = blocked || failure.Collector == pre + } + } + if blocked { + if len(got) != 0 { + t.Fatal("unavailable prerequisite produced conclusive findings") + } + return + } + if len(got) != len(fixture.ExpectedFindings) { + t.Fatalf("findings lost: got=%v expected=%v", got, fixture.ExpectedFindings) + } + for i, f := range got { + want := fixture.ExpectedFindings[i] + // Evidence locations/owners intentionally change; verdict and all + // registry-owned policy/advice must remain identical. + f.Detected = nil + want.Detected = nil + if !reflect.DeepEqual(f, want) { + t.Fatalf("retained verdict changed: got=%+v want=%+v", f, want) + } + } + again, err := bundle.Build(context.Background(), doc, bundle.Options{IncludeLogs: true}) + if err != nil || !bytes.Equal(data, again) { + t.Fatal("same capture did not produce deterministic aliases/archive") + } + }) + } + for _, goos := range []string{"windows", "linux", "darwin"} { + if !osSeen[goos] { + t.Errorf("capture OS %s missing", goos) + } + } +} + +func TestM4EnvironmentAliasUsesCapturedOSAndExactPaths(t *testing.T) { + for _, goos := range []string{"windows", "linux", "darwin"} { + doc := sensitiveDocument() + doc.Snapshot.Errors = nil + doc.Snapshot.Platform.OS = goos + doc.Snapshot.Runtimes = doc.Snapshot.Runtimes[:1] + doc.Snapshot.PythonEnvironment.CanonicalRoot = "/Capture/ENV" + doc.Snapshot.PythonEnvironment.Root = "/Capture/ENV" + doc.Snapshot.Runtimes[0].EnvironmentRoot = "/capture/env/./" + data, err := bundle.Build(context.Background(), doc, bundle.Options{}) + if err != nil { + t.Fatal(err) + } + capture, err := bundle.Read(context.Background(), data) + if err != nil { + t.Fatal(err) + } + results, err := diagnostic.DefaultEngine().Evaluate(capture.Snapshot, diagnostic.Filter{RuleID: "ENV011"}) + if err != nil { + t.Fatal(err) + } + if (len(results) > 0) != (goos != "windows") { + t.Fatalf("capture %s used receiving OS normalization", goos) + } + } + doc := sensitiveDocument() + doc.Snapshot.Errors = nil + doc.Snapshot.Runtimes[1].Path = strings.ToLower(doc.Snapshot.Runtimes[0].Path) + data, err := bundle.Build(context.Background(), doc, bundle.Options{}) + if err != nil { + t.Fatal(err) + } + capture, err := bundle.Read(context.Background(), data) + if err != nil { + t.Fatal(err) + } + if capture.Snapshot.Runtimes[0].Path == capture.Snapshot.Runtimes[1].Path { + t.Fatal("exact path comparison collapsed distinct case") + } +} + +func TestM4RepeatedBundleLifecycleReleasesResources(t *testing.T) { + doc := sensitiveDocument() + data, err := bundle.Build(context.Background(), doc, bundle.Options{IncludeLogs: true}) + if err != nil { + t.Fatal(err) + } + runtime.GC() + var before, after runtime.MemStats + runtime.ReadMemStats(&before) + beforeG := runtime.NumGoroutine() + start := time.Now() + for i := 0; i < 100; i++ { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + out, err := bundle.Build(ctx, doc, bundle.Options{IncludeLogs: true}) + if err != nil { + t.Fatal(err) + } + if _, err := bundle.Read(ctx, out); err != nil { + t.Fatal(err) + } + cancel() + if _, err := bundle.Read(ctx, out); err == nil { + t.Fatal("canceled read succeeded") + } + } + runtime.GC() + runtime.ReadMemStats(&after) + afterG := runtime.NumGoroutine() + t.Logf("100 bundle build/read cycles: %s; archive %d bytes; goroutines %d -> %d; retained heap %d -> %d", time.Since(start), len(data), beforeG, afterG, before.HeapAlloc, after.HeapAlloc) + if afterG > beforeG+2 || int64(after.HeapAlloc)-int64(before.HeapAlloc) > 2<<20 { + t.Fatal("bundle resources retained") + } +} + +func BenchmarkM4BundleBuildRead(b *testing.B) { + doc := sensitiveDocument() + data, err := bundle.Build(context.Background(), doc, bundle.Options{IncludeLogs: true}) + if err != nil { + b.Fatal(err) + } + b.SetBytes(int64(len(data))) + b.ReportAllocs() + b.ResetTimer() + for i := 0; i < b.N; i++ { + data, err := bundle.Build(context.Background(), doc, bundle.Options{IncludeLogs: true}) + if err != nil { + b.Fatal(err) + } + if _, err := bundle.Read(context.Background(), data); err != nil { + b.Fatal(err) + } + } +} + +func FuzzM4BundleReader(f *testing.F) { + data, err := bundle.Build(context.Background(), sensitiveDocument(), bundle.Options{IncludeLogs: true}) + if err != nil { + f.Fatal(err) + } + f.Add(data) + f.Add([]byte("not a zip")) + f.Add([]byte{}) + f.Fuzz(func(t *testing.T, data []byte) { + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + capture, err := bundle.Read(ctx, data) + if err == nil { + if _, err := json.Marshal(capture); err != nil { + t.Fatal(err) + } + } + }) +} diff --git a/internal/bundle/schema_test.go b/internal/bundle/schema_test.go new file mode 100644 index 0000000..2325a79 --- /dev/null +++ b/internal/bundle/schema_test.go @@ -0,0 +1,129 @@ +package bundle_test + +import ( + "archive/zip" + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "os" + "path/filepath" + "testing" + + "github.com/santhosh-tekuri/jsonschema/v5" + "github.com/shellghostt/envdoctor/internal/bundle" + "github.com/shellghostt/envdoctor/internal/report" +) + +func compileBundleSchemas(t *testing.T) map[string]*jsonschema.Schema { + t.Helper() + compiler := jsonschema.NewCompiler() + compiler.LoadURL = func(string) (io.ReadCloser, error) { + return nil, fmt.Errorf("unregistered schema; network loading forbidden") + } + dir := filepath.Join("..", "..", "docs", "schema") + files, err := filepath.Glob(filepath.Join(dir, "*.schema.json")) + if err != nil { + t.Fatal(err) + } + for _, file := range files { + data, err := os.ReadFile(file) + if err != nil { + t.Fatal(err) + } + var id struct { + ID string `json:"$id"` + } + if err := json.Unmarshal(data, &id); err != nil { + t.Fatal(err) + } + if err := compiler.AddResource(id.ID, bytes.NewReader(data)); err != nil { + t.Fatal(err) + } + } + result := map[string]*jsonschema.Schema{} + for member, name := range map[string]string{"manifest.json": "bundle-manifest-v1", "snapshot.json": "bundle-snapshot-v1", "report.json": "bundle-report-v1", "versions.json": "bundle-versions-v1", "diagnostics.json": "bundle-diagnostics-v1"} { + schema, err := compiler.Compile("https://github.com/shellghostt/envdoctor/schema/" + name + ".schema.json") + if err != nil { + t.Fatal(err) + } + result[member] = schema + } + return result +} + +func TestM4BundleMembersMatchCommittedSchemas(t *testing.T) { + schemas := compileBundleSchemas(t) + unsupported := sensitiveDocument() + unsupported.Snapshot.Runtimes[0].Version = "SECRET-VERSION" + for _, doc := range []report.Document{sensitiveDocument(), unsupported} { + data, err := bundle.Build(context.Background(), doc, bundle.Options{IncludeLogs: true}) + if err != nil { + t.Fatal(err) + } + for name, body := range members(t, data) { + if name == "report.md" { + continue + } + var value any + if err := json.Unmarshal(body, &value); err != nil { + t.Fatal(err) + } + if err := schemas[name].Validate(value); err != nil { + t.Fatalf("%s does not match committed schema: %v", name, err) + } + } + } +} + +func TestM4OptionalEmptyAliasesMatchSchemaAndReader(t *testing.T) { + doc := sensitiveDocument() + for i := range doc.Snapshot.Runtimes { + doc.Snapshot.Runtimes[i].ResolvedPath = "" + doc.Snapshot.Runtimes[i].EnvironmentRoot = "" + } + doc.Snapshot.Dependencies.Requirements[0].Path = "" + doc.Snapshot.PythonEnvironment.CanonicalRoot = "" + doc.Snapshot.PythonEnvironment.MetadataKnown = false + data, err := bundle.Build(context.Background(), doc, bundle.Options{}) + if err != nil { + t.Fatal(err) + } + all := members(t, data) + var snapshot map[string]any + if err := json.Unmarshal(all["snapshot.json"], &snapshot); err != nil { + t.Fatal(err) + } + for _, value := range snapshot["runtimes"].([]any) { + runtime := value.(map[string]any) + runtime["resolvedToken"], runtime["environmentToken"] = "", "" + } + requirement := snapshot["dependencies"].(map[string]any)["requirements"].([]any)[0].(map[string]any) + requirement["pathToken"] = "" + snapshot["pythonEnvironment"].(map[string]any)["canonicalToken"] = "" + schema := compileBundleSchemas(t)["snapshot.json"] + if err := schema.Validate(snapshot); err != nil { + t.Fatalf("empty optional aliases disagree with schema: %v", err) + } + all["snapshot.json"], err = json.Marshal(snapshot) + if err != nil { + t.Fatal(err) + } + if _, err := bundle.Read(context.Background(), repack(t, all, zip.Deflate)); err != nil { + t.Fatalf("empty optional aliases disagree with reader: %v", err) + } + for _, invalid := range []string{"C:/Users/SECRET-IDENTITY", "path-0000", "path-4097"} { + requirement["pathToken"] = invalid + if err := schema.Validate(snapshot); err == nil { + t.Fatalf("schema accepted invalid alias %q", invalid) + } + all["snapshot.json"], err = json.Marshal(snapshot) + if err != nil { + t.Fatal(err) + } + if _, err := bundle.Read(context.Background(), repack(t, all, zip.Deflate)); err == nil { + t.Fatalf("reader accepted invalid alias %q", invalid) + } + } +} diff --git a/internal/bundle/validate.go b/internal/bundle/validate.go new file mode 100644 index 0000000..2b1b6da --- /dev/null +++ b/internal/bundle/validate.go @@ -0,0 +1,274 @@ +package bundle + +import ( + "crypto/sha256" + "encoding/hex" + "reflect" + "strconv" + "strings" + + "github.com/shellghostt/envdoctor/internal/diagnostic" + "github.com/shellghostt/envdoctor/internal/report" +) + +var omissionFields = []string{"platform", "platform.version", "shell.name", "shell.path", "path.locations", "runtimes.paths", "runtimes.version", "runtimes.name", "runtimes.manager", "runtimes.resolution", "runtimes.environment", "network.ownership", "docker.context", "docker.endpoint", "docker.version", "docker.api", "git.identity", "git.origins", "git.version", "git.autocrlf", "dependencies.locations", "dependencies.requirement", "dependencies.packageManager", "dependencies.lockfile", "dependencies.gitAutocrlf", "pythonEnvironment.locations", "proxy.endpoint", "proxy.url", "collector.errors", "tool.version"} + +func validToken(value string, kind string, optional bool) bool { + if value == "" { + return optional + } + var digits string + switch kind { + case "path": + if !pathToken.MatchString(value) { + return false + } + digits = value[5:] + case "env": + if !environmentToken.MatchString(value) { + return false + } + digits = value[4:] + case "host": + if !hostToken.MatchString(value) { + return false + } + digits = strings.TrimSuffix(value[5:], ".invalid") + default: + return false + } + n, err := strconv.Atoi(digits) + return err == nil && n >= 1 && n <= 4096 +} + +func validateSnapshot(s SharingSnapshot) error { + if s.SchemaVersion != 1 { + return ErrVersion + } + if s.CollectedAt.IsZero() { + return ErrInvalid + } + if len(s.Runtimes) > 128 || len(s.Ports) > 1024 || len(s.RequestedPorts) > 1024 || len(s.Proxies) > 3 || len(s.Errors) > 32 || s.Path != nil && len(s.Path.Entries) > 1024 || s.Dependencies != nil && len(s.Dependencies.Requirements) > 32 { + return ErrBounds + } + if p := s.Platform; p != nil { + if !allowed(p.OS, "windows", "linux", "darwin") || !allowed(p.Arch, "amd64", "arm64", "386", "arm", "ppc64le", "s390x", "riscv64") || !version(p.Version) { + return ErrInvalid + } + } + if s.Shell != nil && !knownShell(s.Shell.Name) { + return ErrInvalid + } + if p := s.Path; p != nil { + for i, e := range p.Entries { + if !validToken(e.Token, "path", false) || e.Position != i || e.IsDir && !e.Exists { + return ErrInvalid + } + } + } + for _, r := range s.Runtimes { + if !allowed(r.Name, "python", "node") || !knownManager(r.Manager) || !version(r.Version) || !validToken(r.PathToken, "path", false) || !validToken(r.ResolvedToken, "path", true) || !validToken(r.EnvironmentToken, "env", true) || !allowed(r.Resolution, "", "known", "unknown") { + return ErrInvalid + } + } + for _, p := range s.RequestedPorts { + if p < 1 || p > 65535 { + return ErrInvalid + } + } + for _, p := range s.Ports { + if p.Port < 1 || p.Port > 65535 || !allowed(p.Protocol, "tcp", "udp") || !allowed(p.State, "listen", "established", "closed", "unknown") { + return ErrInvalid + } + } + if d := s.Docker; d != nil { + if !version(d.CLIVersion) || !allowed(d.ProbeStatus, "", "absent", "available", "unavailable", "unknown", "denied", "unsupported") { + return ErrInvalid + } + for _, v := range []string{d.ClientAPI, d.ClientMinAPI, d.ClientDefaultAPI, d.ServerAPI, d.ServerMinAPI, d.APIOverride} { + if !knownAPI(v) { + return ErrInvalid + } + } + if d.ProbeStatus == "available" && (!d.Installed || !d.DaemonReachable) || d.ProbeStatus == "absent" && d.Installed { + return ErrInvalid + } + } + if g := s.Git; g != nil { + if !version(g.Version) || !knownAutocrlf(g.Autocrlf) { + return ErrInvalid + } + } + if d := s.Dependencies; d != nil { + if !validToken(d.ProjectToken, "path", true) || !knownAutocrlf(d.GitAutocrlf) { + return ErrInvalid + } + for _, r := range d.Requirements { + if !knownDependency(r.Kind, r.Name) || !allowed(r.Status, "present", "missing", "unknown") || !validToken(r.PathToken, "path", true) { + return ErrInvalid + } + } + if p := d.Package; p != nil { + for _, m := range []*PackageManager{p.Declared, p.Runner} { + if m != nil && (!knownPackageManager(m.Name) || m.Version != "" && !exactVersion(m.Version)) { + return ErrInvalid + } + } + if p.Declared != nil && !exactVersion(p.Declared.Version) { + return ErrInvalid + } + for _, lock := range p.Lockfiles { + if !knownLockfile(lock) { + return ErrInvalid + } + } + } + } + if e := s.PythonEnvironment; e != nil { + if !validToken(e.RootToken, "env", true) || !validToken(e.CanonicalToken, "env", true) || e.MetadataKnown && e.CanonicalToken == "" { + return ErrInvalid + } + } + seen := map[string]bool{} + for _, p := range s.Proxies { + if seen[p.Variable] || !allowed(p.Variable, "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY") || !allowed(p.Scheme, "http", "https", "socks5", "socks5h") || !validToken(p.HostToken, "host", false) || p.Port < 1 || p.Port > 65535 || !allowed(p.Probe, "untested", "reachable", "unreachable", "unknown", "invalid") { + return ErrInvalid + } + seen[p.Variable] = true + } + seen = map[string]bool{} + for _, f := range s.Errors { + if !knownCollector(f.Collector) || f.Reason != "unavailable" || seen[f.Collector] { + return ErrInvalid + } + seen[f.Collector] = true + } + return nil +} + +func validateManifest(m Manifest, all map[string][]byte) error { + if m.BundleVersion != 1 || m.SnapshotVersion != 1 || m.ReportVersion != 1 || m.RedactionPolicy != Policy { + return ErrVersion + } + if m.Tool.Name != "envdoctor" || m.Tool.Version == "" || m.Tool.Version != "dev" && !numericVersion.MatchString(m.Tool.Version) || m.CapturedAt.IsZero() || m.CaptureExitCode < 0 || m.CaptureExitCode > 3 { + return ErrInvalid + } + if len(m.Omissions) > 256 || len(m.Members) > MaxEntries-1 { + return ErrBounds + } + seenOmissions := map[report.Omission]bool{} + for _, o := range m.Omissions { + if !allowed(o.Field, omissionFields...) || !allowed(o.Reason, "identifying_values", "raw_error", "unsupported_value", "unavailable_evidence") || seenOmissions[o] { + return ErrInvalid + } + seenOmissions[o] = true + } + if len(m.Members) != len(all)-1 { + return ErrInvalid + } + seen := map[string]bool{} + for _, member := range m.Members { + body, ok := all[member.Name] + if !ok || member.Name == "manifest.json" || seen[member.Name] || member.Size < 0 || member.Size != len(body) { + return ErrIntegrity + } + seen[member.Name] = true + digest := sha256.Sum256(body) + if member.SHA256 != hex.EncodeToString(digest[:]) { + return ErrIntegrity + } + } + return nil +} + +func makeVersions(s SharingSnapshot, tool report.Tool) Versions { + v := Versions{SchemaVersion: 1, Tool: tool, Runtimes: []RuntimeVersion{}} + seen := map[RuntimeVersion]bool{} + for _, r := range s.Runtimes { + item := RuntimeVersion{Name: r.Name, Version: r.Version} + if r.Version != "" && !seen[item] { + v.Runtimes = append(v.Runtimes, item) + seen[item] = true + } + } + if s.Git != nil { + v.Git = s.Git.Version + } + if s.Docker != nil { + v.Docker = s.Docker.CLIVersion + } + return v +} + +func sourceFor(m Manifest) report.Source { + return report.Source{Kind: "bundle", CaptureTool: m.Tool, CapturedAt: m.CapturedAt, RedactionPolicy: m.RedactionPolicy, CaptureExitCode: m.CaptureExitCode, Omissions: m.Omissions} +} + +func validateReference(doc report.Document, s SharingSnapshot, m Manifest, v Versions, diags *Diagnostics) error { + if doc.SchemaVersion != 1 || v.SchemaVersion != 1 { + return ErrVersion + } + expectedSource := sourceFor(m) + if doc.Source == nil || !reflect.DeepEqual(*doc.Source, expectedSource) || doc.Tool != m.Tool || !doc.GeneratedAt.Equal(m.CapturedAt) || !s.CollectedAt.Equal(m.CapturedAt) || !reflect.DeepEqual(doc.Snapshot, engineSnapshot(s)) || !reflect.DeepEqual(v, makeVersions(s, m.Tool)) { + return ErrInvalid + } + if doc.ExitCode < 0 || doc.ExitCode > 3 || doc.Rules < 0 || doc.Rules > 4096 { + return ErrInvalid + } + summary := report.Summary{Total: len(doc.Findings)} + for _, f := range doc.Findings { + if err := f.Validate(); err != nil { + return ErrInvalid + } + switch f.Severity { + case diagnostic.SeverityInfo: + summary.Info++ + case diagnostic.SeverityWarning: + summary.Warning++ + case diagnostic.SeverityError: + summary.Error++ + case diagnostic.SeverityCritical: + summary.Critical++ + } + } + if summary != doc.Summary { + return ErrInvalid + } + failed := map[string]bool{} + for _, f := range s.Errors { + failed[f.Collector] = true + } + seen := map[string]bool{} + for _, c := range doc.Collectors { + if !knownCollector(c.Name) || seen[c.Name] || c.DurationMs < 0 || c.DurationMs > maxDurationMs || c.Error != "" && c.Error != unavailableNotice || (c.Error != "") != failed[c.Name] { + return ErrInvalid + } + seen[c.Name] = true + } + for name := range failed { + if !seen[name] { + return ErrInvalid + } + } + if diags != nil { + if diags.SchemaVersion != 1 { + return ErrVersion + } + if len(diags.Collectors) > 32 { + return ErrBounds + } + seen = map[string]bool{} + for _, c := range diags.Collectors { + if !knownCollector(c.Collector) || seen[c.Collector] || c.DurationMs < 0 || c.DurationMs > maxDurationMs || !allowed(c.Status, "available", "unavailable") || (c.Status == "unavailable") != failed[c.Collector] { + return ErrInvalid + } + seen[c.Collector] = true + } + for name := range failed { + if !seen[name] { + return ErrInvalid + } + } + } + return nil +} diff --git a/internal/cli/bundle.go b/internal/cli/bundle.go new file mode 100644 index 0000000..5ce32aa --- /dev/null +++ b/internal/cli/bundle.go @@ -0,0 +1,61 @@ +package cli + +import ( + "fmt" + "io" + + "github.com/spf13/cobra" + + "github.com/shellghostt/envdoctor/internal/bundle" + "github.com/shellghostt/envdoctor/internal/config" +) + +func (a *App) newBundleCommand() *cobra.Command { + opts := config.Options{} + output := "envdoctor-bundle.zip" + includeLogs := false + cmd := &cobra.Command{ + Use: "bundle", Short: "Publish a redacted sharing bundle of the complete builtin diagnosis", + Long: "Capture approved diagnostic facts and publish a bounded ZIP atomically.\n" + + "Git identity becomes presence facts; paths and hosts become capture-local aliases.\n" + + "--include-logs includes only structured collector statuses/timings, never raw logs.\n" + + "Publication success exits 0; the capture's diagnosis exit is reference metadata.", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + if err := opts.Validate(); err != nil { + return err + } + if output == "" { + return fmt.Errorf("--output requires a file") + } + doc, err := a.captureDocument(cmd.Context(), opts, false) + if err != nil { + return toolFailure{err} + } + data, err := bundle.Build(cmd.Context(), doc, bundle.Options{IncludeLogs: includeLogs}) + if err != nil { + return toolFailure{err} + } + // Report bounded progress before committing the destination. A broken + // status stream must not turn a successful rename into a failed command + // that has already replaced the user's previous capture. + status := fmt.Sprintf("Writing diagnostic bundle (%d bytes); original diagnosis exit %d.\n", len(data), doc.ExitCode) + n, err := io.WriteString(a.Stdout, status) + if err == nil && n != len(status) { + err = io.ErrShortWrite + } + if err != nil { + return toolFailure{err} + } + if err := bundle.Publish(cmd.Context(), output, data); err != nil { + return toolFailure{err} + } + a.exitCode = ExitOK + return nil + }, + } + cmd.Flags().StringVarP(&output, "output", "o", output, "destination ZIP file") + cmd.Flags().BoolVar(&includeLogs, "include-logs", false, "include only allowlisted structured collector statuses/timings") + bindCaptureFlags(cmd, &opts) + return cmd +} diff --git a/internal/cli/cli.go b/internal/cli/cli.go index 072bfd5..9329d7d 100644 --- a/internal/cli/cli.go +++ b/internal/cli/cli.go @@ -6,16 +6,21 @@ package cli import ( + "context" "errors" "fmt" "io" "os" + "strings" "time" "github.com/spf13/cobra" + "golang.org/x/term" + "github.com/shellghostt/envdoctor/internal/bundle" "github.com/shellghostt/envdoctor/internal/collector" "github.com/shellghostt/envdoctor/internal/diagnostic" + "github.com/shellghostt/envdoctor/internal/report" ) // Process exit codes. PLAN section 8 is the contract. @@ -29,16 +34,22 @@ const ( // App is one invocation of the binary. type App struct { - Version string - Stdout io.Writer - Stderr io.Writer - Getenv func(string) string - Now func() time.Time - Collectors []collector.Collector - HomeDir func() (string, error) - Engine *diagnostic.Engine - - exitCode int + Version string + Stdin io.Reader + Stdout io.Writer + Stderr io.Writer + Getenv func(string) string + LookupEnv func(string) (string, bool) + Context context.Context + Terminals func() report.TerminalState + Interactive func(context.Context, io.Reader, io.Writer, report.Document) error + Now func() time.Time + Collectors []collector.Collector + HomeDir func() (string, error) + Engine *diagnostic.Engine + + exitCode int + bundleMode bool } // toolFailure marks an error as a failure of the tool itself rather than of the @@ -52,15 +63,36 @@ func (e toolFailure) Unwrap() error { return e.err } // which keeps it usable from tests. func Main(args []string, app App) int { app.applyDefaults() + for _, arg := range args[1:] { + if arg == "bundle" || arg == "--from-bundle" || strings.HasPrefix(arg, "--from-bundle=") { + app.bundleMode = true + } + } root := app.newRoot() root.SetArgs(args[1:]) - if err := root.Execute(); err != nil { - home, _ := app.HomeDir() - _, _ = fmt.Fprintf(app.Stderr, "error: %s\n", collector.RedactText(err.Error(), home)) + if err := root.ExecuteContext(app.Context); err != nil { var failure toolFailure - if errors.As(err, &failure) { + failed := errors.As(err, &failure) + message := err.Error() + if app.bundleMode { + message = "invalid bundle command options" + if failed { + message = "diagnostic bundle operation failed" + for _, reason := range []error{bundle.ErrInvalid, bundle.ErrBounds, bundle.ErrVersion, bundle.ErrIntegrity, bundle.ErrEvidence, bundle.ErrRead, bundle.ErrWrite, context.Canceled, context.DeadlineExceeded} { + if errors.Is(err, reason) { + message = reason.Error() + break + } + } + } + } else { + home, _ := app.HomeDir() + message = collector.RedactText(message, home) + } + _, _ = fmt.Fprintf(app.Stderr, "error: %s\n", report.VisibleText(message)) + if failed { return ExitToolFailure } _, _ = fmt.Fprintln(app.Stderr, "Run 'envdoctor --help' for usage.") @@ -70,6 +102,9 @@ func Main(args []string, app App) int { } func (a *App) applyDefaults() { + if a.Context == nil { + a.Context = context.Background() + } if a.Stdout == nil { a.Stdout = io.Discard } @@ -79,6 +114,12 @@ func (a *App) applyDefaults() { if a.Getenv == nil { a.Getenv = os.Getenv } + if a.LookupEnv == nil { + a.LookupEnv = os.LookupEnv + } + if a.Interactive == nil { + a.Interactive = report.WriteInteractive + } if a.Now == nil { a.Now = time.Now } @@ -121,14 +162,29 @@ func (a *App) newRoot() *cobra.Command { } root.SetOut(a.Stdout) root.SetErr(a.Stderr) + root.SetIn(a.Stdin) root.AddCommand(a.newDiagnoseCommand()) + root.AddCommand(a.newBundleCommand()) root.AddCommand(a.newVersionCommand()) root.AddCommand(a.newExplainCommand()) root.AddCommand(a.newRulesCommand()) return root } +func terminalStream(stream any) bool { + file, ok := stream.(interface{ Fd() uintptr }) + return ok && term.IsTerminal(int(file.Fd())) +} + +func (a *App) terminalState() report.TerminalState { + if a.Terminals != nil { + return a.Terminals() + } + _, noColor := a.LookupEnv("NO_COLOR") + return report.TerminalState{Input: terminalStream(a.Stdin), Output: terminalStream(a.Stdout), Error: terminalStream(a.Stderr), Term: a.Getenv("TERM"), NoColor: noColor} +} + func (a *App) newVersionCommand() *cobra.Command { return &cobra.Command{ Use: "version", diff --git a/internal/cli/diagnose.go b/internal/cli/diagnose.go index 65bb575..938ad13 100644 --- a/internal/cli/diagnose.go +++ b/internal/cli/diagnose.go @@ -7,6 +7,7 @@ import ( "github.com/spf13/cobra" + "github.com/shellghostt/envdoctor/internal/bundle" "github.com/shellghostt/envdoctor/internal/collector" "github.com/shellghostt/envdoctor/internal/config" "github.com/shellghostt/envdoctor/internal/diagnostic" @@ -15,56 +16,104 @@ import ( func (a *App) newDiagnoseCommand() *cobra.Command { opts := config.Options{} - + format := report.FormatOptions{} cmd := &cobra.Command{ - Use: "diagnose", - Short: "Collect environment facts and report findings", - Long: "Collects facts about this machine and reports findings from the rules in this build.\n" + - "With --json, writes exactly one JSON document to stdout and nothing else.", + Use: "diagnose", Short: "Collect environment facts and report findings", + Long: "Report environment facts and manual advice as text, Markdown or JSON.\n" + + "Capable terminals use a scrollable viewer by default; --plain forces text.\n" + + "--from-bundle evaluates captured facts offline without inspecting this machine.", Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { + format.JSON, format.Explicit = opts.JSON, cmd.Flags().Changed("format") if err := opts.Validate(); err != nil { return err } + if cmd.Flags().Changed("from-bundle") { + if opts.FromBundle == "" { + return fmt.Errorf("--from-bundle requires a file") + } + for _, flag := range []string{"fixture-dir", "port", "probe-network", "package-manager"} { + if cmd.Flags().Changed(flag) { + return fmt.Errorf("--from-bundle conflicts with live capture flags and --fixture-dir") + } + } + } + // Validate formats before terminal lookup or evidence I/O. + mode, err := report.SelectMode(format, report.TerminalState{}) + if err != nil { + return err + } + if !format.JSON && !format.Explicit && !format.Plain { + mode, err = report.SelectMode(format, a.terminalState()) + if err != nil { + return err + } + } if opts.Rule != "" && !a.Engine.HasRule(opts.Rule) { return fmt.Errorf("rule %s is not registered in this build", opts.Rule) } - document, err := a.diagnose(cmd.Context(), opts) if err != nil { return toolFailure{err} } - - if opts.JSON { - if err := report.WriteJSON(a.Stdout, document); err != nil { - return toolFailure{err} - } - } else if err := report.WriteText(a.Stdout, document); err != nil { + switch mode { + case report.JSON: + err = report.WriteJSON(a.Stdout, document) + case report.Markdown: + err = report.WriteMarkdown(a.Stdout, document) + case report.Interactive: + err = a.Interactive(cmd.Context(), a.Stdin, a.Stdout, document) + default: + err = report.WriteText(a.Stdout, document) + } + if err != nil { return toolFailure{err} } - if opts.Verbose { - writeTimings(a, document) + if err := writeTimings(a, document); err != nil { + return toolFailure{err} + } } - a.exitCode = document.ExitCode return nil }, } - cmd.Flags().BoolVar(&opts.JSON, "json", false, "write one JSON document to stdout") + cmd.Flags().StringVar(&format.Format, "format", "", "output format: text, markdown or json") + cmd.Flags().BoolVar(&format.Plain, "plain", false, "force plain text without the terminal viewer") cmd.Flags().BoolVar(&opts.Verbose, "verbose", false, "write collector timings to stderr") cmd.Flags().StringVar(&opts.Component, "component", "", "only evaluate rules for this component") cmd.Flags().StringVar(&opts.Rule, "rule", "", "only evaluate this rule id (ENV001)") + cmd.Flags().StringVar(&opts.FromBundle, "from-bundle", "", "evaluate a sharing bundle offline; run no collectors") + bindCaptureFlags(cmd, &opts) + return cmd +} + +func bindCaptureFlags(cmd *cobra.Command, opts *config.Options) { cmd.Flags().IntSliceVar(&opts.Ports, "port", nil, "TCP ports your application needs (repeatable or comma separated)") cmd.Flags().StringVar(&opts.FixtureDir, "fixture-dir", "", "read snapshot.json in this directory; do not inspect this machine") cmd.Flags().BoolVar(&opts.ProbeNetwork, "probe-network", false, "probe configured proxy endpoints with a one-second total deadline") cmd.Flags().StringVar(&opts.PackageManager, "package-manager", "", "explicit project runner: npm, pnpm, yarn or bun, optionally @major.minor.patch") - - return cmd } func (a *App) diagnose(ctx context.Context, opts config.Options) (report.Document, error) { + if opts.FromBundle != "" { + capture, err := bundle.Load(ctx, opts.FromBundle) + if err != nil { + return report.Document{}, err + } + findings, err := a.Engine.Evaluate(capture.Snapshot, diagnostic.Filter{Component: opts.Component, RuleID: opts.Rule}) + if err != nil { + return report.Document{}, fmt.Errorf("evaluate rules: %w", err) + } + doc := report.NewDocument(a.Version, a.Now(), capture.Snapshot, findings, nil, len(a.Engine.Rules())) + doc.Source = &capture.Source + return doc, nil + } + return a.captureDocument(ctx, opts, true) +} + +func (a *App) captureDocument(ctx context.Context, opts config.Options, redact bool) (report.Document, error) { var snapshot collector.Snapshot var timings []collector.Timing if opts.FixtureDir != "" { @@ -95,32 +144,36 @@ func (a *App) diagnose(ctx context.Context, opts config.Options) (report.Documen snapshot, timings = runner.Run(ctx) snapshot.RequestedPorts = opts.Ports } - - home, _ := a.HomeDir() - snapshot.Redact(home) - for i := range timings { - if timings[i].Err != nil { - timings[i].Err = errors.New(collector.RedactText(timings[i].Err.Error(), home)) + if err := ctx.Err(); err != nil { + return report.Document{}, err + } + // Sharing export must see exact facts before home redaction can collapse + // distinct paths. Ordinary reports retain their existing M3 redaction. + if redact { + home, _ := a.HomeDir() + snapshot.Redact(home) + for i := range timings { + if timings[i].Err != nil { + timings[i].Err = errors.New(collector.RedactText(timings[i].Err.Error(), home)) + } } } - - findings, err := a.Engine.Evaluate(snapshot, diagnostic.Filter{ - Component: opts.Component, - RuleID: opts.Rule, - }) + findings, err := a.Engine.Evaluate(snapshot, diagnostic.Filter{Component: opts.Component, RuleID: opts.Rule}) if err != nil { return report.Document{}, fmt.Errorf("evaluate rules: %w", err) } - return report.NewDocument(a.Version, a.Now(), snapshot, findings, timings, len(a.Engine.Rules())), nil } -func writeTimings(a *App, document report.Document) { +func writeTimings(a *App, document report.Document) error { for _, c := range document.Collectors { status := "ok" if c.Error != "" { status = c.Error } - _, _ = fmt.Fprintf(a.Stderr, "collector %-10s %5dms %s\n", c.Name, c.DurationMs, status) + if _, err := fmt.Fprintf(a.Stderr, "collector %-10s %5dms %s\n", report.VisibleText(c.Name), c.DurationMs, report.VisibleText(status)); err != nil { + return fmt.Errorf("write collector timings: %w", err) + } } + return nil } diff --git a/internal/cli/m4_test.go b/internal/cli/m4_test.go new file mode 100644 index 0000000..33ae484 --- /dev/null +++ b/internal/cli/m4_test.go @@ -0,0 +1,330 @@ +package cli_test + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/shellghostt/envdoctor/internal/bundle" + "github.com/shellghostt/envdoctor/internal/cli" + "github.com/shellghostt/envdoctor/internal/collector" + "github.com/shellghostt/envdoctor/internal/diagnostic" + "github.com/shellghostt/envdoctor/internal/report" +) + +type panicCollector struct{} + +func (panicCollector) Name() string { return "path" } +func (panicCollector) Collect(context.Context) (collector.Part, error) { + panic("offline diagnosis ran a collector") +} + +func TestM4CLIFormatAndTerminalMatrix(t *testing.T) { + capable := report.TerminalState{Input: true, Output: true, Error: true, Term: "xterm-256color"} + for _, tc := range []struct { + name string + flags []string + term report.TerminalState + interactive bool + kind string + }{ + {"default-viewer", nil, capable, true, "text"}, + {"no-tty", nil, report.TerminalState{}, false, "text"}, + {"stdout-redirect", nil, report.TerminalState{Input: true, Error: true}, false, "text"}, + {"stderr-redirect", nil, report.TerminalState{Input: true, Output: true}, false, "text"}, + {"stdin-redirect", nil, report.TerminalState{Output: true, Error: true}, false, "text"}, + {"dumb", nil, report.TerminalState{Input: true, Output: true, Error: true, Term: "dumb"}, false, "text"}, + {"empty-no-color", nil, report.TerminalState{Input: true, Output: true, Error: true, NoColor: true}, false, "text"}, + {"windows-unset-term", nil, report.TerminalState{Input: true, Output: true, Error: true}, true, "text"}, + {"plain", []string{"--plain"}, capable, false, "text"}, + {"text", []string{"--format", "text"}, capable, false, "text"}, + {"json", []string{"--format", "json"}, capable, false, "json"}, + {"json-alias", []string{"--json"}, capable, false, "json"}, + {"compatible-json", []string{"--json", "--format", "json"}, capable, false, "json"}, + {"markdown", []string{"--format", "markdown"}, capable, false, "markdown"}, + } { + t.Run(tc.name, func(t *testing.T) { + var out, errOut bytes.Buffer + app := newApp(&out, &errOut) + app.Engine = diagnostic.NewEngine(warnRule{severity: diagnostic.SeverityWarning}) + app.Terminals = func() report.TerminalState { return tc.term } + called := false + app.Interactive = func(_ context.Context, _ io.Reader, w io.Writer, d report.Document) error { + called = true + return report.WriteText(w, d) + } + code := cli.Main(append([]string{"envdoctor", "diagnose", "--verbose"}, tc.flags...), app) + if code != 1 || called != tc.interactive { + t.Fatalf("exit=%d viewer=%v stderr=%s", code, called, errOut.String()) + } + if strings.Contains(out.String(), "\x1b") || strings.Contains(out.String(), "collector platform") { + t.Fatal("stdout contaminated") + } + if !strings.Contains(errOut.String(), "collector platform") { + t.Fatal("verbose diagnostics missing") + } + switch tc.kind { + case "json": + validateAgainstSchema(t, compileDiagnoseSchema(t), out.Bytes()) + case "markdown": + if !strings.HasPrefix(out.String(), "# EnvDoctor diagnosis\n") || !strings.Contains(out.String(), "ENV003") { + t.Fatal("Markdown report missing") + } + default: + if !strings.Contains(out.String(), "Broken PATH entry") { + t.Fatal("plain report missing") + } + } + }) + } +} + +func TestM4CLIInvalidFormatsBeforeCollection(t *testing.T) { + for _, flags := range [][]string{{"--format", "html"}, {"--format", ""}, {"--json", "--format", "text"}, {"--json", "--format", "markdown"}, {"--plain", "--json"}, {"--plain", "--format", "markdown"}} { + var out, errOut bytes.Buffer + app := newApp(&out, &errOut) + app.Collectors = []collector.Collector{panicCollector{}} + app.Terminals = func() report.TerminalState { panic("format conflict inspected a terminal") } + if code := cli.Main(append([]string{"envdoctor", "diagnose"}, flags...), app); code != 4 || out.Len() != 0 { + t.Fatalf("exit=%d stdout=%s", code, out.String()) + } + } +} + +func TestM4CLIInteractiveFailurePreservesFallbackAndExit(t *testing.T) { + var out, errOut bytes.Buffer + app := newApp(&out, &errOut) + app.Terminals = func() report.TerminalState { return report.TerminalState{Input: true, Output: true, Error: true} } + app.Interactive = func(_ context.Context, _ io.Reader, w io.Writer, d report.Document) error { + if err := report.WriteText(w, d); err != nil { + return err + } + return context.Canceled + } + if code := cli.Main([]string{"envdoctor", "diagnose"}, app); code != 3 || !strings.Contains(out.String(), "environment diagnosis") { + t.Fatalf("exit=%d output=%s", code, out.String()) + } +} + +func offlineSnapshot() collector.Snapshot { + name, email := "SyntheticOfflineUser", "synthetic@private.invalid" + return collector.Snapshot{SchemaVersion: 1, CollectedAt: fixedNow, + Platform: &collector.Platform{OS: "windows", Version: "11", Arch: "amd64"}, Shell: &collector.Shell{Name: "powershell"}, + Path: &collector.PathInfo{Entries: []collector.PathEntry{{Raw: `C:\Users\SyntheticOfflineUser\gone`, Position: 0}}}, + Git: &collector.Git{Version: "2.53.0", UserName: &name, UserEmail: &email, IdentityChecked: true}, + Dependencies: &collector.Dependencies{ProjectRoot: `C:\Users\SyntheticOfflineUser\project`}, + } +} + +func bundleFile(t *testing.T, snapshot collector.Snapshot) string { + t.Helper() + findings, err := diagnostic.DefaultEngine().Evaluate(snapshot, diagnostic.Filter{}) + if err != nil { + t.Fatal(err) + } + doc := report.NewDocument("0.1.0", fixedNow, snapshot, findings, nil, 12) + data, err := bundle.Build(context.Background(), doc, bundle.Options{IncludeLogs: true}) + if err != nil { + t.Fatal(err) + } + path := filepath.Join(t.TempDir(), "capture.zip") + if err := os.WriteFile(path, data, 0600); err != nil { + t.Fatal(err) + } + return path +} + +func offlineApp(out, errOut *bytes.Buffer) cli.App { + app := newApp(out, errOut) + app.Version = "0.2.0" + app.Engine = diagnostic.DefaultEngine() + app.Collectors = []collector.Collector{panicCollector{}} + app.HomeDir = func() (string, error) { panic("offline diagnosis inspected the home directory") } + app.Getenv = func(string) string { panic("explicit offline format read the environment") } + app.LookupEnv = func(string) (string, bool) { panic("explicit offline format read the environment") } + return app +} + +func TestM4CLIOfflineEvidenceAndProvenance(t *testing.T) { + path := bundleFile(t, offlineSnapshot()) + for _, flags := range [][]string{{"--json"}, {"--format", "markdown"}, {"--plain"}, {"--format", "text"}, {"--json", "--rule", "ENV003", "--verbose"}, {"--json", "--component", "docker"}} { + var out, errOut bytes.Buffer + code := cli.Main(append([]string{"envdoctor", "diagnose", "--from-bundle", path}, flags...), offlineApp(&out, &errOut)) + want := 1 + if strings.Contains(strings.Join(flags, " "), "--component docker") { + want = 0 + } + if code != want { + t.Fatalf("exit=%d stderr=%s", code, errOut.String()) + } + if strings.Contains(out.String(), "SyntheticOfflineUser") || strings.Contains(out.String(), "synthetic@private.invalid") { + t.Fatal("original identity leaked") + } + if flags[0] == "--json" { + var doc report.Document + if err := json.Unmarshal(out.Bytes(), &doc); err != nil { + t.Fatal(err) + } + if doc.Source == nil || doc.Source.CaptureTool.Version != "0.1.0" || doc.Tool.Version != "0.2.0" || !doc.Snapshot.CollectedAt.Equal(fixedNow) { + t.Fatal("capture/evaluator provenance missing") + } + validateAgainstSchema(t, compileDiagnoseSchema(t), out.Bytes()) + } + } +} + +func TestM4CLIOfflineAllExitCodes(t *testing.T) { + for code := 0; code <= 3; code++ { + s := offlineSnapshot() + s.Path.Entries[0].Exists = true + s.Path.Entries[0].IsDir = true + switch code { + case 1: + s.Path.Entries[0].Exists = false + s.Path.Entries[0].IsDir = false + case 2: + s.Docker = &collector.Docker{Installed: true, CLIVersion: "29.9.2", ProbeStatus: "unavailable"} + case 3: + s.Errors = []collector.CollectorError{{Collector: "runtimes", Message: "secret failure"}} + } + var out, errOut bytes.Buffer + if got := cli.Main([]string{"envdoctor", "diagnose", "--from-bundle", bundleFile(t, s), "--json"}, offlineApp(&out, &errOut)); got != code { + t.Fatalf("got=%d want=%d stderr=%s", got, code, errOut.String()) + } + } +} + +func TestM4CLIConflictsAndReadFailuresAreOffline(t *testing.T) { + missing := filepath.Join(t.TempDir(), "SECRET-PATH-not-present.zip") + for _, extra := range [][]string{{"--fixture-dir", "SECRET-PATH"}, {"--port", "3000"}, {"--probe-network"}, {"--probe-network=false"}, {"--package-manager", "npm"}, {"--fixture-dir="}} { + var out, errOut bytes.Buffer + code := cli.Main(append([]string{"envdoctor", "diagnose", "--from-bundle", missing, "--json"}, extra...), offlineApp(&out, &errOut)) + if code != 4 || out.Len() != 0 || strings.Contains(errOut.String(), "SECRET-PATH") { + t.Fatalf("conflict exit=%d stderr=%s", code, errOut.String()) + } + } + for _, path := range []string{missing, filepath.Join(t.TempDir(), "SECRET-PATH-invalid.zip")} { + if path != missing { + if err := os.WriteFile(path, []byte("SECRET-CAPTURED-ERROR"), 0600); err != nil { + t.Fatal(err) + } + } + var out, errOut bytes.Buffer + if code := cli.Main([]string{"envdoctor", "diagnose", "--from-bundle", path, "--json"}, offlineApp(&out, &errOut)); code != 3 || out.Len() != 0 || strings.Contains(errOut.String(), "SECRET-") { + t.Fatalf("invalid input exit=%d stderr=%s", code, errOut.String()) + } + } +} + +func TestM4CLIBundleWriterSuccessAndFailures(t *testing.T) { + dir := t.TempDir() + fixture := filepath.Join(dir, "fixture") + if err := os.Mkdir(fixture, 0700); err != nil { + t.Fatal(err) + } + raw, err := json.Marshal(offlineSnapshot()) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(fixture, "snapshot.json"), raw, 0600); err != nil { + t.Fatal(err) + } + destination := filepath.Join(dir, "SECRET-OUTPUT.zip") + var out, errOut bytes.Buffer + app := offlineApp(&out, &errOut) + code := cli.Main([]string{"envdoctor", "bundle", "--fixture-dir", fixture, "-o", destination, "--include-logs"}, app) + if code != 0 || errOut.Len() != 0 || !strings.Contains(out.String(), "original diagnosis exit 1") || strings.Contains(out.String(), "SECRET-") { + t.Fatalf("exit=%d stdout=%s stderr=%s", code, out.String(), errOut.String()) + } + if _, err := bundle.Load(context.Background(), destination); err != nil { + t.Fatal(err) + } + for _, flags := range [][]string{{"--output", ""}, {"--json"}, {"--rule", "ENV003"}, {"--from-bundle", destination}, {"--fixture-dir", fixture, "--probe-network"}} { + out.Reset() + errOut.Reset() + if code := cli.Main(append([]string{"envdoctor", "bundle"}, flags...), offlineApp(&out, &errOut)); code != 4 { + t.Fatalf("usage exit=%d stderr=%s", code, errOut.String()) + } + } + out.Reset() + errOut.Reset() + if code := cli.Main([]string{"envdoctor", "bundle", "--fixture-dir", fixture, "--output", dir}, offlineApp(&out, &errOut)); code != 3 { + t.Fatalf("I/O exit=%d stderr=%s", code, errOut.String()) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + out.Reset() + errOut.Reset() + app = offlineApp(&out, &errOut) + app.Context = ctx + if code := cli.Main([]string{"envdoctor", "bundle", "--fixture-dir", fixture, "--output", destination}, app); code != 3 { + t.Fatalf("cancel exit=%d", code) + } +} + +type m4WriteFailure struct{} + +func (m4WriteFailure) Write([]byte) (int, error) { return 0, errors.New("SECRET-WRITER-ERROR") } + +type m4WriteShort struct{} + +func (m4WriteShort) Write(p []byte) (int, error) { return max(0, len(p)-1), nil } + +func TestM4CLIBundleStatusFailurePreservesDestination(t *testing.T) { + for _, writer := range []struct { + name string + output io.Writer + }{{"failure", m4WriteFailure{}}, {"short-write", m4WriteShort{}}} { + t.Run(writer.name, func(t *testing.T) { + dir := t.TempDir() + fixture := filepath.Join(dir, "fixture") + if err := os.Mkdir(fixture, 0700); err != nil { + t.Fatal(err) + } + raw, err := json.Marshal(offlineSnapshot()) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(fixture, "snapshot.json"), raw, 0600); err != nil { + t.Fatal(err) + } + destination := filepath.Join(dir, "previous.zip") + previous := []byte("previous capture must survive a failed status write") + if err := os.WriteFile(destination, previous, 0600); err != nil { + t.Fatal(err) + } + var out, errOut bytes.Buffer + app := offlineApp(&out, &errOut) + app.Stdout = writer.output + if code := cli.Main([]string{"envdoctor", "bundle", "--fixture-dir", fixture, "--output", destination}, app); code != 3 || strings.Contains(errOut.String(), "SECRET-") { + t.Fatalf("exit=%d stderr=%s", code, errOut.String()) + } + got, err := os.ReadFile(destination) + if err != nil || !bytes.Equal(got, previous) { + t.Fatalf("previous destination changed: %q, %v", got, err) + } + entries, err := os.ReadDir(dir) + if err != nil || len(entries) != 2 { + t.Fatalf("owned staging file leaked: %v, %v", entries, err) + } + }) + } +} + +func TestM4CLIStructuredOutputErrors(t *testing.T) { + path := bundleFile(t, offlineSnapshot()) + for _, format := range []string{"text", "markdown", "json"} { + var out, errOut bytes.Buffer + app := offlineApp(&out, &errOut) + app.Stdout = m4WriteFailure{} + if code := cli.Main([]string{"envdoctor", "diagnose", "--from-bundle", path, "--format", format}, app); code != 3 || strings.Contains(errOut.String(), "SECRET-") { + t.Fatalf("exit=%d stderr=%s", code, errOut.String()) + } + } +} diff --git a/internal/config/config.go b/internal/config/config.go index 3a10fb4..edac371 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -35,6 +35,7 @@ type Options struct { Rule string Ports []int FixtureDir string + FromBundle string ProbeNetwork bool PackageManager string } @@ -43,6 +44,9 @@ type Options struct { // check whether the rule exists: that needs the rule registry, which the // caller owns. func (o Options) Validate() error { + if o.FromBundle != "" && (o.FixtureDir != "" || len(o.Ports) > 0 || o.ProbeNetwork || o.PackageManager != "") { + return fmt.Errorf("--from-bundle conflicts with live capture flags and --fixture-dir") + } if o.ProbeNetwork && o.FixtureDir != "" { return fmt.Errorf("--probe-network cannot be used with --fixture-dir") } diff --git a/internal/report/document.go b/internal/report/document.go index 37c0984..2d95735 100644 --- a/internal/report/document.go +++ b/internal/report/document.go @@ -21,6 +21,22 @@ type Document struct { ExitCode int `json:"exitCode"` Rules int `json:"rules"` Collectors []Collector `json:"collectors"` + Source *Source `json:"source,omitempty"` +} + +// Source is present only for bundle evidence, never for ordinary M3 output. +type Source struct { + Kind string `json:"kind"` + CaptureTool Tool `json:"captureTool"` + CapturedAt time.Time `json:"capturedAt"` + RedactionPolicy string `json:"redactionPolicy"` + CaptureExitCode int `json:"captureExitCode"` + Omissions []Omission `json:"omissions"` +} + +type Omission struct { + Field string `json:"field"` + Reason string `json:"reason"` } // Tool identifies the binary that produced the document. diff --git a/internal/report/format.go b/internal/report/format.go new file mode 100644 index 0000000..642cd87 --- /dev/null +++ b/internal/report/format.go @@ -0,0 +1,70 @@ +package report + +import ( + "fmt" + "strings" + "unicode" +) + +type Mode string + +const ( + Text Mode = "text" + JSON Mode = "json" + Markdown Mode = "markdown" + Interactive Mode = "interactive" +) + +type FormatOptions struct { + Format string + Explicit bool + JSON bool + Plain bool +} + +// TerminalState is supplied by the CLI. Selection itself never inspects a host. +type TerminalState struct { + Input, Output, Error bool + Term string + NoColor bool +} + +func SelectMode(o FormatOptions, terminal TerminalState) (Mode, error) { + if o.Explicit && o.Format != string(Text) && o.Format != string(JSON) && o.Format != string(Markdown) { + return "", fmt.Errorf("--format must be text, markdown or json") + } + if o.JSON && o.Explicit && o.Format != string(JSON) { + return "", fmt.Errorf("--json conflicts with --format") + } + if o.Plain && (o.JSON || o.Explicit && o.Format != string(Text)) { + return "", fmt.Errorf("--plain requires text output") + } + if o.JSON { + return JSON, nil + } + if o.Explicit { + return Mode(o.Format), nil + } + if o.Plain || terminal.NoColor || strings.EqualFold(strings.TrimSpace(terminal.Term), "dumb") || !terminal.Input || !terminal.Output || !terminal.Error { + return Text, nil + } + return Interactive, nil +} + +// VisibleText preserves ordinary report bytes and makes terminal controls data. +func VisibleText(s string) string { + if !strings.ContainsFunc(s, func(r rune) bool { return r != '\n' && r != '\t' && displayControl(r) }) { + return s + } + var b strings.Builder + for _, r := range s { + if r != '\n' && r != '\t' && displayControl(r) { + fmt.Fprintf(&b, "\\u%04X", r) + } else { + b.WriteRune(r) + } + } + return b.String() +} + +func displayControl(r rune) bool { return unicode.IsControl(r) || unicode.Is(unicode.Cf, r) } diff --git a/internal/report/interactive.go b/internal/report/interactive.go new file mode 100644 index 0000000..94cf916 --- /dev/null +++ b/internal/report/interactive.go @@ -0,0 +1,230 @@ +package report + +import ( + "bytes" + "context" + "errors" + "fmt" + "io" + "strings" + "sync" + "time" + + tea "github.com/charmbracelet/bubbletea" + "github.com/charmbracelet/x/ansi" + "golang.org/x/term" +) + +type viewer struct { + text string + lines []string + width int + height int + top int + interrupted bool +} + +func newViewer(text string) *viewer { + v := &viewer{text: strings.ReplaceAll(text, "\t", " "), width: 80, height: 24} + v.resize(80, 24) + return v +} + +func (v *viewer) resize(width, height int) { + v.width, v.height = max(1, min(width, 512)), max(1, min(height, 256)) + v.lines = strings.Split(ansi.Hardwrap(v.text, v.width, false), "\n") + v.top = min(v.top, max(0, len(v.lines)-max(1, v.height-2))) +} + +func (*viewer) Init() tea.Cmd { return nil } + +func (v *viewer) Update(msg tea.Msg) (tea.Model, tea.Cmd) { + switch msg := msg.(type) { + case tea.WindowSizeMsg: + if max(1, min(msg.Width, 512)) != v.width || max(1, min(msg.Height, 256)) != v.height { + v.resize(msg.Width, msg.Height) + } + case tea.KeyMsg: + switch msg.String() { + case "q", "esc": + return v, tea.Quit + case "ctrl+c": + v.interrupted = true + return v, tea.Quit + case "up", "k": + v.top-- + case "down", "j": + v.top++ + case "pgup": + v.top -= max(1, v.height-2) + case "pgdown", " ": + v.top += max(1, v.height-2) + case "home", "g": + v.top = 0 + case "end", "G": + v.top = len(v.lines) + } + v.top = max(0, min(v.top, max(0, len(v.lines)-max(1, v.height-2)))) + } + return v, nil +} + +func (v *viewer) View() string { + header := ansi.Truncate("EnvDoctor | captured facts and manual advice", v.width, "") + if v.height == 1 { + return header + } + footer := ansi.Truncate(fmt.Sprintf("↑/↓ scroll · pgup/down · q exit | %d/%d", v.top+1, len(v.lines)), v.width, "") + if v.height == 2 { + return header + "\n" + footer + } + end := min(len(v.lines), v.top+v.height-2) + lines := make([]string, 0, end-v.top) + for _, line := range v.lines[v.top:end] { + line = ansi.Truncate(line, v.width, "") + for _, style := range []struct{ prefix, color string }{{"[CRITICAL]", "35"}, {"[ERROR]", "31"}, {"[WARNING]", "33"}, {"[INFO]", "34"}} { + if strings.HasPrefix(line, style.prefix) { + line = "\x1b[1;" + style.color + "m" + line + "\x1b[0m" + break + } + } + lines = append(lines, line) + } + return "\x1b[1;36m" + header + "\x1b[0m\n" + strings.Join(lines, "\n") + "\n\x1b[2m" + footer + "\x1b[0m" +} + +// Bubble Tea's renderer can ignore Write errors. Record them and cancel its +// context so an output failure cannot leave an interactive event loop running. +type terminalWriter struct { + output io.Writer + cancel context.CancelFunc + mu sync.Mutex + err error +} + +func (w *terminalWriter) Fd() uintptr { + if file, ok := w.output.(interface{ Fd() uintptr }); ok { + return file.Fd() + } + return ^uintptr(0) +} + +func (w *terminalWriter) Write(data []byte) (int, error) { + w.mu.Lock() + defer w.mu.Unlock() + n, err := w.output.Write(data) + if err == nil && n != len(data) { + err = io.ErrShortWrite + } + if err != nil { + if w.err == nil { + w.err = err + } + w.cancel() + } + return n, err +} + +type terminalState struct { + fd int + state *term.State +} + +func saveTerminalStates(streams ...any) ([]terminalState, error) { + states := []terminalState{} + seen := map[int]bool{} + for _, stream := range streams { + file, ok := stream.(interface{ Fd() uintptr }) + if !ok { + continue + } + fd := int(file.Fd()) + if seen[fd] || !term.IsTerminal(fd) { + continue + } + state, err := term.GetState(fd) + if err != nil { + return nil, err + } + states = append(states, terminalState{fd: fd, state: state}) + seen[fd] = true + } + return states, nil +} + +func restoreTerminalStates(states []terminalState) error { + var result error + for _, saved := range states { + result = errors.Join(result, term.Restore(saved.fd, saved.state)) + } + return result +} + +func resizePoller(ctx context.Context, request func(), interval time.Duration) <-chan struct{} { + done := make(chan struct{}) + go func() { + defer close(done) + ticker := time.NewTicker(interval) + defer ticker.Stop() + for { + select { + case <-ctx.Done(): + return + case <-ticker.C: + request() + } + } + }() + return done +} + +func (w *terminalWriter) failure() error { + w.mu.Lock() + defer w.mu.Unlock() + return w.err +} + +// WriteInteractive always leaves a plain report after the terminal viewer. +// The caller selects this path only for capable terminal streams. +func WriteInteractive(ctx context.Context, input io.Reader, output io.Writer, doc Document) error { + var plain bytes.Buffer + if err := WriteText(&plain, doc); err != nil { + return err + } + states, saveErr := saveTerminalStates(input, output) + if saveErr != nil { + return errors.Join(saveErr, WriteText(output, doc)) + } + runCtx, cancel := context.WithCancel(ctx) + defer cancel() + w := &terminalWriter{output: output, cancel: cancel} + v := newViewer(plain.String()) + program := tea.NewProgram(v, tea.WithInput(input), tea.WithOutput(w), tea.WithContext(runCtx), + tea.WithAltScreen(), tea.WithoutSignalHandler(), tea.WithoutBracketedPaste()) + // Bubble Tea v1.3.10 only checks the initial size on Windows (no SIGWINCH). + // Poll through its window-size command on terminal outputs. The adapter owns + // and joins this context-cancelled timer on every return, including startup + // and output failure; no Tick command remains asleep after the viewer exits. + var resizeDone <-chan struct{} + if file, ok := output.(interface{ Fd() uintptr }); ok && term.IsTerminal(int(file.Fd())) { + resizeDone = resizePoller(runCtx, func() { program.Send(tea.WindowSize()()) }, 200*time.Millisecond) + } + _, runErr := program.Run() + cancel() + if resizeDone != nil { + <-resizeDone + } + var cleanupErr error + if runErr != nil && input != nil { + cleanupErr = program.ReleaseTerminal() + } + cleanupErr = errors.Join(cleanupErr, restoreTerminalStates(states)) + if v.interrupted { + runErr = errors.Join(runErr, context.Canceled) + } + writeErr := WriteText(output, doc) + if err := errors.Join(runErr, cleanupErr, w.failure(), writeErr); err != nil { + return fmt.Errorf("interactive report failed; plain fallback attempted: %w", err) + } + return nil +} diff --git a/internal/report/interactive_test.go b/internal/report/interactive_test.go new file mode 100644 index 0000000..6247bb7 --- /dev/null +++ b/internal/report/interactive_test.go @@ -0,0 +1,167 @@ +package report + +import ( + "bytes" + "context" + "errors" + "runtime" + "strings" + "testing" + "time" + + tea "github.com/charmbracelet/bubbletea" + "github.com/charmbracelet/x/ansi" + + "github.com/shellghostt/envdoctor/internal/collector" +) + +func TestM4ViewerNarrowResizeScrollAndInterrupt(t *testing.T) { + v := newViewer(strings.Repeat("wide 界 text \t evidence\n", 50)) + for _, size := range [][2]int{{1, 1}, {2, 2}, {12, 8}, {80, 24}, {0, 0}, {10000, 10000}} { + _, _ = v.Update(tea.WindowSizeMsg{Width: size[0], Height: size[1]}) + for _, key := range []tea.KeyMsg{{Type: tea.KeyEnd}, {Type: tea.KeyPgUp}, {Type: tea.KeyDown}, {Type: tea.KeyHome}, {Type: tea.KeyUp}, {Type: tea.KeyPgDown}} { + _, _ = v.Update(key) + } + lines := strings.Split(v.View(), "\n") + if len(lines) > v.height || v.top < 0 || v.top > max(0, len(v.lines)-max(1, v.height-2)) { + t.Fatalf("viewport out of bounds at %v", size) + } + for _, line := range lines { + if width := ansi.StringWidth(line); width > v.width { + t.Fatalf("line width=%d viewport=%d: %q", width, v.width, line) + } + } + } + _, cmd := v.Update(tea.KeyMsg{Type: tea.KeyCtrlC}) + if !v.interrupted || cmd == nil { + t.Fatal("interrupt did not quit") + } + if _, ok := cmd().(tea.QuitMsg); !ok { + t.Fatal("interrupt did not return quit command") + } +} + +type lifecycleWriter struct { + bytes bytes.Buffer + cancel context.CancelFunc + failFrame bool + failed bool +} + +func (w *lifecycleWriter) Write(p []byte) (int, error) { + if w.cancel != nil && bytes.Contains(p, []byte("\x1b[?1049h")) { + w.cancel() + } + if w.failFrame && !w.failed && bytes.Contains(p, []byte("EnvDoctor |")) { + w.failed = true + return 0, errors.New("synthetic frame failure") + } + return w.bytes.Write(p) +} + +func viewerDocument() Document { + stamp := time.Date(2026, 11, 19, 10, 0, 0, 0, time.UTC) + return NewDocument("0.1.0", stamp, collector.Snapshot{SchemaVersion: 1, CollectedAt: stamp, Platform: &collector.Platform{OS: "windows", Arch: "amd64", Version: "11"}}, nil, nil, 12) +} + +func TestM4InteractiveQuitCancellationAndOutputCleanup(t *testing.T) { + for _, name := range []string{"quit", "cancel", "output-failure"} { + t.Run(name, func(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + writer := &lifecycleWriter{} + var input *strings.Reader + if name == "quit" { + input = strings.NewReader("q") + } + if name == "cancel" { + writer.cancel = cancel + } + if name == "output-failure" { + writer.failFrame = true + } + var err error + if input != nil { + err = WriteInteractive(ctx, input, writer, viewerDocument()) + } else { + err = WriteInteractive(ctx, nil, writer, viewerDocument()) + } + if (err != nil) != (name != "quit") { + t.Fatalf("%s error=%v", name, err) + } + if name == "cancel" && !errors.Is(err, context.Canceled) { + t.Fatalf("cancel=%v", err) + } + if name == "output-failure" && !writer.failed { + t.Fatal("frame failure was never exercised") + } + output := writer.bytes.String() + leave := strings.LastIndex(output, "\x1b[?1049l") + plain := strings.LastIndex(output, "EnvDoctor 0.1.0 - environment diagnosis") + if !strings.Contains(output, "\x1b[?1049h") || leave < 0 || !strings.Contains(output, "\x1b[?25h") || plain < leave { + t.Fatalf("screen/cursor/fallback cleanup missing: %q", output) + } + }) + } +} + +func TestM4RepeatedViewerLifecycleReleasesResources(t *testing.T) { + doc := viewerDocument() + if err := WriteInteractive(context.Background(), strings.NewReader("q"), &lifecycleWriter{}, doc); err != nil { + t.Fatal(err) + } + runtime.GC() + var before, after runtime.MemStats + runtime.ReadMemStats(&before) + beforeG := runtime.NumGoroutine() + start := time.Now() + for i := 0; i < 50; i++ { + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + writer := &lifecycleWriter{} + if i%2 == 0 { + if err := WriteInteractive(ctx, strings.NewReader("q"), writer, doc); err != nil { + t.Fatal(err) + } + } else { + writer.cancel = cancel + if err := WriteInteractive(ctx, nil, writer, doc); !errors.Is(err, context.Canceled) { + t.Fatalf("cancel=%v", err) + } + } + cancel() + } + deadline := time.Now().Add(2 * time.Second) + for runtime.NumGoroutine() > beforeG+2 && time.Now().Before(deadline) { + runtime.GC() + time.Sleep(10 * time.Millisecond) + } + runtime.GC() + runtime.ReadMemStats(&after) + afterG := runtime.NumGoroutine() + t.Logf("50 viewers: %s; goroutines %d -> %d; retained heap %d -> %d bytes", time.Since(start), beforeG, afterG, before.HeapAlloc, after.HeapAlloc) + if afterG > beforeG+2 || int64(after.HeapAlloc)-int64(before.HeapAlloc) > 2<<20 { + t.Fatal("viewer resources retained after repeated exits") + } +} + +func TestM4ResizePollerStopsAndJoinsOnCancellation(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + requested := make(chan struct{}, 1) + done := resizePoller(ctx, func() { + select { + case requested <- struct{}{}: + default: + } + }, time.Millisecond) + select { + case <-requested: + case <-time.After(time.Second): + t.Fatal("resize was not requested") + } + cancel() + select { + case <-done: + case <-time.After(time.Second): + t.Fatal("resize timer/goroutine retained") + } +} diff --git a/internal/report/json.go b/internal/report/json.go index ecb12a4..ac32544 100644 --- a/internal/report/json.go +++ b/internal/report/json.go @@ -9,7 +9,7 @@ import ( // WriteJSON writes exactly one JSON document followed by a newline. Nothing // else is written to the stream; progress and warnings go to stderr. func WriteJSON(w io.Writer, document Document) error { - encoder := json.NewEncoder(w) + encoder := json.NewEncoder(checkedWriter{output: w}) encoder.SetEscapeHTML(false) encoder.SetIndent("", " ") if err := encoder.Encode(document); err != nil { @@ -17,3 +17,17 @@ func WriteJSON(w io.Writer, document Document) error { } return nil } + +type checkedWriter struct{ output io.Writer } + +func (w checkedWriter) Write(p []byte) (int, error) { + n, err := w.output.Write(p) + if err == nil && n != len(p) { + err = io.ErrShortWrite + } + return n, err +} +func writeString(w io.Writer, s string) error { + _, err := checkedWriter{output: w}.Write([]byte(s)) + return err +} diff --git a/internal/report/m4_test.go b/internal/report/m4_test.go new file mode 100644 index 0000000..54e843d --- /dev/null +++ b/internal/report/m4_test.go @@ -0,0 +1,144 @@ +package report_test + +import ( + "bytes" + "errors" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/shellghostt/envdoctor/internal/collector" + "github.com/shellghostt/envdoctor/internal/diagnostic" + "github.com/shellghostt/envdoctor/internal/report" +) + +type failingWriter struct{} + +func (failingWriter) Write([]byte) (int, error) { return 0, errors.New("synthetic write failure") } + +func TestM4FormatPolicy(t *testing.T) { + tty := report.TerminalState{Input: true, Output: true, Error: true, Term: "xterm-256color"} + for _, tc := range []struct { + name string + opts report.FormatOptions + term report.TerminalState + want report.Mode + bad bool + }{ + {"interactive", report.FormatOptions{}, tty, report.Interactive, false}, + {"no-terminal", report.FormatOptions{}, report.TerminalState{}, report.Text, false}, + {"redirect-stdout", report.FormatOptions{}, report.TerminalState{Input: true, Error: true}, report.Text, false}, + {"redirect-stderr", report.FormatOptions{}, report.TerminalState{Input: true, Output: true}, report.Text, false}, + {"redirect-stdin", report.FormatOptions{}, report.TerminalState{Output: true, Error: true}, report.Text, false}, + {"dumb", report.FormatOptions{}, report.TerminalState{Input: true, Output: true, Error: true, Term: "dumb"}, report.Text, false}, + {"no-color-even-empty", report.FormatOptions{}, report.TerminalState{Input: true, Output: true, Error: true, NoColor: true}, report.Text, false}, + {"windows-no-term", report.FormatOptions{}, report.TerminalState{Input: true, Output: true, Error: true}, report.Interactive, false}, + {"plain", report.FormatOptions{Plain: true}, tty, report.Text, false}, + {"explicit-text", report.FormatOptions{Format: "text", Explicit: true}, tty, report.Text, false}, + {"json-alias", report.FormatOptions{JSON: true}, tty, report.JSON, false}, + {"json", report.FormatOptions{Format: "json", Explicit: true}, tty, report.JSON, false}, + {"markdown", report.FormatOptions{Format: "markdown", Explicit: true}, tty, report.Markdown, false}, + {"compatible-json", report.FormatOptions{JSON: true, Format: "json", Explicit: true}, tty, report.JSON, false}, + {"conflicting-alias", report.FormatOptions{JSON: true, Format: "markdown", Explicit: true}, tty, "", true}, + {"plain-json", report.FormatOptions{JSON: true, Plain: true}, tty, "", true}, + {"plain-markdown", report.FormatOptions{Plain: true, Format: "markdown", Explicit: true}, tty, "", true}, + {"unknown", report.FormatOptions{Format: "html", Explicit: true}, tty, "", true}, + } { + t.Run(tc.name, func(t *testing.T) { + got, err := report.SelectMode(tc.opts, tc.term) + if (err != nil) != tc.bad || !tc.bad && got != tc.want { + t.Fatalf("mode=%q, err=%v; want=%q, bad=%v", got, err, tc.want, tc.bad) + } + }) + } +} + +func markdownDocument() report.Document { + s := collector.Snapshot{SchemaVersion: 1, CollectedAt: fixedTime, + Platform: &collector.Platform{OS: "windows", Arch: "amd64"}, + Errors: []collector.CollectorError{{Collector: "git", Message: "captured collector unavailable"}}} + findings := []diagnostic.Finding{ + {RuleID: "ENV900", Severity: diagnostic.SeverityCritical, Component: "git", Title: "Critical evidence", + Detected: []string{"|[x](https://invalid.example)"}, Cause: "Unknown cause", + Fix: &diagnostic.Fix{Summary: "Check manually", Commands: []string{"echo `test`"}}, Verify: "echo \"ok\""}, + {RuleID: "ENV901", Severity: diagnostic.SeverityError, Component: "git", Title: "Error evidence", Detected: []string{"error"}}, + {RuleID: "ENV902", Severity: diagnostic.SeverityWarning, Component: "git", Title: "Warning evidence", Detected: []string{"warning"}}, + {RuleID: "ENV903", Severity: diagnostic.SeverityInfo, Component: "git", Title: "Info evidence", Detected: []string{"info"}}, + } + findings[0].Detected = append(findings[0].Detected, `C:\synthetic\project with spaces\`+strings.Repeat(`long-directory-name-0123456789\`, 8)+`|file.txt`) + doc := report.NewDocument("0.1.0", fixedTime, s, findings, nil, 12) + doc.Source = &report.Source{Kind: "bundle", CaptureTool: report.Tool{Name: "envdoctor", Version: "0.1.0"}, + CapturedAt: fixedTime, RedactionPolicy: "allowlist-v1", CaptureExitCode: 2, + Omissions: []report.Omission{{Field: "git.identity", Reason: "identifying_values"}}} + return doc +} + +func TestM4MarkdownBoundsAndBidiControls(t *testing.T) { + doc := markdownDocument() + doc.Findings[0].Detected = []string{"visible\u202Eafter"} + var out bytes.Buffer + if err := report.WriteMarkdown(&out, doc); err != nil { + t.Fatal(err) + } + if strings.ContainsRune(out.String(), '\u202E') || !strings.Contains(out.String(), "u202E") { + t.Fatal("bidi control not made visible") + } + doc.Findings[0].Detected = []string{strings.Repeat("!", 1<<20)} + out.Reset() + if err := report.WriteMarkdown(&out, doc); err == nil || out.Len() != 0 { + t.Fatal("oversized Markdown partially written or accepted") + } +} + +func TestM4MarkdownGoldenAndEscaping(t *testing.T) { + var out bytes.Buffer + if err := report.WriteMarkdown(&out, markdownDocument()); err != nil { + t.Fatal(err) + } + want, err := os.ReadFile(filepath.Join("testdata", "markdown-m4.golden")) + if err != nil { + t.Fatal(err) + } + if out.String() != string(want) { + t.Fatalf("Markdown differs from reviewed golden:\n%s", out.String()) + } + for _, forbidden := range []string{"