status-page-auth

name

status-page-auth

description

Single-password admin authentication for this status-page app. Use this skill whenever working on login, sessions, the session cookie, middleware route protection, or the Node-vs-Edge runtime split for auth. Trigger on phrases like "protect the admin", "login", "session cookie", "middleware auth", "verify the session", "admin password", or anything touching lib/auth.ts, lib/auth-edge.ts, or middleware.ts. Apply automatically when building or changing authentication here.

Status Page Auth (single password)

There is one admin, protected by a single password and a signed session cookie. No users table.

The Node/Edge split (critical)

Next.js middleware.ts runs in the Edge runtime — it has Web Crypto but no sqlite3 and no Node crypto. Importing either into middleware breaks the build. Therefore auth is split into two files:

• lib/auth.ts (Node runtime, used by route handlers only):
  • hashPassword(pw) / verifyPassword(pw, hash) via Node crypto.scrypt + timingSafeEqual.
  • createSession() → jose new SignJWT({ role:'admin' }).setProtectedHeader({alg:'HS256'}).setExpirationTime('7d').sign(secret).
  • SESSION_COOKIE = 'sp_session', plus a helper to build the Set-Cookie options.
• lib/auth-edge.ts (Edge-safe, imported ONLY by middleware.ts):
  • verifySession(token) → jose.jwtVerify(token, secret); returns boolean. No DB, no Node crypto.
  • jose works in Edge because it uses Web Crypto — this is why we use jose instead of Node HMAC.

The signing secret comes from process.env.SESSION_SECRET (available in both runtimes). It MUST be stable across restarts or all sessions invalidate.

middleware.ts

export const config = { matcher: ['/admin/:path*', '/api/admin/:path*'] };

• Allow /admin/login and /api/admin/auth/login through unauthenticated (entry points).
• Read the sp_session cookie → verifySession. On failure: /api/admin/* → 401 JSON; page paths → NextResponse.redirect(new URL('/admin/login', req.url)).

Flows

• Login POST /api/admin/auth/login {password} → getAdminAuth() resolves the expected credential (DB admin.passwordHash first, else env.ADMIN_PASSWORD) → verify → createSession() → set cookie HttpOnly; SameSite=Lax; Path=/; Secure (prod); Max-Age=7d.
• Logout POST /api/admin/auth/logout → clear cookie (Max-Age=0).

Bootstrap rules

• If no DB password hash is set, accept env.ADMIN_PASSWORD (timing-safe compare).
• If neither a DB hash nor ADMIN_PASSWORD is set, the login page shows a "set ADMIN_PASSWORD" notice and blank-password login is rejected.
• Setting a password in the admin settings stores a scrypt hash in settings.admin and takes precedence over env.