Nolan Reyes

{
  "command": "pwd"
}

/Users/warrenthompson/Source/LoginID/03-engineering-delivery

{
  "file_path": "/Users/warrenthompson/Source/LoginID/CLAUDE.md"
}

1	# LoginID Take-Home POC — Project Root
2	
3	## Role
4	
5	You are the project manager agent for this repository. This file is the shared context every track refers back to. Each of the five track directories below has its own CLAUDE.md that can be worked independently by a scoped subagent, but that subagent should read this root file first for the assignment, the overall narrative, and how its track fits with the other four.
6	
7	When you spin up agents or subagents to do work in a track, point them at that track's CLAUDE.md as their brief, and tell them this root file exists for cross-track context. Don't let a track's agent silently duplicate scope another track owns — check the "Owns / does not own" boundaries below first.
8	
9	## What this repository is
10	
11	This is a take-home assignment for a LoginID interview, submitted as a full directory. The goal is not just to answer three coding questions — it's to demonstrate capability as an AI architect: how you scope a problem, use AI tooling deliberately, reason about security and data, and produce something that reads as an intentional, well-run engineering effort rather than a quick script.
12	
13	Code does not need to work or be fully complete. LoginID has said explicitly they care more about the design and the reasoning behind it, and about which AI tools/frameworks were used and how. Every track should document its reasoning, not just its output.
14	
15	## The assignment (verbatim from LoginID)
16	
17	Provide code solutions for the following questions in Go (preferably) or other languages — describe any tool, framework, or AI used.
18	
19	1. Code of a database DAO that can store and retrieve `user_profile` (name, address, phone) and `user_credential` (username, method, password), with support for multiple databases (PostgreSQL or CockroachDB, SQLite, etc).
20	2. Design a RESTful API web service to search and retrieve the above user profile data, plus security API authentication.
21	3. Design a service connector to third-party identity providers (referred to generically as ABC or XYZ) to retrieve personal data from vendors, with the following endpoints:
22	   - `/auth` — retrieves an `access_token` based on a POST JSON body `{"username": "<string>", "password": "<string>"}`
23	   - `/identity` — retrieves user PII (name, phone, address: `street_address`, `locality`, `region`, `postal_code`, `country`) based on a POST JSON body `{"phone": "<string>", "name": "<string>"}`
24	
25	Go is the preferred language. Other languages are acceptable if justified.
26	
27	## Track structure
28	
29	Five directories, each independently workable, each owning a distinct slice of the problem:
30	
31	| Directory | Track | Owns |
32	|---|---|---|
33	| `01-product-industry-research-design/` | Product & Industry Research (incl. Design) | Market/industry framing (IAM, passwordless auth, IDP aggregation space), personas and use cases, API and data contract design rationale, UX of the surfaces that would sit on top of this |
34	| `02-ai-security-architecture/` | AI Architecture & Security Architecture | The AI tooling/workflow used to produce this submission, threat modeling, auth/authz design for the API, credential and PII handling, secrets management, third-party connector security |
35	| `03-engineering-delivery/` | Engineering & Delivery | The actual Go code for all three questions, project structure, test strategy, delivery documentation |
36	| `04-infra-devops/` | Infra & DevOps | How this would be built, containerized, deployed, and operated — CI/CD, environments, multi-database configuration, observability |
37	| `05-data-ops/` | Data Ops | Data modeling for `user_profile` / `user_credential`, multi-database abstraction strategy, migrations, PII data governance and retention |
38	
39	Directories are numbered for reading order in the final submission, not for sequencing of work — tracks can be worked in any order or in parallel.
40	
41	## Working principles for every track
42	
43	- State your reasoning, not just your conclusion. LoginID is grading the "why" as much as the "what."
44	- Name the AI tool/workflow you used for that track's output (this project is being built with Claude Code; say so, and say how — e.g., subagents scoped per track, a given skill, a given model).
45	- Keep each track's CLAUDE.md self-contained enough that a fresh agent with no other context can pick it up and do correct work from it alone, plus this root file.
46	- Cross-reference other tracks by relative path (e.g., `../05-data-ops/CLAUDE.md`) rather than restating their content.
47	- Implementation is gated per story, not project-wide: Warren gave the implementation go on 2026-09-12 (evening) as an agile loop. Code (`.go`, `.sql`, `go.mod`, Dockerfiles, CI config) may be written only for a story the Product Owner has pulled, refined with the research team, and handed to engineering — recorded in `<track>/refinement/<LT-key>.md`. Work happens on a `feature/<LT-key>` branch, never directly on `main`. A story is done only when it is deployed to the public URL and the Product Owner has reviewed it there.
48	- **Attribution rule (Warren, 2026-09-12): every commit, PR, and Jira ticket says who did the work.** *Commits:* the git author is the persona doing the work — set once per worktree with `git config --worktree user.name "<Persona Name> (<track> <role>, <model>)"` and `git config --worktree user.email "<slug>@agents.loginid-takehome.invalid"` (`extensions.worktreeConfig` is enabled repo-wide) — and every commit message ends with trailers: `Story: LT-nn`, `Work-By: <persona> (<seat>); <persona> (<seat>)…` naming each hire who contributed and what they did (implementation, tests, review, objection seat), then `Co-Authored-By: Claude <model> <noreply@anthropic.com>`. *PRs:* title `LT-nn: <summary>`; body has a **Who did the work** section (lead, hires and seats, reviewers incl. 02's independent reviewer where applicable, models), plus links to the refinement doc and the Jira issue. *Jira:* every transition and every PR link is a comment beginning `Work-By: …` with the same names; the story's final comment before Done names who deployed and who reviewed. The PM applies the same rule to its own commits. Persona names, not "Claude" or "the team".
49	- **Shared working tree rule.** Every lead session shares this one checkout, so `git checkout`/`git switch` here changes everyone's tree — **never run them in this directory.** Feature branches live in worktrees outside the repo: `git worktree add /Users/warrenthompson/Source/LoginID-worktrees/<LT-key> -b feature/<LT-key> main`; work, commit, and push from that directory; the root tree stays on `main`. Remote: `origin` = `«email»:wtvamp/loginid-takehome.git` (public). Go code lives at the repo root (`cmd/`, `internal/`, `go.mod`); track directories hold documents.
50	
51	## Org, hiring, and orchestration
52	
53	The project is run as an org: this PM agent (Dana Whitfield) orchestrates five standing track-lead agents, and each lead hires a small sub-team of specialist agents with deliberately varied personalities. **Each track lead runs as its own top-level Claude Code session**, launched from its track directory in its own tmux window — so it loads its own track `CLAUDE.md` and persona natively, owns and spawns its hires as named teammates in that window, and talks to the PM session through cross-session messaging. Hires belong to their lead's session, not the PM's. The governing files, all at the root:
54	
55	- `PLAN.md` — the approved org plan for the planning phase (phases, gates, verification). `~/.claude/plans/` is scratch; this is the record.
56	- `PLANNING.md` — the thin cross-track board: one row per track, one writer per row, plus the service-boundaries section 03 owns and 04 reads.
57	- `CASTING.md` — archetype palette, org-wide variance rules, hire sizing, the persona-writing standard, the orchestration-pattern catalog (adversarial pair, red/blue, three hats, rotating devil's advocate, structured written debate, newcomer's question), the deep-research rule, the hire-creation procedure, and the registry of every hire.
58	- `LOG.md` — dated, append-only journal of what happened and why (team-lead writes it; it is part of the submission).
59	- `.claude/agents/` — one agent definition per hire (model pinned; a once-only per-agent `PreToolUse` hook displays its own persona on its first tool call). `.claude/AGENT_TEMPLATE.md` is the starting point (kept outside the agents directory so it is not registered as an agent type itself).
60	- `02-ai-security-architecture/planning-approach.md` — the agreed Claude-architecture approach: model/effort by role, coordination rules, hand-off standard, dependency order.
61	
62	Rules that hold across every track:
63	- Every agent — lead or hire — has a profile-gen persona (name, temperament, professional history, technical background, stated blind spot). Hires are created text-first with `--output file`; portraits arrive later from `scripts/portrait-queue.sh`. Hires are **never** added as `profile-gen` markers in any `CLAUDE.md` — only the six markers that exist today.
64	- Hires do not spawn subagents. Only track leads (and team-lead) authorize or run deep research (patents, whitepapers, standards, primary sources); hires request it from their lead.
65	- Tracks never modify root-level state (this file, the root persona, root config); flag it to team-lead instead.
66	- **Decisions already made are not re-asked.** Warren's rulings reach tracks through the PM and are recorded in `LOG.md` and this file. A lead must not raise an `AskUserQuestion` to Warren for a decision that is already on the record (e.g., the deployment target, the public repo, the code go) — it asks the PM by message, which answers from the record or escalates. A dialog left open in a lead's session blocks that lead and everything queued behind it (this cost DevOps an hour on 2026-09-12). Genuinely new decisions that only Warren can make still go to Warren — through the PM.
67	- Hand-offs are files by relative path, written so the receiver can act without re-deriving the sender's reasoning; chat messages signal readiness, they do not carry content.
68	- Edit `CLAUDE.md` files at turn boundaries only (prompt-cache stability). Milestone `git` commits at the end of each phase; no mid-task commits.
69	
70	## Status
71	
72	Planning Phases 0–3 are complete (2026-09-12): five track plans approved, 18 hires live in five lead sessions, every track's Phase 3 debates and hand-offs delivered, and the cross-track consistency pass reported (`decisions/cross-track-consistency.md`: 52 findings, six bounded fixes required before planning is declared done — in progress, owned per finding). Phase 4 is under way: Jira Epics `LT-1`…`LT-5` exist, tracks 01 and 05 are transcribed, 02/03/04 follow the pass fixes. All implementation code was deliberately wiped earlier in the day and none has been written since; **no code until Warren's explicit go-ahead**, which he gives after the PM reports the backlog implementation-ready.
73	
74	<!-- profile-gen:start slug=dana-whitfield -->
75	@profiles/dana-whitfield/dana-whitfield.md
76	<!-- profile-gen:end slug=dana-whitfield -->
77	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/CLAUDE.md"
}

