Recipe · Auth flow

How to trace an auth flow with agentmako

TL;DR: Bug report says an authorization path is failing. Instead of grepping for role and reading twelve files, use mako_help → auth_path → route_trace → db_rls → file_preflight to pinpoint the bug. Tools used: mako_help, auth_path, route_trace, route_context, db_rls, file_preflight, reef_inspect.

The bug report

You get a ticket: "Users who should have access are seeing a 403 on one route, but nearby users with similar access can complete the flow."

You don't know this part of the code well. The agent doesn't know it at all.

The vanilla approach (and why it falls over)

Without agentmako, the agent's first ten moves look like:

$ rg -n "authorization failed" .
$ rg -n "/api/example" app/
$ ls app/api/example
$ cat app/api/example/route.ts
$ rg -n "role" lib/auth/
$ cat lib/auth/dal.ts
$ cat lib/auth/roles.ts
$ rg -n "scope" lib/
... etc.

That's 5,000+ tokens of grep output and file reads before the agent has a hypothesis. Worse, it has no idea whether audit_log, membership_scope, or workflow_state are RLS-sensitive — so even if it finds the role check, it'll miss the row-level-security policy that's actually blocking some managers.

The agentmako approach

Four or five targeted tool calls instead of grep loops.

Step 1 — mako_help

{
  "tool": "mako_help",
  "args": { "task": "audit an authorization flow before editing" }
}

Returns a compact workflow: gather the route/auth context, inspect database policy context when relevant, preflight the files, then verify the changed paths.

Step 2 — auth_path

Ask "what's the auth boundary on this route?" before reading any code.

{
  "tool": "auth_path",
  "args": {
    "route": "/api/example/action",
    "verb": "POST"
  }
}

Returns the route → likely auth-guard files → verifySession/requireRole call sites → relevant tables. You now know that the role check lives in lib/auth/dal.ts:resolveManagerScope and the data access is in app/api/example/action/route.ts.

Step 3 — route_trace

{
  "tool": "route_trace",
  "args": { "route": "/api/example/action", "verb": "POST" }
}

Returns the resolved handler file, the imports it pulls in, the Supabase tables it touches via .from(), and any related routes. You learn the handler reads membership_scope and writes workflow_state.

Step 4 — db_rls on the touched tables

{
  "tool": "db_rls",
  "args": { "schema": "public", "table": "membership_scope" }
}

Returns RLS state and policy bodies. Here's where the bug usually hides: a policy that checks auth.uid() = user_id when the application flow expects a membership or resource-scope check.

Step 5 — file_preflight before editing

{
  "tool": "file_preflight",
  "args": { "filePath": "lib/auth/dal.ts", "limit": 20 }
}

Reef returns existing findings, diagnostic stale flags, recent runs, applicable conventions, and ack history on this file. Maybe someone has already reviewed the same access-boundary concern with an explanation. Don't redo that analysis — read it.

Optional — reef_inspect

{
  "tool": "reef_inspect",
  "args": { "subjectKind": "file", "subjectId": "lib/auth/dal.ts" }
}

Full evidence trail: facts, findings, recent diagnostic runs, and any acks. If there's an ack saying "we know this looks weird, it's intentional because X" — read that before changing the code.

The fix

Now the agent has the context it needs to actually edit. The route handler doesn't call resolveAccessScope before the database read; the RLS policy on manager_district is correct but the handler is querying with the session identity rather than the resolved resource scope. One-line fix in the handler.

Total tool calls: 4-5. Total tokens of context: roughly 1,200. Compare to the vanilla path: 12,000+ tokens before any hypothesis.

Variations

  • Cross-tenant audit: swap db_rls for tenant_leak_audit when you suspect the bug is systemic across tenant-keyed tables.
  • Frontend-only auth bug: start with route_context instead of auth_path — it returns the surrounding layout, middleware, and client/server boundary checks.
  • Pre-commit gate: after the fix, run git_precommit_check to catch any boundary regressions in the staged diff.

Tools used in this recipe

  • auth_path — trace likely auth boundaries for a route, file, or feature.
  • route_trace — trace a route to its handler, files, and nearby evidence.
  • route_context — return route resolution and route neighborhood.
  • db_rls — RLS enabled state and policies for one table.
  • file_preflight — pre-edit findings, diagnostic freshness, conventions, and ack history for one file.
  • reef_inspect — full evidence trail for one file or subject.
  • tenant_leak_audit — multi-tenant RLS posture audit.
  • git_precommit_check — staged TS/TSX route auth and boundary checks.