Administrative authentication foundation

Administrators sign in at /admin/login using the shared credential configured as ADMIN_AUTH_SECRET. The page submits the credential directly to POST /api/admin/auth/login; it does not place the credential in a URL or store it in browser storage.

Successful authentication creates the administrative session cookie and sends the browser to /admin. The /admin server-side loader validates that cookie before loading administrative data. A valid session is not sufficient by itself: the existing /admin IP allowlist remains an additional restriction, and a valid administrator outside the allowed network is sent to /403.

The administrative interface provides a Sign out control which calls POST /api/admin/auth/logout, clears the cookie, and returns the browser to /admin/login. Sessions expire after 20 minutes and expired, invalid, or missing sessions are redirected to the login page.

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.
Protecting /admin prevents its server-side Prisma, storage, and CRM data loading from running without a valid administrative session. It does not by itself protect browser-addressable API routes.

Administrative API protection limitations

The current administrative UI directly uses API routes that do not yet enforce the administrative session, including:

/api/admin/getnewappeals_api
/api/admin/getlatestdocuments_api
/api/admin/getStatusCountsByAppeal_api
/api/admin/getStatusCountsByAppealAndLPA_api

The appeals and documents routes expose paging operations used after the page has loaded. The status routes expose administrative dashboard reads. These routes retain their existing relay token and HMAC behaviour but have no independent administrative-session authorization. A later authorised stage must enforce the administrative session on privileged API routes and account for both browser calls and the existing server-side bootstrap callers.

Storage download and queue actions retain their existing authorization behaviour. The other administrative API and storage limitations described in this section remain open.

Directly observed storage routes include:

/api/file/getrepsblobproxy, which forwards a caller-supplied container using server relay credentials and path signing.
/api/file/downloadblob and /api/file/createrepcompletemessage_api, which enforce existing path-HMAC checks but not administrative authorization.

Stage 3 deletion controls

Ordinary case and representation deletion through /api/file/deleteblobcase and /api/file/deleteblobrep now requires a valid NextAuth session whose user ID matches the requested Azure container. The existing signed-query/HMAC check also remains required. Requests that fail ownership or HMAC validation are rejected before the Azure storage deletion operation is called.

Ordinary JSON and multipart uploads through /api/file/upload and /api/file/uploadsinglefile independently require a valid NextAuth session whose user ID exactly matches the submitted containerID. The existing upload HMAC remains mandatory. Missing or unusable sessions, cross-container requests, and invalid HMACs are rejected before file processing or Azure storage writes.

Administrative cross-container representation deletion uses the dedicated POST /api/admin/deleteblobrep route. That endpoint independently validates the administrative session and requires a trusted same-origin request. It also validates the requested container, case-folder segment, and representation-file segment before performing deletion.

Administrative cross-container case deletion uses the dedicated POST /api/admin/deleteblobcase route. That endpoint independently validates the administrative session, requires a trusted same-origin request, and validates the requested container and case-folder segment before performing deletion. It invokes the same existing deleteBlobCase(container, casefolderID) operation as the ordinary endpoint. That operation lists and deletes blobs in the selected container whose names begin with the supplied case-folder prefix; it does not delete the Azure container or broaden deletion to unrelated containers.

Administrative representation JSON unlocking uses the dedicated POST /api/admin/editRepJson route. That endpoint independently validates the administrative session, requires a trusted same-origin request, and validates the requested container and blob path before removing repComplete. The former /api/file/editRepJson route is retired and no longer performs storage access.

Automated contract verification for the implemented deletion controls has passed, including ordinary ownership/HMAC rejection, administrative method, session, origin and input rejection, zero deletion calls on rejected requests, and exact cross-container helper arguments on success. Live Azure behaviour, browser-level behaviour, and deployment configuration have not been verified by that automated coverage. The other administrative API and storage limitations documented above remain open, and these changes do not establish closure of the overall ITHC finding.

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.

7.4 KiB Raw Blame History