Lock the Support bundle security and acceptance contract

[frankieramirez]

Question

What security, backend, frontend, and end-to-end acceptance checks must an implementation pass before Comicarr may restore the Support bundle instruction in its bug-report template?

Cover authentication and CSRF behavior, archive manifest and redaction assertions, supported runtime paths, concurrency and cleanup, binary download behavior, UI states, failure handling, and regression protection.

Settled UI input

Specify the Settings Support bundle interaction places one Support bundle group in Settings → About with an ordered Create → Inspect → Share disclosure sequence and an accessible confirmation dialog. The binary helper validates the fixed response contract before dispatching a short-lived Blob download. The observable state machine covers idle, confirming, creating, complete, partial, canceled, network interruption, concurrent 409, retryable unavailable/generation failure, terminal disclosure validation failure, auth/CSRF, navigation/unmount, focus return, live-region announcements, and object-URL cleanup. Documentation must rename CarePackage and stop claiming the bundle contains config, database, environment, or logs.

[frankieramirez]

Resolution

Restoring the bug-report instruction is a release gate, not a documentation task. The implementation may advertise the Support bundle for public issue attachment only after the closed data, generation, and UI contracts pass the automated and human evidence below. Failure in any required gate keeps the instruction out of the template.

Test ownership and seams

The new implementation receives its own tests; the legacy redaction suite is regression coverage for the isolated CLI path, not evidence that the modern bundle is safe.

• tests/unit/test_support_bundle.py owns the deep-module contract, closed schemas, archive construction, disclosure guards, bounds, source availability, locking, and cleanup-by-construction.
• tests/unit/test_support_bundle_api.py owns the thin router, authentication, CSRF, request/response headers, fixed errors, and absence of alternate routes.
• tests/integration/test_support_bundle_dialects.py owns live aggregate-query behavior for SQLite, PostgreSQL, and MySQL in the existing database-service matrix.
• frontend/tests/unit/lib/supportBundle.test.ts owns the dedicated binary helper and Blob/download lifecycle.
• frontend/tests/components/SupportBundle.test.tsx owns the dialog and observable state machine.
• frontend/tests/pages/SettingsPage.test.ts owns placement and ordering in Settings → About.
• frontend/tests/e2e/support-bundle.smoke.spec.ts owns the authenticated browser happy path and the public HTTP boundary.
• tests/unit/test_carepackage_security.py remains green unchanged unless the separately out-of-scope CLI contract changes. No modern test may instantiate, patch through, or treat carePackage as its system under test.

Names may follow the repository's final organization, but these responsibilities may not be collapsed into one happy-path test.

Closed archive and schema gates

Positive tests must generate through generate_support_bundle(ctx) and prove:

1. the immutable artifact exposes only bytes, contract version 1, fixed filename comicarr-support-bundle-v1.zip, and complete|partial status;
2. the ZIP has exactly README.txt, manifest.json, and diagnostics.json, once each and in that order, with relative fixed names, normalized ZipInfo metadata, no extra fields/comments, no encrypted member, and the settled member and archive size caps;
3. README.txt is byte-for-byte the reviewed static v1 text and contains no runtime substitution;
4. both JSON documents decode as UTF-8, validate against checked-in closed v1 schemas, reject duplicate JSON keys, non-finite numbers, unknown keys/enums, unbounded collections, and wrong primitive types, and round-trip without a permissive serialization fallback;
5. the manifest's contract/product values, one captured UTC generation time, disclosure marker, source states, member names, and the non-self-referential sizes and SHA-256 values defined below agree with the final archive; and
6. complete and partial artifacts are internally consistent: partial requires at least one typed optional-source omission, while complete permits none.

The manifest must not require an impossible self-referential hash. Its inventory lists all three members in fixed order; v1 hashes the two payload members (README.txt and diagnostics.json). manifest.json is protected by its closed schema, fixed position/name, response length, archive cap, and final validation. Adding a manifest self-hash later requires an explicit canonicalization rule and contract-version decision. Tests assert semantic fields and normalized ZIP metadata, not one exact compressed archive hash or compression ratio.

The checked-in v1 field manifest is itself an acceptance artifact. For every emitted field it records path, meaning, sensitivity classification, primitive/enum, cardinality or numeric/string bound, source authority, complete/partial behavior, and contract version. A schema snapshot test fails on any added, removed, or widened member, field, enum, dependency allowlist entry, aggregate, capability, or omission reason until that manifest and the contract version are deliberately reviewed. Adding database tables, config keys, integrations, providers, or log formats alone can never change output.

Disclosure and negative-security gates

