Sanitized diagnostic bundles (honua doctor)

honua doctor creates a local, bounded support artifact without uploading it. The command uses the canonical diagnostic-bundle.v1 JSON Schema, vendored byte-for-byte in schemas/diagnostic-bundle.v1.json and pinned to:

• support source commit 0c990fbe8f519a00a57e26dab21cbb8f80d559ea;
• 6,494 bytes; and
• SHA-256 4dd7282d17bb417d56f1c3cfa243e03b612a401e5d22be766658849287e431a9.

The public provenance record is at diagnostic-bundle.v1.provenance.json.

Capture and review

Capture one failing exchange in a local JSON file. This input may contain raw values because it is read only into memory and is never copied to output:

{
  "request": {
    "method": "GET",
    "url": "https://server.example/api/v1/services/parcels?token=secret",
    "headers": { "authorization": "Bearer secret", "x-request-id": "request-1" }
  },
  "response": {
    "status": 500,
    "mediaType": "application/json",
    "headers": { "content-type": "application/json" },
    "body": { "error": "failed", "apiKey": "secret" }
  }
}

Then explicitly choose classification and both consent values:

honua doctor \
  --exchange ./failure.json \
  --classification customer-data \
  --redaction-acknowledged=true \
  --share-with-support=false \
  --output ./diagnostic-bundle.json \
  --json

Add --base-url https://server.example/honua to attempt an anonymous, credential-free capability probe. The configured base path is preserved (/honua/api/v1/services). Probe failure becomes a sanitized envelope and never removes the explicitly supplied failure, which stays last in the bundle.

Review diagnostic-bundle.json, then rerun with --share-with-support=true only when you intend to submit it through the support intake. The CLI never uploads. Output is written with owner-only permissions where the platform supports them. --json prints only a machine summary and outputWritten state, not the path or captured body previews.

Privacy boundary

The emitter:

• drops Authorization, Proxy-Authorization, Cookie, Set-Cookie, API keys, signatures, tokens, and every non-allowlisted header;
• removes URL origin/userinfo, drops sensitive query parameters, placeholders all query values, and preserves only a small allowlist of public route vocabulary (unknown path segments become {value});
• recursively redacts sensitive JSON keys, form values, free-text credentials, common provider tokens, AWS keys, email addresses, and up to two URL-encoding layers;
• rejects optional bundle ids or consent identities that contain credential-shaped or personal material instead of copying unsafe metadata into the artifact;
• hashes the original in-memory bytes, but persists only a redacted preview capped at 8 KiB, original byte count, SHA-256, and truncation/redaction flags; and
• refuses bodies above the schema's 25 MiB ceiling or bundles above 50 envelopes.

No raw body, credential, cookie, customer payload, or configured API key is written to stdout, stderr, the artifact, telemetry, or snapshots.

Read-only replay

Replay one sanitized exchange against a separately configured server:

honua doctor \
  --replay ./diagnostic-bundle.json \
  --base-url https://server.example \
  --output ./diagnostic-replay.json \
  --timeout-ms 10000 \
  --json

Replay validates the entire input before network access, verifies the schema pin and verifiable body hashes, sends no captured headers or query values, omits credentials, disables redirects and caching, and permits only one bounded GET or HEAD. It refuses mutations, subscriptions/streams, job submission, uploads, traversal, placeholder path segments, non-HTTPS remote origins, unsafe headers, credential-bearing artifacts, hash drift, malformed schemas, over-budget responses, timeout, and abort. The result is a new sanitized bundle; replay never modifies its input.

Programmatic APIs are available from @honua/sdk-js/diagnostics.