AuthGuard

AuthGuard monitors the sign-in security of a web app and explains what it finds in plain language. A connected app sends events (logins, failed logins, signups, password checks, session activity) through a small SDK. AuthGuard runs fixed detection rules on those events, shows alerts in a console, emails the important ones, and can explain any alert with AI.

Werkstatt is a demo client, not a real product. The woodworking school under /werkstatt is a fictional app. It exists only to have something for AuthGuard to monitor, and to show AuthGuard working on top of it. You can't book classes there, and it isn't a real business. Its accounts, notes and logins are demo data.

The databases are not running 24/7. AuthGuard and Werkstatt each use a Supabase database that is paused after a period of inactivity (on Supabase's Free plan, after 7 days of low activity). While a database is paused, the login and signup pages say so ("Sign-in isn't available right now…") and nobody can sign in. Signed-in users are sent to the login page with the same message; their session is kept and works again once the database is back. This is not a bug in the app. To try the demo, email Elise at [email protected] and she will start the databases. You can email the same address with any other questions.

---

Contents

• What's in the repository
• How it works
• Pages and routes
• Detection rules
• Running it locally
• Environment variables
• Supabase setup
• Connecting an app with the SDK
• Privacy and security design
• Known limitations
• Project structure

---

What's in the repository

One Next.js app contains two separate products:

	AuthGuard	Werkstatt (demo client)
What it is	The monitoring product: landing page, console, alerts, AI assistant	A fictional woodworking school with sign-up, login and a private notes page
URL paths	/, /authguard/*, /api/authguard/*, /api/v1/events	/werkstatt/*
Database	AuthGuard's own Supabase project	A separate Supabase project
Accounts	AuthGuard console accounts	Werkstatt customer accounts
Talks to the other product	Receives events on POST /api/v1/events	Only through the AuthGuard SDK (lib/authguard-sdk), over HTTP, like any outside app would

The two products never share a database, a session cookie or a Supabase client. The only link between them is the event API.

Stack: Next.js 16 (App Router, proxy.ts), React 19, TypeScript, Tailwind CSS 4, shadcn/ui, Supabase (Auth and Postgres), Zod, the Vercel AI SDK with Google Gemini, and Resend for alert emails.

How it works

 Werkstatt (demo client)                      AuthGuard
 ───────────────────────                      ─────────────────────────────────────────
 login / signup / page view
        │
        ▼
 AuthGuard SDK  ── POST /api/v1/events ──▶   Events API (x-authguard-key)
 (hashes email + IP,                           │  store event (service role)
  checks password locally)                     ▼
                                              after(): run detection rules
                                               │  new medium/high alert?
                                               ├─▶ authguard_notifications (bell)
                                               └─▶ email via Resend (optional)

                                              Console (/authguard)
                                               └─ alerts are recomputed from the
                                                  last 7 days of events on every load

1. Werkstatt reports what happens. On each login, signup and signed-in page view, Werkstatt's server calls the SDK. The SDK hashes the email and IP with a secret salt, scores the password locally (strength from 0 to 4, plus a breach check), and posts an event to AuthGuard. These calls run after the response is sent, have a 2-second timeout and ignore errors, so monitoring never slows down or breaks the login.
2. AuthGuard stores and checks. The Events API verifies the API key, rejects any password, token, email or ip field, and stores the event. It then re-runs the detection rules on related events and records a notification for each new medium or high alert. If email is configured, it sends an email.
3. The console shows alerts. Alerts are not stored: they are computed from the last 7 days of events each time the console loads. Each alert links to its evidence, and has "Explain" and "Report" buttons that call the AI.
4. Pop-up explanations. Underlined security terms (for example session reuse or breached password), event types, severity labels and the console's stat tiles and table headers open a short explanation when you hover over them or tap them. These texts are written in advance in lib/authguard/glossary.ts; no AI is involved.

Pages and routes

AuthGuard

This is the beginning of the README. Read the rest at the original. Read the full README ↗