Tomasz Wrede

{
  "command": "pwd"
}

/Users/warrenthompson/Source/LoginID/02-ai-security-architecture

{
  "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	- Do not write implementation code until Warren gives an explicit, project-wide go-ahead. Design docs, schemas described in prose, plans, and decision records are fine; `.go`, `.sql`, `go.mod`, Dockerfiles, and CI config are not.
48	
49	## Org, hiring, and orchestration
50	
51	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:
52	
53	- `PLAN.md` — the approved org plan for the planning phase (phases, gates, verification). `~/.claude/plans/` is scratch; this is the record.
54	- `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.
55	- `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.
56	- `LOG.md` — dated, append-only journal of what happened and why (team-lead writes it; it is part of the submission).
57	- `.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).
58	- `02-ai-security-architecture/planning-approach.md` — the agreed Claude-architecture approach: model/effort by role, coordination rules, hand-off standard, dependency order.
59	
60	Rules that hold across every track:
61	- 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.
62	- 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.
63	- Tracks never modify root-level state (this file, the root persona, root config); flag it to team-lead instead.
64	- 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.
65	- Edit `CLAUDE.md` files at turn boundaries only (prompt-cache stability). Milestone `git` commits at the end of each phase; no mid-task commits.
66	
67	## Status
68	
69	Design phase complete for all five tracks (see each track's `CLAUDE.md` Status). All implementation code deliberately wiped 2026-09-12; the project is in the **planning phase** described in `PLAN.md`: Phase 0 scaffolding done, Phase 1 (leads plan in plan mode and propose hires) next, then hiring, in-team debates, a cross-track consistency pass, and Jira stories in project `LT`. No code until Warren's explicit go-ahead.
70	
71	<!-- profile-gen:start slug=dana-whitfield -->
72	@profiles/dana-whitfield/dana-whitfield.md
73	<!-- profile-gen:end slug=dana-whitfield -->
74	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/CLAUDE.md"
}

1	# Track: AI Architecture & Security Architecture
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	Own two things that are related but distinct: (1) the story of how AI was used as an architecture and delivery tool across this whole submission, and (2) the security architecture for everything the engineering track builds — the DAO, the REST API, and the third-party IDP connector.
8	
9	LoginID explicitly asked submitters to describe any tool, framework, or AI used — this track is where that answer lives in full, even though other tracks should each note their own AI usage briefly too.
10	
11	## Owns
12	
13	- AI architecture narrative: what Claude Code was used for across the project, how the five-track structure itself was designed and orchestrated (root CLAUDE.md + per-track CLAUDE.md + scoped subagents), what was AI-generated vs. human-directed, and why that workflow was chosen.
14	- Threat modeling for the system: attacker-relevant risks around storing `user_credential` (usernames/passwords), storing and serving `user_profile` PII, and the third-party connector holding vendor `access_token`s.
15	- API authentication/authorization design for the REST service in question 2 — what "security API authentication" means here (e.g., API keys, OAuth2 client credentials, mTLS, or JWT bearer tokens), and why.
16	- Credential handling: password storage (hashing/salting strategy), token lifecycle for third-party `access_token`s from question 3, and secrets management for any credentials this service itself needs to call ABC/XYZ.
17	- Security review of the connector contracts in question 3: what happens to the third-party `access_token` once retrieved, how `/identity` calls are authenticated to the vendor, and what this service should and shouldn't log or persist from a PII/security standpoint.
18	
19	## Does not own
20	
21	- The industry/product framing for why this system exists — that's `../01-product-industry-research-design/CLAUDE.md`.
22	- Writing the Go code itself — that's `../03-engineering-delivery/CLAUDE.md`, though this track's design should be specific enough to implement directly.
23	- Runtime secrets storage mechanics in a deployed environment (e.g., which secrets manager, which CI/CD injects what) — that's `../04-infra-devops/CLAUDE.md`; this track sets the requirement, infra/devops implements it.
24	- Data retention/governance policy for stored PII — that's `../05-data-ops/CLAUDE.md`; this track covers security of access and transit, not lifecycle/retention.
25	
26	## Deliverables
27	
28	- A written AI-tooling/workflow summary for the whole project.
29	- A threat model covering credential storage, PII exposure, and third-party token handling.
30	- A concrete auth/authz design for the REST API in question 2.
31	- A security design for the IDP connector in question 3, including token handling and what gets logged.
32	
33	## AI tooling note
34	
35	This track is itself where the project's AI-usage story is documented in depth — treat it as both a subject-matter track and the place other tracks' brief AI notes get rolled up if useful. See `ai-workflow-narrative.md` for the full write-up.
36	
37	## Status
38	
39	Threat model, API auth/authz design, and connector security design are drafted:
40	
41	- `threat-model.md` — STRIDE-style analysis of `user_credential`, `user_profile`, and third-party `access_token` exposure, per-asset mitigations.
42	- `api-auth-design.md` — OAuth2 client-credentials grant with short-lived JWT bearer tokens and scoped, object-level authorization for question 2's search/retrieve API. Reasoned against static API keys and mTLS-only alternatives.
43	- `connector-security.md` — token handling, vendor-call authentication, and logging/persistence rules for question 3's `/auth` and `/identity` connector.
44	- `ai-workflow-narrative.md` — the full AI-tooling/workflow story for the submission, building on `research-claude-architecture-best-practices.md`.
45	- `planning-approach.md` — team-wide recommendation (requested by team-lead) for model/effort pairings per role, planning-phase coordination pattern, cross-track dependency order, and the shape/location of the shared planning artifact. Synthesized from all four other tracks' input plus this track's own view. Two follow-ups for this track surfaced from it, deferred until the planning pause lifts: a receiver-shaped 02→03 hand-off (token scheme and validation point, no alternatives discussion) and a 02→04 secrets inventory plus never-log list — the decisions exist in `api-auth-design.md` / `connector-security.md` but not yet in that form.
46	
47	Coordinated with `../05-data-ops/CLAUDE.md` on `user_credential.method` being modeled as a lookup table (not a native enum) — the credential-storage design in `threat-model.md` is method-aware as a result (password vs. WebAuthn vs. TOTP each have different storage requirements), not a single password-hashing assumption.
48	
49	Phase 1 (org planning): `PLAN.md` in this directory is the track plan — eleven Stories, a four-hire roster (Adversary, Principled Architect, Tinkerer, Designated Skeptic), the debate plan, and dependencies; `../CASTING.md` §5 ratified with four ⟨02⟩ amendments; `planning-approach.md` gained Appendix A (attack-tree template) and Appendix B (harness constraints). Awaiting team-lead's "hiring go" before any persona or agent definition is created.
50	
51	Next: available for `03-engineering-delivery` to implement against; open to review/adjustment as data-ops' schema and engineering's implementation surface any gaps.
52	
53	<!-- profile-gen:start slug=marcus-ilori -->
54	@profiles/marcus-ilori/marcus-ilori.md
55	<!-- profile-gen:end slug=marcus-ilori -->
56	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/PLAN.md"
}

1	# Track 02 Plan — AI Architecture & Security Architecture (Phase 1)
2	
3	Owner: Marcus Ilori. Written in plan mode per `PLAN.md` Phase 1. Once approved it is copied verbatim to `02-ai-security-architecture/PLAN.md`; the `~/.claude/plans/` copy is scratch.
4	
5	## Context
6	
7	The org plan (`PLAN.md`) requires every lead to plan in plan mode with four mandatory sections before hiring. Track 02 carries two extra obligations as the AI-architecture owner: ratify or amend the orchestration-pattern catalog in `CASTING.md` §5, and check the harness facts in `PLAN.md` "Verified mechanics" against `research-claude-architecture-best-practices.md` before other leads build on them. The four first-wave deliverables of this track (`threat-model.md`, `api-auth-design.md`, `connector-security.md`, `ai-workflow-narrative.md`) are complete; this plan turns them into debated, second-reviewed, receiver-shaped outputs and adds the org-layer story to the AI narrative. No code anywhere in this plan.
8	
9	## 0. Ratification of `CASTING.md` §5 and the mechanics check
10	
11	**Verdict on §5: ratified, with four amendments.** The six protocols are sound and their use/waste assignments match my own planning-approach reasoning. The amendments each target a structural weakness that the palette's own blind-spot column predicts:
12	
13	1. **Red team / blue team** — add a mandatory ranking step: the Adversary hands over a *top-five* ranked list of leaves before the blue seat responds (counters "sees threats everywhere, no prioritization" structurally rather than by exhortation). Add an optional one-turn *alternatives* seat for the Tinkerer between red and blue: propose design changes that delete leaves outright — a leaf that cannot exist beats a control. Add a residual-risk scoring rule (below). Point to the attack-tree template in `planning-approach.md` Appendix A.
14	2. **Adversarial pair** — every numbered objection from the Designated Skeptic must end with a one-line "what would change my mind" (counters "objections without a counter-proposal"). The Proposer must answer every objection in writing; it may decline to revise, but not silently.
15	3. **Structured written debate** — the lead's synthesis must state which position was stronger on which point and why; preserving both positions is necessary but not a substitute for a ruling (counters the Consensus Weaver blind spot, which is the PM's own listed archetype).
16	4. **All patterns** — each decision artifact records, in a footer, the model each seat ran on and the number of hire turns consumed, so `ai-workflow-narrative.md` can cite measured cost rather than intent.
17	
18	Where the text lives, one source of truth per thing: the four protocol amendments go into `CASTING.md` §5 in place (my permitted scope); the attack-tree *template* — a table shape, not a protocol — goes into `planning-approach.md` as **Appendix A** with a one-line pointer from §5. No new document.
19	
20	**Attack-tree template (Appendix A content):** columns `# | Leaf (attack path toward the goal) | Precondition (what the attacker must already have) | Likelihood L/M/H | Impact L/M/H | Blue response: Control or Accepted risk | Owner (02 requirement / 03 implements / 04 mechanism) | Residual L/M/H | Source`. Rules: red ranks the top five first; blue answers every leaf, and an "accepted risk" must say why it is acceptable *for this system*, not in general; the lead assigns Residual with a one-line justification; any Residual **H** must produce either a follow-up Story or an accepted risk visible to Warren in the artifact. The completed table is appended to the surface's design doc (`connector-security.md`); the full positions live in `decisions/<topic>.md`.
21	
22	**Mechanics check against the research doc: no contradictions.** Three notes for the record, to be added as a short "Harness constraints" addendum to `planning-approach.md` so it stays the single source of truth for the tiers:
23	
24	- Effort: the harness has no per-agent effort key; teammates inherit `high`, and `modelSettings.haiku.effortLevel: low` is the only per-model lever. My sonnet-medium tier therefore collapses to sonnet-high (accepted — errs upward on the tracks that matter), and *sonnet/low research fan-out is unavailable*: research is haiku/low, or sonnet/high when judgment is needed, which is costlier than planned and should be used sparingly.
25	- The per-agent `PreToolUse` hook and the `.claude/agents` frontmatter facts are outside my research doc's scope; I have no primary-source basis to dispute them and record them as verified by team-lead, not by 02.
26	- Research doc §4 (prompt caching) still applies one level down: a hire's `.claude/agents/<slug>.md` is part of that hire's stable prefix. Do not edit a hire's definition while it is running; edit at spawn boundaries.
27	
28	## 1. Deliverables and tasks (Epic: *02 AI & Security Architecture*; one Story each)
29	
30	| # | Story | Hand-off produced (file) | Consumer | Depends on |
31	|---|---|---|---|---|
32	| S1 | Ratify/amend `CASTING.md` §5 (four amendments above) and add Appendix A to `planning-approach.md` | `CASTING.md` §5; `planning-approach.md` App. A | all leads, before any red/blue runs | — |
33	| S2 | "Harness constraints" addendum to `planning-approach.md` | `planning-approach.md` | all leads; `ai-workflow-narrative.md` | — |
34	| S3 | Red/blue on the connector token lifecycle → attack-tree table with residual scores | `connector-security.md` (table appended); `decisions/connector-token-lifecycle-redblue.md` (full record) | 03's opus token-lifecycle seat; 04 (any control that is a mechanism) | hires; S1 |
35	| S4 | Adversarial pair on search-API authorization scoping | `decisions/search-authz-scoping.md`; `api-auth-design.md` gains "Objections considered" | 03 (middleware) | hires |
36	| S5 | Structured written debate on the core claim of `ai-workflow-narrative.md` | `decisions/ai-workflow-claim-debate.md` | S9 | hires |
37	| S6 | **02→03 receiver-shaped auth hand-off** — token scheme (client-credentials → JWT, asymmetric signing, claim set `sub/scope/exp/iat/aud`, TTL 5–15 min, no refresh, no denylist), **where validated** (middleware at the API edge; key retrieval), the final scope vocabulary and object-level policy hook from S4, pagination ceiling and per-client rate limit as requirements, audit-log field list, and an explicit "not yours to decide" list | `handoff-03-auth.md` | 03 — Renata scaffolds now, needs this before middleware is finalized | S4 |
38	| S7 | **02→04 secrets inventory + never-log list** — table `secret | used by (API / connector / authz server) | injection requirement | rotation expectation | never-log`; never-log list (vendor password, vendor token, PII field values, raw vendor error bodies, JWT signing private key, client secrets). Assumes **Kubernetes-native Secret delivery on the LAN lab cluster** 04 names as the design-only target (Warren's decision via Theo, `LOG.md`), stated explicitly rather than a generic "managed store"; requirements still hold if the mechanism changes | `handoff-04-secrets.md` | 04 — gates Theo's producer phase | one Skeptic objection turn; no debate |
39	| S8 | Independent second-review pass on the security-graded docs (`threat-model.md`, `api-auth-design.md`, `connector-security.md`) by hires who did not author or blue-team them | `decisions/second-review-security-docs.md`; fixes applied in place | Warren / final consistency pass | S3, S4 |
40	| S9 | Revise `ai-workflow-narrative.md` to cover the org layer — personas, patterns, debates, measured turn counts and models from the decision-artifact footers; incorporate the S5 ruling honestly, whichever way it goes; state plainly that a real external agent (the cluster operator 04 describes) exists in the environment and was deliberately kept out of scope — never contacted, nothing deployed | `ai-workflow-narrative.md` | submission reader | S3–S5 |
41	| S10 | `threat-model.md` maintenance: (a) repoint the stale reference to `05-data-ops/schema/postgres_cockroachdb.sql` (wiped) at the prose schema in `../05-data-ops/multi-db-strategy.md` — verified 2026-09-12 that `auth_method` and `secret / hash_algo / hash_cost` are already there in prose; (b) add one trust-boundary line: an **external operator agent applying manifests to the deployment target** (04's design-only lab cluster) is a privileged actor outside this service — whoever can apply a manifest can read any Secret it mounts — so the assumption "secrets are safe once in the cluster" is named, not silent | `threat-model.md` | 04 | none — can run at Phase 3 start |
42	| S11 | Post-implementation independent review of 03's auth middleware and connector token code (security-graded surfaces only) | `decisions/second-review-implementation.md` | 03 | Warren's code go-ahead — Phase 4+, listed now so it is not forgotten |
43	| T1 (Task) | Deep research, pre-authorized for one topic only if the Adversary or Architect requests it: bearer-token handling and OAuth 2.0 security best current practice (RFC 6750, RFC 9700) to arm S3 with primary sources; haiku/low fan-out run by me | `research-oauth-token-handling.md` | S3 | request from a hire |
44	
45	Cross-team asks (not my stories): 04's Newcomer performs the cold read of `handoff-03-auth.md` and `handoff-04-secrets.md` (already the one pattern `CASTING.md` assigns 04); the red/blue on the connector is run **once**, here, with 03's opus seat reading the artifact rather than 03 running a second one — I will flag this to Renata so it is not duplicated.
46	
47	## 2. Hire roster (4; all sonnet; all read-only per `_TEMPLATE.md` — they return prose, I write the artifacts)
48	
49	No first name collides with Dana, Naomi, Marcus, Renata, Theo, or Priya. Roster spans serious↔playful and cautious↔bold; two hires are `playful, bold`, contributing to the org-wide minimum of three.
50	
51	### H1 — Tomasz Wrede · Adversary · `playful, bold` · function: attack-tree author
52	Patterns: red/blue (red seat, S3); optional one-turn pre-read on S4 ("what would I do with each scope"). Requester for T1.
53	
54	> Mischievous and quick — the reviewer who reads a sequence diagram and immediately asks where he would stand to steal from it, and grins while asking. Decides by enumerating attack paths first and only then asking which ones matter, which he admits is backwards. Pushes back hardest on any claim that a control is "sufficient" until someone names the attacker it stops and the one it does not. Eight years on an internal red team at a large retailer, then four running penetration tests against payment and identity APIs for a consultancy; fluent in token theft, replay, and cache-poisoning paths, less so in formal proofs. Blind spot: he sees threats everywhere and ranks them poorly — left alone he produces forty leaves of equal weight, so make him hand over a top five before anyone answers. Argues cheerfully, concedes fast when a leaf is shown unreachable, and keeps a list of the ones he lost.
55	
56	### H2 — Helena Marsh · Principled Architect · `serious, cautious` · function: controls author and standards reviewer
57	Patterns: red/blue (blue seat, S3); adversarial pair (Proposer, S4); second review of `threat-model.md` and `api-auth-design.md` (S8 — she did not author them and is not blue on them).
58	
59	> Measured and exact; in a meeting she speaks last, usually with a section number. Decides from the threat model downward and writes every decision as a record with the alternatives she rejected and why. Pushes back on any control offered without the attack it defeats, on any trade of a security property for developer convenience, and on a citation that points at a blog when a specification exists. Eleven years across a national bank's identity platform and a government PKI programme; deep in OAuth 2.0 and its security best current practice, JOSE and the ways JWT libraries fail, and TLS deployment. Blind spot: over-specification — she designs for threats this take-home does not have and can mistake thoroughness for finished, so pair her with someone asking what the assignment actually needs. Courteous under challenge, unhurried, and changes position when shown evidence, saying so plainly.
60	
61	### H3 — Felix Adebayo · Tinkerer (silly & innovative) · `playful, bold` · function: alternatives generator — **my temperament opposite (required)**
62	Patterns: red/blue (alternatives seat between red and blue, S3 — "what if the connector held no token at all?"); structured written debate (Position A, S5).
63	
64	> Playful and fast-associating; he describes a bearer token as a hotel keycard that opens every door until Thursday, and means it as a design question. Decides by sketching three alternatives, one deliberately strange, before defending any, and drops his own without ceremony when someone shows a cleaner failure mode. Pushes back on "that is the standard approach" whenever nobody in the room can say what the standard protects against, and on any diagram with a box labelled "just cache it". Five years building fraud-scoring pipelines at a payments startup, three at a mid-sized identity vendor prototyping passkey flows; Go and Rust, and an unreasonable fondness for property-based tests. Blind spot: novelty bias — he underweights boring, proven controls and needs someone to cite the RFC at him. Warm in disagreement, never sarcastic, delighted to be wrong in an interesting way.
65	
66	### H4 — Ingrid Solano · Designated Skeptic · `serious, bold` · function: standing objector and independent reviewer
67	Patterns: adversarial pair (Skeptic, S4); structured written debate (Position B, S5); one objection turn on the secrets inventory (S7); second review of `connector-security.md` (S8 — she is not blue on it).
68	
69	> Dry and direct; in a meeting she is the one asking "compared to what?" before the proposal is finished. Decides only after hearing the strongest case against the room's favourite, and makes that case herself if nobody else will, even when she privately agrees. Pushes back on consensus that arrived too quickly, on scope vocabularies invented before anyone listed the callers, and on evidence that is one number from one vendor. Nine years as a security reviewer on an enterprise SaaS platform, then three chairing design reviews at a healthcare data company where every authorization decision met a regulator. Background in authorization models — RBAC, ABAC, object-level policy — and in reading audit logs after something went wrong. Blind spot: objections without a counter-proposal — she can leave a team knowing what is wrong and not what to do, so every objection carries a "what would change my mind" line. Polite, unyielding on process, quick to record when an objection was answered.
70	
71	Registry rows (appended to `CASTING.md` §8 only after "hiring go"): `tomasz-wrede`, `helena-marsh`, `felix-adebayo`, `ingrid-solano`; Track 02; Model sonnet; Persona `02-ai-security-architecture/profiles/<slug>/<slug>.md`; Agent def `.claude/agents/<slug>.md`; Portrait `queued`.
72	
73	## 3. Debate plan
74	
75	| Decision | Pattern | Seats | Turns | Artifact |
76	|---|---|---|---|---|
77	| Connector token lifecycle: TTL, at-rest encryption, per-vendor keying, fail-closed, "hold no token" alternative | Red/blue (amended) | Tomasz red → Felix alternatives → Helena blue → Tomasz one rebuttal on the top three → Marcus scores residual | 4 + lead | `decisions/connector-token-lifecycle-redblue.md`; table into `connector-security.md` |
78	| Search-API authz scoping: `profile:search` vs `profile:read:own` vs `profile:read:any`; object-level policy; who gets `profile:search` at all | Adversarial pair (amended) | Helena proposes → Ingrid numbered objections with "what would change my mind" → Helena answers/revises → Marcus rules (optional Tomasz pre-read, 1 turn) | 3 (+1) + lead | `decisions/search-authz-scoping.md`; "Objections considered" into `api-auth-design.md`; feeds S6 |
79	| Core claim of `ai-workflow-narrative.md` — does the multi-agent, persona-driven workflow produce *better design* than one strong session, or is it cost without evidence? (Anthropic's 90.2% figure is for research breadth, not design quality) | Structured written debate (amended) | Felix: it does, and the narrative undersells it → Ingrid: unproven; keep the narrow claim → Marcus rules per point, and the ruling goes into the narrative whichever way it lands | 3 + lead | `decisions/ai-workflow-claim-debate.md` |
80	| Secrets inventory completeness | Single objection turn | Ingrid: what is missing / mis-owned | 1 | inline in `handoff-04-secrets.md` |
81	| Security-graded docs, independent read | Second review | Helena on threat model + API auth; Ingrid on connector security | 2 | `decisions/second-review-security-docs.md` |
82	
83	Budget: about 14 hire turns for the whole track, all sonnet/high. **Declared waste — not debated:** the Argon2id hashing decision (settled by OWASP/NIST — cite, do not debate); the OAuth2 grant *type* (already reasoned in `api-auth-design.md`; S4 is about scoping, not the grant); STRIDE as the framework; endpoint paths and JSON bodies (fixed by the assignment); anything about DAO CRUD or Dockerfiles; a three-hats run (no decision in this track has three legitimate optimist/pessimist/pragmatist positions). No pattern gets a second run "to be sure".
84	
85	## 4. Dependencies
86	
87	**From 05 (Priya):** the `auth_method` lookup-table shape (`id, name, requires_secret, is_active`; `user_credential.secret / hash_algo / hash_cost`) — **settled** by direct two-party coordination and confirmed present in prose in `multi-db-strategy.md`; my threat model is already method-aware. Nothing further needed from 05 for this track's Phase 3; the Go-shaped contract she is delivering is 03's dependency, not mine.
88	
89	**From 01 (Naomi):** `api-connector-design-rationale.md` as the single source of truth for field/endpoint shape — a soft dependency, read before finalizing S6, not before starting.
90	
91	**To 03 (Renata):** `handoff-03-auth.md` (S6) — she scaffolds now and needs it before middleware finalization; target: immediately after S4 rules, early Phase 3. The red/blue table (S3) is the requirement set for her opus token-lifecycle seat; target mid Phase 3. One red/blue, run here, read there.
92	
93	**To 04 (Theo):** `handoff-04-secrets.md` (S7) — gates his producer phase; it depends on no debate, only one objection turn, so it is the **first** deliverable out after hiring. His Newcomer cold-reads both hand-offs.
94	
95	**From 04 / Warren (via team-lead, recorded in `LOG.md`):** the deployment target is a real Kubernetes lab cluster on the LAN operated by an external agent, used as a **design-only** reference. This track assumes Kubernetes-native Secret delivery in S7 and names the operator as a trust boundary in S10. Hard rule inherited: no action on that cluster and no contact with its operator agent, ever, without Warren's explicit go — this track has no reason to touch either.
96	
97	**To all leads:** `CASTING.md` §5 amendments and Appendix A (S1) before any lead runs a red/blue; the harness-constraints addendum (S2) before anyone spawns a "sonnet/low" research subagent that will actually run at high.
98	
99	**From team-lead:** "hiring go" — nothing in §2 is created or spawned before it.
100	
101	## Files touched after ExitPlanMode (Phase 1 close-out only)
102	
103	1. Copy this plan → `02-ai-security-architecture/PLAN.md`.
104	2. `PLANNING.md` — my row only → `plan drafted — awaiting hiring go`, hires `4 / 0 / 0`, planning notes pointer, date.
105	3. `CASTING.md` §5 — the four amendments in place, nothing outside §5.
106	4. `planning-approach.md` — Appendix A (attack-tree template) and the Harness-constraints addendum.
107	5. `02-ai-security-architecture/CLAUDE.md` Status — one line pointing at `PLAN.md` (turn-boundary edit).
108	6. ≤200-word summary with roster to team-lead.
109	
110	Not touched until "hiring go": `profiles/`, `.claude/agents/`, `
… truncated (20 KB cap)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/profiles/tomasz-wrede/tomasz-wrede.md"
}

1	---
2	schema_version: 1
3	name: "Tomasz Wrede"
4	slug: "tomasz-wrede"
5	image: "profiles/tomasz-wrede/tomasz-wrede.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: "Tomasz Wrede, a man in his late 30s with Central European features, short light-brown hair, close-cropped stubble, sharp alert eyes and a faint amused half-smile, wearing a charcoal open-collar shirt under a dark casual blazer, head-and-shoulders portrait, centered, neutral dark 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	# Tomasz Wrede
23	
24	![Tomasz Wrede](profiles/tomasz-wrede/tomasz-wrede.png)
25	
26	
27	## Personality
28	
29	Mischievous and quick — the reviewer who reads a sequence diagram and immediately asks where he would stand to steal from it, and grins while asking. Decides by enumerating attack paths first and only then asking which ones matter. Pushes back hardest on any claim that a control is "sufficient" until someone names the attacker it stops and the one it does not. Eight years on an internal red team at a retailer, then four running penetration tests against payment and identity APIs for a consultancy; fluent in token theft, replay, and cache-poisoning paths, less so in formal proofs. Blind spot: he sees threats everywhere and ranks them poorly — left alone he produces forty leaves of equal weight, so make him hand over a top five before anyone answers. Argues cheerfully, concedes fast when a leaf is shown unreachable, and keeps a list of the ones he lost.
30	
31	

{
  "command": "python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --profile /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/profiles/tomasz-wrede/tomasz-wrede.md --root /Users/warrenthompson/Source/LoginID/02-ai-security-architecture"
}

{"name": "Tomasz Wrede", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

{
  "to": "marcus-ilori",
  "content": "Tomasz here, oriented. Read root CLAUDE.md, track CLAUDE.md, PLAN.md, my persona. Clear on my seat: red seat in S3's red/blue on the connector token lifecycle — I go first, hand over a ranked top five leaves before you or Helena respond, then get one rebuttal turn on the top three after blue answers. Table shape per Appendix A. Holding — not starting until you call the seat. Already sharpening my knives on TTL, at-rest encryption, per-vendor keying, and fail-closed behavior."
}

<tool_use_error>Error: No such tool available: SendMessage. SendMessage is disabled for this session, in subagents as well as here.</tool_use_error>

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md"
}

1	# IDP Connector Security Design — Question 3
2	
3	Owner: Marcus Ilori (`02-ai-security-architecture`). Covers the third-party identity-provider connector (generic vendors "ABC"/"XYZ") exposing `/auth` and `/identity`, per the assignment. Implementation target: `../03-engineering-delivery/CLAUDE.md`.
4	
5	## Contract recap (from the assignment, verbatim in `../CLAUDE.md`)
6	
7	- `POST /auth` — body `{"username": "<string>", "password": "<string>"}` → returns an `access_token`.
8	- `POST /identity` — body `{"phone": "<string>", "name": "<string>"}` → returns PII (name, phone, address fields).
9	
10	Read literally, this connector is a thin proxy in front of ABC/XYZ: it takes vendor credentials, gets a vendor token, and uses that token to pull PII from the vendor. Every security question here is "what does this service do with a vendor secret and vendor PII while it's in our custody," since we don't control the vendor's own security posture.
11	
12	## Threat surface specific to this connector
13	
14	This extends the third-party-token row in `threat-model.md`; this document is the concrete design against those threats.
15	
16	### 1. What happens to the vendor `access_token` once retrieved
17	
18	- **Never logged.** The `/auth` request body contains a vendor password; the response contains a bearer token. A naive "log the request and response for debugging" habit puts both in the same log line — this is called out explicitly because it's the single most common way a connector like this leaks a credential in practice, not a hypothetical.
19	- **Held in memory for the shortest span that satisfies the immediate `/identity` call**, not persisted to our own database as a matter of course. If caching is required for latency/rate-limit reasons, cache with a TTL no longer than the vendor's own token expiry, encrypted at rest (same envelope-encryption requirement as the TOTP-secret case in the threat model — mechanics via KMS, owned by `../04-infra-devops/CLAUDE.md`), and keyed so one vendor-account's token is never returned to a caller resolving a different vendor account.
20	- **Scoped narrowly if the vendor supports it** — request only the scope needed for `/identity`, not a broad token, so a leaked token's blast radius is bounded by the vendor's own authorization model as well as ours.
21	- **Not returned to our own API callers.** The vendor `access_token` is an internal implementation detail of this connector; question 2's API callers never see it. If a caller needs to know "identity lookup succeeded," return our own success/failure signal, not the vendor's token or vendor's raw response.
22	
23	### 2. How `/identity` calls are authenticated to the vendor
24	
25	- Standard bearer-token usage: the vendor `access_token` from `/auth` presented as an `Authorization: Bearer` header to the vendor's identity endpoint (or whatever the vendor's own contract specifies — this connector adapts to the vendor, not the reverse).
26	- **Token refresh/re-auth on expiry** handled by the connector transparently — a caller of our `/identity` endpoint should not need to know or manage vendor token lifecycle.
27	- **Vendor calls over TLS only**, certificate validation never disabled, including in local/dev environments (repeating the threat model's point because it's the most common place a "temporary" dev bypass ships to production unnoticed).
28	- **Our own credentials to call the vendor's `/auth`** (this connector's client id/secret with ABC/XYZ, if the vendor requires connector-level registration in addition to the end-user's own username/password) are runtime-injected secrets, never in source or config committed to the repo — requirement set here, mechanism owned by `../04-infra-devops/CLAUDE.md`.
29	
30	### 3. What this service should and shouldn't log or persist
31	
32	| Data | Log it? | Persist it? |
33	|---|---|---|
34	| End-user's vendor username | No (identifier, but low sensitivity relative to password — still avoid in plaintext logs; use it only for correlation via a hash if audit trails need it) | Only if a legitimate business reason exists; not by default |
35	| End-user's vendor password (`/auth` request body) | **Never, under any circumstance, including error paths and stack traces** | **Never** |
36	| Vendor `access_token` | **Never** | Only as short-TTL encrypted cache per above; never in plaintext, never in application logs |
37	| PII returned by `/identity` (name, phone, address fields) | Never the field values; log only the *fact* of a lookup (caller identity, timestamp, success/failure, which record was resolved by opaque id) | Retention/caching policy for this PII is `../05-data-ops/CLAUDE.md`'s call — this track's requirement is that whatever is persisted follows the same encryption-at-rest and access-control bar as `user_profile` data, no weaker because it arrived via a connector rather than direct input |
38	| Vendor error responses | Log status/error-code only; do not log raw vendor response bodies by default, since a vendor error payload can itself echo back submitted PII or partial credentials | N/A |
39	
40	### 4. Failure handling as a security control, not just reliability
41	
42	- **Vendor auth failures must not leak which part of the credential was wrong** (username vs. password) in whatever this connector surfaces upward — same user-enumeration concern as the threat model's credential-stuffing row, now facing outward at whoever calls our `/auth` passthrough.
43	- **Retry/backoff on vendor calls** should be rate-limited on our side independent of the vendor's own limits, so a compromised or careless caller can't use our connector to hammer the vendor (which is both an availability risk to us and a way to get our connector's vendor credentials rate-limited or banned).
44	- **Circuit-breaking**: if the vendor is failing or behaving anomalously (e.g., returning tokens for identities that don't match the request), fail closed — do not fall back to a cached or stale identity result silently, since that risks serving stale PII as if freshly verified.
45	
46	## What this design does not resolve
47	
48	- Data retention duration for cached `/identity` results — `../05-data-ops/CLAUDE.md`.
49	- Which secrets manager holds this connector's own vendor credentials — `../04-infra-devops/CLAUDE.md`.
50	- Vendor selection/evaluation (which real-world providers "ABC"/"XYZ" might represent) — that's product framing in `../01-product-industry-research-design/CLAUDE.md`, not a security question.
51	
52	## Sources
53	
54	- OWASP API Security Top 10 2023, API7 (Server Side Request Forgery) and API8 (Security Misconfiguration) — both relevant to a service that makes outbound calls to a third party on a user's behalf: https://owasp.org/API-Security/editions/2023/en/0x11-t10/
55	- OWASP Logging Cheat Sheet (what not to log — credentials, tokens, PII): https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
56	

{
  "command": "true"
}

(Bash completed with no output)

{
  "command": "python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --profile ./profiles/tomasz-wrede/tomasz-wrede.md --root ."
}

{"name": "Tomasz Wrede", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md"
}

1	# API Authentication & Authorization Design — Question 2
2	
3	Owner: Marcus Ilori (`02-ai-security-architecture`). Covers the RESTful API service to search/retrieve `user_profile` data (assignment question 2, including its explicit "security API authentication" requirement). Implementation target: `../03-engineering-delivery/CLAUDE.md`. Consumes the schema from `../05-data-ops/CLAUDE.md`.
4	
5	## What "security API authentication" is scoped to mean here
6	
7	The assignment names it without specifying a mechanism, so this is a design decision, not a given — stated with reasoning per this project's working principle.
8	
9	Three realistic candidates and why I'm choosing among them:
10	
11	| Option | Fit here | Verdict |
12	|---|---|---|
13	| Static API keys | Simple, but no expiry semantics, no scoping without inventing one, easy to leak into logs/URLs, no standard revocation flow | Rejected as the primary mechanism — acceptable only as a secondary, coarse-grained "which client system is this" identifier, never as sole authn/authz. |
14	| mTLS | Strong, but assumes both parties (this API and its callers) can manage client certs — reasonable for a closed set of internal service callers, awkward for anything resembling a broader consumer base | Recommended as a **transport-layer supplement** for service-to-service callers where the deploying org already runs a cert infrastructure; not the sole control. |
15	| OAuth2 client-credentials grant → short-lived JWT bearer token | Standard, expresses scopes natively, well-supported Go tooling, matches how the connector in question 3 already authenticates to us conceptually (token-based), and composes cleanly with per-caller authorization | **Chosen primary mechanism.** |
16	
17	**Decision: OAuth2 client-credentials grant issuing short-lived JWT bearer access tokens, with mTLS as an optional additional transport control for known service-to-service callers.**
18	
19	This is a machine-to-machine API (question 2 doesn't describe an end-user-facing login flow — it describes callers searching/retrieving profile data), so client-credentials is the correct OAuth2 grant type, not authorization-code (which is for delegated end-user consent) or password grant (deprecated, and inappropriate for a service caller).
20	
21	## Token shape and lifecycle
22	
23	- **Format**: JWT, signed (not encrypted — it carries no secret, only claims), asymmetric signing (RS256/ES256) so the API can verify tokens without holding the signing key, which itself lives with a token-issuing authorization server component.
24	- **Claims, minimum set**: `sub` (calling client/service identity), `scope` (space-delimited authorization scopes, see below), `exp` (short — 5–15 minutes), `iat`, `aud` (this API specifically, to prevent a token minted for another service being replayed here).
25	- **No refresh tokens** for a client-credentials grant — the client re-authenticates with its own client secret when the access token expires. This bounds the blast radius of a leaked access token to its short TTL.
26	- **Revocation**: because JWTs are self-contained, true revocation requires either a short enough TTL that revocation is unnecessary in practice (the approach here) or a token-denylist check, which reintroduces a stateful lookup and defeats part of the point of JWTs. Given the 5–15 minute TTL, denylist is not required for this design; flagged here so a reviewer sees the trade-off was considered, not missed.
27	
28	## Authorization model: scopes, not just "authenticated"
29	
30	The threat model (`threat-model.md`, Asset 2) already names the core risk: an authenticated-but-unscoped search/retrieve endpoint is a PII enumeration engine. Authentication answers "who is calling"; it does not answer "what may they see." This API needs both.
31	
32	Finalized by the S4 adversarial pair (`decisions/search-authz-scoping.md`; Helena Marsh, Proposer; Ingrid Solano, Skeptic) — this section supersedes the earlier sketch.
33	
34	### Scope vocabulary
35	
36	- **`profile:read:own`** — retrieve a single record by an id the caller already holds a legitimate reference to (e.g., a partner resolving a user it referred). Enforced against a `caller_referral` mapping (below), not by scope alone. Does not authorize search/query by name or phone fragment.
37	- **`profile:read:any`** — retrieve a single record by id, no referral constraint. Not a default grant: provisioning requires an entry in an explicit caller-role table (service name, business justification, and specifically *why* `read:own`'s referral constraint is insufficient for that caller's function), gated the same way `profile:search` is below. If no caller meets that bar, the scope stays defined but unissued.
38	- **`profile:search`** — query by name/phone fragment across the table; the PII-enumeration-engine risk the threat model names. Its own gated capability, not "`read:any` plus search."
39	
40	### `profile:search` provisioning bar (all four required)
41	
42	1. Named service identity — never a shared client credential across a team.
43	2. Documented business function on file before provisioning, not granted speculatively.
44	3. Change-controlled approval with a named human approver, logged.
45	4. Tighter rate/result limits than any other scope (below).
46	
47	### Object-level policy hook
48	
49	A per-scope policy function `authorize(sub, scope, target)` runs after the scope check, not instead of it — directly targeting OWASP API1:2023 (Broken Object Level Authorization):
50	
51	- **`read:own`**: checks `target.id` against the `caller_referral` mapping. Scope-valid but outside the caller's referral set → reject, logged as a policy denial (distinct from an auth failure, for detection). `caller_referral` entries are data owned by `../05-data-ops/CLAUDE.md`, written only through the same partner-onboarding workflow as any other provisioning decision (named approver, logged) — no ad hoc inserts.
52	- **`read:any`**: requires a `reason_code` from a closed, versioned enum (`support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`) logged with the audit record; adding a value to the enum requires a documented change. Freeform justification text is not acceptable — an unaudit-able reason code is the same gap as no reason code, six months later.
53	- **`profile:search`**: additionally enforces the per-query result cap; a query that would exceed it unconstrained (e.g., a bare wildcard) is rejected outright, not truncated.
54	
55	### Pagination, rate limits, and decomposition resistance
56	
57	- **Cursor-based pagination**, not offset — offset walks turn a capped page size into full-table enumeration. Default page 20, hard ceiling 50.
58	- **Per-client-credential rate limits**: 60 req/min for `read:own`/`read:any`, 10 req/min for `profile:search`.
59	- **Cumulative distinct-record-touch counter per caller per rolling window** (e.g., no more than N distinct profiles returned to one credential per 24h without a fresh `reason_code`/justification), tracked independently of per-minute rate. A single-request cap and per-minute throttling only stop single-request or bursty enumeration; a caller stayng under both limits can still walk the namespace in slices and reassemble the population over time (decomposition) — this counter is what catches that pattern regardless of how slowly it's spread. Counting-store mechanism is 03/04's to build; the requirement that volume is measured cumulatively, not just per-minute, is set here.
60	- Sustained near-limit usage on any of the above alerts, not just hard-blocks at the ceiling.
61	
62	### Grant lifecycle
63	
64	- **90-day re-approval** on every scope grant (not `profile:search` alone) is a backstop, not the only mechanism. Grants are revoked immediately, ahead of the 90-day cycle, on: the named approver's offboarding, the caller's stated business function changing, or an idle trigger (no usage for 30 days → revoke pending re-justification) — whichever comes first. This requires 03/04 to consume an offboarding or ownership-change signal; the requirement (lifecycle-triggered revocation, not solely calendar-triggered) is asserted here, the plumbing is theirs.
65	
66	## Defense in depth beyond the token check
67	
68	- **TLS 1.2+ only**, terminated in front of the API; no plaintext.
69	- **Input validation** on search parameters — reject unbounded wildcard queries, cap query complexity, parameterize all DB access (SQL injection is a data-ops/engineering implementation concern, but the API layer's job is to never pass a raw client string into a query string).
70	- **Audit logging**: every search/retrieve call logs caller identity (`sub`), scope used, record id(s) touched, and timestamp — never the PII field values themselves, per the threat model's log-hygiene requirement. This is what makes a compromised-but-legitimate credential's misuse detectable after the fact, which token-based authn alone does not give you.
71	- **Standard API hardening**: no PII in URLs (query strings get logged by proxies/CDNs outside our control) — record identifiers in the path are fine, but search terms containing a phone number or name fragment belong in a POST body or a properly-redacted query parameter set, not a GET query string that ends up in a shared access log.
72	
73	## Why not "just API keys"
74	
75	Worth stating plainly since it's the simplest alternative a reviewer might expect: a static API key has no expiry, no standard scope representation, and if it leaks (URL, log, repo) it's valid until manually rotated. The chosen design bounds leak exposure to minutes (token TTL) rather than "until someone notices," and expresses authorization natively instead of requiring a bespoke key→permissions side table. That trade costs implementation complexity (an authorization-server component, however minimal) which is why it's stated explicitly here rather than assumed.
76	
77	## Objections considered (S4 adversarial pair)
78	
79	Full record: `decisions/search-authz-scoping.md`. Ingrid Solano's five numbered objections against Helena Marsh's initial proposal, all accepted and revised into the sections above: (1) `read:any` was shaped before its actual callers were enumerated — fixed by requiring a caller-role table entry, gated like `search`; (2) `read:any`'s `reason_code` was freeform — fixed with a closed, versioned enum; (3) `caller_referral` membership had no owner or approval process, the softest control gating the narrowest scope — fixed by routing it through the same partner-onboarding workflow as any other grant; (4) per-request rejection and per-minute rate limits don't stop decomposition (slow enumeration under the cap) — fixed with a cumulative distinct-record-touch counter per rolling window; (5) 90-day re-approval is calendar-only, not lifecycle-tied — fixed with immediate revocation on offboarding, function change, or a 30-day idle trigger, with the 90-day cycle as backstop only.
80	
81	## Sources
82	
83	- RFC 6749 (OAuth 2.0), §4.4 Client Credentials Grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
84	- RFC 7519 (JSON Web Token): https://datatracker.ietf.org/doc/html/rfc7519
85	- OWASP API Security Top 10 2023, API1 (Broken Object Level Authorization) and API3 (Broken Object Property Level Authorization): https://owasp.org/API-Security/editions/2023/en/0x11-t10/
86	- NIST SP 800-63B (identity/authorization lifecycle, offboarding-triggered revocation) — cited in `decisions/search-authz-scoping.md`
87	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/search-authz-scoping.md"
}

1	# Decision: Search-API Authorization Scoping — Adversarial Pair (S4)
2	
3	Pattern: adversarial pair, amended per `CASTING.md` §5 ⟨02⟩. Surface: the scope vocabulary, `profile:search` provisioning, object-level policy, pagination/rate limits, and grant lifecycle for the REST API in `api-auth-design.md`. This record is the full positions and rebuttal; the ruling is folded directly into `api-auth-design.md`.
4	
5	## Seats
6	
7	- **Proposer — Helena Marsh.** Drafts the scoping proposal.
8	- **Skeptic — Ingrid Solano.** Numbered objections, each with a "what would change my mind" line.
9	- **Proposer — Helena Marsh.** Answers every objection in writing.
10	- **Lead — Marcus Ilori.** Rules.
11	
12	## Proposer: Helena's initial draft
13	
14	**Scope vocabulary**, sharpened from `api-auth-design.md`'s original sketch: `profile:read:own` (id lookup, constrained to a `caller_referral` mapping — not a search), `profile:read:any` (id lookup, no referral constraint), `profile:search` (fuzzy name/phone query, its own gated capability, not "read:any plus search").
15	
16	**`profile:search` provisioning bar (all four required):** named service identity, not a shared team credential; documented business function on file before provisioning; change-controlled approval with a named human approver, logged; tighter rate/result limits than any other scope.
17	
18	**Object-level policy hook:** `authorize(sub, scope, target)` runs after the scope check — `read:own` checks `caller_referral` membership; `read:any` requires a logged `reason_code`; `search` additionally enforces a result cap, rejecting outright (not truncating) a query that would exceed it unconstrained.
19	
20	**Pagination/rate limits:** cursor-based (not offset), default page 20 / ceiling 50; rate limits 60 req/min for `read:own`/`read:any`, 10 req/min for `search`, with alerting on sustained near-limit usage.
21	
22	## Skeptic: Ingrid's five objections
23	
24	1. **Scope vocabulary built before callers were listed.** No enumerated table of who actually calls each scope — can't tell whether `read:any` reflects a real caller or is invented for symmetry with `read:own`. *Would change my mind:* a table of named calling services/roles mapped to the scope each needs, before finalizing.
25	2. **`reason_code` for `read:any` is logged but not bounded to a controlled vocabulary.** A freeform string is worthless in an audit six months later; `search`'s provisioning bar is rigorous while `read:any`'s control is an order of magnitude looser for a scope that's *less* constrained at query time. *Would change my mind:* a closed enum of reason codes, same rigor as the search bar.
26	3. **`caller_referral` membership has no stated owner or change process.** `read:own` leans entirely on this mapping with no named approver or re-approval, while `search` gets a four-point bar — the narrowest scope is the softer target, not the safer one. *Would change my mind:* the same named-approver-plus-re-approval discipline applied to `caller_referral` changes, or a citation for why it needs less.
27	4. **"Reject outright" on an over-cap query stops single-request enumeration, not decomposition.** A caller at 10 req/min can walk the namespace in under-cap slices and reassemble the population over time; alerting only covers sustained near-limit usage, which a slow enumerator won't trigger. *Would change my mind:* a cumulative-distinct-subjects-per-caller-per-window counter feeding the same alerting path, or evidence that the provisioning bar makes slow enumeration commercially irrational for anyone who'd clear it.
28	5. **90-day re-approval is a calendar control, not a lifecycle control.** Nothing ties revocation to offboarding or role-change; a grant can survive up to 89 days past when it should have been pulled. *Would change my mind:* an explicit statement that revocation is event-triggered with the 90-day cycle as backstop only, or a citation that no such feed exists and the backstop is an accepted residual risk, named as such.
29	
30	## Proposer: Helena's answers
31	
32	All five accepted; none declined.
33	
34	1. **Revised.** `profile:read:any` now requires an entry in an explicit caller-role table (service name, business justification, and why `read:own`'s referral constraint is insufficient for that caller) before the grant is issued — gated the same way `profile:search` already is. If no caller meets the bar, the scope stays defined but unissued, since "any known record, no referral, audited" is a real access pattern some back-office functions need, but nobody gets it by default.
35	2. **Revised.** `reason_code` replaced with a closed, versioned enum (`support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`) defined in `api-auth-design.md`; adding a value requires a documented change, matching the `search` provisioning bar's rigor.
36	3. **Revised — the sharpest of the five.** `caller_referral` entries are data owned by `05-data-ops`, written only through the same partner-onboarding workflow as any other provisioning decision: named approver, logged, reviewed on the same cadence as scope grants. No ad hoc inserts outside that workflow.
37	4. **Revised.** Added a cumulative distinct-record-touch counter per caller per rolling window (e.g., no more than N distinct profiles returned to one credential per 24h without a fresh `reason_code`/justification), tracked independently of per-minute rate — catches decomposition regardless of how slowly it's spread. Counting-store mechanism is 03/04's to build; the requirement (cumulative, not just per-minute, measurement) is asserted here.
38	5. **Revised.** All three scope grants — not just `search` — are revoked immediately, ahead of the 90-day cycle, on: the named approver's offboarding, the caller's business function changing, or a 30-day idle trigger (no usage → revoke pending re-justification). Requires 03/04 to consume an offboarding/ownership-change signal; the requirement (lifecycle-triggered revocation, not solely calendar) is set here, the plumbing is theirs.
39	
40	## Ruling (Marcus Ilori)
41	
42	Accepted in full — Helena's revised proposal is the design. All five of Ingrid's objections identified real gaps (asymmetric rigor between scopes, a control with no owner, a decomposition path the rate limit didn't cover, a calendar-only lifecycle control) and every fix closes the specific gap named rather than gesturing at a general improvement. Ingrid's objection 3 (`caller_referral` ownership) was the strongest single point in this run — the narrowest-privilege scope having the weakest control around it is exactly the kind of asymmetry an adversarial pair exists to catch, and a Proposer working alone would have had no structural reason to notice it. Folded into `api-auth-design.md` directly; this is the scope vocabulary, provisioning bar, and lifecycle rule `handoff-03-auth.md` (S6) builds on next.
43	
44	---
45	Model: sonnet (Helena Marsh, Proposer) / sonnet (Ingrid Solano, Skeptic) / sonnet (Marcus Ilori, lead, ruling). Turns consumed: 3 + lead (draft, objections, answer, ruling) — matches the 3-turns-plus-lead budget in `PLAN.md` §3.
46	

{
  "command": "python3 ~/.claude/skills/profile-gen/scripts/show_profile.py --profile ./profiles/tomasz-wrede/tomasz-wrede.md --root ."
}

{"name": "Tomasz Wrede", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

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

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
--- a/go.sum
+++ b/go.sum
@@ -3,6 +3,8 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
 github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
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
new file mode 100644
index 0000000..a27bf53
--- /dev/null
+++ b/internal/api/grantlimiter_test.go
@@ -0,0 +1,157 @@
+package api
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestGrantLimiter_AllowsFirstAttempt(t *testing.T) {
+	l := NewInProcessGrantLimiter(time.Second, time.Minute, 5, nil)
+	allow, err := l.Allow(context.Background(), "client-a", "«IP»")
+	if err != nil || !allow {
+		t.Fatalf("Allow = %v, %v; want true, nil", allow, err)
+	}
+}
+
+func TestGrantLimiter_BlocksAfterFailure(t *testing.T) {
+	l := NewInProcessGrantLimiter(time.Minute, time.Hour, 5, nil)
+	ctx := context.Background()
+	l.RecordFailure(ctx, "client-a", "«IP»")
+
+	allow, err := l.Allow(ctx, "client-a", "«IP»")
+	if err != nil {
+		t.Fatalf("Allow: %v", err)
+	}
+	if allow {
+		t.Error("should be blocked immediately after a failure, within the backoff window")
+	}
+}
+
+func TestGrantLimiter_BackoffIsExponential(t *testing.T) {
+	l := NewInProcessGrantLimiter(time.Second, time.Hour, 100, nil)
+	fakeNow := time.Now()
+	l.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	l.RecordFailure(ctx, "client-a", "«IP»")
+	// First failure: 1s backoff. Advance 1.5s — should be allowed again.
+	fakeNow = fakeNow.Add(1500 * time.Millisecond)
+	if allow, _ := l.Allow(ctx, "client-a", "«IP»"); !allow {
+		t.Fatal("should be allowed again after the first (1s) backoff elapses")
+	}
+
+	l.RecordFailure(ctx, "client-a", "«IP»")
+	// Second consecutive failure: 2s backoff. Advance only 1.5s again —
+	// should still be blocked, proving the window grew.
+	fakeNow = fakeNow.Add(1500 * time.Millisecond)
+	if allow, _ := l.Allow(ctx, "client-a", "«IP»"); allow {
+		t.Error("should still be blocked — the second failure's backoff (2s) hasn't elapsed yet")
+	}
+}
+
+func TestGrantLimiter_BackoffCappedAtMax(t *testing.T) {
+	l := NewInProcessGrantLimiter(time.Second, 5*time.Second, 100, nil)
+	fakeNow := time.Now()
+	l.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	for i := 0; i < 10; i++ {
+		l.RecordFailure(ctx, "client-a", "«IP»")
+	}
+	// Even after many failures, the backoff must not exceed maxBackoff.
+	fakeNow = fakeNow.Add(5*time.Second + time.Millisecond)
+	if allow, _ := l.Allow(ctx, "client-a", "«IP»"); !allow {
+		t.Error("backoff should be capped at maxBackoff (5s), not grow unbounded across 10 failures")
+	}
+}
+
+func TestGrantLimiter_KeyedIndependentlyByClientIDAndSourceIP(t *testing.T) {
+	l := NewInProcessGrantLimiter(time.Hour, time.Hour, 100, nil)
+	ctx := context.Background()
+
+	// A distributed brute force: many source IPs against one client_id.
+	// The client_id key alone must block a request even from a fresh IP.
+	l.RecordFailure(ctx, "client-a", "«IP»")
+	if allow, _ := l.Allow(ctx, "client-a", "«IP»"); allow {
+		t.Error("a blocked client_id must block attempts from a different source IP too")
+	}
+
+	// A single-source credential-stuffing run: many client_ids from one
+	// IP. The source-IP key alone must block a fresh client_id from that
+	// same IP.
+	if allow, _ := l.Allow(ctx, "client-b", "«IP»"); allow {
+		t.Error("a blocked source IP must block attempts for a different client_id too")
+	}
+
+	// A genuinely unrelated (client_id, IP) pair must not be affected.
+	if allow, _ := l.Allow(ctx, "client-c", "«IP»"); !allow {
+		t.Error("an unrelated client_id/source IP pair must not be blocked")
+	}
+}
+
+func TestGrantLimiter_SuccessResetsBackoff(t *testing.T) {
+	l := NewInProcessGrantLimiter(time.Hour, time.Hour, 100, nil)
+	ctx := context.Background()
+
+	l.RecordFailure(ctx, "client-a", "«IP»")
+	if allow, _ := l.Allow(ctx, "client-a", "«IP»"); allow {
+		t.Fatal("should be blocked after a failure")
+	}
+
+	l.RecordSuccess(ctx, "client-a", "«IP»")
+	if allow, _ := l.Allow(ctx, "client-a", "«IP»"); !allow {
+		t.Error("a successful grant should reset backoff state entirely")
+	}
+}
+
+// TestGrantLimiter_AlertsOnceOnSustainedFailureRun is
+// handoff-03-auth.md v3's "alerting on a sustained run of failed grants
+// against one client_id" — fired exactly once per threshold crossing,
+// not once per failure past it (which would just be alert-fatigue noise
+// indistinguishable from the failures themselves).
+func TestGrantLimiter_AlertsOnceOnSustainedFailureRun(t *testing.T) {
+	var alerts []int
+	l := NewInProcessGrantLimiter(time.Nanosecond, time.Nanosecond, 3, func(clientID string, consecutiveFailures int) {
+		alerts = append(alerts, consecutiveFailures)
+	})
+	fakeNow := time.Now()
+	l.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	for i := 0; i < 6; i++ {
+		l.RecordFailure(ctx, "client-a", "«IP»")
+		fakeNow = fakeNow.Add(time.Millisecond) // clear the (nanosecond) backoff each time
+	}
+
+	if len(alerts) != 1 {
+		t.Fatalf("alerts fired = %v, want exactly one (at the threshold crossing)", alerts)
+	}
+	if alerts[0] != 3 {
+		t.Errorf("alert fired at %d consecutive failures, want at the threshold (3)", alerts[0])
+	}
+}
+
+func TestGrantLimiter_AlertOnlyNamesClientID_NotSourceIP(t *testing.T) {
+	// The requirement names client_id specifically for alerting — a
+	// source IP hitting the threshold across many different client_ids
+	// (each individually under threshold) is a different signal
+	// (distributed credential stuffing) this limiter still blocks via
+	// the source-IP key, but doesn't claim to alert on by itself.
+	var alerted bool
+	l := NewInProcessGrantLimiter(time.Nanosecond, time.Nanosecond, 3, func(clientID string, n int) {
+		alerted = true
+	})
+	fakeNow := time.Now()
+	l.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	clientIDs := []string{"client-a", "client-b", "client-c"}
+	for _, id := range clientIDs {
+		l.RecordFailure(ctx, id, "«IP»")
+		fakeNow = fakeNow.Add(time.Millisecond)
+	}
+	if alerted {
+		t.Error("alertFn should be keyed on a single client_id's consecutive failures, not fired for varying client_ids sharing a source IP")
+	}
+}
diff --git a/internal/api/handlers.go b/internal/api/handlers.go
index 9fd7fa6..d4c92c8 100644
--- a/internal/api/handlers.go
+++ b/internal/api/handlers.go
@@ -28,6 +28,16 @@ const (
 	maxPageSize     = 50
 	readRateLimit   = 60 // req/min, read:own and read:any
 	searchRateLimit = 10 // req/min, profile:search
+
+	// TouchCapPerWindow and TouchCapWindow are the cumulative
+	// distinct-record-touch cap's real values — ruled by Marcus Ilori
+	// (02) since handoff-03-auth.md names the mechanism ("a rolling 24h
+	// window") but not a number: 2,000 distinct records per caller per
+	// rolling 24h, same figure for both profile:search and
+	// profile:read:any. Explicitly tunable, not protocol-fixed — see
+	// handoff-03-auth.md's v5 addendum for the reasoning.
+	TouchCapPerWindow = 2000
+	TouchCapWindow    = 24 * time.Hour
 )
 
 type searchRequest struct {
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.

{
  "command": "gh pr diff 30 --repo wtvamp/loginid-takehome 2>&1 | sed -n '500,1000p'"
}

+// 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)
+	}))
+	defer srv.Close()
+
+	cache := NewJWKSCache(srv.URL, time.Millisecond, nil)
+	if _, err := cache.KeyForKid("key-1"); err != nil {
+		t.Fatalf("first KeyForKid: %v", err)
+	}
+	time.Sleep(5 * time.Millisecond)
+	if _, err := cache.KeyForKid("key-1"); err != nil {
+		t.Fatalf("second KeyForKid: %v", err)
+	}
+	if requests < 2 {
+		t.Errorf("fetched the JWKS endpoint %d times, want at least 2 (TTL should have expired)", requests)
+	}
+}
+
+func TestJWKSCache_UnknownKidIsError(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)
+	}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(body)
+	}))
+	defer srv.Close()
+
+	cache := NewJWKSCache(srv.URL, time.Hour, nil)
+	if _, err := cache.KeyForKid("no-such-kid"); err == nil {
+		t.Error("expected an error for an unrecognized kid")
+	}
+}
+
+func TestJWKSCache_StaleCacheSurvivesTransientFetchFailure(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)
+	}
+
+	failing := false
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if failing {
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(body)
+	}))
+	defer srv.Close()
+
+	cache := NewJWKSCache(srv.URL, time.Millisecond, nil)
+	if _, err := cache.KeyForKid("key-1"); err != nil {
+		t.Fatalf("first KeyForKid: %v", err)
+	}
+	time.Sleep(5 * time.Millisecond)
+	failing = true
+	if _, err := cache.KeyForKid("key-1"); err != nil {
+		t.Errorf("KeyForKid during a transient fetch failure = %v, want the stale cache to still serve the key", err)
+	}
+}
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
new file mode 100644
index 0000000..116049f
--- /dev/null
+++ b/internal/api/jwtmiddleware_test.go
@@ -0,0 +1,352 @@
+package api
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/x509"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"

{
  "command": "gh pr diff 30 --repo wtvamp/loginid-takehome 2>&1 | sed -n '1000,1500p'"
}

+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+const (
+	testIssuer   = "https://auth.loginid-takehome.internal"
+	testAudience = "loginid-api-service"
+)
+
+// fakeKeySource implements KeySource with an in-memory map, for tests
+// that don't need real JWKS-over-HTTP fetching (that's jwks_test.go's
+// job).
+type fakeKeySource struct {
+	keys map[string]*rsa.PublicKey
+}
+
+func (f *fakeKeySource) KeyForKid(kid string) (*rsa.PublicKey, error) {
+	k, ok := f.keys[kid]
+	if !ok {
+		return nil, errNoKey
+	}
+	return k, nil
+}
+
+var errNoKey = jwt.ErrTokenUnverifiable
+
+func generateRSAKeyPair(t *testing.T) *rsa.PrivateKey {
+	t.Helper()
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating RSA key: %v", err)
+	}
+	return key
+}
+
+type tokenOpts struct {
+	kid      string
+	alg      jwt.SigningMethod
+	issuer   string
+	audience string
+	subject  string
+	scope    string
+	expired  bool
+	notYet   bool
+}
+
+func signToken(t *testing.T, key *rsa.PrivateKey, opts tokenOpts) string {
+	t.Helper()
+	now := time.Now()
+	exp := now.Add(10 * time.Minute)
+	if opts.expired {
+		exp = now.Add(-1 * time.Minute)
+	}
+	iat := now
+	nbf := now
+	if opts.notYet {
+		nbf = now.Add(1 * time.Hour)
+	}
+	c := claims{
+		Scope: opts.scope,
+		RegisteredClaims: jwt.RegisteredClaims{
+			Issuer:    opts.issuer,
+			Subject:   opts.subject,
+			Audience:  jwt.ClaimStrings{opts.audience},
+			ExpiresAt: jwt.NewNumericDate(exp),
+			IssuedAt:  jwt.NewNumericDate(iat),
+			NotBefore: jwt.NewNumericDate(nbf),
+		},
+	}
+	token := jwt.NewWithClaims(opts.alg, c)
+	token.Header["kid"] = opts.kid
+	signed, err := token.SignedString(key)
+	if err != nil {
+		t.Fatalf("signing token: %v", err)
+	}
+	return signed
+}
+
+func defaultOpts(kid string) tokenOpts {
+	return tokenOpts{
+		kid:      kid,
+		alg:      jwt.SigningMethodRS256,
+		issuer:   testIssuer,
+		audience: testAudience,
+		subject:  "client-under-test",
+		scope:    string(ScopeSearch),
+	}
+}
+
+func newTestMiddleware(keys map[string]*rsa.PublicKey) func(http.Handler) http.Handler {
+	return NewJWTMiddleware(&fakeKeySource{keys: keys}, testIssuer, testAudience)
+}
+
+func okHandler(gotCtx *AuthContext) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if ac, ok := AuthContextFromContext(r.Context()); ok {
+			*gotCtx = ac
+		}
+		w.WriteHeader(http.StatusOK)
+	})
+}
+
+func doRequest(mw func(http.Handler) http.Handler, token string) (*httptest.ResponseRecorder, AuthContext) {
+	var gotCtx AuthContext
+	h := mw(okHandler(&gotCtx))
+	req := httptest.NewRequest(http.MethodGet, "/profiles/search", nil)
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	return w, gotCtx
+}
+
+func TestJWTMiddleware_ValidTokenPopulatesAuthContext(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	tok := signToken(t, key, defaultOpts("key-1"))
+
+	w, ac := doRequest(mw, tok)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	if ac.Sub != "client-under-test" || ac.Scope != ScopeSearch {
+		t.Errorf("AuthContext = %+v, want Sub=client-under-test Scope=profile:search", ac)
+	}
+}
+
+func TestJWTMiddleware_MissingToken_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	w, _ := doRequest(mw, "")
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", w.Code)
+	}
+}
+
+func TestJWTMiddleware_ExpiredToken_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	opts := defaultOpts("key-1")
+	opts.expired = true
+	tok := signToken(t, key, opts)
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for an expired token", w.Code)
+	}
+}
+
+func TestJWTMiddleware_WrongAudience_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	opts := defaultOpts("key-1")
+	opts.audience = "some-other-service"
+	tok := signToken(t, key, opts)
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for a mismatched audience", w.Code)
+	}
+}
+
+func TestJWTMiddleware_WrongIssuer_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	opts := defaultOpts("key-1")
+	opts.issuer = "https://not-the-real-issuer.example"
+	tok := signToken(t, key, opts)
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for a mismatched issuer", w.Code)
+	}
+}
+
+// TestJWTMiddleware_AlgNone_401 is RFC 8725 §3.1's classic attack: a
+// token whose header claims alg:none, carrying no signature at all. The
+// algorithm-allowlist passed to jwt.ParseWithClaims must reject this
+// before ever reaching the keyfunc/signature-verification step.
+func TestJWTMiddleware_AlgNone_401(t *testing.T) {
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{})
+
+	unsignedClaims := claims{
+		Scope: string(ScopeSearch),
+		RegisteredClaims: jwt.RegisteredClaims{
+			Issuer:    testIssuer,
+			Subject:   "attacker",
+			Audience:  jwt.ClaimStrings{testAudience},
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(10 * time.Minute)),
+		},
+	}
+	tok := jwt.NewWithClaims(jwt.SigningMethodNone, unsignedClaims)
+	signed, err := tok.SignedString(jwt.UnsafeAllowNoneSignatureType)
+	if err != nil {
+		t.Fatalf("constructing alg:none token: %v", err)
+	}
+
+	w, _ := doRequest(mw, signed)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for an alg:none token", w.Code)
+	}
+}
+
+// TestJWTMiddleware_HMACConfusionWithPublicKeyAsSecret_401 is RFC 8725
+// §3.1's other classic attack: an attacker who knows the RSA public key
+// (public by definition — it's published as JWKS) signs a token with
+// HS256 using the PEM-encoded public key bytes as the HMAC secret. A
+// verifier that blindly uses whatever alg the token header claims, and
+// hands the "key" returned by its keyfunc to that algorithm's verifier,
+// gets fooled: HS256 with the public key as the secret "verifies"
+// successfully against a keyfunc that returns the RSA public key
+// unconditionally. The algorithm allowlist must reject this the same way
+// it rejects alg:none.
+func TestJWTMiddleware_HMACConfusionWithPublicKeyAsSecret_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+
+	pubDER := x509.MarshalPKCS1PublicKey(&key.PublicKey)
+
+	forged := claims{
+		Scope: string(ScopeSearch),
+		RegisteredClaims: jwt.RegisteredClaims{
+			Issuer:    testIssuer,
+			Subject:   "attacker",
+			Audience:  jwt.ClaimStrings{testAudience},
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(10 * time.Minute)),
+		},
+	}
+	tok := jwt.NewWithClaims(jwt.SigningMethodHS256, forged)
+	tok.Header["kid"] = "key-1"
+	signed, err := tok.SignedString(pubDER)
+	if err != nil {
+		t.Fatalf("signing HMAC-confusion token: %v", err)
+	}
+
+	w, _ := doRequest(mw, signed)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for an HS256-with-public-key-as-secret forged token", w.Code)
+	}
+}
+
+// TestJWTMiddleware_KidRotation_BothKeysVerify is the acceptance
+// criterion for key rotation: two tokens signed under two different kids
+// both verify successfully when both keys are configured, supporting a
+// rotation overlap window.
+func TestJWTMiddleware_KidRotation_BothKeysVerify(t *testing.T) {
+	oldKey := generateRSAKeyPair(t)
+	newKey := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{
+		"key-old": &oldKey.PublicKey,
+		"key-new": &newKey.PublicKey,
+	})
+
+	oldTok := signToken(t, oldKey, defaultOpts("key-old"))
+	newTok := signToken(t, newKey, defaultOpts("key-new"))
+
+	if w, _ := doRequest(mw, oldTok); w.Code != http.StatusOK {
+		t.Errorf("old-kid token status = %d, want 200 during rotation overlap", w.Code)
+	}
+	if w, _ := doRequest(mw, newTok); w.Code != http.StatusOK {
+		t.Errorf("new-kid token status = %d, want 200 during rotation overlap", w.Code)
+	}
+}
+
+func TestJWTMiddleware_UnknownKid_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	tok := signToken(t, key, defaultOpts("key-does-not-exist"))
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for an unrecognized kid", w.Code)
+	}
+}
+
+func TestJWTMiddleware_WrongKeyForKid_401(t *testing.T) {
+	signingKey := generateRSAKeyPair(t)
+	otherKey := generateRSAKeyPair(t)
+	// The keyfunc returns otherKey's public key for "key-1" — simulating
+	// a mismatched/corrupted JWKS entry. Signature verification must fail.
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &otherKey.PublicKey})
+	tok := signToken(t, signingKey, defaultOpts("key-1"))
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 when the signature doesn't verify against the returned key", w.Code)
+	}
+}
+
+func TestJWTMiddleware_NoScopeClaim_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	opts := defaultOpts("key-1")
+	opts.scope = ""
+	tok := signToken(t, key, opts)
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for a token with no recognized scope", w.Code)
+	}
+}
+
+func TestJWTMiddleware_MultipleScopes_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	opts := defaultOpts("key-1")
+	opts.scope = string(ScopeSearch) + " " + string(ScopeReadOwn)
+	tok := signToken(t, key, opts)
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 — this verifier does not disambiguate a multi-scope token per request", w.Code)
+	}
+}
+
+func TestJWTMiddleware_NoSubClaim_401(t *testing.T) {
+	key := generateRSAKeyPair(t)
+	mw := newTestMiddleware(map[string]*rsa.PublicKey{"key-1": &key.PublicKey})
+	opts := defaultOpts("key-1")
+	opts.subject = ""
+	tok := signToken(t, key, opts)
+
+	w, _ := doRequest(mw, tok)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 for a token with no sub claim", w.Code)
+	}
+}
+
+func TestDeadlineMiddleware_AppliesDeadline(t *testing.T) {
+	var sawDeadline bool
+	h := NewDeadlineMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, sawDeadline = r.Context().Deadline()
+		w.WriteHeader(http.StatusOK)
+	}))
+	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if !sawDeadline {
+		t.Error("request context should carry a deadline after NewDeadlineMiddleware")
+	}
+}
diff --git a/internal/api/stopgap_authorizer.go b/internal/api/stopgap_authorizer.go
new file mode 100644
index 0000000..a63c3fc
--- /dev/null
+++ b/internal/api/stopgap_authorizer.go
@@ -0,0 +1,53 @@
+package api
+
+import "context"
+
+// StopgapAuthorizer is a TEMPORARY, default-deny Authorizer stand-in —
+// NOT the real caller_referral-backed policy engine (handoff-03-auth.md
+// v3's F8 resolution names that as a later story's own datastore work).
+//
+// Ruled by Marcus Ilori (02), in response to a direct question before
+// this was wired to a live public URL: "A permissive allow-all
+// Authorizer must never be deployed to a live public URL on a shared
+// production cluster, 'temporary' or not — that's the exact failure this
+// design exists to prevent, and it's a public repo, so being
+// permissive-even-briefly is a permanent public fact." Ruling: default-
+// deny, in-memory, hard-coded with a small fixed (sub, allowed record id)
+// map for the seeded QA client credential (LT-51) — enough to
+// demonstrate both the allow and deny paths of read:own's referral check
+// in the live review, without ever allowing an arbitrary caller through.
+//
+// This only affects ScopeReadOwn's referral-membership check.
+// ScopeReadAny's authorization is "has a valid reason_code," already
+// checked in the handler before Authorize() is ever called; ScopeSearch
+// has no per-record target for this Authorizer to gate at all. Both
+// return true unconditionally here — there is no real caller_referral
+// data this stopgap could consult for a real decision on those scopes
+// either way, so denying them would not be more correct, only
+// differently placeholder.
+//
+// A follow-up story replacing this with the real datastore-backed
+// implementation must exist before this is considered load-bearing
+// beyond the live-URL review — flag to the PM if it doesn't.
+type StopgapAuthorizer struct {
+	// ReadOwnAllow maps a caller sub to the set of record ids that sub
+	// may read under ScopeReadOwn — the hard-coded "referral" set this
+	// stopgap stands in for. Empty/nil means the map denies everything,
+	// which is the safe default for any sub not explicitly seeded here.
+	ReadOwnAllow map[string]map[string]bool
+}
+
+func (a *StopgapAuthorizer) Authorize(_ context.Context, sub string, scope Scope, target string) (bool, error) {
+	switch scope {
+	case ScopeReadOwn:
+		allowed, ok := a.ReadOwnAllow[sub]
+		if !ok {
+			return false, nil
+		}
+		return allowed[target], nil
+	case ScopeReadAny, ScopeSearch:
+		return true, nil
+	default:
+		return false, nil
+	}
+}
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
new file mode 100644
index 0000000..1f0b6f8
--- /dev/null
+++ b/internal/app/verifier_router_test.go
@@ -0,0 +1,162 @@
+package app
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"

{
  "command": "gh pr diff 30 --repo wtvamp/loginid-takehome 2>&1 | sed -n '1500,2000p'"
}

+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+
+	"loginid-takehome/internal/config"
+	"loginid-takehome/internal/dao"
+	"loginid-takehome/internal/model"
+)
+
+// fakeRepo is a minimal dao.Repository — only Profiles().Search is
+// exercised by this file's tests; everything else panics, so a test
+// that reaches an unexpected method fails loudly rather than silently
+// zero-valuing (mirrors internal/api's own hand-written fakes,
+// decisions/test-double-strategy.md).
+type fakeRepo struct{ profiles fakeProfiles }
+
+func (f *fakeRepo) Profiles() dao.ProfileRepository       { return &f.profiles }
+func (f *fakeRepo) Credentials() dao.CredentialRepository { panic("not used") }
+func (f *fakeRepo) Methods() dao.AuthMethodRepository     { panic("not used") }
+func (f *fakeRepo) CreateProfileWithCredential(ctx context.Context, p *model.UserProfile, c *model.UserCredential) (*model.UserProfile, *model.UserCredential, error) {
+	panic("not used")
+}
+func (f *fakeRepo) DeleteExpired(ctx context.Context, class dao.RetentionClass, olderThan time.Time, maxRows int) (dao.SweepResult, error) {
+	panic("not used")
+}
+func (f *fakeRepo) DeleteProfile(ctx context.Context, id string, externalRef *string) error {
+	panic("not used")
+}
+func (f *fakeRepo) Close() error { return nil }
+
+type fakeProfiles struct{}
+
+func (fakeProfiles) Get(ctx context.Context, id string) (*model.UserProfile, error) {
+	return &model.UserProfile{ID: id, Name: "Jane Doe"}, nil
+}
+func (fakeProfiles) Search(ctx context.Context, q dao.ProfileQuery) ([]model.UserProfile, int, error) {
+	return []model.UserProfile{{ID: "p1", Name: "Jane Doe"}}, 1, nil
+}
+func (fakeProfiles) Create(ctx context.Context, p *model.UserProfile) (*model.UserProfile, error) {
+	panic("not used")
+}
+func (fakeProfiles) Update(ctx context.Context, p *model.UserProfile) (*model.UserProfile, error) {
+	panic("not used")
+}
+func (fakeProfiles) Upsert(ctx context.Context, p *model.UserProfile) (*model.UserProfile, error) {
+	panic("not used")
+}
+func (fakeProfiles) Delete(ctx context.Context, id string) error { panic("not used") }
+
+const (
+	testIssuer   = "https://auth.loginid-takehome.internal"
+	testAudience = "loginid-api-service"
+)
+
+func startFakeJWKS(t *testing.T, kid string, pub *rsa.PublicKey) *httptest.Server {
+	t.Helper()
+	body, err := json.Marshal(map[string]any{
+		"keys": []map[string]string{{
+			"kty": "RSA",
+			"kid": kid,
+			"alg": "RS256",
+			"use": "sig",
+			"n":   base64.RawURLEncoding.EncodeToString(pub.N.Bytes()),
+			"e":   base64.RawURLEncoding.EncodeToString([]byte{1, 0, 1}), // 65537
+		}},
+	})
+	if err != nil {
+		t.Fatalf("marshaling fake JWKS: %v", err)
+	}
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(body)
+	}))
+}
+
+func signTestToken(t *testing.T, key *rsa.PrivateKey, kid, scope string) string {
+	t.Helper()
+	c := jwt.MapClaims{
+		"iss":   testIssuer,
+		"aud":   testAudience,
+		"sub":   "client-under-test",
+		"scope": scope,
+		"exp":   time.Now().Add(10 * time.Minute).Unix(),
+		"iat":   time.Now().Unix(),
+	}
+	tok := jwt.NewWithClaims(jwt.SigningMethodRS256, c)
+	tok.Header["kid"] = kid
+	signed, err := tok.SignedString(key)
+	if err != nil {
+		t.Fatalf("signing test token: %v", err)
+	}
+	return signed
+}
+
+func TestNewVerifierRouter_UnauthenticatedRequest_401(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	jwks := startFakeJWKS(t, "key-1", &key.PublicKey)
+	defer jwks.Close()
+
+	cfg := config.Config{AuthJWTIssuer: testIssuer, AuthJWTAudience: testAudience, AuthJWKSURL: jwks.URL}
+	router := NewVerifierRouter(cfg, &fakeRepo{})
+
+	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401 with no bearer token", w.Code)
+	}
+}
+
+// TestNewVerifierRouter_AuthenticatedSearch_ReachesHandler proves the
+// full stack — deadline middleware, JWT verification against a real
+// JWKS-over-HTTP fetch, AuthContext population, and LT-39's handler —
+// is wired together correctly end to end, not just each piece in
+// isolation.
+func TestNewVerifierRouter_AuthenticatedSearch_ReachesHandler(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	jwks := startFakeJWKS(t, "key-1", &key.PublicKey)
+	defer jwks.Close()
+
+	cfg := config.Config{AuthJWTIssuer: testIssuer, AuthJWTAudience: testAudience, AuthJWKSURL: jwks.URL}
+	router := NewVerifierRouter(cfg, &fakeRepo{})
+	tok := signTestToken(t, key, "key-1", "profile:search")
+
+	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"jane"}`))
+	req.Header.Set("Authorization", "Bearer "+tok)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200, body=%s", w.Code, w.Body.String())
+	}
+}
+
+func TestNewVerifierRouter_HealthzUnaffectedByAuth(t *testing.T) {
+	cfg := config.Config{AuthJWTIssuer: testIssuer, AuthJWTAudience: testAudience, AuthJWKSURL: "http://unused.invalid"}
+	router := NewVerifierRouter(cfg, &fakeRepo{})
+
+	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d, want 200 — /healthz must stay unauthenticated per handoff-03-auth.md", w.Code)
+	}
+}
diff --git a/internal/config/config.go b/internal/config/config.go
index bce9af9..37cf275 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -29,6 +29,23 @@ type Config struct {
 
 	AuthJWTIssuer   string
 	AuthJWTAudience string
+	// AuthJWKSURL is the verifier's only path to public key material
+	// (LT-40, handoff-03-auth.md v4): the issuer Deployment's in-cluster
+	// ClusterIP Service JWKS endpoint, e.g.
+	// "http://api-service-issuer.loginid-takehome.svc.cluster.local/.well-known/jwks.json".
+	// Never a mounted key file — JWKS survives rotation without a config
+	// change, since the verifier fetches by kid.
+	AuthJWKSURL string
+
+	// AuthzQASub and AuthzQAAllowedProfileID seed the temporary,
+	// default-deny StopgapAuthorizer (internal/api) for LT-40/LT-51's
+	// joint live-URL review only — see StopgapAuthorizer's own doc
+	// comment for why a permissive default was explicitly ruled out.
+	// Both empty (the default) means the stand-in denies every
+	// profile:read:own request, the safe default until LT-51 seeds a
+	// real QA client credential and this is set to match it.
+	AuthzQASub              string
+	AuthzQAAllowedProfileID string
 
 	ConnectorJWTAudience  string
 	ConnectorClientID     string
@@ -87,6 +104,10 @@ func Load() (Config, error) {
 
 		AuthJWTIssuer:   os.Getenv("AUTH_JWT_ISSUER"),
 		AuthJWTAudience: os.Getenv("AUTH_JWT_AUDIENCE"),
+		AuthJWKSURL:     os.Getenv("AUTH_JWKS_URL"),
+
+		AuthzQASub:              os.Getenv("AUTHZ_QA_SUB"),
+		AuthzQAAllowedProfileID: os.Getenv("AUTHZ_QA_ALLOWED_PROFILE_ID"),
 
 		ConnectorJWTAudience:  os.Getenv("CONNECTOR_JWT_AUDIENCE"),
 		ConnectorClientID:     os.Getenv("CONNECTOR_CLIENT_ID"),

{
  "command": "gh pr diff 30 --repo wtvamp/loginid-takehome 2>&1 | wc -l; gh pr diff 30 --repo wtvamp/loginid-takehome 2>&1 | sed -n '2000,2400p'"
}

    1689

{
  "command": "gh pr view 30 --repo wtvamp/loginid-takehome --json body,title,files -q '.title, .body' 2>&1 | head -100"
}

LT-40: JWT verification middleware, live router wiring
## 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 | grep -n \"stopgap\" -i"
}

1343:diff --git a/internal/api/stopgap_authorizer.go b/internal/api/stopgap_authorizer.go
1347:+++ b/internal/api/stopgap_authorizer.go
1353:+// StopgapAuthorizer is a TEMPORARY, default-deny Authorizer stand-in —
1373:+// data this stopgap could consult for a real decision on those scopes
1380:+type StopgapAuthorizer struct {
1383:+	// stopgap stands in for. Empty/nil means the map denies everything,
1388:+func (a *StopgapAuthorizer) Authorize(_ context.Context, sub string, scope Scope, target string) (bool, error) {
1448:+		Authz: &api.StopgapAuthorizer{
1449:+			ReadOwnAllow: stopgapReadOwnAllow(cfg),
1471:+// stopgapReadOwnAllow builds StopgapAuthorizer's hard-coded (sub ->
1475:+func stopgapReadOwnAllow(cfg config.Config) map[string]map[string]bool {
1668:+	// default-deny StopgapAuthorizer (internal/api) for LT-40/LT-51's
1669:+	// joint live-URL review only — see StopgapAuthorizer's own doc

{
  "command": "cat > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-review.md << 'EOF'\nIndependent review: Tomasz Wrede (02 Adversary) — PR #30 (LT-40, JWT verification middleware)\n\nI read the full diff (`gh pr diff 30`), not just the PR description, and checked each of the five things I was asked to attack. Ranked by what I'd fix first.\n\n**1. JWKS fail-open on fetch failure has no staleness bound. HIGH.**\n`JWKSCache.KeyForKid` (`internal/api/jwks.go`): on a failed refresh it keeps serving the last-successfully-fetched key set (`if c.keys == nil { return nil, err }` — else it falls through to the old map), and retries on every subsequent call since `fetchedAt` is never advanced on failure. That retry-every-call behavior is good — it heals fast once the issuer recovers — but there is no ceiling on how long \"stale\" is allowed to get, and no alerting on a prolonged fetch-failure run. Concretely: if a key is being retired *because it's compromised* and the issuer's JWKS endpoint is unreachable during that incident (network partition, or the issuer itself is what's being remediated), the verifier keeps accepting tokens signed by the revoked key indefinitely, for as long as the fetch keeps failing — which is exactly the scenario a bounded staleness window exists to prevent. The code comment reasons about *accepting a new key slightly late* being safe; it doesn't reason about *never stopping accepting an old key* being unsafe. Ask: a max-staleness bound (fail closed — reject all tokens — once the cache has been stale beyond N× the fetch TTL) plus an alert on sustained fetch failure.\n\n**2. Unknown `kid` never forces an out-of-band refetch. MEDIUM-HIGH, and it compounds with #1 in the wrong direction.**\nSame function: the refresh condition is `c.keys == nil || time.Since(c.fetchedAt) >= c.ttl` — it does **not** check \"is this specific kid missing.\" If the issuer rotates in a new key and a client is issued a token under it before the verifier's next scheduled TTL refresh (up to 15 minutes, per `jwksCacheTTL`), that legitimately-signed token gets rejected with \"no key found for kid\" until the cache naturally expires — the code never tries the obvious fix (refetch once on an unrecognized kid, then fail only if it's still missing). Combined with #1, this design fails open on the wrong side (revoked keys linger past their retirement) and fails closed on the wrong side (freshly-rotated keys aren't recognized promptly) — both directions of the rotation-overlap window are handled worse than the design intends. `TestJWTMiddleware_KidRotation_BothKeysVerify` only proves both keys work when both are *already* in one JWKS response fetched once; it doesn't test the timing gap between rotation and refetch.\n\n**3. `StopgapAuthorizer`'s deny path has zero test coverage. MEDIUM.**\nThe default-deny logic itself reads correctly (`ReadOwnAllow[sub]` miss → `false`; unrecognized scope → `false`), and the PM's ruling to require default-deny is followed in the code. But there is no `stopgap_authorizer_test.go` at all in this PR, and `verifier_router_test.go` only exercises `POST /profiles/search` (no per-record authz) plus the unauthenticated and healthz paths — `GET /profiles/{id}` under `read:own` is never hit by a test, allow or deny. \"Confirm the deny path is actually exercised by a test\" — it isn't. The code is probably right; nothing here proves it, and this is exactly the kind of authz code where \"probably right, never tested\" is the wrong bar for something Marcus explicitly flagged as risky enough to rule on before it touched a live URL.\n\n**4. `GrantLimiter` fail-closed-on-store-outage — not yet answerable, flagging forward rather than as a defect.**\nCorrectly keyed independently on `client_id` and source IP (`TestGrantLimiter_KeyedIndependentlyByClientIDAndSourceIP` proves either key blocks the attempt), and it's genuinely not wired to a live endpoint in this PR — the in-process map has no external store to fail. The question only becomes real when LT-51 gives it a shared/distributed backing store; flag now so LT-51 doesn't build that store and discover the fail-open/fail-closed question was never decided.\n\n**5. Algorithm confusion — confirmed, and confirmed properly. PASS, no gap.**\nThis is the finding I raised at S8 as a design-doc gap. It's closed for real here, not just claimed: `jwt.WithValidMethods([]string{jwtAlgorithm})` (RS256-only) is passed on every parse, ahead of the keyfunc — and the test suite has both RFC 8725 §3.1 attacks, not just the easy one: `TestJWTMiddleware_AlgNone_401` (bare `alg:none`) **and** `TestJWTMiddleware_HMACConfusionWithPublicKeyAsSecret_401`, which actually forges an HS256 token using the RSA public key's DER bytes as the HMAC secret and confirms it's rejected before signature verification. That's the specific attack I asked for by name, not a weaker stand-in for it — good work, no notes.\n\nNet: 1 and 2 together are the same underlying gap (no forced refetch tied to key state, only to a calendar TTL) manifesting in both directions of a rotation event; I'd want at least a bounded max-staleness fail-closed added for #1 before this is load-bearing beyond the QA review, since #3 doesn't have that safety net either.\nEOF\nwc -l /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-review.md"
}

      20 /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-review.md

{
  "command": "gh pr comment 30 --repo wtvamp/loginid-takehome --body-file /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-review.md"
}

https://github.com/wtvamp/loginid-takehome/pull/30#issuecomment-5653019889

{
  "command": "cd /tmp && rm -rf pr30check && mkdir pr30check && cd pr30check && gh pr diff 30 --repo wtvamp/loginid-takehome --patch > full.diff 2>&1; git log --oneline -5 2>/dev/null; echo \"---\"; gh api repos/wtvamp/loginid-takehome/commits/03181f6 --jq '.files[].filename' 2>&1"
}

---
cmd/api-service/main.go
internal/api/audit.go
internal/api/errors.go
internal/api/grantlimiter.go
internal/api/grantlimiter_test.go
internal/api/jwks.go
internal/api/jwks_test.go
internal/api/jwtmiddleware.go
internal/api/jwtmiddleware_test.go
internal/api/stopgap_authorizer_test.go
internal/app/verifier_router.go
internal/app/verifier_router_test.go
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/02-ai-security-architecture

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/03181f6.diff 2>&1 | head -800"
}

{"message":"No commit found for SHA: 03181f6.diff","documentation_url":"https://docs.github.com/rest/commits/commits#get-a-commit","status":"422"}gh: No commit found for SHA: 03181f6.diff (HTTP 422)

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/03181f6 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | wc -l"
}

    1230

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/03181f6 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | awk '/^diff --git a\\/internal\\/api\\/jwks.go/,/^diff --git a\\/internal\\/api\\/jwks_test.go/' "
}

diff --git a/internal/api/jwks.go b/internal/api/jwks.go
index 9289dea..238c4e5 100644
--- a/internal/api/jwks.go
+++ b/internal/api/jwks.go
@@ -8,11 +8,14 @@
 package api
 
 import (
+	"context"
 	"crypto/rsa"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
+	"log"
 	"math/big"
 	"net/http"
 	"sync"
@@ -81,11 +84,42 @@ func rsaPublicKeyFromJWK(k jwk) (*rsa.PublicKey, error) {
 
 // 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.
+// map-backed fake. ctx carries the calling request's own deadline —
+// KeyForKid's real implementation must bound its network I/O by it, not
+// by some separate, undocumented timeout (Nolan Reyes, PR #30 review: a
+// hung fetch that ignores the caller's context defeats the deadline
+// middleware's whole guarantee).
 type KeySource interface {
-	KeyForKid(kid string) (*rsa.PublicKey, error)
+	KeyForKid(ctx context.Context, kid string) (*rsa.PublicKey, error)
 }
 
+// ErrJWKSStale is returned by JWKSCache.KeyForKid when the cached key set
+// has exceeded its max-staleness bound and could not be refreshed — the
+// verifier must fail closed rather than trust keys this old (Tomasz
+// Wrede, 02 cold review; PM ruling). Exported so NewJWTMiddleware can log
+// a distinct audit event (AuditJWKSUnavailable) for this specific
+// failure mode, rather than folding it into an ordinary auth failure.
+var ErrJWKSStale = errors.New("api: JWKS cache exceeded max staleness and could not be refreshed")
+
+// jwksMaxStalenessMultiple and jwksUnknownKidRefetchInterval are the
+// concrete numbers the PM ruled on for Tomasz Wrede's two findings:
+//   - a signing key can be revoked BECAUSE it's compromised; if the JWKS
+//     endpoint is also unreachable during that same incident, a
+//     stale-cache-forever fallback would keep verifying tokens signed by
+//     the revoked key for as long as fetches keep failing. Bounding
+//     staleness at a multiple of the normal refresh interval (ttl) turns
+//     "fail open forever" into "fail open for a bounded window, then
+//     fail closed" — resilient to a brief blip, not to an extended one.
+//   - an unknown kid could be a key the issuer rotated in since the last
+//     TTL-driven refresh; without an out-of-band refetch, a freshly
+//     rotated key would be rejected for up to a full TTL. Rate-limited
+//     so an unknown-kid flood can't be used to hammer the issuer's JWKS
+//     endpoint.
+const (
+	jwksMaxStalenessMultiple      = 3
+	jwksUnknownKidRefetchInterval = 30 * time.Second
+)
+
 // 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
@@ -94,58 +128,164 @@ type KeySource interface {
 // 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
+	url          string
+	ttl          time.Duration
+	maxStaleness time.Duration
+	httpClient   *http.Client
+	now          func() time.Time
 
-	mu        sync.Mutex
-	keys      map[string]*rsa.PublicKey
-	fetchedAt time.Time
+	mu                  sync.Mutex
+	keys                map[string]*rsa.PublicKey
+	fetchedAt           time.Time // last SUCCESSFUL fetch
+	consecutiveFailures int
+	staleAlerted        bool
+	lastUnknownKidRetry time.Time
 }
 
+// defaultJWKSClientTimeout backstops a hung fetch (a connection that
+// accepts but never responds — not a hard refusal, which fails fast on
+// its own) when no context deadline is shorter. Distinct from and
+// independent of a per-request context deadline: this fires even for a
+// call that somehow reaches fetch() with no deadline on its context at
+// all, which the http.Client.Timeout field guards against regardless of
+// context (Nolan Reyes, PR #30 review — the shipped wiring passed nil
+// for httpClient, resolving to http.DefaultClient, whose zero-value
+// Timeout means "none").
+const defaultJWKSClientTimeout = 10 * time.Second
+
 // NewJWKSCache constructs a cache fetching from url, refetching at most
-// once per ttl. A nil httpClient uses http.DefaultClient.
+// once per ttl (and, for an unrecognized kid specifically, at most once
+// per jwksUnknownKidRefetchInterval outside the normal TTL cycle). A nil
+// httpClient constructs one with defaultJWKSClientTimeout — never
+// http.DefaultClient, whose Timeout is unset (no bound at all) by
+// default. maxStaleness is jwksMaxStalenessMultiple * ttl.
 func NewJWKSCache(url string, ttl time.Duration, httpClient *http.Client) *JWKSCache {
 	if httpClient == nil {
-		httpClient = http.DefaultClient
+		httpClient = &http.Client{Timeout: defaultJWKSClientTimeout}
+	}
+	return &JWKSCache{
+		url:          url,
+		ttl:          ttl,
+		maxStaleness: jwksMaxStalenessMultiple * ttl,
+		httpClient:   httpClient,
+		now:          time.Now,
 	}
-	return &JWKSCache{url: url, ttl: ttl, httpClient: httpClient}
 }
 
-func (c *JWKSCache) KeyForKid(kid string) (*rsa.PublicKey, error) {
+// KeyForKid never holds c.mu across a network fetch (Nolan Reyes, PR #30
+// review, finding #2): the prior shape held the lock for the whole
+// function body, so one hung fetch stalled every other concurrent
+// request through this same cache instance — i.e. every authenticated
+// request the verifying Deployment was serving, not just the one that
+// triggered the refresh. Concurrent callers that both decide a refresh
+// is due may both fetch; that's cheap, occasional duplicate work, and far
+// preferable to serializing the whole authenticated surface behind one
+// goroutine's network call.
+func (c *JWKSCache) KeyForKid(ctx context.Context, kid string) (*rsa.PublicKey, error) {
 	c.mu.Lock()
-	defer c.mu.Unlock()
+	needsRefresh := c.keys == nil || c.now().Sub(c.fetchedAt) >= c.ttl
+	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()
+	if needsRefresh {
+		if err := c.refresh(ctx); err != nil {
+			return nil, err
 		}
 	}
 
-	key, ok := c.keys[kid]
-	if !ok {
-		return nil, fmt.Errorf("api: no key found for kid %q", kid)
+	if key, ok := c.lookupKey(kid); ok {
+		return key, nil
+	}
+
+	// Unknown kid: might be a key the issuer rotated in since the last
+	// TTL-driven refresh. One rate-limited out-of-band refetch before
+	// giving up, so a freshly-rotated key isn't rejected for up to a
+	// full TTL (Tomasz Wrede, 02 cold review). Best-effort: its error is
+	// deliberately ignored here — the outcome that matters is whether
+	// the retry populated the kid we're actually looking for, and a
+	// refresh() failure here has already been handled (logged / staleness
+	// tracked) inside refresh() itself.
+	if c.reserveUnknownKidRetry() {
+		_ = c.refresh(ctx)
+		if key, ok := c.lookupKey(kid); ok {
+			return key, nil
+		}
 	}
-	return key, nil
+
+	return nil, fmt.Errorf("api: no key found for kid %q", kid)
 }
 
-func (c *JWKSCache) fetch() (map[string]*rsa.PublicKey, error) {
-	resp, err := c.httpClient.Get(c.url)
+func (c *JWKSCache) lookupKey(kid string) (*rsa.PublicKey, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	k, ok := c.keys[kid]
+	return k, ok
+}
+
+// reserveUnknownKidRetry reports whether an unknown-kid-triggered refetch
+// may proceed now, and if so atomically marks one as just having started
+// — a caller enumerating unknown kids can trigger at most one extra
+// fetch per jwksUnknownKidRefetchInterval, not one per request.
+func (c *JWKSCache) reserveUnknownKidRetry() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.now().Sub(c.lastUnknownKidRetry) < jwksUnknownKidRefetchInterval {
+		return false
+	}
+	c.lastUnknownKidRetry = c.now()
+	return true
+}
+
+// refresh performs the network fetch (no lock held during it) and
+// updates cache state. Returns an error only when the caller must fail
+// the whole verification: no cache exists yet (cold start against an
+// unreachable issuer), or the existing cache has exceeded maxStaleness —
+// wrapped in ErrJWKSStale in the latter case specifically, so the
+// middleware can log AuditJWKSUnavailable rather than an ordinary auth
+// failure. A transient failure within the staleness bound returns nil:
+// the stale cache is still good enough to use, per the resilience this
+// mechanism exists for.
+func (c *JWKSCache) refresh(ctx context.Context) error {
+	fresh, err := c.fetch(ctx)
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if err == nil {
+		c.keys = fresh
+		c.fetchedAt = c.now()
+		c.consecutiveFailures = 0
+		c.staleAlerted = false
+		return nil
+	}
+
+	c.consecutiveFailures++
+
+	if c.keys == nil {
+		return err
+	}
+
+	staleSince := c.now().Sub(c.fetchedAt)
+	if staleSince > c.maxStaleness {
+		if !c.staleAlerted {
+			c.staleAlerted = true
+			// Log line for 04's alerting pipeline on a prolonged
+			// fetch-failure run — not a policy decision (AuditLogger is
+			// for those), an operational signal that this process's own
+			// key infrastructure is degraded.
+			log.Printf("api: JWKS unrefreshable for %s across %d consecutive failures (exceeds max staleness %s) — failing closed: %v",
+				staleSince, c.consecutiveFailures, c.maxStaleness, err)
+		}
+		return fmt.Errorf("%w: stale for %s across %d consecutive failures: %v", ErrJWKSStale, staleSince, c.consecutiveFailures, err)
+	}
+	return nil
+}
+
+func (c *JWKSCache) fetch(ctx context.Context) (map[string]*rsa.PublicKey, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("api: building JWKS request for %s: %w", c.url, err)
+	}
+	resp, err := c.httpClient.Do(req)
 	if err != nil {
 		return nil, fmt.Errorf("api: fetching JWKS from %s: %w", c.url, err)
 	}
diff --git a/internal/api/jwks_test.go b/internal/api/jwks_test.go

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/03181f6 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | awk '/^diff --git a\\/internal\\/api\\/jwks_test.go/,/^diff --git a\\/internal\\/api\\/jwtmiddleware.go/'"
}

diff --git a/internal/api/jwks_test.go b/internal/api/jwks_test.go
index 7478b48..70d57b0 100644
--- a/internal/api/jwks_test.go
+++ b/internal/api/jwks_test.go
@@ -1,12 +1,15 @@
 package api
 
 import (
+	"context"
 	"crypto/rand"
 	"crypto/rsa"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
+	"sync/atomic"
 	"testing"
 	"time"
 )
@@ -33,16 +36,22 @@ func bigEndianExponent(e int) []byte {
 	return b[i:]
 }
 
+func jwksBody(t *testing.T, kid string, pub *rsa.PublicKey) []byte {
+	t.Helper()
+	doc := jwksResponse{Keys: []jwk{jwkFromPublicKey(kid, pub)}}
+	body, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatalf("marshaling JWKS: %v", err)
+	}
+	return body
+}
+
 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)
-	}
+	data := jwksBody(t, "key-1", &key.PublicKey)
 
 	keys, err := parseJWKS(data)
 	if err != nil {
@@ -52,7 +61,7 @@ func TestParseJWKS_RoundTrip(t *testing.T) {
 	if !ok {
 		t.Fatal("parsed key set missing key-1")
 	}
-	if got.N.Cmp(key.PublicKey.N) != 0 || got.E != key.PublicKey.E {
+	if got.N.Cmp(key.N) != 0 || got.E != key.E {
 		t.Error("parsed public key does not match the original")
 	}
 }
@@ -75,34 +84,55 @@ func TestParseJWKS_MissingKidIsError(t *testing.T) {
 	}
 }
 
+// jwksTestServer serves body while up, or a configurable failure while
+// down — atomic so it's safe to flip from the test goroutine while the
+// cache's own fetches run (any of them) against it.
+type jwksTestServer struct {
+	srv  *httptest.Server
+	up   atomic.Bool
+	body []byte
+}
+
+func newJWKSTestServer(body []byte) *jwksTestServer {
+	s := &jwksTestServer{body: body}
+	s.up.Store(true)
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !s.up.Load() {
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(s.body)
+	}))
+	return s
+}
+
+func (s *jwksTestServer) Close() { s.srv.Close() }
+
 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
+	var requests atomic.Int32
+	body := jwksBody(t, "key-1", &key.PublicKey)
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		requests++
+		requests.Add(1)
 		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 {
+	ctx := context.Background()
+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
 		t.Fatalf("first KeyForKid: %v", err)
 	}
-	if _, err := cache.KeyForKid("key-1"); err != nil {
+	if _, err := cache.KeyForKid(ctx, "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)
+	if requests.Load() != 1 {
+		t.Errorf("fetched the JWKS endpoint %d times, want exactly 1 (cached within TTL)", requests.Load())
 	}
 }
 
@@ -111,43 +141,38 @@ func TestJWKSCache_RefetchesAfterTTLExpires(t *testing.T) {
 	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
+	var requests atomic.Int32
+	body := jwksBody(t, "key-1", &key.PublicKey)
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		requests++
+		requests.Add(1)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write(body)
 	}))
 	defer srv.Close()
 
