Watchtower-Course-Project

Authentication Workflow (Clerk) — Prototype 3

This document describes how authentication works for the WatchTower dashboard in the Prototype 3 flow. We use Clerk for all real authentication. WatchTower keeps its own UI shell (landing, login, signup) and delegates identity, sessions, sign-in, sign-up, password reset, and sign-out to Clerk.

Decision record: see docs/adr/ADR-0006.md.

End-to-end flow

Landing Page (public)
   src/frontend/landing/index.html
        │  "Get Started" / Login
        ▼
Login / Signup (our shell + Clerk component)
   src/frontend/auth/login.html   → #clerk-sign-in
   src/frontend/auth/signup.html  → #clerk-sign-up
        │  Clerk authenticates and starts a session
        ▼
Protected WatchTower UI
   src/frontend/dashboard/index.html   (guarded by auth-guard.js)
        │  Logout
        ▼
Back to Landing Page (public)

Page-by-page responsibilities

1. Public landing page — `src/frontend/landing/index.html`

Fully public. No authentication is required or attempted here.
The “Get Started” / primary CTA routes to the login page (/login when served by the Node server, or ../auth/login.html in the static/file flow).

2. Login / signup pages — `src/frontend/auth/`

We keep our own branding, header, and card layout (the “UI shell”).
The previous fake password forms have been removed. They never performed real authentication and never sent passwords anywhere — they only did client-side validation. No migration of credentials was needed.
login.html contains <div id="clerk-sign-in"></div>; signup.html contains <div id="clerk-sign-up"></div>.
Load order on both pages:
1. ./clerk-config.js — exposes window.CLERK_PUBLISHABLE_KEY.
2. ./auth.js — loads Clerk, mounts the component, handles redirects.
After a successful sign-in or sign-up, Clerk redirects to the dashboard (/dashboard when served by the Node server).
If an already-signed-in user opens login/signup, auth.js redirects them straight to the dashboard.
forgot-password.html no longer pretends to send reset emails; it points users to the “Forgot password?” link inside Clerk’s sign-in box.

3. Protected dashboard — `src/frontend/dashboard/index.html`

