refactor: throw CodexValidationError from rotation-proxy startup guards - #586

Summary

• First slice of the audit's §4.3 error-contract adoption (finding M11): the two startup guards in startRuntimeRotationProxy now throw CodexValidationError with machine-readable metadata instead of bare Error, and the guarantee is documented in docs/reference/error-contracts.md.

What Changed

lib/runtime-rotation-proxy.ts — two conversions, messages byte-identical:

• The loopback-only host refusal (runtime-proxy-01 defense) throws CodexValidationError with field: "host", expected: "a loopback host", and the offending host in context.host.
• The missing-clientApiKey check throws CodexValidationError with field: "clientApiKey", expected: "a non-empty string".

Since messages are unchanged, every existing message-matching caller and test (rejects.toThrow("clientApiKey"), /non-loopback/i, /loopback-only/i) passes untouched; callers gain instanceof CodexValidationError and the stable CODEX_VALIDATION_ERROR code.

docs/reference/error-contracts.md — new "Typed Error Classes" section: lists the lib/errors.ts hierarchy and records the startup-guard guarantee, so the contract doc is backed by machine-readable types as §4.3 intended. It sits next to the existing note that the dual-call helpers deliberately throw native TypeError (that convention is unchanged).

test/runtime-rotation-proxy.test.ts — one new test capturing both guard rejections and asserting the class, field, and context payloads.

Scope Note

The three remaining bare throws in lib/config.ts (Aborting config save because … is unreadable.) are deliberately deferred: one of them sits inside the ESTALE CAS block that open PR #585 rewrites, and converting them now would make my own two open PRs conflict. They'll be a tiny follow-up once #585 merges. After that, the three files §4.3 names carry no bare throws (fetch-helpers already has none — it returns mapped Responses by design).

Validation

• npm run typecheck (also in the pre-commit hook)
• npx eslint lib/runtime-rotation-proxy.ts test/runtime-rotation-proxy.test.ts --max-warnings=0
• npm test -- test/runtime-rotation-proxy.test.ts — 77 passed; the only 2 failures are the documented IPv6-disabled-container baseline names (EAFNOSUPPORT ::1, both present verbatim in docs/audits/evidence/test-baseline-2026-06-10.txt)
• npm run build deferred to CI

Docs and Governance Checklist

• docs/reference/error-contracts.md updated in the same PR as the behavior it documents
• No user-visible message, command, or path changed; CodexValidationError extends CodexError extends Error, so all instanceof Error handling is unaffected

Risk and Rollback

• Risk level: low — error class tightened, message and throw conditions identical. The only observable difference is richer metadata on the error object.
• Rollback plan: revert the single commit.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

tightens the two startup guards in startRuntimeRotationProxy from bare Error to CodexValidationError with machine-readable field, expected, and context fields, and documents the contract in error-contracts.md. messages are byte-identical, so all existing message-matching callers and tests are unaffected.

• lib/runtime-rotation-proxy.ts: host and clientApiKey guards now throw CodexValidationError; callers gain instanceof branching and the stable CODEX_VALIDATION_ERROR code.
• test/runtime-rotation-proxy.test.ts: new test covers both guards end-to-end, asserting field, expected, and context payloads.
• docs/reference/error-contracts.md: new "Typed Error Classes" section records the error hierarchy and the startup-guard guarantee.

Confidence Score: 5/5

safe to merge — error class tightened, throw conditions and messages unchanged, backward-compatible via inheritance

both guards are narrow, deterministic throws at startup; the change only adds metadata to the thrown object. CodexValidationError extends CodexError extends Error, so all instanceof Error and message-matching paths in existing callers and tests continue to work. the new test fully covers field, expected, and context for both guards.

no files require special attention

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[startRuntimeRotationProxy called] --> B{isLoopbackHost host?}
    B -- no --> C[throw CodexValidationError\nfield: host\nexpected: a loopback host\ncontext: host]
    B -- yes --> D{clientApiKey non-empty?}
    D -- no --> E[throw CodexValidationError\nfield: clientApiKey\nexpected: a non-empty string]
    D -- yes --> F[continue startup…]

_{Reviews (2): Last reviewed commit: "test: assert the expected field from bot..." | Re-trigger Greptile}