-	cache := NewJWKSCache(srv.URL, time.Millisecond, nil)
-	if _, err := cache.KeyForKid("key-1"); err != nil {
+	cache := NewJWKSCache(srv.URL, time.Minute, nil)
+	fakeNow := time.Now()
+	cache.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
 		t.Fatalf("first KeyForKid: %v", err)
 	}
-	time.Sleep(5 * time.Millisecond)
-	if _, err := cache.KeyForKid("key-1"); err != nil {
+	fakeNow = fakeNow.Add(time.Minute + time.Second)
+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
 		t.Fatalf("second KeyForKid: %v", err)
 	}
-	if requests < 2 {
-		t.Errorf("fetched the JWKS endpoint %d times, want at least 2 (TTL should have expired)", requests)
+	if requests.Load() < 2 {
+		t.Errorf("fetched the JWKS endpoint %d times, want at least 2 (TTL should have expired)", requests.Load())
 	}
 }
 
-func TestJWKSCache_UnknownKidIsError(t *testing.T) {
+func TestJWKSCache_UnknownKidWithNoStaleCacheIsError(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)
-	}
+	body := jwksBody(t, "key-1", &key.PublicKey)
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write(body)
@@ -155,40 +180,162 @@ func TestJWKSCache_UnknownKidIsError(t *testing.T) {
 	defer srv.Close()
 
 	cache := NewJWKSCache(srv.URL, time.Hour, nil)
-	if _, err := cache.KeyForKid("no-such-kid"); err == nil {
+	if _, err := cache.KeyForKid(context.Background(), "no-such-kid"); err == nil {
 		t.Error("expected an error for an unrecognized kid")
 	}
 }
 
+// TestJWKSCache_StaleCacheSurvivesTransientFetchFailure covers the
+// resilience case within the staleness bound: a fetch failure well
+// inside maxStaleness still serves the last-good key set.
 func TestJWKSCache_StaleCacheSurvivesTransientFetchFailure(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)
+	body := jwksBody(t, "key-1", &key.PublicKey)
+	s := newJWKSTestServer(body)
+	defer s.Close()
+
+	cache := NewJWKSCache(s.srv.URL, time.Minute, nil) // maxStaleness = 3*ttl = 3min
+	fakeNow := time.Now()
+	cache.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
+		t.Fatalf("first KeyForKid: %v", err)
+	}
+	fakeNow = fakeNow.Add(time.Minute + time.Second) // TTL expired, well within the 3min staleness bound
+	s.up.Store(false)
+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
+		t.Errorf("KeyForKid during a transient fetch failure = %v, want the stale cache to still serve the key", err)
+	}
+}
+
+// TestJWKSCache_FailsClosedPastMaxStaleness is the PM's ruling on Tomasz
+// Wrede's HIGH finding: a signing key can be revoked because it's
+// compromised, and if the JWKS endpoint is unreachable during that same
+// incident, an unbounded stale-cache fallback would keep verifying
+// tokens signed by the revoked key for as long as fetches keep failing.
+// Past maxStaleness (3x ttl, per the PM's ruling), the cache must fail
+// closed — ErrJWKSStale — rather than serve the stale set indefinitely.
+func TestJWKSCache_FailsClosedPastMaxStaleness(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
 	if err != nil {
-		t.Fatalf("marshaling JWKS: %v", err)
+		t.Fatalf("generating key: %v", err)
+	}
+	body := jwksBody(t, "key-1", &key.PublicKey)
+	s := newJWKSTestServer(body)
+	defer s.Close()
+
+	cache := NewJWKSCache(s.srv.URL, time.Minute, nil) // maxStaleness = 3min
+	fakeNow := time.Now()
+	cache.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
+		t.Fatalf("first KeyForKid: %v", err)
+	}
+	s.up.Store(false)
+	// Advance past maxStaleness (3min) from the last successful fetch.
+	fakeNow = fakeNow.Add(4 * time.Minute)
+	_, err = cache.KeyForKid(ctx, "key-1")
+	if err == nil {
+		t.Fatal("expected an error once the cache exceeds max staleness with the issuer still unreachable")
+	}
+	if !errors.Is(err, ErrJWKSStale) {
+		t.Errorf("error = %v, want it to wrap ErrJWKSStale so the middleware can log a distinct audit event", err)
+	}
+}
+
+// TestJWKSCache_UnknownKidTriggersOneRateLimitedRefetch is the PM's
+// ruling on Tomasz Wrede's MEDIUM-HIGH finding: an unknown kid (a key
+// the issuer may have just rotated in) triggers one out-of-band refetch
+// before the cache gives up, rather than waiting up to a full TTL for
+// the next calendar-scheduled refresh.
+func TestJWKSCache_UnknownKidTriggersOneRateLimitedRefetch(t *testing.T) {
+	oldKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	newKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
 	}
 
