Verifier Web

Web Verifier (Polar)

The handle is the browser. The evidence is screenshots + the resulting DB/backoffice state. This skill is the repo's replay protocol for any change that a user — human or programmatic — meets through the web UI: the dashboard, the checkout, or the backoffice.

Use the local-environment skill for all stack mechanics (start/stop/logs/instances). This skill adds the browser-driving and auth/payment recipe on top.

When to use

• Verifying a dashboard, checkout, or backoffice change.
• Confirming login works, or a flow that requires being logged in.
• Proving a purchase / subscription path end-to-end against live Stripe (test mode).

For CLI/API/library changes, use the built-in /verify surfaces instead — this skill is for pixels.

Tooling

Drive the browser with the Playwright MCP (mcp__playwright__*). Prefer browser_snapshot (accessibility tree, gives refs) over screenshots for acting; use browser_take_screenshot for evidence. Read backend state with dev docker exec db psql and docker logs.

1. Bring up the stack

dev docker ps          # allocates/detects this worktree's instance number N
dev docker up -d       # build + migrate + seed on first run (several minutes)

dev docker up prints the authoritative ports — always read them from its output, do not compute them. They look like:

API:  http://localhost:81NN
Web:  http://localhost:31NN

(N is the instance; e.g. instance 7 → API :8107, Web :3107. Container names are polar-app-<N>-api-1, -web-1, -worker-1; DB is polar_dev_<N>.)

Poll readiness before driving anything:

for i in $(seq 1 60); do
  a=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:81NN/healthz)
  w=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:31NN)
  # web may answer 200/307/308 (Next.js dev redirects/compiles on first hit)
  [ "$a" = 200 ] && [ "$w" -ge 200 ] && [ "$w" -lt 400 ] && break; sleep 5
done

2. Log in (dashboard + backoffice share one cookie)

Log in through the real email-OTP flow. The backoffice at http://localhost:81NN/backoffice/ uses the same user-session cookie, so logging into the dashboard authenticates the backoffice too.

1. browser_navigate → http://localhost:31NN/auth (the nav "Login" link is hidden; go to /auth directly. /login 404s.)
2. Type admin@polar.sh into the Email field, click Sign in with email. The seed account admin@polar.sh owns admin-org (approved, payout account, products) — go straight to checkout testing, no onboarding.
3. The page advances to /auth/email-otp. Read the code from the api logs:

   docker logs --since 60s polar-app-<N>-api-1 2>&1 | grep -A1 "LOGIN CODE"
   

4. Type the 6-character code (uppercase letters + digits, e.g. C9YLIF) → lands on /dashboard/admin-org.
5. Backoffice: browser_navigate → http://localhost:81NN/backoffice/.

The backoffice needs compiled assets (Tailwind/DaisyUI → static/styles.css + scripts.js). On a clean start these are often not built yet — the backoffice then renders unstyled and /backoffice/static/styles.css + scripts.js 404 (served as application/json). Build them once:

cd server && uv run task backoffice

The output lands in server/polar/backoffice/static/ on the host, which is mounted into the api container — it's picked up live, no recreate needed. (dev docker up has a "Building backoffice assets" step, but don't rely on it having run; check that the backoffice is styled and rebuild if not.)

Login prerequisite — the auth-session cookie domain

Login through the browser requires the auth-session cookie domain to match the host the frontend uses (localhost). This is set in dev/docker/docker-compose.dev.yml:

POLAR_USER_SESSION_COOKIE_DOMAIN: localhost
POLAR_AUTHENTICATION_SESSION_COOKIE_DOMAIN: localhost   # both must be present

If you see POST /v1/auth/email-otp/request → 401 "Invalid or missing authentication session token", the Set-Cookie from /auth/start is being dropped because its Domain= doesn't match the page host. Check:

curl -si -X POST http://localhost:81NN/v1/auth/start \
  -H 'Origin: http://localhost:31NN' -H 'Content-Type: application/json' \
  -d '{"return_to":"/dashboard"}' | grep -i set-cookie

Domain=localhost → good. Domain=127.0.0.1 → the override above is missing; add it, then recreate the api (dev docker up -d api — a restart does NOT reload compose env). Do not fall back to minting/injecting a session cookie.

3. Purchase end-to-end (live Stripe test mode)

A real purchase needs (a) a valid Stripe sandbox key on api and worker, and (b) a webhook listener forwarding to the api. Order creation is async — the api 202s the webhook and the worker creates the order.

3a. Stripe account + keys