1	# Track: Engineering & Delivery
2	
3	Refer back to `../CLAUDE.md` for the full assignment text and how this track fits with the other four.
4	
5	## Mission
6	
7	Write the actual code that answers all three assignment questions, in Go, implementing the designs the other tracks produce rather than re-deciding them here. Code does not need to be complete or working end-to-end — LoginID cares about the design and reasoning — but it should be structured and readable enough to demonstrate real engineering judgment.
8	
9	## Owns
10	
11	- Question 1: the DAO layer for `user_profile` (name, address, phone) and `user_credential` (username, method, password), written to support multiple backing databases (PostgreSQL/CockroachDB, SQLite, etc.) behind a common interface, per the strategy in `../05-data-ops/CLAUDE.md`.
12	- Question 2: the RESTful API service to search/retrieve `user_profile` data, wired to the authentication mechanism designed in `../02-ai-security-architecture/CLAUDE.md`.
13	- Question 3: the third-party IDP connector service implementing `/auth` and `/identity` against the contracts specified in the assignment, following the connector security design in `../02-ai-security-architecture/CLAUDE.md`.
14	- Project structure, module layout, and inline documentation of design decisions and trade-offs made during implementation.
15	- Test strategy (unit/integration scope, what's stubbed vs. real) — tests don't need full coverage, but the approach should be stated.
16	
17	## Does not own
18	
19	- Deciding the API auth mechanism or threat model — that's `../02-ai-security-architecture/CLAUDE.md`; implement what it specifies.
20	- Deciding the multi-database abstraction strategy or schema — that's `../05-data-ops/CLAUDE.md`; implement what it specifies.
21	- Deployment, containerization, CI/CD — that's `../04-infra-devops/CLAUDE.md`.
22	- Product/industry rationale for why the API is shaped this way — that's `../01-product-industry-research-design/CLAUDE.md`; reference it, don't re-derive it.
23	
24	## Deliverables
25	
26	- Go source implementing questions 1, 2, and 3.
27	- A short README in this directory explaining what's implemented, what's stubbed/mocked, and why, plus which AI tool/workflow was used to produce the code and how.
28	- Any test files demonstrating the stated test strategy.
29	
30	## AI tooling note
31	
32	Record which AI tool/workflow generated this track's code (this project is being built with Claude Code) and how much was AI-authored vs. human-reviewed/edited.
33	
34	## Status
35	
36	Planning complete (2026-09-12): 4 hires spawned and live, `PLAN.md` approved, Service boundaries published in root `PLANNING.md`, four implementation-call decisions ruled (`decisions/go-layout-debate.md`, `error-semantics.md`, `context-propagation.md`, `test-double-strategy.md`), 05's DAO contract accepted (including a second-pass review and 05's resulting `CreateProfileWithCredential` fix), 02's `handoff-03-auth.md` v3 accepted, `backlog.md` written (11 stories, Epic `LT-3`). No `.go`/`.sql`/`go.mod` exists yet — still waiting on Warren's explicit implementation go-ahead.
37	
38	<!-- profile-gen:start slug=renata-cole -->
39	@profiles/renata-cole/renata-cole.md
40	<!-- profile-gen:end slug=renata-cole -->
41	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/PLAN.md"
}

