feat: ACCESS_CODE site-level authentication (#407)

[wyuc]

Summary

• Add ACCESS_CODE env var that gates access to the entire app
• When set, unauthenticated users see a full-screen password modal and cannot call APIs
• When not set, zero behavioral change

How it works

1. Next.js middleware checks all requests for a valid openmaic_access cookie
2. First-time visitors see a full-screen modal prompting for the access code
3. Code is verified server-side via /api/access-code/verify, which sets an HMAC-signed HttpOnly cookie (7-day TTL)
4. All subsequent requests (including API calls) are validated by verifying the HMAC signature in the cookie
5. If ACCESS_CODE is not set, middleware exits immediately — zero overhead

New files (10)

File	Purpose
middleware.ts	Gate all requests, validate HMAC-signed cookie
app/api/access-code/verify/route.ts	POST: validate code, set signed cookie
app/api/access-code/status/route.ts	GET: return {enabled, authenticated}
components/access-code-guard.tsx	Layout wrapper: fetch status, show/hide modal
components/access-code-modal.tsx	Full-screen password gate with motion animations

Modified files

• app/layout.tsx — wrap children with <AccessCodeGuard>
• .env.example — add ACCESS_CODE
• lib/i18n/locales/*.json (4 files) — add accessCode.* translation keys (en-US, zh-CN, ja-JP, ru-RU)

Security

• Cookie value is timestamp.HMAC-SHA256(ACCESS_CODE, timestamp) — never the plaintext code
• Middleware validates HMAC signature on every request (not just cookie existence)
• Access code comparison uses constant-time comparison (timingSafeEqual)
• Middleware uses Web Crypto API for Edge Runtime compatibility
• HttpOnly + SameSite=Lax cookie
• Threat model: prevent casual unauthorized access to shared deployments. Not enterprise security.

Code Review Summary

Reviewed by automated code reviewer. All Critical and Important findings addressed:

Severity	Issue	Resolution
Critical	Cookie only checked for existence, not validated	HMAC-signed tokens + middleware validation
Critical	Timing attack on string comparison	timingSafeEqual in verify endpoint
Important	Middleware 401 missing errorCode	Added to match apiError shape
Important	Status endpoint not using apiSuccess	Fixed
Important	Dead accessCode.submit i18n key	Removed from all 4 locales
Suggestion	Guard renders null during loading (white flash)	Now renders children, modal overlays on top
Suggestion	Network error silently disables access control	Defaults to enabled: true on error
Fix	Node.js crypto not available in Edge Runtime	Replaced with Web Crypto API

Test plan

• Set ACCESS_CODE=test123 in .env.local, start dev server
• Visit app → full-screen modal appears
• Enter wrong code → inline error message
• Enter correct code → modal dismisses, app works
• Refresh page → no modal (cookie persists)
• curl /api/verify-model without cookie → 401
• Remove ACCESS_CODE from env, restart → no modal, all APIs work
• Verify dark mode renders correctly

Closes #407
Related: #287, Discussion #293, Roadmap #406

🤖 Generated with Claude Code

[cosarah]

LGTM! Clean architecture and solid security fundamentals (HMAC-signed tokens, timingSafeEqual, httpOnly/secure cookies, fail-closed error handling).

Two minor notes for awareness (non-blocking):

1. Token has no server-side expiry check — the HMAC verification only validates the signature, not the timestamp age. The cookie maxAge handles this in practice, but an extracted token would remain valid indefinitely as long as ACCESS_CODE stays the same.

2. Duplicate HMAC verification logic — verify/route.ts (Node crypto) and middleware.ts (Web Crypto API) implement the same token verification independently. Necessary for Edge Runtime compatibility, but worth keeping in mind if the token format ever changes.