-	failing := false
+	var requests atomic.Int32
+	var serveNewKey atomic.Bool
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if failing {
-			w.WriteHeader(http.StatusInternalServerError)
-			return
+		requests.Add(1)
+		w.Header().Set("Content-Type", "application/json")
+		if serveNewKey.Load() {
+			_, _ = w.Write(jwksBody(t, "key-new", &newKey.PublicKey))
+		} else {
+			_, _ = w.Write(jwksBody(t, "key-old", &oldKey.PublicKey))
 		}
+	}))
+	defer srv.Close()
+
+	// A long TTL so the calendar-scheduled refresh would NOT fire on its
+	// own within this test — proving any successful lookup of "key-new"
+	// came from the unknown-kid-triggered refetch, not an ordinary TTL
+	// rollover.
+	cache := NewJWKSCache(srv.URL, time.Hour, nil)
+	ctx := context.Background()
+
+	if _, err := cache.KeyForKid(ctx, "key-old"); err != nil {
+		t.Fatalf("priming the cache with key-old: %v", err)
+	}
+	requestsAfterPriming := requests.Load()
+
+	// The issuer rotates: key-new is now published, but the cache's TTL
+	// hasn't expired.
+	serveNewKey.Store(true)
+	if _, err := cache.KeyForKid(ctx, "key-new"); err != nil {
+		t.Fatalf("KeyForKid(key-new) = %v, want the unknown-kid refetch to find it", err)
+	}
+	if requests.Load() <= requestsAfterPriming {
+		t.Error("expected an extra fetch triggered by the unknown kid, beyond the priming fetch")
+	}
+}
+
+func TestJWKSCache_UnknownKidRefetchIsRateLimited(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	var requests atomic.Int32
+	body := jwksBody(t, "key-1", &key.PublicKey)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests.Add(1)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write(body)
 	}))
 	defer srv.Close()
 
