Desmond Okafor

{
  "command": "pwd"
}

/Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "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/01-product-industry-research-design/CLAUDE.md"
}

1	# Track: Product & Industry Research (incl. Design)
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	Frame the three assignment questions as a real product problem, not just three isolated coding exercises. Show industry awareness of the space LoginID operates in — identity, authentication, and credential/PII management — and use that framing to justify the design choices the engineering track implements.
8	
9	## Owns
10	
11	- Industry/competitive framing: where this kind of DAO + REST API + third-party IDP connector fits in the identity/IAM landscape (e.g., how it compares to what LoginID itself does with passkeys/FIDO2, and why a password-and-username-based `user_credential` model is the deliberately simpler baseline the assignment is asking for).
12	- Personas and use cases: who calls this API, why they need to search/retrieve user profile data, and why a service would need to pull PII from a third-party identity provider rather than owning that data itself.
13	- API and data contract design rationale from a product lens: what fields belong in `user_profile` vs `user_credential`, what "search/retrieve" needs to support, and why the `/auth` and `/identity` connector contracts are shaped the way LoginID specified them.
14	- Any UX/design artifacts for surfaces that would sit on top of this (e.g., an admin console for profile search, an onboarding flow that triggers the IDP connector) — light-touch, this is a backend assignment, so design work here should support the narrative rather than compete with it for attention.
15	
16	## Does not own
17	
18	- Actual security threat modeling and authn/authz mechanics for the API — that's `../02-ai-security-architecture/CLAUDE.md`.
19	- The Go implementation — that's `../03-engineering-delivery/CLAUDE.md`.
20	- Database schema and multi-DB strategy — that's `../05-data-ops/CLAUDE.md`.
21	
22	## Deliverables
23	
24	- A short industry/competitive framing document.
25	- Persona and use-case notes tied directly back to the three assignment questions.
26	- Design rationale for the API surface and the third-party connector contracts, written so the engineering track can implement against it without re-deriving the reasoning.
27	
28	## AI tooling note
29	
30	Record which AI tool/workflow produced this track's output (this project is being built with Claude Code) and how — e.g., research done via a scoped subagent reading this file as its brief.
31	
32	<!-- profile-gen:start slug=naomi-voss -->
33	@profiles/naomi-voss/naomi-voss.md
34	<!-- profile-gen:end slug=naomi-voss -->
35	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/PLAN.md"
}

1	# Track 01 Plan — Product & Industry Research (incl. Design)
2	
3	Lead: Naomi Voss (`naomi-voss`). Epic: **01 Product & Industry Research**. Governing files: root `CLAUDE.md`, `../PLAN.md` (org plan, Phase 1), `../PLANNING.md` (my row), `../CASTING.md` (palette, variance rules, persona standard, pattern catalog), `../02-ai-security-architecture/planning-approach.md` (coordination rules, hand-off standard, dependency order). This plan is written in plan mode per Phase 1 and is copied verbatim to `./PLAN.md` on exit; the real gate is team-lead's explicit "hiring go".
4	
5	## Context
6	
7	This track's three first-wave deliverables already exist and are complete as drafts: `industry-framing.md` (the "before/after" thesis — the assignment's password baseline is the deliberate "before", LoginID's passkey product is the "after", and the submission's job is to build the before honestly with the seams marked), `personas-use-cases.md` (three personas mapped to the three assignment questions), and `api-connector-design-rationale.md` (the field/endpoint/connector-shape rationale, designated by `planning-approach.md` §2 as the single source of truth 03 implements against). Two research docs (`research-loginid-company.md`, `research-oauth-history.md`) are their evidence base.
8	
9	The work this plan schedules is therefore not drafting — it is **stress-testing and hardening**: the framing has never been argued against, the claims have never been audited for evidence, and the hand-off doc has never been read cold by someone who has to act on it. Those three gaps are exactly what the three hires and the debate plan address. 01 is first-wave and upstream of everyone (nothing hard-blocks on it, but 03 should read the rationale before finalizing), so this work should finish before 03 finalizes handlers and the connector interface.
10	
11	Model/effort: the lead seat runs at whatever Warren has set for the session; all three hires are pinned `sonnet` (inherit effort); any research fan-out I run is `haiku` (project settings pin it to low). No code anywhere in this track — it is a prose track by definition.
12	
13	## 1. Deliverables & tasks (each = one Jira Story under the 01 Epic)
14	
15	Every row names the hand-off file it produces or consumes; acceptance criterion for every row is the hand-off standard from `planning-approach.md` §2: *the receiver can act without re-deriving my reasoning*.
16	
17	| # | Story | Produces | Consumed by | Pattern / hire |
18	|---|---|---|---|---|
19	| S1 | **Claims audit of the three framing docs.** Every quantitative or evaluative claim in `industry-framing.md`, `personas-use-cases.md`, `api-connector-design-rationale.md` gets a row: claim, source (file + section or URL), status (verified / asserted / marketing-sourced / softened). I then fix or soften each unsupported claim in place. Runs **first**, so the debate in S2 argues over verified facts. | `decisions/claims-audit.md`; edits to the three docs | Team-lead (README/packet), 02 (`ai-workflow-narrative.md` cites the framing), evaluators | Desmond (Spreadsheet), 1–2 turns |
20	| S2 | **Structured written debate on the central framing** — is the password baseline a deliberate simplification the submission should narrate as "before/after", or a contradiction at a passkey company that the framing over-reads by claiming to know what evaluators "are really testing for"? Position → rebuttal → my synthesis; both positions preserved. `industry-framing.md` §2 and §4 revised to whatever survives. | `decisions/password-baseline-debate.md`; revised `industry-framing.md` | Team-lead (submission thesis), 02 (narrative alignment) | Imogen (Storyteller, position) vs Tobias (Designated Skeptic, rebuttal); Naomi synthesizes. 3 turns + lead |
21	| S3 | **Harden `api-connector-design-rationale.md` as the single source of truth for field/endpoint shape.** Add a closing "Contract summary for 03" section: the two entities with the assignment's exact field names; the `method` discriminator and 1-to-many profile→credential requirement (consistent with the 02/05 lookup-table decision); the endpoint list (`GET /profiles/{id}`, search endpoint with the `GET` query-param vs `POST /profiles/search` recommendation resolved, not left open); the provider-agnostic connector interface shape (`Authenticate`, `FetchIdentity`) with ABC/XYZ as adapters; and an explicit **"03 does not re-derive / out of scope for 03"** list (auth mechanism is 02's, schema modeling is 05's, address field names are fixed by the assignment). Then a newcomer's-question cold read; I fix everything the reader could not act on. | Revised `api-connector-design-rationale.md`; `decisions/rationale-cold-read.md` | **03** (reads before finalizing handlers and connector interface — soft dependency); 05 (§1 only) | Newcomer's question — reader borrowed from 04 (see §4), fallback a context-free haiku subagent. 1–2 turns |
22	| S4 | **Product requirements for search authorization** — a short appendix to `personas-use-cases.md` stating what Persona 2 legitimately needs from search (fields searchable: name, phone, partial match; masked-by-default results; deliberate expand with audit entry; no bulk export; pagination) and what Persona 2 must *not* be able to do, written as input to 02's adversarial-pair run on `profile:search` vs `profile:read:own`. Product requirements only — no scope names, token formats, or policy mechanics. | `personas-use-cases.md` "Search authorization — product requirements" appendix | **02** (input to its authz scoping decision), 03 indirectly via 02's hand-off | Rotating devil's advocate, 1 turn (seat: Tobias) |
23	| S5 | **UX notes for the two surfaces** that would sit on top of this backend — the admin profile-search console (Persona 2) and the onboarding pre-fill flow that triggers the connector (Persona 3). Text only, one page, describing screens and the one design rule each surface enforces (masked-by-default; never showing the partner password). Supports the narrative; no wireframes, no design canvas (see §3, waste). | `ux-notes.md` | Team-lead (packet), evaluators | Rotating devil's advocate, 1 turn (seat: Desmond — "which of these sentences is a claim?") |
24	| S6 | **Newcomer cold read of `industry-framing.md`** — evaluator-legibility test: can a reader with no project context state the thesis and the three seams in their own words after one pass? Fix what they could not. Secondary to S3; runs only if the borrowed reader has a second turn available. | Revised `industry-framing.md`; appended to `decisions/rationale-cold-read.md` | Evaluators, team-lead | Newcomer's question, 1 turn |
25	| T1 | **Track housekeeping** (Jira Task, not a Story): update `./CLAUDE.md` Status and AI-tooling note at a turn boundary (hires, patterns run, models used, research authorized); keep my `PLANNING.md` row current; append my three registry rows to `CASTING.md` after "hiring go"; create `decisions/` directory. | `./CLAUDE.md`, `../PLANNING.md` row, `../CASTING.md` rows | Team-lead, consistency pass | — |
26	
27	Order: S1 → S2 → S3 → S4 → S5 → S6 (S6 optional). T1 runs alongside. Every pattern run ends in a file under `01-product-industry-research-design/decisions/` — chat is not the record.
28	
29	## 2. Hire roster (3 hires — matches the suggested cast; I am first in arrival order, so the full palette is available)
30	
31	All three: `model: sonnet`, read-only tools (Read, Grep, Glob, Bash), no file ownership — they return prose to me and I write the artifacts. No first name collides with a lead (Dana, Naomi, Marcus, Renata, Theo, Priya) or with each other. Roster spans both temperament axes (serious↔playful, cautious↔bold). Imogen supplies one of the org's required `playful + bold` seats.
32	
33	### 2.1 Imogen Hale — Storyteller — function: narrative counterpart and framing proponent
34	
35	- **Archetype:** Storyteller. **Tags:** `playful`, `bold`. **Slug:** `imogen-hale`.
36	- **Function:** holds and argues the framing position in S2 so I can synthesize rather than defend my own thesis; drafts the README-facing one-paragraph version of the thesis; rotating-advocate seat in S3's follow-up.
37	- **Patterns & role:** Structured written debate — *Position* (S2). Rotating devil's advocate — rotating *Objection* seat (S5 alternate).
38	- **Persona (CASTING.md §4 order, 138 words):**
39	
40	> Warm, quick-to-metaphor product storyteller who opens a review by asking whose day this changes, and only then looks at the design. Decides by drafting the README paragraph first: if a feature's story can't be told in one paragraph to a support analyst, she treats the design as unfinished. Pushes back on framings only an insider would find persuasive, and on "the evaluators will get it" as a reason to skip the explanation. Eight years as a product manager on a consumer fintech onboarding team, then four writing developer-facing docs and launch narratives at a mid-size API company. Reads API contracts and sequence diagrams comfortably; does not write production code. Blind spot: charming beats correct — she will polish a narrative past the point where the facts still hold it up, so pair her with whoever asks for the number. In disagreement she restates the other side's story better than they told it, then says exactly where hers differs.
41	
42	### 2.2 Desmond Okafor — Spreadsheet — function: claims auditor (my temperament opposite — required by variance rule 3)
43	
44	- **Archetype:** Spreadsheet. **Tags:** `serious`, `cautious`. **Slug:** `desmond-okafor`.
45	- **Function:** audits every claim in the three docs for evidence (S1); rotating-advocate seat on the UX notes (S5); the standing "where is the number?" check on both S2 positions before I synthesize.
46	- **Patterns & role:** Claims audit (S1 — a one-hire review, not a catalog pattern; artifact is the table). Rotating devil's advocate — *Objection* seat (S5). Structured written debate — *pre-synthesis fact check*, 1 turn, not a debate participant.
47	- **Persona (147 words):**
48	
49	> Dry, precise analyst who arrives with a table and distrusts any sentence carrying an adjective it can't cash. Quiet in a meeting until someone says "measurably" or "large market," then asks for the number, the source, and the date. Decides by keeping a two-column sheet — claim, evidence — and will not move a claim into a deliverable until the evidence column is filled or the claim is softened to what the evidence supports. Pushes back on narrative momentum, unsourced market sizing, and "everyone knows." Ten years in competitive-intelligence and pricing analysis at an enterprise software vendor, then three as a research analyst covering identity and access management at an industry-analyst firm. Treats vendor whitepapers as marketing until proven otherwise; fluent in SQL and spreadsheets, not a programmer. Blind spot: measures only what is measurable — he discounts true qualitative insight when it has no number, so pair him with the storyteller. Unemotional in disagreement; concedes instantly to a source, never to volume.
50	
51	### 2.3 Tobias Lindqvist — Designated Skeptic — function: framing rebuttal and standing objection
52	
53	- **Archetype:** Designated Skeptic. **Tags:** `serious`, `bold`. **Slug:** `tobias-lindqvist`.
54	- **Function:** writes the rebuttal in S2 (the "contradiction, not simplification" case, and the "you are projecting intent onto the evaluators" case); first Objection seat in the rotating-advocate runs (S4).
55	- **Patterns & role:** Structured written debate — *Rebuttal* (S2). Rotating devil's advocate — *Objection* seat (S4). Because his archetype's blind spot is objections without alternatives, every turn I give him ends with "and your counter-proposal is:".
56	- **Persona (149 words):**
57	
58	> Courteous, contrarian product strategist who argues the other side by default and treats a room in agreement as a room that has stopped thinking. Decides late, after writing the strongest case against the leading option and finding it wanting; his recurring question is "what would have to be true for this to be wrong?" Pushes back on tidy framings, on any claim about what an evaluator "is really testing for," and on extension points built for futures nobody has committed to. Seven years as a strategy consultant to identity and payments vendors, then five as a principal product manager at an authentication company whose passwordless launch he argued against internally and then helped ship. Reads OAuth and WebAuthn specifications closely enough to catch a mischaracterization. Blind spot: objections without a counter-proposal — he can leave a decision weaker but not better, so the lead must ask for his alternative. In disagreement, precise and unhurried; changes his mind visibly when the argument is better.
59	
60	### 2.4 Registry rows to append to `CASTING.md` §8 after "hiring go"
61	
62	```
63	| imogen-hale | Imogen Hale | 01 | narrative counterpart / framing proponent | Storyteller | playful, bold | sonnet | structured written debate: position (S2); rotating advocate: objection (S5 alt) | 01-product-industry-research-design/profiles/imogen-hale/imogen-hale.md | .claude/agents/imogen-hale.md | queued |
64	| desmond-okafor | Desmond Okafor | 01 | claims auditor (lead's opposite) | Spreadsheet | serious, cautious | sonnet | claims audit (S1); rotating advocate: objection (S5); debate fact-check (S2) | 01-product-industry-research-design/profiles/desmond-okafor/desmond-okafor.md | .claude/agents/desmond-okafor.md | queued |
65	| tobias-lindqvist | Tobias Lindqvist | 01 | framing rebuttal / standing objection | Designated Skeptic | serious, bold | sonnet | structured written debate: rebuttal (S2); rotating advocate: objection (S4) | 01-product-industry-research-design/profiles/tobias-lindqvist/tobias-lindqvist.md | .claude/agents/tobias-lindqvist.md | queued |
66	```
67	
68	Hire mechanics follow `CASTING.md` §6 exactly (text-first `write_profile.py --output file --assets tracked --root <this dir>`, `display.autostart: false`, image path pre-declared, no `CLAUDE.md` marker; agent def from `_TEMPLATE.md`; spawn with the fixed three first actions). Portrait prompts will be head-and-shoulders studio headshots in the same style as the leads', written into each persona's `generation` block; rendering is team-lead's queue, not mine.
69	
70	## 3. Debate plan — which decisions get which pattern, and what is waste
71	
72	**Runs (in order):**
73	
74	1. **Claims audit** (S1, Desmond, 1–2 turns) — not a catalog pattern but the precondition for one: the S2 debate must argue over claims that have been checked. Artifact `decisions/claims-audit.md`.
75	2. **Structured written debate** (S2, 3 turns + synthesis) on the one decision that is genuinely mine and genuinely contestable: *is the password baseline a deliberate simplification to narrate as "before/after", or a contradiction at a passkey company, and does the framing over-reach by asserting what LoginID "is really testing for"?* Imogen writes the position (≤600 words), Tobias the rebuttal (≤600 words, ending with a counter-framing), Desmond a ≤200-word fact-check of both, then I synthesize. The synthesis is binding for `industry-framing.md` §2 and §4 and for the one-paragraph thesis the packet uses. Both positions stay in the record — LoginID is grading the reasoning, and a preserved dissent is better evidence of reasoning than a clean conclusion.
76	3. **Newcomer's question** (S3 primary, S6 secondary, 1–2 turns each) — the highest-ROI pattern in the catalog and the one that directly tests the hand-off standard. Primary target is `api-connector-design-rationale.md` because that is the file 03 has to *act* on; the framing doc is secondary because evaluators only have to *understand* it. Reader: 04's Newcomer hire, borrowed under the bounded two-party exception in `planning-approach.md` §2 (see §4). Fallback if the loan is not available when S3 is ready: a `haiku` subagent I spawn with **no project context except the file itself** — a genuinely cold reader, cheap, and within a lead's research-fan-out authority.
77	4. **Rotating devil's advocate** (S4, S5; 1 turn each; seat rotates Tobias → Desmond → Imogen so nobody becomes "the negative one") on the small product calls: the search-authorization product requirements (S4), the UX notes (S5), and — if there is a spare turn — whether `industry-framing.md` §3 (agentic identity / AAuth) earns its place at all or is scope creep dressed as context.
78	
79	**Explicitly not debated (waste):**
80	
81	- Anything the assignment text fixes: endpoint paths, JSON bodies, the `/identity` address field names, the two entities and their fields.
82	- The authn/authz *mechanism* for the API — 02's; I supply product requirements (S4) and stop.
83	- How `user_credential.method` is *modeled* — 05's, already coordinated with 02 as a lookup table; my doc asserts only that it is a real discriminator with room to grow.
84	- The OIDC `address`-claim observation in the rationale — that is a fact check (one `haiku`/low lookup of OpenID Connect Core 1.0 §5.1.1), not a debate.
85	- Red team/blue team, three hats, adversarial pair — built for security and engineering choices I do not own. Zero runs in this track.
86	- Wireframes, a design canvas, or any visual UX artifact — this is a backend assignment; `ux-notes.md` is text, one page, and stops there.
87	- Deep research to *decorate* the narrative (market-size figures, signup drop-off percentages). If a claim survives the audit only with a number nobody has, the fix is to soften the claim, not to fund a research pass.
88	
89	**Deep research I pre-authorize (leads only, per `CASTING.md` §3):** exactly one item — verify the OIDC Core `address` claim member names (`street_address`, `locality`, `region`, `postal_code`, `country`) against the specification, because 03 may reuse those names in Go structs and the rationale currently asserts the match from memory. One `haiku`/low subagent, output to `research-oidc-address-claim.md` with the source URL, recorded in my `PLANNING.md` row. Any other request from a hire is decided against the test in §3: does the answer change a decision another track depends on? For this track, almost nothing does.
90	
91	## 4. Dependencies
92	
93	**Nothing hard-blocks on 01.** First wave, in parallel with 02 and 05 (`planning-approach.md` §2). My debates should complete before 03 finalizes handlers and the connector interface — that is a scheduling preference, not a block on 03's scaffolding.
94	
95	**Provides:**
96	
97	| To | File | Nature |
98	|---|---|---|
99	| 03 | `api-connector-design-rationale.md` (after S3) | **Soft dependency** — 03 reads it before finalizing handler shapes and the connector interface, not before starting scaffolding. It is the single source of truth for field/endpoint shape; 03 does not re-derive it. |
100	| 05 | `api-connector-design-rationale.md` §1 | Read-once check that "method as discriminator" and "1-to-many profile→credential" match `multi-db-strategy.md`. Already consistent with the 02/05 lookup-table decision. |
101	| 02 | `personas-use-cases.md` search-authorization appendix (after S4) | Product input to 02's adversarial-pair run on `profile:search` vs `profile:read:own`. |
102	| Team-lead / 02 | `industry-framing.md` (after S2), `decisions/password-baseline-debate.md` | The submission thesis the README and `ai-workflow-narrative.md` should tell consistently; the consistency pass checks this. |
103	
104	**Needs:**
105	
106	| From | What | Why | Timing |
107	|---|---|---|---|
108	| 02 (Marcus) | A one-message read-only confirmation that the product requirements I assert in rationale §2 (masked-by-default results, independent rate-limiting and pagination for search, every search attributable/auditable) are compatible with `api-auth-design.md` — or the specific change so my doc does not contradict his. | Two tracks must not disagree about what search returns. | Before S3 closes. |
109	| 02 (Marcus) | The 02→04
… truncated (20 KB cap)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/profiles/desmond-okafor/desmond-okafor.md"
}

1	---
2	schema_version: 1
3	name: "Desmond Okafor"
4	slug: "desmond-okafor"
5	image: "profiles/desmond-okafor/desmond-okafor.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: "Desmond Okafor, a composed and precise man in his mid-40s with a calm, evaluating expression, closely cropped hair with a touch of gray at the temples, thin rectangular glasses, wearing a navy quarter-zip over a white collared shirt, head-and-shoulders portrait, centered, neutral light gray studio background, professional corporate headshot photography, soft studio lighting, sharp focus, photorealistic"
16	  negative_prompt: blurry, low quality, distorted, extra limbs, watermark, text, nsfw, nude, nudity, explicit, sexual content
17	  seed: null
18	  gif_mode: null
19	  created_at: "2026-09-12T00:00:00Z"
20	---
21	
22	# Desmond Okafor
23	
24	![Desmond Okafor](profiles/desmond-okafor/desmond-okafor.png)
25	
26	
27	## Personality
28	
29	Dry, precise analyst who arrives with a table and distrusts any sentence carrying an adjective it can't cash. Quiet in a meeting until someone says "measurably" or "large market," then asks for the number, source, and date. Decides by keeping a two-column sheet — claim, evidence — and will not release a claim until its evidence column is filled or the claim is softened to fit. Pushes back on narrative momentum, unsourced market sizing, and "everyone knows." Ten years in competitive-intelligence and pricing analysis at an enterprise software vendor, then three as a research analyst covering identity and access management. Treats vendor whitepapers as marketing until proven otherwise; fluent in SQL and spreadsheets, not a programmer. Blind spot: measures only what is measurable — he discounts qualitative insight that has no number, so pair him with the storyteller. Unemotional in disagreement; concedes instantly to a source, never to volume.
30	
31	

{
  "to": "naomi-voss",
  "content": "Desmond here. Read root CLAUDE.md, track CLAUDE.md, PLAN.md, and my persona file. Staged and ready for S1 — claims audit of industry-framing.md, personas-use-cases.md, api-connector-design-rationale.md, cross-checked against the two research-*.md files. Will return a claim/where/evidence/status/softer-wording table, project sources only, and flag anything needing outside research to you rather than chase it myself. Holding for your call."
}

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

{
  "command": "ls *.md"
}

api-connector-design-rationale.md
CLAUDE.md
industry-framing.md
personas-use-cases.md
PLAN.md
research-loginid-company.md
research-oauth-history.md
research-oidc-address-claim.md

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/industry-framing.md"
}

1	# Industry & Competitive Framing
2	
3	Prepared for the `01-product-industry-research-design` track. See `../CLAUDE.md` for the full assignment text and `./CLAUDE.md` for this track's scope and boundaries. Builds directly on `research-loginid-company.md` and `research-oauth-history.md` in this directory — read those first for sourcing; this document is the synthesized argument, not new research.
4	
5	**AI tooling note:** produced by Claude Code (Sonnet 5) running as a standing track-owner subagent for this track (persona: Naomi Voss), reading this track's own CLAUDE.md as its brief and the two prior research passes as its evidence base. No new web research was done for this document — it is a synthesis pass over material already gathered.
6	
7	## Who is this for
8	
9	Two audiences read this document, and the framing below is written to serve both without contradiction:
10	
11	1. **LoginID's technical evaluators.** They already know their own market. What they're grading here is whether a candidate can place a deliberately simple assignment (password-based credentials, a bare username/password IDP connector) accurately on the map of where the industry actually is — and say so plainly rather than either quietly building an insecure relic or over-engineering a FIDO2 flow nobody asked for.
12	2. **Whoever would actually consume this system if it were built for real** — an internal team building a profile-search admin tool, or a product team wiring up an onboarding flow that calls out to a third-party IDP connector. This document's persona/use-case section (see `personas-use-cases.md`) exists because "who is this for" has a real answer beyond the interview panel, and that real answer should shape the design.
13	
14	## 1. Where this assignment sits in the identity/IAM landscape
15	
16	The three questions asked — a DAO for `user_profile`/`user_credential`, a searchable REST API over that data, and a connector to third-party identity providers using `/auth` (username/password → token) and `/identity` (token → PII) — describe a **classic CIAM (Customer Identity and Access Management) backend**: the boring, load-bearing plumbing that sits underneath every "log in" button. This space is large, mature, and crowded:
17	
18	- **Full-platform CIAM**: Okta/Auth0, Microsoft Entra ID, Ping Identity — passwordless is one feature among many (SSO, MFA, lifecycle management, B2B federation).
19	- **Passkey/FIDO2 specialists**: LoginID itself, HYPR, Beyond Identity, Transmit Security, Corbado, Hanko, Descope — narrower, deeper on one authentication method.
20	- **IDP-aggregation/identity-verification vendors**: services whose entire business is "collect PII from a person once and let many relying parties query it" — the same shape as the assignment's `/identity` endpoint, at a bigger scale.
21	
22	The assignment sits at the intersection of the first and third categories, but built at the "baseline reference implementation" layer rather than the polished-product layer — which tracks with the assignment's own instructions that code doesn't need to be complete, and that reasoning matters more than a finished product.
23	
24	## 2. The deliberate gap: what LoginID sells vs. what LoginID is asking for
25	
26	This is the framing that most needs to be said out loud, because it's easy to miss and, once seen, it reframes the whole submission.
27	
28	LoginID's actual product is FIDO2/WebAuthn passkey authentication: asymmetric device-bound credentials unlocked by biometrics, with **no shared secret ever transmitted or stored server-side** (see `research-loginid-company.md` §1). The assignment, by contrast, specifies:
29	
30	- `user_credential (username, method, password)` — a shared-secret password field, the exact thing passkeys exist to eliminate.
31	- A third-party `/auth` endpoint authenticating with `{"username", "password"}` — a legacy password-grant pattern, not an OAuth2/OIDC delegated-authorization flow.
32	
33	**This is almost certainly intentional, not an oversight in the assignment's wording.** LoginID is testing whether a candidate can:
34	
35	- **Name the gap explicitly** rather than silently building an insecure password store as if it were best practice, or silently substituting a FIDO2 flow the assignment didn't ask for (which would answer a different question than the one asked).
36	- **Design the seams so the gap is closeable later without a rewrite.** The `user_credential.method` field is the natural extension point — a value like `"password"` today, `"webauthn"` or `"passkey"` tomorrow, without changing the table shape. The third-party connector's pluggable-provider design (see `api-connector-design-rationale.md`) is the equivalent seam on the IDP side — a modern OIDC/OAuth2 provider should slot in next to the ABC/XYZ password-grant providers without a redesign.
37	- **Still handle what's actually being asked with the rigor the brand implies** — hashed/salted passwords at minimum if a password field must exist at all, least-privilege API auth on search/retrieve, secrets hygiene for stored third-party access tokens. (Full mechanics of this are `../02-ai-security-architecture/CLAUDE.md`'s scope; this document only asserts the product-narrative reason it matters — LoginID's whole brand *is* auth security, so an unhashed password field in the reference implementation, however illustrative, would read as tone-deaf.)
38	
39	In short: **the assignment's design is the "before" picture; LoginID's product is the "after" picture.** The strongest submission narrative is "here is a solid, honestly-scoped baseline for the before, with the seams marked for exactly where it evolves toward the after" — not pretending the gap doesn't exist, and not solving a harder problem than was asked.
40	
41	## 3. The adjacent frontier: agentic identity, and why it's relevant but out of scope
42	
43	Two things are converging on LoginID's roadmap that are each worth naming, but neither should be built into this submission's actual code:
44	
45	- **LoginID's own 2025–2026 repositioning** toward "agentic commerce" — authenticating AI agents transacting on a human's behalf, with scoped/signed/revocable mandates (`research-loginid-company.md` §1, §3). This is company-stated strategy, not independently confirmed, and it's a genuine pivot from "passkey login for any site" to "identity/payment-authorization layer for AI agents."
46	- **AAuth / the broader machine-identity protocol space** (`research-oauth-history.md`) — a proposal (Dick Hardt, editor of OAuth 2.0/RFC 6749, not a co-author of OAuth 1.0/RFC 5849 — see that document for why the precise credential matters) addressing a different layer of the stack: authorizing *HTTP clients/agents* to services, versus FIDO2's job of authenticating *humans* to services. The two are complementary, not competing — a mature identity platform plausibly needs both, with passkey-based human authentication anchoring the root of trust that agent-identity protocols delegate from.
47	
48	**Relevance to this assignment:** the same critique AAuth levels at static, pre-registered client credentials (API keys that leak, no portable identity, one-time upfront consent rather than per-request authorization) applies loosely to why a third-party-IDP connector built as a static username/password integration is a deliberately dated pattern — and why the connector's provider abstraction should be designed with an eye toward OAuth2/OIDC-style delegated flows as the natural next step, the same way `user_credential.method` is the seam for FIDO2 on the human-authentication side.
49	
50	This belongs in the write-up as forward-looking context, not as scope creep — nobody asked for an agent-identity protocol implementation, and building one would bury the actual assignment under speculative complexity. One paragraph in the submission's narrative, pointing at the seam, is the right amount of ambition.
51	
52	## 4. Competitive takeaway for the submission's narrative
53	
54	Framed as a one-line thesis for whoever reads the final packet: *this submission is a correctly-scoped, honestly-labeled "before" implementation of exactly what was asked, built with explicit extension points toward the "after" — FIDO2/passkey credentials, OIDC-style IDP federation, and (further out) agent-identity delegation — because that's the same intellectual move LoginID's own product makes at industry scale, and it's the move this exercise is actually testing for.*
55	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/personas-use-cases.md"
}

1	# Personas & Use Cases
2	
3	Prepared for the `01-product-industry-research-design` track. See `../CLAUDE.md` for the full assignment text and `./CLAUDE.md` for this track's scope. Ties directly back to the three assignment questions and to `industry-framing.md` in this directory.
4	
5	**AI tooling note:** produced by Claude Code (Sonnet 5), track-owner subagent persona Naomi Voss, as a design-reasoning pass over the assignment text and this track's prior research — no new external research for this document.
6	
7	"Who is this for" comes before "how do we build it" — so each persona below is answered before the corresponding assignment question is treated as a design problem.
8	
9	## Persona 1: The internal service developer (drives Q1 — the DAO)
10	
11	**Who:** an engineer on a different internal team — say, an onboarding flow, a support tool, or a billing system — who needs to read or write a user's profile or credential record, but should never touch SQL or know which database backend is in play this quarter.
12	
13	**Why they need this:** the assignment explicitly requires multi-database support (PostgreSQL/CockroachDB, SQLite, etc. — see root `CLAUDE.md`). That requirement only makes sense if there's a real reason the backing store might change: a startup prototyping on SQLite that needs to graduate to CockroachDB for multi-region durability without a data-layer rewrite, or a team standardizing on Postgres while a legacy service still runs SQLite. The DAO's job is to make that migration invisible to every consumer like this persona — they call `GetUserProfile(id)`, not `SELECT * FROM user_profile WHERE id = $1`.
14	
15	**What this means for Q1's design:** the DAO's interface is the product, not the SQL underneath it. It should be judged on whether a consumer can be written against the interface alone, never learning which database is live. `user_credential.method` existing as a field (not assumed to always be `"password"`) is this persona's forward-compatibility guarantee — when passkeys get added, this developer's code that reads `user_credential.method` to branch on auth type doesn't need to change shape, only add a case.
16	
17	## Persona 2: The support/ops analyst using the search API (drives Q2 — the REST service)
18	
19	**Who:** a customer-support agent or fraud/ops analyst who needs to look up a user profile by partial information — a phone number a customer just read aloud, a name with uncertain spelling, an account ID from a ticket — to resolve a support case or investigate a flagged transaction. Not a developer; a consumer of a UI/API surface someone else built on top of this service.
20	
21	**Why they need "search," specifically, not just "retrieve":** retrieval-by-ID is the easy 80%; a support workflow rarely starts with a clean ID. It starts with whatever the customer said on the phone. That's why Q2 says "search **and** retrieve" — the API needs a query surface (name, phone, partial match) in addition to an exact-key lookup, and that query surface is exactly the thing that needs the tightest authz scoping, because "search by phone number" over a PII store is also the exact capability a bad actor wants.
22	
23	**What this means for Q2's design:** the API's authentication isn't just "is this caller allowed to hit the service" — it's "what can this caller search for and see," because a support analyst's legitimate access pattern (look up one ticket's customer) looks identical, mechanically, to a scraping attack (enumerate the user table) unless the API is designed to distinguish them by identity, scope, and rate — the mechanics of which belong to `../02-ai-security-architecture/CLAUDE.md`, but the *reason* the distinction matters is this persona: a real support tool has real, narrow, audited search needs, not "return everything."
24	
25	**Secondary persona for Q2 — the admin/back-office console.** Per this track's "does not own" boundary, this is light-touch: if a UI ever sits on top of the search API, it's an internal console for exactly Persona 2's workflow — a search box, a result list with masked PII by default (full PII visible only on deliberate expand + audit log entry), and no bulk-export button. That's a UX rationale note, not a wireframe deliverable for this backend-focused assignment.
26	
27	## Persona 3: The onboarding product owner needing third-party PII (drives Q3 — the IDP connector)
28	
29	**Who:** a product owner building a signup/onboarding flow for a service that wants to pre-fill a new user's name, phone, and address rather than making them type it — because the user already has an account with a partner identity provider (the generic "ABC"/"XYZ" in the assignment), and re-typing the same PII into every new service is friction the industry has been trying to design away since long before OAuth existed (see `research-oauth-history.md` for that lineage).
30	
31	**Why a service pulls PII from a third party rather than owning it:** two converging reasons, both real. First, **reduced liability and reduced collection surface** — a service that never independently collects and stores a user's address avoids being a second copy of that PII to secure and eventually breach; it becomes a consumer of an assertion instead of a second source of truth (this is the same reasoning behind "federated identity" broadly — don't collect what you can verify from someone who already has it). Second, **conversion/UX** — fewer form fields at signup measurably reduces drop-off, which is why "sign in with X" patterns dominate consumer onboarding.
32	
33	**What this means for Q3's design:** the `/auth` → `/identity` two-step (get a token, then use the token to fetch PII) is the connector pattern doing exactly what it should — a **short-lived, scoped credential** stands in for the user's actual third-party password, so the calling service never sees or stores that password, only a token it can use for the narrow purpose of one identity lookup. The design rationale for treating `ABC`/`XYZ` as pluggable providers behind a common connector interface (rather than two bespoke integrations) is in `api-connector-design-rationale.md` — but the product reason it must be pluggable is this persona: onboarding flows routinely need to support more than one partner IDP, and adding "sign in with a third provider" should be an integration, not a redesign.
34	
35	## Cross-cutting observation
36	
37	All three personas share one property worth stating plainly: **none of them are the end user whose data this is.** The person whose name/phone/address sits in `user_profile`, and whose credential sits in `user_credential`, never directly calls any of these three interfaces — a developer, a support analyst, and a product owner do, on that person's behalf (with consent, in the legitimate cases). That's precisely why authz-by-caller-identity (not just authn) matters throughout, and why the third-party connector's job is explicitly framed as retrieving *someone else's* PII by proxy — the trust boundary is the whole point of the design, not an afterthought bolted onto a CRUD service.
38	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/api-connector-design-rationale.md"
}

1	# API & Connector Design Rationale
2	
3	Prepared for the `01-product-industry-research-design` track. See `../CLAUDE.md` for the full assignment text and `./CLAUDE.md` for this track's scope. Written so `../03-engineering-delivery/CLAUDE.md` can implement against it directly, without re-deriving the reasoning — that's this document's explicit job per the track brief. Builds on `industry-framing.md` and `personas-use-cases.md` in this directory; read those for the "why," this document is the "so build it this way."
4	
5	**AI tooling note:** produced by Claude Code (Sonnet 5), track-owner subagent persona Naomi Voss, as a design-reasoning pass — no new external research; synthesizes the assignment text plus this track's prior work.
6	
7	This document covers three surfaces in the order the assignment presents them: the `user_profile`/`user_credential` data contract (Q1), the search/retrieve REST API (Q2), and the third-party IDP connector (Q3).
8	
9	## 1. Data contract: `user_profile` and `user_credential`
10	
11	**Why two separate entities, not one row:** the assignment names them separately, and that separation is doing real work, not just organizing fields. `user_profile` is PII a service holds *about* a person (name, address, phone) — data with governance obligations (retention, right-to-deletion, breach-notification exposure) attached to `../05-data-ops/CLAUDE.md`'s scope. `user_credential` is a proof-of-identity mechanism the service uses *to authenticate* that person — a username, an auth `method`, and (for the password method) a secret. Conflating them into one table would mean every profile read touches the credential store and vice versa, which is exactly the wrong blast radius for a credential breach.
12	
13	**Why `user_credential.method` matters as a design decision, not just a column:** per `industry-framing.md` §2, this field is the seam where the assignment's deliberately simple password baseline becomes extensible toward what LoginID actually sells (FIDO2/passkey, `method = "webauthn"`) without a schema rewrite. Concretely: `method` should be treated as a discriminator that governs which other fields on the row are meaningful — a `"password"` row has a password hash; a future `"webauthn"` row would have a public key and credential ID instead, not a password field left null by convention. Whether that's modeled as one wide table with nullable method-specific columns or a base table plus method-specific side tables is an implementation choice for `../03-engineering-delivery/CLAUDE.md` and `../05-data-ops/CLAUDE.md` — the product requirement this document is asserting is only that **`method` must be a real discriminator with room to grow, not a fixed enum assumed to always be `"password"`.**
14	
15	**One relationship, not two independent tables:** a `user_profile` and its `user_credential`(s) need a stable foreign key (one profile can plausibly have more than one credential — a password today, a passkey added later, without replacing the old one until migration is complete). Designing for 1-to-many from the start avoids a breaking migration the day a second auth method is added.
16	
17	## 2. REST API: search and retrieve
18	
19	**Endpoint shape, from the personas in `personas-use-cases.md`:**
20	
21	- `GET /profiles/{id}` — exact retrieval by primary key. Serves any caller who already has the ID (the common, low-risk case).
22	- `GET /profiles?name=&phone=&...` (or `POST /profiles/search` if the query needs to carry more structure than fits cleanly in query params, e.g. partial-match flags) — the search surface Persona 2 (support/ops analyst) actually uses day to day. This is the endpoint that needs the most deliberate authz design, because "search by phone" is simultaneously the legitimate support workflow and the shape of a scraping attack.
23	
24	**Why search and retrieve are named as separate concerns in the assignment, and should stay separate in the API design:** retrieval-by-ID is nearly risk-free — if a caller has a valid ID, they likely already have a legitimate reason to look at that record. Search is different: it's a fuzzy-match query over a PII store, which means the API surface itself is the control point. Design implications this document asserts (mechanics belong to `../02-ai-security-architecture/CLAUDE.md`):
25	
26	- Search results should default to **masked/partial PII** in the response, with full-field detail requiring either a distinct, more tightly scoped call or an explicit "expand" parameter — so that a broad search doesn't silently become a bulk PII export.
27	- Search should be **rate-limited and paginated** independent of retrieval, because unbounded search is the difference between "an analyst looked up one ticket" and "someone enumerated the table."
28	- Every search call is a natural audit-log event (who searched, for what, when) even before considering who's authorized to call it at all — this is a data-governance requirement (`../05-data-ops/CLAUDE.md`) that the API design needs to leave room for (e.g., not designing a stateless-only API that makes call attribution an afterthought).
29	
30	**Why "plus security API authentication" is in the same assignment bullet as search/retrieve, not a separate question:** the assignment is signaling that the two are inseparable — a search/retrieve API over PII without an authentication design isn't a partial answer, it's a wrong one. This document asserts the product-level requirement (search needs scoped, attributable, rate-limited access, not just "logged in"); the actual authn/authz mechanism (API keys vs. OAuth2 client-credentials vs. mTLS, token formats, scope models) is `../02-ai-security-architecture/CLAUDE.md`'s to design.
31	
32	## 3. Third-party IDP connector: `/auth` and `/identity`
33	
34	The assignment specifies exact contracts for both endpoints (see root `CLAUDE.md` — `/auth` takes `{"username", "password"}` and returns an `access_token`; `/identity` takes `{"phone", "name"}` and returns PII including a structured address). The design rationale here is about *why* that shape makes sense and *how to build the connector so it isn't hostage to any one provider's quirks* — not about re-specifying the contract, which is already fixed.
35	
36	**Why the two-call shape (`/auth` then `/identity`) is the right pattern, per Persona 3:** it's a minimal, legacy-style token-exchange flow — trade a long-lived credential (username/password) for a short-lived, purpose-scoped token, then use that token for the actual data pull. This is structurally the same shape as OAuth2's resource-owner-password-credentials grant (the *deliberately old-fashioned* member of the OAuth2 grant family, notably the one most identity providers now discourage in favor of authorization-code or client-credentials flows — see `research-oauth-history.md` for the OAuth lineage this pattern sits in). Recognizing that lineage matters for the write-up: this connector contract is not a novel design, it's a well-understood, slightly dated pattern, being asked for deliberately (see `industry-framing.md` §2 for why "deliberately dated" is the right read, not an oversight).
37	
38	**Why the connector must be built provider-agnostic (ABC/XYZ as instances of one interface, not two bespoke integrations):** the assignment names the providers generically on purpose — this is a request to design *a connector interface*, with ABC and XYZ as its first two implementations, not to hardcode either one. Concretely, that means:
39	
40	- A common internal interface — something like `Authenticate(username, password) → token` and `FetchIdentity(token, phone, name) → PII` — that both ABC and XYZ adapters satisfy, so adding a third provider is "write an adapter," not "touch the calling code."
41	- Each provider adapter owns its own quirks (token expiry format, field-name differences, rate limits, error codes) behind that common interface — the calling code (the onboarding flow from Persona 3) never branches on which provider it's talking to.
42	- The interface's shape should anticipate that a future provider might not be username/password-based at all — an OAuth2/OIDC provider would satisfy `Authenticate` differently (redirect-based auth-code exchange instead of a direct password POST) but still ultimately produce a token this connector can use the same way for `FetchIdentity`. This is the connector-side equivalent of `user_credential.method`'s extensibility from §1 — flagged here, not built here, per `industry-framing.md`'s point about not burying the actual assignment under speculative scope.
43	
44	**Field-mapping note (product-level, not implementation):** the assignment's `/identity` response splits address into `street_address`, `locality`, `region`, `postal_code`, `country` — this is recognizably the OpenID Connect `address` claim shape (a widely-used standard structure for exactly this purpose), which is a useful fact for the write-up: it signals the assignment's own contract is already leaning on real industry convention rather than an arbitrary shape, which is worth naming explicitly as evidence of "this connector is meant to look like a real federated-identity integration," reinforcing the design choices above.
45	
46	## Summary for the engineering track
47	
48	Three seams to build with deliberately, per this document: `user_credential.method` as a real discriminator (not a fixed enum), a search API designed around masked-by-default results + rate limiting + audit logging (not just an authenticated GET), and a provider-agnostic connector interface with ABC/XYZ as its first two adapters (not two copy-pasted integrations). Each seam is where this "before" baseline visibly points toward the "after" — passkeys, scoped search, and modern federated-identity providers — without this submission having to build any of the "after" itself.
49	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/research-loginid-company.md"
}

1	# LoginID: Company & Industry Research
2	
3	Prepared for the `01-product-industry-research-design` track. See `../CLAUDE.md` for the assignment text and `./CLAUDE.md` for this track's scope. AI tooling note: this research was produced by a Claude Code subagent (Sonnet 5) using WebSearch and WebFetch against public sources — LoginID's own site (`loginid.ai`, formerly `loginid.io`), the FIDO Alliance directory, Crunchbase, and independent trade press/blog coverage. Citations are inline; sourcing is flagged as **[Marketing]** (LoginID's own site/press), **[Independent]** (third party, not paid placement), or **[Aggregator]** (data broker sites like Crunchbase/ZoomInfo/The Org — generally reliable for basic facts like dates and titles, but not verified primary sources).
4	
5	## 1. What LoginID sells
6	
7	LoginID is a FIDO2-certified passwordless/passkey authentication platform, sold as SDKs and a headless "FIDO Server" that developers and enterprises integrate via API. **[Marketing]** Per the FIDO Alliance's own certified-solution directory, LoginID provides "a comprehensive FIDO-based multifactor authentication solution that offers frictionless authentication," with mobile SDKs (iOS/Android) for biometric registration, login, and transaction confirmation, plus a backend FIDO Server that handles the cryptographic/attestation operations. ([FIDO Alliance](https://fidoalliance.org/company/loginid/)) This is a moderately independent listing in the sense that FIDO Alliance vets certification claims, though the descriptive text itself is member-supplied.
8	
9	Core capabilities as described on their site: **[Marketing]**
10	
11	- Passkey-based authentication using FIDO2/WebAuthn (device-bound credentials, unlocked by biometrics or device PIN — no shared secret transmitted or stored server-side)
12	- "Digitally-signed transaction authorization" — using the same passkey as a signing key for transaction non-repudiation, not just login, which they position as differentiating for regulated/financial use cases
13	- Compliance framing: NIST AAL2 assurance level, SOC 2, PSD2 Strong Customer Authentication (SCA)
14	- Developer-facing APIs/SDKs meant for rapid integration, pitched at "low operational cost" and reduced fraud/improved conversion vs. password+OTP flows
15	
16	Notably, the company appears to have repositioned in 2025–2026 around "agentic commerce" — authenticating AI agents transacting on a human's behalf. **[Marketing]** The current `loginid.ai` homepage frames the product as turning "anonymous agents into known customers," with "scoped, signed, revocable mandates" limiting what an AI agent can spend (by amount, merchant category, intent), an MCP (Model Context Protocol) server so agent frameworks (ChatGPT, Claude, Gemini, Copilot, Perplexity) can call it directly, and integration with payment processors (Stripe, Adyen, Visa, Mastercard). ([loginid.ai](https://loginid.ai/)) This is a genuine pivot/rebrand from "passkey login for websites and apps" (the `loginid.io` positioning, still reflected in the FIDO Alliance listing) to "identity and payment-authorization layer for AI-agent commerce" — worth flagging explicitly as a company-stated evolution rather than an independently confirmed strategy shift, since it comes entirely from their own marketing site.
17	
18	**Target customers**, per their own materials: developers building consumer or fintech apps who don't want to build authentication infrastructure themselves; e-commerce merchants who want to keep a direct relationship with agent-driven shoppers rather than being disintermediated; and regulated industries (fintech/payments) needing PSD2 SCA-compliant, legally defensible transaction signing. **[Marketing]** An independent competitor-comparison blog (Corbado, itself a LoginID competitor, so read as opinionated) characterizes LoginID similarly from the outside: "a reliable FIDO2-certified identity provider, particularly known for its focus on security, privacy, and compliance," best suited to "regulated industries or companies seeking legally binding authentication," but — in Corbado's view — "lacks the advanced tooling, developer flexibility, and UX optimization required for large-scale consumer-facing deployments" (no fallback orchestration, limited adoption analytics, limited onboarding customization). **[Independent, but vendor-interested]** ([Corbado blog](https://www.corbado.com/blog/best-login-id-alternatives))
19	
20	## 2. Founders
21	
22	**Simon Law — Co-Founder and CEO.** **[Aggregator, cross-referenced]**
23	- B.Eng, Computer Engineering, University of Waterloo (1999–2004)
24	- Founded SALT Technology (formerly Admeris Payment Systems) in 2007, serving as CEO through 2012 and then CTO; SALT built a mobile/e-commerce payment processor and patented the "OneTouch" mobile checkout flow — directly relevant lineage to LoginID's later "one-touch biometric authentication" branding
25	- Director at Visa, Dec 2014 – Aug 2018
26	- Co-founded LoginID in Oct 2018 (company frequently cited as "founded 2019," likely reflecting incorporation/launch vs. founding date)
27	- Sources: [Crunchbase person profile](https://www.crunchbase.com/person/simon-law), [The Org](https://theorg.com/org/loginid/org-chart/simon-law), [RocketReach](https://rocketreach.co/simon-law-email_47385) — these are data-aggregator profiles, not primary interviews, so treat specific dates as approximate.
28	
29	**Jim Brown — Co-Founder and Chief Revenue Officer.** **[Aggregator]** Named in a company press release as CRO in an Algorand Foundation grant announcement (see below), corroborating the Crunchbase co-founder listing. ([Crunchbase](https://www.crunchbase.com/person/jim-brown-a287); [PR Newswire](https://www.prnewswire.com/news-releases/algorand-foundation-announces-grant-to-loginid-301394622.html))
30	
31	**Pasan Hapuarachchi — CTO / Chief Architect.** **[Aggregator]** Listed in third-party company/executive databases (Craft.co, Crunchbase people page); not independently corroborated by a primary LoginID source in this research pass, so treat with slightly lower confidence than Law and Brown.
32	
33	I could not find a substantive founder interview, podcast, or first-person "why we started this" narrative in this pass — searches for "Simon Law LoginID interview passkeys" surfaced only aggregator profiles and unrelated FIDO Alliance/industry interviews (e.g., the FIDO Alliance's own CEO, not LoginID's). The clearest signal of founder motivation is inferential: Law's background at a payments company (SALT/Admeris) and at Visa strongly suggests the founding thesis was "apply frictionless mobile-checkout UX thinking to authentication generally, then specifically to payments/fintech" — consistent with LoginID's transaction-signing and PSD2-SCA emphasis, and with the 2025-era pivot toward agentic commerce/payments. This is my inference from the pattern of facts, not a claim any LoginID source makes directly — flagged as such.
34	
35	## 3. Company history, funding, milestones
36	
37	- **Founded:** Simon Law + Jim Brown, Oct 2018 (LoginID frequently dated to 2019 in aggregator listings). **[Aggregator]**
38	- **Headquarters:** San Mateo, California. **[Aggregator]**
39	- **Funding, per Crunchbase:** **[Aggregator]**
40	  - Pre-Seed round (date/amount not resolved in this pass) — [Crunchbase](https://www.crunchbase.com/funding_round/loginid-pre-seed--85928edd)
41	  - Seed round, Oct 31, 2019: $3.4M — [Crunchbase](https://www.crunchbase.com/funding_round/loginid-seed--4d4d5a7b)
42	  - Seed round, Sep 1, 2020: $692,500 — [Crunchbase](https://www.crunchbase.com/funding-round/3d780ace-ef02-4798-843a-5ace0e897c3a)
43	  - Corporate round, Jun 1, 2021, amount undisclosed — [Crunchbase](https://www.crunchbase.com/funding_round/loginid-corporate-round--8c359820)
44	  - A grant round is also listed — [Crunchbase](https://www.crunchbase.com/funding_round/loginid-grant--aefa7d70), consistent with the Algorand grant below.
45	  - Named investors include George Wallner, Fabrice Grinda, Damien Balsan, RMKB Ventures, and Algorand Foundation (12 investors total per Crunchbase's count). I was blocked from reading the full Crunchbase org page directly (403), so this investor list is reconstructed from search-result summaries of Crunchbase data, not a direct page read — treat as reasonably reliable but not verbatim-verified.
46	- **Algorand Foundation grant, announced Oct 7, 2021 (amount undisclosed):** funded LoginID to build APIs/SDKs letting Algorand developers add FIDO-certified biometric auth for one-touch smart-contract execution, no plugin/download required. CRO Jim Brown, quoted: "Algorand has really started to accelerate, helping businesses in the DeFi and commerce space... LoginID will help lower friction, and make blockchain technology easier to interact when developers integrate our solution." **[Marketing/press release, but names are corroborating]** ([PR Newswire](https://www.prnewswire.com/news-releases/algorand-foundation-announces-grant-to-loginid-301394622.html))
47	- **NFT PRO partnership** (2021), per a PR Newswire release title surfaced in search — not independently examined in depth in this pass. **[Marketing]**
48	- **FIDO Alliance membership and passkey-spec contribution:** LoginID states it is "a contributor to the original FIDO Passkey spec and FIDO Alliance member." **[Marketing, plausible given FIDO Alliance directory listing]**
49	- **Apparent repositioning, ~2025–2026:** shift in public-facing messaging from generic "FIDO2 passwordless login for any site/app" (loginid.io) to "identity/payment-authorization trust layer for AI agentic commerce" (loginid.ai), including MCP server support for LLM agent frameworks and blog content specifically targeting fintech passkey buyers (e.g., "Best Passkey Authentication Providers for Fintech (2026)"). **[Marketing]** This reads as the company riding two successive hype cycles — blockchain/DeFi (2021 Algorand grant) and now agentic AI commerce (2025-26) — while the underlying FIDO2/WebAuthn authentication core stays constant. Framed neutrally: a small vendor adapting its go-to-market narrative to whichever adjacent trend is attracting enterprise budget, on top of a stable technical foundation.
50	
51	## 4. Industry context: passwords → passwordless → passkeys
52	
53	- **2012:** FIDO Alliance founded (PayPal, Lenovo, Validity Sensors, Nok Nok Labs, Agnitio, Infineon) to reduce reliance on passwords via open, interoperable authentication standards. **[Independent]**
54	- **2015 onward:** FIDO Alliance and W3C collaborate to bring FIDO's public-key-based challenge/response model to the open web as the WebAuthn specification.
55	- **March 4, 2019:** W3C and FIDO Alliance jointly announce WebAuthn as an official W3C web standard (Level 1). FIDO2 = WebAuthn (browser/platform API) + CTAP (Client-to-Authenticator Protocol, e.g., for external security keys). This is the moment "passwordless login" became something any website could implement against a standard rather than a proprietary vendor SDK. **[Independent]** ([W3C press release](https://w3.org/press-releases/2019/webauthn); [FIDO Alliance](https://fidoalliance.org/w3c-and-fido-alliance-finalize-web-standard-for-secure-passwordless-logins/))
56	- **April 2021:** WebAuthn Level 2 published. **[Independent]**
57	- **May 2022:** Apple, Google, and Microsoft jointly commit to expanded FIDO support — specifically, syncing FIDO credentials ("passkeys") across a user's devices via platform cloud services (iCloud Keychain, Google Password Manager, etc.) and enabling cross-device sign-in (scan a QR code on a desktop, authenticate via phone). This is the moment FIDO2 credentials went from "one security key/device per registration" to "a synced passkey usable across a person's whole device ecosystem" — the platform-level UX shift that made passkeys viable for mainstream consumer products, not just enterprise/security-key use cases. **[Independent]** ([Apple newsroom](https://www.apple.com/newsroom/2022/05/apple-google-and-microsoft-commit-to-expanded-support-for-fido-standard/))
58	- **2023 onward:** Major consumer platforms (Google, Apple, PayPal, Microsoft accounts, GitHub, etc.) roll out passkey login broadly; industry surveys through 2025-2026 report accelerating enterprise adoption (one cited figure: 87% of surveyed enterprises deployed or deploying passkeys). **[Independent, but figures come from vendor-sponsored surveys — treat adoption percentages as directional, not precise]**
59	
60	**Where LoginID sits competitively:** LoginID is a small, standards-compliant FIDO2/WebAuthn vendor competing in a crowded CIAM/passwordless space that includes much larger identity platforms with passwordless as one feature among many (Okta/Auth0, Microsoft Entra ID, Ping Identity), and other passkey-focused specialists (HYPR, Beyond Identity, Transmit Security, Corbado, Hanko, Descope, Yubico for hardware keys). Its stated differentiators — transaction-signing (using the passkey as a non-repudiation signature, not just a login gate), PSD2/SCA and NIST AAL2 compliance framing, and payments/fintech focus — target a narrower niche than the big CIAM platforms' "authenticate everything for everyone" positioning. Independent commentary (from a competitor, so weighted accordingly) suggests LoginID trades consumer-scale UX tooling and analytics depth for that compliance/regulated-industry focus. **[Independent, vendor-interested]**
61	
62	## 5. Relevance to this take-home
63	
64	LoginID's core competency is passkey/FIDO2 authentication — asymmetric-key, device-bound, biometric-gated credentials that eliminate shared secrets entirely. The assignment's three questions (a DAO storing `user_credential` with a **password** field, a REST API to search/retrieve profile data, and a connector to third-party IDPs using **username/password → access_token** flows) deliberately describe the *opposite* of what LoginID sells: a legacy, password-based credential model and a legacy IDP-connector pattern (`POST /auth {username, password}`) rather than a FIDO2/WebAuthn ceremony.
65	
66	That is almost certainly the point of the exercise, not an oversight. LoginID is evaluating whether a candidate can:
67	
68	1. **Recognize the gap** between "the industry-standard secure way to do this" (passkeys, no server-side password, no shared secret) and "the assignment as literally specified" (password field, username/password connector auth) — and say so explicitly rather than silently building an insecure password store, or silently over-engineering a FIDO2 flow the assignment didn't ask for.
69	2. **Design for extensibility toward LoginID's actual world.** The `user_credential.method` field in Q1 and the pluggable-connector shape in Q3 are natural seams where a FIDO2/passkey credential type, or a modern OIDC/OAuth2 IDP connector, could be added later without a redesign — which is exactly the kind of "architect, not just coder" thinking LoginID says it's grading for (per the root `CLAUDE.md`: "design and reasoning... more than three coding questions").
70	3. **Handle credential/PII data the way a company whose entire brand is auth security would expect** — hashed/salted passwords at minimum if a password field must exist at all, TLS/secrets hygiene for the IDP connector's stored access tokens, and least-privilege API auth on the search/retrieve endpoint — echoing LoginID's own compliance language (PSD2 SCA, SOC 2, non-repudiation) even though this assignment's baseline is deliberately simpler than passkeys.
71	4. **Speak the language of LoginID's stated positioning** in the write-up — e.g., framing the connector design questions around why a service would need to pull PII from a third-party IDP "ABC/XYZ" rather than owning it (federation/aggregation is a real pattern LoginID's own FIDO Server plays a role in), and noting where a LoginID-style passkey/WebAuthn credential would slot into `user_credential.method` if this were built for real.
72	
73	In short: the assignment's plain password/IDP-connector design is the "before" picture: LoginID's entire commercial existence is the "after" picture (FIDO2/WebAuthn, and now agent-mandate signing). Framing the submission as "here's a solid baseline, and here's exactly where it would evolve toward what LoginID sells" is the strongest way to connect this track's competitive research back to the coding tracks' output.
74	
75	## Sources consulted
76	
77	- [FIDO Alliance — LoginID company listing](https://fidoalliance.org/company/loginid/) — **Marketing** (member-supplied, alliance-hosted)
78	- [loginid.ai homepage](https://loginid.ai/) — **Marketing**
79	- [Crunchbase — LoginID organization profile](https://www.crunchbase.com/organization/loginid) — **Aggregator** (direct fetch blocked by 403; facts drawn from search-result summaries of this page and its linked funding-round pages)
80	- [Crunchbase — Simon Law](https://www.crunchbase.com/person/simon-law) — **Aggregator**
81	- [Crunchbase — Jim Brown](https://www.crunchbase.com/person/jim-brown-a287) — **Aggregator**
82	- [The Org — Simon Law](https://theorg.com/org/loginid/org-chart/simon-law) — **Aggregator**
83	- [PR Newswire — Algorand Foundation Announces Grant to LoginID](https://www.prnewswire.com/news-releases/algorand-foundation-announces-grant-to-loginid-301394622.html) — **Marketing/press release**
84	- [Corbado blog — Top 10 LoginID Alternatives](https://www.corbado.com/blog/best-login-id-alternatives) — **Independent, but vendor-interested** (Corbado is a LoginID competitor)
85	- [W3C press release — WebAuthn finalized as web standard, 2019](https://w3.org/press-releases/2019/webauthn) — **Independent**
86	- [FIDO Alliance — W3C/FIDO WebAuthn finalization](https://fidoalliance.org/w3c-and-fido-alliance-finalize-web-standard-for-secure-passwordless-logins/) — **Independent**
87	- [Apple Newsroom — Apple, Google, Microsoft commit to expanded FIDO support, May 2022](https://www.apple.com/newsroom/2022/05/apple-google-and-microsoft-commit-to-expanded-support-for-fido-standard/) — **Independent**
88	
89	## Gaps / lower-confidence items (flagged honestly rather than guessed)
90	
91	- No primary-source founder interview/podcast found explaining founding motivation directly in their own words — the "why" section above is reasoned inference from career history, not a quoted rationale.
92	- Pre-seed round amount/date, total funding raised, and full 12-investor list not independently verified beyond search-result summaries of Crunchbase (direct page fetch was blocked, 403).
93	- Pasan Hapuarachchi's CTO role is corroborated only by data-aggregator sites (Craft.co, Crunchbase), not a primary LoginID source, in this research pass.
94	- No specific named enterprise/fintech customer case studies were found for LoginID itself (searches surfaced industry-wide passkey adoption stats and competitors' case studies, e.g., PayPal, rather than LoginID's own customers).
95	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/research-oauth-history.md"
}

1	# Research: a-auth.dev, Dick Hardt, and the OAuth Lineage
2	
3	Ad hoc research note produced for the `01-product-industry-research-design` track, prompted by a mention of "a-auth.dev" and "Dick Hart" during the LoginID interview. Produced with Claude Code using WebSearch/WebFetch against public sources (Wikipedia, RFC Editor/IETF datatracker, project site, LinkedIn, podcast transcript). No file other than this one was modified.
4	
5	## 0. First correction: the name and the domain
6	
7	Two things said in the interview appear to be slightly off, and it's worth flagging before anything else:
8	
9	- The person is **Dick Hardt**, not "Dick Hart." (There are unrelated people named "Dick Hart" — a footballer, a golfer — who show up in search results and are not this person.)
10	- The live project domain that resolves is **aauth.dev** (no hyphen). `a-auth.dev` returned `ENOTFOUND` (DNS does not resolve) when fetched directly during this research. It's likely a mishearing/mistyping of `aauth.dev` in conversation, or a domain that has since been retired/changed. This note treats `aauth.dev` as the intended site, based on content matching what was described in the interview.
11	
12	## 1. What is aauth.dev?
13	
14	Per the site's own content (fetched via WebFetch, 2026-09-12): AAuth is presented as an **Internet-Draft specification** — i.e. an IETF-track protocol proposal, not a shipping commercial product — with accompanying SDKs, tooling, and reference implementations, plus explainer/community material. It carries some manifesto-like advocacy language alongside the technical spec content, so it's fair to describe it as "a protocol proposal with a manifesto layer," rather than purely one or the other.
15	
16	**Author:** Dick Hardt, described on the site as "original author of OAuth 2.0" (see Section 2 for how accurate that framing is). It's an open-source effort, developed in public with community contribution, and is explicitly positioned as going through (or aiming for) the IETF standards process rather than as a closed vendor spec.
17	
18	**The problem it claims to solve:** traditional authorization protocols (OAuth 2.0 included) assume a client application is compiled/registered ahead of time, with a static, known relationship to the services it calls, and that a static, pre-registered client ID/secret model (API keys) is adequate. The site's argument is that AI agents break this assumption because they:
19	
20	- assemble their own tool/service relationships dynamically at runtime, often against services never seen before,
21	- have no portable identity — an OAuth client ID registered with one provider doesn't transfer to another,
22	- rely on copying around long-lived API keys, which leak,
23	- need authorization decisions made mid-task rather than only as one upfront consent screen,
24	- operate across trust domains (multiple orgs, clouds, identity systems) simultaneously.
25	
26	Quoted tagline from the site: *"Clients used to be written. Now agents assemble them at runtime. The protocols underneath weren't built for that,"* and *"The web gave servers identity. It's time clients got the same."*
27	
28	**The proposed mechanism:** replace shared-secret API keys with **cryptographic agent identity** — every HTTP client gets its own verifiable identity (published at a well-known URL, verifiable without pre-registration or shared secrets) and signs its own requests directly (proof-of-possession per request) rather than presenting a bearer credential. The spec describes five progressive access modes (identity-based, resource-managed, person-identity, person-server, federated) and is explicitly framed as **coexisting with OAuth 2.0**, not replacing it — tokens carry identity + per-request authorization claims rather than standing, long-lived permissions.
29	
30	**Uncertain/unconfirmed:** the deeper technical claims above (the five access modes, the specific token semantics) come from a single WebFetch summarization pass over the live site rather than a full read of the Internet-Draft text itself, and were not cross-checked against a second independent source (e.g., an actual IETF datatracker draft filing). Treat the mechanism description as "what the site says about itself," not independently verified protocol analysis.
31	
32	## 2. Who is Dick Hardt, really, in OAuth history?
33	
34	This is the part worth being careful about, because the interview framing ("associated with the original OAuth standard") is easy to over-read as "co-author of OAuth 1.0," and the evidence does not support that.
35	
36	**Confirmed, from RFC 5849 (OAuth 1.0, published April 2010) itself:** the author/contributor list is Eran Hammer-Lahav (editor), Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, Kellan Elliott-McCrea, Larry Halff, Ben Laurie, Chris Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. **Dick Hardt is not on this list.** He was not a co-author or credited contributor of OAuth 1.0 / RFC 5849. (Source: RFC Editor / IETF datatracker listing for RFC 5849.)
37	
38	**What Dick Hardt actually did:** he was at Microsoft when OAuth 1.0 shipped, found it too complex to deploy, and — working with counterparts at Yahoo and Google — built an alternative simplified authorization profile originally intended to be called "OAuth" but renamed **OAuth WRAP** (Web Resource Authorization Profiles) after Eran Hammer-Lahav objected to reusing the OAuth name for something that didn't build on the OAuth 1.0 base. OAuth WRAP built on / was compatible with OAuth 1.0 concepts and was optimized for simpler implementation. Many WRAP concepts were subsequently folded into what became OAuth 2.0. (Source: Identity, Unlocked podcast transcript — "SignIn.org and the Genesis of the GNAP Working Group" — and IETF 77 (March 2010) OAuth WRAP slide deck.)
39	
40	**His OAuth 2.0 role is well documented and real:** RFC 6749, "The OAuth 2.0 Authorization Framework," published October 2012, lists **D. Hardt (Ed.)** as editor. That is a genuine, verifiable, primary role — he shepherded and edited the specification that obsoleted OAuth 1.0. (Source: RFC 6749, rfc-editor.org.)
41	
42	**Other confirmed biographical facts** (Wikipedia): born 1963, Canadian technology entrepreneur; founded ActiveState (sold to Sophos, 2003); a leading voice in the mid-2000s "Identity 2.0" movement; founded Sxip Identity (2003) and was a founding board member of the OpenID Foundation; joined Microsoft as a partner architect in December 2008 focused on identity, left January 2010 (this is the window during which the WRAP work happened); later founded Bubbler, joined Amazon in 2015. Wikipedia's biography text itself does not mention OAuth WRAP or AAuth by name — those details come from the RFC record and the podcast/site sources above, not from Wikipedia.
43	
44	**Net assessment:** "associated with the original OAuth standard" is defensible only if read loosely — he is a central figure in the OAuth *lineage* (WRAP → OAuth 2.0 editor), but he was **not** a co-author of the original OAuth 1.0 standard (RFC 5849). The precise, defensible framing is: **"Dick Hardt is the editor of OAuth 2.0 (RFC 6749) and creator of OAuth WRAP, not a co-author of OAuth 1.0."** He also self-describes (LinkedIn) as "Creator of OAuth," which is a claim from his own bio and is the kind of self-characterization that should be flagged as his own framing rather than independently confirmed — the RFC record supports "OAuth 2.0 editor," which is a specific and significant credential, but the discrete OAuth 1.0 authorship claim doesn't hold up against RFC 5849's actual byline.
45	
46	## 3. Broader OAuth timeline, for context
47	
48	- **Nov 2006:** Blaine Cook builds an OpenID implementation for Twitter; around the same time Ma.gnolia needs a way to let Mac OS X Dashboard widgets access user accounts without sharing passwords. Cook, Chris Messina, and Larry Halff (Ma.gnolia), plus David Recordon, conclude there's no open standard for this kind of delegated API access.
49	- **April 2007:** an open OAuth discussion group forms; Google's DeWitt Clinton joins.
50	- **July 2007:** an initial spec draft exists; Eran Hammer-Lahav becomes the person coordinating the effort into a formal specification.
51	- **Oct 2007:** OAuth Core 1.0 final draft released.
52	- **Nov 2008:** IETF "Birds of a Feather" session at the Minneapolis meeting builds support for a formally chartered IETF OAuth working group.
53	- **~2009-2010:** Dick Hardt (at Microsoft) and colleagues at Yahoo/Google build OAuth WRAP as a simpler alternative/profile, intending it to fold back into the OAuth effort.
54	- **April 2010:** OAuth 1.0 published as **RFC 5849** (informational, not yet a full IETF standards-track document at that point).
55	- **Aug 2010:** Twitter requires all third-party apps to use OAuth.
56	- **Oct 2012:** **OAuth 2.0** published as **RFC 6749**, edited by Dick Hardt, obsoleting/replacing OAuth 1.0. (RFC 6750, Bearer Token Usage, published alongside it.)
57	- **Later:** the OAuth ecosystem continues to evolve (PKCE, device flow, token exchange, DPoP, GNAP as an even more ambitious successor effort that Hardt has also been involved with per the SignIn.org podcast source) — this track's research did not go deep into post-2012 OAuth evolution since it's outside what's needed to place a-auth.dev/AAuth in context.
58	
59	## 4. Relevance to the LoginID assignment (Track 01 framing)
60	
61	This track owns industry/competitive framing for the identity/IAM space LoginID operates in — passwordless auth, FIDO2/passkeys, and now AI-agent identity is an adjacent, fast-emerging sub-space worth naming explicitly in the framing document.
62	
63	- **Complementary, not competing, with LoginID's core passkey/FIDO2 space.** AAuth is solving a different layer of the identity stack: it's about **authorizing and identifying HTTP clients/agents to services** (a client-credential / machine-to-machine authorization problem), whereas LoginID's core passwordless proposition is about **authenticating a human to a service** (replacing passwords with FIDO2/WebAuthn passkeys). The two are largely orthogonal: FIDO2 answers "is this the real person," AAuth-style protocols answer "is this the real agent/client, acting on whose behalf, with what scoped permission, for this one request." A mature identity platform plausibly needs both.
64	- **Where they do intersect:** AAuth's "person-identity" and "person-server" access modes (per the site's own framing) are explicitly about binding an agent's actions back to a human principal — which is squarely the kind of problem passkey-based strong authentication is meant to anchor. If LoginID were positioning itself for the agentic-AI moment, the credible story is "we provide the strong, phishing-resistant human-authentication anchor that agent-identity protocols like AAuth need at the root of their trust chain," not "we compete with AAuth."
65	- **For this take-home's actual assignment (DAO + REST API + third-party IDP connector):** this research is context/framing rather than something that changes the API contracts already specified by LoginID. It's useful supporting material for the industry-framing document (e.g., a paragraph situating this assignment's `/auth` + `/identity` connector pattern against the broader trend of moving away from static, pre-registered client credentials — the same critique AAuth levels at the "static client at compile-time" assumption applies loosely to why a third-party-IDP connector model, and multi-database credential storage, need to be designed with an eye toward evolving beyond simple username/password `user_credential` records).
66	- **Caveat for whoever uses this in the final submission:** don't cite "Dick Hart" or claim he co-authored OAuth 1.0 in the submission — use "Dick Hardt, editor of OAuth 2.0 (RFC 6749) and creator of OAuth WRAP" if a name/credential needs to be attached to a citation of AAuth/aauth.dev.
67	
68	## Sources
69	
70	- [aauth.dev](https://aauth.dev) — project site (fetched directly)
71	- [RFC 5849 — The OAuth 1.0 Protocol](https://www.rfc-editor.org/rfc/rfc5849.html) (RFC Editor)
72	- [RFC 5849 info page / author list](https://www.rfc-editor.org/info/rfc5849/)
73	- [RFC 5849 — IETF Datatracker](https://datatracker.ietf.org/doc/rfc5849/)
74	- [RFC 6749 — The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html) (RFC Editor)
75	- [RFC 6749 info page](https://www.rfc-editor.org/info/rfc6749/)
76	- [OAuth — Wikipedia](https://en.wikipedia.org/wiki/OAuth)
77	- [Dick Hardt — Wikipedia](https://en.wikipedia.org/wiki/Dick_Hardt)
78	- [Dick Hardt — LinkedIn ("Creator of OAuth, building AAuth")](https://pt.linkedin.com/in/dickhardt) — self-description, treated as a claim rather than independent confirmation
79	- [OAuth WRAP Overview, Dick Hardt, IETF 77 slide deck, March 22, 2010](https://www.ietf.org/proceedings/77/slides/oauth-1.pdf)
80	- [SignIn.org and the Genesis of the GNAP Working Group — Identity, Unlocked podcast transcript](https://identityunlocked.auth0.com/public/49/Identity,-Unlocked.--bed7fada/3a164a46)
81	- [OAuth Web Resource Authorization Profiles (OAuth WRAP) — Microsoft Learn (archived docs)](https://learn.microsoft.com/en-us/previous-versions/azure/azure-services/hh801906(v=azure.100))
82	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/research-oidc-address-claim.md"
}

1	# Research: OIDC `address` claim members and the ROPC grant status
2	
3	**AI tooling note:** Produced by Claude Code haiku research subagent via WebFetch/WebSearch against primary specifications.
4	
5	## Question 1 — OIDC address claim
6	
7	**Finding:** OpenID Connect Core 1.0, Section 5.1.1 "Address Claim" (https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) defines a JSON object containing these six optional members:
8	
9	- `formatted` — full mailing address formatted for display or use on a mailing label
10	- `street_address` — street address component; **MAY contain multiple lines separated by newlines**
11	- `locality` — city or locality
12	- `region` — state, province, prefecture, or region
13	- `postal_code` — zip code or postal code
14	- `country` — country name
15	
16	All members are **optional** — the entire address claim object is optional, and within it, no individual member is required.
17	
18	**What the project had right/wrong:** Project rationale correctly named all six members with no omissions. The project did not list `formatted` in its initial statement ("we believe it is §5.1.1... with members formatted, street_address, locality, region, postal_code, country") but then immediately recognized `formatted` as a member we did not initially list — this was accurate self-correction. The note about `street_address` possibly containing newlines is confirmed; the spec states it "MAY contain multiple lines separated by newlines."
19	
20	**Sources:**
21	- Spring Security AddressStandardClaim: https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/oauth2/core/oidc/AddressStandardClaim.html (implements OIDC Core 1.0 with direct link to spec)
22	- oidc-client-ts OidcAddressClaim: https://authts.github.io/oidc-client-ts/interfaces/OidcAddressClaim.html
23	- OpenID Connect Core 1.0 specification: https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim
24	
25	## Question 2 — ROPC grant
26	
27	**Finding:** RFC 6749, Section 4.3 defines the Resource Owner Password Credentials Grant: "The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application" (https://datatracker.ietf.org/doc/html/rfc6749#section-4.3).
28	
29	OAuth 2.0 Security Best Current Practice (RFC 9700, Section 2.4) states: **"The resource owner password credentials grant [RFC6749] MUST NOT be used."** This is IETF normative language — the strongest prohibition.
30	
31	**Sources:**
32	- RFC 6749 (OAuth 2.0 Authorization Framework), Section 4.3: https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
33	- RFC 9700 (OAuth 2.0 Security Best Current Practice), Section 2.4: https://datatracker.ietf.org/doc/rfc9700/
34	
35	## Could not verify
36	
37	None — all claims confirmed from primary sources.
38	

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

1	# LT-34 refinement — S1: walking skeleton (Go module, two binaries, shared bootstrap, config loading)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S1 (LT-34).
4	
5	## Why this story is pulled first
6	
7	Per team-lead's recommendation, accepted: this is the walking skeleton — it proves the whole pipeline (build → deploy → publicly reachable) end to end before any feature carries real risk on top of an unproven deploy path. If CI/CD, the two-binary split, or the config surface don't work, every later story inherits that failure; pulling a feature story first would let a deploy-pipeline problem hide behind a feature bug. No objection to the sequencing.
8	
9	## User-visible outcome (what "done" means at the public URL)
10	
11	Both binaries are deployed and independently reachable at a public URL, each answering a health probe (`GET /healthz` or equivalent) with:
12	- HTTP 200
13	- a JSON body containing at minimum: `status: "ok"`, `service` (`api-service` or `idp-connector`), and build info (version/commit SHA and build timestamp, however CI injects it)
14	
15	This is the one user-visible behavior a walking skeleton has — no other endpoint, no DAO, no auth, no connector logic is expected to do anything yet. "Done" is verifiable by any reader with only a browser or `curl` and the URL, without reading any code.
16	
17	## Acceptance criteria (restated from `backlog.md` S1, plus research-team additions)
18	
19	From `03-engineering-delivery/backlog.md` S1, unchanged:
20	- [ ] 04 (reading this for containerization) can act on the resulting layout without re-deriving the reasoning in `PLANNING.md` or `decisions/go-layout-debate.md`.
21	- [ ] Both `cmd/*/main.go` are thin wrappers over `internal/app`; no route-registration or config-loading logic duplicated between them. Enforcement site: code review against `decisions/go-layout-debate.md`'s ruling.
22	- [ ] `internal/config` loads every variable named in `PLANNING.md`'s Service boundaries section, with `DB_DSN_FILE` taking precedence over `DB_DSN` when both are set. Enforcement site: a config-loading unit test asserting precedence.
23	- [ ] Module builds and both binaries start (against stub handlers) with no real backend configured.
24	
25	Added for this agile-loop pass, to make the story satisfy the new "done = deployed and reviewable at a public URL" bar, which S1 as originally written (a design-phase story) didn't need to state:
26	- [ ] Each binary exposes a health endpoint returning 200 + JSON body with `status`, `service`, and build info, per "User-visible outcome" above. Enforcement site: an integration test hitting the endpoint in CI, plus the PO review script below run manually against the deployed URL.
27	- [ ] CI (GitHub Actions, DevOps-owned) builds both binaries, runs the test suite, and deploys both to a publicly reachable URL on merge to the story's branch/PR environment. Enforcement site: the GitHub Actions workflow run linked from the PR.
28	- [ ] The deployed health response's build-info field actually changes between two different commits (proves the deploy is live, not a cached/stale artifact). Enforcement site: PO review script, step 3.
29	
30	## Non-goals (explicitly out of scope for this story)
31	
32	- No DAO, no database connection, no `dao.New` implementation — stub handlers only, per the original S1 scope.
33	- No auth/authz — the health endpoint is intentionally unauthenticated; it is infrastructure, not part of the API surface 02 designed auth for.
34	- No connector logic (`/auth`, `/identity`) beyond the binary existing and starting.
35	- No production-grade observability (structured logging, metrics, tracing) — only enough output to confirm the process started; that's `04-infra-devops`'s `observability.md` scope, not this story's.
36	- No TLS/custom domain decisions — whatever the CI/CD pipeline's default publicly-reachable URL is (e.g., a platform-provided preview URL) satisfies "public URL" for this story; a custom domain is not a goal here.
37	
38	## PO review script (what I will actually do to accept this story)
39	
40	1. Open the PR's linked GitHub Actions run; confirm both the build and deploy jobs are green.
41	2. `curl -s <public-url-for-api-service>/healthz` and `curl -s <public-url-for-idp-connector>/healthz` (or whatever path engineering names — confirm the actual path from the PR description); confirm both return HTTP 200 and a JSON body with `status`, `service`, and a build-info field.
42	3. Confirm the build-info field differs from any previously deployed value I've already checked (or, on the very first deploy, that it's present and non-empty) — this is the one check that proves "deployed," not just "code exists."
43	4. Skim the PR diff for `cmd/api-service/main.go` and `cmd/idp-connector/main.go`; confirm each is a thin wrapper (no route registration or config-loading logic inlined) per the acceptance criterion above.
44	5. Confirm the config-loading unit test (DSN/DSN_FILE precedence) is present and passing in the CI run.
45	
46	If all five pass, the story is accepted and I mark it Done in `backlog.md` (03's file — 04/05's respective backlogs if they also track it) and notify the PM.
47	
48	## Research team review
49	
50	**Desmond Okafor — claims check:** [pending]
51	
52	**Tobias Lindqvist — objection:** [pending]
53	
54	**Naomi Voss — ruling:** [pending]
55	

{
  "command": "cd /Users/warrenthompson/Source/LoginID && ls 03-engineering-delivery/decisions/ 2>/dev/null; echo ---; ls 03-engineering-delivery/ 2>/dev/null; echo ---; grep -n \"Service boundaries\" -A 20 PLANNING.md 2>/dev/null | head -40"
}

context-propagation.md
error-semantics.md
go-layout-debate.md
test-double-strategy.md
---
decisions
profiles
refinement
backlog.md
CLAUDE.md
PLAN.md
research-go-best-practices.md
---
30:## Service boundaries (owned by 03, read by 04)
31-
32-Set by 03 during Phase 1 planning (full reasoning: `03-engineering-delivery/PLAN.md` §4).
33-
34-- **Two binaries**, not one: `cmd/api-service` (Q1 DAO + Q2 REST API, client-facing, bearer-token auth) and `cmd/idp-connector` (Q3, outbound-only to vendors) — different threat models/auth surfaces per 02, independent scaling needs, mirrors the assignment's own Q2/Q3 split.
35-- **Package layout:**
36-  ```
37-  cmd/api-service/main.go
38-  cmd/idp-connector/main.go
39-  internal/dao/        # Repository composite interface (Profiles/Credentials/Methods) + postgres/cockroachdb/sqlite implementations
40-  internal/model/      # shared structs: UserProfile, UserCredential
41-  internal/api/         # REST handlers, router, auth middleware
42-  internal/connector/   # /auth, /identity client + handlers
43-  internal/config/      # env-var config loading, shared by both binaries
44-  internal/app/         # shared bootstrap (route registration, config wiring) both cmd/*/main.go wrap thinly
45-  ```
46-- **Config surface:** environment variables only (12-factor: config lives in the environment, not in checked-in files) — `DB_DRIVER` (postgres|cockroachdb|sqlite), `DB_DSN`, `DB_DSN_FILE` (file-mount path; takes precedence over `DB_DSN` when both are set, per 02's `handoff-04-secrets.md` S7 revision — a DSN's embedded password is as exposed by `kubectl describe`/crash dumps/env-in-child-process as any other secret in that inventory, so `DB_DSN` is now a transitional fallback, not a permanent equal option), `HTTP_ADDR`, `AUTH_JWT_ISSUER` = `https://auth.loginid-takehome.internal` / `AUTH_JWT_AUDIENCE` = `loginid-api-service` (literal values per `handoff-03-auth.md` — not secrets, safe to ship in config), `CONNECTOR_JWT_AUDIENCE` = `idp-connector-service` (the connector's own inbound audience, distinct from `AUTH_JWT_AUDIENCE` — `handoff-03-auth.md` v3 / `connector-security.md` §5, consistency-pass F15), `CONNECTOR_CLIENT_ID`/`CONNECTOR_CLIENT_SECRET` (api-service's own client credential for obtaining a `connector:identity-lookup`-scoped token to call idp-connector on a caller's behalf — a secret, added to `handoff-04-secrets.md`'s inventory as row 10 per F15), `APP_MODE` = `verifier` (default) | `issuer` (selects which of `api-service`'s two Kubernetes Deployments a given pod is — the issuer Deployment alone mounts the JWT signing-key Secret, per 02/04's F13 fix in `handoff-04-secrets.md`/`containerization-design.md`; confirmed spelling from Theo), `IDP_ABC_BASE_URL`, `IDP_ABC_CLIENT_ID`/`IDP_ABC_CLIENT_SECRET`. No flags, no config files.
47-- **DAO driver-selection mechanism:** a factory `dao.New(driver, dsn string) (dao.Repository, error)` chosen at startup from `DB_DRIVER`. `dao.Repository` is a composite interface — `Profiles() ProfileRepository`, `Credentials() CredentialRepository`, `Methods() AuthMethodRepository`, plus `CreateProfileWithCredential(ctx, p, c)`, `DeleteExpired(ctx, class, olderThan, maxRows)`, `DeleteProfile(ctx, id, externalRef)`, and `Close() error` directly on the composite — matching 05's now-accepted contract in `multi-db-strategy.md` §1/§3b/§3c (the retention-sweep addendum, consistency-pass F21), kept deliberately distinct (not one flat interface) because it's a load-bearing PII/credential-separation control per `05-data-ops/pii-governance.md`: a handler has to reach for the credential accessor on purpose. Each backend package returns one struct satisfying the composite. Factory signature and `DB_DRIVER` selection are unchanged.
48-- **Stable for 04 to build against:** the two-binary split, the `cmd/` entrypoint names, the env-var config approach and variable names above, and the `dao.New(driver, dsn)` factory signature. **05's contract has landed and is accepted** (consistency-pass F23 — this line previously said the composite's method set was "not yet stable" pending the contract; it has since landed, including `CreateProfileWithCredential` and `Close()` above). **Not yet stable:** internal DAO implementation details, ORM/query-builder choice, handler-package internals — those are implementation, not contract.
49-- **Note for 04, from the Go-layout three-hats ruling (`03-engineering-delivery/decisions/go-layout-debate.md`):** "two binaries" is a *process* boundary, not a claim about host/deploy placement — whether `api-service` and `idp-connector` land on the same node is 04's call, not implied by this section. If they're colocated, `idp-connector`'s outbound-call failure isolation from `api-service` depends on 04's resource limits, not just the process split. Separately, S4 now requires `context.WithTimeout` on every outbound vendor call and a bounded connection pool/backoff on token-refresh retries — not a 04 concern, but flagged here so 04 doesn't assume connector-side backpressure is handled elsewhere.
50-
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "grep -n -i \"thin wrapper\\|main.go\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/decisions/go-layout-debate.md | head -20"
}

7:Argued for one binary on take-home-appropriate grounds: every extra binary is authoring/wiring/README ceremony that doesn't teach the reader anything, for a submission graded on demonstrated reasoning. Conceded the isolation argument is real and already published as stable in `PLANNING.md` with 04 building against it, so declined to relitigate the boundary itself. Actual proposal: **keep two binaries, merge the ceremony, not the process boundary** — both `cmd/api-service/main.go` and `cmd/idp-connector/main.go` become thin wrappers around one shared `internal/app` package (route registration, config loading), so the deployables stay two but the authored code stays close to one. Would yield even that if a shared-bootstrap bug risked taking both down at once.
17:**Adopting Marisol's shared-`internal/app` proposal.** Both `cmd/*/main.go` become thin wrappers over `internal/app`: route registration and config loading live once, not twice. This gets the authoring-cost win she argued for without touching the process boundary 04 depends on. Package layout in `PLANNING.md` gets a note added (not a structural change — `internal/app` slots alongside the existing `internal/` packages).
39:│  main.go                     │        │  main.go                     │

{
  "command": "grep -n -i \"build.info\\|version\\|commit sha\\|timestamp\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/backlog.md /Users/warrenthompson/Source/LoginID/04-infra-devops/*.md 2>/dev/null | head -30"
}

/Users/warrenthompson/Source/LoginID/04-infra-devops/ci-pipeline.md:7:1. **Build.** `go build ./...` for both `cmd/api-service` and `cmd/idp-connector`, against the module's declared Go version. Fails fast — nothing downstream runs against code that doesn't compile.
/Users/warrenthompson/Source/LoginID/04-infra-devops/ci-pipeline.md:13:5. **Build images.** Both Dockerfiles (`./containerization-design.md` §2) built and tagged with the commit SHA. Not pushed yet on a PR build — build-only, to catch a broken multi-stage build before merge.
/Users/warrenthompson/Source/LoginID/04-infra-devops/backlog.md:13:- [ ] Both images build from a pinned Go version, produce a static binary, and contain nothing but the binary (+ CA certs for `idp-connector`) — enforcement site: multi-stage Dockerfile's final `COPY` list.
/Users/warrenthompson/Source/LoginID/04-infra-devops/backlog.md:106:**Description:** The consistency pass (`../decisions/cross-track-consistency.md`, "Deletion gap") ruled the enforcement site: a subject-deletion request reaches `user_profile`/`user_credential` by cascade but not application logs, metrics, or the audit trail, none of which has a `source` column or a deletion hook. 02's never-log list is the upstream control (PII values never enter a log in the first place, per `./observability.md`'s enforcement mechanism), which leaves exactly one remaining artifact needing a retention window: the audit trail itself (`sub`, scope, opaque record id, timestamp) — pseudonymous, not PII-free, and after a profile deletion the only remaining record that a given record id was looked up by a given caller. The enforcement site for its expiry is a retention policy on the log sink 04 already operates (Loki or equivalent, per `./observability.md`'s "Audit-log access" section) — not a deletion job, not a DAO method. 05 adds one row to `pii-governance.md`'s retention table for the audit-log window (basis: unknown, pending legal); 02 adds the two vocabulary/list fixes the pass identified for the never-log list (driver-error detail, `username`). This story configures the sink's retention setting to that window once it's a number.
/Users/warrenthompson/Source/LoginID/04-infra-devops/observability.md:31:Per the hand-off's Kubernetes-specific requirements: the log stream carrying `sub`/scope/record-id/timestamp (the "fact of access" the never-log list still permits) is itself sensitive enough to reconstruct who looked up whom, so it gets its own RBAC — a distinct, narrower `Role` bound to an incident-review group, separate from any ServiceAccount's `Secret`-read grant (`./secrets-delivery.md`). Mechanism: if logs go to a cluster-local sink (e.g., Loki), that sink's read API gets its own RBAC/auth in front of it, not the same one guarding `kubectl get secrets`; if logs go to an external platform, the equivalent is a scoped read-only role in that platform, provisioned separately from any cluster credential.
/Users/warrenthompson/Source/LoginID/04-infra-devops/observability.md:43:Application logs, metrics, and traces have no `source` column, no clock tied to a `user_profile` row, and no key a subject-deletion request could reach by cascade — a deleted profile's data can still exist in a log line indefinitely. 05's never-log list (`handoff-04-secrets.md`) and this document's enforcement mechanism (above) are the upstream control — if PII never enters a log, there's nothing in a log to expire — but that only holds for the fields on the list. What's left (chiefly the audit trail: `sub`, scope, opaque record id, timestamp — permitted by design, pseudonymous rather than PII-free) still needs a retention window: `pii-governance.md` § "Retention windows (S5)", the "Audit-log stream" row (clock: the entry's own timestamp; window: proposed, pending a legal ruling; disposal: **expiry at the sink**) names this document's log-sink retention policy as its enforcement site — the citation resolves in both directions. Not a deletion job 04 writes — a retention setting on infrastructure 04 already operates.
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:26:apiVersion: apps/v1
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:61:apiVersion: v1
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:68:apiVersion: apps/v1
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:107:apiVersion: v1
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:117:**Why two Deployments of one image, not RBAC on one:** a `Role` restricting `get` on the signing-key `Secret` does nothing once that `Secret` is already volume-mounted into a container — every replica of that Deployment can read the file regardless of who's allowed to `kubectl get` it. The only way to keep the verification code path (every `api-service` replica) from being able to read the private key is to never mount it there at all. `APP_MODE=issuer` on the second Deployment is 03's addition to the config surface (env-var only, no flags, per `PLANNING.md`); the same binary handles both modes, wired by that variable, not two separate images. This was F13 in the consistency pass — the earlier version of this manifest mounted the key into `api-service` directly, which the RBAC comment here used to (incorrectly) imply was sufficient.
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:127:R2's mechanism is orchestration-layer exclusivity (a concurrency-gated pipeline stage, `./ci-pipeline.md` §4), not a database lock — final reasoning: a transaction-scoped lock (`pg_advisory_xact_lock`, CockroachDB-compatible) releases between `goose`'s per-file transactions, so a second runner could interleave mid-run even with one held; a session-scoped lock would span the whole run but CockroachDB doesn't support that scope. No single database mechanism covers both the right scope and the right engine, so the exclusivity has to live outside the database entirely, on every backend, not just CockroachDB. 05 also names a cheap backstop — a unique constraint on `goose`'s version-table `version_id` column, added in the first migration regardless of whether goose's default schema already has one — so a second runner that does slip through fails loudly on insert instead of interleaving silently. That's a migration-file change (03/05's to make), not something 04 builds, but it's worth naming here since it's the backstop behind this job's own exclusivity design, not a replacement for it.
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:129:**Fail-closed schema check (R3, final):** the readiness probe below isn't just a liveness ping — `api-service` must refuse to serve if either of goose's two version tables (`shared/` and its backend-specific directory, per `migration-approach.md` §2's two-invocation mechanism) is behind the version the binary was built against. A check against only one table can pass while the other is stale — e.g. `shared/` current but the Postgres-only `pg_trgm` index migration unapplied — which is a passing check that proves nothing. `/healthz` above is liveness only; a separate `/readyz` (or the same endpoint gated by both checks) is where this lives, wired to whatever version-embedding mechanism 03 picks (build-time constant vs. reading the shipped migration files) — the check comparing *both* tables is 04's requirement to build against; the embedding mechanism is 03's call.
/Users/warrenthompson/Source/LoginID/04-infra-devops/containerization-design.md:136:apiVersion: networking.k8s.io/v1
/Users/warrenthompson/Source/LoginID/04-infra-devops/research-infra-devops-best-practices.md:15:- **Build stage**: `golang:1.2x` (pinned minor version, not `latest`) — `go mod download` before copying source so dependency layers cache independently of code changes; `CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app ./cmd/service` to produce a static, stripped binary.
/Users/warrenthompson/Source/LoginID/04-infra-devops/research-infra-devops-best-practices.md:39:1. **Checkout + setup Go** (pinned version, module cache restored).
/Users/warrenthompson/Source/LoginID/04-infra-devops/research-infra-devops-best-practices.md:62:- **PostgreSQL**: standard `postgres:<pinned-version>` image, environment-configured user/db/password, a named volume for data persistence across restarts, and a healthcheck (`pg_isready`) so the app container's `depends_on` can wait for readiness rather than racing startup.
/Users/warrenthompson/Source/LoginID/04-infra-devops/research-infra-devops-best-practices.md:143:**Containerization**: One multi-stage Dockerfile per service (DAO/API service, IDP connector service). Build stage: `golang:1.2x`, `CGO_ENABLED=0`, static stripped binary. Runtime stage: `gcr.io/distroless/static-debian12`, non-root (distroless's built-in UID 65532), CA certs copied in for outbound TLS to the IDP vendor endpoints. Pin base image versions. Mention scratch as a further-shrink option, not the default.

{
  "command": "grep -n -i \"healthz\\|health endpoint\\|/healthz\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/*.md 2>/dev/null"
}

(Bash completed with no output)

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

1	# LT-35 refinement — S2: DAO interface, domain types, sentinels, factory
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S2 (LT-35).
4	
5	## Why this story is pulled second
6	
7	LT-34 (walking skeleton) is in implementation. This is the next story in dependency order per `backlog.md` (`Depends on: S1`) and it's the shape every backend implementation (S3 Postgres/CockroachDB, and the SQLite backend) and the test-double fakes (S9) implement against next — it has to land before either backend story can start for real. No feature-priority reason to pull anything else first.
8	
9	## Acceptance outcome (this story has no public-URL surface — it's an interface, not a running service)
10	
11	Unlike LT-34, "done" here is not something reviewable at a public URL — there's no backend logic yet, nothing to deploy that behaves differently. Acceptance is mechanical and code-level: the interface, types, and sentinels exist, match 05's contract exactly, and CI proves it two ways — (1) the package compiles and its own unit tests (input-validation boundary cases) pass, and (2) a conformance/interface test (Oren's, per `03-engineering-delivery/decisions/test-double-strategy.md`) asserts the Go signatures match `05-data-ops/multi-db-strategy.md` §3 byte-for-byte, not just "close enough."
12	
13	## Acceptance criteria (restated from `backlog.md` S2)
14	
15	- [ ] A hire or reviewer unfamiliar with 05's reasoning can implement a backend against this package without re-reading `multi-db-strategy.md` — the Go types here are the contract, not a paraphrase of it.
16	- [ ] Every sentinel in 05's §4 is defined verbatim (name and wrapped message), including `ErrAlreadyExists`'s status as an internal-error signal with no caller-reachable path. Enforcement site: `dao` package source, doc comment on `ErrAlreadyExists` stating that status explicitly (per Oren's finding #1, ruled by 05).
17	- [ ] `CreateProfileWithCredential(ctx, p, c)` exists on the composite per 05's §3b resolution, with `c.UserID` ignored on input. Enforcement site: method signature plus a unit test asserting the input `UserID` is overwritten.
18	- [ ] Pointer fields follow "absent, never empty" — a non-nil, empty `*string` is rejected as `ErrInvalidArgument` at the boundary, not silently accepted. Enforcement site: input-validation unit test per field.
19	- [ ] (Added for this refinement, the seam-13 mechanical check team-lead named) Every exported type, method signature, and sentinel error name/message in this package matches `05-data-ops/multi-db-strategy.md` §3 **byte-for-byte** — not "equivalent," not "close enough." Enforcement site: a conformance test (Oren's) that fails on any drift, run in CI on the public repo.
20	
21	## Non-goals
22	
23	- No backend implementation (Postgres/CockroachDB or SQLite) — that's S3/S4, next in the queue after this.
24	- No actual database connection or query execution — `dao.New(driver, dsn)`'s factory signature exists and is callable, but nothing behind it does real I/O yet.
25	- No test-double/fake implementation itself — S9 builds the fakes against this interface; this story only has to make that possible, not do it.
26	
27	## PO review script (what I will actually check to accept this story)
28	
29	Since there's no public URL for an interface, acceptance is verified entirely in the repo and CI, at `https://github.com/wtvamp/loginid-takehome`:
30	
31	1. Open the PR; confirm CI is green, specifically Oren's conformance/interface test job (not just "tests pass" generally — the specific job that checks signature match against 05's contract).
32	2. Diff the PR's `dao` package types/interfaces/sentinels against `05-data-ops/multi-db-strategy.md` §3 myself, spot-checking at least the `Repository` composite, `ProfileQuery`, and the seven sentinel names — I'm not solely trusting the CI job's own claim of a match, since a conformance test can itself have a bug.
33	3. Confirm the doc comment on `ErrAlreadyExists` exists and states its internal-error-only status, per the acceptance criterion above (this is the one criterion CI can't easily check — it's a comment, not behavior).
34	4. Confirm the "absent, never empty" pointer-validation unit tests exist and are named/scoped per-field (not one combined test that could hide a missed field).
35	5. Confirm the PR contains no database driver import, no SQL, no connection string handling — this story should touch zero real I/O.
36	
37	If all five pass, the story is accepted and I mark it Done in `backlog.md`, then notify the PM.
38	
39	## Research team review
40	
41	**Desmond Okafor — claims check:** [pending]
42	
43	**Tobias Lindqvist — objection:** [pending]
44	
45	**Naomi Voss — ruling:** [pending]
46	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/05-data-ops/multi-db-strategy.md"
}

1	# Multi-Database Abstraction Strategy
2	
3	Owner: 05-data-ops. Implemented by: `03-engineering-delivery`, from the prose contract below — this project is still in planning phase, so the interface and schema exist here as design, not as `.go`/`.sql` files, until there's an explicit go-ahead to write code. Full research trail: `research-data-ops-best-practices.md`.
4	
5	## The interface contract (prose, not code)
6	
7	> **This section's interface listing has been removed, not corrected.** It restated the repository methods, the domain types and the error sentinel, and every one of those restatements had drifted from the authoritative version: `Update` was described as a portable upsert (it never creates — `Upsert` is a separate method), phone search as exact/prefix (exact only, per finding F9 with 01), pagination as bare limit/offset (there are `Limit` 1..100 and `Offset` 0..10 000 ceilings, enforced with `ErrInvalidQuery`), and `ErrNotFound` as the only sentinel (there are seven).
8	>
9	> **The authoritative definitions are below, in "The Go-shaped contract":** §1 the factory and composite, §2 domain types, §3 the interfaces, §3b–§3c the cross-table operations, §4 error semantics, §5 field-level schema.
10	>
11	> I first tried to fix this by striking through the wrong claims inline. That was the wrong instinct — a corrected restatement is still a restatement, and it would have drifted again the next time the contract moved. Deleting it removes the failure mode rather than patching this instance of it. Found by this track's own seam-13 sweep and finding F20; the reasoning that follows is unaffected and still stands.
12	
13	Two concrete implementations satisfy all three interfaces:
14	
15	- `postgres` package — serves both PostgreSQL and CockroachDB from one implementation. They share enough of the wire protocol and SQL surface that a second implementation would be duplicated effort — **but that is only half the argument, and the half that was originally stated here was the cheap half.** Sourced in `research-cockroachdb-postgres-semantics.md`: CockroachDB defaults to SERIALIZABLE and returns client-retryable `40001` errors that PostgreSQL at READ COMMITTED never emits, and constraint-violation error *text* is not portable between them. One package serves both **only if it carries an explicit engine-aware retry-and-error seam** (see the contract's error semantics and write-path sections). It cannot be a thin PostgreSQL implementation pointed at a second connection string.
16	- `sqlite` package — a separate implementation. SQLite diverges enough (no native UUID/BOOLEAN, no trigram index, app-side ID generation) that forcing it through the Postgres implementation would mean littering that code with backend conditionals, which is the exact failure mode a repository-per-backend split is meant to avoid.
17	
18	The service layer depends only on the interfaces and is constructed with whichever concrete implementation the startup config names. Backend choice is a wiring decision, never a runtime branch inside business logic.
19	
20	## Why not one implementation with dialect branches
21	
22	**Corrected 2026-09-12 after the three-hats run — full reasoning in `decisions/multi-db-abstraction.md`.** This section previously rejected dialect branches as "`if backend == \"sqlite\"` scattered through query construction." That describes a schema we do not have. Of the six concerns in the dialect table below, exactly **two** survive as real conditionals — app-side PK generation for SQLite, and fuzzy name search. Placeholders are the driver's problem, upsert syntax is identical across all three, JSON is unused, booleans map at the boundary. It is two `if`s, not a scattering.
23	
24	The two options therefore cost roughly the same, and the choice between them is made on **reviewability, not cost**: two parallel implementations a reviewer can diff against each other read better than one file with two apologetic conditionals, and this submission is graded on design reasoning. That is a legitimate tiebreak, and it is stated as what it is — a reviewer who counts the conditionals finds the discrepancy in seconds, and claiming a cost advantage that does not exist would be worse than claiming nothing.
25	
26	The real risk of the chosen shape is **silent behavioural divergence**: the interface guarantees both packages compile, not that they behave alike, and the failure mode produces no error, just different results. See the conformance-suite requirement in the contract below — the ruling is conditional on it.
27	
28	## Dialect differences that survive into the DAO layer
29	
30	| Concern | Postgres / CockroachDB | SQLite | Handling |
31	|---|---|---|---|
32	| Primary key | `UUID DEFAULT gen_random_uuid()`, server-generated | `TEXT`, app-generated before insert | DAO layer generates the UUID in Go for SQLite; server-generates for Postgres/CockroachDB. Callers never see the difference — `Create()` returns the populated `ID` either way. |
33	| Placeholders | `$1, $2, ...` | `?` | Handled by the driver/query builder, not hand-rolled per query. |
34	| Upsert | `INSERT ... ON CONFLICT (id) DO UPDATE SET ...` | Same syntax, supported since SQLite 3.24 | One query shape used everywhere. CockroachDB's `UPSERT` shorthand is deliberately not used, to avoid a second query dialect. |
35	| Fuzzy name search | `pg_trgm` GIN expression index on `LOWER(name)`, native on both Postgres and CockroachDB | No native equivalent; `LIKE` scan | **Corrected 2026-09-12 — see `decisions/multi-db-abstraction.md`.** This was previously described as a pure performance gap, on the claim that `Search()` "behaves identically from the caller's side". That was false: SQLite's `LIKE` is case-insensitive for ASCII by default, Postgres's is case-sensitive, so the same search returned *different row sets* per backend with no error. The contract now folds case explicitly on both sides (`LOWER(col) LIKE LOWER(pattern)`), which closes it for ASCII input. Residual, accepted and named: Postgres `lower()` is locale-aware, SQLite's is ASCII-only, so non-ASCII folding still diverges. |
36	| JSON | `JSONB`, indexable, has query operators | `TEXT`/`BLOB` with a differently-formatted internal `JSONB` (SQLite 3.45+) that is not disk-compatible with Postgres's | Not currently used in the reference schema. If a raw IDP `/identity` payload is ever cached, it is stored as opaque `TEXT` at the DAO boundary — no JSON-operator filtering pushed into either implementation, so the column stays portable. |
37	| Boolean | Native `BOOLEAN` | `INTEGER` 0/1 | Mapped at the DAO boundary; Go `bool` on both sides of the interface. |
38	
39	## Schema shape (prose, not DDL)
40	
41	`auth_method` — lookup table, not a native enum: `id` (UUID), `name` (unique — `"password"`, `"passkey"`, `"otp"`, `"oidc"`, ...), `requires_secret` (bool, false for passkey/WebAuthn-style methods), `is_active` (bool), `created_at`. Seeded with one `"password"` row; new methods are inserted as data, never a migration.
42	
43	`user_profile` — pure PII, no secrets: `id` (UUID PK), `name`, `phone` (normalized E.164 at write time), `street_address`, `locality`, `region`, `postal_code`, `country` (ISO 3166-1 alpha-2), `source` (`"direct"` or `"idp_cache"`, constrained), `created_at`, `updated_at`.
44	
45	`user_credential` — this system's own login credentials, no PII: `id` (UUID PK), `user_id` (FK → `user_profile.id`, cascade delete), `username` (unique), `method_id` (FK → `auth_method.id`), `secret` (nullable, salted hash only, never plaintext), `hash_algo`, `hash_cost`, `created_at`, `updated_at`.
46	
47	Indexes: B-Tree on `user_profile.phone`; trigram GIN on `user_profile.name` (Postgres/CockroachDB only); unique on `user_credential.username`; FK indexes on `user_credential.user_id` and `.method_id`.
48	
49	Primary keys are UUID everywhere — server-generated (`gen_random_uuid()`) on Postgres/CockroachDB, app-generated in Go before insert on SQLite (which has no native UUID type). One PK strategy across backends, no per-backend branch in the DAO.
50	
51	## Migration approach
52	
53	- One shared SQL migration series covers the base schema (`CREATE TABLE`, standard column types, the portable upsert-compatible constraints) since it's close enough across all three backends for this schema's scope.
54	- A small, explicitly-named set of per-backend override files covers what genuinely can't be shared — currently exactly one: the `pg_trgm` GIN index on `user_profile.name`, which has no SQLite equivalent and is simply omitted there rather than faked.
55	- Recommended tool: **goose** — plain-SQL-first, minimal dependencies, and its style fits "mostly shared, occasionally per-backend" files more naturally than golang-migrate's stricter up/down pairing. golang-migrate is an equally defensible choice if the engineering track already has tooling preferences; Atlas is worth naming as the more sophisticated schema-as-state alternative but is more than this take-home's scope needs.
56	- Migration files live under version control alongside the DAO code (`03-engineering-delivery` owns the pipeline that runs them — see `../04-infra-devops/CLAUDE.md` for where/how they're actually executed in CI/CD).
57	
58	## What the engineering track should take from this
59	
60	1. Implement `ProfileRepository`, `CredentialRepository`, `AuthMethodRepository` per the interface contract above, once there's a go-ahead to write code — don't redesign the contract, flag back to this track if it doesn't fit.
61	2. Two packages: `postgres` (serves Postgres + CockroachDB) and `sqlite`. No third implementation needed unless a fourth backend is added to the assignment.
62	3. Use the schema shape above as the starting migration content for both backend families.
63	4. Never let `UserCredential` and `UserProfile` fields mix in either implementation, even as an internal convenience struct — that boundary is a governance control (see `pii-governance.md`), not just a modeling choice.
64	
65	---
66	
67	# The Go-shaped contract — the 05→03 hand-off
68	
69	*(Story S1 in `./PLAN.md`: the DAO interface and schema contract. Where this document says S2 it means the `Search()` query-shape ruling, `decisions/search-query-shape.md`; S3 means the multi-database abstraction ruling, `decisions/multi-db-abstraction.md`.)*
70	
71	**Status: stable.** Stable means unlikely to be rewritten, not polished — per `../02-ai-security-architecture/planning-approach.md` §2, 03 should start against this rather than wait. Written to the project's hand-off standard: **03 should be able to implement this without re-deriving my reasoning.** Where a decision has a rationale 03 might otherwise re-litigate, the rationale is here; where something is deliberately out of 03's scope, §6 says so and says why.
72	
73	Everything below is Go-*shaped* prose inside a markdown file. No `.go` or `.sql` files exist or should exist until Warren's explicit go-ahead.
74	
75	**Vocabulary used below, defined once here** (added after a cold read found every one of these assumed rather than explained):
76	
77	- **SQLSTATE** — the five-character error code PostgreSQL returns for every error (`23505` = unique violation, `23503` = foreign-key violation, `23514` = CHECK-constraint violation, `40001` = serialization failure). CockroachDB implements the same table. **SQLite does not have SQLSTATE at all** — it returns extended result codes such as `SQLITE_CONSTRAINT_UNIQUE`. This asymmetry matters in §4.
78	- **GIN / `gin_trgm_ops`** — a PostgreSQL index type suited to "does this text contain that fragment" searches, and the operator class that makes it work on trigrams (three-character fragments). Together they make `LIKE '%smith%'` use an index instead of scanning every row.
79	- **`COLLATE "C"`** — tells the database to compare text by raw byte value rather than by language-aware alphabetical rules. Byte order sorts all uppercase before all lowercase; a locale-aware order does not. Picking one explicitly is what makes two different engines agree.
80	- **SERIALIZABLE / READ COMMITTED** — transaction isolation levels. SERIALIZABLE is stricter and can force the database to reject a transaction that would produce an inconsistent result, asking the client to retry.
81	- **`crdb.ExecuteTx`** — a helper from CockroachDB's official Go library that runs a transaction and automatically retries it when the database returns the retryable `40001` error. There is no PostgreSQL equivalent because PostgreSQL at its default isolation level does not produce that error.
82	
83	Inputs that produced it: `decisions/search-query-shape.md` (S2), `decisions/multi-db-abstraction.md` (S3), `research-cockroachdb-postgres-semantics.md`, and a direct two-party agreement with 03 on the factory shape (below).
84	
85	## 1. The factory and the composite
86	
87	Agreed directly with Renata Cole (03) on 2026-09-12. **Her `dao.New` signature is unchanged**; the composite is the resolution of what had been a silent mismatch between her single `Repository` return type and this track's three interfaces.
88	
89	```go
90	func New(driver, dsn string) (Repository, error)   // driver: "postgres" | "cockroachdb" | "sqlite"
91	
92	type Repository interface {
93	    Profiles()    ProfileRepository
94	    Credentials() CredentialRepository
95	    Methods()     AuthMethodRepository
96	
97	    // CreateProfileWithCredential writes both rows in ONE transaction.
98	    // See §3b.
99	    CreateProfileWithCredential(ctx context.Context, p *UserProfile, c *UserCredential) (*UserProfile, *UserCredential, error)
100	
101	    // Retention and deletion. Both write deletion_log in the SAME transaction
102	    // as the delete. See §3c.
103	    DeleteExpired(ctx context.Context, class RetentionClass, olderThan time.Time, maxRows int) (SweepResult, error)
104	    DeleteProfile(ctx context.Context, id string, externalRef *string) error
105	
106	    Close() error
107	}
108	```
109	
110	`Repository` stays an **interface**, not a struct with exported fields — Renata's reason, which is better than either I offered: an interface is mockable for her test strategy. The three accessors stay distinct rather than flattening into one interface because that separation is a governance control (`pii-governance.md`), not a modelling preference: a call site must reach for the credential accessor deliberately rather than find profile and credential methods side by side on one value.
111	
112	`"postgres"` and `"cockroachdb"` both select the `postgres` package. They are distinct driver strings rather than one because the retry seam in §4 needs to know which engine it is talking to.
113	
114	## 2. Domain types
115	
116	```go
117	type UserProfile struct {
118	    ID            string     // UUID
119	    Name          string     // required, never empty
120	    Phone         *string    // nil if unknown; E.164 when present
121	    StreetAddress *string
122	    Locality      *string
123	    Region        *string
124	    PostalCode    *string
125	    Country       *string    // ISO 3166-1 alpha-2, upper-case
126	    Source        string     // "direct" | "idp_cache"
127	    CreatedAt     time.Time
128	    UpdatedAt     time.Time
129	}
130	
131	type UserCredential struct {
132	    ID          string     // UUID
133	    UserID      string     // FK -> user_profile.id
134	    Username    string     // unique, case-folded
135	    MethodID    string     // FK -> auth_method.id
136	    Secret      []byte     // nil unless SecretState == SecretSet
137	    SecretState string     // "none" | "set" | "revoked"
138	    HashAlgo    *string    // non-nil iff SecretState == "set"
139	    HashCost    *int       // non-nil iff SecretState == "set"
140	    CreatedAt   time.Time
141	    UpdatedAt   time.Time
142	}
143	
144	type AuthMethod struct {
145	    ID             string
146	    Name           string  // "password", "passkey", "otp", "oidc", ...
147	    RequiresSecret bool
148	    IsActive       bool
149	    CreatedAt      time.Time
150	}
151	```
152	
153	**Pointers mean "absent", never "empty".** No field in this contract uses the empty string to mean absent. A `*string` that is non-nil and empty is invalid input, not a value — see §5.
154	
155	**Who owns `ID`, `CreatedAt` and `UpdatedAt`: the DAO, always.**
156	
157	- On `Create`, the caller leaves `ID` as `""`. The DAO generates the UUID (in Go for SQLite, server-side elsewhere) and returns the populated struct. **A non-empty `ID` passed to `Create` is a caller error and returns `ErrInvalidArgument`** — it is not a request to use that ID. This removes the contradiction a cold read found between "callers never see the difference" and `Create` returning `ErrAlreadyExists` "if the ID is taken": for profiles, the ID cannot be taken, because the caller never chooses it.
158	- `CreatedAt` and `UpdatedAt` are set by the DAO on every write and ignored on input. `UpdatedAt` is touched by `Create`, `Update`, and `Upsert` — including IDP re-hydration, which is load-bearing for retention (`pii-governance.md`).
159	
160	**`SecretState` is new and is the fix for a real defect.** The previous prose said `secret` was "nullable, salted hash only" and stopped. Yusuf Karadag's review found that at least three distinct states were collapsing into one null — the method requires no server-held secret (passkey/WebAuthn, where the private key is client-side), the secret is not yet set, or the secret was revoked — and that `auth_method.requires_secret` was consequently load-bearing on nothing. An explicit state column makes the three distinguishable and gives `requires_secret` something to be checked against.
161	
162	## 3. The interfaces
163	
164	```go
165	type ProfileRepository interface {
166	    Get(ctx context.Context, id string) (*UserProfile, error)
167	    Search(ctx context.Context, q ProfileQuery) (results []UserProfile, total int, err error)
168	    Create(ctx context.Context, p *UserProfile) (*UserProfile, error)
169	    Update(ctx context.Context, p *UserProfile) (*UserProfile, error)
170	    Upsert(ctx context.Context, p *UserProfile) (*UserProfile, error)
171	    Delete(ctx context.Context, id string) error
172	}
173	
174	type CredentialRepository interface {
175	    GetByUsername(ctx context.Context, username string) (*UserCredential, error)
176	    ListByUserID(ctx context.Context, userID string) ([]UserCredential, error)
177	    Create(ctx context.Context, c *UserCredential) (*UserCredential, error)
178	    Update(ctx context.Context, c *UserCredential) (*UserCredential, error)
179	    Delete(ctx context.Context, id string) error
180	}
181	
182	type AuthMethodRepository interface {
183	    Get(ctx context.Context, id string) (*AuthMethod, error)
184	    GetByName(ctx context.Context, name string) (*AuthMethod, error)
185	    List(ctx context.Context, activeOnly bool) ([]AuthMethod, error)
186	}
187	
188	type ProfileQuery struct {
189	    Name    *string // case-folded substring match; caller input escaped by the DAO
190	    Phone   *string // EXACT match on the E.164-normalized value (not prefix)
191	    Region  *string // case-folded exact match
192	    Country *string // exact match, alpha-2, upper-cased by the DAO
193	    Limit   int     // 1..100; 0 means "use default 50", deliberately
194	    Offset  int     // 0..10_000
195	}
196	```
197	
198	### `Search` semantics carried over from the S2 ruling
199	
200	These were settled in `decisions/search-query-shape.md` and were missing from the first draft of this contract — the intent-versus-text gap a cold read was run to find.
201	
202	- **`total` is the count of ALL rows matching the filters, ignoring `Limit` and `Offset`** — not the number of rows on this page. Exact, not estimated, computed by a second `COUNT(*)` outside any wrapping transaction, so under concurrent writes it may disagree with the page by a row. **`total` is a magnitude, not a promise of reachability**: it can legitimately exceed what the `Offset` ceiling of 10 000 allows a call
… truncated (20 KB cap)

{
  "command": "grep -n -i \"oren\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/decisions/test-double-strategy.md /Users/warrenthompson/Source/LoginID/03-engineering-delivery/PLAN.md 2>/dev/null | head -20"
}

/Users/warrenthompson/Source/LoginID/03-engineering-delivery/PLAN.md:36:**Oren Castellan — Detail Hawk, code reviewer.** *Function:* second-pass review on DAO/handler/connector Go for error semantics, nullability, off-by-one — the review-seat Renata asked for on her own output, plus the independent pass 02 called for on security-graded surfaces. *Tags:* serious, cautious. *Pattern/role:* rotating devil's advocate seat (implementation calls); second-pass reviewer on S3/S4.
/Users/warrenthompson/Source/LoginID/03-engineering-delivery/PLAN.md:68:  generated mocks). Seat rotates Oren → Nolan → Marisol → Ines per decision so no one hire
/Users/warrenthompson/Source/LoginID/03-engineering-delivery/PLAN.md:135:**Oren Castellan leads QA** (unit, integration, and the end-to-end/UX acceptance tests written from the PO's review script); **Nolan Reyes supports**. 02's independent second review still applies on top of this for every `security-graded` story — QA and 02's review are not the same gate.

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr view 2 --repo wtvamp/loginid-takehome --json files,url 2>&1 | head -100"
}

{"files":[{"path":"internal/dao/conformance_test.go","additions":392,"deletions":0,"changeType":"ADDED"},{"path":"internal/dao/errors.go","additions":28,"deletions":0,"changeType":"ADDED"},{"path":"internal/dao/factory.go","additions":32,"deletions":0,"changeType":"ADDED"},{"path":"internal/dao/query.go","additions":13,"deletions":0,"changeType":"ADDED"},{"path":"internal/dao/repository.go","additions":72,"deletions":0,"changeType":"ADDED"},{"path":"internal/dao/retention.go","additions":27,"deletions":0,"changeType":"ADDED"},{"path":"internal/dao/validate.go","additions":43,"deletions":0,"changeType":"ADDED"},{"path":"internal/dao/validate_test.go","additions":80,"deletions":0,"changeType":"ADDED"},{"path":"internal/model/model.go","additions":50,"deletions":0,"changeType":"ADDED"}],"url":"https://github.com/wtvamp/loginid-takehome/pull/2"}
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr diff 2 --repo wtvamp/loginid-takehome 2>&1"
}

<persisted-output>
Output too large (31.5KB). Full output saved to: /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/tool-results/b9frsqf8u.txt

Preview (first 2KB):
diff --git a/internal/dao/conformance_test.go b/internal/dao/conformance_test.go
new file mode 100644
index 0000000..16480c3
--- /dev/null
+++ b/internal/dao/conformance_test.go
@@ -0,0 +1,392 @@
+package dao
+
+// Conformance test — the "seam-13" mechanical check named in
+// 03-engineering-delivery/refinement/LT-35.md and
+// decisions/test-double-strategy.md. Asserts that this package's exported
+// Go shapes match 05-data-ops/multi-db-strategy.md's §1–§4 (the factory and
+// composite, domain types, sub-interfaces plus ProfileQuery, and sentinels)
+// byte-for-byte, not "close enough".
+//
+// MECHANISM: FROZEN COPY, not live-parse. Reliably extracting exact Go
+// signatures out of markdown prose is impractical — multi-db-strategy.md is
+// prose describing Go shapes inside fenced code blocks, not a Go source
+// file a parser can trust. Instead, the "expected*" declarations below were
+// transcribed by hand from §1–§4 at the time this test was written, and
+// pinned two independent ways so a drift on either side is caught:
+//
+//  1. Structural, on OUR side: assertInterfaceEquivalent checks the actual
+//     dao interfaces against the hand-transcribed expected* interfaces by
+//     mutual reflect.Type.AssignableTo (same method set, both directions)
+//     plus a method-count check, which catches an added, removed, or
+//     resignatured method that "compiles fine" checks alone would miss.
+//     assertStructFields does the same for domain/query/result structs,
+//     field by field, in order. The factory signature (§1) is pinned by a
+//     compile-time function-variable assignment — a mismatch fails the
+//     build, not just this test. Sentinel identity (§4) is checked by
+//     exact wrapped-message string equality, and sentinel-SET completeness
+//     (nothing added or removed without updating this test) is checked by
+//     parsing this package's own errors.go with go/parser — a syntax parse
...
</persisted-output>
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "file_path": "/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/tool-results/b9frsqf8u.txt"
}

1	diff --git a/internal/dao/conformance_test.go b/internal/dao/conformance_test.go
2	new file mode 100644
3	index 0000000..16480c3
4	--- /dev/null
5	+++ b/internal/dao/conformance_test.go
6	@@ -0,0 +1,392 @@
7	+package dao
8	+
9	+// Conformance test — the "seam-13" mechanical check named in
10	+// 03-engineering-delivery/refinement/LT-35.md and
11	+// decisions/test-double-strategy.md. Asserts that this package's exported
12	+// Go shapes match 05-data-ops/multi-db-strategy.md's §1–§4 (the factory and
13	+// composite, domain types, sub-interfaces plus ProfileQuery, and sentinels)
14	+// byte-for-byte, not "close enough".
15	+//
16	+// MECHANISM: FROZEN COPY, not live-parse. Reliably extracting exact Go
17	+// signatures out of markdown prose is impractical — multi-db-strategy.md is
18	+// prose describing Go shapes inside fenced code blocks, not a Go source
19	+// file a parser can trust. Instead, the "expected*" declarations below were
20	+// transcribed by hand from §1–§4 at the time this test was written, and
21	+// pinned two independent ways so a drift on either side is caught:
22	+//
23	+//  1. Structural, on OUR side: assertInterfaceEquivalent checks the actual
24	+//     dao interfaces against the hand-transcribed expected* interfaces by
25	+//     mutual reflect.Type.AssignableTo (same method set, both directions)
26	+//     plus a method-count check, which catches an added, removed, or
27	+//     resignatured method that "compiles fine" checks alone would miss.
28	+//     assertStructFields does the same for domain/query/result structs,
29	+//     field by field, in order. The factory signature (§1) is pinned by a
30	+//     compile-time function-variable assignment — a mismatch fails the
31	+//     build, not just this test. Sentinel identity (§4) is checked by
32	+//     exact wrapped-message string equality, and sentinel-SET completeness
33	+//     (nothing added or removed without updating this test) is checked by
34	+//     parsing this package's own errors.go with go/parser — a syntax parse
35	+//     of our own Go source, not of the markdown, so it doesn't fall under
36	+//     the "impractical" case above.
37	+//
38	+//  2. Drift, on the DOC's side: TestContractChecksumUpToDate hashes
39	+//     05-data-ops/multi-db-strategy.md's §1–§4 section (delimited by the
40	+//     marker strings below, matching this file's own scope) and compares
41	+//     it against expectedContractChecksum, frozen at transcription time.
42	+//     If 05 revises that section, this test FAILS LOUDLY instead of
43	+//     silently continuing to assert a stale copy of the contract — a human
44	+//     must re-transcribe the expected* declarations below and refresh the
45	+//     checksum constant, not just bump a version number.
46	+//
47	+// Known scope limit, stated rather than hidden: this test proves the Go
48	+// shapes named in §1–§4 match what was transcribed from the doc at the time
49	+// of transcription, and that the doc section hasn't since changed
50	+// underneath that transcription. It cannot prove the original transcription
51	+// itself was faithful — that's why the PO review script
52	+// (refinement/LT-35.md) has a human diff the PR against the doc directly,
53	+// rather than trusting this test's own claim of a match.
54	+
55	+import (
56	+	"context"
57	+	"crypto/sha256"
58	+	"encoding/hex"
59	+	"go/ast"
60	+	"go/parser"
61	+	"go/token"
62	+	"os"
63	+	"reflect"
64	+	"sort"
65	+	"strings"
66	+	"testing"
67	+	"time"
68	+
69	+	"loginid-takehome/internal/model"
70	+)
71	+
72	+// ---- §1: the factory and the composite ----
73	+
74	+// New's signature, pinned at compile time: if dao.New's signature ever
75	+// drifts from multi-db-strategy.md §1, this assignment fails to build.
76	+var _ func(string, string) (Repository, error) = New
77	+
78	+type expectedRepository interface {
79	+	Profiles() ProfileRepository
80	+	Credentials() CredentialRepository
81	+	Methods() AuthMethodRepository
82	+	CreateProfileWithCredential(ctx context.Context, p *model.UserProfile, c *model.UserCredential) (*model.UserProfile, *model.UserCredential, error)
83	+	DeleteExpired(ctx context.Context, class RetentionClass, olderThan time.Time, maxRows int) (SweepResult, error)
84	+	DeleteProfile(ctx context.Context, id string, externalRef *string) error
85	+	Close() error
86	+}
87	+
88	+func TestConformance_Repository(t *testing.T) {
89	+	assertInterfaceEquivalent(t, "dao.Repository",
90	+		reflect.TypeOf((*Repository)(nil)).Elem(),
91	+		reflect.TypeOf((*expectedRepository)(nil)).Elem())
92	+}
93	+
94	+// ---- §3: the three sub-interfaces plus ProfileQuery ----
95	+
96	+type expectedProfileRepository interface {
97	+	Get(ctx context.Context, id string) (*model.UserProfile, error)
98	+	Search(ctx context.Context, q ProfileQuery) (results []model.UserProfile, total int, err error)
99	+	Create(ctx context.Context, p *model.UserProfile) (*model.UserProfile, error)
100	+	Update(ctx context.Context, p *model.UserProfile) (*model.UserProfile, error)
101	+	Upsert(ctx context.Context, p *model.UserProfile) (*model.UserProfile, error)
102	+	Delete(ctx context.Context, id string) error
103	+}
104	+
105	+type expectedCredentialRepository interface {
106	+	GetByUsername(ctx context.Context, username string) (*model.UserCredential, error)
107	+	ListByUserID(ctx context.Context, userID string) ([]model.UserCredential, error)
108	+	Create(ctx context.Context, c *model.UserCredential) (*model.UserCredential, error)
109	+	Update(ctx context.Context, c *model.UserCredential) (*model.UserCredential, error)
110	+	Delete(ctx context.Context, id string) error
111	+}
112	+
113	+type expectedAuthMethodRepository interface {
114	+	Get(ctx context.Context, id string) (*model.AuthMethod, error)
115	+	GetByName(ctx context.Context, name string) (*model.AuthMethod, error)
116	+	List(ctx context.Context, activeOnly bool) ([]model.AuthMethod, error)
117	+}
118	+
119	+func TestConformance_SubInterfaces(t *testing.T) {
120	+	assertInterfaceEquivalent(t, "dao.ProfileRepository",
121	+		reflect.TypeOf((*ProfileRepository)(nil)).Elem(),
122	+		reflect.TypeOf((*expectedProfileRepository)(nil)).Elem())
123	+	assertInterfaceEquivalent(t, "dao.CredentialRepository",
124	+		reflect.TypeOf((*CredentialRepository)(nil)).Elem(),
125	+		reflect.TypeOf((*expectedCredentialRepository)(nil)).Elem())
126	+	assertInterfaceEquivalent(t, "dao.AuthMethodRepository",
127	+		reflect.TypeOf((*AuthMethodRepository)(nil)).Elem(),
128	+		reflect.TypeOf((*expectedAuthMethodRepository)(nil)).Elem())
129	+}
130	+
131	+func TestConformance_ProfileQuery(t *testing.T) {
132	+	assertStructFields(t, "dao.ProfileQuery", reflect.TypeOf(ProfileQuery{}), []fieldSpec{
133	+		{"Name", "*string"},
134	+		{"Phone", "*string"},
135	+		{"Region", "*string"},
136	+		{"Country", "*string"},
137	+		{"Limit", "int"},
138	+		{"Offset", "int"},
139	+	})
140	+}
141	+
142	+// §3c addenda ride along with §3's scope in this test, since RetentionClass
143	+// and SweepResult are part of the same sub-interface family the Repository
144	+// composite exposes (DeleteExpired/DeleteProfile), not a separate document
145	+// section with its own conformance obligation.
146	+func TestConformance_RetentionTypes(t *testing.T) {
147	+	if RetentionDirect != "direct" {
148	+		t.Errorf("RetentionDirect = %q, want %q", RetentionDirect, "direct")
149	+	}
150	+	if RetentionIDPCache != "idp_cache" {
151	+		t.Errorf("RetentionIDPCache = %q, want %q", RetentionIDPCache, "idp_cache")
152	+	}
153	+	if RetentionIDPCacheOrphan != "idp_cache_orphan" {
154	+		t.Errorf("RetentionIDPCacheOrphan = %q, want %q", RetentionIDPCacheOrphan, "idp_cache_orphan")
155	+	}
156	+	assertStructFields(t, "dao.SweepResult", reflect.TypeOf(SweepResult{}), []fieldSpec{
157	+		{"RowsExamined", "int"},
158	+		{"RowsDeleted", "int"},
159	+		{"OldestSurvivingAt", "*time.Time"},
160	+		{"Drained", "bool"},
161	+	})
162	+}
163	+
164	+// ---- §2: domain types (package model) ----
165	+
166	+func TestConformance_DomainTypes(t *testing.T) {
167	+	assertStructFields(t, "model.UserProfile", reflect.TypeOf(model.UserProfile{}), []fieldSpec{
168	+		{"ID", "string"},
169	+		{"Name", "string"},
170	+		{"Phone", "*string"},
171	+		{"StreetAddress", "*string"},
172	+		{"Locality", "*string"},
173	+		{"Region", "*string"},
174	+		{"PostalCode", "*string"},
175	+		{"Country", "*string"},
176	+		{"Source", "string"},
177	+		{"CreatedAt", "time.Time"},
178	+		{"UpdatedAt", "time.Time"},
179	+	})
180	+	assertStructFields(t, "model.UserCredential", reflect.TypeOf(model.UserCredential{}), []fieldSpec{
181	+		{"ID", "string"},
182	+		{"UserID", "string"},
183	+		{"Username", "string"},
184	+		{"MethodID", "string"},
185	+		{"Secret", "[]uint8"}, // []byte and []uint8 are identical types; reflect prints the latter
186	+		{"SecretState", "string"},
187	+		{"HashAlgo", "*string"},
188	+		{"HashCost", "*int"},
189	+		{"CreatedAt", "time.Time"},
190	+		{"UpdatedAt", "time.Time"},
191	+	})
192	+	assertStructFields(t, "model.AuthMethod", reflect.TypeOf(model.AuthMethod{}), []fieldSpec{
193	+		{"ID", "string"},
194	+		{"Name", "string"},
195	+		{"RequiresSecret", "bool"},
196	+		{"IsActive", "bool"},
197	+		{"CreatedAt", "time.Time"},
198	+	})
199	+}
200	+
201	+// ---- §4: error semantics ----
202	+
203	+// expectedSentinels is the frozen, exact set from multi-db-strategy.md §4 —
204	+// name and wrapped message. ErrAlreadyExists is included: it is a real
205	+// member of the sentinel set (05's ruling on Oren's original-review finding
206	+// #1), just not a caller-reachable one — see its doc comment in errors.go,
207	+// which is a plain-comment criterion this test cannot check and the PO
208	+// review script checks by hand instead.
209	+var expectedSentinels = []struct {
210	+	name string
211	+	err  error
212	+	msg  string
213	+}{
214	+	{"ErrNotFound", ErrNotFound, "dao: not found"},
215	+	{"ErrAlreadyExists", ErrAlreadyExists, "dao: already exists"},
216	+	{"ErrDuplicateUsername", ErrDuplicateUsername, "dao: duplicate username"},
217	+	{"ErrInvalidMethod", ErrInvalidMethod, "dao: unknown or inactive auth method"},
218	+	{"ErrInvalidQuery", ErrInvalidQuery, "dao: invalid query"},
219	+	{"ErrInvalidArgument", ErrInvalidArgument, "dao: invalid argument"},
220	+	{"ErrInvalidCredential", ErrInvalidCredential, "dao: credential violates secret-state rules"},
221	+}
222	+
223	+func TestConformance_SentinelMessages(t *testing.T) {
224	+	for _, s := range expectedSentinels {
225	+		if s.err == nil {
226	+			t.Errorf("sentinel %s is nil", s.name)
227	+			continue
228	+		}
229	+		if got := s.err.Error(); got != s.msg {
230	+			t.Errorf("%s.Error() = %q, want %q", s.name, got, s.msg)
231	+		}
232	+	}
233	+}
234	+
235	+// TestConformance_SentinelSetIsExactlyTheFrozenSeven parses this package's
236	+// own errors.go (a syntax parse of our Go source, not of the markdown doc)
237	+// to catch a sentinel added or removed from the `var (...)` block without
238	+// this test being updated — reflection alone has no API to enumerate
239	+// package-level vars, so a static AST walk is the only way to check
240	+// set-completeness rather than just checking the seven names we already
241	+// know to look for.
242	+func TestConformance_SentinelSetIsExactlyTheFrozenSeven(t *testing.T) {
243	+	fset := token.NewFileSet()
244	+	f, err := parser.ParseFile(fset, "errors.go", nil, 0)
245	+	if err != nil {
246	+		t.Fatalf("parsing errors.go: %v", err)
247	+	}
248	+
249	+	var found []string
250	+	for _, decl := range f.Decls {
251	+		gd, ok := decl.(*ast.GenDecl)
252	+		if !ok || gd.Tok != token.VAR {
253	+			continue
254	+		}
255	+		for _, spec := range gd.Specs {
256	+			vs, ok := spec.(*ast.ValueSpec)
257	+			if !ok {
258	+				continue
259	+			}
260	+			for i, name := range vs.Names {
261	+				// Only count entries actually initialized with errors.New(...)
262	+				// or fmt.Errorf(...) — this is a sentinel var block, and we
263	+				// want to fail loudly if that assumption ever stops holding
264	+				// rather than silently miscounting.
265	+				if i >= len(vs.Values) {
266	+					continue
267	+				}
268	+				call, ok := vs.Values[i].(*ast.CallExpr)
269	+				if !ok {
270	+					continue
271	+				}
272	+				sel, ok := call.Fun.(*ast.SelectorExpr)
273	+				if !ok {
274	+					continue
275	+				}
276	+				if sel.Sel.Name == "New" || sel.Sel.Name == "Errorf" {
277	+					found = append(found, name.Name)
278	+				}
279	+			}
280	+		}
281	+	}
282	+
283	+	want := make([]string, len(expectedSentinels))
284	+	for i, s := range expectedSentinels {
285	+		want[i] = s.name
286	+	}
287	+	sort.Strings(found)
288	+	sort.Strings(want)
289	+
290	+	if len(found) != len(want) {
291	+		t.Fatalf("errors.go declares %d sentinel(s) %v, frozen §4 copy expects %d %v — a sentinel was added or removed without updating this test", len(found), found, len(want), want)
292	+	}
293	+	for i := range want {
294	+		if found[i] != want[i] {
295	+			t.Fatalf("errors.go's sentinel set %v does not match frozen §4 copy %v", found, want)
296	+		}
297	+	}
298	+}
299	+
300	+// ---- Drift detection on the doc side ----
301	+
302	+// expectedContractChecksum is the SHA-256 of multi-db-strategy.md's exact
303	+// §1–§4 text (from the start of "## 1. The factory and the composite" up
304	+// to, not including, "## 5. Field-level schema"), frozen at the time the
305	+// expected* declarations above were transcribed. Computed with:
306	+//
307	+//	python3 -c 'import hashlib; c=open("05-data-ops/multi-db-strategy.md").read(); \
308	+//	s=c.index("## 1. The factory and the composite"); e=c.index("## 5. Field-level schema"); \
309	+//	print(hashlib.sha256(c[s:e].encode()).hexdigest())'
310	+const expectedContractChecksum = "«REDACTED-HEX»"
311	+
312	+const contractSectionStartMarker = "## 1. The factory and the composite"
313	+const contractSectionEndMarker = "## 5. Field-level schema"
314	+
315	+// contractDocPath is relative to this package's directory (internal/dao),
316	+// which is also `go test`'s working directory for this package.
317	+const contractDocPath = "../../05-data-ops/multi-db-strategy.md"
318	+
319	+func TestContractChecksumUpToDate(t *testing.T) {
320	+	raw, err := os.ReadFile(contractDocPath)
321	+	if err != nil {
322	+		t.Fatalf("reading %s: %v — this test cannot verify the frozen copy above is still in sync with 05's contract", contractDocPath, err)
323	+	}
324	+	content := string(raw)
325	+
326	+	start := strings.Index(content, contractSectionStartMarker)
327	+	end := strings.Index(content, contractSectionEndMarker)
328	+	if start == -1 || end == -1 || end <= start {
329	+		t.Fatalf("could not locate §1–§4 markers in %s (start found=%v, end found=%v) — 05's contract structure changed enough that this test can no longer even find the section it's supposed to check", contractDocPath, start != -1, end != -1)
330	+	}
331	+
332	+	section := content[start:end]
333	+	got := sha256Hex(section)
334	+	if got != expectedContractChecksum {
335	+		t.Fatalf(
336	+			"05-data-ops/multi-db-strategy.md §1–§4 has changed since this test's expected* "+
337	+				"declarations were transcribed (checksum got %s, want %s). This test is FAILING "+
338	+				"LOUDLY rather than silently passing against a stale copy of the contract: a human "+
339	+				"must re-read the current §1–§4, update the expected* types/messages in this file, "+
340	+				"and refresh expectedContractChecksum to match.",
341	+			got, expectedContractChecksum)
342	+	}
343	+}
344	+
345	+// ---- shared assertion helpers ----
346	+
347	+type fieldSpec struct {
348	+	Name string
349	+	Type string
350	+}
351	+
352	+func assertStructFields(t *testing.T, label string, got reflect.Type, want []fieldSpec) {
353	+	t.Helper()
354	+	if got.Kind() != reflect.Struct {
355	+		t.Fatalf("%s: not a struct (kind=%s)", label, got.Kind())
356	+	}
357	+	if got.NumField() != len(want) {
358	+		t.Fatalf("%s: field count drifted from 05's frozen contract — got %d fields, expected %d", label, got.NumField(), len(want))
359	+	}
360	+	for i, w := range want {
361	+		f := got.Field(i)
362	+		if f.Name != w.Name {
363	+			t.Errorf("%s: field %d name = %q, want %q (field order or name drifted from 05's contract)", label, i, f.Name, w.Name)
364	+			continue
365	+		}
366	+		if f.Type.String() != w.Type {
367	+			t.Errorf("%s: field %q type = %s, want %s", label, f.Name, f.Type.String(), w.Type)
368	+		}
369	+	}
370	+}
371	+
372	+func assertInterfaceEquivalent(t *testing.T, label string, got, want reflect.Type) {
373	+	t.Helper()
374	+	if got.Kind() != reflect.Interface {
375	+		t.Fatalf("%s: actual type is not an interface (kind=%s)", label, got.Kind())
376	+	}
377	+	if want.Kind() != reflect.Interface {
378	+		t.Fatalf("%s: expected type is not an interface (kind=%s)", label, want.Kind())
379	+	}
380	+	if got.NumMethod() != want.NumMethod() {
381	+		t.Fatalf("%s: method count drifted from 05's frozen contract — got %d method(s), expected %d", label, got.NumMethod(), want.NumMethod())
382	+	}
383	+	// Mutual assignability of two interface types holds iff their method
384	+	// sets are identical (same names, same signatures) — this is Go's own
385	+	// interface-satisfaction rule, checked structurally by reflect, not
386	+	// stringly.
387	+	if !got.AssignableTo(want) {
388	+		t.Fatalf("%s: does not satisfy the frozen §1/§3 contract shape (missing or resignatured method) — got=%s want=%s", label, got.String(), want.String())
389	+	}
390	+	if !want.AssignableTo(got) {
391	+		t.Fatalf("%s: has grown a method beyond the frozen §1/§3 contract shape — got=%s want=%s", label, got.String(), want.String())
392	+	}
393	+}
394	+
395	+func sha256Hex(s string) string {
396	+	sum := sha256.Sum256([]byte(s))
397	+	return hex.EncodeToString(sum[:])
398	+}
399	diff --git a/internal/dao/errors.go b/internal/dao/errors.go
400	new file mode 100644
401	index 0000000..3413c0d
402	--- /dev/null
403	+++ b/internal/dao/errors.go
404	@@ -0,0 +1,28 @@
405	+package dao
406	+
407	+import "errors"
408	+
409	+// The seven sentinels from multi-db-strategy.md §4, verbatim. Every backend
410	+// implementation (S3/S4) returns one of these for its matching condition —
411	+// the service layer never distinguishes sql.ErrNoRows from a
412	+// SQLite-specific miss. Anything not in this set is wrapped with %w and
413	+// passed through. Test with errors.Is.
414	+var (
415	+	ErrNotFound = errors.New("dao: not found")
416	+
417	+	// ErrAlreadyExists is reachable only via an actual UUID collision or a
418	+	// duplicated retry on Create — never via caller input, since Create
419	+	// never accepts a caller-supplied ID (a non-empty ID is
420	+	// ErrInvalidArgument instead). It is an internal-error signal, not a
421	+	// caller-facing contract: 05's conformance suite is explicitly NOT
422	+	// required to exercise this sentinel, and no test should be built
423	+	// around making it reachable from caller input (05's ruling on
424	+	// Oren's original-review finding #1).
425	+	ErrAlreadyExists = errors.New("dao: already exists")
426	+
427	+	ErrDuplicateUsername = errors.New("dao: duplicate username")
428	+	ErrInvalidMethod     = errors.New("dao: unknown or inactive auth method")
429	+	ErrInvalidQuery      = errors.New("dao: invalid query")
430	+	ErrInvalidArgument   = errors.New("dao: invalid argument")
431	+	ErrInvalidCredential = errors.New("dao: credential violates secret-state rules")
432	+)
433	diff --git a/internal/dao/factory.go b/internal/dao/factory.go
434	new file mode 100644
435	index 0000000..349c0c8
436	--- /dev/null
437	+++ b/internal/dao/factory.go
438	@@ -0,0 +1,32 @@
439	+package dao
440	+
441	+import "fmt"
442	+
443	+// New selects a backend implementation by driver name, matching
444	+// multi-db-strategy.md §1's factory signature exactly. "postgres" and
445	+// "cockroachdb" are distinct driver strings rather than one because the
446	+// engine-aware retry seam (§4) needs to know which engine it is talking to.
447
… truncated (20 KB cap)

{
  "command": "grep -n \"§1a\\|1a\\.\" /Users/warrenthompson/Source/LoginID/05-data-ops/multi-db-strategy.md"
}

114:## 1a. Package placement and how to read these signatures
509:| **Signature conformance** | The Go declarations match §2–§3 | Mechanical diff against §3 **with §1a's `model.` substitution applied** — seam 13, not a review | 03's QA, at LT-35 |
541:| A1 | 2026-09-12 | §1a (new) | Package placement, the leaf criterion, and how to read the signatures | LT-35's "byte-for-byte" acceptance criterion is unmeetable as literally stated: 03's layout puts domain structs in `internal/model`, so `*UserProfile` does not compile inside `internal/dao`. Flagged pre-emptively before implementation rather than at review | Authored: **Priya Nandakumar**. Reviewed: **Anders Vogel** — confirmed the ruling, replaced the usage-based placement reason with the leaf/dependency-direction test, closed `ProfileQuery` rather than deferring it, and found both drift paths. No separate objection seat; the review carried the objections |

{
  "file_path": "/Users/warrenthompson/Source/LoginID/05-data-ops/multi-db-strategy.md",
  "offset": 100,
  "limit": 50
}

100	
101	    // Retention and deletion. Both write deletion_log in the SAME transaction
102	    // as the delete. See §3c.
103	    DeleteExpired(ctx context.Context, class RetentionClass, olderThan time.Time, maxRows int) (SweepResult, error)
104	    DeleteProfile(ctx context.Context, id string, externalRef *string) error
105	
106	    Close() error
107	}
108	```
109	
110	`Repository` stays an **interface**, not a struct with exported fields — Renata's reason, which is better than either I offered: an interface is mockable for her test strategy. The three accessors stay distinct rather than flattening into one interface because that separation is a governance control (`pii-governance.md`), not a modelling preference: a call site must reach for the credential accessor deliberately rather than find profile and credential methods side by side on one value.
111	
112	`"postgres"` and `"cockroachdb"` both select the `postgres` package. They are distinct driver strings rather than one because the retry seam in §4 needs to know which engine it is talking to.
113	
114	## 1a. Package placement and how to read these signatures
115	
116	**Added at implementation go, pre-emptively — the acceptance criterion for LT-35 is that signatures match §3 byte-for-byte, and taken literally that criterion cannot be met.** 03's published layout puts the domain structs in `internal/model` and the interfaces in `internal/dao` (`../PLANNING.md` service boundaries). Inside `internal/dao`, a bare `*UserProfile` does not compile; it is `*model.UserProfile`. So the signatures below and the package layout are both right and cannot both be transcribed literally.
117	
118	**Resolution — the signatures in §2–§3 are written unqualified for readability, and the qualified form is the authoritative one:**
119	
120	| Type | Package | Written below as | Authoritative form inside `internal/dao` |
121	|---|---|---|---|
122	| `UserProfile`, `UserCredential`, `AuthMethod` | `internal/model` | `*UserProfile` | `*model.UserProfile` |
123	| `ProfileQuery`, `SweepResult`, `RetentionClass` | `internal/dao` | `ProfileQuery` | `ProfileQuery` — unchanged |
124	| `Repository`, the three repository interfaces | `internal/dao` | as written | unchanged |
125	| Error sentinels (§4) | `internal/dao` | `ErrNotFound` | unchanged |
126	
127	**The placement criterion — dependency direction, not usage.** My first draft justified this by observing that `internal/api` and `internal/connector` both handle the domain structs without touching the DAO. Review replaced that: it is an observation about today's callers, not a criterion, and it would not tell you where to put the next type. It also loses to a competing test — `UserProfile`'s invariants (E.164 phone, upper-case alpha-2 country) are enforced in DDL and on the DAO write path, so an ownership-of-invariants criterion would put `UserProfile` in `dao`, the opposite answer. Two criteria disagreeing is exactly when the stated one has to be the right one.
128	
129	The criterion that holds: **`internal/model` is the leaf — it imports nothing else in `internal/`. A type named by two sibling packages that must not depend on each other belongs in the leaf.** `api` and `connector` both name `UserProfile`; neither may import the other, and neither should have to go through `dao` to say the word. Same conclusion as the usage argument, but checkable, and it decides the next case without a debate.
130	
131	**`ProfileQuery` stays in `dao`, and this is now settled rather than left open.** I had flagged it to 03 as theirs to overrule, on the worry that `api` importing `dao` to construct a query is an interface whose callers must know its implementation package. Review closed it: that objection is about callers knowing `postgres` or `sqlite`, not about knowing `dao`. `api` already imports `dao` to name `dao.Repository` and to compare `dao.ErrNotFound`, so no new dependency edge is created and moving the type would remove nothing. The leaf test agrees — `ProfileQuery` is named across one existing edge and has no meaning without the method that consumes it, so putting it in the leaf would make a package that depends on nothing carry a type defined entirely by something above it. `SweepResult` and `RetentionClass` follow the same reasoning.
132	
133	**New types default to `internal/dao`** unless the leaf test above places them in `model`. The table is a closed list over an open set, which is a drift path in itself — this default closes it, so a type added next month has an answer without reopening this section.
134	
135	**So "matches §3 byte-for-byte" means: same method names, same parameter order, same types modulo the `model.` qualifier in the table above, same return shapes, same error semantics.** A reviewer should read the criterion that way. **Seam 13 against §3 must run with the substitution applied.** §3 is now a deliberately non-literal rendering of the real signatures, so a raw grep-diff would report every domain type as a mismatch — and a mechanical check that reports false positives on its first run gets marked noisy and stops being run, which costs more than never having added it. Applying the table above makes the check exact, and in that form I would take it as LT-35's acceptance gate in preference to a human comparison.
136	
137	This is the first contract ambiguity surfaced by implementation; per the standing rule it is answered by amending this document rather than letting the code decide.
138	
139	*Amended by Priya Nandakumar (05 Data Ops lead); reviewed by Anders Vogel (Systems Cartographer — boundary placement). The ruling was confirmed and two of its three stated reasons were replaced: the usage-based placement argument gave way to the leaf/dependency-direction test, and `ProfileQuery`'s placement was closed with a reason instead of being left to 03 as an overrule. Both drift paths in this section — the non-literal §3 rendering and the closed type table — were found in that review, not by the author.*
140	
141	## 2. Domain types
142	
143	```go
144	type UserProfile struct {
145	    ID            string     // UUID
146	    Name          string     // required, never empty
147	    Phone         *string    // nil if unknown; E.164 when present
148	    StreetAddress *string
149	    Locality      *string

{
  "file_path": "/Users/warrenthompson/Source/LoginID/05-data-ops/multi-db-strategy.md",
  "offset": 495,
  "limit": 50
}

495	6. **UUID primary keys on every backend.** Required for CockroachDB (sequential keys create write hotspots on a single range), supported on Postgres, app-generated on SQLite. Settled by sourced research; do not reopen. *Enforcement: the column types in §5.*
496	7. **`auth_method` as a lookup table, not a native enum.** Adding a method is an `INSERT`, not a migration and not a deploy. *Enforcement: the FK from `user_credential.method_id`; see `migration-approach.md` §4.*
497	8. **The `ON CONFLICT ... DO UPDATE` upsert form.** The one syntax all three backends accept; CockroachDB's `UPSERT` shorthand is deliberately unused to avoid a second dialect. *Enforcement: `Upsert`'s single query shape.*
498	9. **The two-package split** (`postgres` serving Postgres + CockroachDB, `sqlite` separate) and the engine-aware retry seam inside the former. *Enforcement: package boundaries; `decisions/multi-db-abstraction.md`.*
499	10. **`is_active` on `auth_method`.** `ErrInvalidMethod` is documented as "unknown **or inactive**", and the foreign key catches only *unknown* — a cold read applied item 11's own standard back to this document and found it failing its test. `is_active = false` has no DDL enforcement site and cannot have one, for the same reason as item 11: a `CHECK` on `user_credential` cannot read `auth_method`. *Enforcement: the DAO checks `is_active` before insert and returns `ErrInvalidMethod`, plus a conformance test that creates a credential against a deactivated method and asserts the sentinel.* Deactivating a method deliberately does **not** invalidate existing credentials — it prevents new ones.
500	11. **`deletion_log` carries no PII.** It exists to prove a deletion happened after the row is gone; a log containing the name and address of everyone whose data was deleted would be the retention policy's own failure mode wearing an audit trail's clothes. `profile_id` deliberately has no FK, because the row it names is meant not to exist. *Enforcement: the column set in §5, plus a conformance test asserting no PII-shaped column exists on the table.*
501	12. **The `requires_secret` ↔ `secret_state` relationship.** A credential whose method has `requires_secret = false` must not carry `secret_state = 'set'`. **This one cannot be a DDL constraint** — `CHECK` cannot reference another table — so its enforcement site is DAO-layer validation returning `ErrInvalidCredential`, plus a conformance test. Named honestly as one of the two weakest sites in this contract (the other is item 10, `is_active`), because the discipline is worthless if it only records the cases where a clean site existed.
502	
503	## 7. The conformance suite — a requirement, not a suggestion
504	
505	**Two different checks are easy to conflate here, and §7 previously named only one of them while implying both.** The distinction came from 03 during implementation and is adopted:
506	
507	| | What it checks | How | Owner |
508	|---|---|---|---|
509	| **Signature conformance** | The Go declarations match §2–§3 | Mechanical diff against §3 **with §1a's `model.` substitution applied** — seam 13, not a review | 03's QA, at LT-35 |
510	| **Behavioural conformance** (this section) | The backends *behave* alike | One suite of assertions, written once, executed against every backend | 03, at the DAO-behaviour story |
511	
512	**Signature conformance cannot substitute for behavioural conformance, and passing the first says nothing about the second.** Two implementations can match the same declarations perfectly and return different rows for the same call — which is precisely what would have happened here, three separate times, had design not caught it. Ticking §7 by running a signature diff would leave the per-driver ruling resting on nothing.
513	
514	**One suite, written once against the interface, executed against every backend implementation.** Not per-package unit tests: the same assertions, run twice, so a behavioural difference fails a test rather than reaching a user.
515	
516	This is the condition the whole per-driver ruling rests on (`decisions/multi-db-abstraction.md`). Two implementations behind one interface guarantee both *compile*; nothing guarantees they *behave* alike, and the failure mode produces no error — just different results. Every defect this phase found (the `LIKE` case divergence, the collation ordering divergence, `Country` normalization) is invisible when either implementation is read in isolation, because each is correct on its own terms.
517	
518	Mechanism is 03's. The requirement is 05's, and at minimum the suite asserts: identical result sets and identical ordering for the same `Search` across backends; `errors.Is` sentinel parity for every error condition in §4; the secret-state rules in §5 and §6.10; empty-string rejection on every `*string` filter; and for the retention methods in §3c —
519	
520	- a zero-value `RetentionClass` (`""`) returns `ErrInvalidArgument` — a caller-reachable invalid input, unlike `ErrAlreadyExists`, and therefore owed an explicit assertion rather than only prose;
521	- `maxRows` outside `1..10_000` returns `ErrInvalidArgument`;
522	- `OldestSurvivingAt` is non-nil when rows remain and nothing was old enough to delete, and nil **only** when the class is empty;
523	- `Drained` is false while deletable rows remain at the batch limit and true on the final batch;
524	- every delete writes exactly one `deletion_log` row in the same transaction, with the reason code the *method* asserts;
525	- an already-cancelled context returns before deleting anything;
526	- `deletion_log` carries no PII-shaped column (§6.11).
527	
528	---
529	
530	*AI tooling note: this contract was produced by Claude Opus 5 (05 track-lead session) synthesizing two orchestrated debates run with four Claude Sonnet 5 hires — a three-hats run on the abstraction and an adversarial pair on the query shape, artifacts under `decisions/` — plus one lead-authorized Sonnet research pass (`research-cockroachdb-postgres-semantics.md`) and a direct two-party agreement with the 03 track lead on the factory shape. Six of the eleven substantive changes in it came from hires contradicting the lead's draft, which is what the seats were bought for.*
531	
532	---
533	
534	## Amendments during implementation
535	
536	Every change to this contract after 03 accepted it is logged here with who did the work, per the org attribution rule. The contract is authoritative and the code follows it — an ambiguity found in implementation is answered by amending this document, never by letting the code decide silently. Each entry names the amendment, why it was needed, and the personas who authored, reviewed and objected.
537	
538	| # | Date | Section | Change | Why | Work-By |
539	|---|---|---|---|---|---|
540	| A2 | 2026-09-12 | §7 | Split "conformance" into signature conformance (mechanical, LT-35) and behavioural conformance (the cross-backend suite) | 03 flagged during implementation that the two were being conflated — LT-35's test is signature/type conformance, a different thing from the cross-backend behavioural suite. §7 named only the second while its title implied both, so a signature diff could have been used to tick a requirement it does not satisfy. That would have left the per-driver ruling in `decisions/multi-db-abstraction.md` resting on nothing | Authored: **Priya Nandakumar**. Originated by: **Renata Cole** (03 lead) — the distinction is hers; I only wrote it into the contract. Implementation-side propagation to QA: Renata → Oren Castellan |
541	| A1 | 2026-09-12 | §1a (new) | Package placement, the leaf criterion, and how to read the signatures | LT-35's "byte-for-byte" acceptance criterion is unmeetable as literally stated: 03's layout puts domain structs in `internal/model`, so `*UserProfile` does not compile inside `internal/dao`. Flagged pre-emptively before implementation rather than at review | Authored: **Priya Nandakumar**. Reviewed: **Anders Vogel** — confirmed the ruling, replaced the usage-based placement reason with the leaf/dependency-direction test, closed `ProfileQuery` rather than deferring it, and found both drift paths. No separate objection seat; the review carried the objections |
542	
543	**Standing rule for anything landing in git or Jira from this track:** commits are made from a worktree (never a checkout in the shared tree), authored as `Priya Nandakumar (05 Data Ops lead, Claude Opus 5)`, and carry `Story:` and `Work-By:` trailers naming every persona who contributed to that change — author, reviewers, and objection seats alike, not only whoever typed it.
544	

{
  "command": "cd /Users/warrenthompson/Source/LoginID && python3 -c '\nimport hashlib\nc = open(\"05-data-ops/multi-db-strategy.md\").read()\ns = c.index(\"## 1. The factory and the composite\")\ne = c.index(\"## 5. Field-level schema\")\nsection = c[s:e]\nprint(\"len:\", len(section))\nh = hashlib.sha256(section.encode()).hexdigest()\nprint(\"hash:\", h, len(h))\n'\n"
}

len: 35105
hash: «REDACTED-HEX» 64
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && python3 -c '\nimport hashlib\nc = open(\"05-data-ops/multi-db-strategy.md\").read()\ns = c.index(\"## 1. The factory and the composite\")\ne = c.index(\"## 5. Field-level schema\")\nsection = c[s:e]\nh = hashlib.sha256(section.encode()).hexdigest()\nprint(repr(h))\nprint(\"computed len\", len(h))\nexpected = \"«REDACTED-HEX»\"\nprint(\"expected len\", len(expected))\nprint(\"match:\", h == expected)\n'\n"
}

'«REDACTED-HEX»'
computed len 64
expected len 64
match: False
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "which go; go version 2>&1"
}

/opt/homebrew/bin/go
go version go1.27.1 darwin/arm64

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad && rm -rf pr2-check && gh repo clone wtvamp/loginid-takehome pr2-check -- -q 2>&1 | tail -20 && cd pr2-check && gh pr checkout 2 2>&1 | tail -20"
}

Switched to a new branch 'feature/LT-35'
branch 'feature/LT-35' set up to track 'origin/feature/LT-35'.
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr2-check && ls && echo --- && ls 05-data-ops 2>&1 | head -5 && echo --- && find . -name \"multi-db-strategy.md\""
}

---
decisions
profiles
backlog.md
CLAUDE.md
migration-approach.md
---
./05-data-ops/multi-db-strategy.md
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "diff /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr2-check/05-data-ops/multi-db-strategy.md /Users/warrenthompson/Source/LoginID/05-data-ops/multi-db-strategy.md && echo \"IDENTICAL\""
}

Exit code 1
113a114,140
> ## 1a. Package placement and how to read these signatures
> 
> **Added at implementation go, pre-emptively — the acceptance criterion for LT-35 is that signatures match §3 byte-for-byte, and taken literally that criterion cannot be met.** 03's published layout puts the domain structs in `internal/model` and the interfaces in `internal/dao` (`../PLANNING.md` service boundaries). Inside `internal/dao`, a bare `*UserProfile` does not compile; it is `*model.UserProfile`. So the signatures below and the package layout are both right and cannot both be transcribed literally.
> 
> **Resolution — the signatures in §2–§3 are written unqualified for readability, and the qualified form is the authoritative one:**
> 
> | Type | Package | Written below as | Authoritative form inside `internal/dao` |
> |---|---|---|---|
> | `UserProfile`, `UserCredential`, `AuthMethod` | `internal/model` | `*UserProfile` | `*model.UserProfile` |
> | `ProfileQuery`, `SweepResult`, `RetentionClass` | `internal/dao` | `ProfileQuery` | `ProfileQuery` — unchanged |
> | `Repository`, the three repository interfaces | `internal/dao` | as written | unchanged |
> | Error sentinels (§4) | `internal/dao` | `ErrNotFound` | unchanged |
> 
> **The placement criterion — dependency direction, not usage.** My first draft justified this by observing that `internal/api` and `internal/connector` both handle the domain structs without touching the DAO. Review replaced that: it is an observation about today's callers, not a criterion, and it would not tell you where to put the next type. It also loses to a competing test — `UserProfile`'s invariants (E.164 phone, upper-case alpha-2 country) are enforced in DDL and on the DAO write path, so an ownership-of-invariants criterion would put `UserProfile` in `dao`, the opposite answer. Two criteria disagreeing is exactly when the stated one has to be the right one.
> 
> The criterion that holds: **`internal/model` is the leaf — it imports nothing else in `internal/`. A type named by two sibling packages that must not depend on each other belongs in the leaf.** `api` and `connector` both name `UserProfile`; neither may import the other, and neither should have to go through `dao` to say the word. Same conclusion as the usage argument, but checkable, and it decides the next case without a debate.
> 
> **`ProfileQuery` stays in `dao`, and this is now settled rather than left open.** I had flagged it to 03 as theirs to overrule, on the worry that `api` importing `dao` to construct a query is an interface whose callers must know its implementation package. Review closed it: that objection is about callers knowing `postgres` or `sqlite`, not about knowing `dao`. `api` already imports `dao` to name `dao.Repository` and to compare `dao.ErrNotFound`, so no new dependency edge is created and moving the type would remove nothing. The leaf test agrees — `ProfileQuery` is named across one existing edge and has no meaning without the method that consumes it, so putting it in the leaf would make a package that depends on nothing carry a type defined entirely by something above it. `SweepResult` and `RetentionClass` follow the same reasoning.
> 
> **New types default to `internal/dao`** unless the leaf test above places them in `model`. The table is a closed list over an open set, which is a drift path in itself — this default closes it, so a type added next month has an answer without reopening this section.
> 
> **So "matches §3 byte-for-byte" means: same method names, same parameter order, same types modulo the `model.` qualifier in the table above, same return shapes, same error semantics.** A reviewer should read the criterion that way. **Seam 13 against §3 must run with the substitution applied.** §3 is now a deliberately non-literal rendering of the real signatures, so a raw grep-diff would report every domain type as a mismatch — and a mechanical check that reports false positives on its first run gets marked noisy and stops being run, which costs more than never having added it. Applying the table above makes the check exact, and in that form I would take it as LT-35's acceptance gate in preference to a human comparison.
> 
> This is the first contract ambiguity surfaced by implementation; per the standing rule it is answered by amending this document rather than letting the code decide.
> 
> *Amended by Priya Nandakumar (05 Data Ops lead); reviewed by Anders Vogel (Systems Cartographer — boundary placement). The ruling was confirmed and two of its three stated reasons were replaced: the usage-based placement argument gave way to the leaf/dependency-direction test, and `ProfileQuery`'s placement was closed with a reason instead of being left to 03 as an overrule. Both drift paths in this section — the non-literal §3 rendering and the closed type table — were found in that review, not by the author.*
> 
476a504,510
> 
> **Two different checks are easy to conflate here, and §7 previously named only one of them while implying both.** The distinction came from 03 during implementation and is adopted:
> 
> | | What it checks | How | Owner |
> |---|---|---|---|
> | **Signature conformance** | The Go declarations match §2–§3 | Mechanical diff against §3 **with §1a's `model.` substitution applied** — seam 13, not a review | 03's QA, at LT-35 |
> | **Behavioural conformance** (this section) | The backends *behave* alike | One suite of assertions, written once, executed against every backend | 03, at the DAO-behaviour story |
477a512,513
> **Signature conformance cannot substitute for behavioural conformance, and passing the first says nothing about the second.** Two implementations can match the same declarations perfectly and return different rows for the same call — which is precisely what would have happened here, three separate times, had design not caught it. Ticking §7 by running a signature diff would leave the per-driver ruling resting on nothing.
> 
494a531,543
> 
> ---
> 
> ## Amendments during implementation
> 
> Every change to this contract after 03 accepted it is logged here with who did the work, per the org attribution rule. The contract is authoritative and the code follows it — an ambiguity found in implementation is answered by amending this document, never by letting the code decide silently. Each entry names the amendment, why it was needed, and the personas who authored, reviewed and objected.
> 
> | # | Date | Section | Change | Why | Work-By |
> |---|---|---|---|---|---|
> | A2 | 2026-09-12 | §7 | Split "conformance" into signature conformance (mechanical, LT-35) and behavioural conformance (the cross-backend suite) | 03 flagged during implementation that the two were being conflated — LT-35's test is signature/type conformance, a different thing from the cross-backend behavioural suite. §7 named only the second while its title implied both, so a signature diff could have been used to tick a requirement it does not satisfy. That would have left the per-driver ruling in `decisions/multi-db-abstraction.md` resting on nothing | Authored: **Priya Nandakumar**. Originated by: **Renata Cole** (03 lead) — the distinction is hers; I only wrote it into the contract. Implementation-side propagation to QA: Renata → Oren Castellan |
> | A1 | 2026-09-12 | §1a (new) | Package placement, the leaf criterion, and how to read the signatures | LT-35's "byte-for-byte" acceptance criterion is unmeetable as literally stated: 03's layout puts domain structs in `internal/model`, so `*UserProfile` does not compile inside `internal/dao`. Flagged pre-emptively before implementation rather than at review | Authored: **Priya Nandakumar**. Reviewed: **Anders Vogel** — confirmed the ruling, replaced the usage-based placement reason with the leaf/dependency-direction test, closed `ProfileQuery` rather than deferring it, and found both drift paths. No separate objection seat; the review carried the objections |
> 
> **Standing rule for anything landing in git or Jira from this track:** commits are made from a worktree (never a checkout in the shared tree), authored as `Priya Nandakumar (05 Data Ops lead, Claude Opus 5)`, and carry `Story:` and `Work-By:` trailers naming every persona who contributed to that change — author, reviewers, and objection seats alike, not only whoever typed it.

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr2-check && python3 -c '\nimport hashlib\nc = open(\"05-data-ops/multi-db-strategy.md\").read()\ns = c.index(\"## 1. The factory and the composite\")\ne = c.index(\"## 5. Field-level schema\")\nsection = c[s:e]\nh = hashlib.sha256(section.encode()).hexdigest()\nexpected = \"«REDACTED-HEX»\"\nprint(\"computed:\", h)\nprint(\"expected:\", expected)\nprint(\"match:\", h == expected)\n'\n"
}

computed: «REDACTED-HEX»
expected: «REDACTED-HEX»
match: True
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && git remote -v 2>&1; git log --oneline -3 -- 05-data-ops/multi-db-strategy.md 2>&1; git status 05-data-ops/multi-db-strategy.md 2>&1"
}

origin	«email»:wtvamp/loginid-takehome.git (fetch)
origin	«email»:wtvamp/loginid-takehome.git (push)
51e5380 Planning declared consistent; full backlog in Jira (LT-1..LT-50)
d05876f Phase 3 complete: all five tracks close planning; consistency pass next
3fef95c Phase 0: planning scaffolding for the multi-agent org
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   05-data-ops/multi-db-strategy.md

no changes added to commit (use "git add" and/or "git commit -a")
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && git fetch origin -q 2>&1; git diff origin/main -- 05-data-ops/multi-db-strategy.md 03-engineering-delivery/decisions/error-semantics.md 03-engineering-delivery/backlog.md 2>&1 | head -50"
}

Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-36-LT-37.md"
}

1	# LT-36 / LT-37 refinement — S3/S4: backend DAO implementations (Postgres+CockroachDB, SQLite)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03), running both in parallel worktrees. **Source:** `03-engineering-delivery/backlog.md` S3 (LT-36) and S4 (LT-37).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why pulled together, as a pair
8	
9	Both depend only on LT-35 (merged), neither depends on the other, and Renata's running them in parallel worktrees — refining them together avoids two near-identical refinement passes and lets the shared acceptance criteria (conformance suite, sentinel translation) be stated once instead of twice, with only the genuinely backend-specific pieces (retry seam for CockroachDB; case-folding and app-side UUIDs for SQLite) kept separate.
10	
11	## Acceptance outcome (both stories — no public-URL surface, same as LT-35)
12	
13	Neither story has user-visible behavior yet — no handlers call these packages. Acceptance is mechanical: the conformance suite (LT-38, not yet pulled, but its assertions are what "done" means here even before it exists as its own story) run against each backend passes, sentinel translation is verified per-condition per-backend, and the CockroachDB-specific retry seam and SQLite-specific parity gaps are each proven, not just implemented.
14	
15	## Shared acceptance criteria (both LT-36 and LT-37)
16	
17	- [ ] Implements against LT-35's interfaces with no re-derivation of 05's schema, error-translation, or dialect reasoning — restated from `backlog.md`.
18	- [ ] Driver errors translate to the seven sentinels (`multi-db-strategy.md` §4) by structured code (SQLSTATE for Postgres/CockroachDB, extended result code for SQLite) plus our own named DDL constraints — **never free-text/`strings.Contains` matching on an error message**, per `decisions/error-semantics.md`'s superseded-but-standing rule and 05's §4. Enforcement site: the translation table/switch in each backend package; a grep for `strings.Contains` against any error string returns nothing in either package.
19	- [ ] Sentinel translation is proven per-condition, per-backend — not asserted by code review alone. Enforcement site: the conformance suite (LT-38) exercises every §4 condition against both backends and asserts `errors.Is` against the correct sentinel, per `decisions/error-semantics.md`'s "mandatory per-backend translation, verified by an explicit test case per backend."
20	- [ ] No raw driver error text (including a Postgres `DETAIL`/`Key (...)=(...)` line or a SQLite extended-code message) is ever wrapped, logged, or returned past the translation boundary — per `decisions/error-semantics.md` F50. Enforcement site: the translation function sanitizes to structured code + our constraint name before anything is wrapped for the log; a test asserting a constraint-violation error's logged/wrapped form contains no literal column value.
21	- [ ] `Upsert`'s `ON CONFLICT`/`ON CONFLICT DO UPDATE` (or SQLite equivalent) explicitly excludes `created_at` from the update-set list — per 05's Oren-finding-#3 ruling. Enforcement site: the SQL/query statement itself, plus a unit test asserting `created_at` survives a re-hydration `Upsert` unchanged, one test per backend (not one test assumed to cover both).
22	- [ ] `CreateProfileWithCredential` writes both rows in one transaction with `c.UserID` ignored on input and set from the newly created profile; on any failure, neither row exists. Enforcement site: a unit test per backend that fails the credential write deliberately (e.g. a duplicate username) and asserts the profile row does not exist afterward.
23	
24	## LT-36-specific acceptance criteria (Postgres + CockroachDB)
25	
26	- [ ] Every write method (`Create`, `Update`, `Upsert`, `Delete`, `CreateProfileWithCredential`) runs through the `withRetry` wrapper described in `decisions/error-semantics.md` — an unexported helper inside the `postgres` package, not in the composite and not above the interface boundary. Enforcement site: the wrapper is the single call path every write method uses; grep confirms no write method executes a statement outside it.
27	- [ ] The wrapper retries only when the implementation's unexported `engine` field (set by `New` from the driver string) is `"cockroachdb"`; on `"postgres"` it calls the function once. Enforcement site: a unit test constructing both engine values and asserting call count under a forced-retryable and a non-retryable condition.
28	- [ ] The retry wrapper actually retries a genuine SQLSTATE `40001` (serialization failure) against real CockroachDB, not a mocked/simulated one. Enforcement site: the conformance suite (LT-38) exercises a real retryable condition against a CockroachDB testcontainer/instance, per `backlog.md`'s own acceptance criterion for this story.
29	- [ ] `Search` opens no explicit transaction and is not wrapped by `withRetry` — it's read-only and per `decisions/error-semantics.md`'s ruling never encounters `40001`. Enforcement site: code review confirming `Search`'s implementation has no `withRetry` call.
30	- [ ] Fuzzy name search uses `LOWER(name) LIKE ?` matching the GIN expression index, with explicit `%`/`_`/`\` escaping on caller input. Enforcement site: query construction plus a unit test with a search term containing a literal `%` or `_`, asserting it's treated as a literal character, not a wildcard.
31	
32	## LT-37-specific acceptance criteria (SQLite)
33	
34	- [ ] `Create` generates the UUID in Go before insert (SQLite has no server-side generation) — enforcement site: the `Create` implementation, verified by the conformance suite asserting a populated `ID` comes back structurally identical to the Postgres path (same format, non-empty, DAO-generated either way).
35	- [ ] Search folds case **explicitly** — `LOWER(col) LIKE LOWER(pattern)` — rather than relying on SQLite's default ASCII case-insensitive `LIKE`, so the behavior is asserted by this package's own code, not an accident of the engine default. Enforcement site: the query construction plus the conformance suite's cross-backend result-set comparison (same rows, same order, for ASCII input, per `multi-db-strategy.md`'s "What Search does on SQLite" section).
36	- [ ] The documented non-ASCII case-folding divergence (Postgres `lower()` is locale-aware, SQLite's is ASCII-only) is **not silently accepted as an untested gap** — it must appear as an explicit, named exception in this package's own documentation (a doc comment on the search implementation), not only in `multi-db-strategy.md`'s prose, so a reader of the code alone sees the limitation. Enforcement site: doc comment in the SQLite search implementation, cross-referenced to `multi-db-strategy.md`.
37	- [ ] `SQLITE_CONSTRAINT_UNIQUE`/`FOREIGNKEY`/`CHECK`/`PRIMARYKEY` map to the same sentinels as the Postgres package's SQLSTATE codes, disambiguated by the same DDL constraint names (not by table/column position, which can drift independently between the two schemas). Enforcement site: the translation table, verified by the conformance suite's sentinel-parity assertion across both backends for the same logical condition.
38	
39	## Non-goals
40	
41	- LT-38 (the conformance suite itself) is not this pair's story to write — but its assertions are cited above as the actual enforcement site for several criteria in both. If LT-38 hasn't landed by the time LT-36/LT-37 are otherwise ready, those criteria are pending, not waived — flagged explicitly in the PO review script below, not silently marked done.
42	- No handler/API-layer work — `internal/api` calling into these packages is a later story.
43	- No production connection-pool tuning, migration-execution wiring, or observability — infra/DevOps scope.
44	
45	## PO review script
46	
47	1. Confirm both PRs build and their own unit tests pass in CI (once 04's pipeline exists — flag as pending otherwise, per LT-34's precedent).
48	2. Confirm the conformance suite (LT-38, if it exists yet) runs against both backends in CI and is green; if LT-38 hasn't been pulled yet, explicitly mark every criterion above whose enforcement site is "the conformance suite" as **pending**, not accepted — do not accept LT-36/LT-37 on code review alone for those criteria.
49	3. Grep both packages for `strings.Contains` applied to an error value — must return nothing.
50	4. Spot-check the `Upsert` SQL/query in both packages for the `created_at`-exclusion; confirm a unit test exists per backend.
51	5. For LT-36: confirm the `withRetry` wrapper's engine-conditional behavior in code, and confirm `Search`'s implementation has no retry-wrapper call.
52	6. For LT-37: read the SQLite search implementation's doc comment for the non-ASCII case-folding exception; confirm it's stated, not silent.
53	7. Confirm neither package's tests or logs contain a literal DB error string with embedded values (spot-check by triggering one constraint violation locally and reading what gets logged).
54	
55	## Research team review
56	
57	**Desmond Okafor — claims check:** [pending]
58	
59	**Tobias Lindqvist — objection:** [pending]
60	
61	**Naomi Voss — ruling:** [pending]
62	

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

1	# Decision: Error semantics (wrap vs. sentinel)
2	
3	Pattern: rotating devil's advocate, decision 1 of 3 (seat: Oren Castellan). Proposer: Renata Cole.
4	
5	## Proposal
6	
7	Go 1.13+ error wrapping (`fmt.Errorf("...: %w", err)`) for propagating unexpected/lower-level errors up the call stack, plus a small set of exported sentinel errors (`dao.ErrNotFound`, `dao.ErrDuplicate`) for conditions callers are expected to branch on via `errors.Is`.
8	
9	## Objections — Oren Castellan (Detail Hawk)
10	
11	1. **Sentinel set must be closed and enumerated now**, not left open-ended — otherwise hires add ad hoc `ErrX` values across S2–S4 with no stable contract. Wants a fixed list plus a named owner and a propose-before-adding rule.
12	2. **Wrapped errors must never cross the HTTP boundary raw** — `err.Error()` on a wrapped DB error can leak driver text (DSN fragments, column/constraint names) to an API client. Wants an explicit translation function at the boundary; anything unmapped defaults to a generic 500 with no wrapped detail.
13	3. **`errors.Is` against a sentinel breaks silently if a backend returns a driver-native error instead** (e.g. `*pgconn.PgError` instead of `dao.ErrDuplicate`). Wants the `Repository` interface contract to state translation is *mandatory* per backend, verified by an S5 test case per backend.
14	4. **No stated rule for `context.DeadlineExceeded`/`context.Canceled`.** These aren't ordinary internal errors and shouldn't page as generic 500s. Wants them checked and mapped to a distinct response code before generic wrapping applies.
15	
16	## Ruling (Renata Cole)
17	
18	All four accepted; no decline.
19	
20	1. Sentinel set is closed and fixed now: `dao.ErrNotFound`, `dao.ErrDuplicate`, `dao.ErrInvalidInput`. Defined once in `internal/dao`. Rule: no hire adds a sentinel unilaterally — propose it to me with the one-line reason, I add it. This applies for the rest of the design/implementation phase.
21	2. `internal/api` never serializes `err.Error()` on an unmapped error. A translation function (`internal/api` boundary layer) maps the three sentinels to their HTTP status/safe message; anything else defaults to a generic 500 with no wrapped detail surfaced to the client. Wrapped errors are for logs only.
22	3. The `Repository` interface contract states translation of known driver-native errors to the shared sentinels is **mandatory**, not optional, per backend implementation. S5's test strategy gets an explicit line item: one test per backend proving the translation happens (e.g., a unique-constraint violation surfaces as `dao.ErrDuplicate`, not a raw driver type).
23	4. `context.DeadlineExceeded` and `context.Canceled` are checked explicitly and mapped to a distinct response (504 for deadline exceeded; treat client-cancel as a non-alerting outcome, not logged as a 500) before generic wrapping/translation applies.
24	
25	## Status
26	
27	Ruled. Carries into S2 (DAO sentinel definitions + per-backend translation) and S3 (handler-layer translation function, context-error handling).
28	
29	## Superseded in part — 05's contract lands (2026-09-12)
30	
31	05's `multi-db-strategy.md` §4 is the authoritative sentinel set and translation mechanism for the DAO layer; it supersedes the specific names and the translation rule this decision guessed at before the contract existed. What stands vs. what's replaced:
32	
33	- **Replaced:** the invented sentinel set (`ErrNotFound`/`ErrDuplicate`/`ErrInvalidInput`) is superseded by 05's actual seven: `ErrNotFound`, `ErrAlreadyExists`, `ErrDuplicateUsername`, `ErrInvalidMethod`, `ErrInvalidQuery`, `ErrInvalidArgument`, `ErrInvalidCredential`. These are 05's to own and extend (own-and-propose-before-adding now routes through them, not me, for anything DAO-internal) — my closed-set/no-ad-hoc-additions principle still applies, just to their list.
34	- **Replaced:** "match SQLSTATE only" is superseded by 05's corrected rule — match structured error codes (SQLSTATE on Postgres/CockroachDB, extended result codes on SQLite) plus constraint names we define ourselves in DDL, never free-text messages. This is a more complete version of objection 2's concern (leaking driver text), not a contradiction of it.
35	- **Stands unchanged:** the HTTP-boundary rule (objection 2 — `internal/api` never serializes `err.Error()` on an unmapped error; wrapped errors are for logs only) — this is 03's layer, not 05's, and 05's contract doesn't touch it. The context-cancellation rule (objection 4) also stands unchanged, same reason.
36	- **Stands, now backed by a real mechanism instead of a guess:** objection 3's demand for mandatory per-backend translation — 05's contract §4 gives the actual mapping table (condition → PG/CRDB code → SQLite code → sentinel), and §7's conformance suite makes "sentinel parity for every error condition in §4" a stated, required test — stronger than what this decision asked for.
37	
38	## Consistency-pass fixes (2026-09-12)
39	
40	**F7 — authn/authz failure mapping was unstated.** This decision covered DAO-sentinel and context-error mapping but never said what an authn failure (missing/invalid token) or an authz failure (scope check, or an `authorize()` policy denial) returns. Fixed: a missing or invalid token → `401`. A scope failure and an `authorize()` policy denial both → `403`, with an **identical client-visible response body** — the two are distinguished only in the audit log (`handoff-03-auth.md`'s "policy decision: allow/deny, and if deny, whether it was a scope failure or an authorize() denial" field), never in what the client sees. This closes the gap the consistency pass found in `handoff-03-auth.md:27,50`'s "distinct signals for detection" requirement.
41	
42	**F50 — the boundary-sanitization rule needed to name driver `DETAIL` text explicitly.** The translation function (ruling item 2, above) already stated that unmapped errors default to a generic 500 with no wrapped detail — but a Postgres CHECK or unique-violation error's `DETAIL` line (which echoes the failing row's actual column values, including PII) is exactly the kind of "wrapped detail" that rule exists to stop, and it wasn't named specifically enough for a reader to be sure it was covered. Stated explicitly now: **the translation layer sanitizes every driver error down to its structured code plus our own constraint name before wrapping it for the log — the raw driver error (including any `DETAIL`/`Key (...)=(...)` text) is never wrapped, logged, or passed through in any form.** This translation layer (05's §4 mapping, implemented in `internal/dao`) is the enforcement site; `handoff-04-secrets.md`'s never-log list gets the matching entry from 02.
43	
44	---
45	Model: sonnet (Oren Castellan, objection seat; Renata Cole, lead, proposer + ruling). Turns consumed: 1 hire turn + lead synthesis.
46	

{
  "command": "grep -n -i \"^- \\[ \\]\\|LT-38\\|conformance\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/backlog.md | head -40"
}

5:Split note on the DAO: the two-package abstraction (`postgres` serving Postgres+CockroachDB, `sqlite` separate — `05-data-ops/decisions/multi-db-abstraction.md`) plus the interface/composite layer plus the cross-backend conformance suite are four genuinely separate PR-sized units, not one story with three criteria — each backend package merges independently once the interface (S2) exists, and the conformance suite (S5) only makes sense once at least two backends exist to run it against. Splitting them keeps each story reviewable on its own and matches how the work will actually land as commits.
14:- [ ] The receiving track (04, reading this for containerization) can act on the resulting layout without re-deriving the reasoning in `PLANNING.md` or `decisions/go-layout-debate.md`.
15:- [ ] Both `cmd/*/main.go` are thin wrappers over `internal/app`; no route-registration or config-loading logic duplicated between them — enforcement site: code review against `decisions/go-layout-debate.md`'s ruling.
16:- [ ] `internal/config` loads every variable named in `PLANNING.md`'s Service boundaries section, with `DB_DSN_FILE` taking precedence over `DB_DSN` when both are set — enforcement site: a config-loading unit test asserting precedence.
17:- [ ] Module builds and both binaries start (against stub handlers) with no real backend configured.
31:- [ ] A hire or reviewer unfamiliar with 05's reasoning can implement a backend against this package without re-reading `multi-db-strategy.md` — the Go types here are the contract, not a paraphrase of it.
32:- [ ] Every sentinel in 05's §4 is defined verbatim (name and wrapped message), including `ErrAlreadyExists`'s status as an internal-error signal with no caller-reachable path — enforcement site: `dao` package source, doc comment on `ErrAlreadyExists` stating that status explicitly (per Oren's finding #1, ruled by 05).
33:- [ ] `CreateProfileWithCredential(ctx, p, c)` exists on the composite per 05's §3b resolution, with `c.UserID` ignored on input — enforcement site: method signature plus a unit test asserting the input `UserID` is overwritten.
34:- [ ] Pointer fields follow "absent, never empty" — a non-nil, empty `*string` is rejected as `ErrInvalidArgument` at the boundary, not silently accepted — enforcement site: input-validation unit test per field.
48:- [ ] Implements against S2's interfaces with no re-derivation of 05's schema or error-translation reasoning.
49:- [ ] Every write (`Create`, `Update`, `Upsert`, `Delete`, `CreateProfileWithCredential`) runs through the retry wrapper — enforcement site: the wrapper is the single call path every write method uses, verified by the conformance suite (S5) exercising a retryable condition against CockroachDB.
50:- [ ] Driver errors translate to sentinels by structured code (SQLSTATE) plus our own named DDL constraints, never free-text matching — enforcement site: the translation table in `multi-db-strategy.md` §4, one `switch`/lookup per condition, no `strings.Contains` on an error message anywhere in this package.
51:- [ ] `Upsert`'s `ON CONFLICT DO UPDATE SET` list explicitly excludes `created_at` — enforcement site: the SQL statement itself plus a unit test asserting `created_at` survives a re-hydration Upsert unchanged (per Oren's finding #3, ruled by 05).
52:- [ ] Fuzzy name search uses the `LOWER(name) LIKE ?` form matching the GIN expression index, with explicit `%`/`_`/`\` escaping — enforcement site: query construction plus a unit test with a `%`-containing search term.
66:- [ ] Implements against S2's interfaces with no re-derivation of 05's schema or dialect reasoning.
67:- [ ] `Create` generates the UUID in Go (SQLite has no server-side generation) before insert — enforcement site: the `Create` implementation, verified by the conformance suite asserting a populated `ID` comes back identically to the Postgres path.
68:- [ ] Search folds case explicitly (`LOWER(col) LIKE LOWER(pattern)`) rather than relying on SQLite's default ASCII case-insensitivity, so behavior is asserted rather than incidental — enforcement site: the query construction plus the conformance suite's cross-backend result-set comparison.
69:- [ ] `SQLITE_CONSTRAINT_UNIQUE`/`FOREIGNKEY`/`CHECK`/`PRIMARYKEY` map to the same sentinels as the Postgres package's SQLSTATE codes, disambiguated by the same constraint names — enforcement site: the translation table, verified by the conformance suite's sentinel-parity assertion.
78:## S5. Conformance suite (05's requirement, cross-backend) (LT-38)
83:- [ ] The suite is written once against the interface and executed against all three backends from one test file/table, not duplicated per package.
84:- [ ] Asserts identical `Search` result sets and ordering across backends for ASCII input — enforcement site: this suite is the enforcement site named in `multi-db-strategy.md` for this guarantee; there is no other.
85:- [ ] Asserts `errors.Is` sentinel parity for every condition in the §4 translation table, across all three backends.
86:- [ ] Asserts the `requires_secret`/`secret_state` relationship (§6.11) and `is_active` (§6.10) — the two conditions 05 named as unable to have a DDL enforcement site.
87:- [ ] CI (04's pipeline) runs this suite against every backend including CockroachDB, not just Postgres+SQLite — flagged to 04 if their pipeline doesn't.
101:- [ ] Implements `handoff-03-auth.md` v3's scope vocabulary and pagination/rate-limit numbers without re-deriving 02's authz-scoping reasoning.
102:- [ ] `authorize()` runs as an explicit call inside each handler after request parsing, before the DAO call — enforcement site: handler code structure, per the go-layout-debate.md-adjacent ruling recorded in this track's reply to 02. `authorize()` checks the `caller_referral`/caller-role data against the token-issuer's own datastore, not against 05's schema — 05 was never assigned that table (`handoff-03-auth.md` v3, F8).
103:- [ ] `profile:search` responses carry masked PII fields by default (e.g. phone as `***-***-1234`, address reduced to `locality`/`region` only); unmasked detail requires a separate, separately-audited follow-up call under `profile:read:own` or `profile:read:any` against the specific record id — enforcement site: the search-response serialization path, distinct from the read-response one (`handoff-03-auth.md` v3, resolves F6).
104:- [ ] Cursor-based pagination only, default page size 20, hard ceiling 50 — enforcement site: the pagination parameter parsing, rejecting any offset-based parameter. **The handler's 20/50 is the authoritative clamp, enforced before the DAO is ever called** — the DAO's own `Limit` bound (1..100, default 50 per `multi-db-strategy.md`) is a second, independent backstop only reachable if the handler clamp is bypassed, not a second policy a caller can rely on (consistency-pass F10: no document previously said which of the two governs).
105:- [ ] A search request with no filter field at all is rejected by this handler before it reaches the DAO — the DAO itself treats an all-nil `ProfileQuery` as legal (`multi-db-strategy.md`), so this handler-layer rejection is the only enforcement site for "no bare unconstrained search" (consistency-pass F10, other half owned by 02 in `handoff-03-auth.md`).
106:- [ ] A `profile:search` query is rejected outright, not truncated, if it would exceed the result cap unconstrained (e.g. a bare wildcard) — enforcement site: this handler's query-validation step, per `handoff-03-auth.md` v3's scope table (consistency-pass F52).
107:- [ ] Unmapped DAO errors never surface `err.Error()` to the client; only the mapped sentinels' safe messages do — enforcement site: the boundary translation function from `decisions/error-semantics.md`. Authn failures (missing/invalid token) return 401; scope failures and `authorize()` policy denials both return 403 with an identical client body, distinguished only in the audit log (`decisions/error-semantics.md`, consistency-pass F7).
108:- [ ] `profile:read:any` requests carry a `reason_code` from the closed enum on every call, logged with the audit record.
109:- [ ] When `api-service` calls `idp-connector` on a caller's behalf, it obtains a `connector:identity-lookup`-scoped token first, using its own `CONNECTOR_CLIENT_ID`/`CONNECTOR_CLIENT_SECRET` credential (`PLANNING.md` config surface) — enforcement site: this handler-side outbound-client code, distinct from S8's idp-connector-side handlers, which only validate that token, not issue or hold this credential.
123:- [ ] Implements 02's token scheme without re-deriving the no-refresh/no-denylist reasoning in `api-auth-design.md`.
124:- [ ] Rejects any token whose `aud` doesn't match this service's audience — enforcement site: the claim-validation step, with a unit test using a mismatched-audience token.
125:- [ ] Verifies with the public key only; the private signing key never touches this binary's code path — enforcement site: dependency/import check (no signing-key material referenced in `internal/api`).
126:- [ ] **Pins the expected signing algorithm and rejects any token whose header claims a different one**, including `alg: none` and a symmetric-algorithm downgrade using the public key as an HMAC secret (RFC 8725 §3.1) — enforcement site: explicit algorithm check in the JWT verification call, not left to the library's default (`handoff-03-auth.md` v3 names this as a common library footgun).
127:- [ ] The token-issuing endpoint (the `APP_MODE=issuer` mode) has its own failed-grant rate limiting and progressive backoff per `client_id` and per source IP, separate from the resource-API limits below, with alerting on a sustained run of failed grants against one `client_id` — enforcement site: issuer-mode middleware, distinct from the verifier-mode rate limiter (`handoff-03-auth.md` v3).
128:- [ ] Per-client-credential rate limits (60 req/min read, 10 req/min search) and the cumulative distinct-record-touch counter (rolling 24h) are enforced and alert on sustained near-limit usage, not just throttle — enforcement site: the rate-limit middleware plus its own test.
129:- [ ] The deadline budget for a request (context propagation into the DAO layer) is sized to cover realistic p99 DAO latency, per `decisions/context-propagation.md`'s ruling — stated as a concrete number in this story's implementation, not left as "some deadline."

{
  "command": "grep -n -i \"retry\\|withRetry\\|cockroach\\|40001\\|engine\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/decisions/error-semantics.md"
}

34:- **Replaced:** "match SQLSTATE only" is superseded by 05's corrected rule — match structured error codes (SQLSTATE on Postgres/CockroachDB, extended result codes on SQLite) plus constraint names we define ourselves in DDL, never free-text messages. This is a more complete version of objection 2's concern (leaking driver text), not a contradiction of it.

{
  "command": "grep -n \"^[0-9]*\\.\" /Users/warrenthompson/Source/LoginID/05-data-ops/multi-db-strategy.md | sed -n '1,20p'"
}

60:1. Implement `ProfileRepository`, `CredentialRepository`, `AuthMethodRepository` per the interface contract above, once there's a go-ahead to write code — don't redesign the contract, flag back to this track if it doesn't fit.
61:2. Two packages: `postgres` (serves Postgres + CockroachDB) and `sqlite`. No third implementation needed unless a fourth backend is added to the assignment.
62:3. Use the schema shape above as the starting migration content for both backend families.
63:4. Never let `UserCredential` and `UserProfile` fields mix in either implementation, even as an internal convenience struct — that boundary is a governance control (see `pii-governance.md`), not just a modeling choice.
339:1. **`ErrAlreadyExists` is real but not caller-reachable.** Because no caller supplies an ID, a primary-key collision can only arise from a UUID collision or a duplicated retry — never from caller error. It stays in the sentinel set and stays translated (it is one branch in the error mapping), but it is documented as an **internal-error signal, not a caller contract**, and the conformance suite is **not** required to exercise it. 03 should not spend effort constructing a test for a path a caller cannot reach.
341:2. **`Limit == 0` means "default 50", and requesting zero rows is out of scope.** The review correctly noted this is the same zero-value trap the pointer-means-absent convention avoids elsewhere in the struct. Accepted as a deliberate exception rather than fixed: a count-without-rows query is a *different operation*, and if it is ever wanted it arrives as an explicit `Count(ctx, ProfileQuery)` method — not as a magic value of `Limit`. `total` already gives a caller the count alongside the smallest useful page.
343:3. **`Upsert` must not overwrite `created_at`.** Its `ON CONFLICT (id) DO UPDATE SET` list excludes `created_at` explicitly. Without that, every IDP re-hydration would silently reset the creation timestamp — on a column `pii-governance.md` keys retention to. This was an omission that would have produced a silent, retention-affecting bug, and it is now stated at both the method table and here.
490:1. **PII/credential separation.** `user_credential` carries no name, phone or address; `user_profile` carries no secret. This is a governance control, not normalization convenience — a breach of one table must not expose the other class of data (`pii-governance.md`). *Enforcement: the column sets in §5, the three-accessor split in §1, and a conformance test asserting neither struct gains a field from the other.*
491:2. **Cascade delete from profile to credential, and its asymmetry.** Deleting a profile destroys its credentials; the account ceases to exist. **The reverse does not hold** — deleting a credential leaves the profile and its PII standing on the `direct` retention clock. Deliberate. If "removing your last credential deletes the account" is wanted, that is a product policy decision, not a schema one, and it is currently *not* what the schema does. *Enforcement: `ON DELETE CASCADE` on the FK; the asymmetry is stated in `pii-governance.md`.*
492:3. **Case, collation and folding.** `ORDER BY LOWER(name) COLLATE "C" ASC, id ASC`, fixed and not caller-configurable, with collation named in DDL as well — `COLLATE "C"` on Postgres, `BINARY` on SQLite. Without this, page 1 of a search returns *different rows* per backend, because Postgres sorts by database collation while SQLite's default byte order puts every uppercase letter before every lowercase one. Cost accepted and named: `C` is byte order, so non-English names sort in an order a human would call wrong — identical-across-backends beats locale-pretty for a system whose whole premise is one contract over three engines. *Enforcement: the DDL collation clause, the `ORDER BY` expression, and a conformance test asserting identical ordering across backends.*
493:4. **`LIKE` escaping.** The DAO escapes `%`, `_` and `\` in caller input and emits an explicit `ESCAPE '\'` on both backends — Postgres has a default backslash escape, SQLite has none unless given. Without this, a search for `50%` matches every row. *Enforcement: the DAO's query construction, plus a conformance test using a term containing `%`.*
494:5. **`Country` normalization at write, not only at read.** Upper-casing the query without upper-casing the table makes a stored `us` silently invisible to a search for `US`. SQLite's `upper()` is ASCII-only — sufficient for alpha-2 codes, written down so nobody assumes it generalizes. *Enforcement: the `CHECK` constraint in §5 plus write-side normalization in both implementations.*
495:6. **UUID primary keys on every backend.** Required for CockroachDB (sequential keys create write hotspots on a single range), supported on Postgres, app-generated on SQLite. Settled by sourced research; do not reopen. *Enforcement: the column types in §5.*
496:7. **`auth_method` as a lookup table, not a native enum.** Adding a method is an `INSERT`, not a migration and not a deploy. *Enforcement: the FK from `user_credential.method_id`; see `migration-approach.md` §4.*
497:8. **The `ON CONFLICT ... DO UPDATE` upsert form.** The one syntax all three backends accept; CockroachDB's `UPSERT` shorthand is deliberately unused to avoid a second dialect. *Enforcement: `Upsert`'s single query shape.*
498:9. **The two-package split** (`postgres` serving Postgres + CockroachDB, `sqlite` separate) and the engine-aware retry seam inside the former. *Enforcement: package boundaries; `decisions/multi-db-abstraction.md`.*
499:10. **`is_active` on `auth_method`.** `ErrInvalidMethod` is documented as "unknown **or inactive**", and the foreign key catches only *unknown* — a cold read applied item 11's own standard back to this document and found it failing its test. `is_active = false` has no DDL enforcement site and cannot have one, for the same reason as item 11: a `CHECK` on `user_credential` cannot read `auth_method`. *Enforcement: the DAO checks `is_active` before insert and returns `ErrInvalidMethod`, plus a conformance test that creates a credential against a deactivated method and asserts the sentinel.* Deactivating a method deliberately does **not** invalidate existing credentials — it prevents new ones.
500:11. **`deletion_log` carries no PII.** It exists to prove a deletion happened after the row is gone; a log containing the name and address of everyone whose data was deleted would be the retention policy's own failure mode wearing an audit trail's clothes. `profile_id` deliberately has no FK, because the row it names is meant not to exist. *Enforcement: the column set in §5, plus a conformance test asserting no PII-shaped column exists on the table.*
501:12. **The `requires_secret` ↔ `secret_state` relationship.** A credential whose method has `requires_secret = false` must not carry `secret_state = 'set'`. **This one cannot be a DDL constraint** — `CHECK` cannot reference another table — so its enforcement site is DAO-layer validation returning `ErrInvalidCredential`, plus a conformance test. Named honestly as one of the two weakest sites in this contract (the other is item 10, `is_active`), because the discipline is worthless if it only records the cases where a clean site existed.

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

1	# LT-38 refinement — S5: conformance suite (cross-backend behavioral conformance)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S5 (LT-38).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why pulled now
8	
9	LT-36 and LT-37's refinement (see `refinement/LT-36-LT-37.md`) cited this suite as the sole enforcement site for roughly half their own acceptance criteria and added a hard rule that neither story can be marked Done until LT-38 lands and those criteria actually pass. Pulling LT-38 now is what closes that gap — it's the next dependency in the chain (`Depends on: S3, S4`), and refining it now means it's ready to run the moment either backend PR lands, rather than sitting as a bottleneck after the fact.
10	
11	## Correction found before drafting (citation error in `backlog.md` itself, not introduced here)
12	
13	`backlog.md`'s S5 description cites "the secret-state rules (§5/§6.11)" for the `requires_secret`/`secret_state` relationship. Checked against `multi-db-strategy.md` directly: **§6.11 is item 11 in §6's numbered list — "`deletion_log` carries no PII" — a different guarantee entirely.** The `requires_secret`/`secret_state` relationship is item 12 (unlabeled with an explicit "§6.12" in the source doc's own prose, but numerically next in the same list, referred to there only as "item 12"). `is_active`'s citation as §6.10 is correct — that one checks out exactly. Fixed below by citing item 12 correctly and not repeating the backlog's §6.11 mislabel.
14	
15	## Acceptance outcome
16	
17	No public-URL surface (same as LT-35/36/37) — this is a test suite, not a deployable behavior change. "Done" means the suite exists once, runs against all three backends from one table-driven test, and every guarantee below is asserted as a specific, named test case (not a general "seems to work" pass) — modeled on the frozen-checksum-plus-structural-diff pattern Oren built for LT-35's conformance test, since 05's own §7 explicitly warns that signature conformance (LT-35) proves nothing about behavioral conformance (this story) — two implementations can match every declaration and still return different rows for the same call.
18	
19	## Acceptance criteria (restated from `backlog.md` S5, corrected and expanded)
20	
21	- [ ] The suite is written once against the `Repository` interface and executed against all three backends (postgres, cockroachdb, sqlite) from one table-driven test file, not duplicated per package. Enforcement site: a single test function parameterized over backend, not three near-identical copies.
22	- [ ] Asserts identical `Search` result sets and ordering across backends for ASCII input — this suite is `multi-db-strategy.md`'s named enforcement site for this guarantee; there is no other. Named test case: a fixed dataset seeded identically on all three backends, a fixed query, asserting row-for-row identical results and order.
23	- [ ] Asserts `errors.Is` sentinel parity for every condition in the §4 translation table, across all three backends — named test case per condition (not one combined test), consistent with LT-36/LT-37's "not-Done-until-LT-38" dependency: this is the specific enforcement site those stories were waiting on.
24	- [ ] Asserts the `requires_secret`/`secret_state` relationship (§6, item 12 — corrected citation, see above) as a named test: creating a credential with `secret_state = 'set'` against a method whose `requires_secret = false` returns `ErrInvalidCredential`, on all three backends.
25	- [ ] Asserts `is_active` enforcement (§6.10) as a named test: creating a credential against a deactivated `auth_method` returns `ErrInvalidMethod`, on all three backends — per the doc's own note that deactivation must not invalidate *existing* credentials, so the test also asserts an existing credential against a since-deactivated method still reads back successfully.
26	- [ ] Asserts empty-string rejection on every `*string` filter field in `ProfileQuery` — one named test case per field (`Name`, `Phone`, `Region`, `Country`), not one combined test, per the "absent, never empty" convention.
27	- [ ] Retention/deletion assertions from `multi-db-strategy.md` §7's own minimum list, each as a named test case: a zero-value `RetentionClass` (`""`) returns `ErrInvalidArgument`; `maxRows` outside `1..10_000` returns `ErrInvalidArgument`; `OldestSurvivingAt` is non-nil when rows remain (including when nothing was old enough to delete) and nil only when the class is empty; `Drained` is false while deletable rows remain at the batch limit and true on the final batch; every delete writes exactly one `deletion_log` row in the same transaction with the reason code the method itself asserts; an already-cancelled context returns before deleting anything; `deletion_log` carries no PII-shaped column (§6.11 — correctly cited here, this is the actual §6.11 guarantee).
28	- [ ] The CockroachDB-specific retry path is exercised for real: at least one test forces a genuine SQLSTATE `40001` (e.g. two concurrent transactions racing on the same row) against a real CockroachDB instance/testcontainer and asserts the operation succeeds after retry, not a mocked retry.
29	- [ ] CI (04's pipeline) runs this suite against every backend including CockroachDB, not just Postgres+SQLite — flagged to 04 if their pipeline configuration doesn't do this; enforcement site is the CI job matrix/config itself, not this suite's own code.
30	- [ ] Following the model Oren built for LT-35: the suite's test data / expected-behavior assertions state, in a comment, which parts are derived directly from `multi-db-strategy.md`'s prose (the guarantees list in §7 and the numbered items in §6) and, where practical, carry the same frozen-copy-plus-checksum protection so a later revision to those sections forces a human re-check rather than the suite silently asserting a stale guarantee. Scoped down from LT-35's version since this suite asserts *behavior*, not *signatures* — a full checksum-gated transcription may not be practical for prose guarantees the way it was for Go signatures; at minimum, each test case's doc comment names the specific `multi-db-strategy.md` line/item it enforces, so a future doc change is at least greppable.
31	
32	## Non-goals
33	
34	- No new backend implementation — this story only tests LT-36/LT-37's output.
35	- No handler/API-layer testing — that's LT-39 and later, against fakes per `decisions/test-double-strategy.md`, not this suite.
36	- No performance/load testing — "identical" here means identical correctness (rows, order, errors), not identical latency; SQLite's full-table-scan search is explicitly *not* required to be as fast as Postgres's indexed search, only as correct.
37	
38	## PO review script
39	
40	1. Confirm the suite is one table-driven test executed against all three backends, not three copies (read the test file structure).
41	2. Confirm each guarantee above has its own named test case (grep test names against the list) — not one broad "conformance" test that silently covers several guarantees and can't tell you which one failed.
42	3. Confirm the CockroachDB retry test forces a real `40001` against a real CockroachDB instance, not a mock — read the test setup.
43	4. Confirm CI's job matrix actually includes CockroachDB as a target, not just Postgres+SQLite (04's pipeline config, once it exists).
44	5. Once LT-36 and LT-37 are both implemented and this suite runs against them: confirm it's actually green on all three backends, and go back and mark the LT-38-dependent criteria in LT-36/LT-37's refinement doc as accepted, updating both stories out of "implemented, verification pending LT-38" status.
45	
46	## Research team review
47	
48	**Desmond Okafor — claims check:** [pending]
49	
50	**Tobias Lindqvist — objection:** [pending]
51	
52	**Naomi Voss — ruling:** [pending]
53	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/decisions/deploy-path.md"
}

1	# Deploy Path — Discovery Findings
2	
3	Written per team-lead's agile-loop brief. Answers: how do we reach the cluster, how does GitHub Actions get code onto it, what does the public URL look like.
4	
5	## 1. What the cluster actually is — correction to the planning-phase narrative
6	
7	The planning-phase docs (`../PLAN.md`, `handoff-04-secrets.md`) described the deployment target as a "lab/dev cluster" reachable only through an external operator agent ("amber-kubernetes"). Direct discovery on this machine found something more specific and more consequential:
8	
9	- This machine already holds a working `kubectl` context (`dev`, cluster `uplift-kub`, 5 nodes, `kubeconfig` at `~/.kube/config`) with direct access — no SSH hop, no operator agent needed to *reach* it.
10	- The "OpenClaw CI/CD in Kubernetes dev cluster" session named in the brief is not currently listed by `ListAgents` — not contacted, since direct access already exists and answers the question it would have answered.
11	- **This is a real, live, multi-tenant cluster, not an isolated sandbox.** Namespaces include `bitwarden` (Warren's actual password manager, `bitwarden.uplifttech.org`), `homeassistant`, `kafka`, `cert-manager`, `backup`, and several real business sites (`salemforensics.com`, `mc.uplifttech.org`/`acrimoniousmc.com`, `calcom.uplifttech.org`, `floracore.uplifttech.org`). All public-facing services follow one pattern: an `Ingress` (class `nginx`) under a real hostname, TLS via `cert-manager`'s `letsencrypt-prod` `ClusterIssuer`, routed through one shared `ingress-nginx-controller` `Service` (`LoadBalancer`, internal IP `192.168.1.200`, presumably port-forwarded to the internet at the router — not verified from here, and not something to change).
12	- **Confirmed with Warren directly before proceeding** (this track paused and asked, given the mismatch between the planning-phase "isolated lab cluster" framing and what discovery found): deploy to this real cluster, in an isolated namespace, with a public tunnel/URL, is approved.
13	
14	**Consequence for this design:** every prior "lab cluster, nothing at stake" assumption is replaced with "shared production infrastructure serving real, unrelated services — isolate aggressively." Namespace, RBAC, and resource limits below are sized for that, not for a sandbox.
15	
16	## 2. GitHub Actions → cluster: self-hosted runner already exists
17	
18	GitHub-hosted runners can't reach a LAN cluster; the choice is a self-hosted runner or GitOps pull. **This cluster already runs Actions Runner Controller (ARC):**
19	- `arc-system` namespace: `arc-gha-rs-controller` (the ARC controller itself).
20	- `arc-runners` namespace: an `AutoscalingRunnerSet` named `k8s-linux-x64` (min 1, max 4 runners), with one runner Pod live.
21	
22	This runner set's current GitHub registration target (which org/repo it's scoped to) isn't determined from here without reading a Secret, and isn't assumed to already point at `wtvamp/loginid-takehome` — that's a question for whoever manages this ARC install, not something to touch. **Decision: do not repurpose the existing runner set.** Deploying this take-home's images and manifests needs a `kubectl apply` from inside the cluster's network with a scoped ServiceAccount — reusing an already-provisioned runner set that may serve other repos/workloads would mean this take-home's deploy job runs with whatever permissions that runner already has, which is exactly the shared-blast-radius problem this project's own designs (NetworkPolicy, RBAC-per-service) have been arguing against. Instead: **a second, narrowly-scoped `AutoscalingRunnerSet`**, registered to `wtvamp/loginid-takehome` specifically, in its own namespace, with a ServiceAccount whose RBAC is limited to the take-home's own namespace only (`get`/`list`/`create`/`update`/`patch` on `Deployments`/`Services`/`Ingresses`/`NetworkPolicies`/`Secrets`-by-name in that namespace, nothing cluster-scoped). This is additive to the cluster's existing ARC controller (one controller can run multiple scale sets), not a competing install.
23	
24	## 3. Namespace and isolation
25	
26	New namespace: `loginid-takehome`. Everything in `./containerization-design.md`'s manifests (both Deployments, the issuer Deployment, both Services, the `NetworkPolicy`) targets this namespace, not the placeholder `loginid-poc` used in the design-phase sketch — that name gets corrected in this pass. Resource limits from `./containerization-design.md` stay as designed (they were sized for "a two-service take-home," which is even more clearly correct now that the cluster is shared with real workloads, not less). A `ResourceQuota` on the namespace is a cheap additional backstop worth adding given the shared-cluster finding — caps total CPU/memory the whole take-home can ever consume regardless of what any single manifest requests.
27	
28	## 4. Public URL
29	
30	Following the cluster's existing, uniform pattern rather than inventing a new one (a Cloudflare Tunnel or similar was the planning-phase's guess; the cluster doesn't use one — every existing public service is a plain `Ingress` + `cert-manager` + the shared `ingress-nginx` `LoadBalancer`):
31	
32	- **Ingress host:** `loginid-takehome.uplifttech.org`, `Ingress` class `nginx`, TLS via `letsencrypt-prod`, matching every other app in the cluster.
33	- **Open item, not resolvable from this session:** the DNS record for that hostname doesn't currently resolve (checked; no answer). Either it needs adding at whatever DNS provider hosts `uplifttech.org` (Warren's call — this track has no DNS credentials and isn't requesting them) or it already resolves via a wildcard this check didn't hit correctly; needs one confirmation before the first deploy's public URL is real rather than theoretical. Flagging to Naomi/PO and Dana now rather than discovering it at the acceptance-script step.
34	- **Routes:** `/api/*` (or a path prefix TBD with 03) → `api-service`; the issuer's endpoints (`/auth/token`, `/.well-known/jwks.json` or similar, per 02/03's final route naming) → `api-service-issuer`. `idp-connector` gets no route — it's never publicly reachable, per its own design.
35	- **Acceptance-script shape this enables:** `https://loginid-takehome.uplifttech.org/healthz` (and an equivalent connector-side path if 03 exposes one) returning up + the deployed commit SHA, per team-lead's target script — `/healthz` already exists in the containerization design and 03's `internal/app` build-info work (per PM's note on LT-34) is what supplies the SHA.
36	
37	## 5. What this changes in `./containerization-design.md` (applied in this pass)
38	
39	- `namespace: loginid-poc` → `namespace: loginid-takehome` throughout.
40	- New `Ingress` resource (host above, TLS via `letsencrypt-prod`) added alongside the existing Services.
41	- A namespace-level `ResourceQuota` added as a backstop.
42	- Everything else (two Deployments, the issuer split, `NetworkPolicy`, resource limits per container, the migration `Job`) is unchanged — those were designed correctly for "shared infrastructure, isolate aggressively" even under the earlier, wrong assumption that this was a private sandbox.
43	
44	## 6. CI/CD sequencing (per team-lead's split)
45	
46	The PR-check workflow (lint, build, `-race` tests, `govulncheck`) needs none of the above and ships first, on GitHub-hosted runners — no cluster access required. The merge-to-main workflow (build+push images to GHCR, apply manifests via the new scoped runner set, print the public URL + commit SHA in the job summary) follows once the runner set and namespace exist. Both live at `.github/workflows/` at the repo root.
47	
48	---
49	*AI tooling note: discovery run directly by Theo (Sonnet, this session) via `kubectl`, `dig`, and `ListAgents` — no external operator agent contact was needed or made. Confirmed with Warren directly (AskUserQuestion) before treating the real-cluster finding as a green light, given the mismatch with the planning-phase framing.*
50	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/refinement/LT-45-LT-47.md"
}

1	# LT-45 / LT-47 refinement — containerization + K8s manifests, and CI/CD pipeline
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Theo Bergman (04). **Source:** `04-infra-devops/backlog.md` Story 1 (LT-45) and Story 3 (LT-47); `04-infra-devops/decisions/deploy-path.md` (Theo's discovery).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Theo Bergman.
6	
7	## Why pulled as a pair, and why now
8	
9	LT-34 is implemented and merged but not Done — it becomes Done only once deployed and reviewable at a public URL, and that deploy path is exactly LT-45 (manifests) + LT-47 (the pipeline that applies them). This pair is the unblock for the whole agile-loop bar ("done = deployed"), not just two more stories in the queue — every story behind it (LT-35/36/37/38's eventual deploy, LT-34's own closure) is waiting on this landing.
10	
11	## Correction to the original story text, discovered by Theo (not assumed here)
12	
13	Both `backlog.md` stories were written against a "lab cluster reached via a public tunnel" assumption from planning. Discovery found the real target: **Warren's actual home/production Kubernetes cluster** (`uplift-kub`, 5 nodes), shared with real unrelated workloads (Bitwarden, Home Assistant, several live business sites) — not an isolated sandbox, and not fronted by a tunnel but by a standard `nginx` `Ingress` + `cert-manager` pattern already used by every other app on the cluster. Confirmed directly with Warren before proceeding (`decisions/deploy-path.md` §1). This refinement is written against the real target, not the planning-phase placeholder — LT-45's acceptance criteria below reflect `namespace: loginid-takehome` (not the design-phase placeholder `loginid-poc`), the added `Ingress` and `ResourceQuota`, and a second, narrowly-scoped GitHub Actions runner set rather than repurposing the cluster's existing shared one.
14	
15	**Flagging for the record, not a blocker:** this is a materially higher-stakes deploy target than "an isolated lab cluster" — a misconfigured `NetworkPolicy`, an over-broad RBAC grant, or an unbounded resource request on this take-home's manifests has a real, if contained, blast radius against Warren's own production services. The isolation measures below (dedicated namespace, scoped RBAC, `ResourceQuota`, `NetworkPolicy` default-deny) are the mitigations Theo's already designed for exactly this; this refinement's acceptance criteria treat them as load-bearing, not optional hardening.
16	
17	## Acceptance outcome (LT-45 + LT-47 together = the first end-to-end vertical slice)
18	
19	"Done" for this pair, concretely: `https://loginid-takehome.uplifttech.org/healthz` (on `api-service`) returns HTTP 200 with `{"status":"ok","service":"api-service","build":"<commit-sha>"}`, and the same for `idp-connector`'s equivalent path if it's given one — reachable by anyone with the URL, no VPN, no kubeconfig. This is LT-34's own review script, finally executable.
20	
21	**Open item, not yet resolved — flagged here so it isn't a surprise at review time:** the DNS record for `loginid-takehome.uplifttech.org` doesn't currently resolve (per `decisions/deploy-path.md` §4). This story cannot be accepted as Done until it does — that's a hard dependency, not a nice-to-have, since "reviewable at a public URL" is the whole bar. Owner of the DNS fix is whoever manages `uplifttech.org`'s DNS (Warren, per Theo — this track has no DNS credentials and isn't requesting them).
22	
23	## LT-45 acceptance criteria (restated from `backlog.md`, corrected for the real cluster)
24	
25	- [ ] Both images build multi-stage (distroless final stage, non-root, read-only root filesystem) and contain nothing but the binary (+ CA certs for `idp-connector`). Enforcement site: the Dockerfile's final `COPY` list.
26	- [ ] Neither Pod can write its own root filesystem at runtime. Enforcement site: `securityContext.readOnlyRootFilesystem: true`.
27	- [ ] `idp-connector` is unreachable except from `api-service` — enforced by a **default-deny `NetworkPolicy`**, since the cluster's namespace default is allow, not deny; this is not optional hardening on a shared cluster. Enforcement site: the `NetworkPolicy` ingress rule scoped to `api-service`'s pod selector.
28	- [ ] The JWT signing private key is mounted only into `api-service-issuer`'s Deployment, never `api-service`'s own — enforcement site: `api-service`'s manifest carries no volume/mount referencing that `Secret`, verified by manifest inspection, not RBAC alone.
29	- [ ] All manifests target `namespace: loginid-takehome` (corrected from the design-phase placeholder `loginid-poc`) — enforcement site: every manifest's `metadata.namespace`, grepped for the old placeholder returning nothing.
30	- [ ] A namespace-level `ResourceQuota` caps total CPU/memory the whole take-home can consume, independent of any single manifest's own `resources.limits` — added specifically because this is shared production infrastructure, per `decisions/deploy-path.md` §3. Enforcement site: the `ResourceQuota` object itself, applied to the namespace.
31	- [ ] A public `Ingress` (class `nginx`, TLS via `letsencrypt-prod`) routes `/healthz` (and whatever path prefix 03 finalizes for the rest of the API) to `api-service`, and issuer-specific routes to `api-service-issuer`. `idp-connector` gets **no route** — never publicly reachable, per its own design. Enforcement site: the `Ingress` resource's path rules.
32	- [ ] The migration `Job` runs with `parallelism: 1` and is gated by the CI pipeline's concurrency mechanism (LT-47), not Kubernetes ordering alone.
33	- [ ] The GitHub Actions deploy step uses a **second, narrowly-scoped `AutoscalingRunnerSet`** registered specifically to `wtvamp/loginid-takehome`, with RBAC limited to the `loginid-takehome` namespace only (no cluster-scoped permissions) — **not** the cluster's existing shared runner set, per `decisions/deploy-path.md` §2's blast-radius reasoning. Enforcement site: the runner set's own RBAC manifest, scoped by namespace, reviewed independently of the take-home's application manifests.
34	
35	## LT-47 acceptance criteria (restated from `backlog.md`, revised for real deploy per the agile-loop bar)
36	
37	- [ ] A lint or test failure blocks merge — required status check, not advisory.
38	- [ ] A CockroachDB-specific SQL incompatibility surfaces at PR time via a dedicated CockroachDB testcontainer job.
39	- [ ] Only one migration run can reach the migrate stage at a time, across concurrent deploys — enforced by the pipeline's own concurrency group/mutex on the deploy environment.
40	- [ ] No secret enters a build log or image layer — `gitleaks` stage plus the Dockerfile's minimal `COPY` list (LT-45).
41	- [ ] **Revised — no longer "documented but not invoked":** per Theo's explicit agreement (no objection to full auto-deploy on merge at this take-home's scale, no manual gate requested), the deploy stage actually runs on merge to main — build → push images to GHCR → apply manifests via the scoped runner set → print the public URL and deployed commit SHA in the job summary. This replaces the design-phase criterion that treated deploy as describe-only; that criterion predates the agile-loop bar ("done = deployed and reviewable at a public URL") and is now obsolete, not just superseded in emphasis.
42	- [ ] The PR-check workflow (lint, build, `-race` tests, `govulncheck`) requires no cluster access and runs on GitHub-hosted runners; only the merge-to-main deploy workflow uses the scoped self-hosted runner set — per `decisions/deploy-path.md` §6's sequencing, so a PR from an untrusted or draft branch never touches cluster credentials.
43	- [ ] The job summary on a successful merge-to-main run states the public URL and the deployed commit SHA explicitly, in plain text — this is what makes LT-34's PO review script (and every later story's) executable without a human hunting through logs.
44	
45	## Non-goals
46	
47	- No DNS management — the record's existence/correctness is Warren's call, flagged as an open item above, not something this track has credentials to fix.
48	- No change to the cluster's existing ARC controller or its other runner sets/workloads — additive only.
49	- No production-grade autoscaling, multi-region, or blue/green deploy — a single-replica, single-region deploy is sufficient for this take-home's scale; flag if that assumption is wrong.
50	- No change to other namespaces or other apps' Ingress/DNS on this cluster.
51	
52	## PO review script
53	
54	1. Confirm the DNS record for `loginid-takehome.uplifttech.org` resolves (a plain `dig`/browser check) — if it doesn't, this story is not accepted, full stop, regardless of what else passes.
55	2. `curl -s https://loginid-takehome.uplifttech.org/healthz` — confirm HTTP 200, `{"status","service","build"}` only (per 02's ruling, already verified in LT-34's own review), and that `build` is a real commit SHA, not `"unknown"`.
56	3. Confirm the GitHub Actions job summary for the merge-to-main run states the public URL and the deployed SHA in plain text.
57	4. Read the manifests (or the PR diff) for: `namespace: loginid-takehome` everywhere (no `loginid-poc` leftover), the `NetworkPolicy` default-deny + `api-service`-only ingress rule on `idp-connector`, the `ResourceQuota` object, and that `api-service`'s manifest has no mount referencing the JWT signing `Secret`.
58	5. Confirm the deploy-stage runner set is the new, narrowly-scoped one (check its RBAC binding's namespace scope), not the cluster's pre-existing shared runner set.
59	6. Confirm the PR-check workflow (separate from merge-to-main) runs with no cluster credentials available to it — check the workflow YAML's runs-on/permissions, not just that it passes.
60	7. Trigger (or wait for) a second commit's deploy and re-run step 2, confirming the `build` SHA changes — this is LT-34's own freshness check, finally executable end-to-end.
61	
62	## Research team review
63	
64	**Desmond Okafor — claims check:** [pending]
65	
66	**Tobias Lindqvist — objection:** [pending]
67	
68	**Naomi Voss — ruling:** [pending]
69	

{
  "command": "grep -n -i \"gate\\|auto-deploy\\|manual\\|objection\\|agree\" /Users/warrenthompson/Source/LoginID/04-infra-devops/decisions/deploy-path.md"
}

(Bash completed with no output)

{
  "command": "cd /Users/warrenthompson/Source/LoginID && git fetch origin -q; git diff origin/main -- 03-engineering-delivery/backlog.md 02-ai-security-architecture/handoff-04-secrets.md 2>&1 | head -30\necho \"---backlog deps grep---\"\ngrep -n -i \"LT-32\\|LT-40\\|S7\\|issuer\" 03-engineering-delivery/backlog.md | head -40"
}

---backlog deps grep---
11:**Description:** Stand up the Go module and the two-binary skeleton the org already committed to in `PLANNING.md`'s Service boundaries section: `cmd/api-service`, `cmd/idp-connector`, both thin wrappers over a shared `internal/app` bootstrap package (route registration, config wiring) per `decisions/go-layout-debate.md`. `internal/config` loads the env-var surface named in `PLANNING.md` (`DB_DRIVER`, `DB_DSN`/`DB_DSN_FILE`, `HTTP_ADDR`, `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE`, `IDP_ABC_*`). Stub handlers only — no DAO, no auth, no connector logic yet; this story's job is a buildable skeleton other stories attach to.
102:- [ ] `authorize()` runs as an explicit call inside each handler after request parsing, before the DAO call — enforcement site: handler code structure, per the go-layout-debate.md-adjacent ruling recorded in this track's reply to 02. `authorize()` checks the `caller_referral`/caller-role data against the token-issuer's own datastore, not against 05's schema — 05 was never assigned that table (`handoff-03-auth.md` v3, F8).
118:## S7. Auth middleware (JWT validation) (LT-40)
120:**Description:** The middleware at the `cmd/api-service` edge validating the client-credentials JWT scheme from `handoff-03-auth.md` v3 — public-key-only verification, `sub`/`scope`/`exp`/`iat`/`aud` claim checks, `kid`-based key rotation, no denylist (TTL-only revocation, a deliberate trade-off not to be re-litigated). Also covers the `APP_MODE=verifier|issuer` split (`PLANNING.md`) — this Deployment mode never mounts the signing key regardless of `APP_MODE`'s value, since `verifier` is this story's own code path and `issuer` is a separate mode of the same binary the F13 fix depends on to keep the two isolated by Deployment, not just by RBAC.
127:- [ ] The token-issuing endpoint (the `APP_MODE=issuer` mode) has its own failed-grant rate limiting and progressive backoff per `client_id` and per source IP, separate from the resource-API limits below, with alerting on a sustained run of failed grants against one `client_id` — enforcement site: issuer-mode middleware, distinct from the verifier-mode rate limiter (`handoff-03-auth.md` v3).
158:**Description:** Table-driven unit tests for the handler layer (S6/S7, mocked DAO via S2's hand-written fakes) and the connector (S8, mocked HTTP), per `decisions/test-double-strategy.md`. The DAO's own cross-backend correctness is S5's job, not this story's — this covers request/response shape, auth rejection paths, and error-translation-to-HTTP-status mapping.
166:**Depends on:** S6, S7, S8.
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

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

1	# LT-32 refinement — split the token issuer into its own Deployment with isolated signing-key custody
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03, `APP_MODE` binary support), Theo Bergman (04, manifest/Deployment split); design owner Marcus Ilori (02, `handoff-04-secrets.md`/F13). **Source:** `02-ai-security-architecture/backlog.md` S12 (LT-32).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterparts Renata Cole and Theo Bergman.
6	
7	## Why this one, not LT-39, and why now
8	
9	Checked the actual dependency chain rather than assuming: `backlog.md` S7 (auth middleware, LT-40) lists "04: `APP_MODE` Deployment split" as a hard dependency — that's this story. S6 (the search/retrieve handlers, LT-39) doesn't list LT-32 or S7 as a formal dependency (it can be built and merged against fakes without either), but a handler that calls `authorize()` on claims nothing has yet populated isn't a **reviewable, working endpoint** — it's code that compiles and can't be correctly exercised end-to-end at the public URL. LT-32 is the actual bottleneck: nothing downstream (S7, and a genuinely working authenticated S6) can be truly deployed and reviewed without it. Confirmed by checking the live manifest directly (`deploy/manifests.yaml` on `main` as of this refinement): no `api-service-issuer` Deployment exists, no JWT signing-key mount — this story hasn't landed in any form yet, it isn't partially done.
10	
11	Per Jira's own resolved ambiguity (`LOG.md`: "LT-34 blocks LT-32"), LT-32 was gated on LT-34 landing — LT-34 is now implemented and deployed (review pending only on the build-SHA fix, unrelated to this story), so LT-32 is unblocked and ready to pull.
12	
13	## What this story actually is, restated plainly
14	
15	Not a new binary, not new business logic — a **Deployment-topology fix** closing a real security gap the consistency pass found (F13): `handoff-04-secrets.md` said the signing key "never touches `api-service`" while the manifest mounted it into every replica of one `api-service` Deployment. RBAC on a `Secret`'s `get` verb does nothing once the volume is already mounted into a running container — so the only real fix is a second Deployment of the same image, selected by `APP_MODE=issuer` vs. the default, with its own ServiceAccount that alone can mount the key.
16	
17	## Acceptance outcome (no new public-URL behavior yet, but it's the load-bearing gate before any is trustworthy)
18	
19	This story doesn't add a caller-visible endpoint — `/healthz` still looks the same. "Done" is verified by manifest inspection and a runtime check that the two Deployments' pods genuinely differ in what they can mount, not by curling something new.
20	
21	## Acceptance criteria (restated from `backlog.md` S12)
22	
23	- [ ] `api-service` (the Go binary) supports an `APP_MODE` environment variable selecting issuer vs. default (verifying) behavior from one binary/image — no second `cmd/` entrypoint, per `handoff-04-secrets.md`'s explicit "not a third binary" ruling. Enforcement site: `internal/config` reads `APP_MODE`, `internal/app` branches on it at startup.
24	- [ ] Two Kubernetes Deployments exist in the manifest (`api-service` and `api-service-issuer`), each with its own ServiceAccount. Enforcement site: `deploy/manifests.yaml`, two distinct `Deployment` objects.
25	- [ ] Only `api-service-issuer`'s pod spec mounts the JWT signing-key `Secret` — **physically absent, not just RBAC-denied, from `api-service`'s pod spec.** Enforcement site: manifest inspection of `api-service`'s volumes/volumeMounts list, which must contain no reference to that `Secret` at all — a reviewer checking RBAC alone would miss a mistakenly-shared mount, per F13's own finding that RBAC doesn't prevent this class of leak.
26	- [ ] RBAC (`Role`/`RoleBinding`) additionally restricts `get`/`list` on the signing-key `Secret` to `api-service-issuer`'s ServiceAccount specifically — a second, independent layer on top of the physical-absence criterion above, not a substitute for it.
27	- [ ] 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 — enforcement site: a startup-time check/test asserting the verifying binary's process has no path to the private key even if `APP_MODE` were misconfigured to `issuer` on that Deployment (defense against a manifest typo, not just a design intent).
28	- [ ] `containerization-design.md`'s single-Deployment mount (the line the consistency pass named) is removed from the design doc and replaced with the two-Deployment description, so a future reader of the design doc sees the corrected shape, not the superseded one.
29	- [ ] The issuer Deployment's public route (whatever path 02/03 finalize for token issuance — e.g. `/auth/token`) is added to the `Ingress`, routed to `api-service-issuer`, distinct from `api-service`'s existing routes; `idp-connector` remains unrouted, unaffected by this change.
30	
31	## Non-goals
32	
33	- No change to the JWT scheme itself (claims, TTL, `kid` rotation mechanics) — that's `api-auth-design.md`'s design and S7's (LT-40) implementation, not this story's.
34	- No auth middleware implementation (JWT verification, rate limiting) — that's S7 (LT-40), which depends on this story but is a separate pull.
35	- No handler-layer `authorize()` logic — that's S6 (LT-39), also downstream of this and S7.
36	- No change to `idp-connector` — it has no issuer/verifier split; this story only touches `api-service`.
37	
38	## PO review script
39	
40	1. Confirm `deploy/manifests.yaml` (or wherever the PR puts it) has two distinct `Deployment` objects for the `api-service` image, each with its own `ServiceAccount`.
41	2. Read `api-service-issuer`'s pod spec: confirm the signing-key `Secret` volume mount is present.
42	3. Read `api-service`'s (verifying) pod spec: confirm **no** reference to that `Secret` anywhere — no volume, no volumeMount, not even an unused one.
43	4. Read the `Role`/`RoleBinding` scoping `get`/`list` on the `Secret` to the issuer's ServiceAccount specifically, not both.
44	5. Confirm `containerization-design.md` no longer describes the single-Deployment mount the consistency pass flagged.
45	6. Once deployed: hit the issuer's route (once 02/03 finalize its path) and confirm it's reachable and distinct from `api-service`'s existing routes; confirm `idp-connector` is unaffected (still unrouted).
46	7. If feasible, a deliberate negative check: attempt (from outside, with no special access) to read the signing-key `Secret` via the verifying Deployment's own ServiceAccount token — should fail, confirming criteria 3+4 together, not just one or the other.
47	
48	## Research team review
49	
50	**Desmond Okafor — claims check:** [pending]
51	
52	**Tobias Lindqvist — objection:** [pending]
53	
54	**Naomi Voss — ruling:** [pending]
55	

{
  "command": "grep -n \"^## S\\|Depends on\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/backlog.md"
}

9:## S1. Scaffolding: Go module, entrypoints, shared bootstrap, config loading (LT-34)
19:**Depends on:** none.
26:## S2. DAO interface, domain types, sentinels, factory (LT-35)
36:**Depends on:** S1; **05: DAO Go-shaped contract** (`multi-db-strategy.md`, stable, accepted).
43:## S3. Postgres/CockroachDB DAO implementation (LT-36)
54:**Depends on:** S2.
61:## S4. SQLite DAO implementation (LT-37)
71:**Depends on:** S2.
78:## S5. Conformance suite (05's requirement, cross-backend) (LT-38)
89:**Depends on:** S3, S4.
96:## S6. REST handlers: search/retrieve user_profile (Q2) (LT-39)
111:**Depends on:** S2; **02: Auth scheme and authorization hand-off** (`handoff-03-auth.md` v3, accepted).
118:## S7. Auth middleware (JWT validation) (LT-40)
131:**Depends on:** S1; **02: Auth scheme and authorization hand-off** (`handoff-03-auth.md` v3, accepted); **04: `APP_MODE` Deployment split** (`containerization-design.md`, F13).
138:## S8. Connector: /auth + /identity (Q3) (LT-41)
149:**Depends on:** S1; **02: Connector security spec** (`connector-security.md`, accepted); **02: Auth scheme and authorization hand-off** (`handoff-03-auth.md` v3, accepted, for the connector's own self-auth).
156:## S9. Handler and connector unit tests (LT-42)
166:**Depends on:** S6, S7, S8.
173:## S10. README: implemented vs. stubbed, AI workflow, test strategy (LT-43)
182:**Depends on:** S1–S9.
189:## S11. Retention sweep: DeleteExpired / DeleteProfile wiring (LT-44)
201:**Depends on:** S2; **05: retention sweep contract addendum** (`multi-db-strategy.md` §3c, pending Oren's first-pass review — same process as the original contract); **04: Story 5 — Observability** (`04-infra-devops/backlog.md`, owns where the sweep job runs, and the `rows-examined`/`rows-deleted`/`oldest-surviving-row-age` metrics sink and alert rule this story's `OldestSurvivingAt` feeds). Named as Story 5, not Story 6 — Story 6 is log-sink retention for the audit trail, a different concern; Story 5 is the one that actually specifies the retention-sweep alerting this story depends on.

{
  "command": "grep -n -A 15 \"^## S12\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/backlog.md\necho \"---F13---\"\ngrep -n -B2 -A 15 \"F13\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md"
}

258:## S12 — Split the token issuer into its own Deployment with isolated signing-key custody (LT-32)
259-
260-**Status: open** (from `../decisions/cross-track-consistency.md` F13).
261-
262-**Description:** The pass caught a real contradiction: `handoff-04-secrets.md` said the JWT signing private key "never touches `api-service`" while also defining the issuer as "a mode of `api-service`," and 04's manifest resolved that by mounting the signing key into every replica of a single `api-service` Deployment — RBAC on a Secret's `get` verb does nothing to stop a volume already mounted into a running container. Fixed at the design level in `handoff-04-secrets.md` Assumption 2 and row 2: the issuer runs as a second Deployment of the same `api-service` image, selected by an environment variable (`APP_MODE=issuer` vs. default), with its own ServiceAccount that alone mounts the signing-key Secret. This story is the implementation and manifest work that design change requires — it did not exist as a story before the pass.
263-
264-**Acceptance criteria:**
265-- [ ] `api-service` supports an `APP_MODE` environment variable selecting issuer vs. verifying behavior from one binary/image.
266-- [ ] Two Kubernetes Deployments exist, each with its own ServiceAccount; only the issuer Deployment's pod spec mounts the JWT signing-key Secret — enforcement site: the manifest's volume mounts plus RBAC Role scoping `get`/`list` to the issuer's ServiceAccount.
267-- [ ] The verifying Deployment's pod spec contains no reference to the signing-key Secret at all (not just RBAC-denied — physically absent from its mounts).
268-- [ ] `containerization-design.md`'s mount at the lines the pass named is removed and replaced with the two-Deployment shape.
269-
270-**Depends on:** `handoff-04-secrets.md` v2 (this track); 03's `APP_MODE` config surface addition; 04's manifest change.
271-
272-**Model/effort:** sonnet, high (03 implementation); sonnet, high (04 manifest).
273-
---F13---
1-# Hand-off 02 → 04: Secrets inventory and never-log list
2-
3:Status: **v2** — v1's S7 objection turn and 04's Newcomer cold read are both resolved and folded in below; this revision additionally resolves four findings from the cross-track consistency pass (F12 this version label, F13 the signing-key custody contradiction, F15 a missing credential row, F50 two never-log gaps). 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`.
4-
5-## Assumptions this hand-off makes
6-
7-1. Deployment target is 04's **real Kubernetes lab cluster, reachable behind a public tunnel** (Warren's implementation go-ahead, 2026-09-12 — updated from a design-only reference). Delivery mechanism is therefore Kubernetes-native `Secret` objects unless 04 chooses an external store; every requirement below is written so it still holds if the mechanism changes. **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.
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.
9-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.
10-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.
11-
12-## Secrets inventory
13-
14-| # | Secret | Used by | Injection requirement (02 sets it) | Rotation expectation | Kubernetes-native note (04's mechanism) | Never-log |
15-|---|---|---|---|---|---|---|
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 |
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 |
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) |
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 |
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 |
21-| 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 anywhere in this flow — there is nothing here for 04 to provision | Yes — never, including error paths, on both sides of the exchange |
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 |
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 |
24-| 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 | `kubernetes.io/tls` `Secret`; issuance mechanism is 04's call | Yes |
25-| 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** |
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 |
27-
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.
29-
30-## Kubernetes-specific requirements (04 implements; 02 sets)
31-
32-- **Secrets at rest in etcd are base64, not encrypted, by default.** Either enable encryption at rest for the `Secret` resource type, or source values from an external store that never writes plaintext to etcd. One or the other; the design must say which.

{
  "command": "grep -n \"LT-34 blocks LT-32\\|LT-32\" /Users/warrenthompson/Source/LoginID/LOG.md"
}

77:**Third pass — planning declared internally consistent (2026-09-12).** Seams 1/4, 3, 5, 9 all AGREE, no new regression: the caller-holds-token model is stated identically in `connector-security.md` §1/§2/attack-tree row 3, `api-connector-design-rationale.md:40,72`, `ux-notes.md:27`, and `handoff-04-secrets.md` rows 6/7; the issuer is one design across `handoff-03-auth.md:20`, `PLANNING.md`'s `APP_MODE`, and 04's issuer Deployment + Service + reachability paragraph; the DAO preamble is a banner; `multi-db-strategy.md:225` names `api-service` as the identity resolver; the audit-stream row and the deliberately excluded `deletion_log` table are drawn the same way by 05 and 04. Seam 13 found five stale restatements, all cosmetic, none load-bearing (03's layout artifacts, two composite-method summaries, a v2→v3 hand-off citation, one retention-class name) — routed to Renata and Theo; no further pass. **Backlog complete in Jira:** 50 issues `LT-1`…`LT-50` under five Epics — 01 `LT-6`…`LT-13` (all Done), 05 `LT-14`…`LT-19` + `LT-50` (Done), 02 `LT-21`…`LT-33` (S1–S10 Done; S11 post-implementation review, S12 issuer split-Deployment, S13 connector credential wiring open), 03 `LT-34`…`LT-44` (all open, gated on the code go), 04 `LT-45`…`LT-49` + `LT-20` (open, design complete); 55+ `Blocks` links including every cross-track hand-off; two ambiguous references ruled by team-lead (`LT-34` blocks `LT-32`; `LT-42` blocks `LT-47`). Consistency-pass tally across three passes: 52 findings, 4 regressions from fixes, 5 cosmetic restatements — every one traceable to a file:line and an owner, none silently dropped.

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

1	# LT-39 refinement — S6: REST handlers for search/retrieve user_profile (Q2)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S6 (LT-39); `02-ai-security-architecture/handoff-03-auth.md` v3.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one now
8	
9	LT-32 (issuer Deployment split) is refined and handed off, unblocking S7 (auth middleware, LT-40), which this story sits alongside. LT-39 itself formally depends only on S2 (merged) and 02's accepted hand-off — it doesn't block on LT-32/S7 in `backlog.md`'s own dependency graph, and its handlers can be built and merged against fakes right now, per `decisions/test-double-strategy.md`. Refining it now means it's ready the moment S7 lands, rather than sitting as the next bottleneck after that.
10	
11	## Acceptance outcome
12	
13	This is the first story that adds real, caller-visible REST behavior — not just a skeleton. But it depends on S7 (auth middleware) to be *truly* reviewable at the public URL with a real token; until S7 lands, "done" for this story specifically means: handlers implemented and tested against fakes, all criteria below satisfied in code and unit tests, with the actual live-URL, real-token exercise deferred to whenever S7 merges (same "verification pending" pattern as LT-36/LT-37 waiting on LT-38 — not waived, just sequenced).
14	
15	## Acceptance criteria (restated from `backlog.md` S6, cross-checked against `handoff-03-auth.md` v3)
16	
17	- [ ] Implements `handoff-03-auth.md` v3's scope vocabulary (`profile:read:own`, `profile:read:any`, `profile:search`) and pagination/rate-limit numbers without re-deriving 02's authz-scoping reasoning.
18	- [ ] `authorize(sub, scope, target)` runs as an explicit call inside each handler after request parsing, before the DAO call — not a second middleware, per v3's confirmed placement (it needs the parsed target id, which pre-routing middleware doesn't have). `authorize()` checks `caller_referral`/caller-role data against the token-issuer's own datastore, **not against 05's schema** — 05 was never assigned that table.
19	- [ ] `profile:search` responses carry masked PII fields by default (phone as `***-***-1234`, address reduced to `locality`/`region` only). Unmasked detail requires a separate, separately-audited follow-up call under `profile:read:own` or `profile:read:any` against the specific record id — **this reuses the existing scopes, it does not invent a fourth "expand" flag**; masking is a `profile:search`-response property, not a per-call parameter. Enforcement site: the search-response serialization path is a distinct code path from the read-response one, not the same serializer with a masking flag.
20	- [ ] **Pagination — clarified per v3's F-pag correction, since `backlog.md`'s original wording could be misread by an implementer:** the API-facing cursor is opaque to the caller — callers cannot construct or walk one by hand — but it may (and in the simplest correct implementation, does) encode the DAO's own `Offset` directly underneath. "Cursor-based pagination only" means **the caller-facing contract is opaque-cursor-only, not that the handler is forbidden from using the DAO's `Offset` field internally.** The actual anti-enumeration control is the cumulative distinct-record-touch counter (next bullet), not the cursor mechanism itself. Default page size 20, hard ceiling 50, enforced in the handler before the DAO is ever called — the DAO's own `Limit` bound (1..100, default 50) is a second, independent backstop only reachable if the handler clamp is bypassed, not a second policy a caller can rely on.
21	- [ ] A cumulative distinct-record-touch counter per caller per rolling 24h window is enforced, independent of per-minute rate limits, applying to **both** `profile:search` and `profile:read:any` unconditionally — a valid `reason_code` on `read:any` satisfies the per-call `authorize()` check but does **not** exempt the caller from this cumulative cap (v3's explicit fix to an earlier wording that made the counter a no-op for `read:any`). Enforcement site: a counting store incremented once per distinct record id returned, checked before the response is sent, alerting on threshold.
22	- [ ] A search request with no filter field at all is rejected by this handler with a 400 before it reaches the DAO — the DAO itself treats an all-nil `ProfileQuery` as legal, so this handler-layer rejection is the only enforcement site for "no bare unconstrained search."
23	- [ ] A `profile:search` query rejected for exceeding the result cap unconstrained (e.g. a bare wildcard) is rejected outright, not truncated — enforcement site: the same in-handler call site, checked before the query is built.
24	- [ ] Unmapped DAO errors never surface `err.Error()` to the client; only the mapped sentinels' safe messages do — per `decisions/error-semantics.md`'s boundary translation function. Authn failures (missing/invalid token) return 401; scope failures and `authorize()` policy denials both return 403 with an identical client-visible body, distinguished only in the audit log.
25	- [ ] `profile:read:any` requests carry a `reason_code` from the closed enum (`support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`) on every call, logged with the audit record — adding a fifth value is a documented change to this enum, not a runtime config toggle.
26	- [ ] When `api-service` calls `idp-connector` on a caller's behalf, it obtains a `connector:identity-lookup`-scoped token first, using its own `CONNECTOR_CLIENT_ID`/`CONNECTOR_CLIENT_SECRET` credential — distinct from S8's idp-connector-side handlers, which only validate that token, not issue or hold this credential.
27	
28	## Non-goals
29	
30	- No auth middleware implementation — that's S7 (LT-40), a separate pull; this story's own tests use fakes for the auth context per `decisions/test-double-strategy.md`.
31	- No real backend I/O — built against fakes, per `decisions/test-double-strategy.md`; LT-36/LT-37/LT-38 land separately.
32	- No connector-side (`idp-connector`) handler work — that's S8, which only validates the token this story's handler obtains, not the same code.
33	- No rate-limit/counter *mechanism* choice (Redis vs. in-process) — that's Renata's implementation call, per v3's own "the mechanism is your call" framing.
34	
35	## PO review script
36	
37	1. Confirm `authorize()` is called explicitly inside each handler, after parsing, before the DAO call — not registered as middleware. Read the handler code directly.
38	2. Confirm the search-response serializer and the read-response serializer are genuinely distinct code paths (grep for two separate serialization functions, not one with a masking conditional).
39	3. Confirm the pagination cursor is opaque at the API boundary (no caller-suppliable offset/page-number parameter accepted) — but don't fail the story if the handler internally passes `Offset` to the DAO; that's the correct implementation per the F-pag clarification above.
40	4. Confirm the cumulative distinct-record-touch counter's test coverage includes a `profile:read:any` case with a valid `reason_code` still hitting the cap — this is the specific regression v3 fixed, so it needs its own test, not just a `profile:search` test.
41	5. Confirm a 401/403 test pair exists asserting identical response bodies for a scope failure vs. an `authorize()` denial, distinguished only in a separate audit-log assertion.
42	6. Once S7 lands and this is deployed: a live-URL check with a real client-credentials token, confirming an actual masked search response and an actual 401 on a missing/expired token — deferred, not waived, per the Acceptance outcome above.
43	
44	## Research team review
45	
46	**Desmond Okafor — claims check:** [pending]
47	
48	**Tobias Lindqvist — objection:** [pending]
49	
50	**Naomi Voss — ruling:** [pending]
51	

{
  "command": "sed -n '96,117p' /Users/warrenthompson/Source/LoginID/03-engineering-delivery/backlog.md"
}

## S6. REST handlers: search/retrieve user_profile (Q2) (LT-39)

**Description:** The client-facing handlers in `internal/api` implementing the assignment's Q2 (search and retrieve `user_profile`), built against S2's interfaces (fakes stand in for a real backend per `decisions/test-double-strategy.md`, so this doesn't wait on S3/S4). Implements the object-level `authorize(sub, scope, target)` call as an explicit in-handler step, not a second middleware, per the ruling in `handoff-03-auth.md` v3 (my own answer, confirmed by 02).

**Acceptance criteria:**
- [ ] Implements `handoff-03-auth.md` v3's scope vocabulary and pagination/rate-limit numbers without re-deriving 02's authz-scoping reasoning.
- [ ] `authorize()` runs as an explicit call inside each handler after request parsing, before the DAO call — enforcement site: handler code structure, per the go-layout-debate.md-adjacent ruling recorded in this track's reply to 02. `authorize()` checks the `caller_referral`/caller-role data against the token-issuer's own datastore, not against 05's schema — 05 was never assigned that table (`handoff-03-auth.md` v3, F8).
- [ ] `profile:search` responses carry masked PII fields by default (e.g. phone as `***-***-1234`, address reduced to `locality`/`region` only); unmasked detail requires a separate, separately-audited follow-up call under `profile:read:own` or `profile:read:any` against the specific record id — enforcement site: the search-response serialization path, distinct from the read-response one (`handoff-03-auth.md` v3, resolves F6).
- [ ] Cursor-based pagination only, default page size 20, hard ceiling 50 — enforcement site: the pagination parameter parsing, rejecting any offset-based parameter. **The handler's 20/50 is the authoritative clamp, enforced before the DAO is ever called** — the DAO's own `Limit` bound (1..100, default 50 per `multi-db-strategy.md`) is a second, independent backstop only reachable if the handler clamp is bypassed, not a second policy a caller can rely on (consistency-pass F10: no document previously said which of the two governs).
- [ ] A search request with no filter field at all is rejected by this handler before it reaches the DAO — the DAO itself treats an all-nil `ProfileQuery` as legal (`multi-db-strategy.md`), so this handler-layer rejection is the only enforcement site for "no bare unconstrained search" (consistency-pass F10, other half owned by 02 in `handoff-03-auth.md`).
- [ ] A `profile:search` query is rejected outright, not truncated, if it would exceed the result cap unconstrained (e.g. a bare wildcard) — enforcement site: this handler's query-validation step, per `handoff-03-auth.md` v3's scope table (consistency-pass F52).
- [ ] Unmapped DAO errors never surface `err.Error()` to the client; only the mapped sentinels' safe messages do — enforcement site: the boundary translation function from `decisions/error-semantics.md`. Authn failures (missing/invalid token) return 401; scope failures and `authorize()` policy denials both return 403 with an identical client body, distinguished only in the audit log (`decisions/error-semantics.md`, consistency-pass F7).
- [ ] `profile:read:any` requests carry a `reason_code` from the closed enum on every call, logged with the audit record.
- [ ] When `api-service` calls `idp-connector` on a caller's behalf, it obtains a `connector:identity-lookup`-scoped token first, using its own `CONNECTOR_CLIENT_ID`/`CONNECTOR_CLIENT_SECRET` credential (`PLANNING.md` config surface) — enforcement site: this handler-side outbound-client code, distinct from S8's idp-connector-side handlers, which only validate that token, not issue or hold this credential.

**Depends on:** S2; **02: Auth scheme and authorization hand-off** (`handoff-03-auth.md` v3, accepted).
**Model/effort:** sonnet, high.
**Type:** Story.
**Labels:** `track-03`, `security-graded`, `no-code-yet`.

---

{
  "command": "grep -n -i \"F-pag\\|cursor\\|offset\\|pagination\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md"
}

3: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`.
45:## Pagination, rate limits, decomposition resistance (requirements — numbers are fixed, mechanism is yours)
47:- **Opaque cursor at the API boundary** (resolves F-pag — the earlier "cursor-based pagination only, no offset-based paging" was wrong to imply offset itself is the enumeration risk: a keyset cursor permits the same page-by-page walk, just statefully; the actual control is the cumulative counter below, and 05's DAO contract is `Offset int`, not keyset). The API-facing cursor may encode the DAO's offset directly — callers cannot construct or walk one by hand, which is the property the boundary exists to give you, and the DAO's offset is never caller-visible. **Enforcement site: the cursor-encoding/decoding step in the handler layer**, opaque to the caller regardless of what it encodes underneath. Default page size 20, hard ceiling 50 (05's DAO ceiling is 10,000 — this API's ceiling is the tighter, caller-facing one; don't expose the DAO's).
49:- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that actually resists decomposition-style enumeration (not the pagination scheme, per the F-pag correction above). **Applies to `profile:read:any` as well as `profile:search`, unconditionally on whether a `reason_code` is present** — a valid, logged `reason_code` satisfies the per-call `authorize()` policy check but does not exempt the caller from this cumulative cap (S8 review fix: the original wording made this counter a no-op for `read:any`, since that scope requires a `reason_code` on every call by design). **Enforcement site: a counting store (Redis, in-process with periodic flush, whatever fits your stack) incremented once per distinct record id returned, checked before the response is sent** — the mechanism is your call; the requirement is that it exists, applies to both scopes, and alerts on threshold, not just hard-blocks.

{
  "command": "grep -n -i \"F6\\b\\|F8\\b\\|F10\\b\\|F52\\b\\|reason_code\\|caller_referral\\|expand\\|fourth\\|4th\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md"
}

3: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`.
31:| `profile:read:own` | Retrieve a single record by id the caller already holds a legitimate reference to (e.g., a partner resolving a referred user) | Search/query by name or phone fragment; retrieval of a record outside the caller's referral relationship | `target.id` checked against the `caller_referral` mapping (see "Where `caller_referral` and the caller-role table live," below); out-of-set → reject, logged as a policy denial, distinct from an auth failure |
32:| `profile:read:any` | Retrieve a single record by id, no referral constraint | Search/query by fragment | Requires a `reason_code` from a closed enum (below) on every request, logged with the audit record |
35:`reason_code` enum for `profile:read:any` (closed, versioned — adding a value is a documented change, not a runtime config toggle): `support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`.
39:**Where `caller_referral` and the caller-role table live (resolves F8 — this data was previously asserted as "owned by `../05-data-ops/`" without 05 ever having received that assignment; 05's schema has no such table and shouldn't grow one for this).** Both live in the token-issuing authorization server's own datastore (the same one that holds the hashed `client_secret`s per `handoff-04-secrets.md` row #4), not in `05-data-ops`'s `user_profile`/`user_credential` schema. This is authorization-provisioning data — who a client credential is allowed to act on behalf of — not subject data, and keeping it out of 05's schema also keeps it out of that schema's PII-governance/retention rules, which don't apply to it. 05 owns nothing here; this hand-off's earlier wording was wrong to say otherwise.
41:**Response shape and masking (resolves F6 — 01's product requirement had no mechanism to bind to).** `profile:search` responses carry masked PII fields by default (e.g., a phone shown as `***-***-1234`, an address reduced to `locality`/`region` only) — unmasked, full-field detail is obtained only by a follow-up call under `profile:read:own` or `profile:read:any` against the specific record id returned by the search, which is its own separately-audited call per the audit-log section below. This uses scopes that already exist rather than inventing a fourth "expand" concept: masking is a `profile:search`-response property, not a per-call flag, and "tighter than search" is satisfied structurally because `read:own`/`read:any` are already narrower-provisioned scopes than `search`.
43:**Reject an empty search body before the DAO (resolves F10, first half).** A `profile:search` request with no `name` or `phone` filter at all is rejected by the handler with a 400 before it ever reaches the DAO — the DAO's own "an all-nil query is legal and returns every profile" behavior (`../05-data-ops/multi-db-strategy.md`) is a DAO-layer property this API must not expose directly. This is a shape-based rejection, distinct from and in addition to the count-based result-cap rejection above.
49:- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that actually resists decomposition-style enumeration (not the pagination scheme, per the F-pag correction above). **Applies to `profile:read:any` as well as `profile:search`, unconditionally on whether a `reason_code` is present** — a valid, logged `reason_code` satisfies the per-call `authorize()` policy check but does not exempt the caller from this cumulative cap (S8 review fix: the original wording made this counter a no-op for `read:any`, since that scope requires a `reason_code` on every call by design). **Enforcement site: a counting store (Redis, in-process with periodic flush, whatever fits your stack) incremented once per distinct record id returned, checked before the response is sent** — the mechanism is your call; the requirement is that it exists, applies to both scopes, and alerts on threshold, not just hard-blocks.
59:- `reason_code`, when the scope is `profile:read:any`

{
  "command": "grep -n -i \"wildcard\\|unconstrained\\|truncat\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md"
}

33:| `profile:search` | Query by name/phone fragment across the table | — (this is the broadest scope; there is no broader one) | Result cap enforced; a query that would exceed it unconstrained (e.g., bare wildcard) is rejected outright, not truncated |
37:**Object-level policy hook implementation shape:** a function `authorize(sub, scope, target) -> allow|deny`, called after scope validation, before the handler executes the query/retrieve. This is a second check, not a replacement for the scope check — a valid `profile:read:own` token can still fail `authorize()` if the target isn't in the caller's referral set. **Confirmed placement (per your reply): an explicit call inside each handler right after parsing the request and before the DAO call, not a second middleware** — correct, since `authorize()` needs the parsed target id, which a pre-routing middleware doesn't have. **Enforcement site for the `profile:search` result cap: the same in-handler call site, checked before the query is built** — a query that would exceed the cap unconstrained is rejected there, not truncated after the DAO returns rows.

{
  "command": "python3 ~/.claude/skills/profile-gen/scripts/show_profile.py --profile /Users/warrenthompson/Source/LoginID/01-product-industry-research-design/profiles/desmond-okafor/desmond-okafor.md --root /Users/warrenthompson/Source/LoginID/01-product-industry-research-design"
}

{"name": "Desmond Okafor", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

{
  "command": "cd /Users/warrenthompson/Source/LoginID && git fetch origin -q; git log origin/main --oneline -15"
}

7ff1e0f Merge PR #25: 05 docs — A6 amendment, §7 verification principle, checklist §G, migration R4a
edccff0 Verification principle (contract §7), and migration immutability (checklist G, R4a)
9bf2a5e LT-32 Done; 02 enforcement-site amendments; LOG
4969b8a Merge PR #24: contract amendment A6 — phone CHECK range parity via migration 00002, SQL-side username folding, two conformance assertions
e61d165 fix: apply A6's phone CHECK narrowing as a real 00002 migration, not an edit to 00001
6a1eae4 Contract A6: write validation sets down; fix two portability defects
463f344 fix: contract amendment A6 — phone CHECK parity, GetByUsername single-source case-fold
f978951 Merge PR #23: CI guard — signing-key Secret may appear only in the issuer Deployment manifest
00eef6c Add CI guard: JWT signing-key Secret must only appear in api-service-issuer's Deployment
f4b586a Merge PR #22: raise namespace limits.cpu quota 2→3 for the issuer Deployment's second replica
7fe9299 Bump ResourceQuota limits.cpu — LT-32's second Deployment exceeded it
ec2b74d Loop iterations 15–18: LT-38 merged, LT-32 deployed, concurrency fix; 02 dated updates; LOG
d890a75 Merge PR #21: LT-32 refinement — forward notes for LT-40 (Nolan)
c371ebf Merge PR #18: LT-32 issuer/verifier split — APP_MODE, issuer Deployment + SA + Service, out-of-band signing key
75ff066 Merge PR #16: LT-38 cross-backend behavioral conformance suite
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

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

1	# LT-40 refinement — S7: auth middleware (JWT validation)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S7 (LT-40); `02-ai-security-architecture/api-auth-design.md`, `handoff-03-auth.md` v3.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now, and at priority
8	
9	This is the critical path per team-lead's direction: LT-39's handlers are code-review-passed but deliberately unwired (exposing them before real auth exists would serve unauthenticated PII), LT-32's issuer split is deployed and live at `/auth/token` (currently a 501 placeholder), and LT-34's live-URL story stays open until something real is reachable through auth. This story is what turns all of that into an actual, reviewable, authenticated public endpoint.
10	
11	## Correction to `backlog.md`'s own story text, found before drafting
12	
13	**S7's acceptance criterion 6 ("per-client-credential rate limits and the cumulative distinct-record-touch counter ... enforcement site: the rate-limit middleware plus its own test") is stale relative to work already merged.** `backlog.md` was written before LT-39 (PR #26) implemented `RateLimiter` and `TouchCounter` as explicit, tested checks called *inside* each handler (via a `Deps` struct), not as separate HTTP middleware — confirmed by reading `internal/api/auth.go`, `handlers.go`, `ratelimit.go`, `touchcounter.go` directly. Both are already built, both are already tested (including the two hard-deny regression tests from LT-39's own refinement), and both are already wired to whatever `AuthContext` the request context carries.
14	
15	**What this means for LT-40's actual scope:** this story does **not** rebuild rate limiting or the touch counter. Its job is narrower and already well-seamed: verify the JWT, populate `AuthContext` (via `WithAuthContext`, already exported by `internal/api`) with the token's `sub` and `scope` claims, and wire the resulting middleware into `cmd/api-service`'s router ahead of the already-built handlers. The 90-day-re-approval/lifecycle-revocation machinery (`api-auth-design.md`) and the issuer-side rate limiting (criterion 5, below) are the only genuinely new rate-limit-shaped work this story adds — the resource-API limits are already done.
16	
17	## Acceptance outcome
18	
19	"Done" for this story specifically is the first fully authenticated, live, reviewable REST endpoint: a real client-credentials token obtained from `/auth/token` (once its actual issuance logic lands — see Non-goals) or, in the interim, a token minted directly against the deployed signing key for review purposes, presented to `/profiles/search` or `/profiles/{id}` at the public URL, producing a masked search response or a 401/403/429 exactly as LT-39's tests predict.
20	
21	## Acceptance criteria (restated from `backlog.md` S7, corrected per the finding above)
22	
23	- [ ] Implements 02's token scheme without re-deriving the no-refresh/no-denylist reasoning in `api-auth-design.md` — no refresh tokens (client re-authenticates on expiry); TTL-only revocation (5–15 min), no denylist, an explicitly accepted trade-off, not to be re-litigated.
24	- [ ] Rejects any token whose `aud` doesn't match this service's audience — enforcement site: the claim-validation step, unit test with a mismatched-audience token.
25	- [ ] Verifies with the public key only; the private signing key never touches this binary's code path — enforcement site: dependency/import check, no signing-key material referenced anywhere in `internal/api` or the verifier's own binary path (this is already structurally true per LT-32's Deployment split; this criterion confirms the *code*, not just the *Deployment*, never imports signing-key material).
26	- [ ] **Pins the expected signing algorithm and rejects any token whose header claims a different one**, including `alg: none` and a symmetric-algorithm downgrade using the public key as an HMAC secret (RFC 8725 §3.1) — enforcement site: an explicit algorithm allowlist check in the JWT verification call, never left to the library's default. Unit tests: a token with `alg: none`, a token HMAC-signed using the public key bytes as the secret, both rejected.
27	- [ ] `kid`-based key rotation: the middleware selects the verification key by the token's `kid` header claim, supporting at least two concurrently valid public keys during a rotation overlap window — enforcement site: a unit test presenting tokens signed under two different `kid`s, both verifying successfully when both keys are configured.
28	- [ ] The middleware populates `internal/api.AuthContext` (via the already-exported `WithAuthContext`) with the token's `sub` and `scope` claims on success, and returns 401 (via LT-39's existing unauthorized-response path, not a new one) on any verification failure — **this is the actual integration seam with S6's work, not new response-shape design.**
29	- [ ] The token-issuing endpoint (`APP_MODE=issuer`, currently the 501 placeholder from LT-32) gets its own failed-grant rate limiting and progressive backoff per `client_id` and per source IP, separate from the resource-API limits (which are already built in `internal/api`) — with alerting on a sustained run of failed grants against one `client_id`. This is genuinely new work, not already covered by LT-39.
30	- [ ] The deadline budget for a request (context propagation into the DAO layer) is sized to cover realistic p99 DAO latency per `decisions/context-propagation.md`'s ruling — stated as a concrete number in this story's implementation, not left as "some deadline."
31	- [ ] The resource-API rate limiter and touch counter already built in LT-39 are wired to real, JWT-derived `AuthContext.Sub` values once this middleware populates them — **no new implementation, an integration check**: a live-URL test with a real token confirms the 60/10 req/min limits and the touch cap actually apply per real client identity, not per a test fake's hardcoded value.
32	
33	## Non-goals
34	
35	- **Real token issuance logic** (actually minting a signed JWT from valid client credentials at `/auth/token`) is explicitly out of scope for this story unless `backlog.md`/02 says otherwise — LT-32 only built the placeholder route and the signing-key custody; this story is the *verifier* side. Flagged as an open question below, since without it there's no way to obtain a real token for the live-URL review other than an out-of-band test token minted directly against the deployed key.
36	- No change to `internal/api`'s handler logic, masking, or error translation — that's LT-39, already merged.
37	- No change to the object-level `authorize()` policy datastore — still a stated seam (`Authorizer` interface), real implementation is a later story per `handoff-03-auth.md` v3's F8 resolution.
38	- No client-credential provisioning UI/API for new callers — out of scope for this take-home entirely, per `01-product-industry-research-design`'s track boundary.
39	
40	## Open question, flagged before hand-off rather than discovered at review time
41	
42	**Is there a real token-issuance implementation planned before or alongside this story, or does the live-URL review use an out-of-band test token?** `backlog.md` doesn't have a separate story for `/auth/token`'s actual grant logic (validate client_id/client_secret, mint a signed JWT) — LT-32 only built the route as a 501 placeholder. If issuance isn't a planned story, the PO review script below needs an out-of-band way to mint a real token against the deployed signing key for review purposes, which is a meaningfully different (and less representative) review than "call `/auth/token` for real." Flagging to Renata/team-lead now rather than discovering it when I try to run the review script.
43	
44	## PO review script
45	
46	1. Confirm the algorithm-allowlist and `kid`-rotation unit tests exist and pass — read the test names and assertions directly, not just "tests pass."
47	2. Confirm `AuthContext` population uses the already-exported `WithAuthContext`/`AuthContext` types from `internal/api`, not a parallel/duplicate type — grep for a second definition of anything auth-context-shaped.
48	3. Confirm the issuer-side rate limiting is a distinct code path from the resource-API rate limiter already in `internal/api/ratelimit.go` — this is genuinely new work, shouldn't reuse or be confused with the existing one.
49	4. Confirm the context-propagation deadline is a concrete, named number in code (e.g. a constant), not an inline magic value scattered across call sites.
50	5. Once deployed and a real (or, per the open question above, out-of-band) token is available: hit `/profiles/search` and `/profiles/{id}` at the live URL, confirming a masked response, a 401 on a missing/expired/wrong-audience token, a 403 on a wrong-scope token, and — if enough calls are made — an actual 429 once the touch cap is crossed. This is the live-URL review LT-34/LT-39 have both been waiting on.
51	
52	## Research team review
53	
54	**Desmond Okafor — claims check:** [pending]
55	
56	**Tobias Lindqvist — objection:** [pending]
57	
58	**Naomi Voss — ruling:** [pending]
59	

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad && rm -rf main-check && gh repo clone wtvamp/loginid-takehome main-check -- -q 2>&1 | tail -20"
}

Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && find . -path ./05-data-ops -prune -o -name \"*.go\" -print | grep -i \"internal/api\" "
}

(Bash completed with no output)

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && find . -name \"*.go\" | sort"
}

./cmd/api-service/main.go
./cmd/idp-connector/main.go
./internal/app/app_test.go
./internal/app/app.go
./internal/app/buildinfo.go
./internal/config/config_test.go
./internal/config/config.go
./internal/dao/conformance_test.go
./internal/dao/conformance/conformance_test.go
./internal/dao/conformance/helpers_test.go
./internal/dao/conformance/testutil_test.go
./internal/dao/errors.go
./internal/dao/factory.go
./internal/dao/normalize.go
./internal/dao/postgres/composite.go
./internal/dao/postgres/credentials.go
./internal/dao/postgres/errors_test.go
./internal/dao/postgres/errors.go
./internal/dao/postgres/integration_test.go
./internal/dao/postgres/like.go
./internal/dao/postgres/methods.go
./internal/dao/postgres/postgres.go
./internal/dao/postgres/profiles.go
./internal/dao/postgres/register.go
./internal/dao/postgres/retry_test.go
./internal/dao/postgres/retry.go
./internal/dao/postgres/testutil_test.go
./internal/dao/query.go
./internal/dao/repository.go
./internal/dao/retention.go
./internal/dao/sqlite/composite.go
./internal/dao/sqlite/credentials.go
./internal/dao/sqlite/errors_test.go
./internal/dao/sqlite/errors.go
./internal/dao/sqlite/integration_test.go
./internal/dao/sqlite/like.go
./internal/dao/sqlite/methods.go
./internal/dao/sqlite/profiles.go
./internal/dao/sqlite/register.go
./internal/dao/sqlite/sqlite.go
./internal/dao/sqlite/testutil_test.go
./internal/dao/validate_id.go
./internal/dao/validate_query.go
./internal/dao/validate_test.go
./internal/dao/validate.go
./internal/model/model.go
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr list --repo wtvamp/loginid-takehome --state all --limit 40 2>&1 | tail -50"
}

26	LT-39: REST handlers for search/retrieve user_profile (S6)	feature/LT-39	OPEN	2026-09-13T04:51:39Z
25	Contract A6: write validation sets down; fix two portability defects	docs/05-a6-validation-parity	MERGED	2026-09-13T04:38:56Z
24	fix: contract amendment A6 — phone CHECK parity, GetByUsername single-source case-fold	fix/LT-A6-phone-username	MERGED	2026-09-13T04:37:22Z
23	Add CI guard: JWT signing-key Secret must only appear in api-service-issuer	fix/ci-secret-mount-guard	MERGED	2026-09-13T04:27:32Z
22	Fix: bump ResourceQuota limits.cpu for LT-32's second Deployment	fix/deploy-resourcequota-headroom	MERGED	2026-09-13T04:25:34Z
21	docs: fold Nolan's PR #18 forward notes into LT-32 refinement	docs/03-refinement-notes	MERGED	2026-09-13T04:13:21Z
20	Fix deploy: build concurrency group must include matrix.service	fix/deploy-concurrency-matrix	MERGED	2026-09-13T04:09:22Z
19	LT-32 infra half: issuer Deployment, RBAC, out-of-band signing-key bootstrap	main	CLOSED	2026-09-13T04:05:14Z
18	LT-32: APP_MODE issuer/verifier split for api-service (Go side)	feature/LT-32	MERGED	2026-09-13T04:02:27Z
17	fix: narrow LT-35 conformance checksum to §1-4's Go code fences only	fix/LT-checksum-narrow	MERGED	2026-09-13T03:56:59Z
16	LT-38: cross-backend behavioral conformance suite	feature/LT-38	MERGED	2026-09-13T03:53:12Z
15	Fix deploy: inject commit SHA into build, and don't cancel a run mid-apply	fix/deploy-inject-commit-sha	MERGED	2026-09-13T03:50:12Z
14	Fix deploy: split Namespace to bootstrap-only, fix distroless runAsUser	fix/deploy-manifest-namespace-runasuser	MERGED	2026-09-13T03:45:07Z
13	Fix deploy.yml: install kubectl on the runner before applying	fix/deploy-kubectl-install	MERGED	2026-09-13T03:41:28Z
12	Fix deploy.yml: runs-on must match ARC scale-set name, not a label list	fix/deploy-runson-scaleset	MERGED	2026-09-13T03:39:02Z
11	LT-45 follow-up: support both PAT and GitHub App auth for runner credential	feature/LT-45	MERGED	2026-09-13T03:07:18Z
10	Contract A3: SQLite FK enforcement site, and pin the tested CockroachDB version	docs/05-a3-fk-enforcement	MERGED	2026-09-13T02:44:44Z
9	fix: errcheck lint failure in app_test.go	fix/errcheck-app-test	MERGED	2026-09-13T02:44:36Z
8	LT-37: SQLite DAO implementation	feature/LT-37	MERGED	2026-09-13T02:38:44Z
7	Data Ops: DDL review checklist, and correct the migration run order	docs/05-ddl-review-and-migration-order	MERGED	2026-09-13T02:37:21Z
6	LT-36: Postgres/CockroachDB DAO implementation	feature/LT-36	MERGED	2026-09-13T02:31:40Z
5	LT-45: Multi-stage Dockerfiles for both services	feature/LT-45	MERGED	2026-09-13T02:27:51Z
4	LT-47: PR-check CI workflow	feature/LT-47	MERGED	2026-09-13T02:27:35Z
3	fix: refresh LT-35 conformance checksum after contract amendments	fix/LT-35-checksum	MERGED	2026-09-13T02:26:48Z
2	LT-35: DAO interface, domain types, sentinels, factory	feature/LT-35	MERGED	2026-09-12T23:40:16Z
1	LT-34: walking skeleton (Go module, two binaries, health endpoint)	feature/LT-34	MERGED	2026-09-12T23:30:33Z
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr view 26 --repo wtvamp/loginid-takehome --json files,title,state 2>&1 | python3 -m json.tool | head -60"
}

{
    "files": [
        {
            "path": "internal/api/auth.go",
            "additions": 103,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/cursor.go",
            "additions": 49,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/cursor_test.go",
            "additions": 60,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/errors.go",
            "additions": 98,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/fakes_test.go",
            "additions": 112,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/handlers.go",
            "additions": 260,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/handlers_test.go",
            "additions": 319,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/masking.go",
            "additions": 79,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/masking_test.go",
            "additions": 25,
            "deletions": 0,
            "changeType": "ADDED"
        },
        {
            "path": "internal/api/ratelimit.go",
            "additions": 62,
            "deletions": 0,
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr view 26 --repo wtvamp/loginid-takehome --json files 2>&1 | python3 -c \"\nimport json,sys\nd = json.load(sys.stdin)\nfor f in d['files']:\n    print(f['path'])\n\""
}

internal/api/auth.go
internal/api/cursor.go
internal/api/cursor_test.go
internal/api/errors.go
internal/api/fakes_test.go
internal/api/handlers.go
internal/api/handlers_test.go
internal/api/masking.go
internal/api/masking_test.go
internal/api/ratelimit.go
internal/api/ratelimit_test.go
internal/api/touchcounter.go
internal/api/touchcounter_test.go
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr diff 26 --repo wtvamp/loginid-takehome 2>&1 > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr26.diff; wc -l /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr26.diff"
}

    1481 /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr26.diff
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad && awk '/diff --git a\\/internal\\/api\\/auth\\.go/,/diff --git a\\/internal\\/api\\/cursor\\.go/' pr26.diff | head -140"
}

diff --git a/internal/api/auth.go b/internal/api/auth.go
new file mode 100644
index 0000000..349ef97
--- /dev/null
+++ b/internal/api/auth.go
@@ -0,0 +1,103 @@
+// Package api implements the Q2 REST handlers (search/retrieve
+// user_profile) per 02-ai-security-architecture/handoff-03-auth.md v3 and
+// 03-engineering-delivery/refinement/LT-39.md. This story's own non-goals
+// (LT-39, S6) exclude the JWT verification middleware itself — that's S7
+// (LT-40), a separate pull — so every handler here reads its auth context
+// from the request's context.Context, populated by whatever put it there.
+// Until S7 lands, that's this package's own tests using fakes, per
+// decisions/test-double-strategy.md; once S7 lands, it's S7's middleware.
+// These handlers are not yet wired into cmd/api-service's live router —
+// doing so before S7 exists would expose unauthenticated PII, which is
+// exactly the outcome the whole auth design exists to prevent.
+package api
+
+import "context"
+
+// Scope is the token's authorized action, from handoff-03-auth.md v3's
+// closed vocabulary (§ "Scope vocabulary"). A typed string rather than a
+// bare one so a handler comparing scopes can't typo past the compiler on
+// a scope it never validates against a literal.
+type Scope string
+
+const (
+	// ScopeReadOwn retrieves a single record by id the caller already
+	// holds a legitimate reference to; authorize() checks the target
+	// against the caller_referral mapping.
+	ScopeReadOwn Scope = "profile:read:own"
+	// ScopeReadAny retrieves a single record by id with no referral
+	// constraint, but requires a ReasonCode on every request and is
+	// still subject to the cumulative touch cap.
+	ScopeReadAny Scope = "profile:read:any"
+	// ScopeSearch queries by name/phone fragment across the table. The
+	// broadest scope; there is no broader one.
+	ScopeSearch Scope = "profile:search"
+)
+
+// AuthContext is what a validated request carries once past S7's
+// middleware (or, until S7 exists, whatever a test injects directly via
+// WithAuthContext). Sub is the calling client identity (the token's `sub`
+// claim); Scope is the single scope this request is being made under —
+// handoff-03-auth.md v3 doesn't describe multi-scope tokens being
+// disambiguated per-request, so one request carries exactly one Scope.
+type AuthContext struct {
+	Sub   string
+	Scope Scope
+}
+
+type authContextKey struct{}
+
+// WithAuthContext attaches ac to ctx. The seam S7's middleware (or a
+// test) uses to populate the auth context every handler in this package
+// reads.
+func WithAuthContext(ctx context.Context, ac AuthContext) context.Context {
+	return context.WithValue(ctx, authContextKey{}, ac)
+}
+
+// AuthContextFromContext retrieves the AuthContext WithAuthContext
+// attached, ok=false if none was ever set (e.g. this package's handlers
+// were reached without going through auth middleware — a caller bug, not
+// a request the handler should try to interpret).
+func AuthContextFromContext(ctx context.Context) (AuthContext, bool) {
+	ac, ok := ctx.Value(authContextKey{}).(AuthContext)
+	return ac, ok
+}
+
+// ReasonCode is the closed enum profile:read:any requires on every
+// request (handoff-03-auth.md v3). Adding a value is a documented change
+// to this list, not a runtime config toggle.
+type ReasonCode string
+
+const (
+	ReasonSupportTicket     ReasonCode = "support_ticket"
+	ReasonFraudReview       ReasonCode = "fraud_review"
+	ReasonKYCReverification ReasonCode = "kyc_reverification"
+	ReasonLegalHold         ReasonCode = "legal_hold"
+)
+
+// Valid reports whether r is one of the four closed enum values.
+func (r ReasonCode) Valid() bool {
+	switch r {
+	case ReasonSupportTicket, ReasonFraudReview, ReasonKYCReverification, ReasonLegalHold:
+		return true
+	default:
+		return false
+	}
+}
+
+// Authorizer is the object-level policy hook (handoff-03-auth.md v3):
+// "a function authorize(sub, scope, target) -> allow|deny, called after
+// scope validation, before the handler executes the query/retrieve."
+// caller_referral and the caller-role table live in the token-issuing
+// authorization server's own datastore (v3's F8 resolution) — not
+// 05-data-ops's schema, and not built by this story. This interface is
+// the seam: real implementation is a follow-up story against that
+// datastore; this package's tests use a hand-written fake per
+// decisions/test-double-strategy.md.
+type Authorizer interface {
+	// Authorize reports whether sub may act under scope against target
+	// (a record id for ScopeReadOwn/ScopeReadAny; ignored for
+	// ScopeSearch, which has no single target). A false, nil return is
+	// an ordinary policy denial, not an error — errors are reserved for
+	// the datastore itself being unreachable.
+	Authorize(ctx context.Context, sub string, scope Scope, target string) (bool, error)
+}
diff --git a/internal/api/cursor.go b/internal/api/cursor.go
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad && awk '/diff --git a\\/internal\\/api\\/ratelimit\\.go/,/diff --git a\\/internal\\/api\\/ratelimit_test\\.go/' pr26.diff | head -100"
}

diff --git a/internal/api/ratelimit.go b/internal/api/ratelimit.go
new file mode 100644
index 0000000..6e1db7a
--- /dev/null
+++ b/internal/api/ratelimit.go
@@ -0,0 +1,62 @@
+package api
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// RateLimiter enforces handoff-03-auth.md v3's per-client-credential
+// rate limits (60 req/min for read:own/read:any, 10 req/min for
+// profile:search), keyed per sub+scope. The mechanism is this track's
+// call (v3, explicitly) — an interface so handler tests use a fake
+// instead of real wall-clock behavior.
+type RateLimiter interface {
+	// Allow reports whether sub may make one more request under scope
+	// right now, given limit requests per rolling minute.
+	Allow(ctx context.Context, sub string, scope Scope, limit int) (bool, error)
+}
+
+// InProcessRateLimiter is a fixed-window (per-wall-clock-minute) limiter,
+// in-process rather than Redis-backed — the simplest mechanism satisfying
+// v3's "the mechanism is your call" framing, sufficient for this
+// take-home's single-instance deployment. A fixed window (vs. sliding) can
+// admit up to 2x limit across a window boundary; accepted here as a
+// deliberate simplification, not hidden — a production multi-instance
+// deployment would need a shared store (Redis) instead.
+type InProcessRateLimiter struct {
+	mu      sync.Mutex
+	buckets map[string]*bucket
+	now     func() time.Time
+}
+
+type bucket struct {
+	windowStart time.Time
+	count       int
+}
+
+// NewInProcessRateLimiter constructs a ready-to-use limiter.
+func NewInProcessRateLimiter() *InProcessRateLimiter {
+	return &InProcessRateLimiter{
+		buckets: make(map[string]*bucket),
+		now:     time.Now,
+	}
+}
+
+func (r *InProcessRateLimiter) Allow(_ context.Context, sub string, scope Scope, limit int) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	key := sub + "|" + string(scope)
+	now := r.now()
+	b, ok := r.buckets[key]
+	if !ok || now.Sub(b.windowStart) >= time.Minute {
+		b = &bucket{windowStart: now, count: 0}
+		r.buckets[key] = b
+	}
+	if b.count >= limit {
+		return false, nil
+	}
+	b.count++
+	return true, nil
+}
diff --git a/internal/api/ratelimit_test.go b/internal/api/ratelimit_test.go
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad && awk '/diff --git a\\/internal\\/api\\/handlers\\.go/,/diff --git a\\/internal\\/api\\/handlers_test\\.go/' pr26.diff | head -160"
}

diff --git a/internal/api/handlers.go b/internal/api/handlers.go
new file mode 100644
index 0000000..b094e4f
--- /dev/null
+++ b/internal/api/handlers.go
@@ -0,0 +1,260 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"loginid-takehome/internal/dao"
+)
+
+// Deps bundles a handler's collaborators — the DAO, the object-level
+// policy hook, and the two independent limiters — so NewSearchHandler/
+// NewGetProfileHandler take one argument instead of four, and a test
+// fake for any one of them doesn't require constructing the other three
+// by hand each time.
+type Deps struct {
+	Repo         dao.Repository
+	Authz        Authorizer
+	RateLimiter  RateLimiter
+	TouchCounter TouchCounter
+}
+
+const (
+	defaultPageSize = 20
+	maxPageSize     = 50
+	readRateLimit   = 60 // req/min, read:own and read:any
+	searchRateLimit = 10 // req/min, profile:search
+)
+
+type searchRequest struct {
+	Name     *string `json:"name,omitempty"`
+	Phone    *string `json:"phone,omitempty"`
+	Region   *string `json:"region,omitempty"`
+	Country  *string `json:"country,omitempty"`
+	Cursor   string  `json:"cursor,omitempty"`
+	PageSize int     `json:"page_size,omitempty"`
+}
+
+type searchResponse struct {
+	Results    []SearchResultProfile `json:"results"`
+	Total      int                   `json:"total"`
+	NextCursor string                `json:"next_cursor,omitempty"`
+}
+
+// NewSearchHandler implements profile:search (handoff-03-auth.md v3).
+// Order of checks, deliberately: auth context present -> scope is
+// ScopeSearch -> per-minute rate limit -> cumulative touch cap -> request
+// shape (empty body, bare-wildcard-shaped unconstrained query) ->
+// authorize() -> the DAO call -> record touches -> masked response. Scope
+// mismatch and an authorize() denial return an identical body (F7); only
+// the audit log (not built by this story — see refinement/LT-39.md's
+// non-goals) would distinguish them.
+func NewSearchHandler(d Deps) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		ctx := r.Context()
+		ac, ok := AuthContextFromContext(ctx)
+		if !ok {
+			writeUnauthorized(w)
+			return
+		}
+		if ac.Scope != ScopeSearch {
+			writeForbidden(w)
+			return
+		}
+
+		allow, err := d.RateLimiter.Allow(ctx, ac.Sub, ScopeSearch, searchRateLimit)
+		if err != nil {
+			writeDAOError(w, err)
+			return
+		}
+		if !allow {
+			writeRateLimited(w)
+			return
+		}
+
+		capOK, err := d.TouchCounter.Allowed(ctx, ac.Sub)
+		if err != nil {
+			writeDAOError(w, err)
+			return
+		}
+		if !capOK {
+			writeTouchCapExceeded(w)
+			return
+		}
+
+		var req searchRequest
+		if r.Body != nil {
+			if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+				writeBadRequest(w, "malformed request body")
+				return
+			}
+		}
+
+		// A search request with no filter field at all is rejected here
+		// with a 400 before it ever reaches the DAO — the DAO's own
+		// all-nil ProfileQuery is legal and returns every profile, which
+		// this API must not expose directly (handoff-03-auth.md v3, F10).
+		if req.Name == nil && req.Phone == nil && req.Region == nil && req.Country == nil {
+			writeBadRequest(w, "at least one search filter is required")
+			return
+		}
+
+		offset, err := decodeCursor(req.Cursor)
+		if err != nil {
+			writeBadRequest(w, "malformed cursor")
+			return
+		}
+
+		pageSize := req.PageSize
+		if pageSize <= 0 {
+			pageSize = defaultPageSize
+		}
+		if pageSize > maxPageSize {
+			// A bare/unconstrained request for more than this API's
+			// result cap is rejected outright, not truncated
+			// (handoff-03-auth.md v3) — checked here, before the query
+			// is built, mirroring the same rule for authorize() below.
+			writeBadRequest(w, "page_size exceeds the maximum of 50")
+			return
+		}
+
+		// The object-level policy hook, per v3: called after scope
+		// validation (above) and request-shape validation (above), before
+		// the DAO call. ScopeSearch has no single target id.
+		allowed, err := d.Authz.Authorize(ctx, ac.Sub, ac.Scope, "")
+		if err != nil {
+			writeDAOError(w, err)
+			return
+		}
+		if !allowed {
+			writeForbidden(w)
+			return
+		}
+
+		q := dao.ProfileQuery{
+			Name:    req.Name,
+			Phone:   req.Phone,
+			Region:  req.Region,
+			Country: req.Country,
+			Limit:   pageSize,
+			Offset:  offset,
+		}
+		results, total, err := d.Repo.Profiles().Search(ctx, q)
+		if err != nil {
+			writeDAOError(w, err)
+			return
+		}
+
+		ids := make([]string, len(results))
+		masked := make([]SearchResultProfile, len(results))
+		for i, p := range results {
+			ids[i] = p.ID
+			masked[i] = toSearchResult(p)
+		}
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr view 26 --repo wtvamp/loginid-takehome --json state,mergedAt,baseRefName,headRefName 2>&1"
}

{"baseRefName":"main","headRefName":"feature/LT-39","mergedAt":null,"state":"OPEN"}
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "grep -n -i \"alg\\|kid\\|rotation\\|none\\b\\|RFC 8725\\|HMAC\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md | head -30"
}

27:- **Algorithm confusion at the verifier — S8 review addition (Tomasz Wrede).** The verifier must pin the expected signing algorithm (RS256 or ES256, whichever this deployment chose) and reject any token whose header claims a different algorithm — specifically `alg: none` and an attacker-supplied downgrade to a symmetric algorithm (e.g., HS256 with the public key used as the HMAC secret, the well-documented RS256→HS256 confusion class). This is boilerplate for a correctly-configured JWT library, but it is exactly the kind of thing a security-graded design document should state explicitly rather than assume the library gets right by default — several real-world JWT libraries have shipped this vulnerability.
75:- **Token-endpoint brute-force protection — S8 review addition (Tomasz Wrede).** Every rate limit above protects the resource API *after* a token is issued; none of them protect the token endpoint itself, where a caller presents `client_id`/`client_secret` to obtain one. Require: failed-grant rate limiting and progressive backoff per `client_id` and per source IP, and alerting on a sustained run of failed grants against one `client_id` — the same discipline `threat-model.md` Asset 1 applies to password brute-force, applied here to the client-credentials grant, which had no equivalent control stated. Client-secret entropy and storage are `04-infra-devops`'s and this document's own hashing requirement respectively; the token endpoint's own request-level defense is this document's gap to close.
88:Four findings, ranked; all accepted. **1 (high, fixed above):** the decomposition counter's exemption clause was unconditionally satisfied for `profile:read:any` because that scope already requires a `reason_code` on every call — a no-op control for the scope with the broadest blast radius. **2 (medium, fixed above):** no stated defense against JWT algorithm confusion at the verifier. **3 (medium-high, fixed above):** no brute-force/lockout protection on the client-credentials token endpoint itself, only on the resource API after a token issues. **4 (minor, fixed above):** this API's bearer-token replay risk was silently assumed safe rather than named as an accepted risk, unlike the connector's identical property in `connector-security.md`. Tomasz had no prior involvement with this document (his Phase 2 work was the connector, not the search API), so this review is independent per `PLAN.md` S8.
94:- RFC 8725 (JSON Web Token Best Current Practices, §3.1 algorithm confusion / `alg: none`): https://datatracker.ietf.org/doc/html/rfc8725#section-3.1

{
  "command": "grep -n -i \"deadline\\|p99\\|context-propagation\\|budget\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/decisions/context-propagation.md | head -20"
}

14:2. **Deadline budget, not a boolean.** Unbroken propagation means an inherited, already-partially-consumed deadline reaches the DAO call. If upstream work (e.g., a connector call) already burned most of the HTTP handler's timeout, the DAO gets a shrinking remainder and starts timing out under *normal* latency, not just failure — the good case starts looking like the bad case.
22:2. Deadline propagation is a budget-allocation decision, stated explicitly in S3's middleware design: the HTTP-boundary timeout must be sized to cover realistic p99 DAO latency *plus* any upstream work (e.g., no DAO call should ever be handed a near-zero remaining deadline as a matter of routine operation). This gets a concrete number attached when S3's middleware design is written, not left as "some deadline."
27:Ruled. Carries into S2 (Repository implementation contract: transaction scoping, detach points) and S3 (middleware deadline budget).

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

1	# Decision: Context propagation into the DAO layer
2	
3	Pattern: rotating devil's advocate, decision 2 of 3 (seat: Nolan Reyes). Proposer: Renata Cole.
4	
5	## Proposal
6	
7	Every `Repository` method (and its three sub-interfaces — `Profiles`/`Credentials`/`Methods`) takes `context.Context` as its first argument, propagated unbroken from the HTTP request through the handler into every DB call, so request cancellation/timeout actually cancels in-flight queries.
8	
9	## Objections — Nolan Reyes (Veteran)
10	
11	Agreed with the direction but pushed on three failure modes from production experience:
12	
13	1. **Cancellation racing a multi-statement write.** A cancelled `SELECT` aborts cleanly; a cancelled multi-statement write (e.g., profile + credential saved together) risks a half-written row unless cancellation is scoped to a transaction, not a statement. Cited a migration job killed mid-batch by a deploy SIGTERM, leaving orphaned rows because cancellation was handled per-statement.
14	2. **Deadline budget, not a boolean.** Unbroken propagation means an inherited, already-partially-consumed deadline reaches the DAO call. If upstream work (e.g., a connector call) already burned most of the HTTP handler's timeout, the DAO gets a shrinking remainder and starts timing out under *normal* latency, not just failure — the good case starts looking like the bad case.
15	3. **Sub-interfaces are not uniformly cancel-safe.** Credential writes during auth are exactly the path that caused a real incident: a retry re-issued a credential write against an already-expired derived context and silently no-op'd instead of erroring. Wants explicit naming of which write paths deliberately detach from the inbound context (via `context.WithoutCancel` or a fresh background context) for durability, distinct from read paths that don't need it.
16	
17	## Ruling (Renata Cole)
18	
19	All three accepted; no decline.
20	
21	1. Any `Repository` method that writes to more than one table (e.g., a profile+credential save) runs inside a single `Tx`. Context cancellation during that transaction triggers `Tx.Rollback`, never a partial commit — this is a stated requirement on the `Repository` implementation contract, not left to each backend's discretion.
22	2. Deadline propagation is a budget-allocation decision, stated explicitly in S3's middleware design: the HTTP-boundary timeout must be sized to cover realistic p99 DAO latency *plus* any upstream work (e.g., no DAO call should ever be handed a near-zero remaining deadline as a matter of routine operation). This gets a concrete number attached when S3's middleware design is written, not left as "some deadline."
23	3. Credential writes are named explicitly as the path that needs a detach point for durability, distinct from profile reads and other cancel-safe paths, which propagate the inbound context unmodified. This distinction is documented at the point each such method is implemented, not left implicit.
24	
25	## Status
26	
27	Ruled. Carries into S2 (Repository implementation contract: transaction scoping, detach points) and S3 (middleware deadline budget).
28	
29	## Resolved against 05's contract (2026-09-12)
30	
31	Oren's first-pass review of 05's DAO contract flagged a real tension: this ruling's item 1 requires any multi-table write to run in a single `Tx`, but the contract as first landed had no method spanning both `user_profile` and `user_credential`, and explicitly barred 03 from composing a cross-call transaction — leaving registration's profile+credential creation with no atomic path at all. 05 resolved it by adding `CreateProfileWithCredential(ctx, p, c)` on the `Repository` composite (05's §3b) — the one cross-table operation in the contract, DAO-generated IDs for both rows, single transaction, `c.UserID` ignored on input and set from the just-created profile. This ruling's item 1 now has exactly one caller-visible method satisfying it, rather than being a requirement with no concrete instance.
32	
33	## Consistency-pass fixes (2026-09-12)
34	
35	**F19 — a real contradiction with 05's contract, not just stale wording.** 05's `multi-db-strategy.md` states "`Context` is first on every method and cancellation is honoured" — a blanket guarantee. Item 3 above, as originally written, said credential writes detach via `context.WithoutCancel` *inside the DAO*, which would mean the DAO does not honor cancellation on those specific methods — directly contradicting 05's guarantee. Fixed: **the detach happens in the handler, before the DAO call, not inside the DAO.** The handler passes the DAO a fresh, independently-bounded context for a credential write (not derived from the inbound request's cancellation tree, but with its own timeout) — from the DAO's perspective, cancellation of the context it was given is still honored unconditionally, exactly as 05's contract states. The DAO layer's guarantee is never weakened; the detach decision is a handler-layer policy about *which* context to hand the DAO, not an exception the DAO carves out for itself.
36	
37	**F17 — stale references to a token cache dropped.** Item 3 originally also named "any token-persistence write" as a detach point, left over from before 02's S3 ruling settled on no-cache-by-default for the connector's vendor tokens (`decisions/connector-token-lifecycle-redblue.md`). There is no token-persistence write in the current design, so the phrase is removed (done above) rather than left to describe a mechanism that no longer exists.
38	
39	---
40	Model: sonnet (Nolan Reyes, objection seat; Renata Cole, lead, proposer + ruling). Turns consumed: 1 hire turn + lead synthesis.
41	

{
  "command": "grep -n -i \"90.day\\|re-approval\\|lifecycle\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md"
}

21:## Token shape and lifecycle
65:### Grant lifecycle
67:- **90-day re-approval** on every scope grant (not `profile:search` alone) is a backstop, not the only mechanism. Grants are revoked immediately, ahead of the 90-day cycle, on: the named approver's offboarding, the caller's stated business function changing, or an idle trigger (no usage for 30 days → revoke pending re-justification) — whichever comes first. This requires 03/04 to consume an offboarding or ownership-change signal; the requirement (lifecycle-triggered revocation, not solely calendar-triggered) is asserted here, the plumbing is theirs.
84:Full record: `decisions/search-authz-scoping.md`. Ingrid Solano's five numbered objections against Helena Marsh's initial proposal, all accepted and revised into the sections above: (1) `read:any` was shaped before its actual callers were enumerated — fixed by requiring a caller-role table entry, gated like `search`; (2) `read:any`'s `reason_code` was freeform — fixed with a closed, versioned enum; (3) `caller_referral` membership had no owner or approval process, the softest control gating the narrowest scope — fixed by routing it through the same partner-onboarding workflow as any other grant; (4) per-request rejection and per-minute rate limits don't stop decomposition (slow enumeration under the cap) — fixed with a cumulative distinct-record-touch counter per rolling window; (5) 90-day re-approval is calendar-only, not lifecycle-tied — fixed with immediate revocation on offboarding, function change, or a 30-day idle trigger, with the 90-day cycle as backstop only.
98:- NIST SP 800-63B (identity/authorization lifecycle, offboarding-triggered revocation) — cited in `decisions/search-authz-scoping.md`

{
  "command": "cd /Users/warrenthompson/Source/LoginID && git fetch origin -q; gh pr view 26 --repo wtvamp/loginid-takehome --json state,mergedAt 2>&1; echo ---; ls 02-ai-security-architecture/handoff-03-auth.md; grep -n \"^Status:\" 02-ai-security-architecture/handoff-03-auth.md"
}

{"mergedAt":null,"state":"OPEN"}
---
02-ai-security-architecture/handoff-03-auth.md
3:Status: **v4** — adds the token-issuance grant logic (below), a gap Naomi Voss found during LT-40 refinement: v3 specified verification and scopes in full but never specified `/auth/token`'s actual grant handling, and LT-32 shipped that endpoint as a `501` placeholder with no issuance story behind it. Everything from v3 is unchanged. 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`.
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

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

1	# LT-40 refinement — S7: auth middleware (JWT validation)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S7 (LT-40); `02-ai-security-architecture/api-auth-design.md`, `handoff-03-auth.md` v3.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now, and at priority
8	
9	This is the critical path per team-lead's direction: LT-39's handlers are code-review-passed but deliberately unwired (exposing them before real auth exists would serve unauthenticated PII), LT-32's issuer split is deployed and live at `/auth/token` (currently a 501 placeholder), and LT-34's live-URL story stays open until something real is reachable through auth. This story is what turns all of that into an actual, reviewable, authenticated public endpoint.
10	
11	## Correction to `backlog.md`'s own story text, found before drafting
12	
13	**S7's acceptance criterion 6 ("per-client-credential rate limits and the cumulative distinct-record-touch counter ... enforcement site: the rate-limit middleware plus its own test") is stale relative to work already merged.** `backlog.md` was written before LT-39 (PR #26) implemented `RateLimiter` and `TouchCounter` as explicit, tested checks called *inside* each handler (via a `Deps` struct), not as separate HTTP middleware — confirmed by reading `internal/api/auth.go`, `handlers.go`, `ratelimit.go`, `touchcounter.go` directly. Both are already built, both are already tested (including the two hard-deny regression tests from LT-39's own refinement), and both are already wired to whatever `AuthContext` the request context carries.
14	
15	**What this means for LT-40's actual scope:** this story does **not** rebuild rate limiting or the touch counter. Its job is narrower and already well-seamed: verify the JWT, populate `AuthContext` (via `WithAuthContext`, already exported by `internal/api`) with the token's `sub` and `scope` claims, and wire the resulting middleware into `cmd/api-service`'s router ahead of the already-built handlers. The 90-day-re-approval/lifecycle-revocation machinery (`api-auth-design.md`) and the issuer-side rate limiting (criterion 5, below) are the only genuinely new rate-limit-shaped work this story adds — the resource-API limits are already done.
16	
17	## Acceptance outcome
18	
19	"Done" for this story is a working, tested JWT-verification middleware wired into `cmd/api-service`'s router, with LT-39's handlers reachable through it at the live URL. **Corrected per team-lead, per Marcus's actual design:** nothing ever signs with the deployed private key outside the issuer process — there is no "out-of-band token minted directly against the signing key" path, review or otherwise; the private key's only caller is `/auth/token`'s own real grant logic (LT-51). **LT-40 merges and deploys to In Test on its own** (middleware + wiring, verified by unit tests here), **but its live-URL review happens together with LT-51's**, using a real token obtained from `/auth/token` via a dedicated, narrowly-scoped QA client credential seeded in the client store (LT-51's own criteria). LT-40 and LT-51 go Done together, in one PO pass, with a genuinely issued token — not LT-40 alone on a workaround token.
20	
21	## Acceptance criteria (restated from `backlog.md` S7, corrected per the finding above)
22	
23	- [ ] Implements 02's token scheme without re-deriving the no-refresh/no-denylist reasoning in `api-auth-design.md` — no refresh tokens (client re-authenticates on expiry); TTL-only revocation (5–15 min), no denylist, an explicitly accepted trade-off, not to be re-litigated.
24	- [ ] Rejects any token whose `aud` doesn't match this service's audience — enforcement site: the claim-validation step, unit test with a mismatched-audience token.
25	- [ ] Verifies with the public key only; the private signing key never touches this binary's code path — enforcement site: dependency/import check, no signing-key material referenced anywhere in `internal/api` or the verifier's own binary path (this is already structurally true per LT-32's Deployment split; this criterion confirms the *code*, not just the *Deployment*, never imports signing-key material).
26	- [ ] **Pins the expected signing algorithm and rejects any token whose header claims a different one**, including `alg: none` and a symmetric-algorithm downgrade using the public key as an HMAC secret (RFC 8725 §3.1) — enforcement site: an explicit algorithm allowlist check in the JWT verification call, never left to the library's default. Unit tests: a token with `alg: none`, a token HMAC-signed using the public key bytes as the secret, both rejected.
27	- [ ] `kid`-based key rotation: the middleware selects the verification key by the token's `kid` header claim, supporting at least two concurrently valid public keys during a rotation overlap window — enforcement site: a unit test presenting tokens signed under two different `kid`s, both verifying successfully when both keys are configured.
28	- [ ] The middleware populates `internal/api.AuthContext` (via the already-exported `WithAuthContext`) with the token's `sub` and `scope` claims on success, and returns 401 (via LT-39's existing unauthorized-response path, not a new one) on any verification failure — **this is the actual integration seam with S6's work, not new response-shape design.**
29	- [ ] The token-issuing endpoint (`APP_MODE=issuer`, currently the 501 placeholder from LT-32) gets its own failed-grant rate limiting and progressive backoff per `client_id` and per source IP, separate from the resource-API limits (which are already built in `internal/api`) — with alerting on a sustained run of failed grants against one `client_id`. This is genuinely new work, not already covered by LT-39.
30	- [ ] The deadline budget for a request (context propagation into the DAO layer) is sized to cover realistic p99 DAO latency per `decisions/context-propagation.md`'s ruling — stated as a concrete number in this story's implementation, not left as "some deadline."
31	- [ ] The resource-API rate limiter and touch counter already built in LT-39 are wired to real, JWT-derived `AuthContext.Sub` values once this middleware populates them — **no new implementation, an integration check**: a live-URL test with a real token confirms the 60/10 req/min limits and the touch cap actually apply per real client identity, not per a test fake's hardcoded value.
32	
33	## Non-goals
34	
35	- **Real token issuance logic** (actually minting a signed JWT from valid client credentials at `/auth/token`) is explicitly out of scope for this story unless `backlog.md`/02 says otherwise — LT-32 only built the placeholder route and the signing-key custody; this story is the *verifier* side. Flagged as an open question below, since without it there's no way to obtain a real token for the live-URL review other than an out-of-band test token minted directly against the deployed key.
36	- No change to `internal/api`'s handler logic, masking, or error translation — that's LT-39, already merged.
37	- No change to the object-level `authorize()` policy datastore — still a stated seam (`Authorizer` interface), real implementation is a later story per `handoff-03-auth.md` v3's F8 resolution.
38	- No client-credential provisioning UI/API for new callers — out of scope for this take-home entirely, per `01-product-industry-research-design`'s track boundary.
39	
40	## Open question — resolved
41	
42	**Original question:** `backlog.md` had no story for `/auth/token`'s actual grant logic (validate client_id/client_secret, mint a signed JWT) — LT-32 only built the route as a 501 placeholder, and nothing downstream picked up the real logic. Tobias's objection sharpened this from "a gap this refinement can flag and work around" to "a missing story, not a pending one" — unlike LT-36/37's wait on LT-38, or LT-32's wait on LT-34, this had no ticket and no scheduled end, and treating an out-of-band token as this story's own review method risked quietly weakening "done = deployed and reviewable at a public URL" into "done = reviewable by an engineer with cluster access," without anyone deciding that on purpose.
43	
44	**Resolution (team-lead):** confirmed as a real gap and a new story, not scope creep and not "out of scope forever." **LT-51** (Epic LT-3, security-graded, linked LT-40 → blocks → LT-51) — OAuth2 client-credentials grant at `/auth/token`, per Marcus's `handoff-03-auth.md` v4 addendum (now landed): HTTP Basic client auth, form-encoded `client_credentials` grant per RFC 6749 §4.4, §5.1/§5.2 token/error responses with an identical `invalid_client` for unknown-client vs. wrong-secret (no oracle distinguishing the two), client store in the issuer's own datastore with Argon2id-hashed secrets, a `jti` claim recommended for audit correlation only (not a revocation mechanism — TTL-only revocation stands per `api-auth-design.md`), and the public key distributed via a JWKS endpoint served by the issuer's in-cluster `ClusterIP` `Service` — no public `Ingress` route for it, since only the verifying middleware inside the cluster needs it. 03-owned code, 02-supplied spec. Refined right after this story.
45	
46	**Corrected ruling on the review token, replacing the earlier "out-of-band" framing:** there is no path where the private key signs anything outside the issuer process, not even for review. LT-40's live-URL review therefore happens *together with* LT-51's, using a real token obtained from a real `/auth/token` call, authenticated with a dedicated, narrowly-scoped QA client credential seeded specifically for this purpose (LT-51's own criteria, below) — not a workaround token and not a separate acceptance event.
47	
48	## PO review script
49	
50	1. Confirm the algorithm-allowlist and `kid`-rotation unit tests exist and pass — read the test names and assertions directly, not just "tests pass."
51	2. Confirm `AuthContext` population uses the already-exported `WithAuthContext`/`AuthContext` types from `internal/api`, not a parallel/duplicate type — grep for a second definition of anything auth-context-shaped.
52	3. Confirm the issuer-side rate limiting is a distinct code path from the resource-API rate limiter already in `internal/api/ratelimit.go` — this is genuinely new work, shouldn't reuse or be confused with the existing one.
53	4. Confirm the context-propagation deadline is a concrete, named number in code (e.g. a constant), not an inline magic value scattered across call sites.
54	5. **Run jointly with LT-51's review, once both are deployed:** obtain a real token from `/auth/token` using the seeded QA client credential (LT-51's criteria), then hit `/profiles/search` and `/profiles/{id}` at the live URL, confirming a masked response, a 401 on a missing/expired/wrong-audience token, a 403 on a wrong-scope token, and — if enough calls are made — an actual 429 once the touch cap is crossed. This is the live-URL review LT-34/LT-39/LT-40 have all been waiting on; LT-40 and LT-51 go Done together in this one pass, not separately.
55	
56	## Research team review
57	
58	**Desmond Okafor — claims check:** [pending]
59	
60	**Tobias Lindqvist — objection:** [pending]
61	
62	**Naomi Voss — ruling:** [pending]
63	

{
  "command": "grep -n -i \"token-issuance\\|/auth/token\\|RFC 6749\\|invalid_client\\|jti\\|JWKS\\|ClusterIP\\|Argon2id\\|basic auth\\|client_credentials\\|4\\.4\\|5\\.1\\|5\\.2\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md"
}

3:Status: **v4** — adds the token-issuance grant logic (below), a gap Naomi Voss found during LT-40 refinement: v3 specified verification and scopes in full but never specified `/auth/token`'s actual grant handling, and LT-32 shipped that endpoint as a `501` placeholder with no issuance story behind it. Everything from v3 is unchanged. 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`.
5:## Token issuance (`POST /auth/token`) — v4 addendum
9:**Client authentication:** HTTP Basic (`client_id`:`client_secret` in the `Authorization` header) — not client credentials in the body. Keeps the secret out of any place that logs request bodies more casually than it logs headers, and is RFC 6749 §2.3.1's preferred client-authentication method.
11:**Request:** `grant_type=client_credentials`, form-encoded (`application/x-www-form-urlencoded`, per RFC 6749 §4.4 — not JSON; this is the one endpoint in this API that follows the OAuth2 spec's own wire format rather than this project's usual JSON convention, because it's the one endpoint implementing a named OAuth2 grant). Optional `scope` parameter (space-delimited) to request a subset of the client's granted scopes; if omitted, issue the client's full granted scope set.
13:**Response, success (200):** `{"access_token": "...", "token_type": "Bearer", "expires_in": <seconds, 300–900>, "scope": "..."}` — the granted (or requested-and-granted) scopes, space-delimited, per RFC 6749 §5.1.
15:**Response, errors (RFC 6749 §5.2, never distinguishing *why* in body or status):** `invalid_client` (401, `WWW-Authenticate: Basic`) for any client-authentication failure — unknown `client_id` and wrong `client_secret` get the **identical** response, same user-enumeration discipline already required elsewhere in this document; `invalid_scope` (400) if the requested scope isn't a subset of the client's granted scopes; `unsupported_grant_type` (400) for anything but `client_credentials`. Token-endpoint brute-force protection (rate limit + backoff per `client_id`/IP, already specified above) applies here, at this exact endpoint.
17:**Client store — issuer's own datastore** (per F8/row #4 of `handoff-04-secrets.md`, not 05's schema): `client_id`, `name` (accountability, per S4's provisioning bar — no shared credentials across a team), `client_secret_hash` (**Argon2id, same floor as `threat-model.md` Asset 1** — identical hashing discipline to password storage, not a separate algorithm choice to justify), `granted_scopes` (the provisioned subset of `profile:read:own`/`profile:read:any`/`profile:search`/`connector:identity-lookup`, per each scope's provisioning bar in `api-auth-design.md`), `status` (active/revoked), `created_at`, `revoked_at`. Rotation: single active secret per client is sufficient at this scale (unlike the signing key, this isn't live-traffic-critical enough to need overlap) — reissue generates a new secret and immediately invalidates the old one; no dual-secret rotation window needed.
19:**JWT claims issued:** `iss` = `https://auth.loginid-takehome.internal`; `aud` = `loginid-api-service` or `idp-connector-service` depending on which audience the authenticated client is registered for (a client is provisioned for one audience, not both); `sub` = `client_id`; `scope` = the granted-or-requested set, space-delimited; `exp`/`iat` per the 5–15 min TTL already specified; header `kid` identifying the signing key version. **`jti` (recommended, not required):** a random per-token identifier, included solely as an audit-log correlation aid (so a token's issuance and its later use can be joined in logs) — it is never checked against a denylist at verification time, since this design already ruled out stateful revocation in favor of short TTLs; including it costs nothing statefully and is worth the correlation value.
21:**Public-key distribution for the verifier (enforcement site, your call was open, ruled here): JWKS served by the issuer Deployment, reachable only in-cluster via its own `ClusterIP` Service — no Ingress route, never publicly reachable.** Not a mounted public-key file: JWKS survives key rotation without redeploying the verifying Deployment's config, since the verifier fetches by `kid` and only needs to know the issuer Service's in-cluster DNS name (`<issuer-service>.<namespace>.svc.cluster.local`), not track individual key files. In-cluster-only because this token scheme's only consumers are `api-service` and `idp-connector`, both already inside the cluster network; there's no reason to add a new publicly-reachable route on a shared production cluster (`threat-model.md` Assumption 7) for a key set that only internal services ever need. Verifier caches the fetched key set in memory with a short TTL (matching token TTL is reasonable) to avoid a JWKS fetch on every single verification.
23:**Ruling on LT-40's URL review token (Warren, via the PM's provisional yes — objecting to the literal framing, not the goal):** review tooling must **never** mint a token by signing directly with the deployed private key — that would hand review/QA tooling the same access this design has spent real effort restricting to the issuer process alone (F13, the whole point of the Deployment split), for a purely operational convenience. The correct equivalent: provision a **dedicated, narrowly-scoped review/QA client credential** (its own row in the client store above, its own `client_id`, scoped to the minimum needed for the review — `profile:read:own` unless the review specifically needs to exercise `profile:search`, in which case it goes through `profile:search`'s own provisioning bar like any other caller) and have the review process call the **real** `/auth/token` endpoint with it. This costs nothing extra to set up, never touches key material outside the issuer process, and is a better test besides — it exercises the actual issuance path instead of bypassing it. If "out-of-band" meant this all along (a scripted call to the real endpoint, not raw signing), then there's no disagreement and this section just makes the mechanism explicit for whoever provisions the review credential.
40:- **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.
93:- **Password/client-secret hashing** — Argon2id, decided in `threat-model.md` Asset 1; not this hand-off's concern beyond noting it exists.

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/refinement/postgres-in-namespace.md"
}

1	# New story refinement — deploy real Postgres in `loginid-takehome`, wire migrations, DB_DSN_FILE
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Theo Bergman (04, owner); Priya Nandakumar (05, reviewer). **Source:** gap found during LT-40 refinement — none of `04-infra-devops/backlog.md`'s existing stories (LT-45/46/47/48/49/LT-20) actually deploy a running database instance; they all assume a DB target already exists. **Jira key:** pending team-lead creating it under Epic LT-4.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering owner Theo Bergman; reviewer Priya Nandakumar.
6	
7	## Why this one, now
8	
9	LT-39's handlers are code-review-passed but there's nothing behind the DAO in the live cluster — no database, no applied schema, no seed data. This is the last missing piece before LT-34/LT-39/LT-40/LT-51's joint live-URL review can exercise a real search/retrieve call against real (if empty) data, not just an auth-and-routing check.
10	
11	## What this story is
12	
13	A single-replica PostgreSQL `StatefulSet` in the `loginid-takehome` namespace (Theo's call, confirmed: a managed instance would be disproportionate infra/cost for this take-home's scale; a single `StatefulSet` + `PersistentVolumeClaim` is the standard minimal shape and matches this project's existing "small, isolated, no HA beyond what's needed" pattern), a DB credential `Secret` provisioned out-of-band (same discipline as LT-32's JWT signing key — never through the CI-applied manifest set), a migration `Job` that runs goose against it in the correct two-invocation order before `api-service`'s rollout, and `DB_DSN_FILE` wired into `api-service`'s config so it actually connects to this database instead of erroring on an unset DSN.
14	
15	**Explicit scope limit, stated up front:** CockroachDB is exercised in CI only (LT-47's testcontainer job, against the shared `postgres`-package code path) and is **not** deployed anywhere in this cluster. Only PostgreSQL runs live. This is a deliberate scope limit for a take-home demo, not an oversight — stated here so a reviewer doesn't reasonably expect to find CockroachDB running somewhere and conclude something's missing.
16	
17	## Acceptance criteria
18	
19	- [ ] A single-replica PostgreSQL `StatefulSet` (with a `PersistentVolumeClaim` for data persistence across pod restarts) runs in `loginid-takehome`. Enforcement site: the `StatefulSet` manifest and its `Service`.
20	- [ ] The DB credential (connection string / password) is provisioned out-of-band, never through the CI-applied manifest set — matching the pattern `deploy/issuer-secret-bootstrap.yaml` already established for the JWT signing key. Enforcement site: the credential `Secret` is absent from `deploy/manifests.yaml`; a bootstrap doc/script analogous to `issuer-secret-bootstrap.yaml` documents how it's created.
21	- [ ] Per `05-data-ops/migration-approach.md` R4, the migration-runner credential (DDL rights, plus `CREATE EXTENSION pg_trgm` on Postgres specifically) and the runtime service credential (DML-only, no DDL) are two distinct `Secret`s, never one — matching LT-46's own criterion for this same split, applied here against a database that now actually exists.
22	- [ ] The migration `Job` runs goose in the **correct, corrected order**: the backend directory (`postgres/`, containing the actual `CREATE TABLE` DDL) **first**, then `shared/` (seed data only, currently just the `auth_method` "password" row) **second** — per `migration-approach.md`'s own corrected ordering (the original text had this inverted, caught reading the seed and DDL together, not caught by a green test suite that happened to apply files in a different working order). Enforcement site: the `Job`'s invocation script/command, explicitly two `goose` invocations in this order, each against its own version table (`goose_db_version_postgres`, `goose_db_version_shared`) per R4's two-independent-sequences requirement.
23	- [ ] Both goose invocations must succeed for the migration `Job` to count as successful — a partial success (backend DDL applied, `shared/` seed failed, or vice versa) is a failed `Job`, not a partial pass. Enforcement site: the `Job`'s script exits non-zero if either invocation fails.
24	- [ ] The migration `Job` runs to completion **before** `api-service`'s rollout — enforcement site: deploy pipeline ordering (readiness gate or explicit sequencing in the merge-to-main workflow), not an assumption that Kubernetes scheduling happens to land in the right order.
25	- [ ] `DB_DSN_FILE` (already a config surface `internal/config` supports per `PLANNING.md`'s Service boundaries) is wired to point at the runtime service credential's mounted file — `api-service` connects successfully on startup instead of erroring on an unset/placeholder DSN. Enforcement site: `api-service`'s Deployment manifest, mounting the runtime credential and setting `DB_DSN_FILE` to its path; a startup log line or health-check state confirming a live DB connection (not just that the env var is set).
26	- [ ] `deploy/manifests.yaml`'s header comment (which currently states "no migration Job, no DB_DSN secret — those wire up config the current code doesn't use yet") is updated to reflect that this is no longer true, so a future reader isn't misled by a stale comment.
27	- [ ] **`ResourceQuota` headroom confirmed for the new StatefulSet pod before merge** — added per Theo's own flag, given the earlier `api-service-issuer` `FailedCreate` incident from under-sized quota. Enforcement site: the quota math is shown in the PR description (current `limits.cpu`/`limits.memory` vs. the new total including Postgres's request/limit), and the `ResourceQuota` object is adjusted in the same PR if needed — not discovered as a second `FailedCreate` after merge.
28	
29	## Non-goals
30	
31	- No CockroachDB deployment — CI-only, per the explicit scope limit above.
32	- No backup/restore, replication, or HA for Postgres — single replica, single PVC, take-home scale; `migration-approach.md` explicitly leaves backup schedule/retention as 04's call and out of this document's scope, and this story doesn't add it either.
33	- No connection pooling (e.g., PgBouncer) — direct connections from `api-service` are sufficient at this scale; flag if load testing ever suggests otherwise.
34	- No change to the migration file contents themselves (DDL, seed data) — that's 05's `migration-approach.md` and the actual `.sql` files, already written; this story only runs them.
35	
36	## PO review script
37	
38	1. Confirm the `StatefulSet` and its `PersistentVolumeClaim` exist in the manifest, targeting `loginid-takehome`.
39	2. Confirm the DB credential `Secret` is absent from `deploy/manifests.yaml` and documented as provisioned out-of-band, matching the JWT-signing-key pattern.
40	3. Confirm two distinct `Secret`s exist for the migration-runner vs. runtime credentials, with different RBAC scoping (DDL-capable vs. DML-only).
41	4. Read the migration `Job`'s script directly: confirm two `goose` invocations, backend directory first, `shared/` second, each with its own `-table` flag, and that the script fails if either invocation fails.
42	5. Confirm the deploy pipeline sequences the migration `Job` to completion before `api-service`'s rollout — not merely "applied at some point."
43	6. Once deployed: confirm `api-service` actually connects (a startup log line or health-check field, not just an unset-DSN error going away), and run a real `profile:search`/`profile:read:own` call through the live URL (joint with LT-40/LT-51's review) confirming it reaches real Postgres and returns a real (even if empty) result set — this is the actual proof this story exists to provide.
44	7. Confirm the quota math was shown and the `ResourceQuota` adjusted if needed, before merge — not discovered as a `FailedCreate` after.
45	
46	## Research team review
47	
48	**Desmond Okafor — claims check:** [pending]
49	
50	**Tobias Lindqvist — objection:** [pending]
51	
52	**Naomi Voss — ruling:** [pending]
53	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/05-data-ops/migration-approach.md"
}

1	# Migration Approach
2	
3	Owner: 05-data-ops (Priya Nandakumar). **Primary receiver: `../04-infra-devops/`** — this is one of the three inputs that track is gated on. Secondary receiver: `../03-engineering-delivery/`, which owns the migration files themselves alongside the DAO code.
4	
5	Written to the project's hand-off standard: 04 should be able to act on this without re-deriving my reasoning. Where I state a *requirement*, the mechanism is 04's to choose; where I state a *mechanism*, it is because the requirement cannot be met without it, and I say why.
6	
7	Status: **final.** The devil's-advocate objection turn (story S4 in `./PLAN.md`) ran and raised six objections; all six were accepted. The two I named as most worth attacking — the tool choice and the single-runner requirement — were indeed where it landed: R2's *conclusion* survived but its *reasoning* was wrong and has been replaced, and R3 was found to be checking one version number where §2 creates two. Dispositions: `./decisions/migration-approach-objections.md`.
8	
9	## 1. Tool: goose
10	
11	**goose** — a Go command-line migration runner that applies numbered `.sql` files in order and records which have been applied in a version table inside the target database. Plain-SQL-first, minimal dependencies. Reasoning is in `./multi-db-strategy.md` and `./research-data-ops-best-practices.md` §3: this schema is "mostly shared DDL, occasionally per-backend", and goose's loose directory model fits that better than golang-migrate's stricter paired up/down files. golang-migrate is an equally defensible tool and I will not contest a swap if 03 already has tooling preferences — **nothing in §3–§6 below changes if the tool changes — with one named exception**: §2's two-invocation mechanism uses goose's `-table` flag, so a swap to golang-migrate means re-deriving how two independent version sequences are kept apart. That is the tool-independence claim's only load-bearing use, and pretending otherwise would be the kind of small overclaim this document is otherwise trying to avoid. Atlas is the schema-as-state alternative worth knowing about; it is more than this take-home needs.
12	
13	Version numbering: timestamped filenames during development (avoids collisions when two branches add a migration), converted to a clean sequential 001/002/003 series with `goose fix` — the subcommand that renumbers timestamped files — **before the migrations have been applied anywhere that persists.** That cutoff is the important half: renumbering after application rewrites history the version table already records, so `goose fix` is a pre-first-application step, not a tidy-up before tagging. Not a decision 04 needs to act on — noted so nobody "fixes" the inconsistency later.
14	
15	## 2. Layout
16	
17	```
18	migrations/
19	  shared/       # seed data only — no CREATE TABLE
20	  postgres/     # all DDL for PostgreSQL, incl. COLLATE "C" and the trigram index
21	  cockroachdb/  # all DDL for CockroachDB — no COLLATE clause; trigram index native
22	  sqlite/       # all DDL for SQLite, COLLATE BINARY, no trigram index
23	```
24	
25	**Split three ways as of amendment A5 (2026-09-13), one directory per driver string.** It was previously two, with `postgres/` serving both PostgreSQL and CockroachDB. That could not express the byte-order collation requirement: **`COLLATE "C"` is invalid syntax on CockroachDB** (`42601`) — it takes ICU locale tags, not PostgreSQL's `C`/`POSIX` pseudo-locales — while PostgreSQL needs the clause explicitly because its own default collation is locale-dependent. CockroachDB's uncollated `TEXT` comparison already *is* byte order, so it needs the clause **absent**, and no single portable clause satisfies both. Established empirically by 03 against live CockroachDB v23.2.0; it had blocked the CockroachDB conformance run outright, since the migration would not apply.
26	
27	The alternative — drop the clause from the DDL and provision the PostgreSQL database with `LOCALE 'C'` at creation — was rejected: it moves the guarantee off the schema and into a provisioning step, where it is invisible at review, unenforced by anything the repository contains, and fails silently on any database created without it. **The enforcement site belongs in the artifact that declares the guarantee.**
28	
29	**This does not change the Go package split.** `internal/dao/postgres` still serves both engines: query construction and dialect *are* shared, and the divergences are the retry seam (keyed off the driver string) and now DDL collation. `DB_DRIVER` already had three distinct values, so `migrations/<driver>` follows from the mechanism below without changing it.
30	
31	**Corrected after the cross-track consistency pass (F28).** This section previously put every `CREATE TABLE` in `shared/`, with `postgres/` holding one index file. That was wrong, and wrong in a way the rest of this track's own work had already ruled out: the field-level schema in `multi-db-strategy.md` §5 gives **every** table per-engine DDL — `UUID DEFAULT gen_random_uuid()` vs `TEXT`, `TEXT COLLATE "C"` vs `TEXT COLLATE BINARY`, a regex `CHECK` vs a `GLOB` `CHECK`, `TIMESTAMPTZ` vs `TEXT`, `BYTEA` vs `BLOB`, `BOOLEAN` vs `INTEGER`. A single shared `CREATE TABLE` series cannot express that. SQLite's type affinity would quietly swallow the differing *type names*, which is what made the original claim look survivable, but it does nothing for collation clauses or CHECK syntax — those are hard syntax differences, not affinity.
32	
33	The document already carried the right answer as a hypothetical fallback ("per-backend `CREATE TABLE` files and `shared/` reduced to seed data") and left it contingent on an open item marked "under review in story S1". **S1 closed, the review resolved it in favour of the fallback, and this document was not updated** — so a document marked "final" was carrying a provisional default that its own dependency had already overruled. That is the failure, and it is worse than the layout error: the fallback was correct, written down, and left unpromoted.
34	
35	So:
36	
37	- **`shared/`** carries the `auth_method` seed row and nothing else. No `CREATE TABLE`.
38	- **`postgres/`** and **`cockroachdb/`** each carry the full DDL for `auth_method`, `user_profile`, `user_credential` and `deletion_log`, plus the trigram expression index on `LOWER(name)`. They differ in exactly one respect today — `postgres/` declares `COLLATE "C"` on `user_profile.name`, `cockroachdb/` declares no collate clause. **Every constraint name is identical across all three directories**, which is what keeps them diffable and what makes cross-backend sentinel translation possible.
39	
40	  **Tested CockroachDB version: `cockroachdb/cockroach:v23.2.0`.** On that version `CREATE EXTENSION IF NOT EXISTS pg_trgm` succeeds and `CREATE INDEX … USING GIN (LOWER(name) gin_trgm_ops)` creates a genuine inverted index, confirmed via `SHOW CREATE TABLE`. CockroachDB gained trigram/inverted-index support around v22.2, so v22.2 is the floor; **anything below it is untested and expected to fail.** Verified by 03 against a live container, not inferred — see the withdrawal note below.
41	
42	  > *Finding withdrawn, 2026-09-12.* During review of PR #6 I raised that `CREATE EXTENSION IF NOT EXISTS pg_trgm` would not work on CockroachDB and should be gated or split. **That was wrong, and it was an overreach from my own research rather than a claim my research supported.** R4 below says "CockroachDB needs nothing here; trigram indexes are native" — a statement about *privileges*, not about whether the statement executes. I turned "needs nothing" into "will fail". 03 tested it against a live v23.2.0 and both statements succeed. Tested behaviour on a version we target beats a docs-derived inference, and I could name no version we would deploy where it fails. The concern that produced it was sound — the CockroachDB path had never been executed, only claimed — and the right resolution was the test, which now exists and is pinned above.
43	- **`sqlite/`** carries the same four tables in SQLite types and collations, and no trigram index — there is no SQLite equivalent and it is omitted rather than faked.
44	
45	**Nothing in §3–§6 changes, and neither does 04's design**, exactly as the earlier text promised: the two-invocation mechanism, the separate version tables, R1–R5 and the seed-data rule are untouched. R3's worked example still holds and in fact reads better now — a service can have `shared/` current with the `pg_trgm` index unapplied, which is why fail-closed must check both version tables. (`pg_trgm` is a PostgreSQL extension that indexes three-character fragments of text so that substring searches like `LIKE '%smith%'` can use an index instead of scanning every row — it is what makes name search fast. CockroachDB has the same capability built in; SQLite has no equivalent, so the index is omitted there rather than faked.). That parity gap is documented and deliberate (`./multi-db-strategy.md`); SQLite is the local/dev/demo backend, not a production peer.
46	
47	**Mechanism 04 needs:** goose applies one directory per invocation, so a migration run is **two invocations — the backend directory FIRST, then `shared/`** — and each needs its own version table (`goose -table goose_db_version_<driver>`, then `-table goose_db_version_shared`). One shared table across two directories would interleave version numbers from independent sequences and corrupt the history. Both invocations must succeed for the run to count as successful.
48	
49	> **Order corrected 2026-09-12 — it was inverted, and would have failed on a clean database.** This section originally said `shared/` then the backend directory. That was correct when `shared/` held the `CREATE TABLE`s. **Finding F28 moved all DDL into the per-backend directories and left `shared/` holding only the `auth_method` seed row — which inverted the dependency, and I did not revisit this sentence.** Running `shared/` first now means `INSERT INTO auth_method …` against a table that does not yet exist.
50	>
51	> Caught during review of LT-36's migration files, by reading the seed and the DDL together; it is invisible in either file alone and did not surface in 03's integration run, which applied the files in a working order rather than the documented one. **A green test suite is not evidence that the documented procedure works** — it is evidence that *some* procedure works.
52	>
53	> Fourth instance in this track of the same failure: a document updated and a dependent statement inside it left pointing at the old state (after the stale `S4` reference, F28 itself, and the §3c summary). Unlike the first three this one is not a restatement, so seam 13 would not have caught it — it is an *ordering consequence* of a change, which no grep finds. Recorded as the limit of that check rather than an argument against it.
54	>
55	> *Corrected by Priya Nandakumar (05 Data Ops lead); surfaced by Renata Cole's LT-36 migration files.*
56	
57	**That open item is now closed.** It asked whether a single `shared/` DDL series survives all three backends, given that SQLite does not enforce column types the way PostgreSQL does — it assigns each column a loose "type affinity" and falls back to NUMERIC for any type name it does not recognise, `UUID` included. The answer turned out to be no, and for a reason narrower than type affinity: affinity would have absorbed the type names, but collation clauses and CHECK syntax differ outright. Resolved in favour of the per-backend split above. No open items remain in this document.
58	
59	## 3. Requirements on 04 — the part I actually need decided
60	
61	**R1. Migrations run as a separate step that completes before any service replica starts.** Not on service boot. Two replicas booting together would both attempt to migrate, and see R2 for why the database will not save you from that. A dedicated job/init step that must exit zero before the service rolls.
62	
63	**R2. Exactly one migration runner at a time, enforced by the platform — not by the database.** This is the requirement I most want 04 to read carefully, because the obvious mechanism does not work here. An *advisory lock* is a named lock an application asks the database to hold on its behalf; the database enforces nothing about what it protects, so it is purely a convention between cooperating clients — the usual way to stop two copies of a job running at once. `pg_advisory_lock` is the standard answer on PostgreSQL, but on CockroachDB **session-scoped advisory locks error out, and the `pg_try_advisory_lock` variants silently no-op** — a try-lock returns as though it succeeded and lets a second runner proceed (sourced in `./research-cockroachdb-postgres-semantics.md` §5; only transaction-scoped `pg_advisory_xact_lock` works there). On SQLite the concept is meaningless. A silent false success is a worse failure than an error. **The reason this argument originally gave was wrong, and is replaced.** The first version reasoned "a locking strategy that only works on one backend is not a strategy." That was true of a premise since corrected: `pg_advisory_xact_lock` *does* work on CockroachDB, and SQLite is a single-file local backend where concurrent migration runners are not a scenario that exists — so a transaction-scoped lock works on both backends that can actually have replicas. An objection turn caught that I had over-rotated one research finding into a platform requirement.
64	
65	**The conclusion survives on a different and better reason: a transaction-scoped lock cannot cover a migration run.** `pg_advisory_xact_lock` is released when its transaction ends, and goose applies each migration file in its own transaction. The lock would therefore be released *between files*, letting a second runner interleave mid-run — which is precisely the failure it was supposed to prevent. Session-scoped locks, which would span the whole run, are the ones CockroachDB does not support. So the database can offer either the right scope or the right engine coverage, never both.
66	
67	So mutual exclusion has to come from the orchestration layer — a job with parallelism 1, a pipeline stage that cannot run concurrently with itself, whatever 04's platform offers. **This is a genuinely open question handed to 04, not a resolved item written up for information.** If 04 concludes the platform cannot guarantee single-runner execution, tell me and I will treat it as a real constraint on the design rather than a detail.
68	
69	**A cheap portable backstop worth adding regardless — and an honest gap.** goose's version table is the one artifact all three backends share, so a unique constraint on its `version_id` would make a second concurrent runner fail on insert: portable, free, no platform feature required. **Whether goose's default version table already carries that constraint is unverified here** — I am not asserting it either way, because the objection that raised this correctly pointed out that the document claimed the database could not help without examining the one database-level mechanism goose already creates. The actionable form does not depend on the answer: **add a unique index on `version_id` ourselves in the first migration**, which is portable across all three backends and costs nothing if goose already does it. This is a backstop, not a replacement for R2 — it turns a silent interleave into a loud failure, which is the property actually worth buying.
70	
71	**R3. The service fails closed when the schema is behind — checking BOTH version tables.** §2 creates two independent version sequences (`shared/` and the backend directory), so "the applied version" is two numbers, not one. The check must compare both, and must know which backend directory applies to the engine it is connected to. Checking only `shared/` would let a service pass with the `pg_trgm` index unapplied — caught by an objection turn, and it would have been a passing check that proved nothing. On startup the service compares both applied versions against the versions it was built against and refuses to serve if either is behind, rather than serving traffic against a schema missing a column it will query. The requirement is mine; whether the expected version is embedded at build time or derived from the migration files shipped in the image is 03's and 04's call.
72	
73	**R4. Two distinct database credentials, not one.**
74	- *Migration runner*: DDL rights (`CREATE`/`ALTER`/`DROP`, index creation) plus, on PostgreSQL only, whatever `CREATE EXTENSION pg_trgm` requires — on managed Postgres this is usually an allow-listed extension, otherwise it needs elevated privileges or the platform pre-installing it. CockroachDB needs nothing here; trigram indexes are native. SQLite has no privilege model at all.
75	- *Runtime service user*: DML only (`SELECT`/`INSERT`/`UPDATE`/`DELETE`). **No DDL.** A running service has no legitimate reason to alter the schema, and a service account that can `DROP TABLE user_profile` turns a SQL-injection finding into data destruction rather than data disclosure.
76	
77	Both credentials belong on 02's secrets inventory; I am flagging the requirement, not claiming that surface.
78	
79	**R4a. Applied migrations are immutable, and constraint changes need care on CockroachDB.** A correction to an already-applied migration is a **no-op** — goose does not re-run an applied version, so the live database keeps the old definition while the file looks correct. Corrections ship as a new numbered migration in every affected directory. Two consequences for the pipeline: verification must apply the *previous* state and migrate forward rather than building a fresh schema (a fresh build passes for an edited migration, which is how this hides), and **CockroachDB rejects a same-transaction `DROP` + `ADD` of a same-named constraint**, so those migrations carry `-- +goose NO TRANSACTION`. Established against live CockroachDB v23.2.0.
80	
81	**R5. Rollback is not the recovery plan for data.** Down migrations will exist for the base schema and are genuinely useful in development. They are not a recovery mechanism in production: reversing a migration that dropped a column does not bring the data back, and the data in question here is PII. Recovery from a destructive migration is backup-restore, and backup policy is 04's. I raise it because "we have down migrations" reads like a safety net and is not one.
82	
83	## 4. Seed data
84	
85	The `auth_method` table is seeded with one row, `"password"`. It ships as a migration file in `shared/`, not as a runtime bootstrap in the service — a service that writes its own lookup rows on boot is a service that can write them wrongly, concurrently, on every replica.
86	
87	Idempotent via `INSERT ... ON CONFLICT (name) DO NOTHING`, which the unique constraint on `auth_method.name` already supports and which all three backends accept (the same portable upsert form the DAO uses — see `./multi-db-strategy.md`). goose will not re-run an applied migration anyway; the `ON CONFLICT` makes the file safe against a database someone seeded by hand, which in practice is how this breaks.
88	
89	New auth methods after `"password"` — `passkey`, `otp`, `oidc` — are **inserted as data, not added as migrations**. That is the entire point of the lookup-table design over a native enum: adding a supported method is an operational action, not a schema change and not a deploy. If 04 finds itself asked to write a migration to add an auth method, that is a signal something has been misunderstood upstream — flag it to me.
90	
91	## 5. Explicitly not owned by this document
92	
93	Named so 04 does not read a boundary into this doc that isn't there: where the databases actually run; how the pipeline invokes goose; environment topology and how many of them there are; backup schedule and retention of backups; connection pooling; monitoring of migration runs. All 04's. This document says *what must 
… truncated (20 KB cap)

{
  "command": "grep -n -B2 -A 15 \"LT-46\" /Users/warrenthompson/Source/LoginID/04-infra-devops/backlog.md | head -40"
}

26-**Labels:** `track-04`, `no-code-yet`.
27-
28:## Story 2 — Deliver secrets to both services per 02's inventory (LT-46)
29-
30-**Description:** Implement the Kubernetes-native `Secret` delivery mechanism in `./secrets-delivery.md`: file-mounted secrets keyed by name only in manifests, RBAC scoped per-service (and, for the JWT signing key, scoped to the issuing code path specifically, not `api-service`'s verification path), cluster-level encryption-at-rest for the `Secret` resource type, and the migration-runner credential's backend-specific provisioning (`CREATE EXTENSION pg_trgm` rights on PostgreSQL only, nothing extra on CockroachDB, no privilege model on SQLite) kept distinct from the runtime service credential (DML-only, no DDL, per 05's R4).
31-
32-**Acceptance criteria:**
33-- [ ] 02 (the hand-off's author) confirms this implementation matches `handoff-04-secrets.md` v2's inventory without needing to re-explain any row.
34-- [ ] No `Secret` value appears in a manifest, image layer, build arg, or CI log — enforcement site: manifests reference names only; CI's `gitleaks` stage (Story 3).
35-- [ ] No ServiceAccount can `get`/`list` a `Secret` it doesn't mount — enforcement site: per-service `Role`/`RoleBinding` scoped to named `Secret`s.
36-- [ ] The migration-runner credential and the runtime service credential are provisioned as two distinct `Secret`s, never one — enforcement site: separate `Secret` objects, separate `Role`s, per 05's R4.
37-- [ ] `Secret` resources are encrypted at rest in etcd — enforcement site: cluster `EncryptionConfiguration`.
38-
39-**Depends on:** 02 — `handoff-04-secrets.md` (received, v2, final); 05 — `migration-approach.md` R4 (final).
40-
41-**Model/effort:** Sonnet, medium.
42-
43-**Type:** Story.

{
  "command": "cd /Users/warrenthompson/Source/LoginID && git fetch origin -q; grep -n \"^Status:\" 02-ai-security-architecture/handoff-03-auth.md\necho ---\ngh pr view 30 --repo wtvamp/loginid-takehome --json state,mergedAt,title 2>&1"
}

3:Status: **v6** — fixes the JWKS path/URL and cache/refresh guidance (below), ruled so LT-51 implements to this doc rather than the doc following PR #30's already-shipped code. v5's Authorizer stand-in and cumulative-cap answers are unchanged. 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`.
---
{"mergedAt":null,"state":"OPEN","title":"LT-40: JWT verification middleware, live router wiring"}
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

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

1	# LT-51 refinement — real `/auth/token` grant logic
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S7a (LT-51); `02-ai-security-architecture/handoff-03-auth.md` v6 (final on JWKS path/cache guidance; v3/v4/v5 content otherwise unchanged).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now
8	
9	PR #30 (LT-40) has already built the verifier side and the `GrantLimiter` component this story wires to — the only thing standing between the current deployment and a genuinely issued, end-to-end token is this story's actual grant logic. Once it lands, LT-34/LT-39/LT-40/LT-51 all get their joint live-URL review with a real token, per team-lead's ruling.
10	
11	## What's already built, and what this story actually adds
12	
13	**Do not rebuild these — wire to them:**
14	- `internal/api.GrantLimiter` (PR #30) — the failed-grant rate-limiting/backoff interface, keyed independently by `client_id` and source IP, with alerting on a sustained run against one `client_id`. This story constructs a real implementation instance (or reuses `InProcessGrantLimiter`) and calls `Allow`/`RecordFailure`/`RecordSuccess` around the actual grant attempt — it does not design a new backoff scheme.
15	- The JWKS endpoint (`internal/api/jwks.go` serves the client side; the issuer side serving `/.well-known/jwks.json` is this story's job, but the *shape* — RFC 7517, `kid`-keyed — is already established by what the verifier expects).
16	- `internal/api.AuthContext`/`WithAuthContext` (LT-39) and the JWT verification middleware (LT-40) — this story's only integration point with them is producing tokens whose claims those already-built and already-tested pieces correctly parse; it doesn't touch either.
17	
18	**What's genuinely new:** the `POST /auth/token` handler itself — client authentication, the client store, JWT minting, and serving JWKS at the now-fixed path.
19	
20	## Acceptance criteria (from `backlog.md` S7a, current per `handoff-03-auth.md` v6)
21	
22	- [ ] `POST /auth/token` implements RFC 6749 §4.4: `grant_type=client_credentials`, form-encoded (`application/x-www-form-urlencoded`), **not JSON** — the one endpoint in this API that follows OAuth2's own wire format rather than this project's usual JSON convention, because it's the one endpoint implementing a named OAuth2 grant. An optional `scope` parameter (space-delimited) requests a subset of the client's granted scopes; omitted means issue the full granted set.
23	- [ ] Client authentication is **HTTP Basic** (`client_id`:`client_secret` in the `Authorization` header), **not** credentials in the body — keeps the secret out of anywhere that logs request bodies more casually than headers, per RFC 6749 §2.3.1's preferred method.
24	- [ ] Errors follow RFC 6749 §5.2, **never distinguishing why in body or status**: `invalid_client` (401, `WWW-Authenticate: Basic`) for **any** client-authentication failure — an unknown `client_id` and a wrong secret for a known `client_id` return byte-identical responses. `invalid_scope` (400) if the requested scope isn't a subset of the client's granted scopes. `unsupported_grant_type` (400) for anything but `client_credentials`. Enforcement site: a test comparing the unknown-client and wrong-secret response bodies for equality, not just "both 401."
25	- [ ] Client store lives in the issuer's own datastore (per F8, not 05's schema): `client_id`, `name` (accountability — no shared credentials across a team), `client_secret_hash` (**Argon2id, same floor as `threat-model.md` Asset 1** — identical hashing discipline to password storage), `granted_scopes` (provisioned subset of `profile:read:own`/`profile:read:any`/`profile:search`/`connector:identity-lookup`), `status` (active/revoked), `created_at`, `revoked_at`. Rotation: single active secret per client (reissue generates a new one and immediately invalidates the old — no dual-secret overlap window, unlike the signing key).
26	- [ ] The token-endpoint's own brute-force protection wires to the **already-built** `GrantLimiter` (PR #30) — `Allow` checked before attempting client authentication, `RecordFailure`/`RecordSuccess` called after, keyed by both `client_id` and source IP. Enforcement site: an integration test confirming a sustained run of failed grants against one `client_id` eventually blocks further attempts and fires the alert exactly once per threshold-crossing (not once per subsequent failure) — this is `GrantLimiter`'s own tested behavior, so this test only needs to confirm the wiring, not re-test the limiter's internals.
27	- [ ] Issued JWT claims (`iss`, `aud`, `scope`, `exp`, `sub`) and the algorithm/`kid` header match exactly what LT-40's verifier middleware expects — enforcement site: an integration test that mints a token here and verifies it through the **actual** middleware from PR #30, not two independently-trusted unit tests that never touch each other.
28	- [ ] **JWKS served at the now-fixed path `/.well-known/jwks.json`** (the OIDC-discovery convention, ruled 2026-09-13 specifically so this story implements to the doc rather than the doc following already-shipped code), issuer-mode only (`APP_MODE=issuer`), reachable only in-cluster via the issuer's own `ClusterIP` `Service` — **no public `Ingress` route**, live at `AUTH_JWKS_URL=http://api-service-issuer.loginid-takehome.svc.cluster.local/.well-known/jwks.json` (already wired by Theo on the client/consuming side). Enforcement site: the route exists at that exact path and is absent from the public `Ingress`'s rules.
29	- [ ] The JWKS response may set `Cache-Control: public, max-age=<refresh interval>` as good HTTP practice, but this is **advisory only** — the verifier's own staleness policy (already built, PR #30: max staleness = 3× the refresh TTL, fail closed past that bound, per-`kid` rate-limited refetch on an unknown `kid`) is authoritative, not this endpoint's cache headers. This story does not need to coordinate cache-header values with the verifier's staleness logic; they're independent by design.
30	- [ ] **A dedicated, narrowly-scoped QA client credential is seeded in the client store, out-of-band** (same discipline as LT-32's signing-key `Secret` — never through the CI-applied manifest set), **for the PO's joint live-URL review of LT-34/LT-39/LT-40/LT-51.** Per Warren's explicit ruling (via the PM): review tooling must never mint a token by signing directly with the deployed private key — that would hand review tooling the same access F13's whole Deployment split exists to restrict to the issuer process alone. The correct mechanism is this: a real client credential, provisioned like any other caller, calling the real endpoint. Scoped to the minimum needed for the review — `profile:read:own` by default; add `profile:search` only if the review specifically needs to exercise search, going through that scope's own provisioning bar like any other caller, not a blanket grant. Enforcement site: the credential's row in the client store, its `granted_scopes` listed explicitly in the hand-off to the PO (not "whatever's convenient"), and confirmation it was created out-of-band.
31	
32	## Non-goals
33	
34	- No change to `GrantLimiter`, the JWT verification middleware, or `internal/api`'s existing handlers — all already built (PR #30/LT-39/LT-40); this story only calls into them correctly.
35	- No refresh-token support, no denylist/revocation beyond `status=revoked` at the client-store level — matches `api-auth-design.md`'s standing TTL-only-revocation design, not re-litigated here.
36	- No UI/API for self-service client provisioning — clients are provisioned directly against the datastore for this take-home's scale.
37	- No change to the resource-API's own rate limits or touch counter (LT-39) — this story's `GrantLimiter` wiring is a distinct, separate control, per the interface's own doc comment.
38	
39	## PO review script
40	
41	1. Confirm `POST /auth/token` accepts form-encoded `grant_type=client_credentials` and rejects JSON bodies (or at minimum, doesn't require JSON) — read the handler's content-type handling directly.
42	2. Confirm HTTP Basic client auth — a client presenting credentials in the request body alone (no `Authorization` header) is rejected.
43	3. Confirm the identical-body test for unknown-client vs. wrong-secret exists and passes.
44	4. Confirm `client_secret_hash` is Argon2id — read the hashing call, don't infer from a comment.
45	5. Confirm the `GrantLimiter` wiring test exists (sustained failures against one `client_id` eventually block, alert fires once per threshold-crossing).
46	6. Confirm the mint-then-verify-through-the-real-middleware integration test exists and passes.
47	7. Confirm `/.well-known/jwks.json` is live in-cluster and absent from the public `Ingress`.
48	8. Confirm the QA client credential exists, was seeded out-of-band, and its `granted_scopes` are stated explicitly (not assumed).
49	9. **The joint live-URL review, once this and LT-40 are both deployed:** obtain a real token via `POST /auth/token` using the seeded QA credential, then hit `/profiles/search` and `/profiles/{id}` at the live URL — confirming a masked response, 401/403/429 exactly as LT-39's tests predict, and (per LT-52) a real result set from the actual Postgres instance. This is the review LT-34/LT-39/LT-40/LT-51 have all been building toward; all four are accepted together in this one pass.
50	
51	## Research team review
52	
53	**Desmond Okafor — claims check:** [pending]
54	
55	**Tobias Lindqvist — objection:** [pending]
56	
57	**Naomi Voss — ruling:** [pending]
58	

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr view 26 --repo wtvamp/loginid-takehome --json state,mergedAt 2>&1\ngh pr view 30 --repo wtvamp/loginid-takehome --json files 2>&1 | python3 -c \"\nimport json,sys\nd=json.load(sys.stdin)\nfor f in d['files']: print(f['path'])\n\""
}

{"mergedAt":"2026-09-13T11:21:47Z","state":"MERGED"}
cmd/api-service/main.go
go.mod
go.sum
internal/api/audit.go
internal/api/errors.go
internal/api/grantlimiter.go
internal/api/grantlimiter_test.go
internal/api/handlers.go
internal/api/jwks.go
internal/api/jwks_test.go
internal/api/jwtmiddleware.go
internal/api/jwtmiddleware_test.go
internal/api/stopgap_authorizer.go
internal/api/stopgap_authorizer_test.go
internal/app/verifier_router.go
internal/app/verifier_router_test.go
internal/config/config.go
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr diff 30 --repo wtvamp/loginid-takehome 2>&1 > /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr30.diff\nawk '/diff --git a\\/internal\\/api\\/grantlimiter\\.go/,/diff --git a\\/internal\\/api\\/grantlimiter_test\\.go/' /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/pr30.diff | head -90"
}

diff --git a/internal/api/grantlimiter.go b/internal/api/grantlimiter.go
new file mode 100644
index 0000000..ba7c35c
--- /dev/null
+++ b/internal/api/grantlimiter.go
@@ -0,0 +1,182 @@
+package api
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// GrantLimiter enforces the token-issuing endpoint's own failed-grant
+// rate limiting and progressive backoff — handoff-03-auth.md v3:
+// "Token-endpoint brute-force protection, separate from the resource-API
+// rate limits ... failed-grant rate limiting and progressive backoff per
+// client_id and per source IP on the token-issuing endpoint itself, plus
+// alerting on a sustained run of failed grants against one client_id."
+//
+// This is genuinely separate from RateLimiter (ratelimit.go): that type
+// gates the resource API by an already-authenticated sub, at a fixed
+// per-minute rate; this one gates the endpoint that issues the
+// credential in the first place, keyed independently by client_id AND
+// by source IP — a distributed brute force (many IPs, one client_id)
+// and a single-source credential-stuffing run (one IP, many client_ids)
+// are both attack shapes this is meant to slow down, and either key
+// exceeding its own backoff blocks the attempt.
+//
+// Not wired to a live endpoint by this story: /auth/token's real grant
+// logic is LT-51's scope (this story's non-goals). This is the
+// ready-to-use component LT-51 constructs and calls from the real
+// handler — building it now, tested in isolation, means LT-51 doesn't
+// also have to design a backoff/alerting scheme under its own deadline.
+type GrantLimiter interface {
+	// Allow reports whether a grant attempt for clientID from sourceIP
+	// may proceed right now — false while either key is in backoff.
+	Allow(ctx context.Context, clientID, sourceIP string) (bool, error)
+	// RecordFailure records a failed grant attempt for both clientID and
+	// sourceIP, advancing each key's backoff state independently.
+	// Crossing the alert threshold for a given client_id (not source IP
+	// — the requirement names client_id specifically) fires alert
+	// exactly once per crossing, not once per subsequent failure.
+	RecordFailure(ctx context.Context, clientID, sourceIP string)
+	// RecordSuccess clears backoff state for both clientID and
+	// sourceIP — a successful grant resets the count, standard
+	// exponential-backoff practice: this deters sustained brute force,
+	// it does not permanently degrade a legitimate client that mistyped
+	// a secret once.
+	RecordSuccess(ctx context.Context, clientID, sourceIP string)
+}
+
+// grantBackoffState is one key's (a client_id's, or a source IP's)
+// consecutive-failure bookkeeping.
+type grantBackoffState struct {
+	consecutiveFailures int
+	blockedUntil        time.Time
+	alerted             bool
+}
+
+// InProcessGrantLimiter is an in-process implementation. As with
+// RateLimiter/TouchCounter's in-process implementations, a shared store
+// is the multi-instance replacement behind the same interface — the
+// mechanism is this track's call, per handoff-03-auth.md v3.
+//
+// Both maps are swept periodically (see sweepLocked) rather than left to
+// grow forever: this component's own doc comment names "a distributed
+// brute force (many IPs, one client_id)" as a defended attack shape, and
+// that is exactly the traffic pattern that would otherwise grow
+// bySourceIP without bound — every distinct attacking IP earns a
+// permanent entry that only a matching RecordSuccess would remove, which
+// an attacking IP by definition never triggers (Nolan Reyes, PR #30
+// review — the same unbounded-growth shape an earlier PR's TouchCounter
+// review already found and fixed once).
+type InProcessGrantLimiter struct {
+	mu             sync.Mutex
+	byClientID     map[string]*grantBackoffState
+	bySourceIP     map[string]*grantBackoffState
+	baseBackoff    time.Duration
+	maxBackoff     time.Duration
+	alertThreshold int
+	alertFn        func(clientID string, consecutiveFailures int)
+	now            func() time.Time
+	lastSweep      time.Time
+}
+
+// grantSweepInterval and grantEntryTTL bound how long a key's state
+// survives with no further failures against it. A blocked key is never
+// swept before its own backoff has elapsed (sweeping mid-block would
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "grep -n -i \"jwks\\|well-known\\|cache-control\\|max-age\\|staleness\\|AUTH_JWKS_URL\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md"
}

3:Status: **v6** — fixes the JWKS path/URL and cache/refresh guidance (below), ruled so LT-51 implements to this doc rather than the doc following PR #30's already-shipped code. v5's Authorizer stand-in and cumulative-cap answers are unchanged. 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`.
27:**Public-key distribution for the verifier (enforcement site, your call was open, ruled here): JWKS served by the issuer Deployment, reachable only in-cluster via its own `ClusterIP` Service — no Ingress route, never publicly reachable.** Not a mounted public-key file: JWKS survives key rotation without redeploying the verifying Deployment's config, since the verifier fetches by `kid` and only needs to know the issuer Service's in-cluster DNS name (`<issuer-service>.<namespace>.svc.cluster.local`), not track individual key files. In-cluster-only because this token scheme's only consumers are `api-service` and `idp-connector`, both already inside the cluster network; there's no reason to add a new publicly-reachable route on a shared production cluster (`threat-model.md` Assumption 7) for a key set that only internal services ever need.
29:**Path and URL (ruled 2026-09-13, per PR #30/LT-51 — fixed now so LT-51 implements to the doc, not the other way around):** `/.well-known/jwks.json`, the OIDC-discovery convention, served only when `APP_MODE=issuer`. Live at `AUTH_JWKS_URL=http://api-service-issuer.loginid-takehome.svc.cluster.local/.well-known/jwks.json`, already wired by Theo.
31:**Cache/refresh guidance:** the issuer may set a normal `Cache-Control: public, max-age=<refresh interval>` on the response as good HTTP practice, but it's advisory only — **the verifier's own staleness policy is authoritative, not the issuer's cache headers.** That policy is already built (PR #30, Tomasz's re-check confirmed it closed): max staleness = 3× the normal refresh TTL, fail closed (`ErrJWKSStale`, distinct `AuditJWKSUnavailable` event) past that bound rather than serving indefinitely-stale keys; an unknown `kid` triggers one out-of-band refetch, rate-limited **per-`kid`** (not one global gate — a global gate lets an unauthenticated caller with a garbage `kid` exhaust the shared refetch slot for free, since `kid` lookup runs before signature verification; keying per-`kid` closes that without reopening the endpoint-hammering concern the rate limit exists to prevent).
50:- **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.

{
  "command": "grep -n -i \"^Status.*v5\\|v5 \\|Authorizer stand-in\\|cumulative-cap\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md | head -10"
}

3:Status: **v6** — fixes the JWKS path/URL and cache/refresh guidance (below), ruled so LT-51 implements to this doc rather than the doc following PR #30's already-shipped code. v5's Authorizer stand-in and cumulative-cap answers are unchanged. 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`.
5:## v5 addendum: temporary Authorizer stand-in, and the cumulative-cap number

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

1	# LT-41 refinement — S8: connector `/auth` + `/identity` (Q3)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S8 (LT-41); `02-ai-security-architecture/connector-security.md` (including its attack-tree table), `decisions/connector-token-lifecycle-redblue.md`, `handoff-03-auth.md` v6.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now
8	
9	Q3 (the third assignment question) has no code yet, and it's genuinely independent of LT-51's in-flight work: the connector only *validates* a `connector:identity-lookup`-scoped token presented to it — it doesn't need to know how `api-service` obtains that token in the first place (that's LT-33, 02's still-open story, on `api-service`'s outbound side). Pulling this now keeps refinement from being the bottleneck while Renata and Theo build LT-51.
10	
11	**Checked the dependency graph rather than assuming:** LT-33 (02, `handoff-04-secrets.md` row 10 + `api-service`'s client credential) depends in part on "03's connector-client implementation," but that's the *outbound caller* inside `api-service`, not this story — this story is `cmd/idp-connector` itself, the inbound side. LT-41 can be built, refined, and merged without LT-33 closing first; LT-33 is what wires `api-service` to call it correctly, a separate piece.
12	
13	## Correction to `backlog.md`'s own S8 text, found before drafting
14	
15	**Two real controls from `connector-security.md`'s attack-tree table (S3 red/blue, already run and ruled) are missing from `backlog.md`'s S8 acceptance criteria entirely — not stale, just never transcribed down from the design doc into the story.** The table is the authoritative, already-ratified source; the story text predates or simply didn't carry two of its concrete requirements forward:
16	
17	1. **Leaf 1 (connection-reuse token leak):** "fresh, isolated auth header constructed per outbound request, never inherited from connection reuse" — a pooled HTTP client that doesn't reset `Authorization` per call can attach one request's token to another, even with no cache. `backlog.md`'s S8 only names `context.WithTimeout` + bounded pool + backoff from `decisions/go-layout-debate.md`; it never named this specific, checkable requirement.
18	2. **Leaf 5 (credential-stuffing oracle):** rate limiting on outbound vendor calls, keyed per calling-API-client **and** per source IP, with a stricter threshold specifically on vendor-auth **failure ratio** (not just volume — credential stuffing shows as a high failure ratio before high volume), paired with exponential backoff per identity attempted. `backlog.md`'s S8 has no rate-limiting criterion for outbound vendor calls at all.
19	
20	Both are added below as acceptance criteria, since the attack-tree table already ruled on them (Residual L on both, after blue's response) — this refinement is transcribing an already-ratified control, not inventing a new one.
21	
22	## Acceptance criteria (restated from `backlog.md` S8, plus the two additions above)
23	
24	- [ ] Implements 02's token-lifecycle spec (`connector-security.md`, `decisions/connector-token-lifecycle-redblue.md`) without re-litigating the no-cache-by-default posture.
25	- [ ] No vendor token is persisted or cached across requests by default; if a future exception is ever justified it requires re-review, not a silent default change — enforcement site: no storage/cache call in the token-fetch path.
26	- [ ] Every outbound vendor call sets `context.WithTimeout`; the outbound HTTP client uses a bounded connection pool; token-refresh retries back off rather than tight-looping — enforcement site: the HTTP client construction plus a test asserting a timeout fires.
27	- [ ] **Added (attack-tree leaf 1):** a fresh, isolated `Authorization` header is constructed per outbound vendor request — never inherited from HTTP connection/keep-alive reuse. Enforcement site: a test making two sequential vendor calls with two different presented tokens through the same pooled client, asserting the second call's outbound header matches its own token, not the first call's.
28	- [ ] **Added (attack-tree leaf 5):** outbound vendor calls are rate-limited keyed per calling-API-client identity **and** per source IP independently, with a stricter threshold on vendor-auth failure ratio specifically (not just raw volume), paired with exponential backoff per identity attempted. Enforcement site: the rate-limit/backoff component plus a test asserting a high-failure-ratio pattern trips the stricter threshold before a high-volume-but-mostly-successful pattern would.
29	- [ ] The connector's own `/auth`/`/identity` handlers validate an inbound JWT with `aud: idp-connector-service` and `scope: connector:identity-lookup`, distinct from `api-service`'s audience — enforcement site: this handler's own middleware instance, with a test asserting a `loginid-api-service`-audience token is rejected here.
30	- [ ] `/identity` accepts the vendor token as a request header (not a body field, since the assignment's fixed `{"phone","name"}` body has no credential field), fails closed with a generic error that doesn't distinguish "no token" from "bad token" from "vendor rejected it" (same user-enumeration discipline as elsewhere in this project) — per `connector-security.md`'s F3 resolution.
31	- [ ] The token variable is scoped to the narrowest function possible and never passed up the call stack beyond the vendor-call function itself — per attack-tree leaf 4's control (accepted that Go gives no guaranteed memory zeroing, but the exposure window is narrowed to one function call, not eliminated).
32	- [ ] Never logs, in any environment or error path: the end-user's vendor password, any vendor `access_token` or full `Authorization` header value, or raw vendor error response bodies (per `handoff-04-secrets.md`'s never-log list) — enforcement site: log-call review against that list, plus confirming the token field is excluded from any generic request/response dump used in panic traces or debug output, not only application logs (leaf 4's "same discipline as application logs" extension).
33	
34	## Non-goals
35	
36	- No implementation of `api-service`'s outbound call to this connector, or how `api-service` obtains its own `connector:identity-lookup` token — that's LT-33 (02, still open), a separate story.
37	- No real ABC/XYZ vendor integration — a stubbed vendor per the assignment's generic framing; this story's job is the connector's own contract and security properties, not a specific vendor's API quirks.
38	- No change to `handoff-03-auth.md`'s scope vocabulary or claim scheme — already fixed (v6).
39	- No shared rate-limit store/edge mechanism — attack-tree leaf 5 names that as 04's mechanism if enforced at a gateway; this story's own in-process rate limiting is sufficient for this take-home's scale, matching the pattern already used for `RateLimiter`/`TouchCounter`/`GrantLimiter`.
40	
41	## Flagged gap for the joint LT-34/39/40/51 live-URL review script (not this story's own scope)
42	
43	**Per team-lead's request to update the joint review script** (mint a token, create a profile via whatever write path exists, search it masked, read it full with a `reason_code`, hit the 429 cap): **checked directly — there is no write/create path anywhere in `internal/api`.** `backlog.md`'s S6 (LT-39) only implements search/retrieve (Q2's explicit scope); no `POST /profiles` handler exists, and none is currently planned as a story. The migration `Job`'s `shared/` directory only seeds the `auth_method` lookup row (per `migration-approach.md`), not `user_profile`/`user_credential` test data — there's no seeding mechanism for a reviewable profile either.
44	
45	**This is a real gap in the joint review script's own plan, not something this story can quietly work around.** Two options, neither decided here: (a) a small, explicit "seed one test profile" step — either a one-off manual `INSERT` against the deployed Postgres instance (out-of-band, like the credential bootstraps) for review purposes only, clearly not a production data-entry path, or (b) a minimal `POST /profiles` handler as a new, small story if profile creation is expected to exist at all for a complete Q1/Q2 demonstration. Flagging both to team-lead rather than picking one — this is a product/scope decision (does the submission need a write path at all?), not an engineering detail.
46	
47	## PO review script
48	
49	1. Confirm the fresh-header-per-request test (leaf 1) exists and passes.
50	2. Confirm the failure-ratio rate-limit test (leaf 5) exists and passes.
51	3. Confirm the connector's inbound middleware rejects a `loginid-api-service`-audience token (wrong audience for this service).
52	4. Confirm `/identity`'s generic failure response doesn't distinguish no-token/bad-token/vendor-rejected cases.
53	5. Read the vendor-call code path directly: confirm the token variable's scope doesn't escape the vendor-call function, and confirm no log call anywhere references the token, the vendor password, or a raw vendor error body.
54	6. Once deployed (this connector has no public route — reachable only from `api-service` via the existing `NetworkPolicy`): no direct live-URL check is possible for this story on its own; its behavior is exercised indirectly once `api-service`'s outbound call (LT-33) actually invokes it as part of the onboarding flow. Not part of the LT-34/39/40/51 joint review, which only covers Q1/Q2.
55	
56	## Research team review
57	
58	**Desmond Okafor — claims check:** [pending]
59	
60	**Tobias Lindqvist — objection:** [pending]
61	
62	**Naomi Voss — ruling:** [pending]
63	

{
  "command": "grep -n -B2 -A 3 \"Attack-tree table\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md | head -10"
}

71-- OWASP Logging Cheat Sheet (what not to log — credentials, tokens, PII): https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
72-
73:## Attack-tree table — connector token lifecycle (S3 red/blue, 2026-09-12)
74-
75-Full positions, rebuttals, and ruling: `decisions/connector-token-lifecycle-redblue.md`. Table shape per `planning-approach.md` Appendix A.
76-

{
  "command": "sed -n '73,140p' /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md"
}

## Attack-tree table — connector token lifecycle (S3 red/blue, 2026-09-12)

Full positions, rebuttals, and ruling: `decisions/connector-token-lifecycle-redblue.md`. Table shape per `planning-approach.md` Appendix A.

| # | Leaf (attack path) | Precondition | Likelihood | Impact | Blue response: Control *or* Accepted risk | Owner | Residual | Source |
|---|---|---|---|---|---|---|---|---|
| 1 | Cache-key confusion → cross-tenant token/PII leak via request-derived cache key | Persistent cache (eliminated by default posture below) | M | H | **Eliminated by design:** no cache by default (Felix Adebayo, alternatives seat) — no persistent cache means no key to collide on. **Control, exception-path only:** if caching is ever re-opened, key must derive from immutable vendor-issued ids, never request-supplied `name`/`phone`. **Control (this run, Tomasz's rebuttal):** the connection-reuse variant of this leaf survives even with no cache — a pooled HTTP client that doesn't reset `Authorization` per call can attach one request's token to another. Closed with a required control: fresh, isolated auth header constructed per outbound request, never inherited from connection reuse. | 03 (client construction; cache-key derivation if exception ever opened) | **L** — storage variant eliminated; connection-reuse variant closed by an explicit, checkable implementation requirement | OWASP API8:2023; judgment (connection-reuse variant) |
| 2 | Fail-open on KMS unavailability during a caching window | Persistent cache with KMS-backed encryption at rest (eliminated by default posture) | M | H | **Eliminated by design:** no cache by default removes the write-time KMS dependency from the hot path. **Control, exception-path only:** if caching is ever re-opened, KMS-unreachable fails closed to "no cache, fetch live," never to an unencrypted write. Tomasz conceded this leaf outright — no hole found. | 03/04 (KMS mechanism is 04's) | **L** | NIST SP 800-57 |
| 3 | Vendor token replay — no proof-of-possession/session binding once decrypted for use | Token exfiltrated by any other means within its exposure window | M | H | **Accepted risk.** Bearer tokens under RFC 6750 are possession-equals-authorization by design; PoP/binding (DPoP, RFC 9449; mTLS-bound tokens, RFC 8705) needs vendor-side support this project cannot assume for a generic ABC/XYZ vendor the assignment never specifies. Acceptable *for this system* because the token is never cached or persisted on either side of the exchange — it exists only in the caller's possession for the brief span between our `/auth` and `/identity` calls, and only inside the connector's `/identity` handler for that single request, on the connector's side (**updated for F3's caller-holds-the-token model, seam re-run regression fix** — the original justification described the connector itself fetching and using the token in one function call; the exposure window is now bounded by the same no-cache/no-persist discipline applied across two parties instead of inside one function). Retrying `/identity` with a stale token is the caller's decision, not the connector's own retry-with-reuse — the connector treats each presented token as freshly supplied and never retries the vendor call on its own initiative with a token it already knows is invalid. | — (re-review trigger: a PoP-capable vendor surfacing in 01's research) | **M** — accepted, not eliminated; a real vendor-side constraint, not a design gap, but still "possession = authority" for the token's lifetime | RFC 6750 §5; RFC 9700 §2.5 |
| 4 | Process-memory/crash-dump exposure of the plaintext token before encryption | Attacker has read access to a crash artifact or swap on the host | L | M | **Control:** token field excluded from any generic request/response dump used in error handling (panic traces, debug dumps — same discipline as application logs); token variable scoped to the narrowest function possible, never passed up the call stack beyond the vendor-call function. **Residual accepted:** Go gives no guaranteed memory zeroing without unsafe/cgo, so a crash dump taken mid-call could still capture it; acceptable given the window narrowed from a cache TTL to one function call (Felix's alternatives turn). Core-dump suppression at the runtime level is a 04 mechanism, requirement recorded, not resolved here. | 03 (code discipline) / 04 (runtime config) | **L** — narrowed from a standing cache exposure to a single function-call window | OWASP Logging Cheat Sheet |
| 5 | Connector used as a credential-stuffing oracle against the vendor (rate-limit granularity unstated) | No per-identity/per-IP rate-limit granularity stated in the original design | M | M | **Control:** rate limit keyed per calling-API-client *and* per source IP, with a stricter threshold on vendor-auth *failure ratio* specifically (credential stuffing shows as a high failure ratio before high volume), paired with exponential backoff per identity attempted, not just per client — closes the granularity gap without adding a new requirement beyond what §4 already gestured at. | 03 (rate-limit logic) / 04 (shared rate-limit store or edge mechanism, if enforced at a gateway) | **L** | OWASP API4:2023; NIST SP 800-63B §5.2.2 |

Rules of use followed: Tomasz ranked and handed over his top five before Helena answered (per `CASTING.md` §5 ⟨02⟩); Felix's alternatives turn sat between red and blue and eliminated leaves 1's storage variant and 2's substrate by design change rather than control; Helena answered every leaf with a control or a justified accepted risk; Tomasz's rebuttal turn on the top three surfaced one unaddressed variant (leaf 1's connection-reuse case) and one boundary needing explicit statement (leaf 3), both resolved without reopening the ruling; Marcus assigned Residual with the justification in each row. No Residual **H** — none of the five leaves cleared that bar after blue's response and the rebuttal-turn tightening, so no follow-up Story is required; leaf 3's **M** is the one residual worth Warren's attention as a genuine accepted risk, not a gap.

---
Model: sonnet (Tomasz Wrede, red; Felix Adebayo, alternatives; Helena Marsh, blue) / sonnet (Marcus Ilori, lead, ruling and residual scoring). Turns consumed: 5 (red top-five, alternatives, blue, rebuttal, lead residual scoring) — matches the 4-turns-plus-lead budget in `PLAN.md` §3.

{
  "command": "sed -n '138,156p' /Users/warrenthompson/Source/LoginID/03-engineering-delivery/backlog.md"
}

## S7a. Token issuance: real `/auth/token` grant logic (LT-51)

**Status: new** — created from Tobias's (01) objection during LT-40's refinement (`01-product-industry-research-design/refinement/LT-40.md`), which found the gap was unscheduled, not pending: LT-32 built `/auth/token`'s route (a 501 placeholder on the issuer Deployment) and LT-40 builds the verifier side, but nothing implemented the grant itself. Without it, "done = deployed and reviewable at a public URL" would have quietly weakened into "reviewable by an engineer with cluster access" — a materially different and less credible bar than the one this project has held since LT-34.

**Description:** OAuth2 client-credentials grant at `POST /auth/token` on the issuer Deployment (`APP_MODE=issuer`), per Marcus's `handoff-03-auth.md` v4 addendum:
- **Client authentication:** HTTP Basic, `client_id`/`client_secret`, form-encoded `client_credentials` grant per RFC 6749 §4.4.
- **Client store:** the issuer's own datastore (not 05's schema — same F8 boundary as `caller_referral`), secrets hashed with Argon2id, never stored or logged in plaintext.
- **Responses:** RFC 6749 §5.1 (success) / §5.2 (error) shape. An unknown `client_id` and a wrong secret for a known `client_id` return the **identical** `invalid_client` error — no oracle letting a caller distinguish "doesn't exist" from "exists, wrong secret."
- **Token:** short-lived RS256 JWT, `iss`/`aud`/`scope`/`exp`/`sub` claims per `handoff-03-auth.md` v3, algorithm/`kid` header per RFC 8725 pinning (matches LT-40's verifier-side allowlist). A `jti` claim is recommended for audit correlation only — **not** a revocation mechanism; TTL-only revocation stands per `api-auth-design.md`, not re-litigated here.
- **Public-key distribution:** a JWKS endpoint served by the issuer's in-cluster `ClusterIP` `Service` — **no public `Ingress` route** for it; only the verifying middleware inside the cluster (LT-40) needs it, and exposing it publicly is unnecessary attack surface for a machine-to-machine API with no external relying parties.

**Acceptance criteria:**
- [ ] `POST /auth/token` implements RFC 6749 §4.4 client-credentials grant with HTTP Basic client auth and form-encoded body, without re-deriving 02's scheme reasoning in `handoff-03-auth.md` v4.
- [ ] Client secrets are stored Argon2id-hashed in the issuer's own datastore; never logged, never returned in any response, never present in plaintext outside the initial provisioning step — enforcement site: log-call review against `handoff-04-secrets.md`'s never-log list, plus a test asserting the stored representation isn't the plaintext secret.
- [ ] An unknown `client_id` and a wrong secret for a known `client_id` return byte-identical `invalid_client` error responses — enforcement site: a test comparing both response bodies for equality, not just "both return 401."
- [ ] The issued JWT's claims (`iss`, `aud`, `scope`, `exp`, `sub`) and algorithm/`kid` header match what LT-40's verifier middleware expects and validates — enforcement site: an integration test that mints a token here and verifies it through LT-40's actual middleware, not two independently-trusted unit tests that never touch each other.
- [ ] The JWKS endpoint is served only on the issuer's in-cluster `ClusterIP` `Service`, with no `Ingress` route — enforcement site: manifest inspection (04's side) plus a test confirming the endpoint exists on the issuer's internal address.
- [ ] **A dedicated, narrowly-scoped QA client credential is seeded in the client store specifically for the PO's live-URL review** (LT-34/LT-39/LT-40's joint acceptance) — provisioned out-of-band (same discipline as LT-32's signing-key `Secret`, never through the CI-applied manifest set), scoped to the minimum grant needed to exercise `profile:search`/`profile:read:own`/`profile:read:any`, and named/owned so it can be rotated or revoked independently of any real caller's credential.
- [ ] This story's own failed-grant rate limiting/backoff (LT-40's criterion 5) applies to this endpoint's real implementation, not just the placeholder — confirmed by re-running LT-40's rate-limit tests against the real grant logic, not assumed to still hold.

{
  "command": "sed -n '/## S8\\./,/^## S9/p' /Users/warrenthompson/Source/LoginID/03-engineering-delivery/backlog.md"
}

## S8. Connector: /auth + /identity (Q3) (LT-41)

**Description:** `cmd/idp-connector`'s outbound client and inbound handlers for the assignment's fixed `/auth` and `/identity` contracts, per `connector-security.md`'s no-cache-by-default token lifecycle (fetch per `/identity` call, discard on return; fresh isolated `Authorization` header per outbound request, never inherited from pooling/keep-alive; fetch → use-once → zeroize, retries re-fetch via `/auth`). Includes the connector's own inbound self-auth (distinct audience `idp-connector-service`, scope `connector:identity-lookup`, restricted to `api-service` as caller) per `handoff-03-auth.md` v3 §"Where it's validated" (Ingrid's S8 catch), and the `context.WithTimeout` + bounded pool + backoff requirement from `decisions/go-layout-debate.md`.

**Acceptance criteria:**
- [ ] Implements 02's token-lifecycle spec (`connector-security.md`, `decisions/connector-token-lifecycle-redblue.md`) without re-litigating the no-cache-by-default posture.
- [ ] No vendor token is persisted or cached across requests by default; if a future exception is ever justified it requires re-review, not a silent default change — enforcement site: no storage/cache call in the token-fetch path.
- [ ] Every outbound vendor call sets `context.WithTimeout`; the outbound HTTP client uses a bounded connection pool; token-refresh retries back off rather than tight-looping — enforcement site: the HTTP client construction plus a test asserting a timeout fires.
- [ ] The connector's own `/auth`/`/identity` handlers validate an inbound JWT with `aud: idp-connector-service` and `scope: connector:identity-lookup`, distinct from `api-service`'s audience — enforcement site: this handler's own middleware instance, with a test asserting a `loginid-api-service`-audience token is rejected here.
- [ ] Never logs, in any environment or error path: the end-user's vendor password, any vendor `access_token` or full `Authorization` header value, or raw vendor error response bodies (per `handoff-04-secrets.md`'s never-log list) — enforcement site: log-call review against that list.

**Depends on:** S1; **02: Connector security spec** (`connector-security.md`, accepted); **02: Auth scheme and authorization hand-off** (`handoff-03-auth.md` v3, accepted, for the connector's own self-auth).
**Model/effort:** opus, high — the only implementation seat at this tier, per `planning-approach.md`'s connector-token-lifecycle exception.
**Type:** Story.
**Labels:** `track-03`, `security-graded`, `no-code-yet`.

---

## S9. Handler and connector unit tests (LT-42)

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && git pull -q 2>&1; grep -rn \"POST /profiles\\|CreateProfile\\|http.MethodPost\\|NewCreateHandler\\|profiles/create\" internal/api internal/app 2>&1"
}

internal/api/handlers_test.go:25:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/handlers_test.go:35:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/handlers_test.go:55:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{}`))
internal/api/handlers_test.go:75:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a","page_size":51}`))
internal/api/handlers_test.go:97:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"jane"}`))
internal/api/handlers_test.go:125:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/handlers_test.go:146:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/handlers_test.go:159:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/handlers_test.go:175:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/handlers_test.go:337:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a","offset":40}`))
internal/api/handlers_test.go:357:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"jane"}`))
internal/api/handlers_test.go:381:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/handlers_test.go:442:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/api/fakes_test.go:25:func (f *fakeRepository) CreateProfileWithCredential(ctx context.Context, p *model.UserProfile, c *model.UserCredential) (*model.UserProfile, *model.UserCredential, error) {
internal/app/verifier_router_test.go:32:func (f *fakeRepo) CreateProfileWithCredential(ctx context.Context, p *model.UserProfile, c *model.UserCredential) (*model.UserProfile, *model.UserCredential, error) {
internal/app/verifier_router_test.go:118:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/app/verifier_router_test.go:143:	req := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"jane"}`))
internal/app/verifier_router_test.go:235:	authedReq := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/app/verifier_router_test.go:245:	unauthedReq := httptest.NewRequest(http.MethodPost, "/profiles/search", strings.NewReader(`{"name":"a"}`))
internal/app/verifier_router.go:80:	mux.Handle("POST /profiles/search", protect(searchHandler))
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -n \"mux.Handle\" internal/app/verifier_router.go"
}

46:	mux.HandleFunc("/healthz", healthHandlerWithDB("api-service", pingDB))
80:	mux.Handle("POST /profiles/search", protect(searchHandler))
81:	mux.Handle("GET /profiles/{id}", protect(getHandler))
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && git fetch origin -q\nfind . -name \"pr-check.yml\" -o -name \"pr-check.yaml\" 2>/dev/null | grep -v scratchpad"
}

./.github/workflows/pr-check.yml
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && git pull -q 2>&1; find . -iname \"*.yml\" -path \"*workflows*\""
}

./.github/workflows/deploy.yml
./.github/workflows/pr-check.yml
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "file_path": "/Users/warrenthompson/Source/LoginID/.github/workflows/pr-check.yml"
}

1	name: PR check
2	
3	on:
4	  pull_request:
5	    branches: [main]
6	
7	permissions:
8	  contents: read
9	
10	jobs:
11	  build-lint-test:
12	    name: Build, lint, test
13	    runs-on: ubuntu-latest
14	    steps:
15	      - uses: actions/checkout@v4
16	
17	      - uses: actions/setup-go@v5
18	        with:
19	          go-version: "1.27.1"
20	          cache: true
21	
22	      - name: Build
23	        run: go build ./...
24	
25	      - name: Vet
26	        run: go vet ./...
27	
28	      - name: golangci-lint
29	        uses: golangci/golangci-lint-action@v7
30	        with:
31	          version: latest
32	          install-mode: goinstall # compiles against the job's Go 1.27 toolchain instead of a prebuilt (go1.24) release
33	
34	      - name: Test (race)
35	        run: go test ./... -race -v
36	
37	  security-scan:
38	    name: govulncheck
39	    runs-on: ubuntu-latest
40	    steps:
41	      - uses: actions/checkout@v4
42	        with:
43	          fetch-depth: 0 # gitleaks needs full history, not a shallow clone
44	
45	      - uses: actions/setup-go@v5
46	        with:
47	          go-version: "1.27.1"
48	
49	      - name: govulncheck
50	        run: |
51	          go install golang.org/x/vuln/cmd/govulncheck@latest
52	          govulncheck ./...
53	
54	      - name: gitleaks
55	        uses: gitleaks/gitleaks-action@v2
56	        env:
57	          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
58	
59	  manifest-secret-guard:
60	    name: Guard against the JWT signing-key Secret leaking into another manifest
61	    runs-on: ubuntu-latest
62	    steps:
63	      - uses: actions/checkout@v4
64	
65	      - name: Check deploy/manifests.yaml
66	        run: |
67	          # There is no admission controller (no Gatekeeper/Kyverno/OPA,
68	          # no Pod Security label) on the target cluster restricting which
69	          # Secret a Deployment spec can reference, per 01's LT-32 review —
70	          # the physical-absence guarantee for api-service's pod spec (it
71	          # must never mount api-service-jwt-signing-key) is otherwise
72	          # enforced only by code review. This is the CI-side backstop:
73	          # fail the build if that Secret name appears in any manifest
74	          # document other than the api-service-issuer Deployment's own.
75	          python3 - <<'PYEOF'
76	          import sys
77	          docs = open("deploy/manifests.yaml").read().split("\n---\n")
78	          fail = False
79	          for doc in docs:
80	              if "api-service-jwt-signing-key" in doc and "name: api-service-issuer" not in doc:
81	                  print("::error file=deploy/manifests.yaml::A manifest document references api-service-jwt-signing-key outside the api-service-issuer Deployment:")
82	                  print(doc)
83	                  fail = True
84	          sys.exit(1 if fail else 0)
85	          PYEOF
86	
87	  changes:
88	    name: Detect whether image-buildable code changed
89	    runs-on: ubuntu-latest
90	    outputs:
91	      code: ${{ steps.filter.outputs.code }}
92	    steps:
93	      - uses: actions/checkout@v4
94	      - uses: dorny/paths-filter@v3
95	        id: filter
96	        with:
97	          # Inverse of deploy.yml's paths-ignore: a docs-only PR (LOG.md,
98	          # PLAN.md, track directories, decisions/**) shouldn't spin up
99	          # Docker builds that can't have changed. build-lint-test,
100	          # security-scan, and manifest-secret-guard above are NOT gated
101	          # by this — they stay on every PR regardless of what changed.
102	          filters: |
103	            code:
104	              - 'cmd/**'
105	              - 'internal/**'
106	              - 'migrations/**'
107	              - 'deploy/**'
108	              - 'go.mod'
109	              - 'go.sum'
110	              - '**/Dockerfile'
111	              - '.github/workflows/**'
112	
113	  build-images:
114	    name: Build images (no push)
115	    runs-on: ubuntu-latest
116	    needs: [build-lint-test, changes]
117	    if: needs.changes.outputs.code == 'true'
118	    strategy:
119	      matrix:
120	        service: [api-service, idp-connector]
121	    steps:
122	      - uses: actions/checkout@v4
123	
124	      - name: Build ${{ matrix.service }} image
125	        uses: docker/build-push-action@v6
126	        with:
127	          context: .
128	          file: cmd/${{ matrix.service }}/Dockerfile
129	          push: false
130	          tags: loginid-takehome/${{ matrix.service }}:pr-${{ github.event.pull_request.number }}
131	

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -n -A 20 \"func newPostgresFamilyFixture\" internal/dao/conformance/testutil_test.go"
}

101:func newPostgresFamilyFixture(t *testing.T, driver, dsnEnvVar string) fixture {
102-	t.Helper()
103-	dsn := os.Getenv(dsnEnvVar)
104-	if dsn == "" {
105-		t.Skipf("%s not set — skipping %s conformance run", dsnEnvVar, driver)
106-	}
107-
108-	admin, err := sql.Open("pgx", dsn)
109-	if err != nil {
110-		t.Fatalf("opening %s: %v", dsnEnvVar, err)
111-	}
112-	t.Cleanup(func() { _ = admin.Close() })
113-	admin.SetMaxOpenConns(1)
114-
115-	schemaName := fmt.Sprintf("conf_%s_%d", driver, rand.Int63())
116-	if _, err := admin.Exec("CREATE SCHEMA " + schemaName); err != nil {
117-		t.Fatalf("creating schema: %v", err)
118-	}
119-	t.Cleanup(func() { _, _ = admin.Exec("DROP SCHEMA " + schemaName + " CASCADE") })
120-	if _, err := admin.Exec("SET search_path TO " + schemaName + ", public"); err != nil {
121-		t.Fatalf("setting search_path: %v", err)
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -rn \"TEST_POSTGRES_DSN\\|TEST_COCKROACHDB_DSN\\|newPostgresFamilyFixture(\" internal/dao/conformance/ .github/workflows/"
}

internal/dao/conformance/testutil_test.go:101:func newPostgresFamilyFixture(t *testing.T, driver, dsnEnvVar string) fixture {
internal/dao/conformance/testutil_test.go:215:		return newPostgresFamilyFixture(t, "postgres", "TEST_POSTGRES_DSN")
internal/dao/conformance/testutil_test.go:218:		return newPostgresFamilyFixture(t, "cockroachdb", "TEST_COCKROACHDB_DSN")
internal/dao/conformance/conformance_test.go:626:	repo := newPostgresFamilyFixture(t, "cockroachdb", "TEST_COCKROACHDB_DSN").repo
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && sed -n '1,25p' internal/api/ratelimit.go\necho \"---replicas---\"\ngrep -n -B5 -A5 \"replicas\" deploy/manifests.yaml | grep -B5 -A5 \"api-service\" | head -60"
}

package api

import (
	"context"
	"sync"
	"time"
)

// RateLimiter enforces handoff-03-auth.md v3's per-client-credential
// rate limits (60 req/min for read:own/read:any, 10 req/min for
// profile:search), keyed per sub+scope. The mechanism is this track's
// call (v3, explicitly) — an interface so handler tests use a fake
// instead of real wall-clock behavior.
type RateLimiter interface {
	// Allow reports whether sub may make one more request under scope
	// right now, given limit requests per rolling minute.
	Allow(ctx context.Context, sub string, scope Scope, limit int) (bool, error)
}

// InProcessRateLimiter is a fixed-window (per-wall-clock-minute) limiter,
// in-process rather than Redis-backed — the simplest mechanism satisfying
// v3's "the mechanism is your call" framing, sufficient for this
// take-home's single-instance deployment. A fixed window (vs. sliding) can
// admit up to 2x limit across a window boundary; accepted here as a
// deliberate simplification, not hidden — a production multi-instance
---replicas---
33-spec:
34-  # Quota math (LT-52 adds Postgres + a transient migration Job pod;
35-  # LT-51 adds the issuer database in the same Postgres instance and the
36-  # migration Job's third invocation — no new pods, no change to the
37-  # numbers below beyond what LT-52 already established. api-service-
38:  # issuer's replicas dropped 2 -> 1 per Helena's (02) ruling, which
39-  # only tightens headroom further, not loosens it):
40-  #   requests.cpu:    550m existing + postgres 100m + migrate 50m  = 700m  (limit "1" = 1000m, fits)
41-  #   requests.memory: 704Mi existing + postgres 256Mi + migrate 64Mi = 1024Mi (was AT the 1Gi limit already — bumped to 2Gi for real headroom)
42-  #   limits.cpu:      2750m existing + postgres 500m + migrate 200m = 3450m (was "3" = 3000m — bumped to "4")
43-  #   limits.memory:   1408Mi existing + postgres 512Mi + migrate 128Mi = 2048Mi (was AT the 2Gi limit — bumped to 3Gi)
--
61-# api-service-issuer: the ONLY Deployment that mounts the JWT signing key
62-# (F13's fix, per handoff-04-secrets.md row #2 and
63-# containerization-design.md's "Why two Deployments of one image, not RBAC
64-# on one"). Same image as api-service, mode selected by APP_MODE.
65-#
66:# replicas: 1, not 2 — per Helena's (02) LT-51 review: GrantLimiter
67-# (internal/api, wired around the client-credentials grant) tracks
68:# failed-attempt state in-process, per-pod. Two replicas behind
69-# round-robin means an attacker's failures split across both, silently
--
71-# security regression, not a cosmetic one. This POC issuer has no HA
72-# requirement that would justify accepting that.
73-apiVersion: apps/v1
74-kind: Deployment
75-metadata:
76-  name: api-service-issuer
77-  namespace: loginid-takehome
78-spec:
79:  replicas: 1
80-  selector: {matchLabels: {app: api-service-issuer}}
81-  template:
82-    metadata: {labels: {app: api-service-issuer}}
83-    spec:
84-      serviceAccountName: api-service-issuer
--
238-apiVersion: apps/v1
239-kind: StatefulSet
240-metadata: {name: postgres, namespace: loginid-takehome}
241-spec:
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -n -B15 \"^  name: api-service$\" deploy/manifests.yaml | grep -n \"replicas\\|name: api-service\"\necho \"---\"\nawk '/^kind: Deployment/{d=1} d && /name: api-service$/{print NR\": \"$0; found=1} found && /replicas:/{print NR\": \"$0; exit}' deploy/manifests.yaml"
}

---
87:         - name: api-service
243:   replicas: 1
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && awk '/^kind: Deployment/{blk=\"\"} {blk=blk\"\\n\"$0} /^metadata:.*name: api-service}/{print blk; exit}' deploy/manifests.yaml | head -20\necho \"===alt===\"\ngrep -n \"^kind: Deployment\\|name: api-service\\b\\|replicas:\" deploy/manifests.yaml"
}

===alt===
24:metadata: {name: api-service, namespace: loginid-takehome}
28:metadata: {name: api-service-issuer, namespace: loginid-takehome}
66:# replicas: 1, not 2 — per Helena's (02) LT-51 review: GrantLimiter
74:kind: Deployment
76:  name: api-service-issuer
79:  replicas: 1
87:        - name: api-service
113:metadata: {name: api-service-issuer, namespace: loginid-takehome}
243:  replicas: 1
382:kind: Deployment
387:  replicas: 1
435:metadata: {name: api-service-issuer-default-deny, namespace: loginid-takehome}
460:          - {path: /healthz, pathType: Exact, backend: {service: {name: api-service, port: {number: 443}}}}
461:          - {path: /auth/token, pathType: Exact, backend: {service: {name: api-service-issuer, port: {number: 443}}}}
468:          - {path: /profiles, pathType: Prefix, backend: {service: {name: api-service, port: {number: 443}}}}
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && sed -n '378,400p' deploy/manifests.yaml"
}

              GOOSE_MIGRATION_DIR=/migrations/shared goose -table goose_db_version_shared up
              GOOSE_DBSTRING="$ISSUER_GOOSE_DBSTRING" GOOSE_MIGRATION_DIR=/migrations/issuer goose -table goose_db_version_issuer up
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: idp-connector
  namespace: loginid-takehome
spec:
  replicas: 1
  selector: {matchLabels: {app: idp-connector}}
  template:
    metadata: {labels: {app: idp-connector}}
    spec:
      securityContext: {runAsNonRoot: true, runAsUser: 65532, runAsGroup: 65532}
      containers:
        - name: idp-connector
          image: ghcr.io/wtvamp/loginid-takehome/idp-connector:IMAGE_TAG
          securityContext: {readOnlyRootFilesystem: true}
          resources:
            requests: {cpu: "50m", memory: "64Mi"}
            limits: {cpu: "250m", memory: "128Mi"}
          env:
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && sed -n '1,35p' deploy/manifests.yaml"
}

# Deploy manifests for LT-34/LT-45/LT-47's vertical slice, extended in
# LT-32 for the issuer Deployment split (F13's fix) and LT-52 for a real
# Postgres instance, the migration Job, and DB_DSN_FILE wiring into
# api-service. No CockroachDB deployment here — CI-only (LT-47), per
# LT-52's stated scope limit.
#
# No Namespace object here, deliberately: the scoped loginid-takehome-deployer
# ServiceAccount's RBAC (deploy/rbac.yaml) is namespace-scoped to
# loginid-takehome and correctly cannot get/create/patch a cluster-scoped
# Namespace object — that's the isolation working as designed, not a gap.
# The namespace itself is created once, out of band, by whoever runs the
# initial cluster bootstrap (deploy/rbac.yaml also creates
# loginid-takehome-runners for the same reason).
#
# No Secret object here either, and none ever will be for the JWT signing
# key specifically: deploy/rbac.yaml's Role grants nothing on `secrets` at
# all, so an attempt to apply one here would fail Forbidden, the same way
# Namespace did. The signing-key Secret is created out-of-band — see
# deploy/issuer-secret-bootstrap.yaml — per Tobias's (01) accepted
# objection on LT-32's refinement: the CI-applied manifest set must never
# be the thing that can read or write that key.
apiVersion: v1
kind: ServiceAccount
metadata: {name: api-service, namespace: loginid-takehome}
---
apiVersion: v1
kind: ServiceAccount
metadata: {name: api-service-issuer, namespace: loginid-takehome}
---
apiVersion: v1
kind: ResourceQuota
metadata: {name: loginid-takehome-quota, namespace: loginid-takehome}
spec:
  # Quota math (LT-52 adds Postgres + a transient migration Job pod;
  # LT-51 adds the issuer database in the same Postgres instance and the
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && sed -n '85,120p' deploy/manifests.yaml"
}

      securityContext: {runAsNonRoot: true, runAsUser: 65532, runAsGroup: 65532}
      containers:
        - name: api-service
          image: ghcr.io/wtvamp/loginid-takehome/api-service:IMAGE_TAG
          securityContext: {readOnlyRootFilesystem: true}
          resources:
            requests: {cpu: "100m", memory: "128Mi"}
            limits: {cpu: "500m", memory: "256Mi"}
          env:
            - {name: HTTP_ADDR, value: ":8080"}
            - {name: APP_MODE, value: issuer}
            - {name: JWT_SIGNING_KEY_FILE, value: /secrets/jwt/signing-key}
            - {name: ISSUER_DB_DSN_FILE, value: /secrets/issuer-db/dsn}
            - {name: AUTH_JWT_ISSUER, value: "https://auth.loginid-takehome.internal"}
            - {name: AUTH_JWT_AUDIENCE, value: "loginid-api-service"}
          volumeMounts:
            - {name: jwt-signing-key, mountPath: /secrets/jwt, readOnly: true}
            - {name: issuer-db-runtime-credential, mountPath: /secrets/issuer-db, readOnly: true}
          readinessProbe: {httpGet: {path: /healthz, port: 8080}, initialDelaySeconds: 5}
          livenessProbe: {httpGet: {path: /healthz, port: 8080}, initialDelaySeconds: 10}
      volumes:
        - name: issuer-db-runtime-credential
          secret: {secretName: issuer-db-runtime-credential}
        - name: jwt-signing-key
          secret: {secretName: api-service-jwt-signing-key}
---
apiVersion: v1
kind: Service
metadata: {name: api-service-issuer, namespace: loginid-takehome}
spec:
  selector: {app: api-service-issuer}
  ports: [{port: 443, targetPort: 8080}]
---
# --- Postgres (LT-52) ---
#
# ConfigMap holding the initdb script that creates the migrator/runtime
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -n \"^kind: Deployment\" deploy/manifests.yaml"
}

74:kind: Deployment
382:kind: Deployment
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -n \"^kind:\" deploy/manifests.yaml"
}

23:kind: ServiceAccount
27:kind: ServiceAccount
31:kind: ResourceQuota
74:kind: Deployment
112:kind: Service
138:kind: ConfigMap
222:kind: Issuer
228:kind: Certificate
239:kind: StatefulSet
308:kind: Service
321:kind: NetworkPolicy
345:kind: Job
382:kind: Deployment
407:kind: Service
417:kind: NetworkPolicy
434:kind: NetworkPolicy
446:kind: Ingress
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && sed -n '108,118p' deploy/manifests.yaml\necho \"---\"\ngit log --oneline -5 -- deploy/manifests.yaml"
}

        - name: jwt-signing-key
          secret: {secretName: api-service-jwt-signing-key}
---
apiVersion: v1
kind: Service
metadata: {name: api-service-issuer, namespace: loginid-takehome}
spec:
  selector: {app: api-service-issuer}
  ports: [{port: 443, targetPort: 8080}]
---
# --- Postgres (LT-52) ---
---
336d00f Add AUTH_JWT_ISSUER/AUDIENCE and CONNECTOR_JWT_AUDIENCE; fix runbook audience literal
b035fca Address Priya's PR #36 review: empty-PVC caveat, hand-apply runbook, verified live state
65b4b0d LT-51 infra: issuer database, roles, third migration invocation, QA-client runbook
405b668 Add Ingress route for /profiles (LT-39/LT-40's protected routes)
39b49bc Fix PR #29 review findings: schema CREATE grant, TLS, DSN-in-argv, wait bug
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr view 30 --repo wtvamp/loginid-takehome --json state,mergedAt 2>&1\ngh pr list --repo wtvamp/loginid-takehome --state all --limit 15 --json number,title,state,mergedAt 2>&1 | python3 -m json.tool"
}

{"mergedAt":"2026-09-13T12:03:02Z","state":"MERGED"}
[
    {
        "mergedAt": null,
        "number": 45,
        "state": "OPEN",
        "title": "api-service replicas: 2 -> 1 (in-process rate limiters)"
    },
    {
        "mergedAt": "2026-09-13T14:03:24Z",
        "number": 44,
        "state": "MERGED",
        "title": "fix: JWKS fetch failures were silent; cold-start miscategorized"
    },
    {
        "mergedAt": "2026-09-13T13:54:24Z",
        "number": 43,
        "state": "MERGED",
        "title": "Fix AUTH_JWKS_URL: explicit :443 port"
    },
    {
        "mergedAt": "2026-09-13T13:50:31Z",
        "number": 42,
        "state": "MERGED",
        "title": "fix: fail api-service startup loudly on missing AUTH_JWT_ISSUER/AUDIENCE"
    },
    {
        "mergedAt": "2026-09-13T13:46:47Z",
        "number": 41,
        "state": "MERGED",
        "title": "Wire AUTHZ_QA_SUB/AUTHZ_QA_ALLOWED_PROFILE_ID on api-service"
    },
    {
        "mergedAt": "2026-09-13T14:06:08Z",
        "number": 40,
        "state": "MERGED",
        "title": "LT-41: idp-connector /auth + /identity (Q3, stubbed vendor)"
    },
    {
        "mergedAt": "2026-09-13T13:35:22Z",
        "number": 39,
        "state": "MERGED",
        "title": "LT-51 follow-up: PHC-format Argon2id hashes, verify-then-rehash, goose migration fix"
    },
    {
        "mergedAt": "2026-09-13T12:57:25Z",
        "number": 38,
        "state": "MERGED",
        "title": "LT-51 infra half: issuer database, third migration invocation, QA-client runbook"
    },
    {
        "mergedAt": "2026-09-13T12:46:34Z",
        "number": 37,
        "state": "MERGED",
        "title": "Contract \u00a77: forward requirement for credential verification"
    },
    {
        "mergedAt": null,
        "number": 36,
        "state": "CLOSED",
        "title": "LT-51 infra half: issuer database, third migration invocation, QA-client runbook"
    },
    {
        "mergedAt": "2026-09-13T12:34:43Z",
        "number": 35,
        "state": "MERGED",
        "title": "LT-39: review demo-data SQL"
    },
    {
        "mergedAt": "2026-09-13T12:51:50Z",
        "number": 34,
        "state": "MERGED",
        "title": "LT-51: OAuth2 client-credentials grant with a real Postgres-backed client store"
    },
    {
        "mergedAt": "2026-09-13T12:19:38Z",
        "number": 33,
        "state": "MERGED",
        "title": "LT-52: /healthz reports DB connectivity (criterion 5)"
    },
    {
        "mergedAt": "2026-09-13T12:15:29Z",
        "number": 32,
        "state": "MERGED",
        "title": "Add Ingress route for /profiles (LT-39/LT-40 protected routes)"
    },
    {
        "mergedAt": "2026-09-13T11:53:38Z",
        "number": 31,
        "state": "MERGED",
        "title": "LT-52 follow-up: hex passwords, self-diagnosing RBAC"
    }
]
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && git fetch origin -q; git status; git log --oneline -3 origin/main"
}

On branch main
Your branch is behind 'origin/main' by 4 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean
24b6455 Merge PR #40: LT-41 idp-connector — /auth and /identity against a stubbed vendor, no-cache token lifecycle, per-identity + overflow-bucket backoff, uniform-timing failure branches
aff6e6e Merge PR #44: verifier logs JWKS fetch failures (once per streak) and audits 'verification unavailable' distinctly from 'token invalid'
5f658b7 fix review findings: real-fetch classification test, flip-flop doc note
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && git pull -q origin main 2>&1; grep -n \"^kind: Deployment\" deploy/manifests.yaml; echo ---; grep -n \"name: api-service\\b\" deploy/manifests.yaml"
}

74:kind: Deployment
382:kind: Deployment
---
24:metadata: {name: api-service, namespace: loginid-takehome}
28:metadata: {name: api-service-issuer, namespace: loginid-takehome}
76:  name: api-service-issuer
87:        - name: api-service
113:metadata: {name: api-service-issuer, namespace: loginid-takehome}
435:metadata: {name: api-service-issuer-default-deny, namespace: loginid-takehome}
460:          - {path: /healthz, pathType: Exact, backend: {service: {name: api-service, port: {number: 443}}}}
461:          - {path: /auth/token, pathType: Exact, backend: {service: {name: api-service-issuer, port: {number: 443}}}}
468:          - {path: /profiles, pathType: Prefix, backend: {service: {name: api-service, port: {number: 443}}}}
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && gh pr diff 45 --repo wtvamp/loginid-takehome 2>&1 | head -80"
}

diff --git a/deploy/api-service.yaml b/deploy/api-service.yaml
index 52ae15b..e3804f7 100644
--- a/deploy/api-service.yaml
+++ b/deploy/api-service.yaml
@@ -2,13 +2,23 @@
 # (LT-52) so the deploy workflow can apply it AFTER Postgres exists and
 # the migration Job has completed — api-service is the one thing in this
 # namespace whose startup depends on the schema already being there.
+#
+# replicas: 1, not 2 — per Naomi's (01) live review: RateLimiter,
+# TouchCounter, and GrantLimiter are all in-process, per-pod state. She
+# reproduced a 12-request burst passing a 10 req/min limit because the
+# load balancer split it across two pods, each with its own independent
+# counter — the same class of issue as api-service-issuer's replica
+# count (Helena's review). Production path for real HA is a shared
+# store (Redis), already named in the relevant code comments; not built
+# for this take-home, so replicas stay at 1 rather than shipping a
+# rate limiter that silently doesn't limit at the stated rate.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: api-service
   namespace: loginid-takehome
 spec:
-  replicas: 2
+  replicas: 1
   selector: {matchLabels: {app: api-service}}
   template:
     metadata: {labels: {app: api-service}}
diff --git a/deploy/manifests.yaml b/deploy/manifests.yaml
index 25f4d81..87d0a2f 100644
--- a/deploy/manifests.yaml
+++ b/deploy/manifests.yaml
@@ -35,8 +35,14 @@ spec:
   # LT-51 adds the issuer database in the same Postgres instance and the
   # migration Job's third invocation — no new pods, no change to the
   # numbers below beyond what LT-52 already established. api-service-
-  # issuer's replicas dropped 2 -> 1 per Helena's (02) ruling, which
-  # only tightens headroom further, not loosens it):
+  # issuer's replicas dropped 2 -> 1 per Helena's (02) ruling, and
+  # api-service's own replicas dropped 2 -> 1 per Naomi's (01) live
+  # review — RateLimiter/TouchCounter/GrantLimiter are all in-process,
+  # per-pod state; a 12-request burst passed a 10 req/min limit because
+  # the load balancer split it across two pods, each with its own
+  # independent counter. Both reductions only tighten headroom further,
+  # never loosen it, so the numbers below are unchanged, now with more
+  # margin than shown):
   #   requests.cpu:    550m existing + postgres 100m + migrate 50m  = 700m  (limit "1" = 1000m, fits)
   #   requests.memory: 704Mi existing + postgres 256Mi + migrate 64Mi = 1024Mi (was AT the 1Gi limit already — bumped to 2Gi for real headroom)
   #   limits.cpu:      2750m existing + postgres 500m + migrate 200m = 3450m (was "3" = 3000m — bumped to "4")
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -n \"replicas:\" deploy/api-service.yaml"
}

11:  replicas: 2
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "grep -n -i \"skip\\|TEST_POSTGRES_DSN\\|TEST_COCKROACHDB_DSN\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-38.md 2>/dev/null | head -10\necho \"---LT-39---\"\ngrep -n -i \"replica\\|burst\\|in-process\" /Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-39.md 2>/dev/null | head -10"
}

58:**Finding: the CI acceptance criterion is not met, and "Build, lint, test" going green does not mean what it appears to mean.** `newPostgresFamilyFixture` (shared by the `postgres` and `cockroachdb` backends) explicitly skips (`t.Skipf`) when its DSN env var (`TEST_POSTGRES_DSN`/`TEST_COCKROACHDB_DSN`) isn't set — by its own comment, "this suite asserts behavior, it doesn't stand up infrastructure." `pr-check.yml` never sets either variable and never provisions a Postgres/CockroachDB service or testcontainer. Only the SQLite fixture is genuinely self-contained (in-memory). **Net effect: every Postgres and CockroachDB conformance test — including `TestConformance_CockroachDB_RealSerializationRetry`, this story's own flagship acceptance criterion — silently skips on every CI run, and Go reports a skip as neither pass nor fail, so nothing currently flags this as a problem.** `go test ./... -race` returning success proves SQLite's conformance tests passed; it proves nothing about the other two backends.
60:**Ruling (team-lead):** the suite itself is well-built and correctly scoped — this is a pipeline-wiring gap, not a defect in the tests. Fix in flight: Theo adds real Postgres/CockroachDB service containers to `pr-check.yml`; Renata makes the fixtures fail loudly under `CI=true` rather than skip, so a future regression of this exact gap can't hide behind a green build again.
---LT-39---
34:- No rate-limit/counter *mechanism* choice (Redis vs. in-process) — that's Renata's implementation call, per v3's own "the mechanism is your call" framing.
82:**Real defect found and reproduced live, not from code alone: the per-minute `RateLimiter` (10 req/min search) does not reliably enforce its stated limit.** `api-service` runs 2 replicas; `RateLimiter` is in-process (per-pod memory) — its own code comment states this is "a deliberate simplification, not hidden — a production multi-instance deployment would need a shared store (Redis) instead," but the deployed manifest runs 2 replicas anyway. Reproduced: a 12-call rapid burst produced zero 429s (load-balanced roughly evenly across both pods, each staying under its own independent count of 10); a subsequent 30-call burst started producing 429s at call 9, at a point with no fixed relationship to the stated "10 req/min." The effective limit is somewhere between 10–20 depending on load-balancer distribution, not a real per-client cap. `TouchCounter` and `GrantLimiter` share the identical in-process, per-pod design (confirmed by reading their source) and almost certainly have the same gap, though I could not exercise `TouchCounter`'s cap live — see below.
86:**Ruling (team-lead):** `api-service` moves from 2 replicas to 1 (matching the issuer Deployment's own replica count) — a security control beats nominal HA for a POC at this scale; Redis remains the documented production-scale path (already stated in the code's own comments), not something to build now. Re-run the rate-limit burst test after Theo's manifest PR redeploys.
88:**Correction (Tobias's objection, verified before applying) — 1 replica alone does not close this, it only narrows it, and the doc must say so plainly.** Confirmed directly: neither `deploy/manifests.yaml` nor `deploy/api-service.yaml` sets a `Deployment.spec.strategy` field, so Kubernetes' default applies — `RollingUpdate` with `maxSurge: 25%`, which rounds up to 1 additional pod even at `replicas: 1`. Every future merge-to-main deploy (LT-47's auto-deploy-on-merge design) briefly runs **two** `api-service` pods simultaneously while the new one's readiness probe is pending — the exact condition that broke the limiter in this review's live test, recurring on a predictable schedule during every deploy, not eliminated by the replica-count change. **This is a partial mitigation, not a fix.** The only complete closure is the shared store (Redis) the code's own comment already names as the multi-instance answer. Counter-proposal accepted: flagging to Theo that `api-service`'s `Deployment.spec.strategy.type` should be set to `Recreate` (guaranteeing exactly one pod at any time, at the cost of a brief availability gap during deploy — the same trade this ruling already accepted the spirit of, now actually holding through a rollout too), as a cheap second step beyond the replica-count change alone.
92:- Per-minute `RateLimiter` (10 req/min search / 60 req/min read) — **verified by unit test only; live verification pending the replica fix.** The reproduced cross-replica gap above is real and was live, but it's a deployment-topology defect the replica-count ruling addresses, not a defect in the limiter's own logic (which the unit tests already correctly cover for a single instance).

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

1	# LT-42 refinement — S9: handler and connector unit tests
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S9 (LT-42); `decisions/test-double-strategy.md`.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this shape, not a from-scratch build
8	
9	**Checked before drafting: most of this story's scope already exists**, built incrementally as part of LT-39/LT-40/LT-41/LT-51's own PRs, not deferred to a dedicated later story the way `backlog.md`'s original sequencing (S9 depends on S6, S7, S8) implied. Confirmed by listing the actual test files: `internal/api` has `handlers_test.go`, `jwtmiddleware_test.go`, `ratelimit_test.go`, `touchcounter_test.go`, `grantlimiter_test.go`, `tokenhandler_test.go`, `jwks_test.go`, `masking_test.go`, `cursor_test.go`, `stopgap_authorizer_test.go`, `fakes_test.go`, `clientstore_test.go`, `issuer_verifier_integration_test.go`; `internal/connector` has `handlers_test.go`, `httpvendorclient_test.go`, `identitylimiter_test.go`, `stubvendorclient_test.go`. This story's actual remaining job is **verification of completeness against its own stated criteria, plus closing any real gaps found** — not building a test suite that's already substantially written.
10	
11	## Acceptance criteria (restated from `backlog.md` S9, reframed as a completeness check)
12	
13	- [ ] **Hand-written fakes, not generated mocks** — confirmed already true: `internal/api/fakes_test.go` exists as hand-written interface fakes per `decisions/test-double-strategy.md`'s ruling; no `gomock`/`mockery` dependency anywhere in `go.mod`. Verify this remains true, not re-decide it.
14	- [ ] **Same-PR fake-update discipline** — `decisions/test-double-strategy.md` states this as a *review checklist item*, not an automated check. This story's job: confirm the checklist item is actually stated somewhere a reviewer will see it (PR template, `CONTRIBUTING`, or the decision doc itself, cross-referenced) — not just asserted in a design doc nobody re-reads at review time.
15	- [ ] Handler tests cover every sentinel-to-HTTP-status mapping from `decisions/error-semantics.md`'s boundary translation function, **including the unmapped-error-defaults-to-500-with-no-detail case** — confirm this specific case has its own named test (`TestSearchHandler_DAOError_NeverLeaksRawMessage`, already found in `handlers_test.go` during LT-39's review — re-confirm it covers the *unmapped* case specifically, not only the mapped-sentinel cases).
16	- [ ] Connector tests cover the no-cache token-lifecycle assertion (a second `/identity` call re-fetches via `/auth`, never reuses a prior token) — confirm this exact assertion exists in `internal/connector`'s test files, since it's the one criterion from `backlog.md`'s original S9 text I have not yet independently confirmed is covered by name.
17	- [ ] **Gap check, not assumed clean:** read every test file listed above for the *specific* named assertions this story's criteria require, not just "tests exist." A file existing doesn't mean the specific criterion is covered — the LT-39/LT-40 reviews already found real gaps (audit logging, timing-oracle) in code that had substantial test coverage but missed a specific requirement.
18	
19	## Non-goals
20	
21	- No new handler/connector logic — this story is tests only, confirming and closing gaps in what's already built.
22	- The DAO's own cross-backend correctness — that's LT-38's job, already its own story with its own (currently failing) CI criterion, not duplicated here.
23	- No change to `decisions/test-double-strategy.md` itself unless a real gap in its own stated discipline is found.
24	
25	## PO review script
26	
27	1. Confirm no generated-mock library is a dependency (`go.mod`), and that `fakes_test.go` (or equivalent) contains genuinely hand-written fakes.
28	2. Confirm the same-PR fake-update rule is stated somewhere a reviewer actually sees at review time (not buried only in a decision doc).
29	3. Read `handlers_test.go`'s DAO-error test directly: confirm it specifically exercises an *unmapped* sentinel (one not in the seven-sentinel translation table) and asserts a generic 500 with no wrapped detail — not only the mapped-sentinel cases.
30	4. Read `internal/connector`'s test files for the specific no-cache-reuse assertion: two sequential `/identity` calls, second one re-fetching via `/auth`, asserted via a mock HTTP client call-count or distinct-token check — not just "no persistent storage exists" inferred from the absence of a cache field.
31	5. Report any gap found as a fix, not a new story — this is meant to close S9 in one pass given how much is already built.
32	
33	## Research team review
34	
35	**Desmond Okafor — claims check:** [pending]
36	
37	**Tobias Lindqvist — objection:** [pending]
38	
39	**Naomi Voss — ruling:** [pending]
40	

{
  "command": "cd /Users/warrenthompson/Source/LoginID && grep -n -i \"same.PR\\|same pull request\\|update.*fake\\|fake.*update\" 03-engineering-delivery/decisions/test-double-strategy.md\necho \"---search for PR template / CONTRIBUTING---\"\nfind . -iname \"CONTRIBUTING*\" -o -iname \"pull_request_template*\" 2>/dev/null | grep -v scratchpad\nfind /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check -iname \"CONTRIBUTING*\" -o -iname \"*pull_request_template*\" -o -ipath \"*.github/*\" 2>/dev/null"
}

11:1. **Interface drift is silent with hand-written fakes.** A new interface method still compiles against a stale fake, which silently zero-values it instead of failing a test that should catch the gap. Generated mocks fail loudly or leave a visibly regenerated stub. Marisol's own mitigation: enforce fake regeneration in the same PR as any interface change, as a review checklist item — makes drift a procedural risk, not a tooling one.
21:Adopted: any change to `Repository` or its three sub-interfaces must update the corresponding hand-written fake in the same PR — added as a stated review-checklist item for S2/S5, not left as an assumed discipline. This is the review-time equivalent of what a generated mock would catch automatically, at zero added dependency cost.
---search for PR template / CONTRIBUTING---
/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check/.github/workflows
/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check/.github/workflows/deploy.yml
/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check/.github/workflows/pr-check.yml
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && ls internal/connector/*_test.go\necho \"---\"\ngrep -n -i \"refetch\\|re-fetch\\|second.*identity\\|no.*cache\\|reuse\\|call.*count\\|CallCount\" internal/connector/*_test.go"
}

internal/connector/handlers_test.go
internal/connector/httpvendorclient_test.go
internal/connector/identitylimiter_test.go
internal/connector/stubvendorclient_test.go
---
internal/connector/handlers_test.go:247:// mostly successful calls ever would be. Reuses api.GrantLimiter (PR
internal/connector/httpvendorclient_test.go:29:// connection reuse.
internal/connector/httpvendorclient_test.go:54:		t.Fatalf("second FetchIdentity call: %v", err)
internal/connector/httpvendorclient_test.go:64:		t.Errorf("second request's Authorization = %q, want %q — must not inherit the first call's token via connection reuse", observedHeaders[1], "Bearer token-B")
internal/connector/identitylimiter_test.go:41:	// under the same caller (the "one valid seed account" case).
internal/connector/identitylimiter_test.go:195:	// pressure (reuse the same flood as the sibling test, cheaply, by
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "file_path": "/private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check/internal/connector/httpvendorclient_test.go",
  "offset": 1,
  "limit": 70
}

1	package connector
2	
3	import (
4		"context"
5		"encoding/json"
6		"net/http"
7		"net/http/httptest"
8		"sync"
9		"testing"
10		"time"
11	)
12	
13	func TestNewHTTPVendorClient_RejectsNonHTTPS(t *testing.T) {
14		if _, err := NewHTTPVendorClient("http://vendor.example.com", nil); err == nil {
15			t.Errorf("NewHTTPVendorClient accepted a plain http:// base URL, want an error (connector-security.md §2: TLS only)")
16		}
17		if _, err := NewHTTPVendorClient("not-a-url", nil); err == nil {
18			t.Errorf("NewHTTPVendorClient accepted a garbage base URL, want an error")
19		}
20	}
21	
22	// TestHTTPVendorClient_FetchIdentity_FreshAuthorizationHeaderPerRequest
23	// is attack-tree leaf 1's own named enforcement site (refinement/LT-41.md):
24	// two sequential calls through the SAME pooled *http.Client, each
25	// presenting a DIFFERENT vendor token, must each produce an outbound
26	// Authorization header matching ITS OWN token — never the previous
27	// call's, which a client that held a shared/default header (instead of
28	// building it fresh per call) could otherwise leak across requests via
29	// connection reuse.
30	func TestHTTPVendorClient_FetchIdentity_FreshAuthorizationHeaderPerRequest(t *testing.T) {
31		var mu sync.Mutex
32		var observedHeaders []string
33	
34		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
35			mu.Lock()
36			observedHeaders = append(observedHeaders, r.Header.Get("Authorization"))
37			mu.Unlock()
38			w.Header().Set("Content-Type", "application/json")
39			_ = json.NewEncoder(w).Encode(vendorIdentityResponse{Name: "ok"})
40		}))
41		defer srv.Close()
42	
43		// Construct directly (bypassing NewHTTPVendorClient's https-only
44		// check, which httptest.Server's plain-http URL would otherwise
45		// fail) — this file is in the same package, so it can set the
46		// unexported fields directly rather than needing a second,
47		// test-only constructor in non-test code.
48		client := &HTTPVendorClient{baseURL: srv.URL, httpClient: srv.Client()}
49	
50		if _, err := client.FetchIdentity(context.Background(), "token-A", "+15555550100", "Jane"); err != nil {
51			t.Fatalf("first FetchIdentity call: %v", err)
52		}
53		if _, err := client.FetchIdentity(context.Background(), "token-B", "+15555550100", "Jane"); err != nil {
54			t.Fatalf("second FetchIdentity call: %v", err)
55		}
56	
57		if len(observedHeaders) != 2 {
58			t.Fatalf("server observed %d requests, want 2", len(observedHeaders))
59		}
60		if observedHeaders[0] != "Bearer token-A" {
61			t.Errorf("first request's Authorization = %q, want %q", observedHeaders[0], "Bearer token-A")
62		}
63		if observedHeaders[1] != "Bearer token-B" {
64			t.Errorf("second request's Authorization = %q, want %q — must not inherit the first call's token via connection reuse", observedHeaders[1], "Bearer token-B")
65		}
66	}
67	
68	func TestHTTPVendorClient_Authenticate_SendsCredentialsAndReturnsToken(t *testing.T) {
69		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
70			var body vendorAuthRequest

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && grep -n \"func Test\" internal/connector/handlers_test.go"
}

35:func TestNewAuthHandler_Success(t *testing.T) {
64:func TestNewAuthHandler_VendorRejects_GenericFailure(t *testing.T) {
94:func TestNewAuthHandler_IdentityLimiter_WiredThroughCorrectly(t *testing.T) {
148:func TestNewIdentityHandler_ThreeFailureBranches_ContentIdenticalAndTimingClose(t *testing.T) {
213:func TestNewIdentityHandler_Success_NoFloorApplied(t *testing.T) {
256:func TestVendorCallLimiter_FailureRatioTripsBeforeVolume(t *testing.T) {
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /private/tmp/claude-501/-Users-warrenthompson-Source-LoginID-01-product-industry-research-design/9f72a7fe-5fe0-4320-96cc-449f87d8107b/scratchpad/main-check && sed -n '1,60p' internal/connector/handlers.go 2>/dev/null | head -80\necho \"---identity handler---\"\ngrep -n -A 30 \"func NewIdentityHandler\" internal/connector/handlers.go"
}

package connector

import (
	"context"
	"encoding/json"
	"io"
	"net"
	"net/http"
	"strings"
	"time"

	"loginid-takehome/internal/api"
)

// identityFailureFloor is /identity's uniform response-time floor across
// its three failure branches (no-token, bad-token, vendor-rejected) —
// Marcus Ilori's (02) ruling on Tobias Lindqvist's timing-oracle
// objection (refinement/LT-41.md), recorded in full in
// connector-security.md §4. ~100ms, well under any context.WithTimeout
// budget elsewhere in the chain (vendorCallTimeout is 10s) so it never
// competes with those deadlines. This narrows, but does not fully close,
// the gap between a local-only failure (microseconds) and a
// vendor-round-trip failure (tens-hundreds of ms) — full closure is an
// accepted non-goal per that ruling.
const identityFailureFloor = 100 * time.Millisecond

// identityErrorBody is the one JSON shape every /identity failure
// returns, regardless of which of the three branches produced it —
// content-identical by construction (a single writeIdentityFailure call
// site below), not by three call sites happening to independently agree.
type identityErrorBody struct {
	Error string `json:"error"`
}

// vendorLimiter is the interface these handlers depend on — satisfied
// directly by api.GrantLimiter (PR #30/#34's already-built component,
// reused here rather than rebuilt per LT-41's own non-goals: "this
// story's own in-process rate limiting is sufficient, matching the
// pattern already used for RateLimiter/TouchCounter/GrantLimiter").
// Declared locally so this package's own tests can supply a minimal fake
// satisfying only the calls actually made here, per
// decisions/test-double-strategy.md.
type vendorLimiter interface {
	Allow(ctx context.Context, clientID, sourceIP string) (bool, error)
	RecordFailure(ctx context.Context, clientID, sourceIP string)
	RecordSuccess(ctx context.Context, clientID, sourceIP string)
}

// Deps bundles NewAuthHandler/NewIdentityHandler's collaborators.
//
// IdentityLimiter is the second rate-limit dimension attack-tree leaf 5
// actually specifies ("per identity attempted, not just per client") —
// Limiter alone (keyed by calling-API-client sub + source IP) means one
// success anywhere resets that caller's whole consecutive-failure count,
// letting a compromised caller cycle through many stolen identities
// indefinitely (Tomasz Wrede's cold review, PR #40). May be nil in tests
// that don't exercise this dimension; NewConnectorRouter always
// constructs a real one.
type Deps struct {
	Vendor          VendorClient
---identity handler---
238:func NewIdentityHandler(deps Deps) http.HandlerFunc {
239-	return func(w http.ResponseWriter, r *http.Request) {
240-		start := time.Now()
241-		ctx := r.Context()
242-		ac, _ := api.AuthContextFromContext(ctx)
243-		sourceIP := sourceIPFrom(r)
244-
245-		allowed, err := deps.Limiter.Allow(ctx, ac.Sub, sourceIP)
246-		if err != nil {
247-			writeJSON(w, http.StatusInternalServerError, identityErrorBody{Error: "server_error"})
248-			return
249-		}
250-		if !allowed {
251-			// Not one of the three timing-oracle branches (it's an
252-			// overt, openly-disclosed 429, not a covert signal) — no
253-			// floor applied.
254-			writeJSON(w, http.StatusTooManyRequests, identityErrorBody{Error: "slow_down"})
255-			return
256-		}
257-
258-		var body identityRequestBody
259-		if err := json.NewDecoder(io.LimitReader(r.Body, 1<<16)).Decode(&body); err != nil {
260-			// A malformed body is a caller bug, not one of the three
261-			// named credential/token-validity branches — ordinary 400,
262-			// no floor.
263-			writeJSON(w, http.StatusBadRequest, identityErrorBody{Error: "invalid_request"})
264-			return
265-		}
266-
267-		// Second rate-limit dimension — per (caller, attempted
268-		// phone+name), not just per caller (attack-tree leaf 5, Tomasz
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design