ACCESS_CODE site-level authentication for shared deployments

[YizukiAme]

Motivation

Ref: #287

When deploying OpenMAIC on Vercel for a class or research group, deployers need a way to restrict site access without exposing their LLM API keys. Currently, the codebase does not implement CODE / ACCESS_CODE / HIDE_USER_API_KEY — the environment variables are silently ignored, leaving deployments open to anyone with the URL.

A teacher in #287 is trying to share a deployment with 700 students(——wow!) while keeping their DOUBAO_API_KEY safe. Without access control, anyone can consume their API quota.

Proposed Solution

A zero-dependency, purely additive access-code gate using Next.js 16's proxy.ts:

Architecture

User → proxy.ts → Has valid cookie? → Yes → App
                                    → No  → /auth (password page)
                                           → POST /api/auth/login
                                           → Set HttpOnly signed cookie → App

New files (no changes to existing code)

File	Purpose
proxy.ts	Intercept all requests; redirect unauthenticated users to /auth; return 401 for API calls
lib/server/access-auth.ts	HMAC cookie signing/verification via Web Crypto (no deps)
app/api/auth/login/route.ts	Verify access code, set HttpOnly cookie
app/api/auth/logout/route.ts	Clear cookie
app/auth/page.tsx	Simple password input page

Environment variables

Variable	Required	Description
ACCESS_CODE	Yes	The password users must enter (CODE also supported as alias)
AUTH_SECRET	Yes	Random string (≥32 chars) for HMAC cookie signing
AUTH_TTL_HOURS	No	Cookie lifetime, default 12h

Key design decisions

1. Purely additive — zero modifications to existing files; if ACCESS_CODE is not set, behavior is identical to today
2. No dependencies — uses Web Crypto API (available in Vercel Edge Runtime)
3. HttpOnly + HMAC-signed cookie — prevents tampering, not accessible to client JS
4. Separation of concerns — the access code never touches the API key flow; it's a site-level gate only

What this does NOT solve (yet)

The deeper issue from #287 — when HIDE_USER_API_KEY=true and a server-side provider key is configured, client-submitted apiKey should be ignored in resolve-model.ts. This requires changes to existing code and is a separate concern. Happy to tackle it as a follow-up if maintainers agree on the approach.

Questions for Maintainers

1. [MAJOR] Does this align with the project's roadmap? We'd love to hear whether site-level access control is something the team considers worth supporting, or if shared deployments are out of scope for now.
2. Is this the right scope? Or would you prefer a more comprehensive auth system (e.g., multi-user, token-based)?
3. i18n: The auth page needs user-facing strings — should I add them to the existing messages/ structure? Which locales are required at minimum?
4. Cookie name: I'm using openmaic_auth — any naming convention to follow?
5. Follow-up PR for API key isolation: Should I file a separate issue for the resolve-model.ts changes?

Happy to implement this if the approach looks good.

---

Related: #287

[motowntek]

I think this is an essential feature. I am hoping to also use this for some adult education courses we will be offering.

[wyuc]

Thanks for the thorough RFC! We've included ACCESS_CODE in the v0.1.1 roadmap (#406).

We're going with a simpler variant: Next.js middleware + simple session cookie instead of proxy.ts + HMAC. Same goal, less moving parts.

On your questions:

1. Roadmap — Yes, in scope for v0.1.1.
2. Scope — Site-level password gate only. Multi-user auth is deferred.
3. i18n — New locale JSONs (lib/i18n/locales/*.json), minimum en-US + zh-CN.
4. Cookie name — openmaic_access is fine.
5. API key isolation — Please file a separate issue.

Happy to have your help on the implementation — feel free to open a PR.