-	cache := NewJWKSCache(srv.URL, time.Millisecond, nil)
-	if _, err := cache.KeyForKid("key-1"); err != nil {
-		t.Fatalf("first KeyForKid: %v", err)
+	cache := NewJWKSCache(srv.URL, time.Hour, nil)
+	fakeNow := time.Now()
+	cache.now = func() time.Time { return fakeNow }
+	ctx := context.Background()
+
+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
+		t.Fatalf("priming: %v", err)
 	}
-	time.Sleep(5 * time.Millisecond)
-	failing = true
-	if _, err := cache.KeyForKid("key-1"); err != nil {
-		t.Errorf("KeyForKid during a transient fetch failure = %v, want the stale cache to still serve the key", err)
+	requestsAfterPriming := requests.Load()
+
+	// Two lookups for an unknown kid in quick succession (same fake
+	// "now") must trigger at most one extra refetch between them, not
+	// one per lookup — that's the rate limit closing the "unknown-kid
+	// flood hammers the issuer" gap.
+	_, _ = cache.KeyForKid(ctx, "no-such-kid")
+	afterFirstUnknown := requests.Load()
+	_, _ = cache.KeyForKid(ctx, "no-such-kid")
+	afterSecondUnknown := requests.Load()
+
+	if afterFirstUnknown != requestsAfterPriming+1 {
+		t.Errorf("first unknown-kid lookup triggered %d extra fetch(es), want exactly 1", afterFirstUnknown-requestsAfterPriming)
+	}
+	if afterSecondUnknown != afterFirstUnknown {
+		t.Errorf("second unknown-kid lookup (within the rate-limit window) triggered an extra fetch: %d -> %d, want no change", afterFirstUnknown, afterSecondUnknown)
 	}
 }
diff --git a/internal/api/jwtmiddleware.go b/internal/api/jwtmiddleware.go

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/03181f6 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | awk '/^diff --git a\\/internal\\/api\\/jwtmiddleware.go/,/^diff --git a\\/internal\\/api\\/stopgap_authorizer_test.go/'"
}

diff --git a/internal/api/jwtmiddleware.go b/internal/api/jwtmiddleware.go
index 07ed3d0..5bf0871 100644
--- a/internal/api/jwtmiddleware.go
+++ b/internal/api/jwtmiddleware.go
@@ -57,14 +57,14 @@ type jwtVerifier struct {
 // 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) {
+func (v *jwtVerifier) verify(ctx context.Context, 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)
+		return v.keys.KeyForKid(ctx, kid)
 	}, jwt.WithValidMethods([]string{jwtAlgorithm}), jwt.WithIssuer(v.issuer))
 	if err != nil {
 		return AuthContext{}, err
@@ -78,7 +78,7 @@ func (v *jwtVerifier) verify(tokenString string) (AuthContext, error) {
 	// 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) {
+	if !hasAudience(c.Audience, v.audience) {
 		return AuthContext{}, errors.New("token audience mismatch")
 	}
 
@@ -104,8 +104,8 @@ func hasAudience(aud jwt.ClaimStrings, want string) bool {
 }
 
 // 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
+// distinct 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
@@ -113,25 +113,34 @@ func hasAudience(aud jwt.ClaimStrings, want string) bool {
 // 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.
+// more than one DISTINCT 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.
+//
+// Deduplicated by distinct value, not by occurrence count: a malformed
+// but unambiguous claim like "profile:search profile:search" names one
+// scope repeated, not two different ones to disambiguate between, and
+// rejecting it as "more than one" would contradict this function's own
+// reasoning above (Oren Castellan, PR #30 review).
 func singleScope(raw string) (Scope, error) {
 	fields := strings.Fields(raw)
-	var found []Scope
+	found := make(map[Scope]bool, len(fields))
 	for _, f := range fields {
 		switch Scope(f) {
 		case ScopeReadOwn, ScopeReadAny, ScopeSearch:
-			found = append(found, Scope(f))
+			found[Scope(f)] = true
 		}
 	}
 	switch len(found) {
 	case 0:
 		return "", errors.New("token scope claim names no recognized scope")
 	case 1:
-		return found[0], nil
+		for s := range found {
+			return s, nil
+		}
+		panic("unreachable")
 	default:
-		return "", errors.New("token scope claim names more than one recognized scope, which this verifier does not disambiguate per request")
+		return "", errors.New("token scope claim names more than one distinct recognized scope, which this verifier does not disambiguate per request")
 	}
 }
 
@@ -144,34 +153,59 @@ func singleScope(raw string) (Scope, error) {
 // 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 {
+// for a missing AuthContext, not a new response shape — with one
+// exception: a KeySource failing closed on exceeded JWKS staleness
+// (ErrJWKSStale) logs AuditJWKSUnavailable first, since that's a
+// token-infrastructure degradation, not an ordinary bad-credential
+// attempt, and worth distinguishing in the audit trail (Tomasz Wrede, 02
+// cold review). audit may be nil (tests that don't care about audit
+// output); production wiring always passes a real AuditLogger.
+func NewJWTMiddleware(keys KeySource, issuer, audience string, audit AuditLogger) 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) {
+			ctx := r.Context()
 			tokenString, ok := bearerToken(r)
 			if !ok {
+				logAuthnFailure(ctx, audit, nil)
 				writeUnauthorized(w)
 				return
 			}
-			ac, err := v.verify(tokenString)
+			ac, err := v.verify(ctx, tokenString)
 			if err != nil {
+				logAuthnFailure(ctx, audit, err)
 				writeUnauthorized(w)
 				return
 			}
-			r = r.WithContext(WithAuthContext(r.Context(), ac))
+			r = r.WithContext(WithAuthContext(ctx, ac))
 			next.ServeHTTP(w, r)
 		})
 	}
 }
 