1	# Track 03 (Engineering & Delivery) — Phase 1 Plan
2	
3	## Context
4	
5	Team-lead has asked every track lead to plan in plan mode before any hiring or code. This
6	track (Renata Cole) owns the actual Go implementation of all three assignment questions —
7	the DAO, the REST API, and the IDP connector — so its plan needs to name concrete,
8	Jira-shaped deliverables, propose a 4-hire roster with real personality variance (per
9	`CASTING.md`), decide which decisions in this track deserve a debate pattern versus which are
10	waste, state the dependency order this track already committed to in
11	`../02-ai-security-architecture/planning-approach.md`, and produce the "Service boundaries"
12	section of root `PLANNING.md` that 04 (Theo) is blocked on reading. Nothing here is new
13	strategy — it operationalizes what's already agreed in `planning-approach.md` and the root
14	`CLAUDE.md`'s org section. No code is written in this phase.
15	
16	## 1. Deliverables & tasks (one Jira Story each; Epic = this track)
17	
18	*This table is the Phase 1 planning snapshot (2026-09-12). `backlog.md` (11 stories, Jira Epic `LT-3`) is the current, authoritative, PR-sized expansion — its story descriptions and acceptance criteria supersede this table's "What"/"Acceptance standard" columns wherever they differ. Consult `backlog.md`, not this table, for current story shape, hand-off versions, or acceptance criteria.*
19	
20	| Story | What | Hand-off consumed | Hand-off produced | Acceptance standard |
21	|---|---|---|---|---|
22	| S1. Scaffolding | Go module layout, `cmd/` entrypoints, route wiring, stub handlers, config loading | none (assignment text only) | `PLANNING.md` Service boundaries (this plan, §4 below) | Buildable skeleton; 04 can read the boundaries doc without asking a follow-up question |
23	| S2. DAO per backend | `internal/dao` `Repository` interface + Postgres/CockroachDB/SQLite implementations for `user_profile`, `user_credential` | 05's Go-shaped contract in `../05-data-ops/multi-db-strategy.md` (interface signatures, field types/nullability, credential-method-as-lookup-table note) | none outbound | 03 implements directly from the contract with no re-derivation of schema or interface decisions; if the contract is prose instead of Go signatures, this story is blocked and kicked back to 05 |
24	| S3. REST handlers + auth middleware | Search/retrieve `user_profile` endpoints (Q2) + middleware enforcing 02's scheme | 02's receiver-shaped auth hand-off (token scheme, validation point — the deferred follow-up to `api-auth-design.md` noted in 02's own `CLAUDE.md` Status) | none outbound | Middleware implements the scheme as specified; no alternatives re-litigated in code |
25	| S4. Connector `/auth` + `/identity` | Go client + handlers per the assignment's fixed JSON contracts | 02's `connector-security.md` (token lifecycle: no-cache-by-default, fetch per `/identity` call, discard on return — TTL/refresh apply only to how quickly a re-fetch happens, not to any stored token) | none outbound | Token-lifecycle logic matches 02's spec exactly; endpoint paths/bodies are the assignment's, not re-designed |
26	| S5. Tests | Table-driven unit tests for DAO (mocked driver), handlers (mocked DAO), connector (mocked HTTP), **plus the cross-backend conformance suite 05's per-driver ruling is conditional on (`multi-db-strategy.md` §7) — one suite, written once against the `Repository` interface, run against every backend** (consistency-pass finding F25: this was a requirement with no named deliverable until now; `backlog.md`'s S5 is the current, authoritative expansion of this story) | S1–S4 outputs | none | Stated strategy: unit-heavy, integration deliberately stubbed (assignment doesn't require full end-to-end); documented, not silently absent |
27	| S6. README | What's implemented vs. stubbed/mocked and why; AI tool/workflow used (this plan's own hiring + patterns); test-strategy section must state the hand-written-fake rule from `decisions/test-double-strategy.md` (same-PR fake update on interface change) since that's where LoginID reads the test approach | all of the above | the track's README | A cold reader can tell what runs vs. what's a stub without asking |
28	
29	## 2. Hire roster — 4 hires (suggested cast from `CASTING.md`, adopted as-is)
30	
31	All four: **model sonnet** (planning/design/implementation tier per `planning-approach.md`;
32	opus is reserved for the connector token-lifecycle *implementation* seat in a later phase, not
33	planning — none of these four need it now). No hire spawns subagents; no CLAUDE.md marker;
34	profile-gen text-first, after "hiring go".
35	
36	**Oren Castellan — Detail Hawk, code reviewer.** *Function:* second-pass review on DAO/handler/connector Go for error semantics, nullability, off-by-one — the review-seat Renata asked for on her own output, plus the independent pass 02 called for on security-graded surfaces. *Tags:* serious, cautious. *Pattern/role:* rotating devil's advocate seat (implementation calls); second-pass reviewer on S3/S4.
37	
38	*Persona:* Meticulous and understated; in review he goes quiet, then produces a numbered list nobody else caught. Decides by tracing every input to its type and zero value before trusting a code path. Pushes back on "the happy path handles it" and on errors swallowed with `_`. Eight years reviewing Go services at a logistics company, two more doing contract review for a fintech's PCI-scoped repos. Deep in `go vet`/`staticcheck`, table-driven tests, and nil-vs-empty-slice distinctions. Blind spot: he can spend an hour on a rare nullability edge case while missing that the function solves the wrong problem — pair him with someone who checks the solution's shape first. In disagreement he stays procedural, names the specific line and failure, and drops it once satisfied. (129 words)
39	
40	**Nolan Reyes — Veteran, ops/migrations/token-lifecycle sanity.** *Function:* pattern-matches implementation and layout decisions against real production failure modes; pessimist hat in the Go-layout three-hats run. *Tags:* serious, cautious. *Pattern/role:* three-hats pessimist (Go layout); rotating devil's advocate participant.
41	
42	*Persona:* Dry and unhurried; opens reviews with what broke last time he saw this pattern in production. Decides from incident history more than documentation. Pushes back on any "this will just work" claim about retries, timeouts, or token refresh under load. Eleven years in platform ops — six at a regional bank's card-issuing platform, five running SRE for a logistics SaaS — paged once for an expired-token cascade and once for a migration that locked a table for forty minutes; never forgot either. Deep in Go's `context` package, connection pooling, and graceful shutdown. Blind spot: he over-indexes on failures he personally lived through and under-weights new ones. Argues by scenario, not principle, and concedes fast when shown a failure mode he hasn't seen. (134 words)
43	
44	**Marisol Ferran — Enthusiast, Renata's temperament opposite (required).** *Function:* pushes for trying the promising-but-unproven tool (codegen, generics) rather than the safe default; optimist hat in three-hats. *Tags:* playful, bold. *Pattern/role:* three-hats optimist (Go layout); counterweight voice on S2's driver-abstraction choice.
45	
46	*Persona:* Bright and quick to say "let's just try it" before the room finishes weighing options; energized by tools that remove boilerplate. Decides by prototyping fast and showing the result rather than arguing it abstractly. Pushes back on "we've always done it this way" and on process that delays the first line of code by a week. Four years building internal tools at a logistics startup, two more at a small dev-tools shop evaluating codegen and ORM options for clients. Comfortable with `sqlc`, Go generics, and OpenAPI-driven scaffolding. Blind spot: she underweights the years-long operational cost of a clever tool and can talk a team into a dependency nobody wants to own. In disagreement she stays upbeat, offers to build the smaller version on the spot, and yields once the maintenance cost is spelled out. (141 words)
47	
48	**Ines Dabrowski — Systems Cartographer, Go layout / service topology.** *Function:* owns the diagramming behind the Service boundaries decision below; draws the package/dependency map before anyone commits to prose. *Tags:* serious, bold. *Pattern/role:* drafts the Service boundaries doc (§4); non-hat contributor to three-hats as tie-break if optimist/pessimist stall.
49	
50	*Persona:* Calm and visual; sketches a box-and-arrow diagram before committing an opinion to words. Decides by mapping every boundary and dependency first, then asking what crosses it and why. Pushes back on two services sharing a package for convenience rather than a real shared concern. Seven years as a platform engineer at a multi-tenant SaaS company, three designing service boundaries for a payments integration team. Strong on Go module layout, dependency direction, and where an interface should live versus where it's implemented. Blind spot: she can over-abstract a boundary that would have been fine as one package at this project's size, mistaking cleanliness for necessity. In disagreement she draws the alternative rather than argues it, and updates the diagram in front of the room when persuaded. (135 words)
51	
52	Roster spans both required axes (serious/playful via Marisol; cautious/bold via Ines and
53	Marisol), includes Renata's required opposite (Marisol), and duplicates no archetype from
54	another track's *function* (Detail Hawk here is a code reviewer; 05's Detail Hawk is a DDL
55	reviewer, a different function — allowed per variance rule 2).
56	
57	## 3. Debate plan
58	
59	- **Three hats — Go layout (one binary vs. two).** Marisol (optimist: ship one binary, less
60	  ceremony) / Nolan (pessimist: two binaries, because a shared-everything binary is how a
61	  card-issuing platform he worked on ended up with the connector's outbound vendor calls
62	  taking down the client-facing API during an incident) / **Renata takes the pragmatist hat
63	  herself** rather than hiring a fifth (catalog explicitly allows this) — she's the
64	  Minimalist-leaning lead per `CASTING.md` §7. Ines drafts the resulting diagram either way.
65	  Decision recorded in `decisions/go-layout-debate.md`.
66	- **Rotating devil's advocate — implementation calls.** Error semantics (wrap vs. sentinel
67	  errors), context propagation into the DAO layer, test-double strategy (interface fakes vs.
68	  generated mocks). Seat rotates Oren → Nolan → Marisol → Ines per decision so no one hire
69	  becomes "the objector." Cheapest pattern; run on every non-trivial implementation call in
70	  S2–S4.
71	
72	  *(Consistency-pass finding F47: this section named "Callum" as the pessimist/rotation-2 hire
73	  through Phase 1 while the actual roster in §2 above was already "Nolan Reyes" — Callum
74	  Reyes was renamed to clear a first-name collision with 04's Callum Ferreira before hiring;
75	  this section simply hadn't been updated to match. Fixed above; no roster change.)*
76	- **Newcomer's-question pass on hand-offs — run by Renata herself, not a hired Newcomer.**
77	  This track wasn't allocated a Newcomer seat (04 has one; hiring a second here would exceed
78	  the intent of a 4-hire cap for marginal gain). Renata reads 05's `multi-db-strategy.md` and
79	  02's receiver-shaped hand-offs cold, the moment they land, and lists anything she can't act
80	  on without re-deriving the sender's reasoning — same test the pattern exists to run, just
81	  performed by the actual receiver instead of a proxy.
82	- **Explicit waste:** the `/auth` and `/identity` endpoint paths and JSON bodies are fixed by
83	  the assignment text — never debated. Red team/blue team is 02's pattern for the token
84	  lifecycle's security properties, not this track's to re-run; 03 only debates *how* it
85	  implements what 02 specifies (error handling, retries), never *whether* the scheme is right.
86	
87	## 4. Dependencies (and the Service boundaries output for 04)
88	
89	**Split start**, consistent with `planning-approach.md` §2: S1 (scaffolding) starts as soon as
90	hiring completes — no upstream blocker. S2 (DAO) is blocked on 05's Go-shaped contract landing
91	*stable* (not polished — unlikely to be rewritten). S3's middleware is blocked on 02's
92	receiver-shaped auth hand-off; S3's route wiring and non-auth handler logic can start earlier.
93	S4 is blocked on 02's `connector-security.md` token-lifecycle spec, which already exists in
94	prose form — implementable now, refined if 02's deferred receiver-shaped version changes
95	anything.
96	
97	**Service boundaries (written into root `PLANNING.md` alongside this plan):**
98	
99	*This subsection is the Phase 1 snapshot (2026-09-12, before hiring). Root `PLANNING.md`'s
100	Service boundaries section is the current, authoritative version — it has since gained
101	`internal/app` (shared bootstrap, `decisions/go-layout-debate.md`), `DB_DSN_FILE` (02's
102	`handoff-04-secrets.md` S7), literal `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` values, and the
103	connector's own audience/client-credential variables (consistency-pass F15). Consult
104	`PLANNING.md`, not this snapshot, for what 04 or anyone else should build against.*
105	
106	- **Two binaries**, not one: `cmd/api-service` (Q1 DAO + Q2 REST API, client-facing, bearer-
107	  token auth) and `cmd/idp-connector` (Q3, outbound-only to vendors). Reasoning: different
108	  threat models and auth surfaces per 02's track, independent scaling/deploy needs, and it
109	  mirrors the assignment's own Q2/Q3 split rather than inventing a new boundary.
110	- **Package layout:**
111	  ```
112	  cmd/api-service/main.go
113	  cmd/idp-connector/main.go
114	  internal/dao/        # Repository interface + postgres/cockroachdb/sqlite implementations
115	  internal/model/      # shared structs: UserProfile, UserCredential
116	  internal/api/         # REST handlers, router, auth middleware
117	  internal/connector/   # /auth, /identity client + handlers
118	  internal/config/      # env-var config loading, shared by both binaries
119	  ```
120	- **Config surface:** environment variables only (12-factor, container-friendly for 04) —
121	  `DB_DRIVER` (postgres|cockroachdb|sqlite), `DB_DSN`, `HTTP_ADDR`, `AUTH_JWT_ISSUER` /
122	  `AUTH_JWT_AUDIENCE` (names pending 02's final scheme), `IDP_ABC_BASE_URL`,
123	  `IDP_ABC_CLIENT_ID` / `IDP_ABC_CLIENT_SECRET`. No flags, no config files.
124	- **DAO driver-selection mechanism:** a factory `dao.New(driver, dsn string) (dao.Repository, error)`
125	  chosen at startup from `DB_DRIVER`; every backend satisfies one `Repository` interface
126	  (exact method signatures finalized once 05's contract lands — the factory *shape* is stable
127	  now, its return type's method set is not).
128	- **What 04 may treat as stable:** the two-binary split, the `cmd/` entrypoint names, the
129	  env-var config approach and the variable names above, and the `dao.New(driver, dsn)` factory
130	  signature. **Not yet stable:** internal DAO implementation details, ORM/query-builder choice,
131	  and handler-package internals — those can still shift as 05's and 02's hand-offs land.
132	
133	## Amendment: QA function (2026-09-12, Warren's agile-loop go-ahead)
134	
135	**Oren Castellan leads QA** (unit, integration, and the end-to-end/UX acceptance tests written from the PO's review script); **Nolan Reyes supports**. 02's independent second review still applies on top of this for every `security-graded` story — QA and 02's review are not the same gate.
136	
137	## Verification
138	
139	- `PLAN.md` for this track matches this file verbatim once copied.
140	- `PLANNING.md` row 03 updated to "plan drafted — awaiting hiring go"; Service boundaries
141	  section replaces its "TBD" with the content in §4 above.
142	- No `.go`, `.sql`, `go.mod`, or agent-definition files exist yet — only prose changed.
143	- Roster (4 hires) checked against `CASTING.md` variance rules before messaging team-lead:
144	  no archetype repeated within this team; Renata's required opposite (Enthusiast) present;
145	  two temperament axes spanned; no first name collides with any lead.
146	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/profiles/nolan-reyes/nolan-reyes.md"
}

1	---
2	schema_version: 1
3	name: "Nolan Reyes"
4	slug: "nolan-reyes"
5	image: "profiles/nolan-reyes/nolan-reyes.png"
6	
7	nsfw: false
8	display:
9	  image: true
10	  name: true
11	  autostart: false
12	generation:
13	  backend: "comfyui"
14	  model: "comfyui-workflow.json"
15	  prompt: "Nolan Reyes, a dry and unhurried man in his mid 40s with graying short hair, weathered calm expression, wearing a simple gray quarter-zip pullover, head-and-shoulders portrait, centered, neutral light gray studio background, professional corporate headshot photography, soft studio lighting, sharp focus, photorealistic"
16	  negative_prompt: blurry, low quality, distorted, extra limbs, watermark, text, nsfw, nude, nudity, explicit, sexual content
17	  seed: null
18	  gif_mode: null
19	  created_at: "2026-09-12T00:00:00Z"
20	---
21	
22	# Nolan Reyes
23	
24	![Nolan Reyes](profiles/nolan-reyes/nolan-reyes.png)
25	
26	
27	## Personality
28	
29	Dry and unhurried; opens reviews with what broke last time he saw this pattern in production. Decides from incident history more than documentation. Pushes back on any "this will just work" claim about retries, timeouts, or token refresh under load. Eleven years in platform ops — six at a regional bank's card-issuing platform, five running SRE for a logistics SaaS — paged once for an expired-token cascade and once for a migration that locked a table for forty minutes; never forgot either. Deep in Go's `context` package, connection pooling, and graceful shutdown. Blind spot: he over-indexes on failures he personally lived through and under-weights new ones. Argues by scenario, not principle, and concedes fast when shown a failure mode he hasn't seen.
30	
31	

{
  "command": "gh pr view 30 --repo wtvamp/loginid-takehome 2>&1"
}

title:	LT-40: JWT verification middleware, live router wiring
state:	OPEN
author:	wtvamp (Warren Thompson)
labels:	
assignees:	
reviewers:	
projects:	
milestone:	
number:	30
url:	https://github.com/wtvamp/loginid-takehome/pull/30
additions:	1565
deletions:	1
auto-merge:	disabled
--
## Summary

Implements `handoff-03-auth.md` v3/v4's verifier side and wires LT-39's already-built handlers into `cmd/api-service`'s real router, per `refinement/LT-40.md`. This is the story that turns LT-32's issuer split, LT-39's handlers, and LT-34's health endpoint into an actual authenticated, reachable public endpoint.

## What's new

- **`internal/api/jwks.go`** — a minimal RFC 7517 JWKS client: parses RSA public keys, caches the fetched key set with a TTL matching the token TTL's upper bound (per v4's guidance). A stale-but-present cache survives a transient fetch failure rather than hard-failing every request. Supports a `kid` rotation overlap window by construction (caches the whole published key set, not just the newest key).
- **`internal/api/jwtmiddleware.go`** — the verifier, using `golang-jwt/jwt/v5`:
  - Algorithm pinned to RS256 via `jwt.WithValidMethods` on every parse, never left to the library default. Tested against both RFC 8725 §3.1 attacks named in the spec: a bare `alg:none` token, and an HS256 token forged using the RSA public key's DER bytes as the HMAC secret — both rejected before signature verification is attempted.
  - Public-key-only verification, structurally: nothing in `internal/api` or the verifying binary's path ever references signing-key material.
  - `kid`-based key selection with a real rotation-overlap test (two tokens, two `kid`s, one `KeySource` configured with both, both verify).
  - `iss`/`aud`/`exp`/`sub` checked explicitly; `scope` claim disambiguation: a token naming zero or more than one recognized scope is rejected outright rather than silently picking one (matches this project's standing rule against invented authorization ambiguity — `AuthContext` carries exactly one `Scope` by LT-39's own design).
  - Verification failure returns 401 via the existing `writeUnauthorized` — the actual integration seam with LT-39, not new response-shape design.
  - `NewDeadlineMiddleware` applies a concrete `deadlineBudget` (5s) to every request — the number `decisions/context-propagation.md`'s ruling required, composed outermost so it covers JWT verification (including a JWKS cache-miss fetch) and the handler's DAO call under one budget.
- **`internal/api/stopgap_authorizer.go`** — `StopgapAuthorizer`, a **temporary default-deny** `Authorizer`, per Marcus Ilori's (02) direct ruling after being asked before this was wired to a live URL: a permissive allow-all stand-in must never be deployed to a live public URL. Hard-coded `(sub -> allowed record id)` map, seeded via config for LT-51's QA credential; empty by default (denies everything).
- **`internal/api/grantlimiter.go`** — `GrantLimiter`, the token-issuing endpoint's own failed-grant rate limiting and progressive backoff per `client_id` **and** per source IP independently, with alerting on a sustained failure run against one `client_id` (once per threshold crossing). Genuinely separate from the resource-API `RateLimiter`. Not wired to a live endpoint here (real token issuance is LT-51's scope) — built and tested now so LT-51 doesn't also have to design this under its own deadline.
- **`internal/app/verifier_router.go`** — `NewVerifierRouter` builds the real authenticated router for `ModeVerifier`: `/healthz` plus `POST /profiles/search` and `GET /profiles/{id}` behind `NewDeadlineMiddleware(NewJWTMiddleware(...))`, wired to real `RateLimiter`/`TouchCounter` (2,000 distinct records per rolling 24h, per Marcus's ruling on the number `handoff-03-auth.md` left as "mechanism is your call") and `StdoutAuditLogger`. `cmd/api-service/main.go` now opens a real `dao.Repository` in verifier mode.
- **`internal/config`**: `AUTH_JWKS_URL` (the verifier's only path to public key material) plus the two `StopgapAuthorizer` seed vars.

## Verification

`TestNewVerifierRouter_AuthenticatedSearch_ReachesHandler` proves the whole stack end-to-end, not just piece by piece: signs a real RS256 token, serves a real JWKS document over `httptest`, and confirms a request makes it through deadline middleware, JWT verification, and LT-39's handler to a 200 — the audit log line fires as part of that same request.

`go build`/`go vet` clean. `go test ./... -race` green: 20 new JWT/JWKS tests, 8 new `GrantLimiter` tests, 3 new router-wiring tests, full existing suite unaffected. `gofmt -l` clean.

## What's explicitly not here (per refinement/LT-40.md's non-goals)

Real token issuance logic (`/auth/token`'s actual grant handling) — that's LT-51, sequenced right after this. The real `caller_referral`-backed `Authorizer` — still a stated seam, real implementation is a later story per `handoff-03-auth.md` v3's F8 resolution.

## Live-URL review

Per the refinement doc: LT-40 merges and deploys on its own (verified by the unit/integration tests here), but its live-URL review runs **jointly with LT-51's**, using a real token obtained from `/auth/token` via a dedicated QA client credential — not an out-of-band token.

## Who did the work

- **Renata Cole** (03 Engineering & Delivery, lead) — implementation and tests.
- **Naomi Voss** (01, PO) — refinement, corrected `backlog.md`'s stale rate-limit criterion against LT-39's actual merged shape.
- **Desmond Okafor** (01, claims check) — verified the narrowing against PR #26's real diff, caught two doc-status errors.
- **Tobias Lindqvist** (01, objection) — found the missing token-issuance story (now LT-51), routed to team-lead.
- **Marcus Ilori** (02) — ruled the `StopgapAuthorizer` shape and the touch-cap number (2,000/24h) on direct request before this was wired to a live URL.
- Model: Claude Sonnet 5, via Claude Code.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_011Cuba4JUvrsQCrTdUj4yzk

{
  "command": "gh pr diff 30 --repo wtvamp/loginid-takehome 2>&1"
}

<persisted-output>
Output too large (60.2KB). Full output saved to: /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt

Preview (first 2KB):
diff --git a/cmd/api-service/main.go b/cmd/api-service/main.go
index 5c170ee..9e58604 100644
--- a/cmd/api-service/main.go
+++ b/cmd/api-service/main.go
@@ -10,6 +10,10 @@ import (
 
 	"loginid-takehome/internal/app"
 	"loginid-takehome/internal/config"
+	"loginid-takehome/internal/dao"
+
+	_ "loginid-takehome/internal/dao/postgres" // registers "postgres" and "cockroachdb"
+	_ "loginid-takehome/internal/dao/sqlite"   // registers "sqlite"
 )
 
 func main() {
@@ -24,7 +28,29 @@ func main() {
 	}
 
 	log.Printf("api-service: mode=%s listening on %s", cfg.AppMode, addr)
-	if err := http.ListenAndServe(addr, app.NewRouter("api-service", app.Mode(cfg.AppMode))); err != nil {
+
+	var handler http.Handler
+	switch app.Mode(cfg.AppMode) {
+	case app.ModeVerifier:
+		// The verifying Deployment is the one that talks to the
+		// database (LT-39's search/retrieve handlers) — the issuer
+		// Deployment (below) never needs a Repository at all, since it
+		// only mints tokens.
+		repo, err := dao.New(cfg.DBDriver, cfg.DBDSN)
+		if err != nil {
+			log.Fatalf("api-service: opening DAO repository: %v", err)
+		}
+		handler = app.NewVerifierRouter(cfg, repo)
+	default:
+		// ModeIssuer (and the unrecognized-mode fallback, which
+		// NewRouter itself already logs loudly and treats as verifier —
+		// see app.NewRouter's own doc comment) don't need the full
+		// verifier stack; NewRouter's existing /auth/token placeholder
+		// (LT-32) and /healthz cover both.
+		handler = app.NewRouter("api-service", app.Mode(cfg.AppMode))
+	}
+
+	if err := http.ListenAndServe(addr, handler); err != nil {
 		log.Fatalf("api-service: %v", err)
 	}
 }
diff --git a/go.mod b/go.mod
index acc3f60..eaf1188 100644
--- a/go.mod
+++ b/go.mod
@@ -3,6 +3,7 @@ module loginid-takehome
 go 1.27.1
 
 require (
+	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.11.0
 	modernc.org/sqlite v1.58.0
diff --git a/go.sum b/go.sum
index 0863108..cf541fe 100644
...
</persisted-output>

{
  "command": "awk '/^diff --git a\\/internal\\/api\\/jwks.go/,/^diff --git a\\/internal\\/api\\/jwtmiddleware.go/' \"/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt\" | head -300"
}

diff --git a/internal/api/jwks.go b/internal/api/jwks.go
new file mode 100644
index 0000000..9289dea
--- /dev/null
+++ b/internal/api/jwks.go
@@ -0,0 +1,164 @@
+// jwks.go implements a minimal RFC 7517 JSON Web Key Set client: fetch,
+// parse RSA public keys, cache with a short TTL. handoff-03-auth.md v4:
+// "Public-key distribution for the verifier ... JWKS served by the issuer
+// Deployment, reachable only in-cluster via its own ClusterIP Service ...
+// Verifier caches the fetched key set in memory with a short TTL (matching
+// token TTL is reasonable) to avoid a JWKS fetch on every single
+// verification."
+package api
+
+import (
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/big"
+	"net/http"
+	"sync"
+	"time"
+)
+
+// jwk is one entry in a JWKS response — only the fields this verifier
+// needs to reconstruct an RSA public key (RFC 7517 §4, RFC 7518 §6.3.1).
+// Fields this verifier doesn't use (x5c, x5t, ...) are simply not
+// unmarshaled; unknown fields in the source JSON are not an error.
+type jwk struct {
+	Kty string `json:"kty"`
+	Kid string `json:"kid"`
+	Alg string `json:"alg"`
+	Use string `json:"use"`
+	N   string `json:"n"` // base64url, unpadded — the RSA modulus
+	E   string `json:"e"` // base64url, unpadded — the RSA public exponent
+}
+
+type jwksResponse struct {
+	Keys []jwk `json:"keys"`
+}
+
+// parseJWKS decodes a JWKS JSON document into a map of kid -> public key.
+// Any key with kty != "RSA" is skipped (not an error) — a future non-RSA
+// key in the set (e.g. during an algorithm migration) shouldn't break
+// verification of tokens signed with the RSA keys that ARE present.
+func parseJWKS(data []byte) (map[string]*rsa.PublicKey, error) {
+	var resp jwksResponse
+	if err := json.Unmarshal(data, &resp); err != nil {
+		return nil, fmt.Errorf("api: parsing JWKS: %w", err)
+	}
+	keys := make(map[string]*rsa.PublicKey, len(resp.Keys))
+	for _, k := range resp.Keys {
+		if k.Kty != "RSA" {
+			continue
+		}
+		if k.Kid == "" {
+			return nil, fmt.Errorf("api: JWKS RSA key missing kid")
+		}
+		pub, err := rsaPublicKeyFromJWK(k)
+		if err != nil {
+			return nil, fmt.Errorf("api: JWKS key %q: %w", k.Kid, err)
+		}
+		keys[k.Kid] = pub
+	}
+	return keys, nil
+}
+
+func rsaPublicKeyFromJWK(k jwk) (*rsa.PublicKey, error) {
+	nBytes, err := base64.RawURLEncoding.DecodeString(k.N)
+	if err != nil {
+		return nil, fmt.Errorf("decoding n: %w", err)
+	}
+	eBytes, err := base64.RawURLEncoding.DecodeString(k.E)
+	if err != nil {
+		return nil, fmt.Errorf("decoding e: %w", err)
+	}
+	n := new(big.Int).SetBytes(nBytes)
+	e := new(big.Int).SetBytes(eBytes)
+	if !e.IsInt64() {
+		return nil, fmt.Errorf("exponent out of range")
+	}
+	return &rsa.PublicKey{N: n, E: int(e.Int64())}, nil
+}
+
+// KeySource resolves a kid to the RSA public key that should verify a
+// token carrying it. JWKSCache is the real implementation; tests use a
+// map-backed fake.
+type KeySource interface {
+	KeyForKid(kid string) (*rsa.PublicKey, error)
+}
+
+// JWKSCache fetches a JWKS document from url and caches the parsed key
+// set for ttl, refetching only after it expires — "to avoid a JWKS fetch
+// on every single verification" (handoff-03-auth.md v4). Supports at
+// least two concurrently valid kids during a rotation overlap window by
+// construction: it caches the WHOLE key set the issuer publishes, not
+// just the most recent key, so an old and a new key both verify
+// successfully for as long as the issuer's own JWKS response lists both.
+type JWKSCache struct {
+	url        string
+	ttl        time.Duration
+	httpClient *http.Client
+
+	mu        sync.Mutex
+	keys      map[string]*rsa.PublicKey
+	fetchedAt time.Time
+}
+
+// NewJWKSCache constructs a cache fetching from url, refetching at most
+// once per ttl. A nil httpClient uses http.DefaultClient.
+func NewJWKSCache(url string, ttl time.Duration, httpClient *http.Client) *JWKSCache {
+	if httpClient == nil {
+		httpClient = http.DefaultClient
+	}
+	return &JWKSCache{url: url, ttl: ttl, httpClient: httpClient}
+}
+
+func (c *JWKSCache) KeyForKid(kid string) (*rsa.PublicKey, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if c.keys == nil || time.Since(c.fetchedAt) >= c.ttl {
+		keys, err := c.fetch()
+		if err != nil {
+			// A stale-but-present cache is preferable to a hard failure
+			// on every request the moment one refresh fails (a
+			// transient network blip to the issuer's in-cluster
+			// Service) — verification with a stale key set still
+			// correctly rejects a token signed by a kid that's been
+			// fully retired and removed from the real set, it just
+			// risks accepting a very recently rotated-in key slightly
+			// late, which is not a security regression (the overlap
+			// window already tolerates both old and new keys).
+			if c.keys == nil {
+				return nil, err
+			}
+		} else {
+			c.keys = keys
+			c.fetchedAt = time.Now()
+		}
+	}
+
+	key, ok := c.keys[kid]
+	if !ok {
+		return nil, fmt.Errorf("api: no key found for kid %q", kid)
+	}
+	return key, nil
+}
+
+func (c *JWKSCache) fetch() (map[string]*rsa.PublicKey, error) {
+	resp, err := c.httpClient.Get(c.url)
+	if err != nil {
+		return nil, fmt.Errorf("api: fetching JWKS from %s: %w", c.url, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("api: fetching JWKS from %s: status %d", c.url, resp.StatusCode)
+	}
+	// 1MiB ceiling — a JWKS response is a handful of RSA keys, never
+	// this large; capped so a misbehaving/compromised issuer endpoint
+	// can't force this process to buffer an unbounded response body.
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("api: reading JWKS response: %w", err)
+	}
+	return parseJWKS(body)
+}
diff --git a/internal/api/jwks_test.go b/internal/api/jwks_test.go
new file mode 100644
index 0000000..7478b48
--- /dev/null
+++ b/internal/api/jwks_test.go
@@ -0,0 +1,194 @@
+package api
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+func jwkFromPublicKey(kid string, pub *rsa.PublicKey) jwk {
+	return jwk{
+		Kty: "RSA",
+		Kid: kid,
+		Alg: "RS256",
+		Use: "sig",
+		N:   base64.RawURLEncoding.EncodeToString(pub.N.Bytes()),
+		E:   base64.RawURLEncoding.EncodeToString(bigEndianExponent(pub.E)),
+	}
+}
+
+func bigEndianExponent(e int) []byte {
+	// Standard RSA public exponent (65537) fits in 3 bytes; encode
+	// minimally, matching how real JWKS producers encode "e".
+	b := []byte{byte(e >> 16), byte(e >> 8), byte(e)}
+	i := 0
+	for i < len(b)-1 && b[i] == 0 {
+		i++
+	}
+	return b[i:]
+}
+
+func TestParseJWKS_RoundTrip(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	doc := jwksResponse{Keys: []jwk{jwkFromPublicKey("key-1", &key.PublicKey)}}
+	data, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatalf("marshaling JWKS: %v", err)
+	}
+
+	keys, err := parseJWKS(data)
+	if err != nil {
+		t.Fatalf("parseJWKS: %v", err)
+	}
+	got, ok := keys["key-1"]
+	if !ok {
+		t.Fatal("parsed key set missing key-1")
+	}
+	if got.N.Cmp(key.PublicKey.N) != 0 || got.E != key.PublicKey.E {
+		t.Error("parsed public key does not match the original")
+	}
+}
+
+func TestParseJWKS_SkipsNonRSAKeys(t *testing.T) {
+	data := []byte(`{"keys":[{"kty":"EC","kid":"ec-1","crv":"P-256","x":"AAAA","y":"AAAA"}]}`)
+	keys, err := parseJWKS(data)
+	if err != nil {
+		t.Fatalf("parseJWKS: %v", err)
+	}
+	if len(keys) != 0 {
+		t.Errorf("expected a non-RSA key to be skipped, got %d keys", len(keys))
+	}
+}
+
+func TestParseJWKS_MissingKidIsError(t *testing.T) {
+	data := []byte(`{"keys":[{"kty":"RSA","n":"AAAA","e":"AQAB"}]}`)
+	if _, err := parseJWKS(data); err == nil {
+		t.Error("expected an error for an RSA key with no kid")
+	}
+}
+
+func TestJWKSCache_FetchesAndCaches(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	doc := jwksResponse{Keys: []jwk{jwkFromPublicKey("key-1", &key.PublicKey)}}
+	body, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatalf("marshaling JWKS: %v", err)
+	}
+
+	requests := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests++
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(body)
+	}))
+	defer srv.Close()
+
+	cache := NewJWKSCache(srv.URL, time.Hour, nil)
+	if _, err := cache.KeyForKid("key-1"); err != nil {
+		t.Fatalf("first KeyForKid: %v", err)
+	}
+	if _, err := cache.KeyForKid("key-1"); err != nil {
+		t.Fatalf("second KeyForKid: %v", err)
+	}
+	if requests != 1 {
+		t.Errorf("fetched the JWKS endpoint %d times, want exactly 1 (cached within TTL)", requests)
+	}
+}
+
+func TestJWKSCache_RefetchesAfterTTLExpires(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	doc := jwksResponse{Keys: []jwk{jwkFromPublicKey("key-1", &key.PublicKey)}}
+	body, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatalf("marshaling JWKS: %v", err)
+	}
+
+	requests := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests++
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(body)

