ci(security): govern CodeQL source boundaries

[ty-everett]

Program linkage

Advances the final CodeQL security-extended follow-up in #324.

Summary

• add an advanced CodeQL workflow with the same required check names, three analyzed languages, security-extended suite, remote threat model, and PR/push/weekly coverage as current default setup
• exclude only generated paths already owned in governance/repository-health/projects.json
• make repository controls fail if generated ownership and CodeQL exclusions drift or if languages/events/permissions/query coverage/check names are weakened
• document the scanner boundary and cutover procedure
• characterize the intentionally public BRC-104 handshake route with exact-match and signed-general-dispatch regression tests

Why advanced setup

Default setup cannot apply a repository-owned paths-ignore list. The three remaining generated findings (#168, #169, #183) are inside the checked-in JSight OpenRPC HTML export, whose source contract and generator boundary are already owned. Hand-editing its vendored JavaScript would be non-durable and would recur on regeneration. Advanced setup provides the precise exclusion mechanism while preserving analysis coverage.

The only non-generated alert, #165, treats the public /.well-known/auth handshake selector as a user-controlled bypass. BRC-104 must expose that endpoint before a session can exist; it handles the authentication protocol, not protected application content. All non-handshake traffic still takes signed general-message validation or the explicit allowUnauthenticated policy. New tests prove exact path matching and the signed-request-ID dispatch boundary. After merge and a clean rescan, #165 will receive an evidence-backed false-positive disposition if CodeQL retains it.

Safe cutover

CODEQL_ADVANCED_ENABLED exists as a repository variable and is currently false, so this review PR cannot upload concurrently with default setup. After merge:

1. set the variable to true;
2. disable default setup;
3. dispatch this workflow on main;
4. verify all three language jobs, required contexts, and the alert delta;
5. restore default setup immediately if advanced analysis does not validate.

Coverage preserved

• Analyze (actions)
• Analyze (javascript-typescript)
• Analyze (python)
• security-extended queries (includes the default suite)
• PRs targeting main, every main push, weekly schedule, and manual dispatch
• pinned CodeQL Action v4.37.3
• least-privilege security-events: write job permission and read-only repository/package/action permissions

Verification

• pnpm health:check — 14/14 zero-install controls; 37 projects; 30 public packages; 242 findings; 6 active exceptions; 0 control errors
• pnpm --filter @bsv/auth-express-middleware lint — no errors (7 pre-existing warnings)
• pnpm --filter @bsv/auth-express-middleware build
• pnpm --filter @bsv/auth-express-middleware test:coverage — 3 suites / 31 tests
• pnpm --filter docs-site validate — 93 frontmatter files and links valid
• docs manifest generation — 93 pages, unchanged output
• git diff --check

Compatibility and release impact

No runtime route, authentication policy, public API, CORS, CSP, origin, credential, or service-edge behavior changes. No package is published by this PR. The accumulated @bsv/auth-express-middleware@2.2.0 candidate already includes the documentation-only source clarification and tests; no additional bump is proposed.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ty-everett]

Final pre-cutover verification is complete at fbbb5ab271c58234e0d4a793a27c8f7037437f74.

• 30 checks passed; the only skipped job is the intentionally gated advanced workflow while CODEQL_ADVANCED_ENABLED=false;
• current default setup supplied passing actions, JavaScript/TypeScript, and Python security-extended analyses;
• direct CodeQL PR query: 0 open alerts;
• direct Sonar PR queries: 0 open/confirmed issues and 0 hotspots to review;
• review state: 0 unresolved threads and 0 requested reviewers;
• Auth build and 31 tests passed; repository controls passed 14/14 without dependency installation;
• no runtime auth policy, public API, CORS/CSP, origin/credential, or service-edge behavior changed;
• no npm publication occurred.

GitHub reports only REVIEW_REQUIRED; the author cannot self-approve. Per repository policy and #324, this is ready for the authorized administrator merge and documented CodeQL cutover.