+func logAuthnFailure(ctx context.Context, audit AuditLogger, err error) {
+	if audit == nil {
+		return
+	}
+	kind := AuditAuthnFailure
+	if errors.Is(err, ErrJWKSStale) {
+		kind = AuditJWKSUnavailable
+	}
+	audit.Log(ctx, AuditEvent{Kind: kind, Timestamp: time.Now().UTC()})
+}
+
+// bearerToken's scheme match is case-insensitive ("Bearer", "bearer",
+// "BEARER" all accepted) per RFC 7235 §2.1, which defines the
+// auth-scheme token as case-insensitive — a prior case-sensitive match
+// would 401 a structurally valid request from any client that happened
+// to send a lowercase scheme (Oren Castellan, PR #30 review).
 func bearerToken(r *http.Request) (string, bool) {
 	h := r.Header.Get("Authorization")
-	const prefix = "Bearer "
-	if !strings.HasPrefix(h, prefix) {
+	const prefixLen = len("Bearer ")
+	if len(h) <= prefixLen || !strings.EqualFold(h[:prefixLen], "Bearer ") {
 		return "", false
 	}
-	tok := strings.TrimSpace(strings.TrimPrefix(h, prefix))
+	tok := strings.TrimSpace(h[prefixLen:])
 	if tok == "" {
 		return "", false
 	}
diff --git a/internal/api/jwtmiddleware_test.go b/internal/api/jwtmiddleware_test.go
index 116049f..8649224 100644
--- a/internal/api/jwtmiddleware_test.go
+++ b/internal/api/jwtmiddleware_test.go
@@ -1,6 +1,7 @@
 package api
 
 import (
+	"context"
 	"crypto/rand"
 	"crypto/rsa"
 	"crypto/x509"
@@ -24,7 +25,7 @@ type fakeKeySource struct {
 	keys map[string]*rsa.PublicKey
 }
 
-func (f *fakeKeySource) KeyForKid(kid string) (*rsa.PublicKey, error) {
+func (f *fakeKeySource) KeyForKid(_ context.Context, kid string) (*rsa.PublicKey, error) {
 	k, ok := f.keys[kid]
 	if !ok {
 		return nil, errNoKey
@@ -98,7 +99,7 @@ func defaultOpts(kid string) tokenOpts {
 }
 
 func newTestMiddleware(keys map[string]*rsa.PublicKey) func(http.Handler) http.Handler {
-	return NewJWTMiddleware(&fakeKeySource{keys: keys}, testIssuer, testAudience)
+	return NewJWTMiddleware(&fakeKeySource{keys: keys}, testIssuer, testAudience, &fakeAuditLogger{})
 }
 
 func okHandler(gotCtx *AuthContext) http.Handler {
diff --git a/internal/api/stopgap_authorizer_test.go b/internal/api/stopgap_authorizer_test.go

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/03181f6 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | awk '/^diff --git a\\/internal\\/api\\/stopgap_authorizer_test.go/,/^diff --git a\\/internal\\/app\\/verifier_router.go/'"
}

diff --git a/internal/api/stopgap_authorizer_test.go b/internal/api/stopgap_authorizer_test.go
new file mode 100644
index 0000000..b6569c3
--- /dev/null
+++ b/internal/api/stopgap_authorizer_test.go
@@ -0,0 +1,70 @@
+package api
+
+import (
+	"context"
+	"testing"
+)
+
+// TestStopgapAuthorizer_ReadOwn_AllowedAndDenied is Marcus Ilori's (02)
+// ruling on the review finding that this stand-in's deny path had no
+// test coverage: exercise both the allow and deny outcomes for
+// ScopeReadOwn, the only scope this stopgap actually gates.
+func TestStopgapAuthorizer_ReadOwn_AllowedAndDenied(t *testing.T) {
+	a := &StopgapAuthorizer{
+		ReadOwnAllow: map[string]map[string]bool{
+			"qa-client": {"profile-1": true},
+		},
+	}
+	ctx := context.Background()
+
+	allowed, err := a.Authorize(ctx, "qa-client", ScopeReadOwn, "profile-1")
+	if err != nil {
+		t.Fatalf("Authorize: %v", err)
+	}
+	if !allowed {
+		t.Error("qa-client reading its seeded profile-1 should be allowed")
+	}
+
+	denied, err := a.Authorize(ctx, "qa-client", ScopeReadOwn, "profile-2")
+	if err != nil {
+		t.Fatalf("Authorize: %v", err)
+	}
+	if denied {
+		t.Error("qa-client reading a profile it was not seeded with should be denied")
+	}
+
+	deniedSub, err := a.Authorize(ctx, "some-other-client", ScopeReadOwn, "profile-1")
+	if err != nil {
+		t.Fatalf("Authorize: %v", err)
+	}
+	if deniedSub {
+		t.Error("a sub with no seeded entry at all should be denied, the safe default")
+	}
+}
+
+// TestStopgapAuthorizer_EmptyMapDeniesEverything is the safe-default
+// requirement itself: a StopgapAuthorizer constructed with no seed data
+// (the out-of-the-box state before LT-51 seeds a QA client credential)
+// must deny every ScopeReadOwn request, never fail open.
+func TestStopgapAuthorizer_EmptyMapDeniesEverything(t *testing.T) {
+	a := &StopgapAuthorizer{}
+	allowed, err := a.Authorize(context.Background(), "anyone", ScopeReadOwn, "anything")
+	if err != nil {
+		t.Fatalf("Authorize: %v", err)
+	}
+	if allowed {
+		t.Error("an unseeded StopgapAuthorizer must deny every read:own request, not fail open")
+	}
+}
+
+func TestStopgapAuthorizer_ReadAnyAndSearch_AlwaysAllowed(t *testing.T) {
+	a := &StopgapAuthorizer{}
+	ctx := context.Background()
+
+	if allowed, _ := a.Authorize(ctx, "anyone", ScopeReadAny, "anything"); !allowed {
+		t.Error("read:any has no per-record referral concept this stopgap gates — should not be denied here")
+	}
+	if allowed, _ := a.Authorize(ctx, "anyone", ScopeSearch, ""); !allowed {
+		t.Error("search has no per-record target this stopgap gates — should not be denied here")
+	}
+}
diff --git a/internal/app/verifier_router.go b/internal/app/verifier_router.go

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/03181f6 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | awk '/^diff --git a\\/internal\\/app\\/verifier_router_test.go/,0'"
}

diff --git a/internal/app/verifier_router_test.go b/internal/app/verifier_router_test.go
index 1f0b6f8..03be748 100644
--- a/internal/app/verifier_router_test.go
+++ b/internal/app/verifier_router_test.go
@@ -160,3 +160,92 @@ func TestNewVerifierRouter_HealthzUnaffectedByAuth(t *testing.T) {
 		t.Errorf("status = %d, want 200 — /healthz must stay unauthenticated per handoff-03-auth.md", w.Code)
 	}
 }
+
+// TestNewVerifierRouter_ReadOwn_AllowedAndDenied is Marcus Ilori's (02)
+// ruling: the router-level test that was missing entirely for
+// GET /profiles/{id} under read:own — both the allow and deny paths
+// through the real StopgapAuthorizer, wired the way cmd/api-service
+// actually wires it (via cfg.AuthzQASub/AuthzQAAllowedProfileID).
+func TestNewVerifierRouter_ReadOwn_AllowedAndDenied(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	jwks := startFakeJWKS(t, "key-1", &key.PublicKey)
+	defer jwks.Close()
+
+	cfg := config.Config{
+		AuthJWTIssuer:           testIssuer,
+		AuthJWTAudience:         testAudience,
+		AuthJWKSURL:             jwks.URL,
+		AuthzQASub:              "client-under-test", // matches signTestToken's hardcoded sub
+		AuthzQAAllowedProfileID: "allowed-profile",
+	}
+	router := NewVerifierRouter(cfg, &fakeRepo{})
+	tok := signTestToken(t, key, "key-1", "profile:read:own")
+
+	allowedReq := httptest.NewRequest(http.MethodGet, "/profiles/allowed-profile", nil)
+	allowedReq.Header.Set("Authorization", "Bearer "+tok)
+	wAllowed := httptest.NewRecorder()
+	router.ServeHTTP(wAllowed, allowedReq)
+	if wAllowed.Code != http.StatusOK {
+		t.Errorf("allowed profile: status = %d, want 200, body=%s", wAllowed.Code, wAllowed.Body.String())
+	}
+
+	deniedReq := httptest.NewRequest(http.MethodGet, "/profiles/some-other-profile", nil)
+	deniedReq.Header.Set("Authorization", "Bearer "+tok)
+	wDenied := httptest.NewRecorder()
+	router.ServeHTTP(wDenied, deniedReq)
+	if wDenied.Code != http.StatusForbidden {
+		t.Errorf("unseeded profile: status = %d, want 403 (StopgapAuthorizer's safe-default deny), body=%s", wDenied.Code, wDenied.Body.String())
+	}
+}
+
+// TestNewVerifierRouter_NilRepo_ProtectedRoutesFailClosed503 is the PM's
+// direct question: on a cluster where the database doesn't exist yet (no
+// DB_DRIVER/DB_DSN configured), the verifying Deployment must still come
+// up with /healthz green — cmd/api-service/main.go passes repo=nil
+// rather than crash-looping — and the two protected routes must fail
+// closed (503), not panic on a nil Repository. Auth still runs first: an
+// unauthenticated request still gets 401, proven by the companion
+// TestNewVerifierRouter_UnauthenticatedRequest_401-shaped assertion
+// inline below.
+func TestNewVerifierRouter_NilRepo_ProtectedRoutesFailClosed503(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generating key: %v", err)
+	}
+	jwks := startFakeJWKS(t, "key-1", &key.PublicKey)
+	defer jwks.Close()
+
+	cfg := config.Config{AuthJWTIssuer: testIssuer, AuthJWTAudience: testAudience, AuthJWKSURL: jwks.URL}
+	router := NewVerifierRouter(cfg, nil) // no DAO repository — the no-database-yet case
+	tok := signTestToken(t, key, "key-1", "profile:search")
+
+	// /healthz must still be green.
+	healthReq := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	wHealth := httptest.NewRecorder()
+	router.ServeHTTP(wHealth, healthReq)
+	if wHealth.Code != http.StatusOK {
+		t.Errorf("/healthz status = %d, want 200 even with no DAO repository", wHealth.Code)
+	}
+
+	// An authenticated request to a protected route must fail closed
+	// (503), not panic.
+	authedReq := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
+	authedReq.Header.Set("Authorization", "Bearer "+tok)
+	wAuthed := httptest.NewRecorder()
+	router.ServeHTTP(wAuthed, authedReq)
+	if wAuthed.Code != http.StatusServiceUnavailable {
+		t.Errorf("authenticated request with no repository: status = %d, want 503", wAuthed.Code)
+	}
+
+	// An UNauthenticated request must still get 401, not 503 — auth
+	// still runs before the repository is ever consulted.
+	unauthedReq := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
+	wUnauthed := httptest.NewRecorder()
+	router.ServeHTTP(wUnauthed, unauthedReq)
+	if wUnauthed.Code != http.StatusUnauthorized {
+		t.Errorf("unauthenticated request with no repository: status = %d, want 401 (auth must still run first)", wUnauthed.Code)
+	}
+}

{
  "command": "cat > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-recheck.md << 'EOF'\nIndependent review: Tomasz Wrede (02 Adversary) — PR #30 re-check at `03181f6`\n\nRe-read the diff at `03181f6` against my three findings. Two close clean, one closes *most* of the way but opens a new, smaller hole that's worth naming before this ships.\n\n**Finding 1 (JWKS fail-open, no staleness bound) — CLOSED. No notes.**\n`maxStaleness = 3 * ttl`, `refresh()` fails closed with `ErrJWKSStale` once exceeded, distinct `AuditJWKSUnavailable` event plus a log line for 04's alerting, and `TestJWKSCache_FailsClosedPastMaxStaleness` actually drives the clock past the bound and confirms the error wraps `ErrJWKSStale`. This is the real fix, not a weaker stand-in.\n\n**Finding 3 (`StopgapAuthorizer` deny path untested) — CLOSED. No notes.**\n`stopgap_authorizer_test.go` covers allow, deny-by-record, deny-by-unknown-sub, and the empty-map safe-default; `TestNewVerifierRouter_ReadOwn_AllowedAndDenied` drives it through the real router with the real config wiring, both 200 and 403. Bonus: `TestNewVerifierRouter_NilRepo_ProtectedRoutesFailClosed503` wasn't something I asked for, but it's a good adjacent catch — auth still runs before the nil-repo 503, so an unauthenticated caller can't use a missing DB as an oracle either.\n\n**Finding 2 (unknown-`kid` refetch) — mostly closed, but the rate limit reopens a smaller version of the same window, and this one's on the fix itself, not the original code.**\n`reserveUnknownKidRetry` is a single shared gate (`lastUnknownKidRetry` is one field on the cache, not partitioned per `kid`). That means the 30s rate limit is consumed by *any* unknown-kid lookup, not specifically by the legitimate one. An unauthenticated caller can send a bearer token with a syntactically valid JWT and a garbage `kid` — no valid signature required to reach the keyfunc, since `KeyForKid` is called before signature verification — and that alone claims the rate-limit slot. Timed to repeat roughly every 30s (trivial, unauthenticated, costs nothing), an attacker can keep the slot permanently occupied by noise, so the *actual* freshly-rotated key's first legitimate lookup arrives during an already-consumed window, gets no refetch, and falls back to waiting for the next calendar TTL rollover — which is most of finding #2's original ~15-minute gap, just requiring an attacker to bother.\n\nTo be fair to the fix: this is strictly better than before (an attacker has to actively maintain the interference; a quiet rotation with no attacker present now recovers in ≤30s instead of ≤15min), and rate-limiting *something* here is correct — the alternative of refetching on every unknown kid reopens the exact hammering concern the limit exists for. The gap is specifically that the gate isn't scoped to \"this kid, once\" — it's scoped to \"any kid, globally.\" A fix in the direction of a small per-kid dedup (e.g., only reserve/consume the slot for a kid not already attempted in the current window, or key the rate limit by kid with a short per-kid TTL rather than one global timestamp) would close this without reopening the flood risk. Not blocking on its own given the bound is now 30s instead of unbounded-until-TTL, but I'd want it named as an accepted residual explicitly if it's not going to be fixed now, rather than left implicit.\n\nNet: 1 and 3 are genuinely done. 2 is real progress with a residual gap in the mechanism it added, not a failure to attempt the fix.\nEOF\ngh pr comment 30 --repo wtvamp/loginid-takehome --body-file /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-recheck.md"
}

https://github.com/wtvamp/loginid-takehome/pull/30#issuecomment-5653074168

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/a615dfa -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | awk '/^diff --git a\\/internal\\/api\\/jwks.go/,/^diff --git a\\/internal\\/api\\/jwks_test.go/'"
}

diff --git a/internal/api/jwks.go b/internal/api/jwks.go
index 238c4e5..edee962 100644
--- a/internal/api/jwks.go
+++ b/internal/api/jwks.go
@@ -118,6 +118,28 @@ var ErrJWKSStale = errors.New("api: JWKS cache exceeded max staleness and could
 const (
 	jwksMaxStalenessMultiple      = 3
 	jwksUnknownKidRefetchInterval = 30 * time.Second
+
+	// jwksMinRefreshRetryInterval floors how often a TTL-expired cache
+	// with a just-failed refresh will attempt another real network
+	// fetch. Without this, every single request during a sustained
+	// issuer outage triggers its own fetch attempt for as long as the
+	// outage lasts (up to maxStaleness) — the same "don't hammer a
+	// struggling dependency" reasoning already applied to the
+	// unknown-kid path, missing from the ordinary refresh path (Oren
+	// Castellan, PR #30 re-review). Short relative to ttl/maxStaleness:
+	// this only throttles retries during an active failure, it must not
+	// delay picking up a healthy issuer again once it recovers.
+	jwksMinRefreshRetryInterval = 5 * time.Second
+
+	// jwksMaxTrackedUnknownKids bounds how many distinct kids can hold an
+	// outstanding unknown-kid retry reservation at once. Without this,
+	// keying the reservation per-kid (see reserveUnknownKidRetry) reopens
+	// its own version of the same map-growth concern a flood of DISTINCT
+	// garbage kids would create: capped here, so an attacker sending many
+	// different fabricated kids can force at most this many extra
+	// fetches per jwksUnknownKidRefetchInterval, not one per distinct
+	// value they bother to send.
+	jwksMaxTrackedUnknownKids = 64
 )
 
 // JWKSCache fetches a JWKS document from url and caches the parsed key
@@ -137,9 +159,10 @@ type JWKSCache struct {
 	mu                  sync.Mutex
 	keys                map[string]*rsa.PublicKey
 	fetchedAt           time.Time // last SUCCESSFUL fetch
+	lastAttempt         time.Time // last fetch ATTEMPT, success or failure
 	consecutiveFailures int
 	staleAlerted        bool
-	lastUnknownKidRetry time.Time
+	unknownKidRetryAt   map[string]time.Time // per-kid, not global — see reserveUnknownKidRetry
 }
 
 // defaultJWKSClientTimeout backstops a hung fetch (a connection that
@@ -184,10 +207,20 @@ func NewJWKSCache(url string, ttl time.Duration, httpClient *http.Client) *JWKSC
 func (c *JWKSCache) KeyForKid(ctx context.Context, kid string) (*rsa.PublicKey, error) {
 	c.mu.Lock()
 	needsRefresh := c.keys == nil || c.now().Sub(c.fetchedAt) >= c.ttl
+	canAttempt := c.now().Sub(c.lastAttempt) >= jwksMinRefreshRetryInterval
 	c.mu.Unlock()
 
 	if needsRefresh {
-		if err := c.refresh(ctx); err != nil {
+		if canAttempt {
+			if err := c.refresh(ctx); err != nil {
+				return nil, err
+			}
+		} else if err := c.enforceStaleness(); err != nil {
+			// Backing off from a very recent failed attempt (see
+			// jwksMinRefreshRetryInterval) — no new network call this
+			// time, but the staleness ceiling must still be enforced
+			// against the existing cache regardless of whether this
+			// particular call was the one that tried to refresh it.
 			return nil, err
 		}
 	}
@@ -204,7 +237,7 @@ func (c *JWKSCache) KeyForKid(ctx context.Context, kid string) (*rsa.PublicKey,
 	// the retry populated the kid we're actually looking for, and a
 	// refresh() failure here has already been handled (logged / staleness
 	// tracked) inside refresh() itself.
-	if c.reserveUnknownKidRetry() {
+	if c.reserveUnknownKidRetry(kid) {
 		_ = c.refresh(ctx)
 		if key, ok := c.lookupKey(kid); ok {
 			return key, nil
@@ -222,16 +255,47 @@ func (c *JWKSCache) lookupKey(kid string) (*rsa.PublicKey, bool) {
 }
 
 // reserveUnknownKidRetry reports whether an unknown-kid-triggered refetch
-// may proceed now, and if so atomically marks one as just having started
-// — a caller enumerating unknown kids can trigger at most one extra
-// fetch per jwksUnknownKidRefetchInterval, not one per request.
-func (c *JWKSCache) reserveUnknownKidRetry() bool {
+// may proceed now for THIS specific kid, and if so atomically marks one
+// as just having started. Keyed per kid, not by one global timestamp
+// (Ingrid Solano, 02 cold re-check): KeyForKid runs before signature
+// verification, so an unauthenticated caller can send a token with a
+// fabricated kid at no cost — a single global gate lets that caller
+// permanently occupy the one reservation slot by repeating it every
+// jwksUnknownKidRefetchInterval, pushing a legitimately-rotated real
+// key's own refetch back to the full calendar-TTL rollover, silently
+// recreating most of the original gap this mechanism exists to close.
+// Per-kid closes that: a garbage kid's repeated reservation never blocks
+// a DIFFERENT (real) kid's own reservation. jwksMaxTrackedUnknownKids
+// caps how many distinct kids can hold a reservation at once, so a flood
+// of distinct fabricated kids still can't hammer the issuer past that
+// bound — rate-limiting is scoped per-kid, not removed.
+func (c *JWKSCache) reserveUnknownKidRetry(kid string) bool {
 	c.mu.Lock()
 	defer c.mu.Unlock()
-	if c.now().Sub(c.lastUnknownKidRetry) < jwksUnknownKidRefetchInterval {
+
+	if c.unknownKidRetryAt == nil {
+		c.unknownKidRetryAt = make(map[string]time.Time)
+	}
+	if last, ok := c.unknownKidRetryAt[kid]; ok && c.now().Sub(last) < jwksUnknownKidRefetchInterval {
 		return false
 	}
-	c.lastUnknownKidRetry = c.now()
+
+	// Sweep expired entries before checking the size cap, so a kid
+	// that's aged out of its own window doesn't count against another
+	// kid's chance to reserve.
+	for k, t := range c.unknownKidRetryAt {
+		if c.now().Sub(t) >= jwksUnknownKidRefetchInterval {
+			delete(c.unknownKidRetryAt, k)
+		}
+	}
+	if len(c.unknownKidRetryAt) >= jwksMaxTrackedUnknownKids {
+		// At capacity with distinct in-flight-window kids — deny this
+		// one rather than let the map grow further. The ordinary
+		// TTL-driven refresh still eventually picks up a real rotated
+		// key regardless of this outcome.
+		return false
+	}
+	c.unknownKidRetryAt[kid] = c.now()
 	return true
 }
 
@@ -245,25 +309,44 @@ func (c *JWKSCache) reserveUnknownKidRetry() bool {
 // the stale cache is still good enough to use, per the resilience this
 // mechanism exists for.
 func (c *JWKSCache) refresh(ctx context.Context) error {
+	c.mu.Lock()
+	c.lastAttempt = c.now()
+	c.mu.Unlock()
+
 	fresh, err := c.fetch(ctx)
 
 	c.mu.Lock()
-	defer c.mu.Unlock()
-
 	if err == nil {
 		c.keys = fresh
 		c.fetchedAt = c.now()
 		c.consecutiveFailures = 0
 		c.staleAlerted = false
+		c.mu.Unlock()
 		return nil
 	}
-
 	c.consecutiveFailures++
+	noCache := c.keys == nil
+	c.mu.Unlock()
 
-	if c.keys == nil {
+	if noCache {
 		return err
 	}
+	return c.enforceStaleness()
+}
 
+// enforceStaleness checks the existing cache against maxStaleness and
+// fails closed (ErrJWKSStale) if it's been exceeded — factored out of
+// refresh() so the same check applies on a call that skips an actual
+// network attempt because jwksMinRefreshRetryInterval hasn't elapsed yet
+// (Oren Castellan, PR #30 re-review: without this, backing off from
+// hammering a struggling issuer would also silently suspend the
+// staleness ceiling for however long the backoff lasts).
+func (c *JWKSCache) enforceStaleness() error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.keys == nil {
+		return errors.New("api: JWKS cache not yet populated")
+	}
 	staleSince := c.now().Sub(c.fetchedAt)
 	if staleSince > c.maxStaleness {
 		if !c.staleAlerted {
@@ -272,10 +355,10 @@ func (c *JWKSCache) refresh(ctx context.Context) error {
 			// fetch-failure run — not a policy decision (AuditLogger is
 			// for those), an operational signal that this process's own
 			// key infrastructure is degraded.
-			log.Printf("api: JWKS unrefreshable for %s across %d consecutive failures (exceeds max staleness %s) — failing closed: %v",
-				staleSince, c.consecutiveFailures, c.maxStaleness, err)
+			log.Printf("api: JWKS unrefreshable for %s across %d consecutive failures (exceeds max staleness %s) — failing closed",
+				staleSince, c.consecutiveFailures, c.maxStaleness)
 		}
-		return fmt.Errorf("%w: stale for %s across %d consecutive failures: %v", ErrJWKSStale, staleSince, c.consecutiveFailures, err)
+		return fmt.Errorf("%w: stale for %s across %d consecutive failures", ErrJWKSStale, staleSince, c.consecutiveFailures)
 	}
 	return nil
 }
diff --git a/internal/api/jwks_test.go b/internal/api/jwks_test.go

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/a615dfa -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | awk '/^diff --git a\\/internal\\/api\\/jwks_test.go/,0' | grep -n \"PerKidNotGlobal\\|CapsDistinctKids\" -A 60 | head -140"
}

132:+// TestJWKSCache_UnknownKidReservationIsPerKidNotGlobal is Ingrid
133-+// Solano's (02) cold re-check finding: KeyForKid runs before signature
134-+// verification, so an unauthenticated caller can send a token with a
135-+// fabricated kid at no cost. A single GLOBAL reservation gate would let
136-+// that caller occupy the one slot by repeating a garbage kid every
137-+// jwksUnknownKidRefetchInterval, starving a DIFFERENT, legitimately
138-+// rotated-in real kid's own refetch back to the full calendar TTL —
139-+// silently recreating most of the original gap. Reserving per kid closes
140-+// this: a garbage kid's own reservation must not block a different real
141-+// kid's reservation in the same window.
142:+func TestJWKSCache_UnknownKidReservationIsPerKidNotGlobal(t *testing.T) {
143-+	oldKey, err := rsa.GenerateKey(rand.Reader, 2048)
144-+	if err != nil {
145-+		t.Fatalf("generating key: %v", err)
146-+	}
147-+	newKey, err := rsa.GenerateKey(rand.Reader, 2048)
148-+	if err != nil {
149-+		t.Fatalf("generating key: %v", err)
150-+	}
151-+
152-+	var serveNewKey atomic.Bool
153-+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
154-+		w.Header().Set("Content-Type", "application/json")
155-+		if serveNewKey.Load() {
156-+			_, _ = w.Write(jwksBody(t, "key-new", &newKey.PublicKey))
157-+		} else {
158-+			_, _ = w.Write(jwksBody(t, "key-old", &oldKey.PublicKey))
159-+		}
160-+	}))
161-+	defer srv.Close()
162-+
163-+	cache := NewJWKSCache(srv.URL, time.Hour, nil)
164-+	ctx := context.Background()
165-+
166-+	if _, err := cache.KeyForKid(ctx, "key-old"); err != nil {
167-+		t.Fatalf("priming: %v", err)
168-+	}
169-+
170-+	// Attacker occupies the reservation for a garbage kid.
171-+	_, _ = cache.KeyForKid(ctx, "garbage-kid-from-attacker")
172-+	// Repeats it immediately — this must be denied (rate-limited), same
173-+	// as before the fix.
174-+	_, _ = cache.KeyForKid(ctx, "garbage-kid-from-attacker")
175-+
176-+	// The issuer rotates for real. A legitimate lookup for the new kid,
177-+	// in the SAME window the attacker's garbage kid already consumed,
178-+	// must still get its own reservation and succeed — not be starved by
179-+	// the attacker's unrelated kid.
180-+	serveNewKey.Store(true)
181-+	if _, err := cache.KeyForKid(ctx, "key-new"); err != nil {
182-+		t.Errorf("KeyForKid(key-new) = %v, want the real rotated key's own reservation to succeed regardless of an attacker's unrelated garbage-kid reservation", err)
183-+	}
184-+}
185-+
186:+// TestJWKSCache_UnknownKidReservationCapsDistinctKids is the other half
187-+// of Ingrid's ruling: rate-limiting is scoped per kid, not removed — a
188-+// flood of distinct fabricated kids must still be bounded, not each get
189-+// their own unconditional extra fetch.
190:+func TestJWKSCache_UnknownKidReservationCapsDistinctKids(t *testing.T) {
191-+	key, err := rsa.GenerateKey(rand.Reader, 2048)
192-+	if err != nil {
193-+		t.Fatalf("generating key: %v", err)
194-+	}
195-+	var requests atomic.Int32
196-+	body := jwksBody(t, "key-1", &key.PublicKey)
197-+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
198-+		requests.Add(1)
199-+		w.Header().Set("Content-Type", "application/json")
200-+		_, _ = w.Write(body)
201-+	}))
202-+	defer srv.Close()
203-+
204-+	cache := NewJWKSCache(srv.URL, time.Hour, nil)
205-+	ctx := context.Background()
206-+	if _, err := cache.KeyForKid(ctx, "key-1"); err != nil {
207-+		t.Fatalf("priming: %v", err)
208-+	}
209-+	requestsAfterPriming := requests.Load()
210-+
211-+	// Flood with more distinct garbage kids than jwksMaxTrackedUnknownKids.
212-+	for i := 0; i < jwksMaxTrackedUnknownKids+20; i++ {
213-+		_, _ = cache.KeyForKid(ctx, fmt.Sprintf("garbage-kid-%d", i))
214-+	}
215-+
216-+	extraFetches := requests.Load() - requestsAfterPriming
217-+	if int(extraFetches) > jwksMaxTrackedUnknownKids {
218-+		t.Errorf("a flood of %d distinct garbage kids triggered %d extra fetches, want at most %d (the cap)", jwksMaxTrackedUnknownKids+20, extraFetches, jwksMaxTrackedUnknownKids)
219-+	}
220-+}

{
  "command": "cat > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-recheck2.md << 'EOF'\nIndependent review: Tomasz Wrede (02 Adversary) — PR #30 re-check at `a615dfa`\n\n**The griefing path I raised is closed. Per-kid keying does what it's supposed to.**\n`reserveUnknownKidRetry(kid)` now checks/sets `unknownKidRetryAt[kid]`, so an attacker occupying a garbage kid's own 30s window has no effect on a *different* kid's reservation — confirmed by `TestJWKSCache_UnknownKidReservationIsPerKidNotGlobal`, which reproduces exactly the scenario I described (attacker holds `garbage-kid-from-attacker` hot, real `key-new` still gets its reservation and succeeds in the same window). Good, targeted fix — no notes.\n\n**The 64-kid cap: answering your two questions directly.**\n\n1. *Can an attacker exhaust the cap with 64+ distinct garbage kids?* Yes, trivially — `KeyForKid` runs before signature verification, so a garbage kid costs an attacker nothing but a syntactically-valid JWT shell, and there's no request-volume throttle on this path pre-auth (the resource-API `RateLimiter` only applies to an already-authenticated `sub`). `TestJWKSCache_UnknownKidReservationCapsDistinctKids` confirms the cap holds (`jwksMaxTrackedUnknownKids+20` distinct kids trigger at most 64 extra fetches) — but that test only checks the issuer-side fetch count stays bounded, it doesn't check what happens to a *real* kid that shows up as the unlucky 65th while an attacker is actively keeping 64 slots full. That's the scenario worth naming.\n\n2. *What happens to the 65th kid — unrestricted refetch, or rejection?* Rejection, and that's the right direction. `reserveUnknownKidRetry` denies the reservation once `len(unknownKidRetryAt) >= jwksMaxTrackedUnknownKids` (after sweeping expired entries), `KeyForKid` then falls straight to `\"no key found for kid\"` with no fetch attempted — it does **not** fall through to an unrestricted/unconditional refetch. So the issuer itself stays protected regardless of how hard an attacker floods this: worst case is a real key's early lookup gets no out-of-band refetch and waits for the ordinary calendar-TTL rollover, not that the cap gets bypassed and the issuer gets hammered anyway. That was the important direction to get right, and it's right.\n\n**Net assessment: this is a real, substantial narrowing, not a full close — and I think that's the correct place to stop, not a gap to keep chasing.**\nBefore `03181f6`: any single unauthenticated request with a garbage kid could starve *every* real kid, indefinitely, for free. After `a615dfa`: an attacker needs to sustain **≥64 concurrently-live distinct garbage-kid reservations** to starve one additional real kid past the cap, and even then the failure mode is \"wait up to the full TTL,\" not \"issuer gets hammered\" or \"verification silently opens up.\" That's a meaningfully higher cost attack (sustained volume, not one request) for a bounded, fail-safe-direction outcome. I'd call the residual risk LOW now, versus HIGH originally — closing it further would mean either raising the cap (doesn't fix the shape, just the number) or adding per-source-IP/per-caller throttling ahead of this whole path (a real fix, but a bigger scope change than this story's — that's the resource-API's rate-limit story's territory, not this cache's). I'd take this as done for LT-40 and let the pre-auth request-volume question be a named follow-up if 04/03 want one, rather than block here.\nEOF\ngh pr comment 30 --repo wtvamp/loginid-takehome --body-file /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr30-recheck2.md"
}

https://github.com/wtvamp/loginid-takehome/pull/30#issuecomment-5653113670

{
  "command": "gh pr diff 40 --repo wtvamp/loginid-takehome 2>&1 | wc -l"
}

    1427

{
  "command": "gh pr diff 40 --repo wtvamp/loginid-takehome 2>&1 > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff\ngrep -n \"^diff --git\" /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff"
}

1:diff --git a/cmd/idp-connector/main.go b/cmd/idp-connector/main.go
69:diff --git a/internal/api/auth.go b/internal/api/auth.go
92:diff --git a/internal/api/jwtmiddleware.go b/internal/api/jwtmiddleware.go
105:diff --git a/internal/app/connector_router.go b/internal/app/connector_router.go
180:diff --git a/internal/app/connector_router_test.go b/internal/app/connector_router_test.go
366:diff --git a/internal/connector/handlers.go b/internal/connector/handlers.go
635:diff --git a/internal/connector/handlers_test.go b/internal/connector/handlers_test.go
881:diff --git a/internal/connector/httpvendorclient.go b/internal/connector/httpvendorclient.go
1066:diff --git a/internal/connector/httpvendorclient_test.go b/internal/connector/httpvendorclient_test.go
1194:diff --git a/internal/connector/stubvendorclient.go b/internal/connector/stubvendorclient.go
1295:diff --git a/internal/connector/stubvendorclient_test.go b/internal/connector/stubvendorclient_test.go
1368:diff --git a/internal/connector/vendorclient.go b/internal/connector/vendorclient.go

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff",
  "offset": 881,
  "limit": 190
}

881	diff --git a/internal/connector/httpvendorclient.go b/internal/connector/httpvendorclient.go
882	new file mode 100644
883	index 0000000..f5601d6
884	--- /dev/null
885	+++ b/internal/connector/httpvendorclient.go
886	@@ -0,0 +1,179 @@
887	+package connector
888	+
889	+import (
890	+	"bytes"
891	+	"context"
892	+	"encoding/json"
893	+	"fmt"
894	+	"io"
895	+	"net/http"
896	+	"net/url"
897	+	"time"
898	+)
899	+
900	+// vendorCallTimeout bounds every outbound vendor call — belt-and-braces
901	+// alongside the caller's own context.WithTimeout, the same
902	+// defense-in-depth pattern LT-40's JWKS fetch client uses (an explicit
903	+// http.Client.Timeout independent of context, since a context deadline
904	+// bug elsewhere must not leave this client waiting forever).
905	+const vendorCallTimeout = 10 * time.Second
906	+
907	+// defaultVendorHTTPClient is a bounded-pool client — connector-security.md's
908	+// "bounded connection pool" requirement. Deliberately module-level so
909	+// every HTTPVendorClient constructed without an explicit client shares
910	+// one bounded pool rather than each accidentally getting Go's unbounded
911	+// http.DefaultTransport.
912	+var defaultVendorHTTPClient = &http.Client{
913	+	Timeout: vendorCallTimeout,
914	+	Transport: &http.Transport{
915	+		MaxIdleConns:        20,
916	+		MaxIdleConnsPerHost: 5,
917	+		MaxConnsPerHost:     10,
918	+		IdleConnTimeout:     30 * time.Second,
919	+	},
920	+}
921	+
922	+// HTTPVendorClient calls a real (or real-shaped) vendor over HTTPS,
923	+// demonstrating connector-security.md's outbound discipline: TLS only,
924	+// a bounded connection pool, and a fresh, isolated Authorization header
925	+// built inside each call rather than held as client-level state —
926	+// httpClient's connection pooling can reuse a TCP connection across
927	+// calls, but never a header, since baseURL/httpClient are the only
928	+// fields this type holds; the token is a per-call parameter, never
929	+// stored.
930	+//
931	+// No real ABC/XYZ vendor exists for this take-home (LT-41's own
932	+// non-goal) — this implementation assumes a vendor that happens to
933	+// share this project's own JSON request/response shape, a stated
934	+// simplifying assumption for demonstrating the connector's own outbound
935	+// security properties, not a claim about any real vendor's actual API.
936	+type HTTPVendorClient struct {
937	+	baseURL    string
938	+	httpClient *http.Client
939	+}
940	+
941	+// NewHTTPVendorClient requires an https:// baseURL — connector-security.md
942	+// §2: "Vendor calls over TLS only ... including in local/dev
943	+// environments." httpClient defaults to defaultVendorHTTPClient (bounded
944	+// pool + timeout) if nil.
945	+func NewHTTPVendorClient(baseURL string, httpClient *http.Client) (*HTTPVendorClient, error) {
946	+	u, err := url.Parse(baseURL)
947	+	if err != nil {
948	+		return nil, fmt.Errorf("connector: parsing vendor base URL: %w", err)
949	+	}
950	+	if u.Scheme != "https" {
951	+		return nil, fmt.Errorf("connector: vendor base URL %q must use https, per connector-security.md's TLS-only requirement", baseURL)
952	+	}
953	+	if httpClient == nil {
954	+		httpClient = defaultVendorHTTPClient
955	+	}
956	+	return &HTTPVendorClient{baseURL: baseURL, httpClient: httpClient}, nil
957	+}
958	+
959	+type vendorAuthRequest struct {
960	+	Username string `json:"username"`
961	+	Password string `json:"password"`
962	+}
963	+
964	+type vendorAuthResponse struct {
965	+	AccessToken string `json:"access_token"`
966	+}
967	+
968	+func (c *HTTPVendorClient) Authenticate(ctx context.Context, username, password string) (string, error) {
969	+	reqBody, err := json.Marshal(vendorAuthRequest{Username: username, Password: password})
970	+	if err != nil {
971	+		return "", fmt.Errorf("connector: encoding vendor auth request: %w", err)
972	+	}
973	+
974	+	// A fresh *http.Request built from scratch on every call — no
975	+	// client-level default header exists to leak across calls, and this
976	+	// request object is never retained past this function returning.
977	+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+"/auth", bytes.NewReader(reqBody))
978	+	if err != nil {
979	+		return "", fmt.Errorf("connector: building vendor auth request: %w", err)
980	+	}
981	+	req.Header.Set("Content-Type", "application/json")
982	+
983	+	resp, err := c.httpClient.Do(req)
984	+	if err != nil {
985	+		// Never wrap or surface the raw error to our own caller —
986	+		// connector-security.md §4: vendor errors must not distinguish
987	+		// which part of the credential was wrong, and a raw dial/DNS
988	+		// error can itself carry sensitive detail (host, IP). The
989	+		// caller-facing generic failure is this package's caller's job
990	+		// (internal/connector's handlers); this method's contract is
991	+		// simply "success or ErrVendorAuthFailed", nothing richer.
992	+		return "", ErrVendorAuthFailed
993	+	}
994	+	defer func() { _, _ = io.Copy(io.Discard, resp.Body); _ = resp.Body.Close() }()
995	+
996	+	if resp.StatusCode != http.StatusOK {
997	+		// Do not read/log the response body — connector-security.md §3:
998	+		// "do not log raw vendor response bodies by default, since a
999	+		// vendor error payload can itself echo back submitted PII or
1000	+		// partial credentials."
1001	+		return "", ErrVendorAuthFailed
1002	+	}
1003	+
1004	+	var body vendorAuthResponse
1005	+	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&body); err != nil || body.AccessToken == "" {
1006	+		return "", ErrVendorAuthFailed
1007	+	}
1008	+	return body.AccessToken, nil
1009	+}
1010	+
1011	+type vendorIdentityRequest struct {
1012	+	Phone string `json:"phone"`
1013	+	Name  string `json:"name"`
1014	+}
1015	+
1016	+type vendorIdentityResponse struct {
1017	+	Name          string `json:"name"`
1018	+	Phone         string `json:"phone"`
1019	+	StreetAddress string `json:"street_address"`
1020	+	Locality      string `json:"locality"`
1021	+	Region        string `json:"region"`
1022	+	PostalCode    string `json:"postal_code"`
1023	+	Country       string `json:"country"`
1024	+}
1025	+
1026	+func (c *HTTPVendorClient) FetchIdentity(ctx context.Context, accessToken, phone, name string) (Identity, error) {
1027	+	reqBody, err := json.Marshal(vendorIdentityRequest{Phone: phone, Name: name})
1028	+	if err != nil {
1029	+		return Identity{}, fmt.Errorf("connector: encoding vendor identity request: %w", err)
1030	+	}
1031	+
1032	+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+"/identity", bytes.NewReader(reqBody))
1033	+	if err != nil {
1034	+		return Identity{}, fmt.Errorf("connector: building vendor identity request: %w", err)
1035	+	}
1036	+	req.Header.Set("Content-Type", "application/json")
1037	+	// The one place accessToken is used — set on this request only,
1038	+	// never on a client-level default header, never retained after this
1039	+	// function returns.
1040	+	req.Header.Set("Authorization", "Bearer "+accessToken)
1041	+
1042	+	resp, err := c.httpClient.Do(req)
1043	+	if err != nil {
1044	+		return Identity{}, ErrVendorIdentityNotFound
1045	+	}
1046	+	defer func() { _, _ = io.Copy(io.Discard, resp.Body); _ = resp.Body.Close() }()
1047	+
1048	+	if resp.StatusCode != http.StatusOK {
1049	+		return Identity{}, ErrVendorIdentityNotFound
1050	+	}
1051	+
1052	+	var body vendorIdentityResponse
1053	+	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&body); err != nil {
1054	+		return Identity{}, ErrVendorIdentityNotFound
1055	+	}
1056	+	return Identity{
1057	+		Name:          body.Name,
1058	+		Phone:         body.Phone,
1059	+		StreetAddress: body.StreetAddress,
1060	+		Locality:      body.Locality,
1061	+		Region:        body.Region,
1062	+		PostalCode:    body.PostalCode,
1063	+		Country:       body.Country,
1064	+	}, nil
1065	+}
1066	diff --git a/internal/connector/httpvendorclient_test.go b/internal/connector/httpvendorclient_test.go
1067	new file mode 100644
1068	index 0000000..a0183a3
1069	--- /dev/null
1070	+++ b/internal/connector/httpvendorclient_test.go

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff",
  "offset": 1066,
  "limit": 130
}

