Password Protection

Overview

The starter includes an application-level password gate that runs at the start of the proxy pipeline.

When enabled, unauthenticated requests are redirected to /password, and successful verification sets an HTTP-only cookie used for subsequent access.

Key implementation paths:

• apps/web/config/password-protection.ts
• apps/web/src/features/password-protection/server/proxy/password-proxy.ts
• apps/web/src/features/password-protection/server/api/passwordProtectRoute.ts
• apps/web/src/app/(password-protection)/api/password-verify/route.ts
• apps/web/src/proxy.ts

How it works

1) Enable or disable with environment variables

Password protection is active only when PASSWORD_PROTECTION is set.

• PASSWORD_PROTECTION: shared password for site access
• PASSWORD_PROTECTION_BYPASS: optional secret for automation bypass

If PASSWORD_PROTECTION is not set, the proxy gate exits early and requests continue normally.

2) Proxy-level request gating

passwordGateProxy runs first in apps/web/src/proxy.ts, before transliteration, site setup, redirects, and CSP.

For each request it:

• skips protection for configured paths (/password, /api)
• allows bypass when the request contains the configured bypass header/query value and it matches PASSWORD_PROTECTION_BYPASS
• allows access when the auth cookie value equals PASSWORD_PROTECTION
• otherwise redirects to /password and preserves the original path in redirectTo

3) Password verification and cookie issuance

POST /api/password-verify is wired to passwordProtectRoute.ts.

On successful password validation, it sets:

• cookie name: password-protection-site-access
• httpOnly: true
• sameSite: 'lax'
• secure: process.env.NODE_ENV === 'production'
• max age: 7 days

It also sanitises redirectTo so only safe relative paths are accepted.

Practical usage notes

• This is a single shared site password (not per-user authentication).
• API routes are intentionally excluded from the proxy gate (/api in skip paths).
• The proxy matcher also excludes common static and asset routes, so static files are not gated by this mechanism.
• For CI or synthetic checks, use the bypass mechanism only when PASSWORD_PROTECTION_BYPASS is configured.