security: HMAC signature verification on token validate path (Step 1 — shadow mode)

[chitcommit]

Summary

Step 1 of #4. Adds HMAC signature verification to TokenManager.validate() running in shadow mode (logs mismatches, does not reject). Step 2 will flip enforcement and update SECURITY.md / CHARTER.md.

Why

Today validate() looks up tokens by SHA-256 hash and trusts the row it gets back. The HMAC signature embedded in the wire token is generated at issue time but never re-checked at validate time. That means a D1 compromise alone (SQL injection, leaked credentials, lost backup) is enough to mint forged tokens — an attacker who can write a row whose token_hash, chitty_id, scope, and service_name they control can produce a matching plaintext token that the validator accepts. Verifying the signature raises the bar to "compromise D1 and steal the signing key", restoring the defense-in-depth the HMAC was always meant to provide.

This is documented as Known Limitation #3 in SECURITY.md and tracked as #4.

Changes

• src/token-manager.js
  • New verifySignature(token, chittyId, service, expectedTokenId) helper. Rebuilds the canonical payload (chittyId/service come from the looked-up record — they are HMAC-committed, not in the wire token), peels the fixed-length 32-char base64url signature suffix, timing-safe compares. Never throws; returns false on any malformed input. Gotcha noted inline: base64url alphabet contains _, so the body cannot be split('_') — we right-peel by length instead.
  • validate() now calls verifySignature AFTER lookup, BEFORE expiry. Shadow mode by default: writes a signature_mismatch audit event but still returns valid. Enforce mode requires env.CHITTYAUTH_VERIFY_SIGNATURE === 'enforce' exactly — typo-safe so 'true'/'1' stay in shadow.
  • provisionToken INSERT now writes service_name so the column is available for signature reconstruction at validate time. (Schema already had the column; the INSERT was just dropping it.)
• tests/token-manager.test.js — 29/29 passing, no mocks. Coverage:
  • Helper unit tests: happy path, single-byte mutation in each segment (sig/tokenId/timestamp), wrong chittyId/service in reconstruction, malformed body, null inputs, signature-length guard, 200-token reliability sweep (catches base64url-underscore split regressions).
  • Validate-path integration: shadow tampering still validates but emits signature_mismatch; enforce mode rejects with 'Invalid token signature' and emits both signature_mismatch + token_validation_failed; D1 fallback path exercises the new service_name INSERT; refresh chain works end-to-end under enforce.
• plans/validate-signature-verification/{plan.md,implementation.md} — design + step-by-step rationale.

Why shadow first

If a deployment has been silently using the dev fallback signing key (#5), flipping enforcement immediately invalidates every outstanding token at deploy. Shadow lets operators see the real-world mismatch rate before flipping. Step 2 PR will land enforce + doc updates, gated on this soak.

Test plan

• npm test — 29/29 passing
• No vi.mock / jest.mock on DB or service modules (per global no-mocks rule)
• Tamper-by-one-byte tests fail without verifySignature, pass with it
• Forged-record path: tests construct a token with a different signing key and confirm it's rejected under enforce
• Smoke test against wrangler dev --local after merge before Step 2
• Operator soak in shadow mode → confirm signature_mismatch rate is ~0 before Step 2 enforce flip

Related

• Refs security: enforce HMAC signature verification on token validate path #4 (this issue)
• security: fail closed when signing-key secrets are unset (no hardcoded dev fallback) #5 — fail-closed signing key (recommended to land before Step 2 enforce flip)
• config: resolve wrangler.toml / package.json drift (chittyauth-app vs auth.chitty.cc) #6 — wrangler/package drift (independent)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8b4b306f-67b8-4cc3-80a1-1f8c0889dea5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

✅ Unit Test PR creation complete.

• Create PR with unit tests
• Commit unit tests in branch fix/validate-signature-verification

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Note

Unit test generation is a public access feature. Expect some limitations and changes as we gather feedback and continue to improve it.

---

Generating unit tests... This may take up to 20 minutes.

[coderabbitai]

✅ Created PR with unit tests: #8