1066	diff --git a/internal/connector/httpvendorclient_test.go b/internal/connector/httpvendorclient_test.go
1067	new file mode 100644
1068	index 0000000..a0183a3
1069	--- /dev/null
1070	+++ b/internal/connector/httpvendorclient_test.go
1071	@@ -0,0 +1,122 @@
1072	+package connector
1073	+
1074	+import (
1075	+	"context"
1076	+	"encoding/json"
1077	+	"net/http"
1078	+	"net/http/httptest"
1079	+	"sync"
1080	+	"testing"
1081	+	"time"
1082	+)
1083	+
1084	+func TestNewHTTPVendorClient_RejectsNonHTTPS(t *testing.T) {
1085	+	if _, err := NewHTTPVendorClient("http://vendor.example.com", nil); err == nil {
1086	+		t.Errorf("NewHTTPVendorClient accepted a plain http:// base URL, want an error (connector-security.md §2: TLS only)")
1087	+	}
1088	+	if _, err := NewHTTPVendorClient("not-a-url", nil); err == nil {
1089	+		t.Errorf("NewHTTPVendorClient accepted a garbage base URL, want an error")
1090	+	}
1091	+}
1092	+
1093	+// TestHTTPVendorClient_FetchIdentity_FreshAuthorizationHeaderPerRequest
1094	+// is attack-tree leaf 1's own named enforcement site (refinement/LT-41.md):
1095	+// two sequential calls through the SAME pooled *http.Client, each
1096	+// presenting a DIFFERENT vendor token, must each produce an outbound
1097	+// Authorization header matching ITS OWN token — never the previous
1098	+// call's, which a client that held a shared/default header (instead of
1099	+// building it fresh per call) could otherwise leak across requests via
1100	+// connection reuse.
1101	+func TestHTTPVendorClient_FetchIdentity_FreshAuthorizationHeaderPerRequest(t *testing.T) {
1102	+	var mu sync.Mutex
1103	+	var observedHeaders []string
1104	+
1105	+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
1106	+		mu.Lock()
1107	+		observedHeaders = append(observedHeaders, r.Header.Get("Authorization"))
1108	+		mu.Unlock()
1109	+		w.Header().Set("Content-Type", "application/json")
1110	+		_ = json.NewEncoder(w).Encode(vendorIdentityResponse{Name: "ok"})
1111	+	}))
1112	+	defer srv.Close()
1113	+
1114	+	// Construct directly (bypassing NewHTTPVendorClient's https-only
1115	+	// check, which httptest.Server's plain-http URL would otherwise
1116	+	// fail) — this file is in the same package, so it can set the
1117	+	// unexported fields directly rather than needing a second,
1118	+	// test-only constructor in non-test code.
1119	+	client := &HTTPVendorClient{baseURL: srv.URL, httpClient: srv.Client()}
1120	+
1121	+	if _, err := client.FetchIdentity(context.Background(), "token-A", "+15555550100", "Jane"); err != nil {
1122	+		t.Fatalf("first FetchIdentity call: %v", err)
1123	+	}
1124	+	if _, err := client.FetchIdentity(context.Background(), "token-B", "+15555550100", "Jane"); err != nil {
1125	+		t.Fatalf("second FetchIdentity call: %v", err)
1126	+	}
1127	+
1128	+	if len(observedHeaders) != 2 {
1129	+		t.Fatalf("server observed %d requests, want 2", len(observedHeaders))
1130	+	}
1131	+	if observedHeaders[0] != "Bearer token-A" {
1132	+		t.Errorf("first request's Authorization = %q, want %q", observedHeaders[0], "Bearer token-A")
1133	+	}
1134	+	if observedHeaders[1] != "Bearer token-B" {
1135	+		t.Errorf("second request's Authorization = %q, want %q — must not inherit the first call's token via connection reuse", observedHeaders[1], "Bearer token-B")
1136	+	}
1137	+}
1138	+
1139	+func TestHTTPVendorClient_Authenticate_SendsCredentialsAndReturnsToken(t *testing.T) {
1140	+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
1141	+		var body vendorAuthRequest
1142	+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
1143	+			t.Errorf("server: decoding request: %v", err)
1144	+		}
1145	+		if body.Username != "u" || body.Password != "p" {
1146	+			w.WriteHeader(http.StatusUnauthorized)
1147	+			return
1148	+		}
1149	+		w.Header().Set("Content-Type", "application/json")
1150	+		_ = json.NewEncoder(w).Encode(vendorAuthResponse{AccessToken: "minted-token"})
1151	+	}))
1152	+	defer srv.Close()
1153	+
1154	+	client := &HTTPVendorClient{baseURL: srv.URL, httpClient: srv.Client()}
1155	+	token, err := client.Authenticate(context.Background(), "u", "p")
1156	+	if err != nil {
1157	+		t.Fatalf("Authenticate: %v", err)
1158	+	}
1159	+	if token != "minted-token" {
1160	+		t.Errorf("token = %q, want minted-token", token)
1161	+	}
1162	+}
1163	+
1164	+func TestHTTPVendorClient_Authenticate_VendorRejects_GenericError(t *testing.T) {
1165	+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
1166	+		w.WriteHeader(http.StatusUnauthorized)
1167	+		_, _ = w.Write([]byte(`{"error":"invalid_grant","hint":"password field was 'hunter2'"}`))
1168	+	}))
1169	+	defer srv.Close()
1170	+
1171	+	client := &HTTPVendorClient{baseURL: srv.URL, httpClient: srv.Client()}
1172	+	_, err := client.Authenticate(context.Background(), "u", "wrong")
1173	+	if err != ErrVendorAuthFailed {
1174	+		t.Errorf("err = %v, want ErrVendorAuthFailed — the raw vendor response body must never surface (connector-security.md §3)", err)
1175	+	}
1176	+}
1177	+
1178	+func TestHTTPVendorClient_RespectsContextTimeout(t *testing.T) {
1179	+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
1180	+		time.Sleep(200 * time.Millisecond)
1181	+		w.WriteHeader(http.StatusOK)
1182	+	}))
1183	+	defer srv.Close()
1184	+
1185	+	client := &HTTPVendorClient{baseURL: srv.URL, httpClient: srv.Client()}
1186	+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
1187	+	defer cancel()
1188	+
1189	+	_, err := client.Authenticate(ctx, "u", "p")
1190	+	if err == nil {
1191	+		t.Fatalf("Authenticate did not return an error despite a 20ms context timeout against a 200ms-slow server")
1192	+	}
1193	+}
1194	diff --git a/internal/connector/stubvendorclient.go b/internal/connector/stubvendorclient.go
1195	new file mode 100644

{
  "command": "grep -n \"Header\\|sync\\.\\|var .*=.*http\\.\" /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff | grep -v \"^[0-9]*:+//\" "
}

217:+	tok.Header["kid"] = kid
283:+	req.Header.Set("Authorization", "Bearer "+wrongAudienceToken)
305:+	req.Header.Set("Authorization", "Bearer "+tok)
329:+	authReq.Header.Set("Authorization", "Bearer "+tok)
338:+	identityReq.Header.Set("Authorization", "Bearer "+tok)
339:+	identityReq.Header.Set("X-Vendor-Access-Token", extractAccessToken(t, authW.Body.String()))
436:+	w.Header().Set("Content-Type", "application/json")
437:+	w.WriteHeader(status)
548:+const vendorAccessTokenHeader = "X-Vendor-Access-Token"
584:+		token := strings.TrimSpace(r.Header.Get(vendorAccessTokenHeader))
759:+			req.Header.Set(vendorAccessTokenHeader, "some-token")
809:+	req.Header.Set(vendorAccessTokenHeader, "good-token")
912:+var defaultVendorHTTPClient = &http.Client{
981:+	req.Header.Set("Content-Type", "application/json")
1036:+	req.Header.Set("Content-Type", "application/json")
1040:+	req.Header.Set("Authorization", "Bearer "+accessToken)
1101:+func TestHTTPVendorClient_FetchIdentity_FreshAuthorizationHeaderPerRequest(t *testing.T) {
1102:+	var mu sync.Mutex
1103:+	var observedHeaders []string
1107:+		observedHeaders = append(observedHeaders, r.Header.Get("Authorization"))
1109:+		w.Header().Set("Content-Type", "application/json")
1128:+	if len(observedHeaders) != 2 {
1129:+		t.Fatalf("server observed %d requests, want 2", len(observedHeaders))
1131:+	if observedHeaders[0] != "Bearer token-A" {
1132:+		t.Errorf("first request's Authorization = %q, want %q", observedHeaders[0], "Bearer token-A")
1134:+	if observedHeaders[1] != "Bearer token-B" {
1135:+		t.Errorf("second request's Authorization = %q, want %q — must not inherit the first call's token via connection reuse", observedHeaders[1], "Bearer token-B")
1146:+			w.WriteHeader(http.StatusUnauthorized)
1149:+		w.Header().Set("Content-Type", "application/json")
1166:+		w.WriteHeader(http.StatusUnauthorized)
1181:+		w.WriteHeader(http.StatusOK)
1231:+	mu          sync.Mutex

{
  "command": "grep -n \"GrantLimiter\\|RateLimit\\|timingFloor\\|constantTime\\|100.*[Mm]illisecond\\|sleep\\|time\\.Sleep\" /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff"
}

130:+// NewIssuerRouter's own GrantLimiter constants — same reasoning
165:+	// leaf 5). Reuses api.GrantLimiter (PR #30/#34) rather than
167:+	limiter := api.NewInProcessGrantLimiter(
396:+const identityFailureFloor = 100 * time.Millisecond
407:+// directly by api.GrantLimiter (PR #30/#34's already-built component,
410:+// pattern already used for RateLimiter/TouchCounter/GrantLimiter").
450:+// waitForFloor sleeps out the remainder of identityFailureFloor since
458:+		time.Sleep(remaining)
684:+	limiter := api.NewInProcessGrantLimiter(time.Second, time.Minute, 5, nil)
708:+	limiter := api.NewInProcessGrantLimiter(time.Second, time.Minute, 5, nil)
745:+			time.Sleep(15 * time.Millisecond)
755:+		limiter := api.NewInProcessGrantLimiter(time.Second, time.Minute, 5, nil)
800:+	limiter := api.NewInProcessGrantLimiter(time.Second, time.Minute, 5, nil)
833:+// mostly successful calls ever would be. Reuses api.GrantLimiter (PR
836:+// matching the pattern already used for RateLimiter/TouchCounter/
837:+// GrantLimiter") — GrantLimiter's backoff is driven purely by
843:+	limiter := api.NewInProcessGrantLimiter(10*time.Millisecond, time.Hour, 100, nil)
1180:+		time.Sleep(200 * time.Millisecond)

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff",
  "offset": 105,
  "limit": 80
}

105	diff --git a/internal/app/connector_router.go b/internal/app/connector_router.go
106	new file mode 100644
107	index 0000000..be5fab2
108	--- /dev/null
109	+++ b/internal/app/connector_router.go
110	@@ -0,0 +1,69 @@
111	+package app
112	+
113	+import (
114	+	"log"
115	+	"net/http"
116	+	"time"
117	+
118	+	"loginid-takehome/internal/api"
119	+	"loginid-takehome/internal/config"
120	+	"loginid-takehome/internal/connector"
121	+)
122	+
123	+// connectorJWKSCacheTTL matches api-service's own verifier JWKS TTL
124	+// (internal/app/verifier_router.go) — both binaries verify tokens minted
125	+// by the same issuer, so there's no reason for a different refresh
126	+// cadence.
127	+const connectorJWKSCacheTTL = 15 * time.Minute
128	+
129	+// connectorVendorLimiterBaseBackoff/MaxBackoff/AlertThreshold mirror
130	+// NewIssuerRouter's own GrantLimiter constants — same reasoning
131	+// (handoff-03-auth.md names the mechanism, not specific numbers), reused
132	+// here for the vendor-call rate limiter per LT-41's attack-tree leaf 5
133	+// control rather than inventing a second set of magic numbers.
134	+const (
135	+	connectorVendorLimiterBaseBackoff    = 1 * time.Second
136	+	connectorVendorLimiterMaxBackoff     = 5 * time.Minute
137	+	connectorVendorLimiterAlertThreshold = 5
138	+)
139	+
140	+// NewConnectorRouter builds cmd/idp-connector's real router — LT-41's
141	+// /auth and /identity handlers behind the connector's own inbound JWT
142	+// verification (a distinct audience, connector-security.md §5: aud =
143	+// cfg.ConnectorJWTAudience, scope = connector:identity-lookup — NOT
144	+// api-service's audience, so a profile:*-scoped api-service token
145	+// cannot be replayed against this connector and vice versa).
146	+//
147	+// vendor is the outbound seam to the third-party IDP — either a real
148	+// (HTTPVendorClient) or stub (StubVendorClient) implementation;
149	+// cmd/idp-connector/main.go decides which based on whether
150	+// IDP_ABC_BASE_URL is configured.
151	+func NewConnectorRouter(cfg config.Config, keys api.KeySource, vendor connector.VendorClient) http.Handler {
152	+	mux := http.NewServeMux()
153	+	mux.HandleFunc("/healthz", healthHandler("idp-connector"))
154	+
155	+	auditLog := api.StdoutAuditLogger{}
156	+	authMiddleware := api.NewJWTMiddleware(keys, cfg.AuthJWTIssuer, cfg.ConnectorJWTAudience, auditLog)
157	+	protect := func(h http.Handler) http.Handler {
158	+		return api.NewDeadlineMiddleware(authMiddleware(h))
159	+	}
160	+
161	+	// One shared limiter instance across both handlers — a caller
162	+	// hammering /auth and a caller hammering /identity are the same
163	+	// abuse signal against the same vendor, keyed by the same
164	+	// (calling-API-client sub, source IP) pair (LT-41 attack-tree
165	+	// leaf 5). Reuses api.GrantLimiter (PR #30/#34) rather than
166	+	// building a new rate-limit type, per this story's own non-goals.
167	+	limiter := api.NewInProcessGrantLimiter(
168	+		connectorVendorLimiterBaseBackoff, connectorVendorLimiterMaxBackoff, connectorVendorLimiterAlertThreshold,
169	+		func(clientID string, consecutiveFailures int) {
170	+			log.Printf("idp-connector: ALERT sustained failed vendor calls from caller sub=%s (%d consecutive)", clientID, consecutiveFailures)
171	+		},
172	+	)
173	+
174	+	deps := connector.Deps{Vendor: vendor, Limiter: limiter, AuditLog: auditLog}
175	+	mux.Handle("POST /auth", protect(connector.NewAuthHandler(deps)))
176	+	mux.Handle("POST /identity", protect(connector.NewIdentityHandler(deps)))
177	+
178	+	return mux
179	+}
180	diff --git a/internal/app/connector_router_test.go b/internal/app/connector_router_test.go
181	new file mode 100644
182	index 0000000..9bab1cb
183	--- /dev/null
184	+++ b/internal/app/connector_router_test.go

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff",
  "offset": 366,
  "limit": 270
}

366	diff --git a/internal/connector/handlers.go b/internal/connector/handlers.go
367	new file mode 100644
368	index 0000000..e16f09b
369	--- /dev/null
370	+++ b/internal/connector/handlers.go
371	@@ -0,0 +1,263 @@
372	+package connector
373	+
374	+import (
375	+	"context"
376	+	"encoding/json"
377	+	"io"
378	+	"net"
379	+	"net/http"
380	+	"strings"
381	+	"time"
382	+
383	+	"loginid-takehome/internal/api"
384	+)
385	+
386	+// identityFailureFloor is /identity's uniform response-time floor across
387	+// its three failure branches (no-token, bad-token, vendor-rejected) —
388	+// Marcus Ilori's (02) ruling on Tobias Lindqvist's timing-oracle
389	+// objection (refinement/LT-41.md), recorded in full in
390	+// connector-security.md §4. ~100ms, well under any context.WithTimeout
391	+// budget elsewhere in the chain (vendorCallTimeout is 10s) so it never
392	+// competes with those deadlines. This narrows, but does not fully close,
393	+// the gap between a local-only failure (microseconds) and a
394	+// vendor-round-trip failure (tens-hundreds of ms) — full closure is an
395	+// accepted non-goal per that ruling.
396	+const identityFailureFloor = 100 * time.Millisecond
397	+
398	+// identityErrorBody is the one JSON shape every /identity failure
399	+// returns, regardless of which of the three branches produced it —
400	+// content-identical by construction (a single writeIdentityFailure call
401	+// site below), not by three call sites happening to independently agree.
402	+type identityErrorBody struct {
403	+	Error string `json:"error"`
404	+}
405	+
406	+// vendorLimiter is the interface these handlers depend on — satisfied
407	+// directly by api.GrantLimiter (PR #30/#34's already-built component,
408	+// reused here rather than rebuilt per LT-41's own non-goals: "this
409	+// story's own in-process rate limiting is sufficient, matching the
410	+// pattern already used for RateLimiter/TouchCounter/GrantLimiter").
411	+// Declared locally so this package's own tests can supply a minimal fake
412	+// satisfying only the calls actually made here, per
413	+// decisions/test-double-strategy.md.
414	+type vendorLimiter interface {
415	+	Allow(ctx context.Context, clientID, sourceIP string) (bool, error)
416	+	RecordFailure(ctx context.Context, clientID, sourceIP string)
417	+	RecordSuccess(ctx context.Context, clientID, sourceIP string)
418	+}
419	+
420	+// Deps bundles NewAuthHandler/NewIdentityHandler's collaborators.
421	+type Deps struct {
422	+	Vendor   VendorClient
423	+	Limiter  vendorLimiter
424	+	AuditLog api.AuditLogger
425	+}
426	+
427	+func sourceIPFrom(r *http.Request) string {
428	+	host, _, err := net.SplitHostPort(r.RemoteAddr)
429	+	if err != nil {
430	+		return r.RemoteAddr
431	+	}
432	+	return host
433	+}
434	+
435	+func writeJSON(w http.ResponseWriter, status int, v any) {
436	+	w.Header().Set("Content-Type", "application/json")
437	+	w.WriteHeader(status)
438	+	_ = json.NewEncoder(w).Encode(v)
439	+}
440	+
441	+// writeIdentityFailure is the single call site for every /identity
442	+// failure response — the one place that guarantees byte-identical
443	+// content across the no-token, bad-token, and vendor-rejected branches
444	+// (connector-security.md §1/F3), never three call sites independently
445	+// trying to agree.
446	+func writeIdentityFailure(w http.ResponseWriter) {
447	+	writeJSON(w, http.StatusUnauthorized, identityErrorBody{Error: "identity_lookup_failed"})
448	+}
449	+
450	+// waitForFloor sleeps out the remainder of identityFailureFloor since
451	+// start, if any — applied uniformly across /identity's three failure
452	+// branches so none of them is distinguishable from the others by
453	+// response latency alone (partial mitigation per connector-security.md
454	+// §4's own accepted-residual language; not applied to the success path,
455	+// which was never part of the timing-oracle concern).
456	+func waitForFloor(start time.Time) {
457	+	if remaining := identityFailureFloor - time.Since(start); remaining > 0 {
458	+		time.Sleep(remaining)
459	+	}
460	+}
461	+
462	+// authRequestBody is the assignment's own fixed POST /auth contract.
463	+type authRequestBody struct {
464	+	Username string `json:"username"`
465	+	Password string `json:"password"`
466	+}
467	+
468	+type authResponseBody struct {
469	+	AccessToken string `json:"access_token"`
470	+}
471	+
472	+// NewAuthHandler implements POST /auth. The caller (in this project's
473	+// shape, cmd/api-service acting on an onboarding flow's behalf) must
474	+// already be authenticated with a connector:identity-lookup-scoped,
475	+// idp-connector-service-audience token — enforced by whatever middleware
476	+// wraps this handler (internal/app.NewConnectorRouter), not by this
477	+// function; AuthContextFromContext here is read-only identification for
478	+// rate-limiting and audit purposes.
479	+func NewAuthHandler(deps Deps) http.HandlerFunc {
480	+	return func(w http.ResponseWriter, r *http.Request) {
481	+		ctx := r.Context()
482	+		ac, _ := api.AuthContextFromContext(ctx)
483	+		sourceIP := sourceIPFrom(r)
484	+
485	+		allowed, err := deps.Limiter.Allow(ctx, ac.Sub, sourceIP)
486	+		if err != nil {
487	+			writeJSON(w, http.StatusInternalServerError, identityErrorBody{Error: "server_error"})
488	+			return
489	+		}
490	+		if !allowed {
491	+			writeJSON(w, http.StatusTooManyRequests, identityErrorBody{Error: "slow_down"})
492	+			return
493	+		}
494	+
495	+		var body authRequestBody
496	+		if err := json.NewDecoder(io.LimitReader(r.Body, 1<<16)).Decode(&body); err != nil {
497	+			writeJSON(w, http.StatusBadRequest, identityErrorBody{Error: "invalid_request"})
498	+			return
499	+		}
500	+
501	+		// accessToken is scoped to this block only — read from the
502	+		// vendor call's return value, written straight into the
503	+		// response, never assigned to any wider-scoped variable or
504	+		// logged. This IS the narrowest this value can be scoped given
505	+		// /auth's own contract: its job is delivering the token to the
506	+		// caller, so it necessarily reaches the response writer, but
507	+		// nothing else.
508	+		accessToken, err := deps.Vendor.Authenticate(ctx, body.Username, body.Password)
509	+		if err != nil {
510	+			deps.Limiter.RecordFailure(ctx, ac.Sub, sourceIP)
511	+			logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditAuthnFailure)
512	+			// Generic failure regardless of *why* the vendor rejected
513	+			// it (unknown username vs. wrong password vs. vendor
514	+			// unreachable) — connector-security.md §4: "must not leak
515	+			// which part of the credential was wrong."
516	+			writeJSON(w, http.StatusUnauthorized, identityErrorBody{Error: "vendor_authentication_failed"})
517	+			return
518	+		}
519	+		deps.Limiter.RecordSuccess(ctx, ac.Sub, sourceIP)
520	+		logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditSuccess)
521	+
522	+		writeJSON(w, http.StatusOK, authResponseBody{AccessToken: accessToken})
523	+	}
524	+}
525	+
526	+// identityRequestBody is the assignment's own fixed POST /identity
527	+// contract — no credential field, since the vendor token travels as a
528	+// request header instead (connector-security.md §1).
529	+type identityRequestBody struct {
530	+	Phone string `json:"phone"`
531	+	Name  string `json:"name"`
532	+}
533	+
534	+type identityResponseBody struct {
535	+	Name          string `json:"name"`
536	+	Phone         string `json:"phone"`
537	+	StreetAddress string `json:"street_address"`
538	+	Locality      string `json:"locality"`
539	+	Region        string `json:"region"`
540	+	PostalCode    string `json:"postal_code"`
541	+	Country       string `json:"country"`
542	+}
543	+
544	+// vendorAccessTokenHeader is the header /identity accepts the vendor's
545	+// access_token on — a header, not a body field, since the assignment's
546	+// fixed {"phone","name"} body has no credential field (LT-41 acceptance
547	+// criteria).
548	+const vendorAccessTokenHeader = "X-Vendor-Access-Token"
549	+
550	+// NewIdentityHandler implements POST /identity. Every failure path
551	+// (missing token, malformed-looking token, vendor rejection) returns
552	+// through writeIdentityFailure after waitForFloor — the two calls
553	+// together are what make the three branches content- and
554	+// (approximately) time-identical, per connector-security.md §1/§4.
555	+func NewIdentityHandler(deps Deps) http.HandlerFunc {
556	+	return func(w http.ResponseWriter, r *http.Request) {
557	+		start := time.Now()
558	+		ctx := r.Context()
559	+		ac, _ := api.AuthContextFromContext(ctx)
560	+		sourceIP := sourceIPFrom(r)
561	+
562	+		allowed, err := deps.Limiter.Allow(ctx, ac.Sub, sourceIP)
563	+		if err != nil {
564	+			writeJSON(w, http.StatusInternalServerError, identityErrorBody{Error: "server_error"})
565	+			return
566	+		}
567	+		if !allowed {
568	+			// Not one of the three timing-oracle branches (it's an
569	+			// overt, openly-disclosed 429, not a covert signal) — no
570	+			// floor applied.
571	+			writeJSON(w, http.StatusTooManyRequests, identityErrorBody{Error: "slow_down"})
572	+			return
573	+		}
574	+
575	+		var body identityRequestBody
576	+		if err := json.NewDecoder(io.LimitReader(r.Body, 1<<16)).Decode(&body); err != nil {
577	+			// A malformed body is a caller bug, not one of the three
578	+			// named credential/token-validity branches — ordinary 400,
579	+			// no floor.
580	+			writeJSON(w, http.StatusBadRequest, identityErrorBody{Error: "invalid_request"})
581	+			return
582	+		}
583	+
584	+		token := strings.TrimSpace(r.Header.Get(vendorAccessTokenHeader))
585	+		if token == "" {
586	+			deps.Limiter.RecordFailure(ctx, ac.Sub, sourceIP)
587	+			logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditAuthnFailure)
588	+			waitForFloor(start)
589	+			writeIdentityFailure(w)
590	+			return
591	+		}
592	+
593	+		// token is scoped to this function only, passed by value into
594	+		// FetchIdentity, and never assigned to any variable outside
595	+		// this block or returned — attack-tree leaf 4's control
596	+		// (connector-security.md §1/Attack-tree row 4).
597	+		identity, err := deps.Vendor.FetchIdentity(ctx, token, body.Phone, body.Name)
598	+		if err != nil {
599	+			deps.Limiter.RecordFailure(ctx, ac.Sub, sourceIP)
600	+			logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditAuthnFailure)
601	+			waitForFloor(start)
602	+			writeIdentityFailure(w)
603	+			return
604	+		}
605	+		deps.Limiter.RecordSuccess(ctx, ac.Sub, sourceIP)
606	+		logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditSuccess)
607	+
608	+		// Success is not part of the timing-oracle concern — no floor.
609	+		writeJSON(w, http.StatusOK, identityResponseBody{
610	+			Name:          identity.Name,
611	+			Phone:         identity.Phone,
612	+			StreetAddress: identity.StreetAddress,
613	+			Locality:      identity.Locality,
614	+			Region:        identity.Region,
615	+			PostalCode:    identity.PostalCode,
616	+			Country:       identity.Country,
617	+		})
618	+	}
619	+}
620	+
621	+// logAuditOutcome logs caller sub/scope/timestamp/outcome only — never
622	+// the vendor username/password, vendor access_token, or any PII field
623	+// value, per connector-security.md §3/§5's audit discipline.
624	+func logAuditOutcome(ctx context.Context, auditLog api.AuditLogger, sub string, kind api.AuditEventKind) {
625	+	if auditLog == nil {
626	+		return
627	+	}
628	+	auditLog.Log(ctx, api.AuditEvent{
629	+		Sub:       sub,
630	+		Scope:     api.ScopeConnectorIdentityLookup,
631	+		Kind:      kind,
632	+		Timestamp: time.Now().UTC(),
633	+	})
634	+}
635	diff --git a/internal/connector/handlers_test.go b/internal/connector/handlers_test.go

{
  "command": "grep -n \"floor\\|timing\\|100ms\\|100 ms\\|oracle\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md"
}

