pedwfrontend/docs/administrative-authentication.md

Administrative authentication foundation

Stage 1 scope

This foundation is independent of NextAuth, Prisma, CRM, the existing /admin page restriction, and draft deletion. It provides shared-credential login, logout, and session-status API handlers only. It is not wired into /admin or any storage API in this stage.

Required server-side configuration

The deployment must provide all of the following server-side values:

• ADMIN_AUTH_SECRET: a unique high-entropy administrative passphrase of at least 32 characters.
• ADMIN_SESSION_SECRET: a different unique high-entropy signing key of at least 32 characters.
• NEXTAUTH_URL: the existing canonical application URL. Administrative login and logout compare the request Origin with this server-configured origin.

The administrative values must never use a NEXT_PUBLIC_ prefix or be exposed to browser JavaScript. Do not commit real values. Missing, short, or identical administrative secrets fail closed.

Security properties and limitations

• Credentials are derived with Node scrypt and compared with timingSafeEqual.
• Sessions are stateless, versioned HMAC-SHA256 tokens with a 20-minute fixed lifetime and a random nonce.
• The cookie is HttpOnly, SameSite=Strict, scoped to /, explicitly expires, and is Secure in production.
• Login and logout require an exact same-origin Origin match against NEXTAUTH_URL; missing or malformed origins fail closed.
• Authentication responses use Cache-Control: no-store.
• Logout clears the browser cookie. Because sessions are stateless, a stolen token can remain valid until its short expiry; later protected routes must continue verifying signature and expiry on every request.
• This is shared-credential authentication. A valid token proves knowledge of the shared credential, not the identity of a named administrator.

Deployment requirements before production use

The repository does not provide a demonstrated distributed rate-limit service. Administrative login must therefore be protected by an ingress, gateway, WAF, or shared backing service that enforces rate limits consistently across all deployed instances. A process-local limiter is intentionally not used because it would reset on restart and could be bypassed across instances.

The deployment must also ensure NEXTAUTH_URL is the correct canonical HTTPS origin. Login and logout intentionally do not derive trust from Host or forwarding headers.

Any future administrative state-changing API must require more than possession of the cookie: it must independently validate the administrative session and enforce same-origin/CSRF protection before performing side effects.