fix(security): bind analysis paths to filesystem authority

[seonghobae]

Security outcome

Analysis path strings are authority-bearing inputs. This Draft addresses #852 in BandScope without dependency, lockfile, workflow, model, network, database, or vulnerability-suppression changes.

Exact current state

• Exact head: bbea51769915b0383dd74d9e900d221e479afeea.
• Protected base: develop@749511c3ad4000090048718f685c6bee6b3d2c25.
• Open, Draft, unmerged. No predecessor check/review evidence transfers to this head.
• Protected develop is already integrated into this branch through ordinary history-preserving ancestry; fix(security): establish canonical npm, PDF.js, Nanoid, and Undici baseline #783 is protected truth rather than a remaining prerequisite.

Bounded authority contract

The branch rejects relative/drive-relative paths, traversal, UNC/network roots including mixed-separator spellings, Win32 device namespaces and console aliases, alternate streams, foreign-host absolute authority at native preflight, direct selected-source symlinks, non-directory writable roots, and already-present derived cache/temp symlink escapes. Lexical cross-platform validation stays separate from native filesystem authority and diagnostics stay payload-safe.

Exact feature-cache files, atomic-write siblings, stem-work arrays, and the stem-work metadata sidecar are revalidated against app-owned authority before repository-owned I/O. The parent helper treats the already-authorized arrays_path as authority, not the worker-returned arraysPath; a missing or unequal payload path fails closed before sidecar write or unlink. Late path-authority failures remain payload-safe invalid_request results, while ordinary media/runtime failures retain the existing engine-unavailable/fallback contract.

Canonicalization is a point-in-time control and does not claim descriptor/handle-level race freedom against a privileged local actor replacing entries after validation.

Current-head causal repair

Exact predecessor head 197664bcb2fec097aee252e924c12870ebc8c44f added a production-boundary privacy regression for rejected traversal values. Its release-preflight run 33496149363, job 99818702562, proved two real failures: cacheRoot and tempRoot traversal were rejected safely but emitted no security warning, while projectId already did. The full analysis suite otherwise reached 777 passed / 24 skipped and 100% owned coverage; the two missing-log assertions made release-preflight correctly fail.

Current head bbea51769915b0383dd74d9e900d221e479afeea is the smallest causal repair. validate_local_path_shape now emits one WARNING that names only the trusted field identifier when its own lexical traversal branch rejects a value, then preserves the same payload-safe ValueError. It never logs the untrusted path text. This keeps traversal classification and telemetry at the path-authority boundary instead of duplicating parsing in API callers, and the existing privacy regression requires the secret marker to remain absent from logs.

Fresh repository workflows have materialized for this exact head and are currently queued/in progress. Queued or in-progress evidence is non-passing; predecessor GREEN does not transfer.

Verification contract

The exact PR head must cover POSIX/Windows adversarial path syntax; mixed UNC/device namespaces; DOS/console devices; Windows normalization/stream forms; foreign-host preflight; source/writable-root type and symlink cases; exact feature-cache and atomic-write child authority; stem-work sidecar and worker-envelope authority; late invalid-request classification; payload-safe diagnostics; full analysis-engine behavior; exact 100% owned statement/branch coverage; docstrings/type/lint/build; SAST/security/dependency/SBOM/supply-chain/package/release gates; zero valid unresolved findings; current automated review; and a qualifying independent non-author approval.

Keep Draft until the branch has current review and all applicable exact-head gates required for independent review. Do not merge until every applicable required check is terminal-success on one unchanged exact head and ordinary protected-branch acceptance succeeds without bypass. Queued, pending, skipped-required, cancelled, absent, neutral, failed, stale, predecessor-head, protected-base, model-only, self/author, status-only, or administrative-bypass evidence is not success.

Closes #852 only after protected merge.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

@jules Implement the production half of this Draft on the existing fix/path-authority-boundary-852 branch only, starting from exact head db92b8b1b3698ed8eb03335f9bbe6e24685186dc. The RED contract is already in services/analysis-engine/tests/test_path_authority.py; do not weaken or delete those tests to get green.