47:- **Timing side-channel on `/identity`'s fail-closed error, partially mitigated, accepted residual (found by Tobias Lindqvist during LT-41 refinement, ruled 2026-09-13).** The identical-error requirement for "no token" / "bad token" / "vendor rejected it" (§1) covers response *body and status code*, but the three paths have inherently different latencies: no-token and bad-token fail locally (microseconds), vendor-rejected requires an actual round-trip to the third-party IDP (tens–hundreds of ms, and variable — the vendor's latency is not under our control). An attacker can distinguish "malformed/missing token" from "well-formed enough to reach the vendor" via timing alone, regardless of identical bodies.
49:  **This is a materially lower-severity leak than the classic timing side-channel this track has otherwise guarded against (e.g., password/account-existence timing, which this design closes by always running the same fixed-cost hash regardless of outcome).** What's disclosed here is only that a presented string has a shape that reached the vendor — not whether any specific identity or account exists, not PII, and not which part of a credential was wrong (§4's existing rule already normalizes vendor-rejection reasons). It's recon on token *shape*, not on any subject's identity.
51:  **Mitigation applied, not full closure: a response-time floor (~100ms, well under any `context.WithTimeout` budget in the call chain, so it doesn't interact with the timeout requirements elsewhere) applied uniformly across all three failure branches** — padding the fast local-fail paths up to roughly the floor narrows the trivially-observable microseconds-vs-hundreds-of-ms gap into something requiring statistical analysis across many requests rather than one request telling an attacker everything instantly. **Full closure is not pursued and is accepted as a residual**, because the vendor round-trip's latency *distribution* (not just its average) varies with real-world network and vendor conditions in ways a fixed floor cannot fully mask — unlike a local hash computation, which this design can and does make constant-time-equivalent regardless of outcome, a third-party network call's tail latency isn't ours to control. Closing this further would mean either delaying every request to match the vendor's worst observed latency (a real availability cost for a low-value information leak) or removing the network call from the timing entirely (impossible — we must actually ask the vendor). Accepted for this system on the grounds that the disclosed information is low-value token-shape recon, not identity or PII exposure, and the cost of full closure is disproportionate to that value.
58:- **Why this matters concretely:** without it, an unauthenticated caller could hit our `/auth` passthrough with arbitrary vendor credentials all day and use this connector as exactly the credential-testing oracle §4's rate-limit control is meant to prevent — but "rate-limited per calling-API-client" has nothing to bind "per calling-API-client" to if no caller identity is required to reach the endpoint at all.
65:This connector cannot enforce that boundary itself — the assignment's generic `/identity` contract (`{"phone": "...", "name": "..."}`, no scoping field) puts that decision entirely on the vendor's own API. **Stated assumption, not a resolved control:** this design assumes a real ABC/XYZ-shaped vendor binds `/identity` queries to the authenticated principal at the vendor side (i.e., the vendor's own API rejects a query for an identity other than the token-holder's). If that assumption doesn't hold for a given real vendor, this connector becomes a lookup oracle for anyone who can obtain one valid vendor token, and no control in §1–§5 touches that risk, because none of them govern token *authority* rather than token *custody*. This is the same class of question as the search API's object-level authorization (`api-auth-design.md`, S4) and belongs on `../01-product-industry-research-design/CLAUDE.md`'s list when evaluating which real vendor ABC/XYZ represents — this track cannot resolve it without knowing a concrete vendor's actual token semantics.
88:| 5 | Connector used as a credential-stuffing oracle against the vendor (rate-limit granularity unstated) | No per-identity/per-IP rate-limit granularity stated in the original design | M | M | **Control:** rate limit keyed per calling-API-client *and* per source IP, with a stricter threshold on vendor-auth *failure ratio* specifically (credential stuffing shows as a high failure ratio before high volume), paired with exponential backoff per identity attempted, not just per client — closes the granularity gap without adding a new requirement beyond what §4 already gestured at. | 03 (rate-limit logic) / 04 (shared rate-limit store or edge mechanism, if enforced at a gateway) | **L** | OWASP API4:2023; NIST SP 800-63B §5.2.2 |

{
  "command": "grep -n \"identityFailureFloor\\|waitForFloor\\|Since\\|Elapsed\\|Floor\" /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40.diff | sed -n '1,60p'"
}

386:+// identityFailureFloor is /identity's uniform response-time floor across
396:+const identityFailureFloor = 100 * time.Millisecond
450:+// waitForFloor sleeps out the remainder of identityFailureFloor since
456:+func waitForFloor(start time.Time) {
457:+	if remaining := identityFailureFloor - time.Since(start); remaining > 0 {
552:+// through writeIdentityFailure after waitForFloor — the two calls
588:+			waitForFloor(start)
601:+			waitForFloor(start)
764:+		elapsed := time.Since(start)
768:+	noTokenStatus, noTokenBody, noTokenElapsed := runCase(badTokenVendor, false)
769:+	badTokenStatus, badTokenBody, badTokenElapsed := runCase(badTokenVendor, true)
770:+	vendorRejectedStatus, vendorRejectedBody, vendorRejectedElapsed := runCase(vendorRejectedVendor, true)
780:+	// All three must land close to the ~100ms floor (identityFailureFloor),
786:+		"no-token":        noTokenElapsed,
787:+		"bad-token":       badTokenElapsed,
788:+		"vendor-rejected": vendorRejectedElapsed,
790:+		if elapsed < identityFailureFloor {
791:+			t.Errorf("%s branch returned in %v, want at least the %v floor", name, elapsed, identityFailureFloor)
793:+		if elapsed > identityFailureFloor+50*time.Millisecond {
794:+			t.Errorf("%s branch returned in %v, want within ~50ms of the %v floor", name, elapsed, identityFailureFloor)
799:+func TestNewIdentityHandler_Success_NoFloorApplied(t *testing.T) {
813:+	elapsed := time.Since(start)
818:+	if elapsed >= identityFailureFloor {

{
  "command": "cat > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40-review.md << 'EOF'\nIndependent review: Tomasz Wrede (02 Adversary) — PR #40 (LT-41, idp-connector `/auth`/`/identity`)\n\nRead the full diff. Three things checked, one real finding.\n\n**1. Fresh-Authorization-header-per-request — PASS, and it's structural, not test-shaped.**\n`httpvendorclient.go` builds a brand-new `*http.Request` via `http.NewRequestWithContext` inside `Authenticate`/`FetchIdentity` on every call, sets `Authorization` on that request object only, and never touches a client- or transport-level default header. `HTTPVendorClient` itself holds only `baseURL` (immutable string) and `httpClient` (a `*http.Client`, documented safe for concurrent use) as fields — there is no shared mutable state a concurrent-request race could corrupt, because nothing about the token is ever stored anywhere except as a local parameter passed straight into one request build. `Renata's test (`TestHTTPVendorClient_FetchIdentity_FreshAuthorizationHeaderPerRequest`) is sequential, correctly noted, but the reason it doesn't need to be concurrent to prove the property is that Go's connection-pool reuse (`http.Transport`) multiplexes TCP connections, never `*http.Request` objects or their headers — there's no code path here where two goroutines could contend over the same header. I'd still add a `-race`-run concurrent variant as cheap insurance against a future refactor reintroducing shared state (e.g., someone \"optimizing\" by hoisting a default header onto `defaultVendorHTTPClient` later), but this isn't a live gap today.\n\n**2. `GrantLimiter` reuse for vendor-call rate limiting — real gap, and it's a documented deviation from this project's own ruled control, not just my own preference. Flag as the one to fix.**\n`connector-security.md`'s own attack-tree row 5 (the credential-stuffing-oracle leaf S3/S8 chain already ruled on) specifies the control as: *\"rate limit keyed per calling-API-client and per source IP, with a stricter threshold on vendor-auth failure ratio specifically ... paired with exponential backoff per identity attempted, not just per client.\"* The shipped code (`connector_router.go`, `handlers.go`) keys the shared `GrantLimiter` instance on `(ac.Sub, sourceIP)` only — `ac.Sub` is the *calling internal API client's* subject (e.g., api-service's own service credential), not the end-user identity/username being tried against the vendor. The \"per identity attempted\" half of the ruled control is simply absent from this PR, with no comment naming the gap or an accepted-risk statement for it.\n\nWhy this matters concretely, not just as a documentation mismatch: this connector is called by a small number of trusted internal services sharing a small number of client credentials and source IPs — the effective `(sub, IP)` key space here is tiny, likely a single bucket for the whole connector's traffic in this project's own shape. That produces two failure modes at once, not one:\n- **Under-protective against a real attacker:** if the attacker's foothold is a compromised or malicious *internal caller* (the actual trust boundary this control is meant to defend), keying only by that caller's own sub does nothing to slow down testing many different stolen end-user credentials through it — they all share the same `(sub, IP)` bucket, but `RecordSuccess` on any one legitimate end-user login (which will happen regularly in normal traffic) resets the whole bucket's backoff, effectively laundering the attacker's failures.\n- **Over-protective against ordinary use:** the same coarse key means a handful of ordinary end-user password typos, all going through the one shared internal caller, can trip the shared backoff and rate-limit *every other unrelated end-user's* identity lookup behind that same caller — collateral denial-of-service from normal typo volume, not attacker behavior.\n\nBoth directions trace to the same root cause: the design explicitly named a second key dimension (identity attempted) as necessary to close this leaf, and the implementation dropped it silently. This should either be added (e.g., a secondary backoff bucket keyed on a salted/hashed form of the submitted username or phone — never the raw value, consistent with connector-security.md §3's never-log rule) or explicitly re-ruled as an accepted narrower scope with reasoning, the same way the timing floor below was.\n\n**3. ~100ms timing floor — PASS, framing matches the accepted-residual language exactly, applied uniformly, not over-claimed.**\n`identityFailureFloor`'s doc comment mirrors `connector-security.md` §4 near verbatim (\"narrows, but does not fully close ... full closure is an accepted non-goal\"), `waitForFloor` is called at both failure call sites that are part of the timing-oracle concern (no-token, and the merged bad-token/vendor-rejected path — the implementation actually collapses those into one code path rather than three, which reduces distinguishable branches versus the doc's three-way framing, a conservative deviation, not a risky one), and is correctly *not* applied to the 429 rate-limit branch (openly disclosed, not covert) or the malformed-JSON-body branch (not part of the named concern) or the success path. `TestNewIdentityHandler_AllThreeFailureBranches...` (name truncated in diff) checks all three named branches land within ~50ms of the floor, and a separate test confirms success is never floored. No gap, no over-claim.\n\nNet: 1 and 3 clean. 2 is the one that needs another pass — it's not a hypothetical concern, it's the project's own ruled control missing half its stated shape.\nEOF\ngh pr comment 40 --repo wtvamp/loginid-takehome --body-file /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40-review.md"
}

https://github.com/wtvamp/loginid-takehome/pull/40#issuecomment-5653525432

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/5d67789 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 | wc -l"
}

     691

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/5d67789 -H \"Accept: application/vnd.github.v3.diff\" 2>&1 > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit5d67789.diff\ngrep -n \"^diff --git\" /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit5d67789.diff"
}

1:diff --git a/cmd/idp-connector/main.go b/cmd/idp-connector/main.go
30:diff --git a/internal/app/connector_router.go b/internal/app/connector_router.go
70:diff --git a/internal/app/connector_router_test.go b/internal/app/connector_router_test.go
131:diff --git a/internal/connector/handlers.go b/internal/connector/handlers.go
280:diff --git a/internal/connector/handlers_test.go b/internal/connector/handlers_test.go
345:diff --git a/internal/connector/httpvendorclient.go b/internal/connector/httpvendorclient.go
368:diff --git a/internal/connector/identitylimiter.go b/internal/connector/identitylimiter.go
541:diff --git a/internal/connector/identitylimiter_test.go b/internal/connector/identitylimiter_test.go

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit5d67789.diff",
  "offset": 368,
  "limit": 175
}

368	diff --git a/internal/connector/identitylimiter.go b/internal/connector/identitylimiter.go
369	new file mode 100644
370	index 0000000..5792884
371	--- /dev/null
372	+++ b/internal/connector/identitylimiter.go
373	@@ -0,0 +1,167 @@
374	+package connector
375	+
376	+import (
377	+	"context"
378	+	"crypto/hmac"
379	+	"crypto/rand"
380	+	"crypto/sha256"
381	+	"encoding/hex"
382	+	"sync"
383	+	"time"
384	+
385	+	"loginid-takehome/internal/api"
386	+)
387	+
388	+// identityLimiterBaseBackoff/MaxBackoff/AlertThreshold are this
389	+// component's own engineering defaults, same reasoning as
390	+// connectorVendorLimiterBaseBackoff/etc. in internal/app/connector_router.go
391	+// — flagged for 02's review rather than treated as ruled numbers.
392	+const (
393	+	identityLimiterBaseBackoff    = 1 * time.Second
394	+	identityLimiterMaxBackoff     = 5 * time.Minute
395	+	identityLimiterAlertThreshold = 10
396	+)
397	+
398	+// maxTrackedIdentities bounds this limiter's own tracked-key set
399	+// independently of api.GrantLimiter's time-based sweep — the same
400	+// "bounded distinct-key cardinality" pattern LT-40's JWKSCache already
401	+// uses for unknown kids (jwksMaxTrackedUnknownKids), extended here to a
402	+// much larger value: unlike a kid (a small, bounded set of currently
403	+// valid signing keys), a legitimate identity space can genuinely be
404	+// large (many real vendor end-users), so capping at JWKS's own
405	+// small number would fail open on ordinary traffic almost immediately.
406	+// This is this component's own engineering default (flagged for 02's
407	+// review), not a ruled number.
408	+const maxTrackedIdentities = 10000
409	+
410	+// identityTrackedKeyTTL/identitySweepInterval bound how long a tracked
411	+// identity key survives with no further activity — same sweep-based
412	+// eviction shape as InProcessGrantLimiter/InProcessTouchCounter/
413	+// JWKSCache's own unknown-kid map, so a burst of one-off garbage
414	+// identities doesn't permanently consume tracked-key slots.
415	+const (
416	+	identityTrackedKeyTTL = time.Hour
417	+	identitySweepInterval = time.Minute
418	+)
419	+
420	+// identityHMACKey is generated once per process — this limiter's keys
421	+// never need to survive a restart (the state itself is in-process and
422	+// ephemeral), so a random key generated at process start is sufficient
423	+// and avoids embedding any fixed secret in source.
424	+var identityHMACKey = mustRandomBytes(32)
425	+
426	+func mustRandomBytes(n int) []byte {
427	+	b := make([]byte, n)
428	+	if _, err := rand.Read(b); err != nil {
429	+		panic("connector: generating identity-limiter HMAC key: " + err.Error())
430	+	}
431	+	return b
432	+}
433	+
434	+// hashIdentity derives this limiter's map key from (callerSub,
435	+// attemptedIdentity) — HMAC-SHA256, never the raw attempted identity
436	+// (a vendor username, or a phone/name pair) held as a map key or ever
437	+// logged (Tomasz Wrede's review, PR #40: "a salted/hashed submitted
438	+// identity, never the raw username/phone/whatever's being tried against
439	+// the vendor"). Composite over BOTH callerSub and attemptedIdentity —
440	+// per Marcus Ilori's ruling — so two different internal callers
441	+// submitting the same identity string never share one bucket, even
442	+// though this project's actual topology has only one internal caller
443	+// today.
444	+func hashIdentity(callerSub, attemptedIdentity string) string {
445	+	mac := hmac.New(sha256.New, identityHMACKey)
446	+	mac.Write([]byte(callerSub))
447	+	mac.Write([]byte{0}) // separator: prevents ("ab","c") colliding with ("a","bc")
448	+	mac.Write([]byte(attemptedIdentity))
449	+	return hex.EncodeToString(mac.Sum(nil))
450	+}
451	+
452	+// identityRateLimiter is attack-tree leaf 5's missing second dimension
453	+// (Tomasz Wrede's cold review of PR #40): connector-security.md's own
454	+// ruled control specifies backoff "per identity attempted, not just per
455	+// client" — the caller-level GrantLimiter instance
456	+// (internal/app/connector_router.go) alone means a single success
457	+// anywhere resets that caller's ENTIRE consecutive-failure count,
458	+// letting a compromised caller cycle through many stolen identities
459	+// indefinitely as long as it occasionally succeeds against one of them.
460	+// This type tracks backoff per (caller, attempted identity) instead, so
461	+// retrying the SAME identity trips independently of whether some OTHER
462	+// identity under the same caller just succeeded — and, symmetrically,
463	+// one legitimate user's typo never affects a different legitimate
464	+// user's own attempt under the same caller (both are named,
465	+// enforcement-tested properties, not just a design intent).
466	+//
467	+// Wraps api.GrantLimiter (not a new backoff mechanism — the hashed
468	+// identity is used as BOTH of GrantLimiter's own two key slots, since
469	+// neither "client_id" nor "source IP" is the right name for what this
470	+// tracks; using the same value for both is harmless, just double
471	+// bookkeeping for one entity) with an explicit, bounded tracked-key set
472	+// so an attacker submitting unbounded distinct garbage identities can't
473	+// grow memory without limit between GrantLimiter's own periodic sweeps.
474	+type identityRateLimiter struct {
475	+	underlying *api.InProcessGrantLimiter
476	+
477	+	mu        sync.Mutex
478	+	trackedAt map[string]time.Time
479	+	lastSweep time.Time
480	+}
481	+
482	+func NewIdentityRateLimiter() *identityRateLimiter {
483	+	return &identityRateLimiter{
484	+		underlying: api.NewInProcessGrantLimiter(
485	+			identityLimiterBaseBackoff, identityLimiterMaxBackoff, identityLimiterAlertThreshold, nil,
486	+		),
487	+		trackedAt: make(map[string]time.Time),
488	+	}
489	+}
490	+
491	+// allow reports whether an attempt against attemptedIdentity by
492	+// callerSub may proceed. Once maxTrackedIdentities distinct keys are
493	+// already tracked, a genuinely NEW identity is allowed through this
494	+// limiter (fails open on THIS dimension only) rather than blocking
495	+// every new identity outright — the caller-level GrantLimiter still
496	+// provides a base rate limit regardless, so this degrades to
497	+// caller-level-only protection under a tracked-key flood rather than
498	+// denying service to legitimate new identities (same reasoning as
499	+// JWKSCache's own bounded unknown-kid cap).
500	+func (l *identityRateLimiter) allow(ctx context.Context, callerSub, attemptedIdentity string) (bool, error) {
501	+	key := hashIdentity(callerSub, attemptedIdentity)
502	+
503	+	l.mu.Lock()
504	+	now := time.Now()
505	+	l.sweepLocked(now)
506	+	if _, tracked := l.trackedAt[key]; !tracked {
507	+		if len(l.trackedAt) >= maxTrackedIdentities {
508	+			l.mu.Unlock()
509	+			return true, nil
510	+		}
511	+		l.trackedAt[key] = now
512	+	} else {
513	+		l.trackedAt[key] = now
514	+	}
515	+	l.mu.Unlock()
516	+
517	+	return l.underlying.Allow(ctx, key, key)
518	+}
519	+
520	+func (l *identityRateLimiter) recordFailure(ctx context.Context, callerSub, attemptedIdentity string) {
521	+	key := hashIdentity(callerSub, attemptedIdentity)
522	+	l.underlying.RecordFailure(ctx, key, key)
523	+}
524	+
525	+func (l *identityRateLimiter) recordSuccess(ctx context.Context, callerSub, attemptedIdentity string) {
526	+	key := hashIdentity(callerSub, attemptedIdentity)
527	+	l.underlying.RecordSuccess(ctx, key, key)
528	+}
529	+
530	+func (l *identityRateLimiter) sweepLocked(now time.Time) {
531	+	if now.Sub(l.lastSweep) < identitySweepInterval {
532	+		return
533	+	}
534	+	l.lastSweep = now
535	+	for k, seenAt := range l.trackedAt {
536	+		if now.Sub(seenAt) >= identityTrackedKeyTTL {
537	+			delete(l.trackedAt, k)
538	+		}
539	+	}
540	+}
541	diff --git a/internal/connector/identitylimiter_test.go b/internal/connector/identitylimiter_test.go
542	new file mode 100644

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit5d67789.diff",
  "offset": 541,
  "limit": 160
}

541	diff --git a/internal/connector/identitylimiter_test.go b/internal/connector/identitylimiter_test.go
542	new file mode 100644
543	index 0000000..5c8f9e6
544	--- /dev/null
545	+++ b/internal/connector/identitylimiter_test.go
546	@@ -0,0 +1,145 @@
547	+package connector
548	+
549	+import (
550	+	"context"
551	+	"testing"
552	+)
553	+
554	+// TestIdentityRateLimiter_StolenIdentitiesSurviveAnUnrelatedSuccess is
555	+// Tomasz Wrede's named attack scenario (cold review of PR #40): the
556	+// caller-level GrantLimiter alone resets its ENTIRE consecutive-failure
557	+// count on any success, so a compromised caller cycling through many
558	+// stolen identities can keep a fresh allowance indefinitely as long as
559	+// it occasionally succeeds against ONE of them (e.g. one seed valid
560	+// account). Per-(caller, identity) keying must not have that property:
561	+// a specific identity's own backoff must trip on its own repeated
562	+// failures and must NOT be reset by a completely different identity
563	+// succeeding under the same caller.
564	+func TestIdentityRateLimiter_StolenIdentitiesSurviveAnUnrelatedSuccess(t *testing.T) {
565	+	l := NewIdentityRateLimiter()
566	+	ctx := context.Background()
567	+	const caller = "api-service"
568	+
569	+	// Fail against "victim-1" enough times to trip its own backoff.
570	+	blockedAfter := -1
571	+	for i := 0; i < 10; i++ {
572	+		allowed, err := l.allow(ctx, caller, "victim-1")
573	+		if err != nil {
574	+			t.Fatalf("allow: %v", err)
575	+		}
576	+		if !allowed {
577	+			blockedAfter = i
578	+			break
579	+		}
580	+		l.recordFailure(ctx, caller, "victim-1")
581	+	}
582	+	if blockedAfter == -1 {
583	+		t.Fatalf("victim-1 was never blocked across 10 consecutive failures")
584	+	}
585	+
586	+	// The attacker now succeeds against a COMPLETELY DIFFERENT identity
587	+	// under the same caller (the "one valid seed account" case).
588	+	allowed, err := l.allow(ctx, caller, "victim-2")
589	+	if err != nil {
590	+		t.Fatalf("allow: %v", err)
591	+	}
592	+	if !allowed {
593	+		t.Fatalf("victim-2 (never attempted before) was blocked — test setup bug")
594	+	}
595	+	l.recordSuccess(ctx, caller, "victim-2")
596	+
597	+	// victim-1 must STILL be blocked — victim-2's success must not have
598	+	// reset it. This is exactly the property a single shared per-caller
599	+	// bucket does NOT have (a success there resets everything).
600	+	allowed, err = l.allow(ctx, caller, "victim-1")
601	+	if err != nil {
602	+		t.Fatalf("allow: %v", err)
603	+	}
604	+	if allowed {
605	+		t.Errorf("victim-1 is allowed again after an unrelated identity (victim-2) succeeded — a per-identity bucket must not be resettable by a different identity's success")
606	+	}
607	+}
608	+
609	+// TestIdentityRateLimiter_TypoIsolation is Tomasz Wrede's other named
610	+// scenario: two different LEGITIMATE users behind the same caller, one
611	+// of whom mistypes their credential once, must not affect the other —
612	+// "strangers' typos" must not over-limit an unrelated identity.
613	+func TestIdentityRateLimiter_TypoIsolation(t *testing.T) {
614	+	l := NewIdentityRateLimiter()
615	+	ctx := context.Background()
616	+	const caller = "api-service"
617	+
618	+	// user-A mistypes once — this correctly starts user-A's OWN backoff
619	+	// (same progressive-backoff-from-the-first-failure design as
620	+	// api.GrantLimiter elsewhere in this codebase; not itself the
621	+	// property under test here) — then eventually succeeds.
622	+	if allowed, err := l.allow(ctx, caller, "user-A"); err != nil || !allowed {
623	+		t.Fatalf("user-A first attempt: allowed=%v err=%v", allowed, err)
624	+	}
625	+	l.recordFailure(ctx, caller, "user-A")
626	+	l.recordSuccess(ctx, caller, "user-A")
627	+
628	+	// user-B, a completely different identity under the same caller,
629	+	// must never have been affected by user-A's typo — first attempt
630	+	// must be allowed.
631	+	allowed, err := l.allow(ctx, caller, "user-B")
632	+	if err != nil {
633	+		t.Fatalf("allow: %v", err)
634	+	}
635	+	if !allowed {
636	+		t.Errorf("user-B was blocked by user-A's unrelated typo under the same caller — per-identity isolation must prevent this")
637	+	}
638	+}
639	+
640	+func TestIdentityRateLimiter_DifferentCallersSameIdentityDoNotShareState(t *testing.T) {
641	+	l := NewIdentityRateLimiter()
642	+	ctx := context.Background()
643	+
644	+	// caller-1 fails repeatedly against "shared-name" (both callers
645	+	// happen to submit the same attempted-identity string).
646	+	for i := 0; i < 10; i++ {
647	+		allowed, err := l.allow(ctx, "caller-1", "shared-name")
648	+		if err != nil {
649	+			t.Fatalf("allow: %v", err)
650	+		}
651	+		if !allowed {
652	+			break
653	+		}
654	+		l.recordFailure(ctx, "caller-1", "shared-name")
655	+	}
656	+
657	+	// caller-2 attempting the SAME identity string must not be affected
658	+	// — the key is composite over (caller, identity), per Marcus Ilori's
659	+	// ruling, not identity alone.
660	+	allowed, err := l.allow(ctx, "caller-2", "shared-name")
661	+	if err != nil {
662	+		t.Fatalf("allow: %v", err)
663	+	}
664	+	if !allowed {
665	+		t.Errorf("caller-2 was blocked by caller-1's failures against the same identity string — the key must be composite over (caller, identity)")
666	+	}
667	+}
668	+
669	+func TestIdentityRateLimiter_BoundedCardinality_DegradesOpenNotClosed(t *testing.T) {
670	+	l := NewIdentityRateLimiter()
671	+	ctx := context.Background()
672	+
673	+	// Flood past maxTrackedIdentities with distinct identities.
674	+	for i := 0; i < maxTrackedIdentities+10; i++ {
675	+		if _, err := l.allow(ctx, "flooding-caller", string(rune(i))+"-flood"); err != nil {
676	+			t.Fatalf("allow: %v", err)
677	+		}
678	+	}
679	+
680	+	// A brand-new identity past the cap must still be ALLOWED (fails
681	+	// open on this dimension only, per this type's own doc comment) —
682	+	// never silently denying service to a legitimate new identity just
683	+	// because the tracked-key set is full.
684	+	allowed, err := l.allow(ctx, "flooding-caller", "one-more-new-identity")
685	+	if err != nil {
686	+		t.Fatalf("allow: %v", err)
687	+	}
688	+	if !allowed {
689	+		t.Errorf("a new identity past maxTrackedIdentities was denied — this dimension must fail OPEN (allow), not closed, once the tracked-key cap is reached")
690	+	}
691	+}
692	

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit5d67789.diff",
  "offset": 131,
  "limit": 150
}

131	diff --git a/internal/connector/handlers.go b/internal/connector/handlers.go
132	index e16f09b..9695fe6 100644
133	--- a/internal/connector/handlers.go
134	+++ b/internal/connector/handlers.go
135	@@ -47,10 +47,45 @@ type vendorLimiter interface {
136	 }
137	 
138	 // Deps bundles NewAuthHandler/NewIdentityHandler's collaborators.
139	+//
140	+// IdentityLimiter is the second rate-limit dimension attack-tree leaf 5
141	+// actually specifies ("per identity attempted, not just per client") —
142	+// Limiter alone (keyed by calling-API-client sub + source IP) means one
143	+// success anywhere resets that caller's whole consecutive-failure count,
144	+// letting a compromised caller cycle through many stolen identities
145	+// indefinitely (Tomasz Wrede's cold review, PR #40). May be nil in tests
146	+// that don't exercise this dimension; NewConnectorRouter always
147	+// constructs a real one.
148	 type Deps struct {
149	-	Vendor   VendorClient
150	-	Limiter  vendorLimiter
151	-	AuditLog api.AuditLogger
152	+	Vendor          VendorClient
153	+	Limiter         vendorLimiter
154	+	IdentityLimiter *identityRateLimiter
155	+	AuditLog        api.AuditLogger
156	+}
157	+
158	+// identityGateAllow/RecordFailure/RecordSuccess are deps.IdentityLimiter's
159	+// call sites, tolerant of a nil IdentityLimiter (tests that only care
160	+// about the caller-level Limiter dimension can omit it — the identity
161	+// dimension then simply isn't enforced, never a panic).
162	+func identityGateAllow(ctx context.Context, l *identityRateLimiter, callerSub, attemptedIdentity string) (bool, error) {
163	+	if l == nil {
164	+		return true, nil
165	+	}
166	+	return l.allow(ctx, callerSub, attemptedIdentity)
167	+}
168	+
169	+func identityGateRecordFailure(ctx context.Context, l *identityRateLimiter, callerSub, attemptedIdentity string) {
170	+	if l == nil {
171	+		return
172	+	}
173	+	l.recordFailure(ctx, callerSub, attemptedIdentity)
174	+}
175	+
176	+func identityGateRecordSuccess(ctx context.Context, l *identityRateLimiter, callerSub, attemptedIdentity string) {
177	+	if l == nil {
178	+		return
179	+	}
180	+	l.recordSuccess(ctx, callerSub, attemptedIdentity)
181	 }
182	 
183	 func sourceIPFrom(r *http.Request) string {
184	@@ -127,6 +162,20 @@ func NewAuthHandler(deps Deps) http.HandlerFunc {
185	 			return
186	 		}
187	 
188	+		// Second rate-limit dimension — per (caller, attempted vendor
189	+		// username), not just per caller (attack-tree leaf 5, Tomasz
190	+		// Wrede's cold review of PR #40): gates BEFORE the vendor call,
191	+		// same as the caller-level Limiter above.
192	+		identityAllowed, err := identityGateAllow(ctx, deps.IdentityLimiter, ac.Sub, body.Username)
193	+		if err != nil {
194	+			writeJSON(w, http.StatusInternalServerError, identityErrorBody{Error: "server_error"})
195	+			return
196	+		}
197	+		if !identityAllowed {
198	+			writeJSON(w, http.StatusTooManyRequests, identityErrorBody{Error: "slow_down"})
199	+			return
200	+		}
201	+
202	 		// accessToken is scoped to this block only — read from the
203	 		// vendor call's return value, written straight into the
204	 		// response, never assigned to any wider-scoped variable or
205	@@ -137,6 +186,7 @@ func NewAuthHandler(deps Deps) http.HandlerFunc {
206	 		accessToken, err := deps.Vendor.Authenticate(ctx, body.Username, body.Password)
207	 		if err != nil {
208	 			deps.Limiter.RecordFailure(ctx, ac.Sub, sourceIP)
209	+			identityGateRecordFailure(ctx, deps.IdentityLimiter, ac.Sub, body.Username)
210	 			logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditAuthnFailure)
211	 			// Generic failure regardless of *why* the vendor rejected
212	 			// it (unknown username vs. wrong password vs. vendor
213	@@ -146,6 +196,7 @@ func NewAuthHandler(deps Deps) http.HandlerFunc {
214	 			return
215	 		}
216	 		deps.Limiter.RecordSuccess(ctx, ac.Sub, sourceIP)
217	+		identityGateRecordSuccess(ctx, deps.IdentityLimiter, ac.Sub, body.Username)
218	 		logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditSuccess)
219	 
220	 		writeJSON(w, http.StatusOK, authResponseBody{AccessToken: accessToken})
221	@@ -210,9 +261,26 @@ func NewIdentityHandler(deps Deps) http.HandlerFunc {
222	 			return
223	 		}
224	 
225	+		// Second rate-limit dimension — per (caller, attempted
226	+		// phone+name), not just per caller (attack-tree leaf 5, Tomasz
227	+		// Wrede's cold review of PR #40). Not one of the three
228	+		// timing-oracle branches (an overt 429, same as the caller-level
229	+		// gate above) — no floor.
230	+		attemptedIdentity := body.Phone + "|" + body.Name
231	+		identityAllowed, err := identityGateAllow(ctx, deps.IdentityLimiter, ac.Sub, attemptedIdentity)
232	+		if err != nil {
233	+			writeJSON(w, http.StatusInternalServerError, identityErrorBody{Error: "server_error"})
234	+			return
235	+		}
236	+		if !identityAllowed {
237	+			writeJSON(w, http.StatusTooManyRequests, identityErrorBody{Error: "slow_down"})
238	+			return
239	+		}
240	+
241	 		token := strings.TrimSpace(r.Header.Get(vendorAccessTokenHeader))
242	 		if token == "" {
243	 			deps.Limiter.RecordFailure(ctx, ac.Sub, sourceIP)
244	+			identityGateRecordFailure(ctx, deps.IdentityLimiter, ac.Sub, attemptedIdentity)
245	 			logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditAuthnFailure)
246	 			waitForFloor(start)
247	 			writeIdentityFailure(w)
248	@@ -226,24 +294,22 @@ func NewIdentityHandler(deps Deps) http.HandlerFunc {
249	 		identity, err := deps.Vendor.FetchIdentity(ctx, token, body.Phone, body.Name)
250	 		if err != nil {
251	 			deps.Limiter.RecordFailure(ctx, ac.Sub, sourceIP)
252	+			identityGateRecordFailure(ctx, deps.IdentityLimiter, ac.Sub, attemptedIdentity)
253	 			logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditAuthnFailure)
254	 			waitForFloor(start)
255	 			writeIdentityFailure(w)
256	 			return
257	 		}
258	 		deps.Limiter.RecordSuccess(ctx, ac.Sub, sourceIP)
259	+		identityGateRecordSuccess(ctx, deps.IdentityLimiter, ac.Sub, attemptedIdentity)
260	 		logAuditOutcome(ctx, deps.AuditLog, ac.Sub, api.AuditSuccess)
261	 
262	 		// Success is not part of the timing-oracle concern — no floor.
263	-		writeJSON(w, http.StatusOK, identityResponseBody{
264	-			Name:          identity.Name,
265	-			Phone:         identity.Phone,
266	-			StreetAddress: identity.StreetAddress,
267	-			Locality:      identity.Locality,
268	-			Region:        identity.Region,
269	-			PostalCode:    identity.PostalCode,
270	-			Country:       identity.Country,
271	-		})
272	+		// identityResponseBody's fields are identical in name/order/type
273	+		// to Identity (only the json tags differ), so a direct type
274	+		// conversion is both valid and clearer than restating every
275	+		// field (staticcheck S1016).
276	+		writeJSON(w, http.StatusOK, identityResponseBody(identity))
277	 	}
278	 }
279	 
280	diff --git a/internal/connector/handlers_test.go b/internal/connector/handlers_test.go

{
  "command": "cat > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40-recheck.md << 'EOF'\nIndependent review: Tomasz Wrede (02 Adversary) — PR #40 re-check at `5d67789`\n\n**My original finding 2 is closed. Both named scenarios are real, tested, and pass.**\n`identityRateLimiter` keys on `HMAC-SHA256(callerSub, attemptedIdentity)` — never the raw vendor username or phone/name — and is wired alongside, not instead of, the caller-level `GrantLimiter`. `TestIdentityRateLimiter_StolenIdentitiesSurviveAnUnrelatedSuccess` reproduces exactly the attack I named (compromised caller cycling stolen identities, occasionally succeeding against one seed account) and confirms the OTHER identity's backoff survives that unrelated success. `TestIdentityRateLimiter_TypoIsolation` confirms the opposite direction (one legitimate user's typo doesn't rate-limit a different legitimate user under the same caller). `TestIdentityRateLimiter_DifferentCallersSameIdentityDoNotShareState` is a good bonus check I didn't ask for but matches the design (\"composite over caller AND identity, per Marcus's ruling\") rather than identity alone, which would have been a different, subtler cross-tenant leak. Wiring in `handlers.go` gates before the vendor call in both handlers, correctly using `body.Username` for `/auth` and `phone|name` for `/identity`. This closes the gap connector-security.md's own ruled control specified and this PR's original version was missing.\n\n**The 10,000-key cap — you asked me to check this on my own initiative, and there is a real finding, but it's the opposite failure direction from the JWKS cap, and worth naming precisely.**\n\nUnlike JWKS's cap (which fails toward *rejection* when full — a bounded delay, never a bypass), this cap fails toward *allowance*: once 10,000 distinct `(caller, identity)` keys are tracked, a **brand-new** identity is let through with **no per-identity backoff applied at all** (`identityRateLimiter.allow`, the `len(l.trackedAt) >= maxTrackedIdentities` branch returns `true, nil` unconditionally) — confirmed and even explicitly tested as the intended behavior (`TestIdentityRateLimiter_BoundedCardinality_DegradesOpenNotClosed`). The design comment frames this as \"degrades to caller-level-only protection,\" which is true — but that caller-level-only state is *exactly* the weakness this whole fix exists to close (the original finding 2: one success anywhere resets the caller's whole bucket, so a compromised caller cycling many stolen identities defeats it as long as it occasionally succeeds against one).\n\nConcretely: an attacker doesn't need to attack real identities to trigger this. They can cheaply pre-fill the table — 10,000 distinct garbage `(caller, identity)` pairs, each touched at least once per `identityTrackedKeyTTL` (1 hour) to survive the sweep, which is roughly 3 requests/second sustained, trivial for even a small botnet, and doesn't require any valid vendor credential since a rejected `/auth` attempt still calls `identityGateRecordFailure` before the vendor rejects it — then proceed against real stolen identities, which now bypass identity-level backoff entirely and fall back to the exact caller-level bucket behavior finding 2 was written to fix. This isn't a hypothetical: the table is deliberately not evicting existing entries under pressure (good — that protects already-tracked legitimate identities from premature eviction, avoiding the JWKS-style mistake in that direction), but the flip side of that same design choice is that *new* identities past the cap get zero identity-level protection, which is precisely the dimension an attacker cares about exploiting.\n\nTo be fair to the design: refusing to evict existing tracked state to make room was the right call (protects already-established legitimate backoff state from a flood, unlike a naive LRU cap would), and *some* number has to degrade somehow once memory is bounded — there's no free lunch here. But \"degrades to caller-level-only\" needs to be read as \"degrades to the exact weakness finding 2 fixed,\" not as a soft, acceptable floor, and the 10,000 figure is called out in the code itself as \"this component's own engineering default... not a ruled number\" — so this is squarely a number Marcus should rule on with that framing in mind, the same way the JWKS staleness multiple and timing floor got explicit rulings. I'd want either a materially higher cap (raising the attacker's cost, not eliminating the shape) or a fallback response for the past-cap case that's stricter than \"identity-unlimited, caller-limit-only\" — e.g., a global cheap Bloom-filter-style \"have I seen many distinct new identities from this caller recently\" secondary signal — named as a follow-up rather than assumed closed.\n\nNet: identity-dimension gap from my first review — closed, both named scenarios pass. New finding: the cap's fail-open direction reintroduces a cheaper, attacker-triggerable path back to that same original weakness, and it's an unrolled engineering default rather than a ruled number.\nEOF\ngh pr comment 40 --repo wtvamp/loginid-takehome --body-file /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40-recheck.md"
}

https://github.com/wtvamp/loginid-takehome/pull/40#issuecomment-5653622652

{
  "command": "gh api repos/wtvamp/loginid-takehome/commits/38a2bdd -H \"Accept: application/vnd.github.v3.diff\" 2>&1 > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit38a2bdd.diff\nwc -l /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit38a2bdd.diff\ngrep -n \"^diff --git\" /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit38a2bdd.diff"
}

     417 /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit38a2bdd.diff
1:diff --git a/internal/connector/handlers.go b/internal/connector/handlers.go
79:diff --git a/internal/connector/identitylimiter.go b/internal/connector/identitylimiter.go
303:diff --git a/internal/connector/identitylimiter_test.go b/internal/connector/identitylimiter_test.go

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit38a2bdd.diff",
  "offset": 79,
  "limit": 225
}