Load order:
1. /login/clerk-config.js — publishable key (generated into src/frontend/auth).
2. /dashboard/auth-guard.js — client-side route guard (in <head>).
3. /dashboard/app.js — the existing dashboard logic (unchanged).
auth-guard.js hides the dashboard shell until Clerk confirms a session.
- Signed in: the shell is revealed, the user label (#auth-user-label) is populated, logout controls are wired, and the guard upserts the user into Supabase via POST /api/users/sync (see below).
- Signed out / Clerk fails to load / key missing: the guard fails closed and redirects to /login/.
All dashboard data fetches in app.js (/api/events, /api/stats, /api/developer/stream, /api/developer/insights, /api/developer/query) send an X-Clerk-User-Id header so the backend returns only that user’s data.

Per-user data scoping

WatchTower keeps Clerk as the only authentication provider and uses Supabase purely as the application database — there is no Supabase Auth and no password is ever stored.

Concern	Where it lives
Identity / sessions / sign-in	Clerk
Application users	Supabase `public.app_users` (keyed by `clerk_user_id`)
Telemetry events	Supabase `public.prototype3_events`, scoped by `user_id`

How a user is recognized

After Clerk confirms a session, auth-guard.js calls POST /api/users/sync with { clerkUserId, email, displayName } and an X-Clerk-User-Id header.
The server calls eventStore.syncUser(...), which upserts a row into app_users (clerk_user_id, email, display_name, last_seen_at). No password or credential is stored — Clerk owns those.

How data is scoped

Dashboard read routes (GET /api/events, GET /api/stats, GET /api/developer/stream, GET /api/developer/insights, POST /api/developer/query) call requireCurrentUser(...). With no X-Clerk-User-Id header they return 401.
They load events with eventStore.listEvents(limit, { userId }) / eventStore.allEvents(limit, { userId }), which filter prototype3_events.user_id = <Clerk user id>.
POST /api/events (and POST /api/beacon) resolve an ingest owner with getIngestOwnerUserId(...) and, when present, stamp each incoming event with user_id = <owner> before insert. The owner is the authenticated dashboard user when present, otherwise the temporary DEFAULT_INGEST_OWNER_USER_ID fallback (see “External GitHub Pages test app ownership” below), otherwise none (the event stays anonymous with user_id = null).

Monitored ShopDemo bridge (`/demo/`)

The demo is a same-origin stand-in for an external monitored app. Its SDK sends events to POST /api/events without the dashboard’s Clerk header.
So the dashboard can show demo-generated events, auth-guard.js stores the signed-in Clerk id in localStorage (watchtower_clerk_user_id), and demo/app.js initializes the SDK with userId = <that id>. The id then rides in the event payload and is persisted as prototype3_events.user_id.
Open /demo/ after signing in to the dashboard (or refresh it) so the id is present. A truly external app on another origin has no such id and ingests as anonymous (user_id = null) — which is the intended future “needs a project/app key” path.

External GitHub Pages test app ownership (temporary)

The separate, GitHub Pages–hosted test app (https://cse110-sp26-group09.github.io/Watchtower-test-app/) is a real external monitored app. It loads its own copy of the WatchTower SDK, points at the absolute Render endpoint (https://watchtower-course-project-g8dv.onrender.com/api/events), and sends the same { events: [...] } batches as the local demo.
It has no Clerk session: it does not (and should not) send an Authorization: Bearer token or an X-Clerk-User-Id header, and its SDK does not set a userId on events. The backend therefore accepts the events (200 OK) but stores them with user_id = NULL — so, now that the dashboard is scoped per Clerk user, those events do not appear for any logged-in user.
To make these external events visible during a live demo, set DEFAULT_INGEST_OWNER_USER_ID (Render env, or local .env) to the demo owner’s Clerk user id. On ingest, when there is no authenticated user, the backend stamps anonymous events with this id so they land on that owner’s scoped dashboard.
This is applied as a fallback only: it fills user_id for events that arrive without one. Authenticated dashboard ingests still win and override it, and the same-origin demo’s own per-user tagging is preserved.
This is temporary, for the prototype/live demo only. It hard-codes the entire external app’s traffic to one owner. The long-term solution is a per-app/project key system so each monitored app maps to the correct owner without a human login and without a single global default. Never hard-code the Clerk user id in source — it lives only in the environment variable.

Resulting behavior

First-time user: no rows yet, so stats and feeds start at 0.
Returning user: the same clerk_user_id filters back the rows persisted during earlier sessions, so they see their saved data after logging back in.
Different user: a different clerk_user_id never matches the first user’s user_id, so users cannot see each other’s events.

Trust model & token verification

The backend resolves the current user id with this preference order (resolveCurrentUserId in server.js):

Verified Clerk session JWT — the browser sends Authorization: Bearer <Clerk.session.getToken()>. The server verifies the signature against Clerk’s public JWKS (<issuer>/.well-known/jwks.json) and the iss claim, then takes the user id from the signed sub claim. This is cryptographically authoritative and cannot be spoofed.
X-Clerk-User-Id header fallback — used only when token verification is not configured (no real Clerk key, e.g. CI / local memory-store runs) or when WATCHTOWER_TRUST_USER_HEADER=true is explicitly set.

The Clerk issuer (Frontend API origin, e.g. https://your-app.clerk.accounts.dev) is derived from CLERK_PUBLISHABLE_KEY (base64-encoded inside the key) or set explicitly via CLERK_JWT_ISSUER. No Clerk secret key is needed — JWKS verification uses only public keys.

When a real Clerk instance is configured, the dashboard routes require a valid token: a request with only a (forged) X-Clerk-User-Id header and no valid token is rejected with 401.

Logout behavior

A #logout-button lives in the dashboard topbar; the existing Settings → “Sign out” button (#sign-out-button) is also wired.
Both call Clerk.signOut() and then redirect to the login page (/login/).

Clerk vs WatchTower responsibilities

Concern	Owner
Sign-in / sign-up UI components	Clerk (mounted into our shell)
Password handling & storage	Clerk only — WatchTower stores nothing
Sessions & tokens	Clerk
Password reset / email verification	Clerk
Page branding & layout shell	WatchTower
Routing between landing/login/dashboard	WatchTower
Event ingestion + storage	WatchTower (unrelated to user auth)

Why WatchTower does not store passwords

Storing passwords means owning hashing, salting, breach response, reset flows, and compliance. Clerk is purpose-built for this. By delegating, WatchTower never receives a password, so there is nothing sensitive to leak from our database or backend. The dashboard stores telemetry events only — no credentials.

Protection model

Prototype 3 demonstrates the dashboard experience, the landing → login → dashboard journey, and per-user data isolation.
The client guard bounces anonymous users to login so they never see dashboard content.
The dashboard read routes (GET /api/events, GET /api/stats, GET /api/developer/stream, GET /api/developer/insights, POST /api/developer/query) require an authenticated user (401 otherwise) and scope all data to that user.
When a real Clerk instance is configured, the user id comes from a verified Clerk session JWT (see “Trust model & token verification”), so it cannot be spoofed. The X-Clerk-User-Id header is only a fallback for unconfigured/test environments.
POST /api/events, POST /api/beacon, and /api/events/stream remain open so external/SDK ingestion keeps working without a dashboard login.

Remaining hardening (optional, defense-in-depth)

Token verification is enforced at the API layer. A further step is to push scoping into the database via Supabase RLS using the Clerk Third-Party Auth integration (policies on auth.jwt() ->> 'sub'), so even an API bug cannot leak cross-user rows. This requires the DB client to carry the Clerk token (the server currently uses the service-role key, which bypasses RLS).
The event schema does not change for any of this.

Dashboard user auth vs SDK event ingestion auth (important distinction)

These are two different authentication problems and must not be conflated:

	Dashboard user auth	SDK event ingestion auth
Who authenticates	A human operator viewing dashboards	A monitored application sending events
Mechanism	Clerk login/signup/session	A future per-app/project key or token
Requires a user login?	Yes	No — must work headless/server-side
Implemented today	Clerk (this work)	Not yet — ingestion is currently open

The browser SDK (src/sdk/watchtower.js) and the ingestion endpoint should never require a normal Clerk user login. A separate app/project key or signed token is the correct future mechanism so that monitored apps can send telemetry without a human signing in.

Configuration & secrets

The only Clerk value in the frontend is the publishable key, written at runtime to src/frontend/auth/clerk-config.js by npm run config:clerk from the CLERK_PUBLISHABLE_KEY environment variable (see .env.example).
clerk-config.js is gitignored — set the key in a local .env file or in Render Environment settings, not in committed source.
Never add a Clerk secret key to any frontend file or commit it. Secret keys belong only on a backend, in environment variables, when backend verification is added later.

Running via the WatchTower Node server

npm start   # runs config:clerk, then boots src/backend/server.js

The backend serves the dashboard at /dashboard, the login shell at /login/, and the landing page at /landing/. The landing, auth, and dashboard pages live under src/frontend/ and the server resolves all three from there, so the full Clerk flow works end to end through the Node server (not just the static file flow).

Manual verification steps

Set CLERK_PUBLISHABLE_KEY in .env, then run npm start.
Open http://localhost:3000/landing/.
Click Get Started / Login.
Confirm the login page loads at /login.
Confirm the Clerk sign-in UI appears inside the card.
Sign in through Clerk.
Confirm redirect to the dashboard (/dashboard).
Refresh the dashboard while signed in.
Confirm you stay on the WatchTower UI (no bounce to login) and the user label shows your email/username.
Click Logout.
Confirm redirect to the landing (or login) page.
Open the dashboard directly while signed out.
Confirm you are redirected to the login page.
Open the signup page.
Confirm the Clerk sign-up UI appears, and signing up redirects to the Prototype 3 dashboard.

Per-user scoping verification (requires Supabase configured)

Sign in as User A.
In Supabase, confirm a row for User A appears in app_users (clerk_user_id = User A’s Clerk id, with last_seen_at set).
Confirm User A’s dashboard shows their own stats/events (a brand-new user starts at 0).
Generate events as User A (the dashboard sends X-Clerk-User-Id, so new prototype3_events rows get user_id = User A’s Clerk id).
Log out, then log back in as User A.
Confirm User A still sees the same saved events/stats.
Sign in as a different User B.
Confirm User B starts at 0 and does not see any of User A’s data.

External test app ownership verification (`DEFAULT_INGEST_OWNER_USER_ID`)

Set DEFAULT_INGEST_OWNER_USER_ID to the demo owner’s Clerk user id in the local .env (or in Render → Environment for the hosted backend).
Restart the local server, or redeploy the Render backend, so the new env var is loaded.
Open the GitHub Pages test app (https://cse110-sp26-group09.github.io/Watchtower-test-app/).
Trigger page view / click / error / custom events from the test app.
In the browser Network tab, confirm POST /api/events → 200 OK.
In Supabase, run the verification query below and confirm the newest rows now have user_id populated with DEFAULT_INGEST_OWNER_USER_ID instead of NULL.
Log into the WatchTower dashboard as that Clerk user and confirm the test app events appear.
Log into the dashboard as a different Clerk user and confirm those events do not appear for them (per-user scoping is preserved).

select
  id,
  user_id,
  type,
  event_name,
  route,
  app_name,
  received_at
from public.prototype3_events
order by received_at desc
limit 20;

Automated checks

npm run test:unit   # event-store + shared utils
npm run test:e2e    # Playwright
npm run docs:js     # JSDoc generation

The Playwright API specs send an X-Clerk-User-Id header so they post and read back events as a single synthetic user, validating the per-user scoping without weakening external SDK ingestion (which stays open).