Phase 2 walkthrough

Phase 2 is reproduced lesson by lesson: each lesson's walkthrough has the steps and the code. This page adds only what no single lesson shows: the order to follow them in, how the finished pieces work together on one request, and where to re-prove the phase's exit criteria. It assumes Pre-2 is complete (Pre-2 walkthrough), including the post notes listed below.

The design is recorded in Phase 2 build rules and target design (version 2.8.1), the plan in the completed Phase 2 plan.

Follow the lessons in order

Lesson 5 reshapes lesson 4's guard.ts; lesson 4's post note says how. Lesson 3's post note sends you back to earlier phases first.

How a request travels

A request to a guarded route, for example GET /api/health from a signed-in browser, passes through these steps. Each one names the lesson that built it.

1. Proxy (apps/web/src/proxy.ts, Phase 1). It calls getUser(), which refreshes an expired session and writes the new cookies, then returns early for /api paths. It never answers an API request with a redirect: authentication is the guard's job.
2. Route (route.ts, lesson 6). export const GET = withApiGuard(handler, opts). Next.js calls the function the guard returned with (req, ctx).
3. withApiGuard (lessons 4 and 5). It starts the latency timer and records method and path (the pathname only, never the query string).
4. resolveApiCaller (lesson 2). Any Authorization header → undefined. Otherwise getUser() verifies the session with Supabase Auth → a session caller, or undefined.
5. authorizeAndHandle (lesson 5), cheapest check first:
   1. No caller → denial UNAUTHENTICATED.
   2. A key caller without requireScope → denial SCOPE_MISSING. No connection has been taken yet.
6. withRLS(caller.userId, …) (Pre-2). BEGIN on the pooled app_runtime connection, then set_config('app.current_user_id', userId, true), which lasts until the transaction ends.
7. Entitlements (lesson 3), only when opts.feature is set: getEnabledFeatures(tx) reads the caller's rows, filtered by RLS. The key missing → denial FEATURE_DISABLED, and the transaction commits with nothing written.
8. Handler (any route). handler({ tx, caller, req, ctx }). Its queries see only the caller's rows. Resolving commits; throwing rolls back.
9. Logs and response (lesson 5), back in withApiGuard:
   • a denial → api.denied with its code, then the { error, code } body with 401 or 403;
   • a throw → api.error with toLoggedError(error), then 500 INTERNAL, with no details sent;
   • every request, last → one api.request with status and latencyMs.

Four checks stand around that path and never run per request:

What if one route dropped the guard? Its handler would lose tx, and it has no other way in: @sidekick/core doesn't export the raw client, and lint bans importing unsafe anywhere but rls.ts. A connection without app.current_user_id sees zero rows, so user data stays hidden. What breaks is the promise: the route would answer anyone, with no 401, no logs and no entitlement check. pnpm dev and pnpm build would serve it locally (lesson 6 proved the build doesn't lint). CI's lint step catches it, and branch protection keeps it off main.

Where entitlements come from

Nothing in the request path writes entitlements. A person runs pnpm ops:entitlements:grant (lesson 7) as the privileged role, and the user's next request reads the new rows at step 7 above. Disabling is a DELETE with the same role. ALL_FEATURES is still empty, so --all grants nothing until Phase 4 registers Taxila.

Exit criteria and proofs

The plan's exit criteria, each with the proof that holds on main:

Re-run them on a fresh main:

pnpm turbo test:integration --force
pnpm dev   # then, in another terminal:
curl -i localhost:3000/api/health
pnpm ops:entitlements:grant --email <you> --all

Post notes in earlier walkthroughs

Fixes found during Phase 2 that belong to an earlier phase went into that phase's walkthrough as dated post notes, so anyone following the guides in order ends at the same code:

Within Phase 2, three lesson walkthroughs carry post notes of their own: lesson 3 (the follow-ups above), lesson 4 (changed in lesson 5) and lesson 6 (the startup check). Lesson 2 was edited in place for undefined, with a note at the top.

Next: Phase 3, the graph store and metadata service. What Phase 2 left for later is listed in the completed plan.