Security hardening from suite audit: RFC 3161 verification, keyed audit chain, XFF + return-url

[DrBaher]

Findings from an audit of the contract-ops CLI suite. A companion PR covers contract-ops-mcp.

Landed

P0 — RFC 3161 timestamp tokens are now cryptographically verified

inspectTimestampResponse trusted any response whose PKIStatus byte was 0/1 and did an unsigned byte-search for the digest; the TSA's CMS signature was never checked and the default TSA URL was plaintext http. A network attacker could substitute the entire "proof". New timestamp-verify.ts performs full CMS SignedData verification (RFC 5652 / RFC 3161):

• verifies the TSA signature over TSTInfo with the signer cert's public key (Node crypto.verify + X509Certificate, no hand-rolled signature math);
• requires the signer cert to carry extendedKeyUsage = id-kp-timeStamping;
• confirms the token's messageImprint equals the digest we asked to be stamped (a valid token over different data is rejected);
• checks the signed messageDigest == hash(TSTInfo) and contentType == id-ct-TSTInfo;
• optional trust-anchor chaining.

cryptographicallyVerified is now the authoritative signal and is persisted into the audit.timestamped / audit.anchored events. issueRfc3161Timestamp refuses non-HTTPS TSA URLs (localhost / SIGN_ALLOW_INSECURE_TSA=1 excepted for test mocks); default TSA is https. Tested against a real OpenSSL-issued token (committed under fixtures/rfc3161/) across valid / wrong-digest / trust-anchor / tampered / status-only cases.

P1 — Optional keyed-HMAC audit chain

The chain was unkeyed SHA-256, so anyone with DB-file write access could recompute a self-consistent forged chain. Added opt-in HMAC keying (SIGN_AUDIT_HMAC_KEY / SIGN_AUDIT_HMAC_KEY_FILE), keyed by material held outside the DB. Backward-compatible (existing chains hash identically and keep verifying; each row records its hash_algo), fail-closed (a keyed chain can't pass without the key), and downgrade-resistant (a legacy row after a keyed one is flagged as tampering). Threaded through the sync + async (Postgres) paths, both schemas (+ migrations), and the portable receipt-bundle verifier.

P1 — sign serve rate limiter no longer trusts X-Forwarded-For by default

XFF is client-controlled, so it could be rotated per request to defeat the limiter. Now keys on the socket peer address unless sign serve --trust-proxy true.

P2 — Optional return-url host allowlist

validateReturnUrl accepted any https host; an agent could steer the signer's post-sign redirect anywhere. Added opt-in SIGN_RETURN_URL_ALLOWED_HOSTS.

P3 — --version drift (0.6.4 → 0.6.5)

Tests

Build + typecheck pass. Full suite: 782 pass, 1 skip, 0 fail (was 766 before this PR; +16 new tests).

Reported but intentionally not changed here (flagged for your call)

• Webhook ingest-before-verify: I verified the actual behavior — state mutations (persistRequestProviderMetadata, recordSignerSigningState) are already gated behind if (verified), and an existing test (webhook-replay-protection.test.ts:149) deliberately pins "unverified replays still recorded as failures". The residual is audit-log injection (an unauthenticated caller who knows a request_id can append verified:false events), which contradicts that test. It's an architectural decision, so I left it for you rather than flip a documented behavior.
• Trust-label spoofing (classifyTrust): the labels are explicitly documented as descriptive, not enforced; a robust fix needs pinning the local CA's public key (a larger change). Left as-is.
• createSigningRequest path confinement: attempted as defense-in-depth but it broke legitimate absolute-path callers (MCP/bulk/tests use absolute temp paths); the correct boundary is the CLI/MCP entry layer, where confinement already exists. Reverted.
• sign/decline lifecycle + audit append not wrapped in a transaction (P2) — not addressed in this PR.