Scope is strictly #852: services/analysis-engine/src/bandscope_analysis/api.py, a small dedicated path-authority module if useful, focused tests, CHANGELOG.md, and docs/doctoring/filesystem-path-authority.md. No dependency, lockfile, .trivyignore, workflow, model, generated patch script, or unrelated cleanup changes.

Required behavior:

• localSource.sourcePath, cacheRoot, and tempRoot must reject relative paths, Windows drive-relative forms (including C:..\\x), UNC/network roots, Windows device paths, and lexical ./.. traversal without echoing attacker-controlled path values in errors.
• Preserve ordinary native absolute POSIX paths and ordinary native absolute Windows paths on Windows; do not reject valid local absolute paths merely because CI runs on another OS. Implement lexical shape classification cross-platform, then enforce native-path authority at the actual filesystem-use boundary.
• Before stem separation, resolve the selected local source using a fail-closed helper: expand user, require native absolute local path, reject a direct symlink, resolve(strict=True), require a regular file, and pass only the canonical resolved path to the separator. Keep missing-file vs invalid-request behavior safe and existing public error envelopes compatible.
• Cache/temp derived paths must stay under the canonical authorized root even if the fixed analysis-cache-v1 or stem-work-v1 child already exists as a symlink. Use fixed digest filenames and canonical containment; do not introduce caller-controlled child names.
• Keep source absolute paths out of persisted cache metadata and out of user-facing errors/logs.
• Document the residual TOCTOU boundary honestly rather than claiming descriptor-level race freedom.
• Maintain 100% owned production statement/branch coverage and public docstrings.

Use current primary references in doctoring: Microsoft Learn Windows path formats/namespaces, MITRE CWE-22, and Python 3.14 pathlib documentation, formatted APA 7. First prove the existing RED test fails for the intended reason, then make the narrowest implementation and run focused tests plus full repository quickcheck. If exact head or branch moves before your write, refetch and reconcile rather than overwriting. Keep the PR Draft; do not merge, bypass protection, change reviewer credentials, or touch #783/#1008.

[seonghobae]

Exact-head gate refresh for e020e4c77db473b9578746a356a4c3fba391356a after the previously non-terminal runs completed:

• ci run 31930865376 is terminal-success. ci / build-and-test job 95125363073 successfully installed the native Rust numeric extension and completed repository quickcheck; gate / ci / rust-check job 95125363103 also completed successfully, including frontend build, Tauri check, and Tauri tests.
• release run 31930865342 is terminal-success.
• build-baseline run 31930865322 is terminal-success.
• sbom, Semgrep, Bandit, and secret-scan remain terminal-success on this exact head.
• security-audit run 31930865304, job 95125362768, is terminal-failure specifically at Audit npm dependencies; setup/install completed first, and Python/Rust audit stages are skipped after npm exits. The exact check-run annotation is only the generic exit-code-1 marker. Both the exact job-log and run-log endpoints were inspected and return an empty payload through the connector, so no unobserved log text is being represented as evidence.
• Aggregate Security Scan run 31930865354 remains terminal-failure only in trivy-fs job 95125364112. The exact job sequence shows filesystem scan and SARIF-output requirement succeed before the finding gate fails; OSV base-vs-head/PR-introduced comparison, dependency review, and Scorecard are terminal-success. The exact Trivy annotation is likewise only the generic exit-code-1 marker and the job-log endpoint returns an empty payload through the connector.

This seven-file branch has no JavaScript dependency/root-lock delta. Combined with the clean exact-head PR-introduced OSV comparison and the already inspected protected-base pdfjs-dist finding on this same run, the remaining whole-tree npm/Trivy failures stay classified as inherited protected-develop evidence owned by canonical #783. They are not suppressed, duplicated, or counted as success here.