{
  "command": "grep -n \"NewVerifierRouter\\|NewDeadlineMiddleware\\|deadlineBudget\" -r \"/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt\" | head -50"
}

/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:33:+		handler = app.NewVerifierRouter(cfg, repo)
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:956:+// deadlineBudget is the context.WithTimeout duration this middleware
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:965:+// is bounded by deadlineBudget itself, not a separate timeout, since it
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:969:+const deadlineBudget = 5 * time.Second
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:971:+// NewDeadlineMiddleware applies deadlineBudget to every request's
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:978:+func NewDeadlineMiddleware(next http.Handler) http.Handler {
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:980:+		ctx, cancel := context.WithTimeout(r.Context(), deadlineBudget)
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1332:+	h := NewDeadlineMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1340:+		t.Error("request context should carry a deadline after NewDeadlineMiddleware")
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1426:+// NewVerifierRouter builds api-service's real, authenticated router —
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1438:+func NewVerifierRouter(cfg config.Config, repo dao.Repository) http.Handler {
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1456:+	// api.NewDeadlineMiddleware outermost: the deadline budget must cover
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1462:+		return api.NewDeadlineMiddleware(authMiddleware(h))
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1595:+func TestNewVerifierRouter_UnauthenticatedRequest_401(t *testing.T) {
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1604:+	router := NewVerifierRouter(cfg, &fakeRepo{})
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1614:+// TestNewVerifierRouter_AuthenticatedSearch_ReachesHandler proves the
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1619:+func TestNewVerifierRouter_AuthenticatedSearch_ReachesHandler(t *testing.T) {
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1628:+	router := NewVerifierRouter(cfg, &fakeRepo{})
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1640:+func TestNewVerifierRouter_HealthzUnaffectedByAuth(t *testing.T) {
/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt:1642:+	router := NewVerifierRouter(cfg, &fakeRepo{})

{
  "command": "awk '/^diff --git a\\/internal\\/api\\/jwtmiddleware.go/,/^diff --git a\\/internal\\/api\\/jwtmiddleware_test.go/' \"/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt\""
}

diff --git a/internal/api/jwtmiddleware.go b/internal/api/jwtmiddleware.go
new file mode 100644
index 0000000..07ed3d0
--- /dev/null
+++ b/internal/api/jwtmiddleware.go
@@ -0,0 +1,209 @@
+// jwtmiddleware.go is LT-40's core: verify the client-credentials JWT
+// scheme from handoff-03-auth.md v3/v4 and populate AuthContext for
+// LT-39's already-built handlers. This is the actual integration seam
+// with S6's work, not new response-shape design — a verification failure
+// uses the exact same writeUnauthorized this package's handlers already
+// call for a missing AuthContext.
+package api
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// jwtAlgorithm is the one signing algorithm this verifier ever accepts.
+// Passed explicitly to jwt.WithValidMethods on every parse — never left
+// to the library's default, per handoff-03-auth.md v3's explicit
+// instruction ("check your JWT library's default behavior — several
+// popular libraries have shipped this vulnerability by not doing this by
+// default") and RFC 8725 §3.1. This is what makes alg:none and an
+// HMAC-with-the-public-key-as-secret downgrade both fail before the
+// library ever calls KeySource — jwt/v5's WithValidMethods rejects a
+// token whose header alg isn't in this allowlist ahead of signature
+// verification, not as a secondary check after.
+const jwtAlgorithm = "RS256"
+
+// claims is this service's JWT claim set (handoff-03-auth.md v3's
+// minimum: sub, scope, exp, iat, aud, plus iss and kid via the header).
+// RegisteredClaims gives exp/iat/iss/aud validation for free from the
+// library — this verifier still explicitly re-checks Audience below
+// because jwt/v5's built-in audience check (via WithAudience) does not
+// distinguish "no aud claim at all" from "aud present but empty," and a
+// token with no audience claim must not silently pass as if it matched.
+type claims struct {
+	Scope string `json:"scope"`
+	jwt.RegisteredClaims
+}
+
+// jwtVerifier is the collaborator NewJWTMiddleware wraps — an interface
+// so a test can supply a fake instead of a real *JWKSCache doing network
+// I/O, mirroring this package's existing test-double approach
+// (decisions/test-double-strategy.md).
+type jwtVerifier struct {
+	keys     KeySource
+	issuer   string
+	audience string
+}
+
+// verify parses and fully validates tokenString, returning the populated
+// AuthContext on success. Every failure returns a generic error — the
+// specific reason (expired, wrong audience, bad signature, unknown kid,
+// disallowed algorithm) is never distinguishable to the caller of this
+// function beyond "verification failed," which is what makes
+// writeUnauthorized's single, undifferentiated 401 body correct here
+// without an extra translation step.
+func (v *jwtVerifier) verify(tokenString string) (AuthContext, error) {
+	var c claims
+	token, err := jwt.ParseWithClaims(tokenString, &c, func(t *jwt.Token) (any, error) {
+		kid, _ := t.Header["kid"].(string)
+		if kid == "" {
+			return nil, errors.New("token header has no kid")
+		}
+		return v.keys.KeyForKid(kid)
+	}, jwt.WithValidMethods([]string{jwtAlgorithm}), jwt.WithIssuer(v.issuer))
+	if err != nil {
+		return AuthContext{}, err
+	}
+	if !token.Valid {
+		return AuthContext{}, errors.New("token invalid")
+	}
+
+	// Audience checked explicitly, not via jwt.WithAudience above: v5's
+	// audience option treats an all-nil/absent Audience claim
+	// inconsistently across versions in a way we don't want to depend
+	// on — asserting it here directly means this check's behavior is
+	// this file's own to guarantee, not the library's default to trust.
+	if !hasAudience(c.RegisteredClaims.Audience, v.audience) {
+		return AuthContext{}, errors.New("token audience mismatch")
+	}
+
+	if c.Subject == "" {
+		return AuthContext{}, errors.New("token has no sub claim")
+	}
+
+	scope, err := singleScope(c.Scope)
+	if err != nil {
+		return AuthContext{}, err
+	}
+
+	return AuthContext{Sub: c.Subject, Scope: scope}, nil
+}
+
+func hasAudience(aud jwt.ClaimStrings, want string) bool {
+	for _, a := range aud {
+		if a == want {
+			return true
+		}
+	}
+	return false
+}
+
+// singleScope requires the token's scope claim to name exactly one
+// recognized scope. handoff-03-auth.md v3 describes the claim as
+// "space-delimited, values below" without describing how a handler
+// disambiguates a multi-scope token per request, and AuthContext (LT-39)
+// carries exactly one Scope by design ("handoff-03-auth.md v3 doesn't
+// describe multi-scope tokens being disambiguated per-request, so one
+// request carries exactly one Scope"). Rather than guess which of
+// several granted scopes a request is "really" using — silently picking
+// one is exactly the kind of authorization ambiguity this project's
+// contracts have consistently ruled against — a token naming zero or
+// more than one recognized scope is rejected outright. This matches the
+// provisioning model in decisions/search-authz-scoping.md: a client is
+// provisioned for the one use case its credential exists for.
+func singleScope(raw string) (Scope, error) {
+	fields := strings.Fields(raw)
+	var found []Scope
+	for _, f := range fields {
+		switch Scope(f) {
+		case ScopeReadOwn, ScopeReadAny, ScopeSearch:
+			found = append(found, Scope(f))
+		}
+	}
+	switch len(found) {
+	case 0:
+		return "", errors.New("token scope claim names no recognized scope")
+	case 1:
+		return found[0], nil
+	default:
+		return "", errors.New("token scope claim names more than one recognized scope, which this verifier does not disambiguate per request")
+	}
+}
+
+// NewJWTMiddleware verifies every request's bearer token and populates
+// AuthContext on success, per handoff-03-auth.md v3/v4: public-key-only
+// verification (keys never includes signing-key material — enforced
+// structurally, since KeySource's real implementation, JWKSCache, only
+// ever holds *rsa.PublicKey values parsed from a JWKS response), pinned
+// RS256, kid-based key selection supporting a rotation overlap window (a
+// KeySource backed by the issuer's full published key set, not a single
+// cached key), and issuer/audience checks. Verification failure returns
+// 401 via writeUnauthorized — the same path LT-39's handlers already use
+// for a missing AuthContext, not a new response shape.
+func NewJWTMiddleware(keys KeySource, issuer, audience string) func(http.Handler) http.Handler {
+	v := &jwtVerifier{keys: keys, issuer: issuer, audience: audience}
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			tokenString, ok := bearerToken(r)
+			if !ok {
+				writeUnauthorized(w)
+				return
+			}
+			ac, err := v.verify(tokenString)
+			if err != nil {
+				writeUnauthorized(w)
+				return
+			}
+			r = r.WithContext(WithAuthContext(r.Context(), ac))
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func bearerToken(r *http.Request) (string, bool) {
+	h := r.Header.Get("Authorization")
+	const prefix = "Bearer "
+	if !strings.HasPrefix(h, prefix) {
+		return "", false
+	}
+	tok := strings.TrimSpace(strings.TrimPrefix(h, prefix))
+	if tok == "" {
+		return "", false
+	}
+	return tok, true
+}
+
+// deadlineBudget is the context.WithTimeout duration this middleware
+// applies to every request before it reaches a handler — the concrete
+// number decisions/context-propagation.md's ruling required ("this gets
+// a concrete number attached when [the middleware] is written, not left
+// as 'some deadline'"). Sized to cover realistic p99 DAO latency
+// (single-digit milliseconds for an indexed Postgres/CockroachDB point
+// query or trigram search, per 05-data-ops/research-cockroachdb-postgres-semantics.md)
+// plus this middleware's own JWKS verification path (a cache hit is
+// sub-millisecond; a cache-miss fetch to the issuer's in-cluster Service
+// is bounded by deadlineBudget itself, not a separate timeout, since it
+// happens inside the same request). 5 seconds leaves an order of
+// magnitude of headroom over expected p99 without ever handing the DAO
+// layer a near-zero remaining deadline as a matter of routine operation.
+const deadlineBudget = 5 * time.Second
+
+// NewDeadlineMiddleware applies deadlineBudget to every request's
+// context before it reaches a handler — the enforcement site
+// decisions/context-propagation.md's ruling named ("a concrete number
+// attached when [the middleware] is written"). Composed outermost (see
+// router wiring), so the budget covers JWT verification (including a
+// JWKS cache-miss fetch) and the handler's own DAO call under one
+// deadline, not two independently-sized timeouts that could disagree.
+func NewDeadlineMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		ctx, cancel := context.WithTimeout(r.Context(), deadlineBudget)
+		defer cancel()
+		next.ServeHTTP(w, r.WithContext(ctx))
+	})
+}
diff --git a/internal/api/jwtmiddleware_test.go b/internal/api/jwtmiddleware_test.go

{
  "command": "awk '/^diff --git a\\/internal\\/api\\/grantlimiter.go/,/^diff --git a\\/internal\\/api\\/grantlimiter_test.go/' \"/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt\""
}

diff --git a/internal/api/grantlimiter.go b/internal/api/grantlimiter.go
new file mode 100644
index 0000000..c70c50c
--- /dev/null
+++ b/internal/api/grantlimiter.go
@@ -0,0 +1,138 @@
+package api
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// GrantLimiter enforces the token-issuing endpoint's own failed-grant
+// rate limiting and progressive backoff — handoff-03-auth.md v3:
+// "Token-endpoint brute-force protection, separate from the resource-API
+// rate limits ... failed-grant rate limiting and progressive backoff per
+// client_id and per source IP on the token-issuing endpoint itself, plus
+// alerting on a sustained run of failed grants against one client_id."
+//
+// This is genuinely separate from RateLimiter (ratelimit.go): that type
+// gates the resource API by an already-authenticated sub, at a fixed
+// per-minute rate; this one gates the endpoint that issues the
+// credential in the first place, keyed independently by client_id AND
+// by source IP — a distributed brute force (many IPs, one client_id)
+// and a single-source credential-stuffing run (one IP, many client_ids)
+// are both attack shapes this is meant to slow down, and either key
+// exceeding its own backoff blocks the attempt.
+//
+// Not wired to a live endpoint by this story: /auth/token's real grant
+// logic is LT-51's scope (this story's non-goals). This is the
+// ready-to-use component LT-51 constructs and calls from the real
+// handler — building it now, tested in isolation, means LT-51 doesn't
+// also have to design a backoff/alerting scheme under its own deadline.
+type GrantLimiter interface {
+	// Allow reports whether a grant attempt for clientID from sourceIP
+	// may proceed right now — false while either key is in backoff.
+	Allow(ctx context.Context, clientID, sourceIP string) (bool, error)
+	// RecordFailure records a failed grant attempt for both clientID and
+	// sourceIP, advancing each key's backoff state independently.
+	// Crossing the alert threshold for a given client_id (not source IP
+	// — the requirement names client_id specifically) fires alert
+	// exactly once per crossing, not once per subsequent failure.
+	RecordFailure(ctx context.Context, clientID, sourceIP string)
+	// RecordSuccess clears backoff state for both clientID and
+	// sourceIP — a successful grant resets the count, standard
+	// exponential-backoff practice: this deters sustained brute force,
+	// it does not permanently degrade a legitimate client that mistyped
+	// a secret once.
+	RecordSuccess(ctx context.Context, clientID, sourceIP string)
+}
+
+// grantBackoffState is one key's (a client_id's, or a source IP's)
+// consecutive-failure bookkeeping.
+type grantBackoffState struct {
+	consecutiveFailures int
+	blockedUntil        time.Time
+	alerted             bool
+}
+
+// InProcessGrantLimiter is an in-process implementation. As with
+// RateLimiter/TouchCounter's in-process implementations, a shared store
+// is the multi-instance replacement behind the same interface — the
+// mechanism is this track's call, per handoff-03-auth.md v3.
+type InProcessGrantLimiter struct {
+	mu             sync.Mutex
+	byClientID     map[string]*grantBackoffState
+	bySourceIP     map[string]*grantBackoffState
+	baseBackoff    time.Duration
+	maxBackoff     time.Duration
+	alertThreshold int
+	alertFn        func(clientID string, consecutiveFailures int)
+	now            func() time.Time
+}
+
+// NewInProcessGrantLimiter constructs a limiter with exponential backoff
+// starting at baseBackoff (doubling per consecutive failure, capped at
+// maxBackoff) and alertFn called once per client_id crossing
+// alertThreshold consecutive failures. alertFn may be nil (no alerting —
+// tests use this; production wiring passes a real sink).
+func NewInProcessGrantLimiter(baseBackoff, maxBackoff time.Duration, alertThreshold int, alertFn func(clientID string, consecutiveFailures int)) *InProcessGrantLimiter {
+	return &InProcessGrantLimiter{
+		byClientID:     make(map[string]*grantBackoffState),
+		bySourceIP:     make(map[string]*grantBackoffState),
+		baseBackoff:    baseBackoff,
+		maxBackoff:     maxBackoff,
+		alertThreshold: alertThreshold,
+		alertFn:        alertFn,
+		now:            time.Now,
+	}
+}
+
+func (l *InProcessGrantLimiter) Allow(_ context.Context, clientID, sourceIP string) (bool, error) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	now := l.now()
+	return !isBlocked(l.byClientID[clientID], now) && !isBlocked(l.bySourceIP[sourceIP], now), nil
+}
+
+func isBlocked(s *grantBackoffState, now time.Time) bool {
+	return s != nil && now.Before(s.blockedUntil)
+}
+
+func (l *InProcessGrantLimiter) RecordFailure(_ context.Context, clientID, sourceIP string) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	now := l.now()
+
+	cs := l.advance(l.byClientID, clientID, now)
+	l.advance(l.bySourceIP, sourceIP, now)
+
+	if cs.consecutiveFailures >= l.alertThreshold && !cs.alerted {
+		cs.alerted = true
+		if l.alertFn != nil {
+			l.alertFn(clientID, cs.consecutiveFailures)
+		}
+	}
+}
+
+// advance increments key's consecutive-failure count and sets its
+// exponential backoff window, creating the state entry if this is its
+// first failure.
+func (l *InProcessGrantLimiter) advance(m map[string]*grantBackoffState, key string, now time.Time) *grantBackoffState {
+	s, ok := m[key]
+	if !ok {
+		s = &grantBackoffState{}
+		m[key] = s
+	}
+	s.consecutiveFailures++
+	backoff := l.baseBackoff << uint(s.consecutiveFailures-1) // 2^(n-1) * base
+	if backoff > l.maxBackoff || backoff <= 0 {               // overflow guard: a left-shifted duration can wrap negative
+		backoff = l.maxBackoff
+	}
+	s.blockedUntil = now.Add(backoff)
+	return s
+}
+
+func (l *InProcessGrantLimiter) RecordSuccess(_ context.Context, clientID, sourceIP string) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	delete(l.byClientID, clientID)
+	delete(l.bySourceIP, sourceIP)
+}
diff --git a/internal/api/grantlimiter_test.go b/internal/api/grantlimiter_test.go