One seeded canary fixture must place unique values in every reachable authority: active config, custom directory names, database URL and rows, log tail, environment, runtime username/hostname, provider/downloader configuration, notification and AI/chat content, exception paths, and mocked dependency/build inputs. It includes at least:

• passwords, API/JWT/Fernet/provider/32P tokens and authorization headers;
• credentialed and query-bearing URLs, endpoints, proxies, email-like values, IP/host/user names, absolute and relative POSIX and Windows paths, basenames, branch/commit-like values, and executable locations;
• library titles, issue names, external IDs, torrent hashes, payload JSON, chat/prompts/results, raw log lines, tracebacks, and free-text exception messages; and
• dangerous archive names, JSON keys, oversized counts/strings, invalid Unicode/control characters, and values that resemble permitted enums but are not exact members.

After generation, a single archive-wide guard scans the filename, response headers, ZIP comment and metadata, member names, and every decompressed byte for every exact canary and for reviewed credential-, URL-, path-, and control-character patterns. Each canary must first be proven present in its source fixture so a broken setup cannot pass vacuously. The test also proves that no raw source file or row is copied and no redaction marker is used as an admission mechanism. One forbidden key, type, value, member, bound, or serialization fallback aborts generation with no bytes returned.

Guard-pattern tests use explicit safe fixtures and false-positive cases. They do not claim that regex can detect every secret; the closed allowlist is the security boundary and scanning is defense in depth.

Runtime, source, and dialect gates

Tests resolve every source from the active AppContext and active SQLAlchemy engine using default and custom config, data, log, secure, and database locations. Every source path contains a unique canary that is never serialized. There is no guessed-default fallback when a custom source is missing, unreadable, malformed, or access-denied.

For every optional source, tests cover available and each supported fixed omission reason. Optional failure yields a schema-valid partial artifact and never leaks the caught message or path. Missing mandatory authority, final validation failure, and unexpected collection failure return no artifact. Collection performs no network call or subprocess, uses a fixed number of bounded aggregate queries, exports no rows, reads no log rotation, and respects all settled byte/cardinality caps.

The existing CI database matrix is extended to execute the same support-bundle projection integration test against live SQLite, PostgreSQL 16, and MySQL 8.4. It proves the fixed aggregates and schema/migration facts have equivalent normalized output and that database URLs, credentials, dialect-specific errors, table contents, and physical paths do not appear. SQL compilation mocks alone do not satisfy this gate. The normal Python 3.10, 3.11, and 3.12 unit matrix remains required.

Lifecycle, concurrency, and logging gates

Deterministic barrier tests prove one in-process request owns the private non-blocking lock, a simultaneous request fails immediately with the typed concurrent error, and a fresh request succeeds after each success and failure path. The lock releases from finally after collector, validation, ZIP, client-disconnect, and shutdown-path failures. Waiting, byte sharing, caching, polling, and automatic retry are forbidden.

The service uses memory only, so tests inspect its seam and a dedicated temporary working directory before and after success, partial success, every typed failure, disconnect, and repeated generation. No bundle, staging file, temp directory, cache/job record, file handle, or partial response remains. Tests do not require interrupting the synchronous server work when a browser aborts: bounded generation may finish, its result is discarded, and the lock becomes available.

Logging tests inject source and exception canaries and capture every logger level. The only permitted fields are the fixed outcome code, contract version, complete/partial state, duration bucket, output-size bucket, and exception class where necessary. Artifact bytes, headers/cookies, username, paths, source values, and raw exception text are absent. Unexpected errors still map to a safe typed response and do not escape as a traceback body.

HTTP and failure gates

Router and end-to-end tests prove there is exactly one modern route: session-only POST /api/system/support-bundle, with no body or query options and no GET, API-key, legacy-mode, or unauthenticated path.

• Missing/expired/invalid session: existing 401 behavior.
• Missing or wrong X-Requested-With: existing 403 CSRF behavior; exact ComicarrFrontend proceeds.
• Complete or partial success: 200 application/zip, non-empty body no larger than 512 KiB, fixed Content-Disposition, Cache-Control: no-store, private, Pragma: no-cache, contract/status headers, and no ETag or Last-Modified.
• Concurrent request: fixed 409 support_bundle_in_progress, retryable true, Retry-After: 2.
• Mandatory authority/shutdown: fixed 503 support_bundle_unavailable, retryable true.
• Disclosure/schema failure: fixed 500 support_bundle_validation_failed, retryable false.
• Unexpected generation failure: fixed 500 support_bundle_generation_failed, retryable true.

Every error body has exactly the settled detail, code, and retryable keys with fixed safe text. No failure sends ZIP headers or partially assembled bytes. A route introspection test prevents accidentally registering another support-bundle method or authentication class.