Review refresh: both visible inline threads remain resolved and the formal review list still contains no qualifying independent non-author approval. Python branch coverage is also not inferred from this protected-base-lineage quickcheck; #861 remains the measurement prerequisite. Keep Draft; no merge/auto-merge is eligible.

[cursor]

Exact-head review of 8a9321d3eeadbf4a35c996d3d3a013b294af38ca.

The prior stem-work {digest}.json sidecar residual is fixed on this head: a pre-existing symlink next to the authorized arrays file is rejected before write, and the job fails as invalid_request before progress. Mixed-separator UNC/device prefixes, CONIN$/CONOUT$, leading ASCII-space components, and feature-cache sibling re-resolve still hold.

Do not merge this head as closing #852. _run_stem_separation_with_timeout still treats a worker-supplied arraysPath as writable tempRoot authority. A mismatched ok_file envelope can write or unlink a sidecar outside the authorized stem-work child. I reproduced that write/unlink against an outside sentinel, then bound sidecar write and array reload to the parent-helper authorized arrays_path on successor 30293ac30680f9cff5b3888bb9399d6b611f7e75.

Late _build_local_audio_features path-authority ValueError after progress is still mapped to engine_unavailable on this head. That is fail-closed but tells the musician the engine died instead of asking them to pick another temp folder. The successor keeps that failure as invalid_request.

Inherited JavaScript findings stay with #783. Python branch-coverage ownership stays with #861. Canonicalization remains point-in-time; descriptor-level TOCTOU is still out of scope.

Prefer the successor over this head. Do not open a third #852 PR.

  

_{Sent by Cursor Automation: Fix Issues}

Findings were verified against successor head 30293ac and addressed on the canonical #858 branch: worker arraysPath is now required to equal the parent-authorized arrays_path before sidecar/reload I/O, and late Invalid analysis job request: ValueError remains invalid_request. Both corresponding threads are resolved. Dismissing this predecessor-head CHANGES_REQUESTED review only clears stale review state; it is not approval, and current-head required checks plus qualifying independent last-push approval remain required.

[seonghobae]

@opencode-agent EXECUTION-FIRST owner repair on existing fix/path-authority-boundary-852 only. Fresh identity: PR #858 is open/Draft/unmerged and currently non-mergeable at exact head bedc2069494c0687f02873097226de04fa86f484; live protected develop is 7ad56cf0065d068ec6463d92726de4855a6e201d after #783 merged. Refetch head/base/target blobs/reviews/checks immediately before writing and adapt if anything moves. Do not create another branch/PR, force-push, destructively rebase, or weaken gates.

The old Draft body still treats #783 as pending and its protected base as acdbea...; that evidence is stale. Non-destructively integrate current protected develop@7ad56cf... into this branch using ordinary history-preserving merge/restack. Fresh changed-file inventory for #858 is confined to CHANGELOG.md, filesystem-authority doctoring, api.py, path_authority.py, and focused analysis-engine tests; #783's shipped dependency/workflow/npm authority must be preserved, not duplicated. Resolve only genuine overlap (expected shared prose such as CHANGELOG) while retaining both shipped security truth and #858's path-authority invariants.

Apply systematic-debugging, receiving-code-review, and verification-before-completion. Re-run the exact path-authority regressions for relative/drive-relative/traversal/UNC/device/ADS inputs, direct symlink and derived cache/temp/stem-work escape rejection, worker arraysPath binding, late invalid_request classification, payload-safe diagnostics and residual TOCTOU documentation. Then run analysis-engine mypy/Ruff/tests, exact owned statement+branch coverage, canonical ./scripts/harness/quickcheck.sh, repository CI/build/release/SAST/security/SBOM/supply-chain, and current central coverage/OpenCode/Noema/Strix gates. Do not transfer the old npm/Trivy failures: #783 is protected truth now, so any successor security failure must be inspected from the new exact checkout/job/log.

