Add independent administrative authentication foundation
This commit is contained in:
@@ -0,0 +1,56 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user