Use your own Stripe sandbox (https://dashboard.stripe.com/sandboxes). Never a live account, and never a shared team account — dev stripe refuses both. The Stripe CLI profile is always polar-sandbox.

Secrets are set up once and reused across worktrees. They live centrally in ~/.config/polar/secrets.env and dev/setup-environment propagates them into each worktree's server/.env. So you don't redo Stripe setup per worktree — populate the central file once. The one-step path:

dev stripe --listen --port <api-port>   # <api-port> = the API port from `dev docker up`

This installs/logs-in the Stripe CLI if needed, writes the API keys + webhook secret into the central secrets file, propagates them, and starts the webhook listener (3b). If the CLI is already configured it skips straight to listening.

CLI test keys expire every 90 days. Symptom of an expired key: checkout sticks on "We are processing your order" and the worker/api logs show AuthenticationError: Expired API Key provided. Refresh with dev stripe, which detects the expired key and re-runs the link flow, then recreate services (3c).

If you ever set keys by hand, set them in the central file (or server/.env) and keep them on the same account: POLAR_STRIPE_SECRET_KEY (the secret key), POLAR_STRIPE_PUBLISHABLE_KEY and NEXT_PUBLIC_STRIPE_KEY (the publishable key — the browser tokenizes the card with it). pk and sk must belong to one account or the card tokenizes against one account while the backend charges another.

3b. Webhook listener

dev stripe --listen --port <api-port> starts it for you. To run it directly in the background with its output captured to a log you can grep later:

stripe listen \
  --forward-to http://localhost:81NN/v1/integrations/stripe/webhook \
  --forward-connect-to http://localhost:81NN/v1/integrations/stripe/webhook-connect \
  > /tmp/stripe-listen.log 2>&1 &

(If you started it via dev stripe --listen instead, its events print in that command's terminal — redirect to a file as above if you want to grep them in 3e.)

It prints Your webhook signing secret is whsec_.... Both POLAR_STRIPE_WEBHOOK_SECRET and POLAR_STRIPE_CONNECT_WEBHOOK_SECRET must equal that secret. Leave the listener running in the background. If webhooks come back 400 (signature failure), the configured secret is stale — re-sync it to the value the listener prints.

3c. Recreate ALL THREE services after any key change

dev docker up -d api web worker

The worker is easy to forget — if it keeps a stale/expired key, the api will 202 the webhook but order creation fails silently and retries forever. Recreate api, web, and worker on every env change.

3d. Drive the checkout

1. Find/make a checkout link for an admin-org product, then open its redirect to start a checkout session. The redirect token is the link's client_secret (the polar_cl_... value — not the UUID id):

   http://localhost:81NN/v1/checkout-links/<polar_cl_...>/redirect
   

   List it (qualify the column — both tables have id/client_secret):

   select cl.client_secret from checkout_links cl
     join organizations o on o.id = cl.organization_id
     where o.slug = 'admin-org' limit 1;
   

2. Fill the form:
   • Email — real domain + tag, e.g. petru+verify-<flow>@polar.sh. .local and example.com are rejected by checkout email validation.
   • Card (inside the Stripe iframe): 4242 4242 4242 4242, exp 12 / 34, CVC 123.
   • Cardholder name, then Billing country (Radix combobox — click to open, click the option). Selecting United States reveals required address line1, city, state (Radix combobox), ZIP — fill all. React inputs need the native value-setter + an input event if you set them via browser_evaluate.
3. Click Subscribe now / Pay. The page goes to …/confirmation showing "We are processing your order", then "Thank you for your order!".

Test cards (Stripe test mode; any future expiry, any 3-digit CVC, any ZIP):

Verify the unhappy paths too: a decline should surface an inline card error and create no order; a 3DS card should pop the authentication modal. Full list: https://docs.stripe.com/testing.

3e. Verify the result (don't trust the UI alone)

# webhook delivery (expect charge.succeeded + payment_intent.succeeded → 202)
# from the listener log you captured in 3b:
grep -E 'POST|payment_intent|charge' /tmp/stripe-listen.log

# order + subscription created by the worker
dev docker exec db psql -U polar -d polar_dev_<N> -tc \
 "select o.status, o.net_amount_v2, c.email from orders o
   join customers c on c.id=o.customer_id
   where c.email='petru+verify-<flow>@polar.sh' order by o.created_at desc limit 1;"

Expect paid | 2000 | …. Also confirm it renders in backoffice Orders (/backoffice/orders/). Screenshot the confirmation page and the backoffice row.

Report

Follow the built-in /verify report format: Verdict (PASS/FAIL/BLOCKED/SKIP), Claim, Method, and numbered Steps where each step is one thing you did to the running app and what it showed — attach the screenshots. Test runs and typechecks are not steps. Note anything that made you pause (a slow poll, a stale-key retry, a confusing validation message) — that's the signal.

Gotchas seen in practice

• Restart ≠ recreate. dev docker restart keeps the old compose env; use dev docker up -d <svc> to load env/key changes.
• The api session is DB-backed, so recreating the api keeps you logged in.
• dev stripe --listen refreshes the webhook secret whenever it writes new API keys, so switching sandbox propagates the new signing secret too. It leaves the two secrets alone when they already differ from each other — that means they came from dashboard endpoints, not the CLI listener.
• dev seed runs on the host against server/.env (POLAR_POSTGRES_*), which is not the dockerized polar_dev_<N>. For a docker instance, seed inside the container instead: docker exec polar-app-<N>-api-1 sh -c 'cd /app/server && uv run python -m scripts.seeds_load'