{
  "command": "awk '/^diff --git a\\/internal\\/app\\/verifier_router.go/,/^diff --git a\\/internal\\/app\\/verifier_router_test.go/' \"/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/bk20tvjgo.txt\""
}

diff --git a/internal/app/verifier_router.go b/internal/app/verifier_router.go
new file mode 100644
index 0000000..647e7ab
--- /dev/null
+++ b/internal/app/verifier_router.go
@@ -0,0 +1,75 @@
+package app
+
+import (
+	"net/http"
+	"time"
+
+	"loginid-takehome/internal/api"
+	"loginid-takehome/internal/config"
+	"loginid-takehome/internal/dao"
+)
+
+// jwksCacheTTL matches the token TTL per handoff-03-auth.md v4's own
+// guidance ("Verifier caches the fetched key set in memory with a short
+// TTL (matching token TTL is reasonable)") — using the upper bound of the
+// 5-15 minute TTL range so a cache refresh never fires more often than a
+// token itself could have already expired and been re-issued.
+const jwksCacheTTL = 15 * time.Minute
+
+// NewVerifierRouter builds api-service's real, authenticated router —
+// LT-39's handlers (search/retrieve) wired behind LT-40's JWT
+// verification middleware, plus /healthz. This is the ModeVerifier
+// Deployment's router; the issuer Deployment (ModeIssuer) still uses the
+// plain NewRouter above, since it has no need for any of this — it never
+// verifies inbound tokens, only issues them.
+//
+// repo may be nil (e.g. DB_DRIVER unset in a minimal smoke-test
+// environment); the search/retrieve routes still register in that case,
+// they'll simply fail at the DAO call with whatever error a nil
+// Repository produces — this function's job is wiring, not validating
+// that a database is reachable, which is /healthz's own job (LT-52).
+func NewVerifierRouter(cfg config.Config, repo dao.Repository) http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/healthz", healthHandler("api-service"))
+
+	deps := api.Deps{
+		Repo:        repo,
+		RateLimiter: api.NewInProcessRateLimiter(),
+		TouchCounter: api.NewInProcessTouchCounter(
+			api.TouchCapPerWindow, api.TouchCapWindow),
+		AuditLog: api.StdoutAuditLogger{},
+		Authz: &api.StopgapAuthorizer{
+			ReadOwnAllow: stopgapReadOwnAllow(cfg),
+		},
+	}
+
+	keys := api.NewJWKSCache(cfg.AuthJWKSURL, jwksCacheTTL, nil)
+	authMiddleware := api.NewJWTMiddleware(keys, cfg.AuthJWTIssuer, cfg.AuthJWTAudience)
+
+	// api.NewDeadlineMiddleware outermost: the deadline budget must cover
+	// JWT verification (including a JWKS cache-miss fetch) as well as
+	// the handler's own DAO call, per decisions/context-propagation.md's
+	// ruling — a single deadline, not the middleware's and the handler's
+	// own disagreeing.
+	protect := func(h http.Handler) http.Handler {
+		return api.NewDeadlineMiddleware(authMiddleware(h))
+	}
+
+	mux.Handle("POST /profiles/search", protect(api.NewSearchHandler(deps)))
+	mux.Handle("GET /profiles/{id}", protect(api.NewGetProfileHandler(deps)))
+
+	return mux
+}
+
+// stopgapReadOwnAllow builds StopgapAuthorizer's hard-coded (sub ->
+// allowed record id) map from cfg — empty (denies everything) unless
+// both AuthzQASub and AuthzQAAllowedProfileID are set, which LT-51 does
+// once the QA client credential and a matching seeded profile exist.
+func stopgapReadOwnAllow(cfg config.Config) map[string]map[string]bool {
+	if cfg.AuthzQASub == "" || cfg.AuthzQAAllowedProfileID == "" {
+		return nil
+	}
+	return map[string]map[string]bool{
+		cfg.AuthzQASub: {cfg.AuthzQAAllowedProfileID: true},
+	}
+}
diff --git a/internal/app/verifier_router_test.go b/internal/app/verifier_router_test.go