Admin Observability

The web application includes a protected admin panel at /admin for reviewing API telemetry without exposing observability data publicly.

What It Captures

• Route key, pathname, method, and status code
• End-to-end handler latency
• Cache-control hints
• Request identifiers for incident correlation
• Redacted failure context for server-side exceptions
• Hashed client IPs instead of raw addresses
• Admin audit events for login, logout, and observability reads

Security Model

• Admin access uses Google or GitHub OAuth via better-auth
• Successful login issues a signed HttpOnly session cookie
• Only accounts with role = 'admin' are granted access
• The session and role are checked before rendering /admin
• Admin telemetry APIs reject unauthenticated or non-admin access
• OAuth tokens are never persisted into telemetry records

Minimal Environment Variables

# pragma: allowlist secret - documentation placeholder
DATABASE_URL=postgresql://user:pass@host.neon.tech/db?sslmode=require
BETTER_AUTH_SECRET=replace-with-a-long-random-secret
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Optional Environment Variables

AIWF_TELEMETRY_DIR=../../data/telemetry
# AIWF_TELEMETRY_SALT=replace-with-a-stable-hashing-salt

Generate a session secret locally with either command:

openssl rand -base64 32

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

Admin Role Assignment

The first user with email wyattowalsh@gmail.com is automatically granted the admin role on account creation. Additional admins can be assigned by updating the role column in the user table directly.

Current Scope

This implementation focuses on the Next.js API surface.

• Route-level API observability for App Router handlers
• Protected admin overview for throughput, error rate, and latency trends
• Recent 5xx failures and request activity stream
• Admin audit trail for privileged access

Future backend integration can replace the local telemetry sink with a shared service-backed store without changing the admin surface.