Security & Reliability

Production Guarantees & Known Degradations

Transparency about what HAIEC guarantees in production and known limitations.

Last updated: January 2026 | Schema Version: 2

Fail-Closed Guarantees

Redis Required for /api/verify

Enforced

The verification endpoint requires Redis for both nonce replay protection and rate limiting. If Redis is unavailable, the endpoint returns 503 with no signature emitted.

Error code: REPLAY_PROTECTION_UNAVAILABLE or RATE_LIMIT_SERVICE_UNAVAILABLE

Strict Whitelist Sanitization

Enforced

Public verification responses use a strict whitelist of allowed fields. Only explicitly approved fields are included, preventing accidental leakage of internal data.

Error code: N/A - fields are silently excluded

Test Keys Rejected in Production

Enforced

Signatures created with CI/test signing keys are automatically rejected in production mode. This prevents accidental use of test credentials.

Error code: Signature was created with a test/CI key

Nonce Replay Protection

Enforced

Each verification response includes a unique nonce stored in Redis with TTL. Replayed requests are detected and rejected.

Error code: Nonce already used - possible replay attack

Key Rotation Support

HAIEC supports seamless key rotation with multiple active keys:

  • 1.HAIEC_SIGNING_KEY - Primary key for new signatures
  • 2.HAIEC_SIGNING_KEY_PREVIOUS - Previous key (still valid for verification)
  • 3.HAIEC_SIGNING_KEY_LEGACY - Legacy key (extended grace period)

Key ID derivation: First 8 characters of SHA-256 hash of key material. This ensures keyId is deterministic and stable across deployments.

State Machine Integrity

HAIEC includes a periodic FSM bypass detector that scans for illegal state transitions:

CRITICAL

Auto-revoke artifact

HIGH

Flag for review

MEDIUM

Log only

Alert-Only Mode Available

Set HAIEC_FSM_ALERT_ONLY=true to prevent auto-revocation during initial rollout.

Known Degradations

Redis Unavailable

high

Impact: Verification endpoint returns 503

Mitigation: Retry after 30 seconds. Redis typically recovers within 1-2 minutes.

HMAC vs Asymmetric Signatures

medium

Impact: Third parties cannot independently verify signatures

Mitigation: Verification requires calling HAIEC endpoint. Ed25519 upgrade planned.

Multi-Instance Nonce Race

low

Impact: Extremely rare: parallel identical requests may both succeed

Mitigation: Redis SETNX provides atomic nonce consumption. Window is <1ms.

CI Enforcement

The following tests run on every PR and push to main:

  • npm run test:integrity - All integrity tests
  • npm run test:adversarial - Adversarial audit tests
  • npm run test:fingerprint - Fingerprint golden vectors
  • npm run test:verifier - Verifier endpoint smoke test

Build fails if fingerprint output changes without schema version bump.

Schema Versions

Fingerprint Schema

v2

Signature Algorithm

v1 (HMAC-SHA256)

View Full Documentation →