Instruction file imported from hupe1980/krafka (.github/instructions/auth.instructions.md). Copyright stays with the author.

Auth Module Rules

Credential Safety (Non-Negotiable)

• Every field holding a secret (password, secret_access_key, session_token, token_value, salted_password, server_signature) must derive Zeroize + ZeroizeOnDrop.
• All credential structs must override fmt::Debug to print [REDACTED] instead of the secret.
• Never log credentials at any level — not even debug! or trace!.
• Temporary buffers containing secrets (e.g., SASL auth bytes) must be wrapped in Zeroizing<Vec<u8>>.

When adding a new auth mechanism or field that holds sensitive data, verify all four rules above.

SCRAM State Machine

States: Initial → WaitingServerFirst → WaitingClientFinal → WaitingServerFinal → Complete | Failed

• Invalid transitions must set state = Failed immediately — never silently ignored.
• Iteration count bounds: min 4096, max 1,000,000 (prevents downgrade and DoS).
• Server nonce must start with client nonce (validated, not assumed).
• Signature verification uses subtle::ConstantTimeEq — never use == for HMAC comparison.

TLS

• rustls only (no OpenSSL / native-tls).
• Insecure mode (verify_server_cert = false) is a runtime opt-in: no compile-time feature gate is required. Setting the flag emits a warn! log and uses NoServerCertVerifier — intended only for local development / testing. For production, use with_ca_cert().
• File I/O for certs: use build_tls_config() (async, wraps sync impl in a single spawn_blocking). The sync build_tls_config_sync is private and used only in tests. ConnectionConfig::init_tls() caches the built TlsConnector so cert files are read once, not per-reconnection.
• SNI hostname extraction must handle IPv6 brackets ([::1]:9092).

General Auth Patterns

• Auth mechanisms use enum dispatch (no trait objects).
• All auth errors are KrafkaError::auth(message) — no custom auth error variants.
• Auth failures are not retried internally; the network layer handles reconnection.
• AWS MSK IAM signing uses system clock — no built-in skew tolerance.