Frontend and accessibility gates

Helper tests prove one same-origin credentialed POST with the exact CSRF header and no caller-controlled path, payload, filename, or options. The helper accepts a download only after validating status, media type, contract/status headers, fixed Content-Disposition, non-empty body, and the 512 KiB cap. It sanitizes typed JSON errors through the existing ApiError rules. Protocol mismatch, empty/oversized body, invalid header, Blob creation failure, or anchor dispatch failure offers no file and becomes the terminal safety result.

Spies on URL.createObjectURL, the hidden anchor, and URL.revokeObjectURL prove the fixed filename is dispatched once and every created URL is revoked after dispatch or on failure/unmount. Browser tests assert the download event and suggested filename, not the operating system's save dialog or final filesystem location.

Component tests cover every settled observable transition: idle; confirmation; cancel/Escape/backdrop/close without a request; one disabled/busy creating request; complete; partial; visible cancellation; interrupted network with manual fresh retry; 409 with Retry-After before retry becomes enabled; retryable 503 and generation failure without automatic retry; terminal server/client validation failure with Close only; 401; 403; navigation/unmount; and rejection of double submission or late completion.

They assert exact disclosure/result copy, complete-versus-partial treatment, no automatic polling/retry, no retained Blob, and no mutation of or dependency on unsaved Settings form state. Dialog tests cover accessible name/description, initial focus on Cancel, focus trap, keyboard operation, disabled and aria-busy state, Escape semantics, and focus return to Create support bundle. A mounted atomic polite role=status is authoritative for progress/cancel/success/partial; errors use role=alert; decorative progress is hidden; results are not dependent on toast announcement or color.

Page tests prove one group appears in Settings → About between What's new and Build / environment, with the literal ordered Create → Inspect → Share sequence and mobile-preserving DOM order. The interaction adds no new settings-rail entry and does not submit or discard the global form.

The authenticated Playwright smoke test exercises confirmation through a real response, validates the browser download filename, opens the returned ZIP bytes in test code to check the exact three-member inventory and disclosure marker, and leaves the browser monitor clean. Its API companions cover unauthenticated and CSRF-negative requests. Unit/component tests, rather than timing-sensitive browser tests, own every error state and object-URL implementation detail.

Documentation and human review gate

The inaccurate current CarePackage block is not grandfathered. It must be removed before the feature is available, or replaced atomically only after all gates pass. The bug template, contributing guide, and security guide then use only Support bundle and the settled Settings → About → Create and download → inspect three files → public-if-comfortable/private-otherwise instructions. They make no claim about config, database, environment, or logs and never suggest a raw DEBUG log as the public fallback.

A terminology/source scan fails on user-facing CarePackage/Care Package, the old content claims, or an unreviewed instruction to attach raw diagnostics. Legacy implementation identifiers and explicitly historical developer tests may remain only in an enumerated versioned allowlist; any new match fails CI.

Before template restoration, a maintainer/security reviewer records inspection of one complete and one partial artifact produced from the seeded canary fixture. The PR evidence records contract version, schemas/field-manifest revision, artifact SHA-256 values, test commit, reviewer, and confirmation that filenames, metadata, and decompressed contents meet the public-attachment threat model. The artifacts themselves are retained only as ephemeral CI/review artifacts with short retention and are never committed when they contain runtime-derived data.

Required merge evidence

The implementation and documentation may merge together only when all required checks are green:

• uv lock --check
• npm run lint
• uv run pytest tests/unit -v -m "not slow"
• uv run pytest tests/integration -v -m "not slow", including the live three-dialect support-bundle matrix
• cd frontend && npm run test:run && npm run typecheck && npm run build
• cd frontend && npm run test:e2e:smoke
• the terminology/source allowlist scan; and
• the recorded complete/partial human artifact review.

The existing full E2E schedule remains a regression signal, but the Support bundle happy path belongs in required smoke coverage so documentation cannot ship ahead of it. There is no coverage-percentage gate: the named security properties and mutation-resistant negative cases are the acceptance boundary.

Regression and change control

Changes to members, schemas, field manifest, enum sets, dependency allowlist, bounds, source authorities, sharing copy, route/method/authentication, filename, persistence, or public-attachment claim require an explicit contract-version/security review. Tests fail closed until that decision is recorded. Refactors that claim identical behavior regenerate complete and partial artifacts from the canary fixture and pass the same archive-wide comparison and human-review checklist.

These gates intentionally do not require a universal secret detector, exact compressed ZIP bytes, a browser “file saved” signal, interruption of already-running bounded synchronous work, coverage of unsupported operating systems/deployments, or a progress percentage/job lifecycle. None of those is a reliable or settled property.