Quality backlog from 2026-07 audit: untested paths, typed HTTP errors, config validation, release hygiene

[kurok]

Low-priority follow-ups from the 2026-07 repository audit, collected in one place. None of these block the other audit issues (#104, #105, #106, #107, #108, #109, #110); pick them up opportunistically or when touching the surrounding code.

Untested paths

• VaultKubernetesAuth: fs.readFileSync throw path (missing/unreadable service-account token file — the most realistic real-world failure)
• VaultIAMAuth: default AWS credential-chain path (construction without explicit credentials) is never invoked in tests
• test/auth.base.test.mjs "reschedules when a renewal fails": assert the timer actually re-arms
• Prototype-pollution guard in VaultNodeConfig.deepMerge — a deliberate security control with zero test coverage
• Dedicated Lease.getMetadata() test
• VaultApiClient non-2xx handling: assert err.error contents and the non-JSON-body fallback

Code quality

• Wrap HTTP errors in the VaultError hierarchy — VaultApiClient currently throws a plain Error with ad-hoc .statusCode/.error, so callers cannot instanceof-check HTTP failures. Keep the existing field shape for compatibility.
• Validate required config fields (role, role_id, …) consistently across auth backends — only VaultTokenAuth validates its input today. Note: stricter validation is a behavior change; flag as a minor bump.
• VaultBaseAuth.__authToken holds either a Promise<AuthToken> or a resolved AuthToken, discriminated by instanceof — consider separating into two fields for clarity.

Dependencies & release process

• long-timeout@0.1.1 is unmaintained (last release 2016, ~50 LOC): document the decision to keep it, or inline the code
• Add a release-time check that CHANGELOG.md was updated (currently manual and unenforced)
• Structured logging + log-at-source in VaultApiClient — do this after the catch/log/rethrow wrapper from Refactor: unify the 4x copy-pasted request pipeline in VaultClient #110 to avoid double-logging

Considered and rejected (do not build)

Generic middleware/plugin chain for the request pipeline; a generic secret-scrubbing log framework; TTL-based mount re-detection; aspirational coverage targets; README TOC generation tooling. The codebase is ~1.9k LOC — bespoke abstractions cost more than the duplication they remove.

---

Filed from the 2026-07-02 repository audit of commit 4225f9b.

[kurok]

Closing as completed — all actionable items landed:

• Untested paths (all 6: VaultKubernetesAuth fs-throw, VaultIAMAuth default cred-chain, renewal-reschedule re-arm assertion, VaultNodeConfig.deepMerge prototype-pollution guard, Lease.getMetadata(), VaultApiClient non-2xx handling) — done in chore: quality backlog from the 2026-07 audit (typed HTTP errors, config validation, untested paths, release hygiene) #119.
• Typed HTTP errors (VaultHttpError) and consistent auth config validation — chore: quality backlog from the 2026-07 audit (typed HTTP errors, config validation, untested paths, release hygiene) #119.
• long-timeout keep-decision documented and release-time CHANGELOG check — chore: quality backlog from the 2026-07 audit (typed HTTP errors, config validation, untested paths, release hygiene) #119.
• Structured logging / log-at-source in VaultApiClient — its prerequisite Refactor: unify the 4x copy-pasted request pipeline in VaultClient #110 is completed (via refactor: unify the request pipeline in VaultClient #118), and VaultApiClient now takes an injected _logger and logs at source with a deliberate "never log response bodies / secret material" guard.
• "Considered and rejected (do not build)" items — N/A by design.

The one remaining item — the VaultBaseAuth.__authToken promise/token two-field split — was an explicitly optional, no-behavior-change clarity refactor. Split out into its own low-priority issue #120 rather than keeping this whole backlog open for it.