79	diff --git a/internal/connector/identitylimiter.go b/internal/connector/identitylimiter.go
80	index 5792884..ea44ed0 100644
81	--- a/internal/connector/identitylimiter.go
82	+++ b/internal/connector/identitylimiter.go
83	@@ -22,6 +22,26 @@ const (
84	 	identityLimiterAlertThreshold = 10
85	 )
86	 
87	+// identityOverflowBaseBackoff/MaxBackoff/AlertThreshold govern the
88	+// SHARED overflow bucket (below) — deliberately more aggressive than
89	+// the per-identity constants above: this bucket protects against every
90	+// identity that couldn't get its own slot at once, so it should trip
91	+// faster and stay tripped longer than any single identity's own bucket
92	+// would (Marcus Ilori's ruling, PR #40: "fail-toward-stricter under
93	+// pressure, not fail-open... a shared, aggressive rate limit instead of
94	+// no limit at all").
95	+const (
96	+	identityOverflowBaseBackoff    = 5 * time.Second
97	+	identityOverflowMaxBackoff     = 10 * time.Minute
98	+	identityOverflowAlertThreshold = 3
99	+)
100	+
101	+// identityOverflowKey is the shared bucket's single, fixed key — used
102	+// via the overflow limiter's own clientID/sourceIP slots exactly like
103	+// any per-identity key is, but always this one fixed value, never a
104	+// hash of a real identity.
105	+const identityOverflowKey = "identity-limiter-overflow"
106	+
107	 // maxTrackedIdentities bounds this limiter's own tracked-key set
108	 // independently of api.GrantLimiter's time-based sweep — the same
109	 // "bounded distinct-key cardinality" pattern LT-40's JWKSCache already
110	@@ -32,6 +52,14 @@ const (
111	 // small number would fail open on ordinary traffic almost immediately.
112	 // This is this component's own engineering default (flagged for 02's
113	 // review), not a ruled number.
114	+//
115	+// Past this cap, a genuinely new identity does NOT bypass identity-level
116	+// limiting entirely — Marcus Ilori's ruling rejected that as
117	+// "degrading to the exact original weakness Tomasz found," since a cap
118	+// an attacker can cheaply fill (no valid vendor credential needed) would
119	+// just delay, not close, the stolen-identities scenario. Instead it
120	+// falls into the shared overflow bucket below: coarser (many identities
121	+// share one bucket once the table is full), but never zero protection.
122	 const maxTrackedIdentities = 10000
123	 
124	 // identityTrackedKeyTTL/identitySweepInterval bound how long a tracked
125	@@ -58,21 +86,34 @@ func mustRandomBytes(n int) []byte {
126	 	return b
127	 }
128	 
129	-// hashIdentity derives this limiter's map key from (callerSub,
130	-// attemptedIdentity) — HMAC-SHA256, never the raw attempted identity
131	-// (a vendor username, or a phone/name pair) held as a map key or ever
132	-// logged (Tomasz Wrede's review, PR #40: "a salted/hashed submitted
133	-// identity, never the raw username/phone/whatever's being tried against
134	-// the vendor"). Composite over BOTH callerSub and attemptedIdentity —
135	+// hashIdentity derives this limiter's map key from callerSub plus one
136	+// or more identity components (a single vendor username for /auth; a
137	+// phone AND name passed as two SEPARATE components for /identity,
138	+// rather than pre-joined with a printable separator) — HMAC-SHA256,
139	+// never the raw attempted identity held as a map key or ever logged
140	+// (Tomasz Wrede's review, PR #40: "a salted/hashed submitted identity,
141	+// never the raw username/phone/whatever's being tried against the
142	+// vendor"). Composite over BOTH callerSub and the identity components —
143	 // per Marcus Ilori's ruling — so two different internal callers
144	-// submitting the same identity string never share one bucket, even
145	-// though this project's actual topology has only one internal caller
146	-// today.
147	-func hashIdentity(callerSub, attemptedIdentity string) string {
148	+// submitting the same identity never share one bucket, even though this
149	+// project's actual topology has only one internal caller today.
150	+//
151	+// Each component is written with its own null-byte separator rather
152	+// than concatenated by the caller first: passing body.Phone and
153	+// body.Name as two separate arguments here (instead of joining them
154	+// with a printable delimiter like "|" before calling this function)
155	+// avoids a delimiter collision with a printable character that's
156	+// actually plausible in real phone/name input, narrowing (not fully
157	+// eliminating — a null byte could theoretically still appear in an
158	+// input) the same class of concatenation ambiguity a naive join would
159	+// have (Oren Castellan, PR #40 review).
160	+func hashIdentity(callerSub string, identityParts ...string) string {
161	 	mac := hmac.New(sha256.New, identityHMACKey)
162	 	mac.Write([]byte(callerSub))
163	-	mac.Write([]byte{0}) // separator: prevents ("ab","c") colliding with ("a","bc")
164	-	mac.Write([]byte(attemptedIdentity))
165	+	for _, part := range identityParts {
166	+		mac.Write([]byte{0})
167	+		mac.Write([]byte(part))
168	+	}
169	 	return hex.EncodeToString(mac.Sum(nil))
170	 }
171	 
172	@@ -98,8 +139,13 @@ func hashIdentity(callerSub, attemptedIdentity string) string {
173	 // bookkeeping for one entity) with an explicit, bounded tracked-key set
174	 // so an attacker submitting unbounded distinct garbage identities can't
175	 // grow memory without limit between GrantLimiter's own periodic sweeps.
176	+// A second, separate GrantLimiter instance backs the shared overflow
177	+// bucket past maxTrackedIdentities — its own key space is exactly one
178	+// fixed value (identityOverflowKey), so it's bounded by construction
179	+// regardless of how many distinct identities overflow into it.
180	 type identityRateLimiter struct {
181	-	underlying *api.InProcessGrantLimiter
182	+	underlying *api.InProcessGrantLimiter // per-identity buckets, for tracked keys
183	+	overflow   *api.InProcessGrantLimiter // one shared bucket for everything past the cap
184	 
185	 	mu        sync.Mutex
186	 	trackedAt map[string]time.Time
187	@@ -111,47 +157,87 @@ func NewIdentityRateLimiter() *identityRateLimiter {
188	 		underlying: api.NewInProcessGrantLimiter(
189	 			identityLimiterBaseBackoff, identityLimiterMaxBackoff, identityLimiterAlertThreshold, nil,
190	 		),
191	+		overflow: api.NewInProcessGrantLimiter(
192	+			identityOverflowBaseBackoff, identityOverflowMaxBackoff, identityOverflowAlertThreshold, nil,
193	+		),
194	 		trackedAt: make(map[string]time.Time),
195	 	}
196	 }
197	 
198	-// allow reports whether an attempt against attemptedIdentity by
199	-// callerSub may proceed. Once maxTrackedIdentities distinct keys are
200	-// already tracked, a genuinely NEW identity is allowed through this
201	-// limiter (fails open on THIS dimension only) rather than blocking
202	-// every new identity outright — the caller-level GrantLimiter still
203	-// provides a base rate limit regardless, so this degrades to
204	-// caller-level-only protection under a tracked-key flood rather than
205	-// denying service to legitimate new identities (same reasoning as
206	-// JWKSCache's own bounded unknown-kid cap).
207	-func (l *identityRateLimiter) allow(ctx context.Context, callerSub, attemptedIdentity string) (bool, error) {
208	-	key := hashIdentity(callerSub, attemptedIdentity)
209	-
210	+// trackOrCheck is the ONE place that decides whether key is "tracked" —
211	+// called from allow (where a not-yet-tracked key is admitted if there's
212	+// room under maxTrackedIdentities) and from recordFailure/recordSuccess
213	+// (where a not-tracked key is never admitted; record* never adds a new
214	+// entry on its own). This single choke point is what actually enforces
215	+// the memory bound: recordFailure/recordSuccess used to skip this check
216	+// entirely and call straight into the wrapped api.GrantLimiter, so an
217	+// attacker flooding past the cap with fresh failing identities grew that
218	+// limiter's own byClientID/bySourceIP maps without limit even though
219	+// allow() itself correctly degraded open — the cap was checked in the
220	+// one place that doesn't retain state and skipped in the two places
221	+// that do (Nolan Reyes, PR #40 review). Now every one of the three entry
222	+// points agrees on the same tracked/not-tracked answer for a given key
223	+// at a given moment, and only a tracked key ever reaches the wrapped
224	+// limiter at all.
225	+func (l *identityRateLimiter) trackOrCheck(key string, admitIfRoom bool) bool {
226	 	l.mu.Lock()
227	+	defer l.mu.Unlock()
228	 	now := time.Now()
229	 	l.sweepLocked(now)
230	-	if _, tracked := l.trackedAt[key]; !tracked {
231	-		if len(l.trackedAt) >= maxTrackedIdentities {
232	-			l.mu.Unlock()
233	-			return true, nil
234	-		}
235	-		l.trackedAt[key] = now
236	-	} else {
237	-		l.trackedAt[key] = now
238	+
239	+	if _, tracked := l.trackedAt[key]; tracked {
240	+		l.trackedAt[key] = now // refresh: this is activity, extend the TTL
241	+		return true
242	+	}
243	+	if !admitIfRoom || len(l.trackedAt) >= maxTrackedIdentities {
244	+		return false
245	 	}
246	-	l.mu.Unlock()
247	+	l.trackedAt[key] = now
248	+	return true
249	+}
250	 
251	-	return l.underlying.Allow(ctx, key, key)
252	+// allow reports whether an attempt against attemptedIdentity by
253	+// callerSub may proceed. Once maxTrackedIdentities distinct keys are
254	+// already tracked, a genuinely NEW identity does NOT bypass
255	+// identity-level limiting — it falls into the shared overflow bucket
256	+// instead (Marcus Ilori's ruling: fail toward stricter under pressure,
257	+// not open, matching this project's own pattern elsewhere — JWKS fails
258	+// toward rejection past its staleness bound, the distinct-record
259	+// counter hard-denies rather than merely alerting). Existing tracked
260	+// identities keep their own individual buckets, unaffected.
261	+func (l *identityRateLimiter) allow(ctx context.Context, callerSub string, identityParts ...string) (bool, error) {
262	+	key := hashIdentity(callerSub, identityParts...)
263	+	if l.trackOrCheck(key, true) {
264	+		return l.underlying.Allow(ctx, key, key)
265	+	}
266	+	return l.overflow.Allow(ctx, identityOverflowKey, identityOverflowKey)
267	 }
268	 
269	-func (l *identityRateLimiter) recordFailure(ctx context.Context, callerSub, attemptedIdentity string) {
270	-	key := hashIdentity(callerSub, attemptedIdentity)
271	-	l.underlying.RecordFailure(ctx, key, key)
272	+// recordFailure/recordSuccess never admit a new key into the per-identity
273	+// tracked set on their own — only allow() (called first, on every
274	+// request, per handlers.go's wiring) decides whether a key gets its own
275	+// slot. A key that allow() routed to the overflow bucket is recorded
276	+// there too, keeping the per-identity limiter's own maps bounded by
277	+// maxTrackedIdentities regardless of how many distinct identities an
278	+// attacker generates, while the shared overflow bucket still
279	+// accumulates failures across all of them (bounded by construction: its
280	+// key space is exactly one fixed value).
281	+func (l *identityRateLimiter) recordFailure(ctx context.Context, callerSub string, identityParts ...string) {
282	+	key := hashIdentity(callerSub, identityParts...)
283	+	if l.trackOrCheck(key, false) {
284	+		l.underlying.RecordFailure(ctx, key, key)
285	+		return
286	+	}
287	+	l.overflow.RecordFailure(ctx, identityOverflowKey, identityOverflowKey)
288	 }
289	 
290	-func (l *identityRateLimiter) recordSuccess(ctx context.Context, callerSub, attemptedIdentity string) {
291	-	key := hashIdentity(callerSub, attemptedIdentity)
292	-	l.underlying.RecordSuccess(ctx, key, key)
293	+func (l *identityRateLimiter) recordSuccess(ctx context.Context, callerSub string, identityParts ...string) {
294	+	key := hashIdentity(callerSub, identityParts...)
295	+	if l.trackOrCheck(key, false) {
296	+		l.underlying.RecordSuccess(ctx, key, key)
297	+		return
298	+	}
299	+	l.overflow.RecordSuccess(ctx, identityOverflowKey, identityOverflowKey)
300	 }
301	 
302	 func (l *identityRateLimiter) sweepLocked(now time.Time) {
303	diff --git a/internal/connector/identitylimiter_test.go b/internal/connector/identitylimiter_test.go

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/commit38a2bdd.diff",
  "offset": 303,
  "limit": 115
}

303	diff --git a/internal/connector/identitylimiter_test.go b/internal/connector/identitylimiter_test.go
304	index 5c8f9e6..6d47cd9 100644
305	--- a/internal/connector/identitylimiter_test.go
306	+++ b/internal/connector/identitylimiter_test.go
307	@@ -120,26 +120,102 @@ func TestIdentityRateLimiter_DifferentCallersSameIdentityDoNotShareState(t *test
308	 	}
309	 }
310	 
311	-func TestIdentityRateLimiter_BoundedCardinality_DegradesOpenNotClosed(t *testing.T) {
312	+// TestIdentityRateLimiter_BoundedCardinality_OverflowsToSharedBucket is
313	+// Marcus Ilori's ruling (PR #40): past maxTrackedIdentities, a new
314	+// identity does NOT bypass identity-level limiting — it falls into a
315	+// shared overflow bucket instead. First proves a brand-new identity past
316	+// the cap is still allowed on its FIRST attempt (the overflow bucket
317	+// starts fresh, same as any bucket would); then proves the bucket is
318	+// genuinely SHARED — failures recorded against one overflowing identity
319	+// eventually block a DIFFERENT overflowing identity too, which is
320	+// exactly the "never zero protection" property a plain fail-open design
321	+// would not have.
322	+func TestIdentityRateLimiter_BoundedCardinality_OverflowsToSharedBucket(t *testing.T) {
323	 	l := NewIdentityRateLimiter()
324	 	ctx := context.Background()
325	 
326	-	// Flood past maxTrackedIdentities with distinct identities.
327	+	// Flood past maxTrackedIdentities with distinct identities, each
328	+	// only ever calling allow() (no failures recorded) — fills the
329	+	// per-identity tracked set without touching the overflow bucket.
330	 	for i := 0; i < maxTrackedIdentities+10; i++ {
331	 		if _, err := l.allow(ctx, "flooding-caller", string(rune(i))+"-flood"); err != nil {
332	 			t.Fatalf("allow: %v", err)
333	 		}
334	 	}
335	 
336	-	// A brand-new identity past the cap must still be ALLOWED (fails
337	-	// open on this dimension only, per this type's own doc comment) —
338	-	// never silently denying service to a legitimate new identity just
339	-	// because the tracked-key set is full.
340	-	allowed, err := l.allow(ctx, "flooding-caller", "one-more-new-identity")
341	+	// A brand-new identity past the cap is allowed on its first attempt
342	+	// — the shared overflow bucket itself hasn't been tripped yet.
343	+	allowed, err := l.allow(ctx, "flooding-caller", "overflow-identity-1")
344	 	if err != nil {
345	 		t.Fatalf("allow: %v", err)
346	 	}
347	 	if !allowed {
348	-		t.Errorf("a new identity past maxTrackedIdentities was denied — this dimension must fail OPEN (allow), not closed, once the tracked-key cap is reached")
349	+		t.Fatalf("a new identity past maxTrackedIdentities was denied on its FIRST attempt — the shared overflow bucket should start unblocked")
350	+	}
351	+	l.recordFailure(ctx, "flooding-caller", "overflow-identity-1")
352	+
353	+	// A DIFFERENT identity, also past the cap, must eventually be
354	+	// blocked by the SAME shared bucket — proving this isn't a
355	+	// per-overflow-identity allowance in disguise, and that the "never
356	+	// zero protection" property actually holds: enough overflow traffic
357	+	// (from any mix of identities) still trips real limiting.
358	+	blockedAfter := -1
359	+	for i := 0; i < 10; i++ {
360	+		ok, err := l.allow(ctx, "flooding-caller", "overflow-identity-2")
361	+		if err != nil {
362	+			t.Fatalf("allow: %v", err)
363	+		}
364	+		if !ok {
365	+			blockedAfter = i
366	+			break
367	+		}
368	+		l.recordFailure(ctx, "flooding-caller", "overflow-identity-2")
369	+	}
370	+	if blockedAfter == -1 {
371	+		t.Fatalf("the shared overflow bucket never blocked anything across 10 consecutive overflow failures — overflow traffic is getting no protection at all")
372	+	}
373	+}
374	+
375	+// TestIdentityRateLimiter_TrackedIdentityUnaffectedByOverflowPressure
376	+// confirms an identity that DID get its own tracked slot (within the
377	+// cap) is completely unaffected by however much unrelated traffic is
378	+// hammering the shared overflow bucket — the two are genuinely
379	+// independent limiters, not one shared fate.
380	+func TestIdentityRateLimiter_TrackedIdentityUnaffectedByOverflowPressure(t *testing.T) {
381	+	l := NewIdentityRateLimiter()
382	+	ctx := context.Background()
383	+
384	+	// A legitimately-tracked identity, within the cap.
385	+	if allowed, err := l.allow(ctx, "caller", "legit-user"); err != nil || !allowed {
386	+		t.Fatalf("legit-user first attempt: allowed=%v err=%v", allowed, err)
387	+	}
388	+
389	+	// Drive the shared overflow bucket into its blocked state with a
390	+	// flood of DIFFERENT, never-tracked identities under the same cap
391	+	// pressure (reuse the same flood as the sibling test, cheaply, by
392	+	// filling the tracked set first).
393	+	for i := 0; i < maxTrackedIdentities; i++ {
394	+		if _, err := l.allow(ctx, "caller", string(rune(i))+"-fill"); err != nil {
395	+			t.Fatalf("allow: %v", err)
396	+		}
397	+	}
398	+	for i := 0; i < 10; i++ {
399	+		ok, err := l.allow(ctx, "caller", "overflow-attacker")
400	+		if err != nil {
401	+			t.Fatalf("allow: %v", err)
402	+		}
403	+		if !ok {
404	+			break
405	+		}
406	+		l.recordFailure(ctx, "caller", "overflow-attacker")
407	+	}
408	+
409	+	// legit-user's OWN tracked bucket must be untouched by any of that.
410	+	allowed, err := l.allow(ctx, "caller", "legit-user")
411	+	if err != nil {
412	+		t.Fatalf("allow: %v", err)
413	+	}
414	+	if !allowed {
415	+		t.Errorf("legit-user (a tracked, within-cap identity) was blocked by unrelated overflow-bucket pressure — the two must be independent")
416	 	}
417	 }

{
  "command": "cat > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40-recheck2.md << 'EOF'\nIndependent review: Tomasz Wrede (02 Adversary) — PR #40 final re-check at `38a2bdd`\n\n**Does the pre-fill-then-attack scenario now get meaningfully throttled? Yes, in isolation — confirmed by mechanics, not just by the tests' names.**\nPast `maxTrackedIdentities`, `trackOrCheck` now routes an untracked key to `overflow.Allow`/`RecordFailure`/`RecordSuccess` instead of the old unconditional `true, nil`. `TestIdentityRateLimiter_BoundedCardinality_OverflowsToSharedBucket` proves the shared bucket genuinely accumulates and trips across *different* overflowing identities, not per-identity in disguise, and `TestIdentityRateLimiter_TrackedIdentityUnaffectedByOverflowPressure` proves it doesn't leak backward onto already-tracked identities. Nolan's fix to route `recordFailure`/`recordSuccess` through the same `trackOrCheck` choke point (not just `allow`) closes a real adjacent bug — the old code would have let overflow failures grow the wrapped `GrantLimiter`'s own maps unbounded even after `allow()` correctly degraded. So: an attacker who pre-fills the table and then attacks one specific stolen identity, **with no other overflow traffic happening concurrently**, does get genuinely rate-limited by the shared bucket — confirmed, not merely nominal.\n\n**But you're right to ask about the shared bucket itself, and there's a real structural point here, not just a hypothetical.**\n`api.InProcessGrantLimiter.RecordSuccess` clears a key's backoff state entirely — that's its documented, correct behavior for the caller-credentials use case it was originally built for. The overflow bucket uses ONE fixed key (`identityOverflowKey`) shared by every identity that overflows, from every caller, for any reason. That means: **any single success by any legitimately new identity overflowing at the same time resets the entire shared bucket** — including an attacker's own accumulating failures against an unrelated stolen identity that also happens to be in overflow. This is precisely the \"one success anywhere resets everything\" flaw that per-identity buckets were built to eliminate in the first place — it has been reintroduced one tier up, at the overflow population instead of the caller population. None of the new tests exercise this: both overflow tests only ever call `recordFailure`, never `recordSuccess`, so the reset-by-unrelated-success property isn't verified either way.\n\n**Is that acceptable coarsening, per your framing? Conditionally, and the condition isn't established anywhere.**\nIt's acceptable if the overflow population stays genuinely rare — a true edge case reached only under sustained flooding, where an attacker attacking in isolation (no organic overflow traffic) still gets caught, as demonstrated. It stops being acceptable if `maxTrackedIdentities` (10,000, still explicitly flagged in the code as \"this component's own engineering default... not a ruled number\") is small relative to real expected traffic: if this connector's real-world identity-lookup volume routinely exceeds 10,000 distinct identities within `identityTrackedKeyTTL` (1 hour), overflow becomes the *normal* case for new users, not the degraded edge case, and the shared-bucket reset-by-unrelated-success dilution becomes routine rather than adversarial — a real attacker could then hide targeted failures among ordinary background overflow successes essentially permanently, since normal traffic would keep clearing the bucket. Nothing in this PR establishes what \"normal\" traffic volume is expected to be, so there's no basis yet to say which side of that line this system sits on.\n\n**My recommendation, not blocking merge:** this is a legitimate accepted-residual candidate, same shape as the timing floor — should get the same explicit named treatment (\"shared overflow bucket resets on any overflow success; acceptable because overflow is expected to be rare given traffic volume X; revisit if actual volume approaches the cap\") rather than being left as an implicit property nobody has stated out loud. I don't think this blocks the gate — the isolated-attacker scenario I originally raised is genuinely fixed, and \"coarser but never zero\" under flood is a defensible engineering trade-off — but I'd want that reasoning written down before this is treated as fully closed, the same way `connector-security.md` §4 wrote down the timing floor's own accepted-residual reasoning explicitly rather than leaving it implicit.\n\nNet: original scenario — closed, verified by mechanics and test. New structural note — a real, nameable residual (shared-bucket reset dilution at scale), not a blocker, but it should get a ruling and a line in the doc rather than stay silent.\nEOF\ngh pr comment 40 --repo wtvamp/loginid-takehome --body-file /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/24287bc9-e284-45c4-9fca-81a6a4212461/scratchpad/pr40-recheck2.md"
}

https://github.com/wtvamp/loginid-takehome/pull/40#issuecomment-5653735240