If the integrated exact head is review-ready, update the PR body to the actual head/base/current evidence and move out of Draft only after the branch itself is clean enough for independent review. Request/obtain a qualifying independent non-author last-push review through the existing authorized review path. Do not merge unless every applicable required exact-head gate succeeds without bypass.

[seonghobae]

@opencode-agent EXECUTION-FIRST owner repair on existing fix/path-authority-boundary-852 only. I have non-destructively integrated protected develop@749511c3ad4000090048718f685c6bee6b3d2c25 into this branch; the current exact head is 718d9d50d132ce2ad75cfe319b34cdadb2f2dd84. Refetch head/base/target blobs/checks immediately before writing and adapt if anything moves. Do not create another branch/PR, force-push, weaken gates, or revert the payload-safe logging boundary.

Apply systematic-debugging, test-driven-development, receiving-code-review, and verification-before-completion to the now-proven CI defect. Historical exact-head CI run 32384777744, job 96476466188, checked out merge SHA 8a09562fda912f57009c0b12d0f11838da066cdb and failed quickcheck with exactly two Python failures plus 99.78% coverage: test_run_analysis_job_updates_fail_safely_when_local_separation_fails and test_stem_separation_worker_maps_safe_error_kinds. Both tests still assert logger.exception(...), while current branch production deliberately uses payload-safe logger.error("Stem separation failed before analysis job completion. (%s)", type(error).__name__) and logger.error("%s (%s)", log_message, type(error).__name__).

That production direction is intentional security behavior, not the defect: tests/test_analysis_orchestration_logging_privacy.py requires local paths/secrets to stay out of logs and requires record.exc_info is None. Reintroducing logger.exception would leak exception-controlled payloads/tracebacks and is forbidden.

Smallest repair on this exact owner branch: update only the two stale tests/test_api.py logging assertions to the current safe logger.error contract. For the job-level ValueError case assert logger.error.assert_called_once_with("Stem separation failed before analysis job completion. (%s)", "ValueError"); in the worker cases assert logger.error.assert_called_once_with("%s (%s)", expected_log_message, type(error).__name__). Preserve the privacy regression unchanged.

Run RED/GREEN evidence focused on those two tests plus test_analysis_orchestration_logging_privacy.py, then the full analysis-engine suite with exact 100% owned statement+branch coverage and canonical ./scripts/harness/quickcheck.sh. After any new head, inspect exact current workflow jobs/logs rather than transferring predecessor evidence. Keep Draft until all applicable exact-head required gates and qualifying independent review pass.

[seonghobae]

@opencode-agent Review current exact head f1f5e877f07aa7486cd343ddfe8aa45a9d628bbd of existing Draft PR #858 only; do not mutate source unless the review proves a current-head BandScope-owned defect. Refetch protected develop@749511c3ad4000090048718f685c6bee6b3d2c25, the exact PR head, diff, reviews/threads, and current checks before acting.

The prior stale-test defect has already been repaired on this head by test(api): match redacted stem failure logging: the two affected assertions now require the payload-safe logger.error(..., exception_type) contract, while the privacy regression continues to forbid exc_info/path-secret leakage. Exact-head ci / build-and-test, Rust check, and Windows/macOS build gates have completed successfully. The current required opencode-review failed only at Fail closed without a current-head OpenCode verdict; predecessor reviews/verdicts do not transfer.

Perform an independent current-head review of the #852 filesystem-authority boundary and the new logging-test repair. Revalidate relative/drive-relative/traversal/UNC/device/ADS rejection, selected-source and derived cache/temp/stem-work authority, worker arraysPath binding, late invalid_request mapping, payload-safe diagnostics, residual TOCTOU claims, and that the two updated tests match production without weakening privacy. Publish the formal verdict against this exact SHA. If you find a defect, identify the first causal boundary and smallest realistic regression/fix on this canonical branch; otherwise publish the current-head approval/no-change verdict through the existing authorized review path. Do not self-approve on behalf of the PR author, weaken gates, force-push, create another PR, or transfer predecessor evidence.