mcp-auth-template CLAUDE.md

Repository conventions

Guidance for AI agents and humans working in this repository. These are rules that have already caused bugs when broken, not stylistic preferences.

Security

Constant-time comparison is targeted, not blanket. It is for comparing a genuine secret against attacker-controlled input. That is:

• src/auth/client-secret.ts — OAuth client secrets, compared as scrypt-derived keys via crypto.timingSafeEqual. This is the primary path.
• src/util/safe-compare.ts — timingSafeEqualString, used by StaticTokenVerifier for the dev/CI shared-secret mode.

Secrets are additionally never stored recoverably: CLIENT_SECRETS holds scrypt hashes, never secrets. Hashing and constant-time comparison are independent requirements — hashing alone still leaks through a naive === on the digest, and constant-time comparison alone still loses the secret to a config dump.

An unregistered client is verified against a decoy hash so it costs the same as a real one. Without that, the token endpoint is an oracle for which client_ids are registered.

Do not extend it to:

• JWT signature verification — jose already does this correctly. Wrapping it is a downgrade.
• Issuer, audience, scope or client_id comparisons — none are secrets. A timing oracle on a value the attacker already knows reveals nothing.

Applying it everywhere is cargo cult and obscures where the real boundary is. If you add a new secret comparison, use it there and say why in a comment.

Never early-return on length when comparing secrets. if (a.length !== b.length) leaks the secret's length, and crypto.timingSafeEqual throws on mismatched lengths. HMAC both sides first — that is what safe-compare.ts does.

Failure responses must be uniform. Expired, wrong-audience and bad-signature all collapse to one invalid_token message. There is a test asserting the responses are byte-identical. Do not add a helpful error that distinguishes them.

Never log secrets. Not tokens, not assertions, not API keys, not config values. Config validation errors name the offending variable, never its value.