Helena Marsh

{
  "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/helena-marsh/helena-marsh.md"
}

1	---
2	schema_version: 1
3	name: "Helena Marsh"
4	slug: "helena-marsh"
5	image: "profiles/helena-marsh/helena-marsh.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: "Helena Marsh, a woman in her mid 40s with shoulder-length dark blonde hair tied back neatly, thin-framed glasses, a composed and attentive expression, wearing a navy blouse under a structured grey jacket, 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	# Helena Marsh
23	
24	![Helena Marsh](profiles/helena-marsh/helena-marsh.png)
25	
26	
27	## Personality
28	
29	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.
30	
31	

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

{"name": "Helena Marsh", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

{
  "to": "marcus-ilori",
  "content": "Helena Marsh, checked in. Read root CLAUDE.md, track CLAUDE.md, PLAN.md, and my persona; profile displayed. Oriented on my seats: S3 blue (connector token lifecycle red/blue), S4 Proposer (search-API authz scoping adversarial pair), S8 second review (threat-model.md, api-auth-design.md — not authored by me). Holding until you call my seat."
}

<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	

{
  "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	- **Scopes**, carried in the JWT `scope` claim, e.g. `profile:read:own`, `profile:read:any`, `profile:search`. A given client-credential is provisioned with the narrowest scope its actual use case requires — most integrations should get `profile:read:own` (retrieve a specific known record by id, e.g. resolving a record the caller already has a legitimate reference to) rather than `profile:search` (query by name/phone fragments across the table), which should be reserved for a small number of explicitly-provisioned back-office callers.
33	- **Object-level authorization is enforced per request, not just per token.** Holding `profile:read:any` scope is necessary but not sufficient — every retrieve/search call is logged (see below) and, where the caller model supports it, additionally checked against a resource-level policy (e.g., a partner integration scoped to only its own referred users) rather than trusting the coarse scope alone. This directly targets OWASP API1:2023 (Broken Object Level Authorization), cited in the threat model.
34	- **Search results are paginated with a hard page-size ceiling** and rate-limited per client, independent of the scope check — a legitimately-scoped caller doing an anomalously large number of sequential searches is still a signal worth throttling and alerting on, not just permitting because the token was valid.
35	
36	## Defense in depth beyond the token check
37	
38	- **TLS 1.2+ only**, terminated in front of the API; no plaintext.
39	- **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).
40	- **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.
41	- **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.
42	
43	## Why not "just API keys"
44	
45	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.
46	
47	## Sources
48	
49	- RFC 6749 (OAuth 2.0), §4.4 Client Credentials Grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
50	- RFC 7519 (JSON Web Token): https://datatracker.ietf.org/doc/html/rfc7519
51	- 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/
52	

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

{"name": "Helena Marsh", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

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

1	# Threat Model
2	
3	Owner: Marcus Ilori (`02-ai-security-architecture`). Scope per this track's `CLAUDE.md`: credential storage, PII exposure, and third-party `access_token` handling. Retention/lifecycle policy is `../05-data-ops/CLAUDE.md`'s call, not mine — I model exposure and access risk, not how long data should live.
4	
5	## Assumptions, named explicitly
6	
7	1. **Assets in scope**: `user_credential` (username, method, password — modeled by Priya/`05-data-ops` as a lookup-table `method`, not a native enum, so a given user can have more than one credential row, e.g. password + WebAuthn), `user_profile` (name, address, phone), and third-party `access_token`s obtained via the IDP connector's `/auth`.
8	2. **`method` is not "always password."** Priya's schema treats `method` as an FK into an `auth_method` table (`id`, `name`, `requires_secret`, `is_active`). That means "credential storage" is not one hashing problem — it's a family of them, one per method, and this document treats it that way rather than assuming a single password column.
9	
10	### Concrete hashing decision, against the landed schema
11	
12	Priya's prose schema in `../05-data-ops/multi-db-strategy.md` (the `.sql` files were deliberately wiped with the rest of the code on 2026-09-12; the prose contract is the source of truth until Warren's code go-ahead) gives `user_credential` three columns for this purpose: `secret` (nullable TEXT, salted hash only — NULL where `auth_method.requires_secret = false`, e.g. passkey/WebAuthn), `hash_algo` (VARCHAR, e.g. `'argon2id'`), and `hash_cost` (INTEGER, the work factor at hash time). This track's concrete decision against those columns:
13	
14	- **`hash_algo = 'argon2id'`**, per OWASP's and NIST SP 800-63B's current recommendation for password storage. bcrypt is the documented fallback (`hash_algo = 'bcrypt'`) only if the Go implementation's Argon2id library support is unavailable in the chosen stack — a call for `03-engineering-delivery` to confirm, not a reason to default to bcrypt speculatively.
15	- **Salt handling**: no separate salt column is needed or wanted. Argon2id's standard encoded output (the `«REDACTED-ARGON2»` PHC string format) embeds a fresh random salt per row inside the `secret` column's own text — this is what makes the hash self-describing and rehashable without a side lookup. Do not add a `salt` column; it would be redundant with the encoded format and an easy place for an implementation to accidentally desync salt from hash.
16	- **`hash_cost` at minimum**: memory ≥19 MiB, iterations ≥2, parallelism ≥1 (OWASP's Argon2id floor) — recorded per-row (not just globally) specifically so a future cost bump can be applied to newly-created/rotated rows without forcing every existing row to rehash in lockstep, per the schema's own stated intent of supporting an in-place scheme upgrade.
17	- **`requires_secret = false` rows** (passkey/WebAuthn, `secret IS NULL`): no hashing question at all — the server holds only public key material for those methods, which is a different asset class (public, not secret) and does not belong in `secret`/`hash_algo`/`hash_cost` at all if/when a passkey method is actually added. Flagged here so `03-engineering-delivery` doesn't try to force a WebAuthn public key through the password-hashing path.
18	3. **LoginID's own business is passwordless/FIDO2-based authentication.** The assignment nonetheless asks for a `password` field in `user_credential`. I treat that as a deliberate test of whether the submitter still applies correct secret-handling discipline to a legacy-shaped requirement, not as license to under-engineer it. Noted once here; not re-litigated per section.
19	4. **No real infrastructure exists yet.** This is a design-time threat model for a take-home, not an audit of a running system. Findings are stated as requirements the engineering track (`../03-engineering-delivery/CLAUDE.md`) must implement, not as "confirmed" vulnerabilities.
20	5. **Trust boundary**: this service is the system of record for `user_profile`/`user_credential` and is a *client* of third-party IDPs (ABC/XYZ) for `/auth` and `/identity`. Those vendors are outside our control; we can only constrain what we do with what they return.
21	6. **Trust boundary — deployment operator.** The design-only deployment target (`../04-infra-devops/`) is a Kubernetes lab cluster whose manifests would be applied by an external operator agent. Whoever can apply a manifest can read any Secret it mounts, so "secrets are safe once they are in the cluster" is an assumption about that operator, not a property of the design. Consequence, set as a requirement in `handoff-04-secrets.md`: manifests carry Secret names, never values; values are provisioned out-of-band; the operator's rights are documented, not hidden. Nothing is deployed and the operator is never contacted during this take-home.
22	
23	## Method: STRIDE per asset, attacker-centric
24	
25	I'm using STRIDE (Microsoft, but the categories are now common vocabulary in the field — not claiming Anthropic or LoginID provenance for the framework itself) as the checklist, but organized by asset rather than by data flow diagram element, since that maps directly onto this track's ownership boundaries.
26	
27	### Asset 1: `user_credential` (password + other auth methods)
28	
29	| Threat | Scenario | Mitigation (this track's requirement) |
30	|---|---|---|
31	| **Information disclosure** — password store compromise | DB dump or SQL injection exposes the `password` column | Never store plaintext or reversibly-encrypted passwords. Argon2id (OWASP Password Storage Cheat Sheet current recommendation, memory-hard, GPU-resistant) with per-row random salt, tuned to ≥19 MiB memory / ≥2 iterations as a floor, re-tuned to the deploying hardware. bcrypt is an acceptable fallback only if Argon2id is unavailable in the chosen Go stack. |
32	| **Information disclosure** — non-password methods | A WebAuthn public key or TOTP shared secret is not a password, but the table conflates them under one `password` column name | Method-aware storage: WebAuthn credential public keys are not secrets and can be stored in the clear (they're public keys by design) but the associated counter and credential ID must not be attacker-writable; TOTP shared secrets ARE secrets and must be encrypted at rest (not hashed — the server needs to recover the value to verify), using envelope encryption with a KMS-held key, mechanics owned by `../04-infra-devops/CLAUDE.md`. |
33	| **Elevation of privilege** — credential stuffing / brute force | Attacker replays leaked username/password pairs against `/auth`-adjacent endpoints | Rate limiting and progressive backoff per username and per source IP; account lockout or step-up challenge after a threshold; never reveal via response timing or error text whether the *username* or the *password* was wrong (user enumeration). |
34	| **Tampering** | Attacker modifies `method` or the credential row to downgrade a user from a strong method (WebAuthn) to a weak one (password) they control | Method changes/additions require re-authentication with an *existing* registered method (step-up), never a bare authenticated-session write. |
35	| **Repudiation** | No record of who created/rotated a credential | Audit log of credential creation/rotation events (actor, timestamp, method type — never the secret itself). |
36	
37	### Asset 2: `user_profile` (name, address, phone — PII)
38	
39	| Threat | Scenario | Mitigation |
40	|---|---|---|
41	| **Information disclosure via the search API** | Question 2 asks for "search and retrieve." An authenticated-but-unscoped search endpoint is a PII enumeration engine — an attacker with any valid token can page through the entire user table by name/phone fragments | Search must be authorization-scoped (a caller sees only records it's entitled to, not the whole table) and rate-limited/paginated; see `api-auth-design.md` for the concrete authz model. This is the single highest-severity finding in this document, precisely because it's easy to build the search feature "to spec" and miss that spec implies a data-exfiltration primitive. |
42	| **Information disclosure in transit** | PII served over an unencrypted or downgradable channel | TLS 1.2+ mandatory, HSTS, no plaintext fallback. Mechanics of certificate issuance are `04-infra-devops`'s call; the requirement is this track's. |
43	| **Information disclosure via logs** | PII (address, phone) written to application logs, error traces, or APM breadcrumbs | Structured logging with an explicit PII-field denylist; log the *fact* of a profile access (who, when, which record id) never the field values themselves. |
44	| **Tampering** | Unauthorized profile field modification | Same authz model as read access; write operations additionally require the resource owner or an admin-scoped credential, not just "any authenticated caller." |
45	
46	### Asset 3: Third-party `access_token` (from the IDP connector, question 3)
47	
48	| Threat | Scenario | Mitigation |
49	|---|---|---|
50	| **Information disclosure** — token at rest | `access_token` from ABC/XYZ cached or persisted in plaintext | Treat it as a secret with the same bar as our own credentials: encrypted at rest if persisted at all, short TTL, never written to application logs (a full request/response log of `/auth` is an anti-pattern — vendor password *and* resulting token both land in the same log line). |
51	| **Information disclosure** — token in transit / replay | Token intercepted and replayed against the vendor or against us | Vendor calls over TLS only; tokens treated as bearer secrets — anyone holding one can act as us to the vendor, so token scope should be minimized to `/identity` only if the vendor's API supports scoped tokens. |
52	| **Spoofing** | A malicious or compromised proxy sits between us and ABC/XYZ | Certificate validation not disabled "for convenience" in any environment, including local dev — a design note the engineering track should carry into implementation. |
53	| **Denial of service via credential exhaustion** | Our own credentials to call ABC/XYZ (needed to obtain the `access_token` in the first place) are hardcoded or checked into source | Secrets management is `04-infra-devops`'s mechanism, but the requirement — never in source, never in a committed config file, injected at runtime — is set here. |
54	
55	## What this track deliberately does not resolve
56	
57	- How long a cached `/identity` result may be retained — that's data governance (`../05-data-ops/CLAUDE.md`).
58	- Which specific secrets manager or KMS product is used — that's `../04-infra-devops/CLAUDE.md`; I only require that one exists and that secrets never live in source or plaintext config.
59	- Whether the product should offer passwordless auth as the primary path (it should, per LoginID's own market position, and `../01-product-industry-research-design/CLAUDE.md` makes that case) — that's product framing, not a threat.
60	
61	## Sources
62	
63	- OWASP Password Storage Cheat Sheet (Argon2id as current default recommendation): https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html
64	- OWASP API Security Top 10 (particularly API1:2023 Broken Object Level Authorization and API3:2023 Broken Object Property Level Authorization — both directly relevant to the search/retrieve endpoint finding above): https://owasp.org/API-Security/editions/2023/en/0x11-t10/
65	- STRIDE threat modeling categories, Microsoft: https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats
66	

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

diff --git a/cmd/api-service/main.go b/cmd/api-service/main.go
index d884151..dc63793 100644
--- a/cmd/api-service/main.go
+++ b/cmd/api-service/main.go
@@ -24,7 +24,7 @@ func main() {
 	}
 
 	log.Printf("api-service: mode=%s listening on %s", cfg.AppMode, addr)
-	if err := http.ListenAndServe(addr, app.NewRouter("api-service")); err != nil {
+	if err := http.ListenAndServe(addr, app.NewRouter("api-service", cfg.AppMode)); err != nil {
 		log.Fatalf("api-service: %v", err)
 	}
 }
diff --git a/cmd/idp-connector/main.go b/cmd/idp-connector/main.go
index 424df32..ae72c9b 100644
--- a/cmd/idp-connector/main.go
+++ b/cmd/idp-connector/main.go
@@ -24,7 +24,10 @@ func main() {
 	}
 
 	log.Printf("idp-connector: listening on %s", addr)
-	if err := http.ListenAndServe(addr, app.NewRouter("idp-connector")); err != nil {
+	// idp-connector has no issuer/verifier split (LT-32 only touches
+	// api-service, per that story's non-goals) — always ModeVerifier, the
+	// mode that adds no route beyond /healthz.
+	if err := http.ListenAndServe(addr, app.NewRouter("idp-connector", app.ModeVerifier)); err != nil {
 		log.Fatalf("idp-connector: %v", err)
 	}
 }
diff --git a/internal/app/app.go b/internal/app/app.go
index ad1dfd7..9762413 100644
--- a/internal/app/app.go
+++ b/internal/app/app.go
@@ -22,15 +22,47 @@ type healthResponse struct {
 	Build   string `json:"build"`
 }
 
-// NewRouter builds the http.Handler shared by both binaries' main.go. service
-// identifies which binary is answering ("api-service" or "idp-connector") in
-// the health response, per LT-34's acceptance criteria.
-func NewRouter(service string) http.Handler {
+// ModeVerifier and ModeIssuer are api-service's two run modes (LT-32),
+// selected by config.Config.AppMode and passed to NewRouter by cmd/
+// api-service/main.go. idp-connector has no issuer/verifier split — its
+// main.go passes ModeVerifier, the only mode that adds no route beyond
+// /healthz, since that value is also this package's harmless default.
+const (
+	ModeVerifier = "verifier"
+	ModeIssuer   = "issuer"
+)
+
+// NewRouter builds the http.Handler shared by both binaries' main.go.
+// service identifies which binary is answering ("api-service" or
+// "idp-connector") in the health response, per LT-34's acceptance
+// criteria. mode is api-service's APP_MODE (LT-32) — the router itself is
+// this story's startup-time branch point named in refinement/LT-32.md's
+// acceptance criteria ("internal/app branches on it at startup"): in
+// ModeIssuer, a placeholder route is registered at the path reserved for
+// token issuance so the issuer and verifier Deployments are demonstrably
+// different routers, not just different env vars read by code that
+// otherwise behaves identically. The actual issuance handler is S7/LT-40's
+// scope, not this story's (refinement/LT-32.md's non-goals) — this only
+// proves the wiring exists and is reachable on the Deployment that is
+// supposed to have it, and absent on the one that isn't.
+func NewRouter(service string, mode string) http.Handler {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/healthz", healthHandler(service))
+	if mode == ModeIssuer {
+		mux.HandleFunc("/auth/token", issuerPlaceholderHandler)
+	}
 	return mux
 }
 
+// issuerPlaceholderHandler exists only to make the issuer/verifier router
+// split observable and testable before S7/LT-40 implements real token
+// issuance. It deliberately does no cryptography and holds no reference to
+// config.Config.JWTSigningKeyPath — that wiring belongs to whichever S7
+// handler replaces this one.
+func issuerPlaceholderHandler(w http.ResponseWriter, r *http.Request) {
+	http.Error(w, "token issuance not yet implemented — reserved for LT-40", http.StatusNotImplemented)
+}
+
 func healthHandler(service string) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
diff --git a/internal/app/app_test.go b/internal/app/app_test.go
index 3a1d002..8997fd5 100644
--- a/internal/app/app_test.go
+++ b/internal/app/app_test.go
@@ -12,7 +12,7 @@ import (
 func TestHealthz(t *testing.T) {
 	Commit = "abc123"
 
-	srv := httptest.NewServer(NewRouter("api-service"))
+	srv := httptest.NewServer(NewRouter("api-service", ModeVerifier))
 	defer srv.Close()
 
 	resp, err := http.Get(srv.URL + "/healthz")
@@ -49,3 +49,46 @@ func TestHealthz(t *testing.T) {
 		}
 	}
 }
+
+// TestNewRouter_IssuerModeAddsTokenRoute is LT-32's acceptance-criteria
+// enforcement site for "internal/app branches on it at startup": the
+// issuer and verifier routers must be demonstrably different handlers, not
+// just two identical routers reading a value neither acts on.
+func TestNewRouter_IssuerModeAddsTokenRoute(t *testing.T) {
+	srv := httptest.NewServer(NewRouter("api-service", ModeIssuer))
+	defer srv.Close()
+
+	resp, err := http.Post(srv.URL+"/auth/token", "application/json", nil)
+	if err != nil {
+		t.Fatalf("POST /auth/token: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	// 501, not 404: the route must exist and be reachable on the issuer
+	// router even though S7/LT-40 hasn't implemented real issuance yet —
+	// a 404 here would mean the route isn't actually wired.
+	if resp.StatusCode != http.StatusNotImplemented {
+		t.Errorf("status = %d, want %d (route must exist on the issuer router)", resp.StatusCode, http.StatusNotImplemented)
+	}
+}
+
+// TestNewRouter_VerifierModeHasNoTokenRoute is the other half of the same
+// criterion: the verifying router — the one actually deployed as
+// api-service, per LT-32's physical-absence requirement — must not expose
+// the issuance route at all, not even as a 501. A 404 here is the correct
+// outcome, mirroring "physically absent, not just RBAC-denied" one layer
+// up, at the HTTP surface rather than the Kubernetes manifest.
+func TestNewRouter_VerifierModeHasNoTokenRoute(t *testing.T) {
+	srv := httptest.NewServer(NewRouter("api-service", ModeVerifier))
+	defer srv.Close()
+
+	resp, err := http.Post(srv.URL+"/auth/token", "application/json", nil)
+	if err != nil {
+		t.Fatalf("POST /auth/token: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusNotFound {
+		t.Errorf("status = %d, want %d (verifier router must not expose the issuance route)", resp.StatusCode, http.StatusNotFound)
+	}
+}
diff --git a/internal/config/config.go b/internal/config/config.go
index 604173d..ab6decf 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -13,9 +13,17 @@ import (
 // boundaries section. Fields unused by S1's stub handlers are still loaded
 // here so later stories don't have to touch this package's shape again.
 type Config struct {
-	AppMode  string // "verifier" (default) | "issuer"
+	AppMode  string // "verifier" (default) | "issuer" — see LT-32
 	HTTPAddr string
 
+	// JWTSigningKeyPath is the file path to the JWT signing private key
+	// (handoff-04-secrets.md row #2 — "runtime-injected as a file, never
+	// an env var"). Only meaningful when AppMode == "issuer"; empty in
+	// verifier mode, since the verifying Deployment's pod spec never
+	// mounts this Secret at all (LT-32's physical-absence criterion) and
+	// therefore has no path set to point at.
+	JWTSigningKeyPath string
+
 	DBDriver string // postgres | cockroachdb | sqlite
 	DBDSN    string // resolved value: DB_DSN_FILE content takes precedence over DB_DSN
 
@@ -35,6 +43,21 @@ type Config struct {
 // is read and its trimmed content used as DBDSN in preference to DB_DSN —
 // DB_DSN is a transitional fallback, not a permanent equal option, per
 // handoff-04-secrets.md's S7 revision.
+//
+// APP_MODE is validated, not merely defaulted: an unrecognized value is a
+// startup error rather than a silent fall-through to "verifier", because a
+// typo'd issuer Deployment silently running as a verifier (or vice versa)
+// is exactly the class of misconfiguration LT-32 exists to make loud
+// instead of invisible.
+//
+// In issuer mode, JWT_SIGNING_KEY_FILE must be set and the file it names
+// must actually be readable, checked here at startup rather than deferred
+// to whatever first tries to use it. This is LT-32's defense-in-depth
+// criterion: the verifying Deployment's pod spec never mounts this Secret
+// at all (enforced on 04's side, by physical absence, not by this check),
+// so if APP_MODE were ever misconfigured to "issuer" on that Deployment,
+// this still fails startup rather than serving traffic in a half-issuer
+// state with no actual path to the private key.
 func Load() (Config, error) {
 	dsn, err := resolveDSN()
 	if err != nil {
@@ -45,10 +68,19 @@ func Load() (Config, error) {
 	if appMode == "" {
 		appMode = "verifier"
 	}
+	if appMode != "verifier" && appMode != "issuer" {
+		return Config{}, fmt.Errorf("config: APP_MODE %q is not one of \"verifier\", \"issuer\"", appMode)
+	}
+
+	signingKeyPath, err := resolveSigningKeyPath(appMode)
+	if err != nil {
+		return Config{}, err
+	}
 
 	return Config{
-		AppMode:  appMode,
-		HTTPAddr: os.Getenv("HTTP_ADDR"),
+		AppMode:           appMode,
+		JWTSigningKeyPath: signingKeyPath,
+		HTTPAddr:          os.Getenv("HTTP_ADDR"),
 
 		DBDriver: os.Getenv("DB_DRIVER"),
 		DBDSN:    dsn,
@@ -66,6 +98,31 @@ func Load() (Config, error) {
 	}, nil
 }
 
+// resolveSigningKeyPath enforces LT-32's issuer-mode requirement: in
+// "issuer" mode, JWT_SIGNING_KEY_FILE must name a file this process can
+// actually open, checked now rather than left for whatever code first
+// tries to sign a token — a startup failure here is the only thing that
+// distinguishes "issuer mode with no key" from "issuer mode with a key",
+// and the whole point of the physical-absence criterion is that those two
+// must never be confused for one another. In "verifier" mode the variable
+// is not read at all: the verifying binary has no legitimate use for a
+// signing-key path, set or not.
+func resolveSigningKeyPath(appMode string) (string, error) {
+	if appMode != "issuer" {
+		return "", nil
+	}
+	path := os.Getenv("JWT_SIGNING_KEY_FILE")
+	if path == "" {
+		return "", fmt.Errorf("config: APP_MODE=issuer requires JWT_SIGNING_KEY_FILE to be set")
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return "", fmt.Errorf("config: APP_MODE=issuer set but JWT_SIGNING_KEY_FILE %q is not readable: %w", path, err)
+	}
+	_ = f.Close()
+	return path, nil
+}
+
 func resolveDSN() (string, error) {
 	if path := os.Getenv("DB_DSN_FILE"); path != "" {
 		b, err := os.ReadFile(path)
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 715488d..07d3b07 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -53,3 +53,88 @@ func TestLoad_AppModeDefault(t *testing.T) {
 		t.Errorf("AppMode = %q, want %q (default when APP_MODE is unset)", got, want)
 	}
 }
+
+// TestLoad_AppModeRejectsUnknownValue is LT-32's guard against a typo'd
+// APP_MODE silently falling through to verifier (or being misread as
+// issuer) — a startup error here, per Load's own doc comment, rather than
+// a silent default.
+func TestLoad_AppModeRejectsUnknownValue(t *testing.T) {
+	t.Setenv("APP_MODE", "verifyer") // deliberate typo
+
+	if _, err := Load(); err == nil {
+		t.Fatal("Load should reject an unrecognized APP_MODE value, got nil error")
+	}
+}
+
+// TestLoad_IssuerModeRequiresSigningKeyFile is LT-32's core enforcement
+// site for "the api-service (verifying) Deployment holds only the public
+// key material needed to verify, never the private key, regardless of
+// APP_MODE's runtime value": issuer mode with JWT_SIGNING_KEY_FILE unset
+// must fail startup rather than run with no key at all. This is the case
+// that would occur if the verifying Deployment's pod spec (which never
+// sets this variable, per its manifest) had APP_MODE misconfigured to
+// "issuer" — this test proves that misconfiguration crashes the process
+// instead of silently serving as an unkeyed issuer.
+func TestLoad_IssuerModeRequiresSigningKeyFile(t *testing.T) {
+	t.Setenv("APP_MODE", "issuer")
+	t.Setenv("JWT_SIGNING_KEY_FILE", "")
+
+	if _, err := Load(); err == nil {
+		t.Fatal("Load should reject APP_MODE=issuer with JWT_SIGNING_KEY_FILE unset, got nil error")
+	}
+}
+
+// TestLoad_IssuerModeRequiresSigningKeyFileToBeReadable covers the
+// physical-absence half of the same criterion from the opposite
+// direction: JWT_SIGNING_KEY_FILE pointing at a path that does not exist
+// (the exact shape of "the Secret volume was never mounted") must also
+// fail startup, not just an unset variable.
+func TestLoad_IssuerModeRequiresSigningKeyFileToBeReadable(t *testing.T) {
+	t.Setenv("APP_MODE", "issuer")
+	t.Setenv("JWT_SIGNING_KEY_FILE", filepath.Join(t.TempDir(), "does-not-exist"))
+
+	if _, err := Load(); err == nil {
+		t.Fatal("Load should reject APP_MODE=issuer with an unreadable JWT_SIGNING_KEY_FILE, got nil error")
+	}
+}
+
+// TestLoad_IssuerModeWithSigningKeyFileSucceeds is the positive case: a
+// real issuer Deployment, with the Secret actually mounted, must start
+// cleanly and report the path back on Config.
+func TestLoad_IssuerModeWithSigningKeyFileSucceeds(t *testing.T) {
+	dir := t.TempDir()
+	keyPath := filepath.Join(dir, "signing.key")
+	if err := os.WriteFile(keyPath, []byte("fake-key-material"), 0o600); err != nil {
+		t.Fatalf("writing fake signing key: %v", err)
+	}
+
+	t.Setenv("APP_MODE", "issuer")
+	t.Setenv("JWT_SIGNING_KEY_FILE", keyPath)
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load returned error: %v", err)
+	}
+	if cfg.JWTSigningKeyPath != keyPath {
+		t.Errorf("JWTSigningKeyPath = %q, want %q", cfg.JWTSigningKeyPath, keyPath)
+	}
+}
+
+// TestLoad_VerifierModeIgnoresSigningKeyFile asserts the verifying binary
+// never surfaces a signing-key path on Config even if the variable
+// happens to be set in its environment (e.g. a stray value left over from
+// a shared env template) — Config.JWTSigningKeyPath is the only thing
+// anything downstream could use to find the private key, so it must be
+// empty whenever AppMode is not "issuer", unconditionally.
+func TestLoad_VerifierModeIgnoresSigningKeyFile(t *testing.T) {
+	t.Setenv("APP_MODE", "verifier")
+	t.Setenv("JWT_SIGNING_KEY_FILE", "/should/never/be/read")
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load returned error: %v", err)
+	}
+	if cfg.JWTSigningKeyPath != "" {
+		t.Errorf("JWTSigningKeyPath = %q, want empty in verifier mode regardless of the env var", cfg.JWTSigningKeyPath)
+	}
+}

{
  "command": "cat handoff-03-auth.md 2>/dev/null | head -150; echo ---; cat handoff-04-secrets.md 2>/dev/null | head -150"
}

<persisted-output>
Output too large (33.7KB). Full output saved to: /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/tool-results/bj3y2q125.txt

Preview (first 2KB):
# Hand-off 02 → 03: Auth scheme, validation point, and authorization requirements

Status: **v3** — updated after the cross-track consistency pass (`../decisions/cross-track-consistency.md`) resolved six findings owned by this track that touched this hand-off (F3, F5, F6, F8, F10, F-pag, F52); v2's S8-driven fixes are unchanged and folded in below as before. Receiver: Renata Cole, `../03-engineering-delivery/`. Written so 03 should be able to scaffold and build the middleware without re-deriving the reasoning in `api-auth-design.md`, `connector-security.md`, or the S3/S4/S8 decision records. Full reasoning, if wanted: `api-auth-design.md`, `decisions/search-authz-scoping.md`, `decisions/connector-token-lifecycle-redblue.md`.

## Token scheme

- **Grant type:** OAuth2 client-credentials. Machine-to-machine only; no end-user login flow for question 2's API.
- **Token format:** JWT, signed, asymmetric (RS256 or ES256 — pick one and use it consistently; RS256 is the safer default if your Go JWT library's ES256 support is less mature).
- **Claim set (minimum):** `sub` (calling client identity), `scope` (space-delimited, values below), `exp`, `iat`, `aud` (this API, specifically — reject tokens minted for another audience).
- **Literal values, filling the "pending 02's final scheme" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = "https://auth.loginid-takehome.internal"`, `AUTH_JWT_AUDIENCE = "loginid-api-service"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3.
- **TTL:** 5–15 minutes. No refresh tokens — the client re-authenticates with its own client secret on expiry.
- **No denylist.** Revocation is handled by TTL shortness, not a stateful lookup. Don't build one; it's not missing, it's a deliberate trade-off already reasoned through in `api-auth-design.md`.
...
</persisted-output>

{
  "command": "grep -n -i \"kid\\|rotat\\|key retrieval\\|JWT_SIGNING\\|signing key\\|APP_MODE\\|issuer\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md"
}

/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md:10:- **Literal values, filling the "pending 02's final scheme" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = "https://auth.loginid-takehome.internal"`, `AUTH_JWT_AUDIENCE = "loginid-api-service"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3.
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md:20:- **Key retrieval:** middleware verifies with the **public** key only (JWKS or a fetched public key — see `handoff-04-secrets.md` row #3). The private signing key never touches the verifying `api-service` Deployment; it lives with the token-issuing function, which is a mode of the same `api-service` image but runs as its **own Deployment** (`APP_MODE=issuer`, its own ServiceAccount), not the same Deployment doing both (corrected in `handoff-04-secrets.md` Assumption 2 and row #2, F13 — RBAC on a Secret's `get` verb doesn't stop a volume already mounted into a shared Deployment's containers, so the separation has to be a second Deployment, not RBAC alone). This is a second `APP_MODE` value for you to wire alongside your existing config surface.
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md:21:- **Key rotation:** expect a `kid` claim; publish old and new public keys together during rotation overlap. Token TTL (5–15 min) bounds how long that overlap needs to last.
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:8:2. Service topology is 03's published boundary (`../PLANNING.md`, Service boundaries): two binaries, `cmd/api-service` (Q1 DAO + Q2 REST API) and `cmd/idp-connector` (Q3), env-var configuration only. Variable names below are 03's; two are marked as pending this track's final scheme. **The token-issuing authorization-server function is a mode of `api-service`, not a third binary** — this take-home's scope doesn't justify a standalone authz server, and 03 has published no third `cmd/` entrypoint. **Corrected by the cross-track consistency pass (F13):** "a mode of the same binary" is not "the same Kubernetes Deployment," and the earlier text here was wrong to imply RBAC alone separates them — a Kubernetes Role restricting `get` on a Secret has no effect on a volume already mounted into a container, so if `api-service`'s one Deployment mounted the signing key, every replica (verification path included) would have it on disk regardless of RBAC. **The fix: the issuer runs as a second Deployment of the same `api-service` image**, selected by an environment variable 03 adds to the config surface (e.g. `APP_MODE=issuer` vs. the default, consistent with the surface's env-var-only, no-flags rule), with **its own ServiceAccount that alone mounts the signing-key Secret** (row #2) — the `api-service` Deployment serving verification/search mounts nothing from row #2. This is a request into 03's Deployment/mode surface, not a unilateral change on my part; flag to me if the mode-selection mechanism needs to differ.
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:14:| # | Secret | Used by | Injection requirement (02 sets it) | Rotation expectation | Kubernetes-native note (04's mechanism) | Never-log |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:16:| 1 | Database credentials, carried inside `DB_DSN` | `api-service` | Runtime-injected; never in source, image, or committed config. **Required, not preferred: file mount via a `DB_DSN_FILE` convention** (03 to add alongside `DB_DSN`), because a DSN's embedded password is exposed by `kubectl describe`, crash dumps, and child-process environment exactly as much as any other secret in this table — there is no citation that makes `DB_DSN` a lesser case, so this track is not treating it as one | On credential rotation; service restart or reload acceptable | `Secret` mounted read-only as a file, read via `DB_DSN_FILE`; env-var `DB_DSN` is a fallback only until 03 ships the file-based convention, not a permanent equal option | Yes — the DSN contains the password; log the driver name and host at most |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:17:| 2 | JWT signing **private** key (RS256/ES256), per `api-auth-design.md` | The issuer Deployment (`api-service` image, `APP_MODE=issuer`) only — **not** the `api-service` Deployment that verifies with the public key; these are two Deployments of one image, not one Deployment doing both (F13 fix) | Runtime-injected as a **file**, never an env var; asymmetric so the verifying Deployment never holds it | Key rotation with a `kid` claim; publish old and new public keys together during overlap; TTL of tokens (5–15 min) bounds the overlap window | `Secret` mounted read-only as a file, **only into the issuer Deployment's pod spec** (not the verifying Deployment's); RBAC restricts `get`/`list` to the issuer's own ServiceAccount | Yes |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:18:| 3 | JWT **public** key / JWKS | `api-service` middleware | Not a secret; may ship in config or be fetched from the issuer | Follows #2 | Plain `ConfigMap` or fetched URL; listed here so 04 does not over-protect it | No (but never log full tokens — see below) |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:19:| 4 | API caller `client_secret`s (OAuth2 client-credentials) | Authorization server (verifies); callers hold their own copy | **Stored hashed** (Argon2id, same floor as `threat-model.md` Asset 1), never plaintext at rest; issued once at provisioning and not recoverable | Per-client rotation on demand; revoke by deleting the hash | Lives in the issuer's datastore, not a Kubernetes `Secret`; 04 delivers only that datastore's credentials (#1-shaped) | Yes |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:20:| 5 | Connector's own vendor registration: `IDP_ABC_CLIENT_ID`, `IDP_ABC_CLIENT_SECRET` (and the XYZ pair if a second vendor is configured) | `idp-connector` | Runtime-injected; never in source or committed config; `client_id` is low-sensitivity but travels with the secret and gets the same handling | Per vendor's policy; expect manual rotation | One `Secret` per vendor so rotating ABC never touches XYZ; file mount preferred | Yes for the secret; keep the id out of logs too |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:22:| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets | `api-service` (TOTP) only — **not a committed feature of this submission**; `user_credential.method` is modeled as an extensible lookup table (`../05-data-ops/multi-db-strategy.md`) that supports TOTP as a *possible* value, but no TOTP implementation is planned unless 03 builds one. **The vendor-token-cache use case for this row no longer exists**: S3's red/blue on the connector token lifecycle is closed (`decisions/connector-token-lifecycle-redblue.md`) — no cache by default, and the token is never held by the connector between calls at all under F3's model (row 6), so there is no vendor-token cache for a KEK to encrypt. This row is provisioned only if TOTP materializes — it is a contingency the inventory names in advance, not a live requirement for 04 to build now | Runtime-injected as a file; the KEK never leaves the process that decrypts | Rotation by re-wrapping DEKs; never requires re-hashing passwords (those are hashed, not encrypted) | `Secret` (file mount) or an external KMS if 04 prefers — the requirement is only that a KEK exists and is not in source | Yes |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:23:| 7a | Credential to reach the external KMS, **only if 04 exercises the KMS alternative in row #7** (a role, API key, or client cert — whichever the chosen KMS uses) | Whichever binary holds the KEK reference (#7) | Same discipline as every other row here: runtime-injected, never in source, never provisioned ad hoc outside this table | Per the KMS provider's own rotation mechanism | Cloud-KMS access is typically workload-identity-based (no static credential to store) rather than a `Secret` object; if the chosen KMS instead requires a static credential, it gets its own `Secret` under the same RBAC discipline as row #2 | Yes |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:26:| 10 | `api-service`'s own client credential (`client_id`/`client_secret`) toward the issuer, scoped `connector:identity-lookup`/`aud: idp-connector-service` — required for `api-service` to call `idp-connector`'s own authenticated `/auth`/`/identity` (`connector-security.md` §5) | `api-service` (the Deployment serving question 2's API, acting as a caller of the connector on a user's behalf) | Runtime-injected; never in source or committed config — same discipline as row 5's vendor registration, added by the cross-track consistency pass (F15), which found this credential asserted as a requirement in `connector-security.md`/`handoff-03-auth.md` with no inventory row | Same per-client rotation as row 4 (revoke by deleting the issuer-side hash) | File mount, one `Secret`, `api-service`'s own ServiceAccount | Yes |
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:28:Names marked pending in 03's boundary: `AUTH_JWT_ISSUER` / `AUTH_JWT_AUDIENCE` are configuration, not secrets; this track will confirm their final values in `handoff-03-auth.md`. They are listed here only so 04 does not classify them as secrets.
/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md:46:5. JWT signing private key (#2) and any JWT in full — log `sub`, `aud`, `exp`, and `kid` if needed, never the token.

{
  "command": "grep -n -i \"auth/token\\|/token\\b\\|endpoint\\|route\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md | head -30"
}

14:- **Token-endpoint brute-force protection**, separate from the resource-API rate limits below: 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 protects the endpoint where a caller presents `client_id`/`client_secret`, which none of the resource-API limits below cover.
23:## Health endpoints (ruling, not open for re-litigation)

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

{"name": "Helena Marsh", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

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

<persisted-output>
Output too large (72.8KB). Full output saved to: /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/tool-results/bva81bzyv.txt

Preview (first 2KB):
diff --git a/cmd/api-service/main.go b/cmd/api-service/main.go
index 636be6d..94e6fc9 100644
--- a/cmd/api-service/main.go
+++ b/cmd/api-service/main.go
@@ -5,13 +5,20 @@
 package main
 
 import (
+	"database/sql"
 	"log"
 	"net/http"
 
+	"loginid-takehome/internal/api"
 	"loginid-takehome/internal/app"
 	"loginid-takehome/internal/config"
 	"loginid-takehome/internal/dao"
 
+	// internal/dao/postgres's own blank import of pgx/v5/stdlib already
+	// registers the "pgx" database/sql driver this file uses directly
+	// for the issuer database below — Go dedupes an import by package
+	// path, so this isn't a second registration, and no separate blank
+	// import of that package is needed here.
 	_ "loginid-takehome/internal/dao/postgres" // registers "postgres" and "cockroachdb"
 	_ "loginid-takehome/internal/dao/sqlite"   // registers "sqlite"
 )
@@ -51,12 +58,43 @@ func main() {
 			repo = nil
 		}
 		handler = app.NewVerifierRouter(cfg, repo)
+	case app.ModeIssuer:
+		// config.Load already fails startup if JWT_SIGNING_KEY_FILE is
+		// missing/unreadable in issuer mode (resolveSigningKeyPath) —
+		// LoadSigningKey failing here means the file is readable but not
+		// a valid RSA private key, a genuine misconfiguration this
+		// process cannot usefully run past (there is no "serve /healthz,
+		// fail closed" story for a router with no key at all: both of
+		// its routes need one). Fatal, not degrade — unlike the DAO
+		// repository above, which has a real story for "not there yet."
+		key, err := api.LoadSigningKey(cfg.JWTSigningKeyPath)
+		if err != nil {
+			log.Fatalf("api-service: loading JWT signing key: %v", err)
+		}
+
+		// issuerDB, like the verifier's pingDB, is opened independently
+		// of whether it can be reached yet — sql.Open never dials. Empty
+		// IssuerDBDSN (not configured yet) leaves issuerDB nil;
+		// NewIssuerRouter's /auth/token then fails every grant closed
+		// with server_error rather than panicking on a nil ClientStore.
...
</persisted-output>

{
  "file_path": "/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/tool-results/bva81bzyv.txt"
}

1	diff --git a/cmd/api-service/main.go b/cmd/api-service/main.go
2	index 636be6d..94e6fc9 100644
3	--- a/cmd/api-service/main.go
4	+++ b/cmd/api-service/main.go
5	@@ -5,13 +5,20 @@
6	 package main
7	 
8	 import (
9	+	"database/sql"
10	 	"log"
11	 	"net/http"
12	 
13	+	"loginid-takehome/internal/api"
14	 	"loginid-takehome/internal/app"
15	 	"loginid-takehome/internal/config"
16	 	"loginid-takehome/internal/dao"
17	 
18	+	// internal/dao/postgres's own blank import of pgx/v5/stdlib already
19	+	// registers the "pgx" database/sql driver this file uses directly
20	+	// for the issuer database below — Go dedupes an import by package
21	+	// path, so this isn't a second registration, and no separate blank
22	+	// import of that package is needed here.
23	 	_ "loginid-takehome/internal/dao/postgres" // registers "postgres" and "cockroachdb"
24	 	_ "loginid-takehome/internal/dao/sqlite"   // registers "sqlite"
25	 )
26	@@ -51,12 +58,43 @@ func main() {
27	 			repo = nil
28	 		}
29	 		handler = app.NewVerifierRouter(cfg, repo)
30	+	case app.ModeIssuer:
31	+		// config.Load already fails startup if JWT_SIGNING_KEY_FILE is
32	+		// missing/unreadable in issuer mode (resolveSigningKeyPath) —
33	+		// LoadSigningKey failing here means the file is readable but not
34	+		// a valid RSA private key, a genuine misconfiguration this
35	+		// process cannot usefully run past (there is no "serve /healthz,
36	+		// fail closed" story for a router with no key at all: both of
37	+		// its routes need one). Fatal, not degrade — unlike the DAO
38	+		// repository above, which has a real story for "not there yet."
39	+		key, err := api.LoadSigningKey(cfg.JWTSigningKeyPath)
40	+		if err != nil {
41	+			log.Fatalf("api-service: loading JWT signing key: %v", err)
42	+		}
43	+
44	+		// issuerDB, like the verifier's pingDB, is opened independently
45	+		// of whether it can be reached yet — sql.Open never dials. Empty
46	+		// IssuerDBDSN (not configured yet) leaves issuerDB nil;
47	+		// NewIssuerRouter's /auth/token then fails every grant closed
48	+		// with server_error rather than panicking on a nil ClientStore.
49	+		var issuerDB *sql.DB
50	+		if cfg.IssuerDBDSN != "" {
51	+			issuerDB, err = sql.Open("pgx", cfg.IssuerDBDSN)
52	+			if err != nil {
53	+				log.Printf("api-service: opening issuer database: %v — /auth/token will return server_error until this is resolved", err)
54	+				issuerDB = nil
55	+			}
56	+		} else {
57	+			log.Printf("api-service: ISSUER_DB_DSN/ISSUER_DB_DSN_FILE not set — /auth/token will return server_error until this is resolved")
58	+		}
59	+
60	+		handler = app.NewIssuerRouter(cfg, key, issuerDB)
61	 	default:
62	-		// ModeIssuer (and the unrecognized-mode fallback, which
63	-		// NewRouter itself already logs loudly and treats as verifier —
64	-		// see app.NewRouter's own doc comment) don't need the full
65	-		// verifier stack; NewRouter's existing /auth/token placeholder
66	-		// (LT-32) and /healthz cover both.
67	+		// The unrecognized-mode fallback (NewRouter itself already logs
68	+		// loudly and treats it as verifier — see app.NewRouter's own doc
69	+		// comment) doesn't need the full verifier stack; NewRouter's
70	+		// /healthz alone covers it, matching the safer of the two route
71	+		// sets.
72	 		handler = app.NewRouter("api-service", app.Mode(cfg.AppMode))
73	 	}
74	 
75	diff --git a/go.mod b/go.mod
76	index eaf1188..20a1f16 100644
77	--- a/go.mod
78	+++ b/go.mod
79	@@ -17,9 +17,10 @@ require (
80	 	github.com/mattn/go-isatty v0.0.24 // indirect
81	 	github.com/ncruces/go-strftime v1.0.0 // indirect
82	 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
83	-	golang.org/x/sync v0.22.0 // indirect
84	-	golang.org/x/sys v0.47.0 // indirect
85	-	golang.org/x/text v0.39.0 // indirect
86	+	golang.org/x/crypto v0.57.0 // indirect
87	+	golang.org/x/sync v0.23.0 // indirect
88	+	golang.org/x/sys v0.48.0 // indirect
89	+	golang.org/x/text v0.42.0 // indirect
90	 	modernc.org/libc v1.75.6 // indirect
91	 	modernc.org/mathutil v1.7.1 // indirect
92	 	modernc.org/memory v1.12.1 // indirect
93	diff --git a/go.sum b/go.sum
94	index cf541fe..9225b92 100644
95	--- a/go.sum
96	+++ b/go.sum
97	@@ -32,16 +32,26 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
98	 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
99	 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
100	 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
101	+golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
102	+golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
103	 golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
104	 golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
105	+golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
106	 golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
107	 golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
108	+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
109	+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
110	 golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
111	 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
112	+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
113	+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
114	 golang.org/x/text v0.39.0 h1:UbZz4pLOvn600D6Oh6GGEI6VAmndrEBLv8/6BEXzyus=
115	 golang.org/x/text v0.39.0/go.mod h1:3UwRclnC2g0TU9x8PZiyfOajCd1zaUNHF9cvqcQZ+ZM=
116	+golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
117	+golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
118	 golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
119	 golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
120	+golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
121	 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
122	 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
123	 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
124	diff --git a/internal/api/clientstore.go b/internal/api/clientstore.go
125	new file mode 100644
126	index 0000000..226475d
127	--- /dev/null
128	+++ b/internal/api/clientstore.go
129	@@ -0,0 +1,229 @@
130	+// clientstore.go implements the token-issuer's client store per
131	+// handoff-03-auth.md v6/LT-51: client_id, name, an Argon2id-hashed
132	+// secret (same floor as threat-model.md Asset 1's password hashing),
133	+// granted scope, audience, and status.
134	+//
135	+// Backed by a real, persistent PostgreSQL database — a separate
136	+// "issuer" database (migrations/issuer/00001_initial_schema.sql), not
137	+// an in-process map — per Priya Nandakumar's (05) explicit ruling on
138	+// this story: unlike every other in-process component this track has
139	+// built (RateLimiter, TouchCounter, GrantLimiter), a client credential
140	+// has to survive a pod restart, and the QA client seeded for the PO's
141	+// live-URL review has to be seeded out-of-band (04's runbook), never by
142	+// this application's own code or a migration — "migrations carry
143	+// reference data, never credentials." Lives in its own database, not
144	+// 05's main DAO schema, so a cross-database join to user_profile is
145	+// structurally impossible, not just policy-forbidden (F8 resolution,
146	+// handoff-03-auth.md v3).
147	+package api
148	+
149	+import (
150	+	"context"
151	+	"crypto/rand"
152	+	"crypto/subtle"
153	+	"database/sql"
154	+	"encoding/base64"
155	+	"errors"
156	+	"fmt"
157	+	"strings"
158	+
159	+	"golang.org/x/crypto/argon2"
160	+)
161	+
162	+// Argon2id parameters — one fixed cost profile for every client secret
163	+// (and the fixed dummy hash timing-parity depends on, below). Matches
164	+// threat-home.md Asset 1's own floor: this is not a separate, weaker
165	+// hashing decision for machine credentials, it's the same discipline
166	+// applied to a second credential class.
167	+const (
168	+	argon2Time    = 1
169	+	argon2Memory  = 64 * 1024 // 64 MiB
170	+	argon2Threads = 4
171	+	argon2KeyLen  = 32
172	+	argon2SaltLen = 16
173	+)
174	+
175	+// hashSecret returns an Argon2id hash of secret, encoded as
176	+// "<base64-salt>$<base64-hash>" — self-contained, no separate parameter
177	+// storage needed since every hash in this store uses the same fixed
178	+// profile above.
179	+func hashSecret(secret string) (string, error) {
180	+	salt := make([]byte, argon2SaltLen)
181	+	if _, err := rand.Read(salt); err != nil {
182	+		return "", fmt.Errorf("api: generating salt: %w", err)
183	+	}
184	+	hash := argon2.IDKey([]byte(secret), salt, argon2Time, argon2Memory, argon2Threads, argon2KeyLen)
185	+	return base64.RawStdEncoding.EncodeToString(salt) + "$" + base64.RawStdEncoding.EncodeToString(hash), nil
186	+}
187	+
188	+// verifySecret reports whether secret matches encodedHash, produced by
189	+// hashSecret. Comparison is constant-time (crypto/subtle) — Argon2id's
190	+// own cost already dominates timing versus a plain []byte equality, but
191	+// there is no reason to reintroduce a length/byte-position side channel
192	+// on top of it for free.
193	+func verifySecret(secret, encodedHash string) bool {
194	+	parts := strings.SplitN(encodedHash, "$", 2)
195	+	if len(parts) != 2 {
196	+		return false
197	+	}
198	+	salt, err := base64.RawStdEncoding.DecodeString(parts[0])
199	+	if err != nil {
200	+		return false
201	+	}
202	+	want, err := base64.RawStdEncoding.DecodeString(parts[1])
203	+	if err != nil {
204	+		return false
205	+	}
206	+	got := argon2.IDKey([]byte(secret), salt, argon2Time, argon2Memory, argon2Threads, argon2KeyLen)
207	+	return subtle.ConstantTimeCompare(got, want) == 1
208	+}
209	+
210	+// dummyHash is computed once, at package init, from a fixed (not
211	+// secret — its value doesn't matter, only that it's fixed and uses the
212	+// SAME cost parameters as every real hash) salt and secret. The
213	+// unknown-client_id path in the token handler runs verifySecret against
214	+// this exact value before returning invalid_client, so an unknown
215	+// client_id and a wrong-secret-for-a-known-client_id take
216	+// statistically indistinguishable time (Tobias Lindqvist's objection,
217	+// LT-51 refinement — RFC 6749 §5.2's identical-response-body
218	+// requirement closes the content side channel; this closes the timing
219	+// one, which the body requirement alone leaves wide open).
220	+var dummyHash = mustHashSecret("dummy-fixed-secret-never-issued-to-any-real-client")
221	+
222	+func mustHashSecret(secret string) string {
223	+	h, err := hashSecret(secret)
224	+	if err != nil {
225	+		// Only reachable if crypto/rand itself fails at process start —
226	+		// a condition this process cannot usefully continue past anyway
227	+		// (every real hashSecret call would fail identically).
228	+		panic(fmt.Sprintf("api: computing fixed dummy Argon2id hash: %v", err))
229	+	}
230	+	return h
231	+}
232	+
233	+// ClientRecord is one row in the client store.
234	+type ClientRecord struct {
235	+	ClientID         string
236	+	Name             string // accountability — no shared credentials across a team
237	+	ClientSecretHash string // Argon2id, hashSecret's encoding
238	+	GrantedScope     Scope  // exactly one — see ClientStore's doc comment
239	+	Audience         string // the JWT aud this client's tokens are minted for
240	+	Active           bool
241	+}
242	+
243	+// ClientStore is the token-issuer's client datastore — client
244	+// authentication and scope/audience lookup, keyed by client_id.
245	+//
246	+// GrantedScope is a single Scope, not a set, even though
247	+// handoff-03-auth.md v6 describes "granted_scopes" as a provisioned
248	+// subset of the four possible values: this project's own provisioning
249	+// model (decisions/search-authz-scoping.md; LT-40's singleScope) commits
250	+// to exactly one scope per credential — "a client is provisioned for the
251	+// one use case its credential exists for" — and AuthContext (LT-39)
252	+// carries exactly one Scope per token by the same design. A client
253	+// record holding more than one granted scope would have no way to
254	+// produce a token LT-40's verifier accepts (which rejects a multi-scope
255	+// token outright, deliberately, not an oversight this story should route
256	+// around). So provisioning is one client credential per scope a caller
257	+// needs, not one client holding several — consistent with, not a
258	+// deviation from, the system's existing single-scope-per-token
259	+// commitment.
260	+type ClientStore interface {
261	+	// Get returns the record for clientID, ok=false if no such client
262	+	// exists at all (a different outcome from an inactive client, which
263	+	// Get still returns — the token handler decides what "not usable"
264	+	// means, this interface only reports what's on file).
265	+	Get(ctx context.Context, clientID string) (rec ClientRecord, ok bool, err error)
266	+}
267	+
268	+// PostgresClientStore is a real, persistent ClientStore backed by the
269	+// issuer database's oauth_client table (migrations/issuer/
270	+// 00001_initial_schema.sql). Constructed once at startup from a *sql.DB
271	+// dialed against config.Config.IssuerDBDSN — always the "pgx" driver,
272	+// since the issuer database has no SQLite/CockroachDB peer to abstract
273	+// over (unlike 05's main DAO schema), so this reaches for
274	+// database/sql directly rather than routing through dao.New's
275	+// multi-backend factory, which was never asked to know about this
276	+// table.
277	+type PostgresClientStore struct {
278	+	db *sql.DB
279	+}
280	+
281	+// NewPostgresClientStore wraps an already-opened *sql.DB. Opening (and
282	+// its lifetime) is cmd/api-service/main.go's responsibility, same
283	+// pattern as LT-52's separate /healthz ping handle — this type never
284	+// calls sql.Open itself.
285	+func NewPostgresClientStore(db *sql.DB) *PostgresClientStore {
286	+	return &PostgresClientStore{db: db}
287	+}
288	+
289	+// Get deliberately does not distinguish "no such client_id",
290	+// "provisioned but secret_state != 'set'", or "status = 'disabled'" in
291	+// its ok/err results — all three come back as ok=true with whatever's
292	+// on file (or ok=false only for a genuinely absent row), and it's
293	+// tokenhandler.go's job to decide what counts as usable. This keeps
294	+// every one of those states on the same code path through
295	+// verifySecret/dummyHash, so none of them becomes a second timing
296	+// signal alongside the unknown-client_id one dummyHash already closes.
297	+func (s *PostgresClientStore) Get(ctx context.Context, clientID string) (ClientRecord, bool, error) {
298	+	var rec ClientRecord
299	+	var secretHash sql.NullString
300	+	var scopesRaw string
301	+	var status string
302	+
303	+	row := s.db.QueryRowContext(ctx, `
304	+		SELECT client_id, name, client_secret_hash, granted_scopes, audience, status
305	+		FROM oauth_client
306	+		WHERE client_id = $1
307	+	`, clientID)
308	+	err := row.Scan(&rec.ClientID, &rec.Name, &secretHash, &scopesRaw, &rec.Audience, &status)
309	+	if errors.Is(err, sql.ErrNoRows) {
310	+		return ClientRecord{}, false, nil
311	+	}
312	+	if err != nil {
313	+		return ClientRecord{}, false, fmt.Errorf("api: querying oauth_client: %w", err)
314	+	}
315	+	scopes, err := parsePostgresTextArray(scopesRaw)
316	+	if err != nil {
317	+		return ClientRecord{}, false, fmt.Errorf("api: parsing granted_scopes for %q: %w", clientID, err)
318	+	}
319	+	if len(scopes) != 1 {
320	+		// The migration's own CHECK (ck_oauth_client_granted_scopes_single)
321	+		// makes this unreachable in practice — surfaced as an error rather
322	+		// than silently taking scopes[0] of an empty slice, in case that
323	+		// constraint is ever relaxed without this code being revisited.
324	+		return ClientRecord{}, false, fmt.Errorf("api: oauth_client row %q has %d granted scopes, want exactly 1", clientID, len(scopes))
325	+	}
326	+
327	+	rec.ClientSecretHash = secretHash.String // "" when NULL (secret_state != "set")
328	+	rec.GrantedScope = Scope(scopes[0])
329	+	rec.Active = status == "active"
330	+	return rec, true, nil
331	+}
332	+
333	+// parsePostgresTextArray decodes Postgres's default text output format
334	+// for a TEXT[] column (e.g. "{profile:search}") into its elements. This
335	+// project's own scope values are plain identifiers — letters, digits,
336	+// ":" — never containing a comma, brace, backslash, or double quote, so
337	+// this deliberately does not implement the general Postgres array
338	+// literal grammar (quoted elements, backslash escaping, NULL elements):
339	+// pgx/v5's stdlib driver has no built-in database/sql Scanner for array
340	+// types, and a hand-rolled general parser would be untested complexity
341	+// this table's actual value domain never exercises. Any input outside
342	+// that domain is an error, not a best-effort guess.
343	+func parsePostgresTextArray(raw string) ([]string, error) {
344	+	if len(raw) < 2 || raw[0] != '{' || raw[len(raw)-1] != '}' {
345	+		return nil, fmt.Errorf("not a Postgres array literal: %q", raw)
346	+	}
347	+	inner := raw[1 : len(raw)-1]
348	+	if inner == "" {
349	+		return nil, nil
350	+	}
351	+	elems := strings.Split(inner, ",")
352	+	for _, e := range elems {
353	+		if e == "" || strings.ContainsAny(e, `{}"\`) {
354	+			return nil, fmt.Errorf("unsupported array element %q in %q — only plain unquoted values are supported", e, raw)
355	+		}
356	+	}
357	+	return elems, nil
358	+}
359	diff --git a/internal/api/clientstore_pg_test.go b/internal/api/clientstore_pg_test.go
360	new file mode 100644
361	index 0000000..7f9535c
362	--- /dev/null
363	+++ b/internal/api/clientstore_pg_test.go
364	@@ -0,0 +1,200 @@
365	+package api
366	+
367	+import (
368	+	"context"
369	+	"database/sql"
370	+	"fmt"
371	+	"math/rand"
372	+	"os"
373	+	"path/filepath"
374	+	"strings"
375	+	"testing"
376	+
377	+	_ "github.com/jackc/pgx/v5/stdlib"
378	+)
379	+
380	+// setupIssuerDB connects to TEST_POSTGRES_DSN (skipping the test if
381	+// unset, same discipline as internal/dao/postgres's own setupDB — real
382	+// Postgres verification is this file's responsibility, not something a
383	+// hand-written fake could ever exercise), applies the real
384	+// migrations/issuer/00001_initial_schema.sql into a fresh, uniquely-named
385	+// schema, and tears it down on cleanup.
386	+func setupIssuerDB(t *testing.T) *sql.DB {
387	+	t.Helper()
388	+	dsn := os.Getenv("TEST_POSTGRES_DSN")
389	+	if dsn == "" {
390	+		t.Skip("TEST_POSTGRES_DSN not set — skipping issuer-database integration test")
391	+	}
392	+
393	+	db, err := sql.Open("pgx", dsn)
394	+	if err != nil {
395	+		t.Fatalf("opening TEST_POSTGRES_DSN: %v", err)
396	+	}
397	+	t.Cleanup(func() { _ = db.Close() })
398	+	db.SetMaxOpenConns(1)
399	+
400	+	schemaName := fmt.Sprintf("test_issuer_%d", rand.Int63())
401	+	if _, err := db.Exec("CREATE SCHEMA " + schemaName); err != nil {
402	+		t.Fatalf("creating test schema: %v", err)
403	+	}
404	+	t.Cleanup(func() {
405	+		_, _ = db.Exec("DROP SCHEMA " + schemaName + " CASCADE")
406	+	})
407	+	if _, err := db.Exec("SET search_path TO " + schemaName); err != nil {
408	+		t.Fatalf("setting search_path: %v", err)
409	+	}
410	+
411	+	wd, err := os.Getwd()
412	+	if err != nil {
413	+		t.Fatalf("getwd: %v", err)
414	+	}
415	+	repoRoot := filepath.Join(wd, "..", "..") // this package: <repoRoot>/internal/api
416	+	migrationPath := filepath.Join(repoRoot, "migrations", "issuer",
… truncated (20 KB cap)

{
  "file_path": "/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/tool-results/bva81bzyv.txt",
  "offset": 1121,
  "limit": 760
}

1121	+// Tobias Lindqvist's objection (LT-51 refinement), the endpoint most
1122	+// likely to be pattern-matched against known real-world OAuth2
1123	+// timing-oracle bugs by an outside reviewer.
1124	+package api
1125	+
1126	+import (
1127	+	"encoding/json"
1128	+	"net"
1129	+	"net/http"
1130	+	"strings"
1131	+	"time"
1132	+
1133	+	"github.com/golang-jwt/jwt/v5"
1134	+	"github.com/google/uuid"
1135	+)
1136	+
1137	+// tokenTTL is this issuer's fixed token lifetime — the middle of
1138	+// handoff-03-auth.md's 5-15 minute range. No refresh tokens: a client
1139	+// re-authenticates with its own client secret on expiry, per
1140	+// api-auth-design.md's standing TTL-only-revocation design (this
1141	+// story's own non-goal list; not re-litigated here).
1142	+const tokenTTL = 10 * time.Minute
1143	+
1144	+// tokenErrorResponse is RFC 6749 §5.2's error body shape.
1145	+type tokenErrorResponse struct {
1146	+	Error string `json:"error"`
1147	+}
1148	+
1149	+// tokenResponse is RFC 6749 §5.1's success body shape.
1150	+type tokenResponse struct {
1151	+	AccessToken string `json:"access_token"`
1152	+	TokenType   string `json:"token_type"`
1153	+	ExpiresIn   int    `json:"expires_in"`
1154	+	Scope       string `json:"scope"`
1155	+}
1156	+
1157	+func writeTokenError(w http.ResponseWriter, status int, errCode string) {
1158	+	if status == http.StatusUnauthorized {
1159	+		// RFC 6749 §5.2: invalid_client with a 401 MUST carry
1160	+		// WWW-Authenticate identifying the auth scheme this endpoint
1161	+		// expects — the same header any HTTP Basic-protected resource
1162	+		// returns, not something specific to OAuth2 error semantics.
1163	+		w.Header().Set("WWW-Authenticate", `Basic realm="token"`)
1164	+	}
1165	+	w.Header().Set("Content-Type", "application/json")
1166	+	w.WriteHeader(status)
1167	+	_ = jsonEncode(w, tokenErrorResponse{Error: errCode})
1168	+}
1169	+
1170	+// jsonEncode is a one-line indirection kept trivial and named for
1171	+// clarity rather than inlined at each of this file's two call sites.
1172	+func jsonEncode(w http.ResponseWriter, v any) error {
1173	+	return json.NewEncoder(w).Encode(v)
1174	+}
1175	+
1176	+// NewTokenHandler implements POST /auth/token. deps bundles the
1177	+// collaborators this handler wires to rather than reimplements per
1178	+// refinement/LT-51.md's explicit instruction: store is the client
1179	+// datastore (this story's own, new); limiter is PR #30's already-built
1180	+// GrantLimiter, called exactly as its own doc comment specifies (Allow
1181	+// before authentication, RecordFailure/RecordSuccess after); key is the
1182	+// loaded signing key this story mints tokens with.
1183	+func NewTokenHandler(store ClientStore, limiter GrantLimiter, key *SigningKey, issuer string) http.HandlerFunc {
1184	+	return func(w http.ResponseWriter, r *http.Request) {
1185	+		ctx := r.Context()
1186	+
1187	+		// store is nil when the issuer database was never configured
1188	+		// (config.Config.IssuerDBDSN empty) — fail every grant closed
1189	+		// with server_error rather than panic on a nil ClientStore, the
1190	+		// same fail-closed shape NewVerifierRouter uses for a nil
1191	+		// dao.Repository. This deliberately runs before ParseForm/
1192	+		// BasicAuth so a misconfigured issuer fails identically for
1193	+		// every request shape, not just the ones that get far enough to
1194	+		// reach store.Get.
1195	+		if store == nil {
1196	+			writeTokenError(w, http.StatusInternalServerError, "server_error")
1197	+			return
1198	+		}
1199	+
1200	+		// RFC 6749 §4.4: form-encoded, not JSON. r.ParseForm reads the
1201	+		// body as application/x-www-form-urlencoded regardless of a
1202	+		// caller's declared Content-Type, which is deliberately
1203	+		// permissive here — this handler's job is accepting the one wire
1204	+		// format the spec names, not policing a header a legitimate
1205	+		// client-credentials implementation might send inconsistently.
1206	+		if err := r.ParseForm(); err != nil {
1207	+			writeTokenError(w, http.StatusBadRequest, "invalid_request")
1208	+			return
1209	+		}
1210	+		if r.PostForm.Get("grant_type") != "client_credentials" {
1211	+			writeTokenError(w, http.StatusBadRequest, "unsupported_grant_type")
1212	+			return
1213	+		}
1214	+
1215	+		clientID, clientSecret, hasBasicAuth := r.BasicAuth()
1216	+		if !hasBasicAuth {
1217	+			// No Authorization header at all: reject before ever
1218	+			// touching the client store or GrantLimiter — there is no
1219	+			// client_id yet to key either by.
1220	+			writeTokenError(w, http.StatusUnauthorized, "invalid_client")
1221	+			return
1222	+		}
1223	+
1224	+		sourceIP := sourceIPFrom(r)
1225	+
1226	+		allowed, err := limiter.Allow(ctx, clientID, sourceIP)
1227	+		if err != nil {
1228	+			writeTokenError(w, http.StatusInternalServerError, "server_error")
1229	+			return
1230	+		}
1231	+		if !allowed {
1232	+			// RFC 6749 doesn't name a status for endpoint-level
1233	+			// throttling (it's a brute-force control this project adds
1234	+			// on top of the spec, not part of it) — 429 matches this
1235	+			// API's own convention elsewhere (internal/api/ratelimit.go,
1236	+			// internal/api/touchcounter.go) for the same class of
1237	+			// decision.
1238	+			writeTokenError(w, http.StatusTooManyRequests, "slow_down")
1239	+			return
1240	+		}
1241	+
1242	+		rec, found, err := store.Get(ctx, clientID)
1243	+		if err != nil {
1244	+			writeTokenError(w, http.StatusInternalServerError, "server_error")
1245	+			return
1246	+		}
1247	+
1248	+		// Both branches run the SAME Argon2id comparison at the SAME
1249	+		// cost before deciding anything — a found client with a real
1250	+		// secret on file (secret_state = "set") compares against its own
1251	+		// hash; every other case (client_id not found at all, OR found
1252	+		// but secret_state is "none"/"revoked" and ClientSecretHash is
1253	+		// empty) compares against the fixed dummyHash instead of
1254	+		// skipping the comparison or short-circuiting on a malformed
1255	+		// hash. Whichever branch runs, exactly one verifySecret call
1256	+		// happens before the outcome is known, so an unknown client_id,
1257	+		// a not-yet-secreted or revoked client, and a wrong secret for a
1258	+		// fully provisioned one all take statistically indistinguishable
1259	+		// time (Tobias Lindqvist's objection, LT-51 refinement) —
1260	+		// closing the timing side-channel the identical response body
1261	+		// alone leaves open.
1262	+		var secretOK bool
1263	+		if found && rec.ClientSecretHash != "" {
1264	+			secretOK = verifySecret(clientSecret, rec.ClientSecretHash)
1265	+		} else {
1266	+			_ = verifySecret(clientSecret, dummyHash)
1267	+			secretOK = false
1268	+		}
1269	+
1270	+		if !found || !secretOK || !rec.Active {
1271	+			limiter.RecordFailure(ctx, clientID, sourceIP)
1272	+			writeTokenError(w, http.StatusUnauthorized, "invalid_client")
1273	+			return
1274	+		}
1275	+		limiter.RecordSuccess(ctx, clientID, sourceIP)
1276	+
1277	+		// scope is optional per RFC 6749 §4.4: omitted means issue the
1278	+		// client's full granted set, which — per ClientRecord's own doc
1279	+		// comment on why GrantedScope is singular, not a set — is
1280	+		// exactly one scope. A requested scope must equal that one
1281	+		// scope exactly; anything else (a different scope, an empty
1282	+		// string when one is explicitly passed, more than one
1283	+		// space-delimited value) is invalid_scope. This is stricter than
1284	+		// "subset of a set" only because the set this system provisions
1285	+		// is never larger than one element to begin with.
1286	+		requested := strings.TrimSpace(r.PostForm.Get("scope"))
1287	+		if requested != "" && Scope(requested) != rec.GrantedScope {
1288	+			writeTokenError(w, http.StatusBadRequest, "invalid_scope")
1289	+			return
1290	+		}
1291	+
1292	+		now := time.Now()
1293	+		c := claims{
1294	+			Scope: string(rec.GrantedScope),
1295	+			RegisteredClaims: jwt.RegisteredClaims{
1296	+				Issuer:    issuer,
1297	+				Subject:   clientID,
1298	+				Audience:  jwt.ClaimStrings{rec.Audience},
1299	+				IssuedAt:  jwt.NewNumericDate(now),
1300	+				ExpiresAt: jwt.NewNumericDate(now.Add(tokenTTL)),
1301	+				// jti: audit-correlation aid only, per handoff-03-auth.md
1302	+				// v4 — never checked against a denylist at verification
1303	+				// time (this design's TTL-only revocation stands).
1304	+				ID: uuid.NewString(),
1305	+			},
1306	+		}
1307	+		token := jwt.NewWithClaims(jwt.SigningMethodRS256, c)
1308	+		token.Header["kid"] = key.Kid
1309	+		signed, err := token.SignedString(key.Private)
1310	+		if err != nil {
1311	+			writeTokenError(w, http.StatusInternalServerError, "server_error")
1312	+			return
1313	+		}
1314	+
1315	+		w.Header().Set("Content-Type", "application/json")
1316	+		w.Header().Set("Cache-Control", "no-store") // RFC 6749 §5.1: token responses must not be cached
1317	+		w.WriteHeader(http.StatusOK)
1318	+		_ = jsonEncode(w, tokenResponse{
1319	+			AccessToken: signed,
1320	+			TokenType:   "Bearer",
1321	+			ExpiresIn:   int(tokenTTL.Seconds()),
1322	+			Scope:       string(rec.GrantedScope),
1323	+		})
1324	+	}
1325	+}
1326	+
1327	+// sourceIPFrom extracts the caller's address for GrantLimiter's
1328	+// per-source-IP key. r.RemoteAddr is the direct TCP peer — if this
1329	+// service ever sits behind a proxy that needs X-Forwarded-For honored
1330	+// instead, that's a deployment-topology decision for whoever wires the
1331	+// proxy, not assumed here.
1332	+func sourceIPFrom(r *http.Request) string {
1333	+	host, _, err := net.SplitHostPort(r.RemoteAddr)
1334	+	if err != nil {
1335	+		return r.RemoteAddr
1336	+	}
1337	+	return host
1338	+}
1339	diff --git a/internal/api/tokenhandler_test.go b/internal/api/tokenhandler_test.go
1340	new file mode 100644
1341	index 0000000..38393e5
1342	--- /dev/null
1343	+++ b/internal/api/tokenhandler_test.go
1344	@@ -0,0 +1,300 @@
1345	+package api
1346	+
1347	+import (
1348	+	"context"
1349	+	"crypto/rand"
1350	+	"crypto/rsa"
1351	+	"encoding/json"
1352	+	"io"
1353	+	"net/http"
1354	+	"net/http/httptest"
1355	+	"net/url"
1356	+	"strings"
1357	+	"testing"
1358	+
1359	+	"github.com/golang-jwt/jwt/v5"
1360	+)
1361	+
1362	+// fakeClientStore implements ClientStore, per decisions/test-double-strategy.md.
1363	+type fakeClientStore struct {
1364	+	records map[string]ClientRecord
1365	+	getErr  error
1366	+	gotIDs  []string // records every clientID Get was called with, for call-shape assertions
1367	+}
1368	+
1369	+func (f *fakeClientStore) Get(_ context.Context, clientID string) (ClientRecord, bool, error) {
1370	+	f.gotIDs = append(f.gotIDs, clientID)
1371	+	if f.getErr != nil {
1372	+		return ClientRecord{}, false, f.getErr
1373	+	}
1374	+	rec, ok := f.records[clientID]
1375	+	return rec, ok, nil
1376	+}
1377	+
1378	+// fakeGrantLimiter implements GrantLimiter.
1379	+type fakeGrantLimiter struct {
1380	+	allow           bool
1381	+	allowErr        error
1382	+	failedClientIDs []string
1383	+	succeededIDs    []string
1384	+}
1385	+
1386	+func (f *fakeGrantLimiter) Allow(_ context.Context, clientID, sourceIP string) (bool, error) {
1387	+	return f.allow, f.allowErr
1388	+}
1389	+func (f *fakeGrantLimiter) RecordFailure(_ context.Context, clientID, sourceIP string) {
1390	+	f.failedClientIDs = append(f.failedClientIDs, clientID)
1391	+}
1392	+func (f *fakeGrantLimiter) RecordSuccess(_ context.Context, clientID, sourceIP string) {
1393	+	f.succeededIDs = append(f.succeededIDs, clientID)
1394	+}
1395	+
1396	+func testSigningKey(t *testing.T) *SigningKey {
1397	+	t.Helper()
1398	+	priv, err := rsa.GenerateKey(rand.Reader, 2048)
1399	+	if err != nil {
1400	+		t.Fatalf("generating RSA key: %v", err)
1401	+	}
1402	+	return &SigningKey{Private: priv, Kid: "test-kid"}
1403	+}
1404	+
1405	+func postToken(t *testing.T, h http.HandlerFunc, form url.Values, clientID, clientSecret string, setBasicAuth bool) *http.Response {
1406	+	t.Helper()
1407	+	req := httptest.NewRequest(http.MethodPost, "/auth/token", strings.NewReader(form.Encode()))
1408	+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
1409	+	if setBasicAuth {
1410	+		req.SetBasicAuth(clientID, clientSecret)
1411	+	}
1412	+	w := httptest.NewRecorder()
1413	+	h.ServeHTTP(w, req)
1414	+	return w.Result()
1415	+}
1416	+
1417	+func decodeTokenError(t *testing.T, resp *http.Response) tokenErrorResponse {
1418	+	t.Helper()
1419	+	var body tokenErrorResponse
1420	+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
1421	+		t.Fatalf("decoding error body: %v", err)
1422	+	}
1423	+	return body
1424	+}
1425	+
1426	+func TestNewTokenHandler_MissingGrantType_UnsupportedGrantType(t *testing.T) {
1427	+	store := &fakeClientStore{records: map[string]ClientRecord{}}
1428	+	limiter := &fakeGrantLimiter{allow: true}
1429	+	h := NewTokenHandler(store, limiter, testSigningKey(t), "https://issuer.test")
1430	+
1431	+	resp := postToken(t, h, url.Values{}, "any", "any", true)
1432	+	if resp.StatusCode != http.StatusBadRequest {
1433	+		t.Fatalf("status = %d, want 400", resp.StatusCode)
1434	+	}
1435	+	if body := decodeTokenError(t, resp); body.Error != "unsupported_grant_type" {
1436	+		t.Errorf("error = %q, want unsupported_grant_type", body.Error)
1437	+	}
1438	+}
1439	+
1440	+func TestNewTokenHandler_NoBasicAuth_InvalidClient401(t *testing.T) {
1441	+	store := &fakeClientStore{records: map[string]ClientRecord{}}
1442	+	limiter := &fakeGrantLimiter{allow: true}
1443	+	h := NewTokenHandler(store, limiter, testSigningKey(t), "https://issuer.test")
1444	+
1445	+	form := url.Values{"grant_type": {"client_credentials"}}
1446	+	resp := postToken(t, h, form, "", "", false)
1447	+	if resp.StatusCode != http.StatusUnauthorized {
1448	+		t.Fatalf("status = %d, want 401", resp.StatusCode)
1449	+	}
1450	+	if got := resp.Header.Get("WWW-Authenticate"); !strings.HasPrefix(got, "Basic") {
1451	+		t.Errorf("WWW-Authenticate = %q, want a Basic challenge", got)
1452	+	}
1453	+	if len(store.gotIDs) != 0 {
1454	+		t.Errorf("store.Get called %d times, want 0 — no client_id exists yet to key by", len(store.gotIDs))
1455	+	}
1456	+}
1457	+
1458	+// TestNewTokenHandler_UnknownClient_And_WrongSecret_ByteIdenticalResponses
1459	+// is RFC 6749 §5.2's own requirement plus Tobias Lindqvist's timing-oracle
1460	+// objection (LT-51 refinement): an unknown client_id and a wrong secret
1461	+// for a known client_id must be indistinguishable to the caller — same
1462	+// status, same body — and internally must run the same real Argon2id
1463	+// comparison exactly once, never short-circuiting one path cheaper than
1464	+// the other.
1465	+func TestNewTokenHandler_UnknownClient_And_WrongSecret_ByteIdenticalResponses(t *testing.T) {
1466	+	hash, err := hashSecret("correct-secret")
1467	+	if err != nil {
1468	+		t.Fatalf("hashing secret: %v", err)
1469	+	}
1470	+	store := &fakeClientStore{records: map[string]ClientRecord{
1471	+		"known-client": {ClientID: "known-client", Name: "Known", ClientSecretHash: hash, GrantedScope: Scope("profile:search"), Audience: "aud", Active: true},
1472	+	}}
1473	+	limiter := &fakeGrantLimiter{allow: true}
1474	+	h := NewTokenHandler(store, limiter, testSigningKey(t), "https://issuer.test")
1475	+
1476	+	form := url.Values{"grant_type": {"client_credentials"}}
1477	+
1478	+	respUnknown := postToken(t, h, form, "does-not-exist", "whatever", true)
1479	+	bodyUnknown, _ := io.ReadAll(respUnknown.Body)
1480	+
1481	+	respWrongSecret := postToken(t, h, form, "known-client", "wrong-secret", true)
1482	+	bodyWrongSecret, _ := io.ReadAll(respWrongSecret.Body)
1483	+
1484	+	if respUnknown.StatusCode != http.StatusUnauthorized || respWrongSecret.StatusCode != http.StatusUnauthorized {
1485	+		t.Fatalf("status codes = %d, %d, want both 401", respUnknown.StatusCode, respWrongSecret.StatusCode)
1486	+	}
1487	+	if string(bodyUnknown) != string(bodyWrongSecret) {
1488	+		t.Errorf("response bodies differ: unknown-client=%q wrong-secret=%q — must be byte-identical", bodyUnknown, bodyWrongSecret)
1489	+	}
1490	+
1491	+	if len(limiter.failedClientIDs) != 2 {
1492	+		t.Errorf("RecordFailure called %d times, want 2 (once per failed attempt)", len(limiter.failedClientIDs))
1493	+	}
1494	+}
1495	+
1496	+func TestNewTokenHandler_FoundButNoSecretSet_TreatedSameAsNotFound(t *testing.T) {
1497	+	// secret_state = "none"/"revoked" rows have an empty ClientSecretHash
1498	+	// (the migration's own CHECK ties the two together) — this must run
1499	+	// the dummyHash comparison, not a malformed-hash short-circuit, per
1500	+	// the same timing-parity reasoning as the unknown-client_id case.
1501	+	store := &fakeClientStore{records: map[string]ClientRecord{
1502	+		"provisioned-no-secret": {ClientID: "provisioned-no-secret", Name: "No Secret Yet", ClientSecretHash: "", GrantedScope: Scope("profile:search"), Audience: "aud", Active: true},
1503	+	}}
1504	+	limiter := &fakeGrantLimiter{allow: true}
1505	+	h := NewTokenHandler(store, limiter, testSigningKey(t), "https://issuer.test")
1506	+
1507	+	form := url.Values{"grant_type": {"client_credentials"}}
1508	+	resp := postToken(t, h, form, "provisioned-no-secret", "anything", true)
1509	+	if resp.StatusCode != http.StatusUnauthorized {
1510	+		t.Fatalf("status = %d, want 401", resp.StatusCode)
1511	+	}
1512	+	if body := decodeTokenError(t, resp); body.Error != "invalid_client" {
1513	+		t.Errorf("error = %q, want invalid_client", body.Error)
1514	+	}
1515	+}
1516	+
1517	+func TestNewTokenHandler_CorrectCredentials_IssuesValidToken(t *testing.T) {
1518	+	hash, err := hashSecret("s3cr3t")
1519	+	if err != nil {
1520	+		t.Fatalf("hashing secret: %v", err)
1521	+	}
1522	+	key := testSigningKey(t)
1523	+	store := &fakeClientStore{records: map[string]ClientRecord{
1524	+		"known-client": {ClientID: "known-client", Name: "Known", ClientSecretHash: hash, GrantedScope: Scope("profile:search"), Audience: "loginid-api-service", Active: true},
1525	+	}}
1526	+	limiter := &fakeGrantLimiter{allow: true}
1527	+	h := NewTokenHandler(store, limiter, key, "https://issuer.test")
1528	+
1529	+	form := url.Values{"grant_type": {"client_credentials"}}
1530	+	resp := postToken(t, h, form, "known-client", "s3cr3t", true)
1531	+	if resp.StatusCode != http.StatusOK {
1532	+		body, _ := io.ReadAll(resp.Body)
1533	+		t.Fatalf("status = %d, want 200, body=%s", resp.StatusCode, body)
1534	+	}
1535	+	if got := resp.Header.Get("Cache-Control"); got != "no-store" {
1536	+		t.Errorf("Cache-Control = %q, want no-store (RFC 6749 §5.1)", got)
1537	+	}
1538	+
1539	+	var body tokenResponse
1540	+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
1541	+		t.Fatalf("decoding success body: %v", err)
1542	+	}
1543	+	if body.TokenType != "Bearer" {
1544	+		t.Errorf("token_type = %q, want Bearer", body.TokenType)
1545	+	}
1546	+	if body.Scope != "profile:search" {
1547	+		t.Errorf("scope = %q, want profile:search", body.Scope)
1548	+	}
1549	+
1550	+	parsed, err := jwt.ParseWithClaims(body.AccessToken, &claims{}, func(tok *jwt.Token) (any, error) {
1551	+		return &key.Private.PublicKey, nil
1552	+	}, jwt.WithValidMethods([]string{"RS256"}))
1553	+	if err != nil {
1554	+		t.Fatalf("parsing/verifying minted token: %v", err)
1555	+	}
1556	+	c := parsed.Claims.(*claims)
1557	+	if c.Subject != "known-client" {
1558	+		t.Errorf("sub = %q, want known-client", c.Subject)
1559	+	}
1560	+	if c.Issuer != "https://issuer.test" {
1561	+		t.Errorf("iss = %q, want https://issuer.test", c.Issuer)
1562	+	}
1563	+	if len(c.Audience) != 1 || c.Audience[0] != "loginid-api-service" {
1564	+		t.Errorf("aud = %v, want [loginid-api-service]", c.Audience)
1565	+	}
1566	+	if c.Scope != "profile:search" {
1567	+		t.Errorf("scope claim = %q, want profile:search", c.Scope)
1568	+	}
1569	+	if parsed.Header["kid"] != key.Kid {
1570	+		t.Errorf("kid header = %v, want %q", parsed.Header["kid"], key.Kid)
1571	+	}
1572	+
1573	+	if len(limiter.succeededIDs) != 1 || limiter.succeeded
… truncated (20 KB cap)

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

     784

{
  "command": "gh pr diff 39 --repo wtvamp/loginid-takehome > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/scratchpad/pr39.diff 2>&1; wc -l /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/scratchpad/pr39.diff"
}

     784 /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/scratchpad/pr39.diff

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-02-ai-security-architecture/01db5ea7-33b3-444b-8eae-57a267d4ed1b/scratchpad/pr39.diff"
}

1	diff --git a/deploy/demo-data/qa-client-bootstrap.md b/deploy/demo-data/qa-client-bootstrap.md
2	index 7e19569..1957224 100644
3	--- a/deploy/demo-data/qa-client-bootstrap.md
4	+++ b/deploy/demo-data/qa-client-bootstrap.md
5	@@ -1,5 +1,7 @@
6	 # QA client credential — out-of-band seeding runbook
7	 
8	+**Format change (handoff-03-auth.md v7):** `gen-argon2-hash.go` now emits a PHC-format hash instead of the earlier `<base64-salt>$<base64-hash>` encoding — the two are not interchangeable. Any row seeded before this change must be re-seeded (re-run step 1 for a new secret, then the rotation `UPDATE` in "Rotation / revocation" below) before it will verify again.
9	+
10	 Per Priya's ruling on LT-51: "migrations carry reference data, never credentials" — the QA client row in `oauth_client` is seeded by hand, directly against the issuer database's own migrator role, never through a migration file, never through the CI-applied manifest set (`deploy/rbac.yaml` grants the deployer nothing on `secrets`, so it has no path to this credential regardless), and never with the plaintext secret or its hash committed anywhere in this repo.
11	 
12	 ## 1. Generate the secret and its Argon2id hash
13	@@ -11,7 +13,7 @@ HASH=$(cat /tmp/qa-hash.txt)
14	 rm -f /tmp/qa-hash.txt
15	 ```
16	 
17	-`deploy/gen-argon2-hash.go` produces the exact encoding `internal/api/clientstore.go`'s `hashSecret`/`verifySecret` expect (`<base64-salt>$<base64-hash>`, same fixed Argon2id cost profile) — verified by round-tripping a test hash through the app's own comparison logic before this runbook was written, not assumed from reading the source.
18	+`deploy/gen-argon2-hash.go` produces a standard PHC-format Argon2id hash (`«REDACTED-ARGON2»`) — the same self-describing encoding `user_credential.secret` already uses, and what `internal/api/clientstore.go`'s `verifySecret` reads its cost parameters back from (never assumed to match the app's own current constants — Priya Nandakumar's ruling, `handoff-03-auth.md` v7). Verified by round-tripping a test hash through the app's own comparison logic before this runbook was written, not assumed from reading the source, and again by a permanent test (`internal/api/clientstore_test.go`'s hand-constructed-different-parameters case) that fails if the verifier is ever changed to ignore the embedded parameters.
19	 
20	 **Give `$CLIENT_SECRET` to whoever will run the PO review script and nowhere else** — it is the Basic-auth password for `POST /auth/token`. It cannot be recovered from `$HASH` afterward; if lost, generate a new secret and re-run step 2 (an `UPDATE`, not a fresh `INSERT`).
21	 
22	diff --git a/deploy/gen-argon2-hash.go b/deploy/gen-argon2-hash.go
23	index a78790b..676be06 100644
24	--- a/deploy/gen-argon2-hash.go
25	+++ b/deploy/gen-argon2-hash.go
26	@@ -1,13 +1,20 @@
27	 //go:build ignore
28	 
29	 // Standalone runbook helper, never built into any image or run by any
30	-// application code path — generates an Argon2id hash in exactly the
31	-// encoding internal/api/clientstore.go's hashSecret/verifySecret expect
32	-// ("<base64-salt>$<base64-hash>", RawStdEncoding), with the same fixed
33	-// cost profile (time=1, memory=64MiB, threads=4, keyLen=32, saltLen=16).
34	-// Kept as source, not a checked-in binary, and excluded from normal
35	-// builds via the "ignore" build tag above — `go run` compiles and
36	-// discards it each time.
37	+// application code path — generates an Argon2id hash as a standard PHC
38	+// string («REDACTED-ARGON2» the same
39	+// self-describing encoding internal/api/clientstore.go's verifySecret
40	+// reads its cost parameters back from — not the app's own compile-time
41	+// constants (Priya Nandakumar's ruling, handoff-03-auth.md v7: a bare
42	+// "<base64-salt>$<base64-hash>" with no embedded parameters would make a
43	+// future cost-profile bump break every existing hash at once with no way
44	+// to tell an old row from a new one). Cost profile here
45	+// (time=1, memory=64MiB, threads=4, keyLen=32, saltLen=16) matches
46	+// clientstore.go's CURRENT profile, but the hash this program emits
47	+// verifies correctly even after that profile changes, since the
48	+// parameters travel with the hash. Kept as source, not a checked-in
49	+// binary, and excluded from normal builds via the "ignore" build tag
50	+// above — `go run` compiles and discards it each time.
51	 //
52	 // Usage (never let the plaintext or the hash reach a log, a commit, or a
53	 // chat message — pipe or redirect only):
54	@@ -16,7 +23,7 @@
55	 //   go run deploy/gen-argon2-hash.go "$QA_SECRET" > /tmp/qa-hash.txt
56	 //   unset QA_SECRET
57	 //
58	-// /tmp/qa-hash.txt then holds the PHC-shaped string to embed in the
59	+// /tmp/qa-hash.txt then holds the PHC-format string to embed in the
60	 // INSERT in deploy/demo-data/qa-client-bootstrap.md's runbook step;
61	 // delete the temp file after.
62	 package main
63	@@ -52,5 +59,9 @@ func main() {
64	 	}
65	 	hash := argon2.IDKey([]byte(secret), salt, argon2Time, argon2Memory, argon2Threads, argon2KeyLen)
66	 
67	-	fmt.Println(base64.RawStdEncoding.EncodeToString(salt) + "$" + base64.RawStdEncoding.EncodeToString(hash))
68	+	fmt.Printf("«REDACTED-ARGON2»",
69	+		argon2.Version, argon2Memory, argon2Time, argon2Threads,
70	+		base64.RawStdEncoding.EncodeToString(salt),
71	+		base64.RawStdEncoding.EncodeToString(hash),
72	+	)
73	 }
74	diff --git a/go.mod b/go.mod
75	index 20a1f16..d399160 100644
76	--- a/go.mod
77	+++ b/go.mod
78	@@ -15,8 +15,12 @@ require (
79	 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
80	 	github.com/jackc/puddle/v2 v2.2.2 // indirect
81	 	github.com/mattn/go-isatty v0.0.24 // indirect
82	+	github.com/mfridman/interpolate v0.0.2 // indirect
83	 	github.com/ncruces/go-strftime v1.0.0 // indirect
84	+	github.com/pressly/goose/v3 v3.28.0 // indirect
85	 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
86	+	github.com/sethvargo/go-retry v0.4.0 // indirect
87	+	go.uber.org/multierr v1.11.0 // indirect
88	 	golang.org/x/crypto v0.57.0 // indirect
89	 	golang.org/x/sync v0.23.0 // indirect
90	 	golang.org/x/sys v0.48.0 // indirect
91	diff --git a/go.sum b/go.sum
92	index 9225b92..70249d7 100644
93	--- a/go.sum
94	+++ b/go.sum
95	@@ -21,17 +21,26 @@ github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo
96	 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
97	 github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
98	 github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
99	+github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
100	+github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
101	 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
102	 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
103	 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
104	 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
105	+github.com/pressly/goose/v3 v3.28.0 h1:D2M+iL31GmpZxSHOhX8mqyqAT3CXnokUmm0eKoSP+Vc=
106	+github.com/pressly/goose/v3 v3.28.0/go.mod h1:v26MOuB8bL3kzzrt3Vqhb3R0PRVsl8hFQKdrht/L6Rk=
107	 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
108	 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
109	+github.com/sethvargo/go-retry v0.4.0 h1:9qy1OoIAxBL+gBYnkTnTnWle5wlfsXQlwRzIbbpdqPw=
110	+github.com/sethvargo/go-retry v0.4.0/go.mod h1:tvsjdKG6xfiCx4LSiUZ06kcv38xvdVQwv8R6/VnnVWg=
111	 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
112	 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
113	 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
114	 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
115	 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
116	+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
117	+go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
118	+go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
119	 golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
120	 golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
121	 golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
122	diff --git a/internal/api/clientstore.go b/internal/api/clientstore.go
123	index aed59ea..4cd604e 100644
124	--- a/internal/api/clientstore.go
125	+++ b/internal/api/clientstore.go
126	@@ -25,17 +25,25 @@ import (
127	 	"encoding/base64"
128	 	"errors"
129	 	"fmt"
130	+	"strconv"
131	 	"strings"
132	 	"time"
133	 
134	 	"golang.org/x/crypto/argon2"
135	 )
136	 
137	-// Argon2id parameters — one fixed cost profile for every client secret
138	-// (and the fixed dummy hash timing-parity depends on, below). Matches
139	-// threat-home.md Asset 1's own floor: this is not a separate, weaker
140	-// hashing decision for machine credentials, it's the same discipline
141	-// applied to a second credential class.
142	+// Argon2id parameters used when HASHING A NEW secret — hashSecret's own
143	+// cost profile, matching threat-model.md Asset 1's floor. verifySecret
144	+// below deliberately does NOT use these constants to recompute a hash:
145	+// it reads the cost parameters (m, t, p) out of the stored PHC string
146	+// itself. A verifier that ignored the embedded parameters and always
147	+// recomputed with these constants would make the PHC string's own
148	+// self-description pointless — the day this profile changes, every
149	+// existing hash would break at once with no way to tell an old row from
150	+// a new one, exactly the failure oauth_client's schema (no hash_algo/
151	+// hash_cost columns, unlike user_credential) was designed to avoid by
152	+// relying on the hash string being self-describing (Priya Nandakumar's
153	+// review, handoff-03-auth.md v7).
154	 const (
155	 	argon2Time    = 1
156	 	argon2Memory  = 64 * 1024 // 64 MiB
157	@@ -44,39 +52,171 @@ const (
158	 	argon2SaltLen = 16
159	 )
160	 
161	-// hashSecret returns an Argon2id hash of secret, encoded as
162	-// "<base64-salt>$<base64-hash>" — self-contained, no separate parameter
163	-// storage needed since every hash in this store uses the same fixed
164	-// profile above.
165	+// phcVersion is Argon2id's own version identifier (argon2.Version,=19,
166	+// i.e. 0x13) as it appears in a PHC string's "v=" field — a property of
167	+// the algorithm itself, not a cost knob, so unlike time/memory/threads
168	+// it is not expected to change independently of upgrading the algorithm
169	+// version.
170	+const phcVersion = argon2.Version
171	+
172	+// hashSecret returns an Argon2id hash of secret encoded as a standard
173	+// PHC string: «REDACTED-ARGON2»
174	+// (RFC-adjacent PHC string format; RawStdEncoding, unpadded, matching
175	+// the same encoding user_credential.secret already uses for its own
176	+// Argon2id hashes — one encoding convention project-wide, not two).
177	+// Self-describing: deploy/gen-argon2-hash.go emits the same shape, and
178	+// verifySecret below reads the embedded parameters back rather than
179	+// assuming they match argon2Time/argon2Memory/argon2Threads above.
180	 func hashSecret(secret string) (string, error) {
181	 	salt := make([]byte, argon2SaltLen)
182	 	if _, err := rand.Read(salt); err != nil {
183	 		return "", fmt.Errorf("api: generating salt: %w", err)
184	 	}
185	 	hash := argon2.IDKey([]byte(secret), salt, argon2Time, argon2Memory, argon2Threads, argon2KeyLen)
186	-	return base64.RawStdEncoding.EncodeToString(salt) + "$" + base64.RawStdEncoding.EncodeToString(hash), nil
187	+	return encodePHC(argon2Memory, argon2Time, argon2Threads, salt, hash), nil
188	 }
189	 
190	-// verifySecret reports whether secret matches encodedHash, produced by
191	-// hashSecret. Comparison is constant-time (crypto/subtle) — Argon2id's
192	-// own cost already dominates timing versus a plain []byte equality, but
193	-// there is no reason to reintroduce a length/byte-position side channel
194	-// on top of it for free.
195	-func verifySecret(secret, encodedHash string) bool {
196	-	parts := strings.SplitN(encodedHash, "$", 2)
197	-	if len(parts) != 2 {
198	-		return false
199	+// encodePHC always stamps the CURRENT phcVersion — it's for producing a
200	+// brand-new hash under this package's own live cost profile, never for
201	+// re-serializing a parsed hash's own (possibly different, possibly
202	+// older) parameters.
203	+func encodePHC(memory, time, threads int, salt, hash []byte) string {
204	+	return fmt.Sprintf("«REDACTED-ARGON2»",
205	+		phcVersion, memory, time, threads,
206	+		base64.RawStdEncoding.EncodeToString(salt),
207	+		base64.RawStdEncoding.EncodeToString(hash),
208	+	)
209	+}
210	+
211	+// parsedPHC is a PHC-string Argon2id hash's parameters, read off the
212	+// string itself rather than assumed from this package's own constants —
213	+// the whole reason to use PHC instead of the bare "<salt>$<hash>"
214	+// encoding this replaced.
215	+type parsedPHC struct {
216	+	memory  uint32
217	+	time    uint32
218	+	threads uint8
219	+	salt    []byte
220	+	hash    []byte
221	+}
222	+
223	+// parsePHC parses a PHC-format Argon2id hash string
224	+// («REDACTED-ARGON2» into
225	+// its components. Returns an error for anything that doesn't match this
226	+// exact shape — verifySecret treats a parse failure as "does not
227	+// verify," never as a reason to fall back to any other interpretation.
228	+func parsePHC(encoded string) (parsedPHC, error) {
229	+	// "«REDACTED-ARGON2»" split on "$" is:
230	+	// ["", "argon2id", "v=19", "m=65536,t=1,p=4", "<salt>", "<hash>"]
231	+	parts := strings.Split(encoded, "$")
232	+	if len(parts) != 6 || parts[0] != "" || parts[1] != "argon2id" {
233	+		return parsedPHC{}, fmt.Errorf("api: not a recognized argon2id PHC string")
234	 	}
235	-	salt, err := base64.RawStdEncoding.DecodeString(parts[0])
236	+
237	+	// parsePHCParam, not fmt.Sscanf: Sscanf doesn't require consuming the
238	+	// whole input, so "v=19x" would silently parse as version 19 with
239	+	// "x" discarded — inconsistent with parsePHCParam's own stricter,
240	+	// whole-field parsing below, and the same "malformed-but-plausible"
241	+	// gap this function otherwise guards against (Oren Castellan, PR #39
242	+	// review).
243	+	versionU64, err := parsePHCParam(parts[2], "v")
244	+	if err != nil {
245	+		return parsedPHC{}, err
246	+	}
247	+	version := int(versionU64)
248	+	if version != phcVersion {
249	+		return parsedPHC{}, fmt.Errorf("api: PHC string names argon2 version %d, this package verifies version %d", version, phcVersion)
250	+	}
251	+
252	+	params := strings.Split(parts[3], ",")
253	+	if len(params) != 3 {
254	+		return parsedPHC{}, fmt.Errorf("api: PHC parameter field %q does not have exactly 3 comma-separated parameters", parts[3])
255	+	}
256	+	var memory, timeCost, threads uint64
257	+	if memory, err = parsePHCParam(params[0], "m"); err != nil {
258	+		return parsedPHC{}, err
259	+	}
260	+	if timeCost, err = parsePHCParam(params[1], "t"); err != nil {
261	+		return parsedPHC{}, err
262	+	}
263	+	if threads, err = parsePHCParam(params[2], "p"); err != nil {
264	+		return parsedPHC{}, err
265	+	}
266	+
267	+	salt, err := base64.RawStdEncoding.DecodeString(parts[4])
268	+	if err != nil {
269	+		return parsedPHC{}, fmt.Errorf("api: decoding PHC salt: %w", err)
270	+	}
271	+	hash, err := base64.RawStdEncoding.DecodeString(parts[5])
272	+	if err != nil {
273	+		return parsedPHC{}, fmt.Errorf("api: decoding PHC hash: %w", err)
274	+	}
275	+
276	+	return parsedPHC{
277	+		memory:  uint32(memory),
278	+		time:    uint32(timeCost),
279	+		threads: uint8(threads),
280	+		salt:    salt,
281	+		hash:    hash,
282	+	}, nil
283	+}
284	+
285	+// parsePHCParam parses one "<name>=<digits>" field (e.g. "m=65536") and
286	+// requires the field's name to match wantName exactly, in the position
287	+// PHC's own fixed m,t,p ordering requires — a defensive check against a
288	+// hand-edited or malformed string silently reading the wrong value into
289	+// the wrong slot.
290	+func parsePHCParam(field, wantName string) (uint64, error) {
291	+	name, digits, found := strings.Cut(field, "=")
292	+	if !found || name != wantName {
293	+		return 0, fmt.Errorf("api: PHC parameter field %q is not in the expected %q= form", field, wantName)
294	+	}
295	+	v, err := strconv.ParseUint(digits, 10, 32)
296	+	if err != nil {
297	+		return 0, fmt.Errorf("api: parsing PHC parameter %q: %w", field, err)
298	+	}
299	+	return v, nil
300	+}
301	+
302	+// verifySecret reports whether secret matches encodedHash, a PHC-format
303	+// Argon2id hash produced by hashSecret (or by deploy/gen-argon2-hash.go,
304	+// which emits the identical shape). Recomputes using the memory/time/
305	+// threads parameters PARSED OUT OF encodedHash itself — never this
306	+// package's own argon2Time/argon2Memory/argon2Threads constants — so a
307	+// hash created under a different (older or newer) cost profile still
308	+// verifies correctly; only the embedded parameters and the embedded
309	+// salt/hash length (via keyLen = len(parsed hash)) participate.
310	+// Comparison is constant-time (crypto/subtle) — Argon2id's own cost
311	+// already dominates timing versus a plain []byte equality, but there is
312	+// no reason to reintroduce a length/byte-position side channel on top
313	+// of it for free.
314	+func verifySecret(secret, encodedHash string) bool {
315	+	parsed, err := parsePHC(encodedHash)
316	 	if err != nil {
317	 		return false
318	 	}
319	-	want, err := base64.RawStdEncoding.DecodeString(parts[1])
320	+	got := argon2.IDKey([]byte(secret), parsed.salt, parsed.time, parsed.memory, parsed.threads, uint32(len(parsed.hash)))
321	+	return subtle.ConstantTimeCompare(got, parsed.hash) == 1
322	+}
323	+
324	+// needsRehash reports whether encodedHash's embedded cost parameters
325	+// differ from this package's CURRENT profile (argon2Memory/argon2Time/
326	+// argon2Threads) — the mechanism by which a cost-profile bump migrates
327	+// existing rows forward opportunistically (verify-then-rehash-on-next-
328	+// successful-auth, Marcus Ilori's ruling, handoff-03-auth.md v7) instead
329	+// of requiring a live-credential migration. Only ever called after
330	+// verifySecret has already succeeded against encodedHash — this reports
331	+// "should be re-hashed under the current profile," not "is valid."
332	+// encodedHash is assumed parseable here (verifySecret already parsed it
333	+// successfully in the same call); a parse failure reports false rather
334	+// than panicking, since "can't tell, so don't rehash" is the safe
335	+// default for a function only ever called after a successful verify.
336	+func needsRehash(encodedHash string) bool {
337	+	parsed, err := parsePHC(encodedHash)
338	 	if err != nil {
339	 		return false
340	 	}
341	-	got := argon2.IDKey([]byte(secret), salt, argon2Time, argon2Memory, argon2Threads, argon2KeyLen)
342	-	return subtle.ConstantTimeCompare(got, want) == 1
343	+	return parsed.memory != argon2Memory || parsed.time != argon2Time || parsed.threads != argon2Threads
344	 }
345	 
346	 // dummyHash is computed once, at package init, from a fixed (not
347	@@ -
… truncated (20 KB cap)

{
  "command": "sed -n '1,80p' handoff-04-secrets.md 2>/dev/null; echo \"---\"; find ../04-infra-devops -iname \"*vault-provisioning*\""
}

# Hand-off 02 → 04: Secrets inventory and never-log list

Status: **v3.1** — corrects v3's own reasoning on `postgres-superuser` (below): it does *not* stay a Kubernetes Secret after all, since the "bootstrap before Vault exists" argument doesn't hold once Vault is already running independently of Postgres — Theo's finding. Three named exceptions remain, not four. v3 (delivery mechanism changes from raw Kubernetes `Secret` mounts to **Vault Agent Injector, per-ServiceAccount Vault roles**, Warren's ruling, LT-46, 2026-09-13) and everything else are otherwise unchanged. v2's S7 objection turn, F12/F13/F15/F50 fixes still hold — this revision changes *delivery mechanism*, not the inventory or the never-log list. Receiver: Theo Bergman, `../04-infra-devops/`. Written to the project's hand-off standard: 04 should be able to act on this without re-deriving the reasoning in `threat-model.md`, `api-auth-design.md`, or `connector-security.md`.

## Assumptions this hand-off makes

1. Deployment target is 04's **real Kubernetes cluster, reachable via a plain nginx Ingress + cert-manager on the cluster's shared LoadBalancer** (DNS CNAME to `uplifttech.ddns.net`, public at `https://loginid-takehome.uplifttech.org` — no tunnel; Warren's implementation go-ahead, 2026-09-12, updated from a design-only reference). **Delivery mechanism (updated 2026-09-13, LT-46): the Vault Agent Injector, not raw Kubernetes `Secret` mounts, for every application-level secret in the inventory below** — a Vault Agent sidecar, added via pod annotation, authenticates to Vault using the pod's own Kubernetes ServiceAccount token (Vault's Kubernetes auth method) and renders each secret to a file on an in-memory (`emptyDir`, `medium: Memory`) volume shared with the application container; nothing application-level is written to a Kubernetes `Secret` object, and therefore nothing application-level reaches etcd's base64-not-encrypted-by-default storage at all — this closes the etcd requirement below by removing the object from etcd entirely, not by enabling etcd encryption at rest. Amber (Vault operator) provisions the KV paths, Vault policies, and Kubernetes-auth roles that make this work; names only are visible in any transcript, never values. Every requirement below is written so it still holds regardless of mechanism; this is the mechanism 04 actually builds to now. **The repository is now public** (`https://github.com/wtvamp/loginid-takehome`) — every requirement in this document that says "never in source or committed config" is now categorical, with no private-repo safety net.

**`postgres-superuser` is Vault-delivered after all — v3's reasoning here was wrong, corrected rather than quietly patched over.** v3 argued a Vault Agent sidecar "doesn't help a database's own first-init bootstrap" because it's a pattern for pods already running and authenticating to Vault themselves. That's true of the *sidecar* pattern specifically, but conflates two different things: whether *Vault itself* exists yet (it does — an independent HA Vault, already running on this cluster, not something Postgres hosts or depends on existing) versus whether *this specific pod* has started yet. Vault Agent supports an **init-container** mode for exactly this shape of problem: it runs to completion *before* the main container starts, authenticates via the pod's own ServiceAccount token the same as the sidecar pattern, and renders the credential to a shared volume the main container then reads at its own startup — Postgres's official image already supports `POSTGRES_PASSWORD_FILE` (a file path) as an alternative to `POSTGRES_PASSWORD` (a literal value), so the init script reading from a Vault-rendered file instead of a `secretKeyRef` env var is a small, well-supported change, not a redesign. There was no actual chicken-and-egg here once Vault's own existence is independent of Postgres's — v3 treated "the database is bootstrapping" and "Vault needs bootstrapping" as the same problem when they aren't.

**Postgres gets its own Vault role, `loginid-takehome-postgres`**, reading `postgres-superuser` plus the four existing DB-credential paths (`db-migrator-credential`, `db-runtime-credential`, `issuer-db-migrator-credential`, `issuer-db-runtime-credential`) — five paths, the widest of any role in this system, since the Postgres StatefulSet's init script is what seeds all of them. This is the role deserving the closest look in Helena's policy review, precisely because it's the widest.

**Three named exceptions remain Kubernetes Secrets, not Vault-delivered:**

- **`postgres-server-tls`** — cert-manager's own `Certificate`/`Secret` mechanism (`threat-model.md` Assumption 9), consumed directly by the Postgres StatefulSet's TLS startup args. cert-manager already *is* a secure, automated, rotation-aware delivery mechanism purpose-built for exactly this (a server needing a TLS keypair) — routing it through Vault instead would duplicate a solved problem, not close a gap.
- **`loginid-takehome-tls`** — same reasoning, one level up: the public Ingress's cert-manager-issued certificate, consumed by the Ingress controller directly. Same native, already-secure mechanism; no benefit to re-routing through Vault.
- **The ARC GitHub App auth credential** (in the runner namespace, not this application's namespace) — a platform/CI-infrastructure secret belonging to the runner controller itself, not to `api-service`/`idp-connector`/the issuer. It authenticates GitHub's App to provision self-hosted runners; it's outside this application's own trust boundary and namespace, and this hand-off's scope is this application's secrets, not the CI platform's own.

The common thread across all three: each is either an already-native, already-secure Kubernetes-integrated mechanism (cert-manager) that Vault would only duplicate, or a platform-level secret outside this application's own namespace/trust boundary — not an ad hoc carve-out, and not "hasn't gotten to it yet."

**A fourth item, `qa-client-credential`, is a different category from the three above and stays a Kubernetes Secret for a different reason (ruled 2026-09-13, jointly with Theo Bergman): it's an ops/review-tooling artifact, not an application secret, and structurally cannot use the Vault Agent Injector pattern at all.** The Vault Agent mechanism delivers a secret into a *running pod's filesystem at startup* — `qa-client-credential` is never consumed that way; its only consumption pattern is a human running `kubectl get secret qa-client-credential -o jsonpath=...` directly to manually mint a review token, with no pod in between. There's nothing to inject into. Moving it to Vault would only relocate where a human types a fetch command (`kubectl` → `vault` CLI); it wouldn't close any actual exposure, since the exposure surface either way is "whoever can authenticate as a cluster operator." **Least-privilege confirmation, not just deferred:** checked against `deploy/rbac.yaml` directly — the CI deployer's Role has no `secrets` verbs at all, and no application ServiceAccount (api-service, issuer, idp-connector) has any Secrets-API grant either, since Vault handles their application secrets now. `qa-client-credential`'s actual access boundary is therefore "human operators with direct cluster access," which is Assumption 7's existing operator trust boundary — not a new, unstated exposure this migration should have closed and didn't.
2. Service topology is 03's published boundary (`../PLANNING.md`, Service boundaries): two binaries, `cmd/api-service` (Q1 DAO + Q2 REST API) and `cmd/idp-connector` (Q3), env-var configuration only. Variable names below are 03's; two are marked as pending this track's final scheme. **The token-issuing authorization-server function is a mode of `api-service`, not a third binary** — this take-home's scope doesn't justify a standalone authz server, and 03 has published no third `cmd/` entrypoint. **Corrected by the cross-track consistency pass (F13):** "a mode of the same binary" is not "the same Kubernetes Deployment," and the earlier text here was wrong to imply RBAC alone separates them — a Kubernetes Role restricting `get` on a Secret has no effect on a volume already mounted into a container, so if `api-service`'s one Deployment mounted the signing key, every replica (verification path included) would have it on disk regardless of RBAC. **The fix: the issuer runs as a second Deployment of the same `api-service` image**, selected by an environment variable 03 adds to the config surface (e.g. `APP_MODE=issuer` vs. the default, consistent with the surface's env-var-only, no-flags rule), with **its own ServiceAccount that alone mounts the signing-key Secret** (row #2) — the `api-service` Deployment serving verification/search mounts nothing from row #2. This is a request into 03's Deployment/mode surface, not a unilateral change on my part; flag to me if the mode-selection mechanism needs to differ.
3. An **external operator agent** — a human or automated actor outside this project, holding cluster-admin or namespace-admin rights on 04's real lab cluster, who applies Kubernetes manifests to it — is a privileged actor outside this service: anyone who can apply a manifest can read any Secret it mounts. Consequence for 04: manifests reference Secrets by name and never carry values; values are set out-of-band. This is a named trust boundary in `threat-model.md` Assumption 7, not a silent assumption; nothing further about who that operator is needs to be re-derived from 04's own files to act on this hand-off. As of this update, 04 has not yet made contact with that operator or deployed anything — `threat-model.md` carries the dated status.
4. **Updated 2026-09-12:** with Warren's implementation go-ahead, 04's build stories will deploy to and contact the operator of the real cluster named in Assumption 1 — this is no longer a hypothetical the document describes in the abstract. As of this update, that contact hasn't happened yet; `threat-model.md` Assumption 7 carries the current, dated status and gets updated the moment it changes.

## Secrets inventory

| # | Secret | Used by | Injection requirement (02 sets it) | Rotation expectation | Delivery mechanism (04's, updated v3: Vault Agent unless named otherwise) | Never-log |
|---|---|---|---|---|---|---|
| 1 | Database credentials, carried inside `DB_DSN` | `api-service` | Runtime-injected; never in source, image, or committed config. **Required, not preferred: file mount via a `DB_DSN_FILE` convention** (03 to add alongside `DB_DSN`), because a DSN's embedded password is exposed by `kubectl describe`, crash dumps, and child-process environment exactly as much as any other secret in this table — there is no citation that makes `DB_DSN` a lesser case, so this track is not treating it as one | On credential rotation; service restart or reload acceptable | **Vault Agent sidecar**, rendered to the path `DB_DSN_FILE` reads, on an in-memory volume; `api-service`'s Vault role reads exactly this KV path and nothing else. Env-var `DB_DSN` remains a fallback only until 03 ships the file-based convention | Yes — the DSN contains the password; log the driver name and host at most |
| 2 | JWT signing **private** key (RS256/ES256), per `api-auth-design.md` | The issuer Deployment (`api-service` image, `APP_MODE=issuer`) only — **not** the `api-service` Deployment that verifies with the public key; these are two Deployments of one image, not one Deployment doing both (F13 fix) | Runtime-injected as a **file**, never an env var; asymmetric so the verifying Deployment never holds it | Key rotation with a `kid` claim; publish old and new public keys together during overlap; TTL of tokens (5–15 min) bounds the overlap window | **Vault Agent sidecar, only on the issuer Deployment's pod spec** — the verifying Deployment's Vault role has no policy path granting this secret at all (least-privilege at the Vault-policy layer now, in addition to the pod-spec-absence and CI-deployer-Role controls below, which still hold independently of the delivery mechanism): (a) the verifying Deployment's pod spec contains no reference to this secret at all; (b) the CI deployer's Role has no `secrets` verbs on Kubernetes Secrets, and (new) no Vault policy grants it read on this KV path either; (c) provisioned into Vault out-of-band, never through the CI-managed manifest set | Yes |
| 3 | JWT **public** key / JWKS | `api-service` middleware | Not a secret; may ship in config or be fetched from the issuer | Follows #2 | Plain `ConfigMap` or fetched URL; listed here so 04 does not over-protect it — not secret, not Vault-delivered | No (but never log full tokens — see below) |
| 4 | API caller `client_secret`s (OAuth2 client-credentials) | Authorization server (verifies); callers hold their own copy | **Stored hashed** (Argon2id, same floor as `threat-model.md` Asset 1), never plaintext at rest; issued once at provisioning and not recoverable | Per-client rotation on demand; revoke by deleting the hash | Lives in the issuer's own Postgres database (`oauth_client` table), not a Kubernetes Secret or Vault KV path; 04 delivers only that database's own connection credential (Vault-delivered, same shape as row #1) | Yes |
| 5 | Connector's own vendor registration: `IDP_ABC_CLIENT_ID`, `IDP_ABC_CLIENT_SECRET` (and the XYZ pair if a second vendor is configured) | `idp-connector` | Runtime-injected; never in source or committed config; `client_id` is low-sensitivity but travels with the secret and gets the same handling | Per vendor's policy; expect manual rotation | **Vault Agent sidecar**, one KV path per vendor so rotating ABC never touches XYZ; `idp-connector`'s Vault role reads exactly its own vendor paths | Yes for the secret; keep the id out of logs too |
| 6 | Vendor `access_token` (returned by our own `/auth` to its authenticated caller, presented as a header on our own `/identity` — updated for F3's caller-holds-the-token model, seam re-run regression fix) | `api-service` holds it briefly between the two calls; `idp-connector` only ever sees it as a caller-presented header on a single `/identity` request, never fetches or holds it between calls itself | **Not a deployed secret** — transient on both sides, never cached, never persisted. Neither `api-service` nor `idp-connector` writes it to a datastore (S3's no-cache ruling, restated for the two-party model in `connector-security.md` §1) | Expires on its own; never persisted across restarts by either party | No `Secret` object and no Vault KV path anywhere in this flow — there is nothing here for 04 to provision | Yes — never, including error paths, on both sides of the exchange |
| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets | `api-service` (TOTP) only — **not a committed feature of this submission**; `user_credential.method` is modeled as an extensible lookup table (`../05-data-ops/multi-db-strategy.md`) that supports TOTP as a *possible* value, but no TOTP implementation is planned unless 03 builds one. **The vendor-token-cache use case for this row no longer exists**: S3's red/blue on the connector token lifecycle is closed (`decisions/connector-token-lifecycle-redblue.md`) — no cache by default, and the token is never held by the connector between calls at all under F3's model (row 6), so there is no vendor-token cache for a KEK to encrypt. This row is provisioned only if TOTP materializes — it is a contingency the inventory names in advance, not a live requirement for 04 to build now | Runtime-injected as a file; the KEK never leaves the process that decrypts | Rotation by re-wrapping DEKs; never requires re-hashing passwords (those are hashed, not encrypted) | If this row is ever provisioned: Vault's own Transit engine is a more natural fit than a static KEK on a KV path (Vault already does envelope encryption as a first-class feature) — 04's call if this materializes, the requirement is only that the key exists, is not in source, and isn't a plain KV secret if Transit is available | Yes |
| 7a | Credential to reach the external KMS, **only if 04 exercises a non-Vault-Transit KMS alternative in row #7** (a role, API key, or client cert — whichever the chosen KMS uses) | Whichever binary holds the KEK reference (#7) | Same discipline as every other row here: runtime-injected, never in source, never provisioned ad hoc outside this table | Per the KMS provider's own rotation mechanism | Cloud-KMS access is typically workload-identity-based (no static credential to store); if the chosen KMS instead requires a static credential, it's Vault-delivered the same as every other row, kept out of the CI deployer's access the same way row #2's is | Yes |
| 8 | TLS serving private keys for `api-service` and `idp-connector` | Ingress / each binary, per 04's termination choice | Runtime-injected; TLS 1.2+ only; certificate validation never disabled in any environment (`connector-security.md` §2) | Per certificate lifetime; automated issuance preferred | **Named exception, stays a Kubernetes `Secret` (`kubernetes.io/tls`), not Vault-delivered** — cert-manager's native mechanism, same reasoning as `loginid-takehome-tls`/`postgres-server-tls` above: Vault would only duplicate a problem cert-manager already solves | Yes |
| 9 | End-user's vendor password (`POST /auth` request body) | `idp-connector`, transient | Never persisted, never cached, held only for the vendor call | n/a | Nothing for 04 to deliver; listed so nobody creates a place for it | **Yes — under no circumstance, including stack traces** |
| 10 | `api-service`'s own client credential (`client_id`/`client_secret`) toward the issuer, scoped `connector:identity-lookup`/`aud: idp-connector-service` — required for `api-service` to call `idp-connector`'s own authenticated `/auth`/`/identity` (`connector-security.md` §5) | `api-service` (the Deployment serving question 2's API, acting as a caller of the connector on a user's behalf) | Runtime-injected; never in source or committed config — same discipline as row 5's vendor registration, added by the cross-track consistency pass (F15), which found this credential asserted as a requirement in `connector-security.md`/`handoff-03-auth.md` with no inventory row | Same per-client rotation as row 4 (revoke by deleting the issuer-side hash) | **Vault Agent sidecar**, `api-service`'s Vault role reads this path in addition to row #1's — the two are separate KV paths under the same role, not merged, so a policy review can still see them as distinct grants | Yes |
| 11 | Postgres bootstrap superuser credential (`postgres-superuser`), plus the four DB-credential paths the same init script seeds (`db-migrator-credential`, `db-runtime-credential`, `issuer-db-migrator-credential`, `issuer-db-runtime-credential`) | Postgres StatefulSet's `initdb` scripts, at first container init | `POSTGRES_PASSWORD_FILE` (file path, not a literal env var) for the superuser; the init script reads the other four the same way | Manual, rare (bootstrap-only credentials) | **Vault-delivered via init-container mode (corrected, v3.1) — not the sidecar pattern, and not a Kubernetes Secret.** A Vault Agent init container runs to completion before the main Postgres container starts, authenticates via the StatefulSet's own ServiceAccount, and renders all five paths to a shared volume the main container reads at its own startup. Dedicated role `loginid-takehome-postgres`, the widest role in this system (five paths) — the one deserving the closest look in policy review | Yes |

Names marked pending in 03's boundary: `AUTH_JWT_ISSUER` / `AUTH_JWT_AUDIENCE` are configuration, not secrets; this track will confirm their final values in `handoff-03-auth.md`. They are listed here only so 04 does not classify them as secrets.

## Kubernetes-specific requirements (04 implements; 02 sets)

- **Secrets at rest in etcd are base64, not encrypted, by default (updated v3.1): closed by removal, not by enabli
… truncated (20 KB cap)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/handoff-amber-vault-provisioning.md"
}

1	# Hand-off: Vault provisioning for `loginid-takehome` (LT-46)
2	
3	**From:** Amber (OpenClaw Kubernetes agent on the Mac mini, model claude-opus-4-7), on Warren's authorization, 2026-09-13 10:06–10:25 PDT. **Requested by:** Dana Whitfield (PM). **Receiver:** Theo Bergman (04) for the manifest side; Helena Marsh (02) for policy review; Naomi Voss (01) for the refinement record.
4	
5	This is Amber's report, verbatim from her session output, lightly framed. It contains names and paths only; no secret value, token, or key appears here or appeared in her session. The request she answered is summarised at the end.
6	
7	---
8	
9	## 1. Kubernetes auth — already enabled, no change needed
10	
11	`auth/kubernetes` was already mounted and correctly configured for **this** cluster: `kubernetes_host = https://192.168.0.44:6443` (uplift-kub-ctrl-plane-1), `token_reviewer_jwt_set = true`, `disable_iss_validation = true`. I enabled nothing and re-configured nothing.
12	
13	## 2–3. KV mount and the copy
14	
15	**Mount `secret/`** — pre-existing and already KV **v2** (`options.version=2`), so I did not enable a new one. Prefix **`secret/loginid-takehome/`** (it joins existing `fmn/` and `mail/`).
16	
17	All six copied, key names preserved exactly, each at version 1:
18	
19	| Vault path | keys |
20	|---|---|
21	| `secret/loginid-takehome/db-runtime-credential` | `dsn`, `password` |
22	| `secret/loginid-takehome/db-migrator-credential` | `dsn`, `password` |
23	| `secret/loginid-takehome/issuer-db-runtime-credential` | `dsn`, `password` |
24	| `secret/loginid-takehome/issuer-db-migrator-credential` | `dsn`, `password` |
25	| `secret/loginid-takehome/api-service-jwt-signing-key` | `signing-key` |
26	| `secret/loginid-takehome/postgres-superuser` | `password` |
27	
28	Verified by SHA-256 per key, source vs. read-back — all identical. `postgres-server-tls`, `loginid-takehome-tls`, `qa-client-credential` untouched. **The Kubernetes Secrets were copied, not deleted** — nothing is removed until Theo's side is live and you say so.
29	
30	## 4–5. Policies and roles
31	
32	Five policies, `read` only, on exact `secret/data/loginid-takehome/<name>` paths; five `auth/kubernetes` roles of the same names, `token_ttl=1h`, `token_max_ttl=4h`, namespace `loginid-takehome`.
33	
34	| Role / policy name | bound ServiceAccount | read paths |
35	|---|---|---|
36	| `loginid-takehome-api-service` | `api-service` | db-runtime-credential, connector-client-credential |
37	| `loginid-takehome-api-service-issuer` | `api-service-issuer` | issuer-db-runtime-credential, api-service-jwt-signing-key |
38	| `loginid-takehome-db-migrate` | **`db-migrate`** | db-migrator-credential, issuer-db-migrator-credential |
39	| `loginid-takehome-postgres` | **`postgres`** | postgres-superuser + all four db credentials |
40	| `loginid-takehome-idp-connector` | **`idp-connector`** | none (policy exists, grants nothing) |
41	
42	`connector-client-credential` returns **404, not 403** for api-service — permitted by policy, just not populated yet. LT-33 can write it with no Vault change.
43	
44	## ⚠️ The blocker: three workloads have no ServiceAccount
45	
46	Your brief assumed each workload had its own `serviceAccountName`. It doesn't. Across the entire repo only `api-service` and `api-service-issuer` are defined. **`postgres` (StatefulSet), `db-migrate` (Job), and `idp-connector` (Deployment) declare no `serviceAccountName` and run as `default`** — confirmed against both the repo manifests and the live pods after Theo's 17:15Z redeploy.
47	
48	I did not bind three roles to `default`. Doing so would mean any pod on the `default` SA could assume **any** of those roles — `idp-connector`, which you ruled gets nothing, could have assumed `loginid-takehome-postgres` and read `postgres-superuser`. That would have inverted the least-privilege requirement while appearing to satisfy it.
49	
50	Instead I created dedicated ServiceAccounts `postgres`, `db-migrate`, `idp-connector` in the namespace and bound the roles to those. They're inert until used. Verified: `default` is denied all five roles (403), `idp-connector` cannot assume the postgres role (403), and the same SA name in another namespace is denied (403).
51	
52	**So Theo must add `serviceAccountName: postgres` / `db-migrate` / `idp-connector` to those three workloads.** Until he does, those three cannot authenticate to Vault at all — this is a hard failure, not a degradation. Ideally the SA objects go into `manifests.yaml` too so it's declarative; his `loginid-takehome-deployer` Role already has `serviceaccounts` create/update.
53	
54	## 6. Vault address for the injector
55	
56	**`https://vault.vault.svc:8200`** — note **https**, not the `http://` in your brief. The listener has `tls_disable = 0`. Theo does **not** need to set an address annotation: that exact value is already the injector's built-in default (`AGENT_INJECT_VAULT_ADDR`).
57	
58	For TLS, two options:
59	- **House pattern** (what ns `mail` uses): `vault.hashicorp.com/tls-skip-verify: "true"`.
60	- **Proper verification**: I staged Secret **`vault-ca-cert`** (key `ca.crt`) into `loginid-takehome`, fingerprint-identical to the one in ns `vault`. Mount via `vault.hashicorp.com/agent-extra-secret: "vault-ca-cert"` + `vault.hashicorp.com/ca-cert`. The cert's SANs include `vault.vault.svc`, so this validates cleanly.
61	
62	**Flag:** that CA expires **2026-12-14**, about three months out. Not urgent, not mine to renew unilaterally, but it shouldn't be a surprise.
63	
64	## End-to-end proof, and one trap for Theo
65	
66	I ran a throwaway pod through the real injector on the `api-service` SA and deleted it afterwards. Full chain works: SA → k8s auth → role → policy → KV v2 → agent → file.
67	
68	It also caught something worth having: the obvious multi-line template renders a **trailing newline** into the file — 49 bytes for a 48-byte password. A `\n` on a DB password fails auth looking exactly like a wrong password. The single-line form produces an exact byte match, and I verified this rather than just recommending it:
69	
70	```
71	'{{- with secret "secret/data/loginid-takehome/db-runtime-credential" -}}{{ .Data.data.password }}{{- end -}}'
72	```
73	
74	## What I changed beyond the brief
75	
76	- Created ServiceAccounts `postgres`, `db-migrate`, `idp-connector` (reason above).
77	- Created Secret `vault-ca-cert` in `loginid-takehome`.
78	- Nothing enabled, nothing deleted, no existing Vault policy or role touched. The four `db-*`/`issuer-*` credentials, the JWT key, and the superuser remain live as Kubernetes Secrets.
79	
80	No secret value, token, or key appears above or in any file I wrote; the local Vault token cache was shredded and the port-forward is closed.
81	
82	---
83	
84	## The request Amber answered (summary)
85	
86	Copy six named Kubernetes Secrets from `loginid-takehome` into KV v2 at `secret/loginid-takehome/<secret-name>` preserving key names; create five read-only policies and five Kubernetes-auth roles (`loginid-takehome-{api-service, api-service-issuer, db-migrate, postgres, idp-connector}`) bound to the matching ServiceAccounts in the namespace, `token_ttl=1h`, `token_max_ttl=4h`; report names only. Leave `postgres-server-tls`, `loginid-takehome-tls`, and `qa-client-credential` as Kubernetes Secrets by ruling (`../02-ai-security-architecture/handoff-04-secrets.md` v3.1).
87	
88	## PM notes for the receivers
89	
90	- **Theo:** the three `serviceAccountName` additions (`postgres`, `db-migrate`, `idp-connector`) are a hard prerequisite; add the ServiceAccount objects to `deploy/manifests.yaml` so they are declarative. Use the single-line template form Amber verified (trailing-newline trap). Prefer the `vault-ca-cert` verification path over `tls-skip-verify`; the CA expiry (2026-12-14) is Warren's platform item, recorded in `teardown.md`'s neighbourhood, not this project's.
91	- **Helena:** five roles; `loginid-takehome-postgres` is the widest. Amber's denial matrix (default SA denied all five, idp-connector denied postgres, same SA name in another namespace denied) is the evidence to re-run, not re-derive.
92	- **Deletion of the six Kubernetes Secrets** happens only after Theo's PR is deployed and Naomi's live review passes, on the PM's word, via runbook.
93