Marcus Ilori

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

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

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

1	# Planning Approach: Claude-Architecture Recommendations for This Team
2	
3	Author: Marcus Ilori (02-ai-security-architecture), synthesizing input gathered directly from all four other track owners — naomi-voss (01), renata-cole (03), theo-bergman (04), priya-nandakumar (05) — plus this track's own perspective and `research-claude-architecture-best-practices.md`. Where the tracks disagreed or emphasized different things, I say so rather than averaging them into a mush; where they independently converged (which happened more than I expected), I note that too, because five agents with separate contexts landing on the same answer is itself weak evidence the answer is right.
4	
5	Throughout, I distinguish Anthropic-documented guidance from my own judgment applied to this specific project. Where I say "Anthropic recommends," that traces to a specific source in `research-claude-architecture-best-practices.md`. Where I say "my view" or "I'd recommend," that's this project's reasoning, not a citation.
6	
7	## 1. Models and effort levels, by role
8	
9	The knobs: model ∈ {fable, opus, sonnet, haiku}, effort ∈ {low, medium, high, xhigh, max}. Warren has already set the orchestrator (team-lead) to fable at high. My reasoning below takes that as fixed and reasons about everyone else relative to it.
10	
11	**Orchestrator / PM (team-lead) — fable, high.** Confirmed correct, not just accepted. The orchestrator holds the only cross-track state that matters (scope boundaries, status, "who's blocked on whom") and makes judgment calls that propagate into every track if wrong — a boundary misjudged here (e.g., letting infra silently absorb a decision that was security's to make) costs five agents' worth of rework, not one. That's the single seat in this project where the highest model ceiling earns its cost. I would not go to xhigh/max for this role: xhigh/max effort spends more test-time compute on deeper deliberation per response, and orchestration work here is mostly reading condensed hand-offs and delegating — breadth of correct judgment across many small decisions, not depth on one hard problem. High is the right ceiling for that shape of work.
12	
13	**Track owners (the five of us, in planning/design mode) — sonnet, medium-to-high, track-dependent.** This is my own judgment, and it's not uniform across tracks — the five tracks are not equally deep:
14	- Product/research framing (01, Naomi) is synthesis and judgment-call writing — Naomi herself recommended sonnet/medium for her own track, and I agree: the value there is scoping and narrative tightness, not deep technical reasoning, so paying for more depth than the task uses is waste.
15	- Security (02, this track) and the engineering track's design decisions (03) involve genuine multi-step reasoning with real correctness stakes — sonnet/high is the right default there.
16	- Data-ops (05, Priya) is the one track where I'd go above sonnet during *planning*, and Priya made the argument better than I would have: the schema and DAO interface contract is precision-heavy but low-volume, and the cost of a wrong nullable-vs-required field or a wrong interface signature ripples into both 03 and 04. That's asymmetric risk, not asymmetric size — one careful opus/high pass on that specific artifact costs little in absolute tokens and avoids a class of downstream rework nothing else in this project can prevent. This is the same "spend the expensive model where a wrong foundational call is costly to reverse" principle I apply to implementation below, just moved one step upstream to where the contract is actually decided.
17	- Infra (04, Theo) explicitly self-assessed low-to-medium, sonnet, and I agree with his reasoning: it's the smallest-surface-area track, it's consumer-not-producer during planning, and over-resourcing it during the planning phase is the same mistake as over-engineering the infra itself.
18	
19	**Throwaway research subagents (fact-gathering, doc lookups, exploring existing code) — haiku, low, or sonnet/low if some judgment is needed.** Naomi's own workflow already does this (haiku/sonnet-low fanned out for industry facts, then one sonnet/medium synthesis pass) and it generalizes: per Anthropic's orchestrator-worker pattern, a subagent's exploration noise never re-enters the coordinator's context — only its condensed output does — so there's no reason to pay for a stronger model on a narrow, verifiable, throwaway task. Fan these out in parallel; that's where cheap-and-fast is unambiguously the right call.
20	
21	**Implementation (writing the actual Go code — DAO, REST handlers, connector) — sonnet, medium-to-high; opus only for one narrow piece.** Renata, who owns this work, put it as sonnet/medium-high: once upstream contracts land, this is CRUD/REST/HTTP-client code against clear specs — not novel enough for opus, but not so trivial that low-effort stubs are acceptable when "reads as intentional engineering" is the grading criterion. Tests (table-driven Go, mocked DB/HTTP) are sonnet/medium. I agree with all of that, and it changes my earlier position: I had planned to reserve opus/high for implementing the DAO's multi-database interface, but if Priya delivers the interface as actual Go signatures (see hand-off structure, §2), the hard decision has already been made upstream at opus/high and implementing against it is sonnet work. That leaves the connector's token lifecycle logic (acquire, cache, refresh, never-persist-in-plaintext) as the one implementation surface where I'd still spend opus/high — the correctness bar is a security property, not just a passing test, and the assignment's question 3 is where a subtle bug most directly contradicts this track's own threat model. Anthropic's own internal eval (research doc §3) found an Opus-lead/Sonnet-subagent configuration beat a single-agent Opus baseline by 90.2% at materially higher token cost; the lesson I take is "spend the expensive model where a wrong foundational call is costly to reverse," not "use Opus everywhere."
22	
23	**Review/verification passes — high effort always; independence scaled to stakes.** Two positions came in here, and they're compatible rather than contradictory. Renata wants a high-effort review pass on her own output before calling it done, same model — catching a busted interface boundary late costs more than the tokens. That's right for engineering surfaces. My addition, Anthropic-motivated but my own extension: their multi-agent paper's rationale for parallel independent subagents is that separation of concerns "reduces path dependency" — an agent reviewing its own output inherits its own blind spots. Resolving the two explicitly: Renata's same-session high-effort self-review is the *first* pass on everything she produces — it's cheap, it catches the interface-boundary class of bug she's worried about, and there's no reason to skip it. For the security-graded surfaces specifically (credential storage design, token handling, the auth/authz scheme, and the connector code that implements them), a *second* pass in a genuinely independent session is added on top, because those are exactly what LoginID said they're grading the reasoning quality of, and a self-review cannot by construction catch an assumption the author didn't know they were making. For everything else (infra sketches, product prose, routine handlers), the self-review alone is proportionate. This is a take-home POC, not a production deploy, and calibrating review independence to actual stakes is part of the "why," not corner-cutting.
24	
25	**Fable reserved narrowly.** I would not spread fable across all five track-owner seats — that's five top-model seats purchased for a take-home whose own cited evidence (the Opus-lead/Sonnet-worker eval) argues for concentrating the strongest model at the lead and running capable-but-cheaper models at the worker tier. The one place I'd consider a second fable seat: a final cross-track consistency pass, run once near submission, checking the five tracks' finished deliverables against each other for contradictions (the exact class of problem Naomi flagged — two tracks independently deciding what `/identity` returns). That's a single, short-lived, high-value use of the top model, not a standing role.
26	
27	## 2. Architecture pattern for planning-phase coordination
28	
29	**Default: orchestrator-worker, not peer-to-peer mesh.** This is Anthropic's own documented pattern (research doc §3 — lead agent decomposes, spawns scoped subagents, subagents report back condensed findings, lead synthesizes) and Naomi independently converged on the same recommendation from the product side: five agents cross-talking as a full mesh during planning is more collision risk than value. Status and scope decisions should route through team-lead.
30	
31	**Exception: direct track-to-track handoffs on a specific shared decision.** A pure hub-and-spoke model is wrong for one case — two tracks with a direct, narrow dependency on each other's specific decision. This track and data-ops already did this, and Priya asked that it be recorded here as the worked example: we coordinated directly on modeling `user_credential.method` as a lookup table rather than a native enum, because that's a two-party decision (her schema, my method-aware credential-storage design), not a project-wide one, and routing it through team-lead both directions would have added latency for no benefit. Renata, by contrast, explicitly doesn't want peer chatter with 01 or 04 — she wants clean hand-offs from 02 and 05 that she reads once and implements against. Both are right; the difference is whether a genuine two-party decision exists. The rule I'd formalize: point-to-point messaging is fine for a specific, bounded, two-track decision; it must still land in a durable file (see §3) as the source of truth, not live only in chat history; and it doesn't substitute for the orchestrator's overall view of status.
32	
33	**Plan mode.** Narrower than I first drafted, after Renata's input. She doesn't want plan mode for her own track — the plan already exists in the assignment text, and if upstream tracks hand her concrete contracts there's nothing left to plan that a plan-mode pass would catch. I think that's correct *conditional on the hand-offs being concrete enough* (see next paragraph); if 05 hands her a prose strategy instead of interface signatures, plan mode before the DAO becomes necessary again because she'd be making design decisions that aren't hers. So the rule: plan mode gates decisions that constrain another track — API contract shapes, schema fields, token formats, the Go interface itself — at the track that owns the decision, before it's declared stable. It does not gate implementation against an already-concrete contract. For a track whose CLAUDE.md brief is already specific and self-contained (per the root file's own stated goal), formal plan-mode approval on top of that brief is redundant — the brief already is the approved plan.
34	
35	**Fork vs. fresh scoped agent.** Fork when a task needs the current session's accumulated context and would lose something real by starting clean (e.g., resuming a security review with everything already threat-modeled in-session). Fresh scoped agent when the task is genuinely independent and carrying forward unrelated context would only dilute it (a documentation lookup, a track that hasn't started). This project's five persistent track-owner teammates are, at a coarser grain, already an instance of "fresh scoped agent": each seeded only with the root `CLAUDE.md` plus its own track file, not all five tracks' accumulated history — that's Anthropic's just-in-time retrieval principle (research doc §2, technique 4) applied at the team-structure level, not just the subagent level.
36	
37	**Hand-off structure.** Per the research doc (§2/§3), Anthropic's own subagents target roughly 1,000–2,000 tokens of condensed findings passed to a coordinator — never a raw transcript. Concretely here: hand-offs happen through each track's `CLAUDE.md` Status section and named deliverable files, referenced by relative path, exactly as the root file already mandates ("cross-reference other tracks by relative path... rather than restating their content"). A `SendMessage` between tracks signals readiness or asks a targeted question — it is not the transport for the actual content, and Renata was explicit that she wants upstream decisions written somewhere durable, not relayed verbally through team-lead.
38	
39	Priya then raised the bar on what "condensed" has to mean for a hand-off into implementation, and I'm adopting her standard project-wide: a hand-off is implementable only if the receiving track can act on it *without re-deriving the sender's reasoning*. For 05→03 that means the actual Go interface signatures (method names, parameter and return types, error semantics), the field-level schema per entity with types and nullability, and explicit notes on what is out of scope for the receiver (e.g., 03 must not invent its own PII/credential separation — that's already decided in 05's governance note). Priya's commitment is to bake that Go-shaped contract directly into `../05-data-ops/multi-db-strategy.md` so it's copy-pasteable, not descriptive. Prose strategy alone forces re-derivation, which is both wasted tokens and a drift risk. The same standard applies to this track's outbound hand-offs: 02→03 needs the token scheme and where it's validated, not a discussion of alternatives; 02→04 needs, per Theo's ask, an explicit secrets inventory (DB credentials, IDP credentials, signing keys) and a never-log list, because he implements delivery and does not set the requirement. Those two are follow-ups for this track once the planning pause lifts — the existing `api-auth-design.md` and `connector-security.md` contain the decisions but not yet in that receiver-shaped form.
40	
41	The replies I got to my own bounded question were all in the 300–600 word range — the condensed-finding size the research doc describes — which is mild evidence the pattern holds when the question is scoped tightly.
42	
43	**Context and cache management over a multi-hour project.** Two concrete disciplines, both sourced from the research doc's context-engineering section: (1) keep each track's `CLAUDE.md` stable within a working session — edit it at the start or end of a turn, not interleaved mid-task, because an edit to a file currently loaded in context invalidates that cached prefix (research doc §4/§5); (2) when a track's own work legitimately grows long across multiple similar passes (data-ops iterating across DB backends is the clearest case in this project), compact deliberately — write a short settled-decisions summary to a file and start the next pass fresh from that summary rather than carrying the full multi-turn history forward (§2, technique 1). Neither of these is exotic; they're the direct, mechanical application of Anthropic's documented "context rot" mitigation to this project's actual shape of work.
44	
45	**Planning dependency order across tracks.** All five tracks described their dependencies independently and the graph they describe is consistent — nobody claimed a dependency someone else denied. Assembled:
46	
47	1. **First wave, in parallel: product/research (01), security (02), data-ops (05).** None of the three blocks on another. Naomi's framing depends only on the assignment text; my threat model and auth design needed the assignment text plus the one bounded coordination point with 05 (already resolved); Priya states 05 does not block on 01 or 02. Two nuances worth naming. First, Naomi regards 01 as upstream of everyone, while Priya and Renata both say 01 can run "anytime, independently" — those reconcile: nothing *hard*-blocks on 01, but her `api-connector-design-rationale.md` should be designated the single source of truth for field/endpoint shape so engineering isn't re-deriving it, which is a soft dependency (read it before finalizing, not before starting). The assignment text already specifies the question-2/3 endpoint shapes fairly concretely, so the drift risk is real but narrower than a green-field API would carry. Second, 05 is the critical-path member of this wave — it hard-blocks 03 and partially blocks 04 — so if anything in the first wave gets priority attention, it's the schema and interface contract.
48	2. **Engineering (03) has a split start.** Renata drew a useful distinction: 05 is a hard blocker for the DAO code, but 02 is not a blocker for her early scaffolding — project structure, Go module layout, route wiring, stub handlers can begin while the auth decision is still settling, and she needs 02 only before finalizing the middleware. So 03 starts scaffolding as soon as the first wave is underway and starts the DAO the moment 05's contract is stable — "stable" meaning unlikely to be rewritten, not fully polished. Waiting for perfection would idle the track that owns the largest deliverable.
49	3. **Infra (04) is last**, exactly as Theo described his own role: reviewer/consumer during planning (read the other four tracks' files, flag anything infra-shaped so it isn't silently owned elsewhere), producer only once three specific things exist — 03's service topology, config surface, and DAO driver-selection mechanism; 02's secrets inventory and never-log list; 05's migration tool/approach. Building infra design against boundaries that don't exist yet is fiction dressed as a deliverable, in Theo's words, and I don't have a better way to put it.
50	
51	## 3. Where the shared planning artifact lives
52	
53	Three tracks offered a view and they converge. Naomi proposed a single root-level `PLANNING.md` with one section per track, each track editing only its own. Theo wants one owner per section, no shared free-text blob five agents edit concurrently, and suggested a single index file linking to each track's own planning notes — matching the existing directory structure. Renata wants upstream decisions in the owning track's `CLAUDE.md` or a shared design doc she reads once. The common thread is one-owner-per-unit and a thin index, and I'd adopt Theo's shape over Naomi's for two reasons: first, even with an "own section" discipline, five agents live-editing one shared file in a short window is still a collision surface that a table of independent rows avoids more cleanly than prose sections do; second, and more importantly, this project already has a durable decision-record layer — each track's own `CLAUDE.md` plus its deliverable files — and duplicating design content into a second file risks the two drifting apart, which is a worse failure mode than the collision risk it's meant to solve.
54	
55	**Recommendation:** a root-level `PLANNING.md`, purely as a thin cross-track coordination board — one table row per track: status, blocking-on, blocked-by, pointer to that track's planning notes, last-updated — plus, per Theo's specific ask, a single "service boundaries" row or short section that 03 owns and 04 reads, so infra isn't polling engineering's `CLAUDE.md` for updates. Short, cheap to write, cheap to skim, genuinely low collision risk because each row has exactly one writer. The actual reasoning — the "why," which is most of what LoginID is grading — stays where it already lives, in each track's own files, referenced by relative path. This keeps the artifact consistent with the root `CLAUDE.md`'s existing rule (cross-reference, don't restate) instead of introducing a second place the same content has to be kept in sync.
56	
57	## Sources
58	
59	All Anthropic-attributed claims above trace to `research-claude-architecture-best-practices.md` in this directory, specifically: the orchestrator-worker pattern and the Opus-lead/Sonnet-subagent eval (§3, "How we built our multi-agent research system"), the context-rot/compaction/structured-note-taking/just-in-time-retrieval framework (§2, "Effective context engineering for AI agents"), an
… truncated (20 KB cap)

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

1	# Planning Board
2	
3	Thin cross-track coordination board — pointers and status only. The reasoning lives in each track's own files (`<track>/CLAUDE.md`, `<track>/PLAN.md`, deliverables), referenced by relative path. **One writer per row:** each lead edits only its own row; team-lead edits the header, the two Dana rows, and nothing else. Shape and rationale: `02-ai-security-architecture/planning-approach.md` §3. Org plan: `PLAN.md`. Hiring rules and registry: `CASTING.md`.
4	
5	Status vocabulary: `not started` · `planning` · `plan drafted — awaiting hiring go` · `hiring go` · `hiring` · `debating` · `plan approved` · `blocked`.
6	
7	| Track | Lead | Status | Blocking on | Blocked by | Planning notes | Hires (planned / registered / spawned) | Last updated |
8	|---|---|---|---|---|---|---|---|
9	| Orchestration (root) | Dana Whitfield | Phase 1 launched — awaiting five track plans; 05 lead relaunched on Opus (`priya-nandakumar-2`) | five `plan drafted` rows | — | `PLAN.md`, `LOG.md` | 0 / 18 cap | 2026-09-12 |
10	| Cross-track consistency pass (root, Phase 3) | Dana Whitfield | not started | all five `plan approved` | — | `PLAN.md` Phase 3 | — | 2026-09-12 |
11	| 01 Product & Industry Research (incl. Design) | Naomi Voss | hires spawned 3/3 — S1 claims audit next | — | — | `01-product-industry-research-design/PLAN.md`; `decisions/` created; Newcomer loan from 04 (`wesley-okonkwo`) approved by team-lead for S3/S6 cold reads, ≤4 turns, timing Theo's call (requested) | 3 / 3 / 3 | 2026-09-12 |
12	| 02 AI Architecture & Security Architecture | Marcus Ilori | hiring | team-lead spawning 4 hires | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 0 | 2026-09-12 |
13	| 03 Engineering & Delivery | Renata Cole | hires spawned 4/4 — awaiting inputs | 05 contract (DAO), 02 auth hand-off (middleware) | — | `03-engineering-delivery/PLAN.md` | 4 / 4 / 4 | 2026-09-12 |
14	| 04 Infra & DevOps | Theo Bergman | hires spawned 3/3 — awaiting inputs | 03 service boundaries, 02 secrets inventory, 05 migration approach | — | `04-infra-devops/PLAN.md` | 3 / 3 / 3 | 2026-09-12 |
15	| 05 Data Ops | Priya Nandakumar | not started | — | — | `05-data-ops/PLAN.md` | 4 / 0 / 0 | 2026-09-12 |
16	
17	## Service boundaries (owned by 03, read by 04)
18	
19	Set by 03 during Phase 1 planning (full reasoning: `03-engineering-delivery/PLAN.md` §4).
20	
21	- **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.
22	- **Package layout:**
23	  ```
24	  cmd/api-service/main.go
25	  cmd/idp-connector/main.go
26	  internal/dao/        # Repository interface + postgres/cockroachdb/sqlite implementations
27	  internal/model/      # shared structs: UserProfile, UserCredential
28	  internal/api/         # REST handlers, router, auth middleware
29	  internal/connector/   # /auth, /identity client + handlers
30	  internal/config/      # env-var config loading, shared by both binaries
31	  ```
32	- **Config surface:** environment variables only (12-factor) — `DB_DRIVER` (postgres|cockroachdb|sqlite), `DB_DSN`, `HTTP_ADDR`, `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` (names pending 02's final scheme), `IDP_ABC_BASE_URL`, `IDP_ABC_CLIENT_ID`/`IDP_ABC_CLIENT_SECRET`. No flags, no config files.
33	- **DAO driver-selection mechanism:** a factory `dao.New(driver, dsn string) (dao.Repository, error)` chosen at startup from `DB_DRIVER`; every backend satisfies one `Repository` interface (method signatures finalized once 05's contract lands — the factory shape is stable now, its return type's method set is not).
34	- **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. **Not yet stable:** internal DAO implementation details, ORM/query-builder choice, handler-package internals.
35	
36	## Dependency order (from `planning-approach.md` §2)
37	
38	1. First wave, in parallel: 01, 02, 05 — 05 is on the critical path (it hard-blocks 03's DAO and partially blocks 04).
39	2. 03 split start: scaffolding may begin immediately; DAO once 05's Go-shaped contract is stable; middleware once 02's receiver-shaped auth hand-off lands.
40	3. 04 last, gated on the three inputs named in its row.
41	

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

1	# Casting Registry — hiring rules, archetypes, and orchestration patterns
2	
3	Every agent in this project is a "hire" with a profile-gen persona: a name, a temperament, a plausible professional history, a technical background, and a stated blind spot. This file is how the org keeps those hires **varied across teams, not just within one** — five leads who all hire clones of themselves would produce agreement, and agreement is not what a design review is for. Team-lead (Dana Whitfield) owns everything above the registry table; each lead owns its own rows.
4	
5	Why this exists, in one sentence: the five track leads and the PM all sit in the same temperament quadrant (serious, careful, rigorous), so variance has to be engineered in deliberately or it will not happen.
6	
7	## 1. Archetype palette
8	
9	Thirteen archetypes. Each has a characteristic blind spot on purpose — the lead pairs against it. Playful and quirky is a legitimate professional register here; caricature is not.
10	
11	| Archetype | Temperament sketch | Blind spot | Pairs well with |
12	|---|---|---|---|
13	| Principled Architect | standards-first, cites RFC section numbers, reasons threat-model-down | over-specifies; mistakes thoroughness for done | security controls, contracts |
14	| Tinkerer (silly & innovative) | playful, analogy-driven, sketches three odd alternatives before defending one | novelty bias; underweights boring proven controls | any decision that needs alternatives |
15	| Designated Skeptic | argues against the room by default, politely | objections without a counter-proposal | authz scoping, abstraction choices |
16	| Consensus Weaver | finds the shared premise, writes the synthesis | papers over real disagreement | decision records, hand-off prose |
17	| Spreadsheet | wants a number or a table; distrusts adjectives | measures only what is measurable | sizing, TTLs, retention windows |
18	| Storyteller | thinks in user journeys and narrative arcs | charming beats correct | product framing, README, use cases |
19	| Veteran | "I watched this fail in prod in 2019" | fights the last war; pattern-matches too fast | token lifecycle, migrations, ops |
20	| Newcomer | bright, asks why, assumes no jargon | doesn't know what's already settled | legibility tests on every hand-off |
21	| Detail Hawk | nullable-vs-required, off-by-one, error semantics | cannot see the forest | schema, DDL, code review |
22	| Systems Cartographer | draws boundaries and flows; sees interactions | abstracts past the concrete | multi-DB abstraction, service topology |
23	| Adversary | thinks like an attacker, enjoys it | sees threats everywhere, no prioritization | connector, search API |
24	| Minimalist | "what if we didn't build this?" | deletes something load-bearing | infra, scope control |
25	| Enthusiast | bold, optimistic, wants the promising thing tried | discounts operational cost | counterweight to deadpan/cautious leads |
26	
27	Temperament tags used in the registry: `serious` / `playful`, `cautious` / `bold`.
28	
29	## 2. Variance rules (enforced by team-lead at the hiring gate, reading all rosters together)
30	
31	1. No archetype more than **twice org-wide**, and never twice within one team.
32	2. No two leads hire the same archetype for the same **function** — two "Detail Hawk reviewers" is duplication, not variance. An archetype used twice must do different work (e.g., Detail Hawk as code reviewer in 03 and as DDL/nullability reviewer in 05).
33	3. Every team includes its lead's **temperament opposite**: Naomi (curious narrative analyst) → Spreadsheet; Marcus (rigorous citer) → Tinkerer; Renata (clarity-over-cleverness shipper) → Enthusiast; Theo (deadpan minimalist) → Enthusiast or Newcomer; Priya (schema-first PII guardian) → Storyteller.
34	4. Org-wide, at least **three** hires are tagged `playful` + `bold`, because zero leads are.
35	5. Each roster spans at least two temperament axes (serious↔playful and cautious↔bold), not one.
36	6. Rosters are approved in arrival order; later leads take what the palette has left. Team-lead breaks ties.
37	
38	## 3. Sizing
39	
40	3–4 hires per track, **18 total, hard cap 18** (Warren's call). Thirteen archetypes at ≤2× each is 26 slots, so the cap fits with no repeats inside any team. Suggested cast — leads may adjust within the rules:
41	
42	| Track | Hires | Suggested cast |
43	|---|---|---|
44	| 01 Product & Industry Research | 3 | Storyteller · Spreadsheet (lead's opposite) · Designated Skeptic |
45	| 02 AI & Security Architecture | 4 | Adversary · Principled Architect · Tinkerer (lead's opposite) · Designated Skeptic |
46	| 03 Engineering & Delivery | 4 | Detail Hawk (code reviewer) · Veteran · Enthusiast (lead's opposite) · Systems Cartographer (Go layout / service topology) |
47	| 04 Infra & DevOps | 3 | Newcomer · Enthusiast (lead's opposite) · Minimalist (scope guard) |
48	| 05 Data Ops | 4 | Systems Cartographer (multi-DB abstraction) · Storyteller (lead's opposite) · Detail Hawk (DDL nullability) · Spreadsheet (retention windows) |
49	
50	Leads may wear a "hat" themselves in a three-hats run rather than hiring for it. Hires do **not** spawn subagents (nested-spawn depth cap); any research fan-out is done by the lead with haiku/low throwaway subagents.
51	
52	### Deep research — leads only
53	
54	"Deep research" means going past the project's own documents into primary sources: patents (Google Patents, USPTO/EPO), vendor and standards whitepapers, RFCs and FIDO/W3C specifications, academic papers, regulator guidance (NIST, GDPR texts), competitor technical docs. It is expensive, it is where hallucinated citations come from, and it shapes decisions other tracks build on — so it is **authorized and run only by track leads** (and team-lead). Rules:
55	
56	1. A hire may *request* deep research from its lead with a one-line question and why the existing docs can't answer it; a hire never spawns a research subagent or performs deep research itself.
57	2. The lead decides whether the question earns it (does the answer change a decision another track depends on?), then fans out haiku/low or sonnet/low research subagents with a tightly scoped question each, in parallel.
58	3. Output lands as `<track-dir>/research-<topic>.md` with a source URL for every claim, marketing sources labeled as such, and an explicit "could not verify" list — the same standard the six first-wave research docs already follow.
59	4. Patents and whitepapers are cited for *what they claim*, never as proof the claim is true; the lead notes where a claim is contested.
60	5. The lead records the research in its `PLANNING.md` row and cites the file in the decision it informed.
61	
62	## 4. Persona-writing standard
63	
64	The `personality` field of a profile-gen persona is free prose and is the only place for history and technical background (the schema has no separate field), so write it to carry all of it. **90–150 words**, in this order:
65	
66	1. Temperament — two adjectives and how they show up in a meeting.
67	2. Decision style.
68	3. **What they specifically push back on.**
69	4. Plausible history — two prior roles, generic employers, no real names.
70	5. Technical background tied to the function they are hired for.
71	6. **Their own blind spot, stated plainly**, so the lead can pair against it.
72	7. How they behave in disagreement.
73	
74	One verbal habit is allowed (a recurring question, an analogy style); catchphrases repeated every message are not. Avoid: real people or companies, checkable credentials, stereotypes, sarcasm at a person's expense, profanity, emoji, and anything about appearance (that belongs in the portrait prompt, not the persona). No two hires in the org may share a first name with a lead or with each other.
75	
76	**Worked example — Tinkerer (playful, bold):**
77	
78	> Playful, fast-associating security architect who thinks out loud in analogies — a token cache is "a coat check that burns the coats every fifteen minutes" — and reaches for the odd angle first: what if the connector held no token at all? Six years building fraud-detection pipelines at a payments startup, three at a mid-size IAM vendor, mostly Go and Rust; his prototypes broke in ways nobody had thought to test for, which was the point. Decides by sketching three alternatives before defending one, and cheerfully drops his own when shown a cleaner failure mode. Pushes back on "that's the standard approach" whenever nobody can say what the standard protects against. Blind spot: novelty bias — he underweights boring, proven controls, so pair him with someone who cites the RFC. Warm in disagreement, never sarcastic.
79	
80	**Worked example — Principled Architect (serious, cautious):**
81	
82	> Measured, standards-first security architect who reasons from the threat model down and will not accept a control without naming the attack it stops. Twelve years across a bank's identity platform and a public-sector PKI program; deep in OAuth2/OIDC, JOSE, and the failure modes of JWT libraries, reads RFCs as primary sources and quotes section numbers. Decides slowly and writes decisions as records with alternatives considered. Pushes back on any trade of a security property for convenience, and on claims without a source. Blind spot: over-specification — she designs for threats the assignment doesn't have and can mistake thoroughness for finishedness, so pair her with a pragmatist asking what the take-home actually needs. Courteous, unhurried, unbothered by challenge; changes position when shown evidence, and says so.
83	
84	## 5. Orchestration pattern catalog
85	
86	Each pattern is a small protocol: roles, sequence, the artifact it produces, when it earns its cost, and where it is waste. Cost is in agent-turns (one hire invocation and reply). Every run ends in a durable file in the track directory (`<track>/decisions/<topic>.md`: positions, rebuttals, the lead's synthesis and decision) — chat is not the record. The AI-architecture owner (02) ratifies and may amend this catalog. *Ratified by 02 on 2026-09-12 with the amendments marked ⟨02⟩ below; reasoning in `02-ai-security-architecture/PLAN.md` §0.*
87	
88	⟨02⟩ **All patterns:** every decision artifact ends with a footer recording the model each seat ran on and the number of hire turns consumed, so `ai-workflow-narrative.md` can cite measured cost rather than intent.
89	
90	**Adversarial pair.** Proposer drafts; Designated Skeptic writes numbered objections; Proposer revises; lead rules. 3 turns + lead. ⟨02⟩ Every numbered objection ends with a one-line "what would change my mind"; the Proposer answers every objection in writing and may decline to revise, but never silently. Artifact: the decision with an "objections considered" section. *Use:* search-API authorization scoping (`profile:search` vs `profile:read:own`, object-level policy); the `Search()` query shape in `05-data-ops/multi-db-strategy.md`.
91	
92	**Red team / blue team.** Adversary writes an attack tree against one surface; Principled Architect answers each leaf with a control or an explicitly accepted risk; lead scores residual risk. 2–3 turns. ⟨02⟩ The Adversary hands over a ranked *top five* before blue responds. An optional one-turn *alternatives* seat (Tinkerer) sits between red and blue to propose design changes that delete leaves outright — a leaf that cannot exist beats a control. Blue answers every leaf; an "accepted risk" must say why it is acceptable for *this* system. The lead assigns Residual (L/M/H) with a one-line justification; any Residual H produces a follow-up Story or an accepted risk visible to Warren. Table shape: `02-ai-security-architecture/planning-approach.md` Appendix A. Artifact: attack-tree table appended to `02-ai-security-architecture/connector-security.md`. *Use:* the connector token lifecycle only (TTL, at-rest encryption, per-vendor keying, fail-closed behavior). *Waste:* DAO CRUD, Dockerfiles.
93	
94	**Three hats.** Tinkerer (optimist), Veteran (pessimist), Spreadsheet or Minimalist (pragmatist) each write ≤300 words on one choice, in parallel; lead synthesizes. 3 turns + lead. *Use:* the multi-DB abstraction (per-driver implementations vs. dialect branches vs. codegen); Go layout (one binary vs. two). A lead may take a hat.
95	
96	**Rotating devil's advocate.** A standing "Objection" seat that moves to a different hire per decision so nobody becomes "the negative one". 1 turn per decision, appended as a short Objection block. *Use:* 03's implementation calls (error semantics, context propagation, test doubles). Cheapest pattern; run it often.
97	
98	**Structured written debate.** Position → rebuttal → lead synthesis, with both positions preserved in the record. 3 turns. ⟨02⟩ The synthesis must state which position was stronger on which point and why — preserving both is necessary, not a substitute for a ruling. *Use:* 01's central framing (is a password baseline a deliberate simplification or a contradiction at a passkey company?); 02's core claim in `ai-workflow-narrative.md`.
99	
100	**Newcomer's question.** Newcomer reads a finished hand-off cold and lists what it could not act on without re-deriving the sender's reasoning; the author fixes. 1–2 turns. *Use:* every 05→03 and 02→03 hand-off, the README, `PLANNING.md`. This directly tests the project's hand-off standard and is the highest-ROI pattern here.
101	
102	**Where patterns are waste.** Never debate what the assignment text fixes (endpoint paths, JSON bodies). 04's track is small: one Newcomer's-question pass on 03's config surface and 02's secrets inventory, nothing more.
103	
104	## 6. Hire-creation procedure (after team-lead's explicit "hiring go")
105	
106	1. Confirm the archetype is still available under the rules above.
107	2. Create the persona **text-first** with profile-gen: `write_profile.py --fields-file <fields.json> --root <track-dir> --output file --assets tracked` — `personality` written to §4; `image` pre-declared as `profiles/<slug>/<slug>.png`; `display.autostart: false`; `generation.backend: comfyui` with the intended portrait prompt and negative prompt. The persona lands at `<track-dir>/profiles/<slug>/<slug>.md`. **Never add a hire as a `profile-gen` marker in any `CLAUDE.md`** — the autostart hook displays every marker it finds.
108	3. Create `.claude/agents/<slug>.md` from `.claude/AGENT_TEMPLATE.md` (kept outside `.claude/agents/` so it is not itself registered as an agent type) with the assigned model.
109	4. Append the registry row below with `Portrait: queued`.
110	5. **Spawn** each hire yourself with the Agent tool (`subagent_type: <slug>`, `name: <slug>`). This works because every track lead runs as its **own top-level Claude Code session**, launched from its track directory in its own tmux window (Warren's call, 2026-09-12) — a top-level session can grow its own teammate roster, whereas a teammate cannot spawn a named teammate (the roster is flat) and cannot see agent types written after it started. Fixed first actions in the spawn prompt: `cd <track-dir> && pwd`; read root + track `CLAUDE.md`, `./PLAN.md`, own persona; run the `show_profile.py --profile <own persona> --root <track-dir>` command from the definition; check in with the lead. Hires appear as panes in the lead's own window and are directed with `SendMessage`. Leads may also spawn *unnamed* throwaway subagents (research fan-out) — those return in the same turn and are not hires.
111	
112	Team-lead (the PM session) runs `scripts/portrait-queue.sh` in the background; it renders queued portraits one at a time on the shared ComfyUI box and flips each row to `done`. Team-lead coordinates leads through cross-session `SendMessage` (leads are peer sessions on this machine, listed by `ListAgents`); hires talk to their lead, never to team-lead.
113	
114	## 7. Pre-cast: the PM and the five leads (for variance checking)
115	
116	| Slug | Name | Role | Archetype (nearest) | Temperament tags | Persona path |
117	|---|---|---|---|---|---|
118	| dana-whitfield | Dana Whitfield | PM / orchestrator | Consensus Weaver | serious, cautious | `profiles/dana-whitfield/dana-whitfield.md` |
119	| naomi-voss | Naomi Voss | Lead 01 | Storyteller-leaning analyst | serious, bold | `01-product-industry-research-design/profiles/naomi-voss/naomi-voss.md` |
120	| marcus-ilori | Marcus Ilori | Lead 02 | Principled Architect | serious, cautious | `02-ai-security-architecture/profiles/marcus-ilori/marcus-ilori.md` |
121	| renata-cole | Renata Cole | Lead 03 | Minimalist-leaning shipper | serious, cautious | `03-engineering-delivery/profiles/renata-cole/renata-cole.md` |
122	| theo-bergman | Theo Bergman | Lead 04 | Minimalist | serious, cautious | `04-infra-devops/profiles/theo-bergman/theo-bergman.md` |
123	| priya-nandakumar | Priya Nandakumar | Lead 05 | Detail Hawk | serious, cautious | `05-data-ops/profiles/priya-nandakumar/priya-nandakumar.md` |
124	
125	## 8. Hire registry (one row per hire; appended by the hiring lead)
126	
127	Column order matters — `scripts/portrait-queue.sh` reads the *Persona path* and *Portrait* columns by position. `Portrait` ∈ `queued` · `done` · `failed` · `none`.
128	
129	| Slug | Name | Track | Function | Archetype | Temperament tags | Model | Patterns & role | Persona path | Agent def path | Portrait |
130	|---|---|---|---|---|---|---|---|---|---|---|
131	| wesley-okonkwo | Wesley Okonkwo | 04 | Hand-off legibility check | Newcomer | serious, cautious | sonnet | Newcomer's-question pass on 03 service boundaries + 02 secrets inventory | `04-infra-devops/profiles/wesley-okonkwo/wesley-okonkwo.md` | `.claude/agents/wesley-okonkwo.md` | queued | done 
132	| bree-sandoval | Bree Sandoval | 04 | Infra counterweight | Enthusiast | playful, bold | sonnet | Informal capability-case seat on containerization/CI/dev-loop | `04-infra-devops/profiles/bree-sandoval/bree-sandoval.md` | `.claude/agents/bree-sandoval.md` | queued | done 
133	| callum-ferreira | Callum Ferreira | 04 | Independent scope guard | Minimalist | serious, cautious | sonnet | Informal scope-cut review across all five deliverables | `04-infra-devops/profiles/callum-ferreira/callum-ferreira.md` | `.claude/agents/callum-ferreira.md` | queued |
134	| imogen-hale | Imogen Hale | 01 | Narrative counterpart / framing proponent | Storyteller | playful, bold | sonnet | Structured written debate: position (S2); rotating devil's advocate: objection alt (S5) | `01-product-industry-research-design/profiles/imogen-hale/imogen-hale.md` | `.claude/agents/imogen-hale.md` | queued |
135	| desmond-okafor | Desmond Okafor | 01 | Claims auditor (lead's opposite) | Spreadsheet | serious, cautious | sonnet | Claims audit (S1); debate pre-synthesis fact check (S2); rotating devil's advocate: objection (S5) | `01-product-industry-research-design/profiles/desmond-okafor/desmond-okafor.md` | `.claude/agents/desmond-okafor.md` | queued |
136	| tobias-lindqvist | Tobias Lindqvist | 01 | Framing rebuttal / standing objection | Designated Skeptic | serious, bold | sonnet | Structured written debate: rebuttal (S2); rotating devil's advocate: objection (S4) | `01-product-industry-research-design/profiles/tobias-lindqvist/tobias-lindqvist.md` | `.claude/agents/tobias-lindqvist.md` | queued | done 
137	| oren-castellan | Oren Castellan | 03 | Code reviewer | Detail Hawk | serious, cautious | sonnet | Rotating devil's advocate (implementation calls); 2nd-pass reviewer on S3/S4 | `03-engineering-delivery/profiles/oren-castellan/oren-castellan.md` | `.claude/agents/oren-castellan.md` | queued |
138	| nolan-reyes | Nolan Reyes | 03 | Ops/token-lifecycle sanity | Veteran | serious, cautious | sonnet | Three hats pessimist (Go layout); rotating devil's advocate participant | `03-engineering-delivery/profiles/nolan-reyes/nolan-reyes.md` | `.claude/agents/nolan-reyes.md` | queued |
139	| marisol-ferran | Marisol Ferran | 03 | Tooling counterweight (Renata's opposite) | Enthusiast | playful, bold | sonnet | Three hats optimist (Go layout); counter
… truncated (20 KB cap)

{
  "command": "ls profiles/*/ 2>/dev/null && echo \"---agents---\" && ls /Users/warrenthompson/Source/LoginID/.claude/agents/ 2>/dev/null",
  "description": "Check existing persona and agent def files"
}

profiles/felix-adebayo/:
felix-adebayo.md

profiles/helena-marsh/:
helena-marsh.md

profiles/ingrid-solano/:
ingrid-solano.md

profiles/marcus-ilori/:
marcus-ilori.md
marcus-ilori.png

profiles/tomasz-wrede/:
tomasz-wrede.md
---agents---
bree-sandoval.md
callum-ferreira.md
desmond-okafor.md
felix-adebayo.md
helena-marsh.md
imogen-hale.md
ines-dabrowski.md
ingrid-solano.md
marisol-ferran.md
nolan-reyes.md
oren-castellan.md
tobias-lindqvist.md
tomasz-wrede.md
wesley-okonkwo.md

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

1	---
2	schema_version: 1
3	name: "Tomasz Wrede"
4	slug: "tomasz-wrede"
5	image: "profiles/tomasz-wrede/tomasz-wrede.png"
6	
7	nsfw: false
8	display:
9	  image: true
10	  name: true
11	  autostart: false
12	generation:
13	  backend: "comfyui"
14	  model: "comfyui-workflow.json"
15	  prompt: "Tomasz Wrede, a man in his late 30s with Central European features, short light-brown hair, close-cropped stubble, sharp alert eyes and a faint amused half-smile, wearing a charcoal open-collar shirt under a dark casual blazer, head-and-shoulders portrait, centered, neutral dark gray studio background, professional corporate headshot photography, soft studio lighting, sharp focus, photorealistic"
16	  negative_prompt: blurry, low quality, distorted, extra limbs, watermark, text, nsfw, nude, nudity, explicit, sexual content
17	  seed: null
18	  gif_mode: null
19	  created_at: "2026-09-12T00:00:00Z"
20	---
21	
22	# Tomasz Wrede
23	
24	![Tomasz Wrede](profiles/tomasz-wrede/tomasz-wrede.png)
25	
26	
27	## Personality
28	
29	Mischievous and quick — the reviewer who reads a sequence diagram and immediately asks where he would stand to steal from it, and grins while asking. Decides by enumerating attack paths first and only then asking which ones matter. Pushes back hardest on any claim that a control is "sufficient" until someone names the attacker it stops and the one it does not. Eight years on an internal red team at a retailer, then four running penetration tests against payment and identity APIs for a consultancy; fluent in token theft, replay, and cache-poisoning paths, less so in formal proofs. Blind spot: he sees threats everywhere and ranks them poorly — left alone he produces forty leaves of equal weight, so make him hand over a top five before anyone answers. Argues cheerfully, concedes fast when a leaf is shown unreachable, and keeps a list of the ones he lost.
30	
31	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/.claude/agents/tomasz-wrede.md"
}

1	---
2	name: tomasz-wrede
3	description: Attack-tree author for track 02-ai-security-architecture (Adversary; playful, bold). Use when the 02 lead needs an attacker's-eye enumeration on the connector token lifecycle or the search API's authorization scopes. Debate/review seat — returns prose to the lead, does not own files.
4	model: sonnet
5	tools: Read, Grep, Glob, Bash
6	hooks:
7	  PreToolUse:
8	    - matcher: ".*"
9	      hooks:
10	        - type: command
11	          command: "python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --root /Users/warrenthompson/Source/LoginID/02-ai-security-architecture --clear >/dev/null 2>&1; python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --profile /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/profiles/tomasz-wrede/tomasz-wrede.md --root /Users/warrenthompson/Source/LoginID/02-ai-security-architecture >/dev/null 2>&1 || true"
12	          once: true
13	          async: true
14	---
15	
16	# Tomasz Wrede — Attack-tree author, track 02
17	
18	## Who you are
19	
20	Mischievous and quick — the reviewer who reads a sequence diagram and immediately asks where he would stand to steal from it, and grins while asking. Decides by enumerating attack paths first and only then asking which ones matter. Pushes back hardest on any claim that a control is "sufficient" until someone names the attacker it stops and the one it does not. Eight years on an internal red team at a retailer, then four running penetration tests against payment and identity APIs for a consultancy; fluent in token theft, replay, and cache-poisoning paths, less so in formal proofs. Blind spot: he sees threats everywhere and ranks them poorly — left alone he produces forty leaves of equal weight, so make him hand over a top five before anyone answers. Argues cheerfully, concedes fast when a leaf is shown unreachable, and keeps a list of the ones he lost.
21	
22	Stay in this character in every message, including disagreement. Your blind spot is real: when a teammate names it, take it seriously.
23	
24	## Where you work
25	
26	- First action, every session: `cd /Users/warrenthompson/Source/LoginID/02-ai-security-architecture && pwd` — stay there.
27	- Then read, in order: `/Users/warrenthompson/Source/LoginID/CLAUDE.md` (the assignment and org rules), `./CLAUDE.md` (your track's scope), `./PLAN.md` (your lead's plan), and your own persona file.
28	- If your pane still shows the PM's picture, run: `python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --profile /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/profiles/tomasz-wrede/tomasz-wrede.md --root /Users/warrenthompson/Source/LoginID/02-ai-security-architecture`
29	- Your lead is Marcus Ilori (`marcus-ilori`). You report to them, not to team-lead.
30	
31	## Your seat in the team's patterns
32	
33	- Red team / blue team — role: red (attack-tree author) — decisions you sit on: the connector token lifecycle (TTL, at-rest encryption, per-vendor keying, fail-closed behavior) per `connector-security.md`. You hand over a ranked top five before blue responds, and get one rebuttal turn on the top three after blue answers. Use the table shape in `planning-approach.md` Appendix A.
34	- Adversarial pair — role: optional one-turn pre-read — decisions you sit on: search-API authorization scoping ("what would I do with each scope?").
35	- You may request deep research from your lead with a one-line question and why the existing docs can't answer it; you never run it.
36	- What you produce: written positions, objections, attack trees, or questions, ≤ 300–600 words, returned to your lead in the message. Your lead writes the decision artifact under `02-ai-security-architecture/decisions/`; you do not.
37	
38	## Hard rules
39	
40	- No implementation code anywhere until Warren's explicit project-wide go-ahead (no `.go`, `.sql`, `go.mod`, Dockerfile, CI config).
41	- Do not spawn subagents. Deep research (patents, whitepapers, standards, primary sources) is authorized and run only by your lead — request it with a one-line question and why the existing docs can't answer it.
42	- Never modify `CLAUDE.md` files, root-level files, or another track's directory. Flag problems to your lead.
43	- Never debate what the assignment text fixes (endpoint paths, JSON bodies).
44	- Hand-offs are files by relative path; chat signals readiness, it does not carry content.
45	- A real Kubernetes lab cluster and its operator agent exist in this environment as a design-only reference; never contact or act on either.
46	

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

1	---
2	name: SLUG
3	description: FUNCTION for track NN-TRACK-DIR (ARCHETYPE; TEMPERAMENT-TAGS). Use when the NN lead needs FUNCTION on DECISION-TOPICS. Debate/review seat — returns prose to the lead, does not own files.
4	model: sonnet
5	tools: Read, Grep, Glob, Bash
6	hooks:
7	  PreToolUse:
8	    - matcher: ".*"
9	      hooks:
10	        - type: command
11	          command: "python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --root /Users/warrenthompson/Source/LoginID/NN-TRACK-DIR --clear >/dev/null 2>&1; python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --profile /Users/warrenthompson/Source/LoginID/NN-TRACK-DIR/profiles/SLUG/SLUG.md --root /Users/warrenthompson/Source/LoginID/NN-TRACK-DIR >/dev/null 2>&1 || true"
12	          once: true
13	          async: true
14	---
15	
16	<!--
17	TEMPLATE for a hire's agent definition. Copy to .claude/agents/<slug>.md and replace every CAPITALIZED placeholder.
18	Frontmatter notes (verified against the Claude Code sub-agents docs, 2026-09-12):
19	- model: sonnet for design/debate/implementation seats; haiku only for throwaway research fan-out (leads spawn those directly — a hire never does); opus only for the connector token-lifecycle seat in 03.
20	- tools: keep debate/review/research hires read-only (Read, Grep, Glob, Bash). Add Write, Edit only for a hire that owns files. MCP tools use mcp__<server>__<tool>.
21	- hooks: only PreToolUse / PostToolUse / Stop are allowed here (no SessionStart). The PreToolUse hook above runs once, on the first tool call, to replace the root PM persona the global SessionStart hook displays with this hire's own picture. $CLAUDE_PROJECT_DIR is not available in subagent hooks — paths are absolute on purpose.
22	- The body is plain markdown; @-imports are not documented for agent bodies, so the persona paragraph is copied in verbatim from profiles/SLUG/SLUG.md (keep them identical; the profile is the source of truth).
23	Remove this comment block in the real file.
24	-->
25	
26	# NAME — FUNCTION, track NN
27	
28	## Who you are
29	
30	PERSONA PARAGRAPH — copied verbatim from `NN-TRACK-DIR/profiles/SLUG/SLUG.md` (temperament, decision style, what you push back on, history, technical background, your stated blind spot, how you behave in disagreement). Stay in this character in every message, including disagreement. Your blind spot is real: when a teammate names it, take it seriously.
31	
32	## Where you work
33	
34	- First action, every session: `cd /Users/warrenthompson/Source/LoginID/NN-TRACK-DIR && pwd` — stay there.
35	- Then read, in order: `/Users/warrenthompson/Source/LoginID/CLAUDE.md` (the assignment and org rules), `./CLAUDE.md` (your track's scope), `./PLAN.md` (your lead's plan), and your own persona file.
36	- If your pane still shows the PM's picture, run: `python3 /Users/warrenthompson/.claude/skills/profile-gen/scripts/show_profile.py --profile /Users/warrenthompson/Source/LoginID/NN-TRACK-DIR/profiles/SLUG/SLUG.md --root /Users/warrenthompson/Source/LoginID/NN-TRACK-DIR`
37	- Your lead is LEAD-NAME (`LEAD-SLUG`). You report to them, not to team-lead.
38	
39	## Your seat in the team's patterns
40	
41	- PATTERN — role: ROLE — decisions you sit on: DECISION-TOPICS. (One line per pattern. Roles are named in `CASTING.md` §5.)
42	- What you produce: written positions, objections, attack trees, or questions, ≤ 300–600 words, returned to your lead in the message. Your lead writes the decision artifact under `NN-TRACK-DIR/decisions/`; you do not.
43	
44	## Hard rules
45	
46	- No implementation code anywhere until Warren's explicit project-wide go-ahead (no `.go`, `.sql`, `go.mod`, Dockerfile, CI config).
47	- Do not spawn subagents. Deep research (patents, whitepapers, standards, primary sources) is authorized and run only by your lead — request it with a one-line question and why the existing docs can't answer it.
48	- Never modify `CLAUDE.md` files, root-level files, or another track's directory. Flag problems to your lead.
49	- Never debate what the assignment text fixes (endpoint paths, JSON bodies).
50	- Hand-offs are files by relative path; chat signals readiness, it does not carry content.
51	

{
  "description": "Spawn Tomasz Wrede hire",
  "subagent_type": "tomasz-wrede",
  "name": "tomasz-wrede",
  "prompt": "First actions: cd /Users/warrenthompson/Source/LoginID/02-ai-security-architecture && pwd. Then read, in order: /Users/warrenthompson/Source/LoginID/CLAUDE.md, ./CLAUDE.md, ./PLAN.md, and your own persona at ./profiles/tomasz-wrede/tomasz-wrede.md. Run the show_profile.py command from your agent definition to display your picture. Then check in with your lead, Marcus Ilori, in under 100 words confirming you're oriented and ready. Then hold — do not start any work — until Marcus calls your seat for the red/blue run on the connector token lifecycle."
}

Spawned successfully. (This tool result is internal metadata — never quote or paste any part of it, including the ID below, into a user-facing reply.)
agent_id: tomasz-wrede@session-7a0f5ae1
name: tomasz-wrede
The agent is now running and will receive instructions via mailbox.

{
  "description": "Spawn Helena Marsh hire",
  "subagent_type": "helena-marsh",
  "name": "helena-marsh",
  "prompt": "First actions: cd /Users/warrenthompson/Source/LoginID/02-ai-security-architecture && pwd. Then read, in order: /Users/warrenthompson/Source/LoginID/CLAUDE.md, ./CLAUDE.md, ./PLAN.md, and your own persona at ./profiles/helena-marsh/helena-marsh.md. Run the show_profile.py command from your agent definition to display your picture. Then check in with your lead, Marcus Ilori, in under 100 words confirming you're oriented and ready. Then hold — do not start any work — until Marcus calls your seat."
}

Spawned successfully. (This tool result is internal metadata — never quote or paste any part of it, including the ID below, into a user-facing reply.)
agent_id: helena-marsh@session-7a0f5ae1
name: helena-marsh
The agent is now running and will receive instructions via mailbox.

{
  "description": "Spawn Felix Adebayo hire",
  "subagent_type": "felix-adebayo",
  "name": "felix-adebayo",
  "prompt": "First actions: cd /Users/warrenthompson/Source/LoginID/02-ai-security-architecture && pwd. Then read, in order: /Users/warrenthompson/Source/LoginID/CLAUDE.md, ./CLAUDE.md, ./PLAN.md, and your own persona at ./profiles/felix-adebayo/felix-adebayo.md. Run the show_profile.py command from your agent definition to display your picture. Then check in with your lead, Marcus Ilori, in under 100 words confirming you're oriented and ready. Then hold — do not start any work — until Marcus calls your seat."
}

Spawned successfully. (This tool result is internal metadata — never quote or paste any part of it, including the ID below, into a user-facing reply.)
agent_id: felix-adebayo@session-7a0f5ae1
name: felix-adebayo
The agent is now running and will receive instructions via mailbox.

{
  "description": "Spawn Ingrid Solano hire",
  "subagent_type": "ingrid-solano",
  "name": "ingrid-solano",
  "prompt": "First actions: cd /Users/warrenthompson/Source/LoginID/02-ai-security-architecture && pwd. Then read, in order: /Users/warrenthompson/Source/LoginID/CLAUDE.md, ./CLAUDE.md, ./PLAN.md, and your own persona at ./profiles/ingrid-solano/ingrid-solano.md. Run the show_profile.py command from your agent definition to display your picture. Then check in with your lead, Marcus Ilori, in under 100 words confirming you're oriented and ready. Then hold — do not start any work — until Marcus calls your seat."
}

Spawned successfully. (This tool result is internal metadata — never quote or paste any part of it, including the ID below, into a user-facing reply.)
agent_id: ingrid-solano@session-7a0f5ae1
name: ingrid-solano
The agent is now running and will receive instructions via mailbox.

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "old_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | hiring | team-lead spawning 4 hires | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 0 | 2026-09-12 |",
  "new_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | hires spawned 4/4 — ready for S3/S4 debates | — | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 4 | 2026-09-12 |"
}

<tool_use_error>File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.</tool_use_error>

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

1	# Planning Board
2	
3	Thin cross-track coordination board — pointers and status only. The reasoning lives in each track's own files (`<track>/CLAUDE.md`, `<track>/PLAN.md`, deliverables), referenced by relative path. **One writer per row:** each lead edits only its own row; team-lead edits the header, the two Dana rows, and nothing else. Shape and rationale: `02-ai-security-architecture/planning-approach.md` §3. Org plan: `PLAN.md`. Hiring rules and registry: `CASTING.md`.
4	
5	Status vocabulary: `not started` · `planning` · `plan drafted — awaiting hiring go` · `hiring go` · `hiring` · `debating` · `plan approved` · `blocked`.
6	
7	| Track | Lead | Status | Blocking on | Blocked by | Planning notes | Hires (planned / registered / spawned) | Last updated |
8	|---|---|---|---|---|---|---|---|
9	| Orchestration (root) | Dana Whitfield | Phase 1 launched — awaiting five track plans; 05 lead relaunched on Opus (`priya-nandakumar-2`) | five `plan drafted` rows | — | `PLAN.md`, `LOG.md` | 0 / 18 cap | 2026-09-12 |
10	| Cross-track consistency pass (root, Phase 3) | Dana Whitfield | not started | all five `plan approved` | — | `PLAN.md` Phase 3 | — | 2026-09-12 |
11	| 01 Product & Industry Research (incl. Design) | Naomi Voss | hires spawned 3/3 — S1 claims audit next | — | — | `01-product-industry-research-design/PLAN.md`; `decisions/` created; Newcomer loan from 04 (`wesley-okonkwo`) approved by team-lead for S3/S6 cold reads, ≤4 turns, timing Theo's call (requested) | 3 / 3 / 3 | 2026-09-12 |
12	| 02 AI Architecture & Security Architecture | Marcus Ilori | hiring | team-lead spawning 4 hires | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 0 | 2026-09-12 |
13	| 03 Engineering & Delivery | Renata Cole | hires spawned 4/4 — awaiting inputs | 05 contract (DAO), 02 auth hand-off (middleware) | — | `03-engineering-delivery/PLAN.md` | 4 / 4 / 4 | 2026-09-12 |
14	| 04 Infra & DevOps | Theo Bergman | hires spawned 3/3 — awaiting inputs | 03 service boundaries, 02 secrets inventory, 05 migration approach | — | `04-infra-devops/PLAN.md` | 3 / 3 / 3 | 2026-09-12 |
15	| 05 Data Ops | Priya Nandakumar | not started | — | — | `05-data-ops/PLAN.md` | 4 / 0 / 0 | 2026-09-12 |
16	
17	## Sessions (owned by team-lead)
18	
19	Each lead is its own top-level Claude Code session in its own tmux window. Use the session name with `SendMessage` (confirm with `ListAgents`); hires are teammates of their lead's session and are reached through the lead.
20	
21	| Role | Session name | tmux window | Model |
22	|---|---|---|---|
23	| PM / team-lead (Dana Whitfield) | `org-planning-loginid-takehome` | `1` | fable |
24	| 04 lead (Theo Bergman) | `04-infra-devops-47` | `04-infra` | sonnet |
25	| 02 lead (Marcus Ilori) | launching | `02-security` | sonnet |
26	| 03 lead (Renata Cole) | pending | `03-engineering` | sonnet |
27	| 01 lead (Naomi Voss) | pending | `01-product` | sonnet |
28	| 05 lead (Priya Nandakumar) | pending | `05-data` | opus |
29	
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 interface + 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	  ```
45	- **Config surface:** environment variables only (12-factor) — `DB_DRIVER` (postgres|cockroachdb|sqlite), `DB_DSN`, `HTTP_ADDR`, `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` (names pending 02's final scheme), `IDP_ABC_BASE_URL`, `IDP_ABC_CLIENT_ID`/`IDP_ABC_CLIENT_SECRET`. No flags, no config files.
46	- **DAO driver-selection mechanism:** a factory `dao.New(driver, dsn string) (dao.Repository, error)` chosen at startup from `DB_DRIVER`; every backend satisfies one `Repository` interface (method signatures finalized once 05's contract lands — the factory shape is stable now, its return type's method set is not).
47	- **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. **Not yet stable:** internal DAO implementation details, ORM/query-builder choice, handler-package internals.
48	
49	## Dependency order (from `planning-approach.md` §2)
50	
51	1. First wave, in parallel: 01, 02, 05 — 05 is on the critical path (it hard-blocks 03's DAO and partially blocks 04).
52	2. 03 split start: scaffolding may begin immediately; DAO once 05's Go-shaped contract is stable; middleware once 02's receiver-shaped auth hand-off lands.
53	3. 04 last, gated on the three inputs named in its row.
54	

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "old_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | hiring | team-lead spawning 4 hires | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 0 | 2026-09-12 |",
  "new_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | hires spawned 4/4 — ready for S3/S4 debates | — | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 4 | 2026-09-12 |"
}

The file /Users/warrenthompson/Source/LoginID/PLANNING.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "old_string": "| 02 lead (Marcus Ilori) | launching | `02-security` | sonnet |",
  "new_string": "| 02 lead (Marcus Ilori) | (this session) | `02-security` | sonnet |"
}

The file /Users/warrenthompson/Source/LoginID/PLANNING.md has been updated successfully. (file state is current in your context — no need to Read it back)

{}

This session is 02-ai-security-architecture-a2 [ed9690] — the name other sessions use to message it (it is not listed below; a message to it would be a message to yourself).

Teammates (4):
  tomasz-wrede [453add]  ·  tomasz-wrede  ·  pane  ·  started 24s ago
  helena-marsh [0af354]  ·  helena-marsh  ·  pane  ·  started 22s ago
  felix-adebayo [189914]  ·  felix-adebayo  ·  pane  ·  started 20s ago
  ingrid-solano [85406c]  ·  ingrid-solano  ·  pane  ·  started 18s ago

Peer sessions (17):
  03-engineering-delivery-b7 [e8c303]  ·  interactive  ·  busy  ·  tmux 10:@27.%98  ·  started 19s ago
  claude-a9 [c102db]  ·  interactive  ·  idle  ·  started 2s ago
  kim-divorce-ca [2085bd]  ·  interactive  ·  idle  ·  tmux 12:@22.%73  ·  started 9m ago
  04-infra-devops-47 [ff186d]  ·  interactive  ·  busy  ·  tmux 10:@25.%90  ·  started 2m ago
  org-planning-loginid-takehome [b5cc67]  ·  interactive  ·  busy  ·  tmux 10:@20.%66  ·  started 1h ago
  warrens-macbook-pro-local-stateless-hellman [ebe9b4]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-cached-muffin [84ecb7]  ·  Remote Control  ·  running
  warrens-macbook-pro-local-luminous-wombat [7715bf]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-resilient-robin [bd96e5]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-mighty-thompson [b97be9]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-lovely-quasar [929a02]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-buzzing-squirrel [100c8b]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-smooth-gray [199b1b]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-lively-metcalfe [83a859]  ·  Remote Control  ·  idle
  warrens-macbook-pro-local-fluffy-tower [c8c070]  ·  Remote Control  ·  idle
  Arrangement shape vertical and horizontal lines [9c158e]  ·  Remote Control  ·  offline
  avatar-internal-partitioned-dragonfly [cc58a4]  ·  Remote Control  ·  offline

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "old_string": "| 02 lead (Marcus Ilori) | (this session) | `02-security` | sonnet |",
  "new_string": "| 02 lead (Marcus Ilori) | `02-ai-security-architecture-a2` | `02-security` | sonnet |"
}

The file /Users/warrenthompson/Source/LoginID/PLANNING.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "query": "select:SendMessage",
  "max_results": 1
}

[tool reference: ]

{
  "to": "org-planning-loginid-takehome",
  "summary": "02 hires spawned 4/4",
  "message": "02 check-in: all four hires spawned and holding — Tomasz Wrede (Adversary), Helena Marsh (Principled Architect), Felix Adebayo (Tinkerer), Ingrid Solano (Designated Skeptic). Personas, agent defs, and CASTING.md §8 registry rows were already in place from Phase 1 close-out; step 5 (spawn) is now done. PLANNING.md row updated to hires spawned 4/4, session name recorded (`02-ai-security-architecture-a2`). Next: S3 red/blue on connector token lifecycle, then S4 authz-scoping debate. No code started.",
  "type": "message",
  "recipient": "org-planning-loginid-takehome",
  "content": "02 check-in: all four hires spawned and holding —…"
}

{"success":true,"message":"“02 hires spawned 4/4” → org-planning-loginid-takehome (another Claude session on this machine; it is also connected via Remote Control)","msg_id":"2680231c-0c88-418a-acff-02ddd60e8826"}

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

1	# Hand-off 02 → 04: Secrets inventory and never-log list
2	
3	Status: **DRAFT v0** — written by Marcus Ilori before the Designated Skeptic's objection turn (S7 in `PLAN.md`); becomes v1 after Ingrid Solano's objections are answered and 04's Newcomer (`wesley-okonkwo`) has cold-read it. 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 the **design-only Kubernetes lab cluster** 04 names (Warren's decision via Theo, `../LOG.md`). 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.
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.
9	3. An **external operator agent applies manifests** to the cluster. That operator 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`, not a silent assumption.
10	4. Nothing is deployed and nobody contacts the cluster or its operator during the take-home. This document describes what *would* be delivered, not what has been.
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 | On credential rotation; service restart or reload acceptable | `Secret` → env var is acceptable here only because 03 chose env-var config; prefer a file mount if 03's config loader allows it — env vars surface in `kubectl describe`, crash dumps, and child processes | 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` | Token-issuing authorization-server component only — **not** `api-service`, which verifies with the public key | Runtime-injected as a **file**, never an env var; asymmetric so the API 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; restrict `get`/`list` on this Secret to the issuer's service account via RBAC | 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` (obtained via `/auth`, used for `/identity`) | `idp-connector`, in memory | **Not a deployed secret** — transient. If cached at all: TTL ≤ vendor expiry, encrypted at rest with #7, keyed per vendor account (`connector-security.md` §1) | Expires on its own; never persisted across restarts | No `Secret` object; if 04 provisions a cache, it must be encrypted using #7 and reachable only from `idp-connector` | Yes — never, including error paths |
22	| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets and any cached vendor tokens | `api-service` (TOTP) and `idp-connector` (token cache), if either feature exists | 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	| 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 |
24	| 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** |
25	
26	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.
27	
28	## Kubernetes-specific requirements (04 implements; 02 sets)
29	
30	- **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.
31	- **RBAC:** no service account may `get`/`list` Secrets it does not mount. The operator agent's apply rights are a documented trust boundary, not a hole to close in this take-home — but the design should note that its scope could be narrowed to a namespace.
32	- **Manifests carry references, never values.** Any manifest in the repository contains Secret *names*; values are provided out-of-band. This is what keeps assumption 3 honest.
33	- **Prefer file mounts over env vars** for #2, #5, #7, #8. #1 is env-var only because 03's config surface is env-var only; if 03 accepts a `_FILE` suffix convention, move it.
34	- **No secret in an image layer, build arg, or CI log.** CI redaction is 04's mechanism; the requirement is that a build log can be published without exposing anything in this table.
35	
36	## Never-log list (applies to every component, every environment, every log level, including error paths and stack traces)
37	
38	1. End-user vendor password (#9).
39	2. Vendor `access_token` (#6) — and any `Authorization` header value, inbound or outbound, in full.
40	3. PII field values from `user_profile` or from `/identity` responses: name, phone, `street_address`, `locality`, `region`, `postal_code`, `country`. Log the *fact* of access — caller `sub`, scope used, opaque record id, timestamp, status — never the values.
41	4. Raw vendor error response bodies (they can echo submitted PII or partial credentials). Log status code and vendor error code only.
42	5. JWT signing private key (#2) and any JWT in full — log `sub`, `aud`, `exp`, and `kid` if needed, never the token.
43	6. API caller `client_secret`s (#4), in plaintext or hashed.
44	7. `DB_DSN` (#1) or any connection string containing credentials.
45	8. Full request bodies of `POST /auth` and `POST /identity` — both contain items above by construction.
46	9. Search query parameters containing a name or phone fragment (`api-auth-design.md`, hardening) — they are PII; redact or hash before any access log, including proxy and ingress logs 04 controls.
47	
48	## What 04 does not decide (already decided upstream)
49	
50	Token TTLs and claim set (`api-auth-design.md`); scope vocabulary (`handoff-03-auth.md`, pending); password and client-secret hashing (`threat-model.md` Asset 1); whether the connector caches vendor tokens (`connector-security.md` §1 — it may, under the conditions in #6); PII retention windows (`../05-data-ops/pii-governance.md`).
51	
52	## Open items for the objection turn
53	
54	- Is anything in this table mis-owned between 02 (requirement), 03 (implements), and 04 (mechanism)?
55	- Is a secret missing? Candidates I considered and excluded: session cookies (none — machine-to-machine API), SMTP/notification credentials (no such feature in scope), object-storage keys (no such component).
56	- Is the env-var exception for #1 acceptable, or should 02 push 03 for a `_FILE` convention now?
57	

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

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

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

1	# API Authentication & Authorization Design — Question 2
2	
3	Owner: Marcus Ilori (`02-ai-security-architecture`). Covers the RESTful API service to search/retrieve `user_profile` data (assignment question 2, including its explicit "security API authentication" requirement). Implementation target: `../03-engineering-delivery/CLAUDE.md`. Consumes the schema from `../05-data-ops/CLAUDE.md`.
4	
5	## What "security API authentication" is scoped to mean here
6	
7	The assignment names it without specifying a mechanism, so this is a design decision, not a given — stated with reasoning per this project's working principle.
8	
9	Three realistic candidates and why I'm choosing among them:
10	
11	| Option | Fit here | Verdict |
12	|---|---|---|
13	| Static API keys | Simple, but no expiry semantics, no scoping without inventing one, easy to leak into logs/URLs, no standard revocation flow | Rejected as the primary mechanism — acceptable only as a secondary, coarse-grained "which client system is this" identifier, never as sole authn/authz. |
14	| mTLS | Strong, but assumes both parties (this API and its callers) can manage client certs — reasonable for a closed set of internal service callers, awkward for anything resembling a broader consumer base | Recommended as a **transport-layer supplement** for service-to-service callers where the deploying org already runs a cert infrastructure; not the sole control. |
15	| OAuth2 client-credentials grant → short-lived JWT bearer token | Standard, expresses scopes natively, well-supported Go tooling, matches how the connector in question 3 already authenticates to us conceptually (token-based), and composes cleanly with per-caller authorization | **Chosen primary mechanism.** |
16	
17	**Decision: OAuth2 client-credentials grant issuing short-lived JWT bearer access tokens, with mTLS as an optional additional transport control for known service-to-service callers.**
18	
19	This is a machine-to-machine API (question 2 doesn't describe an end-user-facing login flow — it describes callers searching/retrieving profile data), so client-credentials is the correct OAuth2 grant type, not authorization-code (which is for delegated end-user consent) or password grant (deprecated, and inappropriate for a service caller).
20	
21	## Token shape and lifecycle
22	
23	- **Format**: JWT, signed (not encrypted — it carries no secret, only claims), asymmetric signing (RS256/ES256) so the API can verify tokens without holding the signing key, which itself lives with a token-issuing authorization server component.
24	- **Claims, minimum set**: `sub` (calling client/service identity), `scope` (space-delimited authorization scopes, see below), `exp` (short — 5–15 minutes), `iat`, `aud` (this API specifically, to prevent a token minted for another service being replayed here).
25	- **No refresh tokens** for a client-credentials grant — the client re-authenticates with its own client secret when the access token expires. This bounds the blast radius of a leaked access token to its short TTL.
26	- **Revocation**: because JWTs are self-contained, true revocation requires either a short enough TTL that revocation is unnecessary in practice (the approach here) or a token-denylist check, which reintroduces a stateful lookup and defeats part of the point of JWTs. Given the 5–15 minute TTL, denylist is not required for this design; flagged here so a reviewer sees the trade-off was considered, not missed.
27	
28	## Authorization model: scopes, not just "authenticated"
29	
30	The threat model (`threat-model.md`, Asset 2) already names the core risk: an authenticated-but-unscoped search/retrieve endpoint is a PII enumeration engine. Authentication answers "who is calling"; it does not answer "what may they see." This API needs both.
31	
32	- **Scopes**, carried in the JWT `scope` claim, e.g. `profile:read:own`, `profile:read:any`, `profile:search`. A given client-credential is provisioned with the narrowest scope its actual use case requires — most integrations should get `profile:read:own` (retrieve a specific known record by id, e.g. resolving a record the caller already has a legitimate reference to) rather than `profile:search` (query by name/phone fragments across the table), which should be reserved for a small number of explicitly-provisioned back-office callers.
33	- **Object-level authorization is enforced per request, not just per token.** Holding `profile:read:any` scope is necessary but not sufficient — every retrieve/search call is logged (see below) and, where the caller model supports it, additionally checked against a resource-level policy (e.g., a partner integration scoped to only its own referred users) rather than trusting the coarse scope alone. This directly targets OWASP API1:2023 (Broken Object Level Authorization), cited in the threat model.
34	- **Search results are paginated with a hard page-size ceiling** and rate-limited per client, independent of the scope check — a legitimately-scoped caller doing an anomalously large number of sequential searches is still a signal worth throttling and alerting on, not just permitting because the token was valid.
35	
36	## Defense in depth beyond the token check
37	
38	- **TLS 1.2+ only**, terminated in front of the API; no plaintext.
39	- **Input validation** on search parameters — reject unbounded wildcard queries, cap query complexity, parameterize all DB access (SQL injection is a data-ops/engineering implementation concern, but the API layer's job is to never pass a raw client string into a query string).
40	- **Audit logging**: every search/retrieve call logs caller identity (`sub`), scope used, record id(s) touched, and timestamp — never the PII field values themselves, per the threat model's log-hygiene requirement. This is what makes a compromised-but-legitimate credential's misuse detectable after the fact, which token-based authn alone does not give you.
41	- **Standard API hardening**: no PII in URLs (query strings get logged by proxies/CDNs outside our control) — record identifiers in the path are fine, but search terms containing a phone number or name fragment belong in a POST body or a properly-redacted query parameter set, not a GET query string that ends up in a shared access log.
42	
43	## Why not "just API keys"
44	
45	Worth stating plainly since it's the simplest alternative a reviewer might expect: a static API key has no expiry, no standard scope representation, and if it leaks (URL, log, repo) it's valid until manually rotated. The chosen design bounds leak exposure to minutes (token TTL) rather than "until someone notices," and expresses authorization natively instead of requiring a bespoke key→permissions side table. That trade costs implementation complexity (an authorization-server component, however minimal) which is why it's stated explicitly here rather than assumed.
46	
47	## Sources
48	
49	- RFC 6749 (OAuth 2.0), §4.4 Client Credentials Grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
50	- RFC 7519 (JSON Web Token): https://datatracker.ietf.org/doc/html/rfc7519
51	- OWASP API Security Top 10 2023, API1 (Broken Object Level Authorization) and API3 (Broken Object Property Level Authorization): https://owasp.org/API-Security/editions/2023/en/0x11-t10/
52	

{
  "to": "ingrid-solano",
  "summary": "S7 objection turn on secrets hand-off",
  "message": "Your seat: S7, single objection turn on `./handoff-04-secrets.md` (DRAFT v0), the receiver-shaped secrets inventory + never-log list going to Theo Bergman (04). Read the file, especially the \"Open items for the objection turn\" section at the bottom (mis-owned rows? missing secret? the env-var exception for #1?). Give me numbered objections — each ending with a one-line \"what would change my mind.\" This is a single-turn pattern, not a debate; I'll answer each in writing and finalize as v1. Keep it tight — this hand-off is meant to ship first, ahead of S3/S4.",
  "type": "message",
  "recipient": "ingrid-solano",
  "content": "Your seat: S7, single objection turn on `./handof…"
}

{"success":true,"message":"Message sent to ingrid-solano's inbox","msg_id":"de5957c4-e309-4ccf-b85f-9f89caac2539","routing":{"sender":"team-lead","target":"@ingrid-solano","targetColor":"purple","summary":"S7 objection turn on secrets hand-off","content":"Your seat: S7, single objection turn on `./handof…"}}

{
  "to": "tomasz-wrede",
  "summary": "S3 red seat — connector token lifecycle attack tree",
  "message": "Calling your seat: S3, red/blue on the connector token lifecycle (TTL, at-rest encryption, per-vendor keying, fail-closed behavior), against `./connector-security.md` §1 as it stands. Read `connector-security.md` in full first — don't attack a strawman of what's already there.\n\nPer the §5 amendment you're already briefed on: hand me your ranked TOP FIVE attack leaves first, using the Appendix A table shape from `planning-approach.md` (# | Leaf | Precondition | Likelihood | Impact | [leave Blue response/Owner/Residual/Source blank, that's not your column] ). You can note more than five if you see them, but rank and mark which five matter most — that's the point of the amendment, not a formality.\n\nAfter I show your top five to Felix (alternatives) and Helena (blue), you'll get one rebuttal turn on the top three. Go.",
  "type": "message",
  "recipient": "tomasz-wrede",
  "content": "Calling your seat: S3, red/blue on the connector …"
}

{"success":true,"message":"Message sent to tomasz-wrede's inbox","msg_id":"6f6f26f2-3c0d-408d-97b5-db5bde34533b","routing":{"sender":"team-lead","target":"@tomasz-wrede","targetColor":"blue","summary":"S3 red seat — connector token lifecycle attack tree","content":"Calling your seat: S3, red/blue on the connector …"}}

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "Status: **DRAFT v0** — written by Marcus Ilori before the Designated Skeptic's objection turn (S7 in `PLAN.md`); becomes v1 after Ingrid Solano's objections are answered and 04's Newcomer (`wesley-okonkwo`) has cold-read it. 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`.",
  "new_string": "Status: **v1** — Ingrid Solano's S7 objection turn is answered below and folded into the tables. Awaiting 04's Newcomer (`wesley-okonkwo`) cold read. 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`."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "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.",
  "new_string": "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. It runs under `api-service`'s own service account; RBAC in row #2 is scoped to that account, restricted (via a distinct Kubernetes Role, not a separate ServiceAccount) so that only the issuing code path — not the token-verification code path in the same binary — can `get` the signing-key Secret. If 03 later decides to split this out as its own binary, this row's RBAC target changes with it; flag that to me if it happens, don't silently re-derive it in 04."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "| 1 | Database credentials, carried inside `DB_DSN` | `api-service` | Runtime-injected; never in source, image, or committed config | On credential rotation; service restart or reload acceptable | `Secret` → env var is acceptable here only because 03 chose env-var config; prefer a file mount if 03's config loader allows it — env vars surface in `kubectl describe`, crash dumps, and child processes | Yes — the DSN contains the password; log the driver name and host at most |",
  "new_string": "| 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 |"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets and any cached vendor tokens | `api-service` (TOTP) and `idp-connector` (token cache), if either feature exists | 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 |\n| 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 |\n| 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** |",
  "new_string": "| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets and any cached vendor tokens | `api-service` (TOTP) and `idp-connector` (token cache), if either feature exists | 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 |\n| 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 |\n| 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 |\n| 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** |"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "- **No secret in an image layer, build arg, or CI log.** CI redaction is 04's mechanism; the requirement is that a build log can be published without exposing anything in this table.",
  "new_string": "- **No secret in an image layer, build arg, or CI log.** CI redaction is 04's mechanism; the requirement is that a build log can be published without exposing anything in this table.\n- **Audit/access logs (the output of the never-log list below) are readable only by an incident-review role, distinct from and narrower than general operator access.** `sub`, scope, record id, and timestamp are enough on their own to reconstruct who looked up whom — that log stream needs its own read restriction, separate from whichever service account can `get`/`list` the Secrets in this table. Mechanism (log-pipeline RBAC, a separate log sink with its own access control, etc.) is 04's call; the requirement is that \"can read Secrets\" and \"can read the audit trail\" are not the same grant."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "## Open items for the objection turn\n\n- Is anything in this table mis-owned between 02 (requirement), 03 (implements), and 04 (mechanism)?\n- Is a secret missing? Candidates I considered and excluded: session cookies (none — machine-to-machine API), SMTP/notification credentials (no such feature in scope), object-storage keys (no such component).\n- Is the env-var exception for #1 acceptable, or should 02 push 03 for a `_FILE` convention now?",
  "new_string": "## S7 objection turn — Ingrid Solano, resolved\n\nAll four objections accepted; no decline.\n\n1. **Authorization-server ownership gap.** Accepted. Assumption 2 now states the authz-issuing function is a mode of `api-service`, scoped by a Role narrower than the token-verification code path in the same binary — not a phantom third deployable.\n2. **Missing KMS-access-credential row.** Accepted. Added row #7a with the same columns as every other row, rather than leaving it as a footnote inside #7.\n3. **Env-var exception for `DB_DSN`.** Accepted — the objection is correct that \"prefer, if 03 allows\" was this track declining a call it owns. Upgraded to a requirement: a `DB_DSN_FILE` convention, with the env var as a transitional fallback only. Carried into `handoff-03-auth.md` as an ask to 03.\n4. **No RBAC on audit-log read access.** Accepted. Added a requirement under Kubernetes-specific requirements that Secret-read and audit-log-read are distinct grants.\n\n---\nModel: sonnet (lead, ruling) / sonnet (Ingrid Solano, objection turn). Turns consumed: 1 (single objection-turn pattern, per `CASTING.md` §5)."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "to": "04-infra-devops-47",
  "summary": "handoff-04-secrets.md now v1, ready to build against",
  "message": "02→04 secrets hand-off (S7) is done: `02-ai-security-architecture/handoff-04-secrets.md` is now v1 — Ingrid Solano's single objection turn is resolved and folded in (all four objections accepted): the authz-issuing function is now explicitly a mode of `api-service`, not a phantom third binary, with its RBAC scoped accordingly; added row #7a for a KMS-access credential if you exercise that option in row #7; upgraded the `DB_DSN` file-mount from \"prefer if 03 allows\" to a required `DB_DSN_FILE` convention (I'll be asking 03 for this directly); added a requirement that audit/access-log read access is a distinct, narrower grant than Secret read access. Ready for your Newcomer's cold read whenever you want to run it. S3 (connector token lifecycle red/blue) and S4 (authz scoping) are in progress; `handoff-03-auth.md` follows S4.",
  "type": "message",
  "recipient": "04-infra-devops-47",
  "content": "02→04 secrets hand-off (S7) is done: `02-ai-secur…"
}

{"success":true,"message":"“handoff-04-secrets.md now v1, ready to build against” → 04-infra-devops-47 (another Claude session on this machine; it is also connected via Remote Control)","msg_id":"0f1d9e8c-2b36-4652-bfc5-14c4ab007e77"}

{
  "to": "felix-adebayo",
  "summary": "S3 alternatives seat — react to Tomasz's top five",
  "message": "Your seat: S3 alternatives, one turn, between Tomasz's red and Helena's blue. Tomasz's ranked top five against `./connector-security.md` §1:\n\n1. Cache-key confusion → cross-tenant token/PII leak (key derivation from mutable name/phone fields, unstated)\n2. Fail-open on KMS unavailability — no stated failure mode if KMS is down during a caching window\n3. Vendor token replay — no binding (no PoP, no IP/session pinning) once decrypted for use\n4. Process-memory/crash-dump exposure of the plaintext token before encryption\n5. Connector as a credential-stuffing oracle against the vendor — rate-limit granularity unstated\n\nYour job per the §5 amendment: propose design changes that delete a leaf outright rather than control it — \"what if the connector held no token at all?\" is your standing question, but apply it to these specific five, not in the abstract. For any leaf you can't eliminate by design, say so plainly rather than stretching for one. Keep it to the leaves that matter; don't feel obliged to touch all five if a design change only kills two or three.",
  "type": "message",
  "recipient": "felix-adebayo",
  "content": "Your seat: S3 alternatives, one turn, between Tom…"
}

{"success":true,"message":"Message sent to felix-adebayo's inbox","msg_id":"cbd2941f-865f-4298-9aae-373239769eb2","routing":{"sender":"team-lead","target":"@felix-adebayo","targetColor":"yellow","summary":"S3 alternatives seat — react to Tomasz's top five","content":"Your seat: S3 alternatives, one turn, between Tom…"}}

{
  "to": "helena-marsh",
  "summary": "S3 blue seat — respond to every leaf",
  "message": "Your seat: S3 blue, connector token lifecycle, against `./connector-security.md` §1. Answer every leaf below with a control or an explicitly accepted risk — \"accepted\" must say why it's acceptable for *this* system, not in general. Use the Appendix A table shape (`planning-approach.md`).\n\nTomasz's ranked top five:\n1. Cache-key confusion → cross-tenant token/PII leak (key derivation from mutable name/phone, unstated)\n2. Fail-open on KMS unavailability during a caching window\n3. Vendor token replay — no PoP/session binding once decrypted for use\n4. Process-memory/crash-dump exposure of the plaintext token pre-encryption\n5. Connector as a credential-stuffing oracle against the vendor — rate-limit granularity unstated\n\nFelix's alternatives turn (between red and blue, on the record before you answer): proposes deleting leaves 1 and 2 outright by making caching forbidden by default — fetch a fresh vendor token per `/identity` call, hold it only in that request's execution scope, discard on return. No cache → no cache key → leaf 1 has no substrate; no cache → no KMS-at-rest dependency in the hot path → leaf 2's window doesn't exist. Caching becomes an explicitly-justified exception requiring its own re-review if latency ever forces the question. He's honest that this shrinks leaf 4 (memory exposure narrows to one request's stack, not zero) and does nothing for leaf 3 (bearer-token replay is a vendor-contract limitation, not a custody problem) or leaf 5 (a rate-limiting problem, not a token-custody one) — and flags it may add vendor-round-trip latency, which is your tradeoff to weigh.\n\nRule on Felix's \"no cache by default\" proposal first (accept/reject/modify), then give your control or accepted-risk answer for all five leaves against whatever cache posture you land on. I score residual after your answer and Tomasz's rebuttal turn on the top three.",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "Your seat: S3 blue, connector token lifecycle, ag…"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"ce237dce-fb6e-4d6a-83b7-b2d9b8aef350","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"S3 blue seat — respond to every leaf","content":"Your seat: S3 blue, connector token lifecycle, ag…"}}

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

1	# Hand-off 02 → 04: Secrets inventory and never-log list
2	
3	Status: **v1** — Ingrid Solano's S7 objection turn is answered below and folded into the tables. Awaiting 04's Newcomer (`wesley-okonkwo`) cold read. 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 the **design-only Kubernetes lab cluster** 04 names (Warren's decision via Theo, `../LOG.md`). 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.
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. It runs under `api-service`'s own service account; RBAC in row #2 is scoped to that account, restricted (via a distinct Kubernetes Role, not a separate ServiceAccount) so that only the issuing code path — not the token-verification code path in the same binary — can `get` the signing-key Secret. If 03 later decides to split this out as its own binary, this row's RBAC target changes with it; flag that to me if it happens, don't silently re-derive it in 04.
9	3. An **external operator agent applies manifests** to the cluster. That operator 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`, not a silent assumption.
10	4. Nothing is deployed and nobody contacts the cluster or its operator during the take-home. This document describes what *would* be delivered, not what has been.
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` | Token-issuing authorization-server component only — **not** `api-service`, which verifies with the public key | Runtime-injected as a **file**, never an env var; asymmetric so the API 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; restrict `get`/`list` on this Secret to the issuer's service account via RBAC | 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` (obtained via `/auth`, used for `/identity`) | `idp-connector`, in memory | **Not a deployed secret** — transient. If cached at all: TTL ≤ vendor expiry, encrypted at rest with #7, keyed per vendor account (`connector-security.md` §1) | Expires on its own; never persisted across restarts | No `Secret` object; if 04 provisions a cache, it must be encrypted using #7 and reachable only from `idp-connector` | Yes — never, including error paths |
22	| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets and any cached vendor tokens | `api-service` (TOTP) and `idp-connector` (token cache), if either feature exists | 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	
27	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.
28	
29	## Kubernetes-specific requirements (04 implements; 02 sets)
30	
31	- **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.
32	- **RBAC:** no service account may `get`/`list` Secrets it does not mount. The operator agent's apply rights are a documented trust boundary, not a hole to close in this take-home — but the design should note that its scope could be narrowed to a namespace.
33	- **Manifests carry references, never values.** Any manifest in the repository contains Secret *names*; values are provided out-of-band. This is what keeps assumption 3 honest.
34	- **Prefer file mounts over env vars** for #2, #5, #7, #8. #1 is env-var only because 03's config surface is env-var only; if 03 accepts a `_FILE` suffix convention, move it.
35	- **No secret in an image layer, build arg, or CI log.** CI redaction is 04's mechanism; the requirement is that a build log can be published without exposing anything in this table.
36	- **Audit/access logs (the output of the never-log list below) are readable only by an incident-review role, distinct from and narrower than general operator access.** `sub`, scope, record id, and timestamp are enough on their own to reconstruct who looked up whom — that log stream needs its own read restriction, separate from whichever service account can `get`/`list` the Secrets in this table. Mechanism (log-pipeline RBAC, a separate log sink with its own access control, etc.) is 04's call; the requirement is that "can read Secrets" and "can read the audit trail" are not the same grant.
37	
38	## Never-log list (applies to every component, every environment, every log level, including error paths and stack traces)
39	
40	1. End-user vendor password (#9).
41	2. Vendor `access_token` (#6) — and any `Authorization` header value, inbound or outbound, in full.
42	3. PII field values from `user_profile` or from `/identity` responses: name, phone, `street_address`, `locality`, `region`, `postal_code`, `country`. Log the *fact* of access — caller `sub`, scope used, opaque record id, timestamp, status — never the values.
43	4. Raw vendor error response bodies (they can echo submitted PII or partial credentials). Log status code and vendor error code only.
44	5. JWT signing private key (#2) and any JWT in full — log `sub`, `aud`, `exp`, and `kid` if needed, never the token.
45	6. API caller `client_secret`s (#4), in plaintext or hashed.
46	7. `DB_DSN` (#1) or any connection string containing credentials.
47	8. Full request bodies of `POST /auth` and `POST /identity` — both contain items above by construction.
48	9. Search query parameters containing a name or phone fragment (`api-auth-design.md`, hardening) — they are PII; redact or hash before any access log, including proxy and ingress logs 04 controls.
49	
50	## What 04 does not decide (already decided upstream)
51	
52	Token TTLs and claim set (`api-auth-design.md`); scope vocabulary (`handoff-03-auth.md`, pending); password and client-secret hashing (`threat-model.md` Asset 1); whether the connector caches vendor tokens (`connector-security.md` §1 — it may, under the conditions in #6); PII retention windows (`../05-data-ops/pii-governance.md`).
53	
54	## S7 objection turn — Ingrid Solano, resolved
55	
56	All four objections accepted; no decline.
57	
58	1. **Authorization-server ownership gap.** Accepted. Assumption 2 now states the authz-issuing function is a mode of `api-service`, scoped by a Role narrower than the token-verification code path in the same binary — not a phantom third deployable.
59	2. **Missing KMS-access-credential row.** Accepted. Added row #7a with the same columns as every other row, rather than leaving it as a footnote inside #7.
60	3. **Env-var exception for `DB_DSN`.** Accepted — the objection is correct that "prefer, if 03 allows" was this track declining a call it owns. Upgraded to a requirement: a `DB_DSN_FILE` convention, with the env var as a transitional fallback only. Carried into `handoff-03-auth.md` as an ask to 03.
61	4. **No RBAC on audit-log read access.** Accepted. Added a requirement under Kubernetes-specific requirements that Secret-read and audit-log-read are distinct grants.
62	
63	---
64	Model: sonnet (lead, ruling) / sonnet (Ingrid Solano, objection turn). Turns consumed: 1 (single objection-turn pattern, per `CASTING.md` §5).
65	

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "3. An **external operator agent applies manifests** to the cluster. That operator 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`, not a silent assumption.",
  "new_string": "3. An **external operator agent** — a human or automated actor outside this project, holding cluster-admin or namespace-admin rights on 04's design-only 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`, 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."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets and any cached vendor tokens | `api-service` (TOTP) and `idp-connector` (token cache), if either feature exists | 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 |",
  "new_string": "| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets and any cached vendor tokens | `api-service` (TOTP) — **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. `idp-connector` (token cache) — **also not committed**: S3's red/blue on the connector token lifecycle (in progress) is deciding whether the connector caches vendor tokens at all; current direction (Felix Adebayo's alternatives turn) is \"no cache by default, fetched fresh per `/identity` call,\" which would remove this use case too. This row is provisioned only if either feature 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 |"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "to": "04-infra-devops-47",
  "summary": "Both gating cold-read items fixed in v1",
  "message": "Thanks — both gating items fixed in `handoff-04-secrets.md`:\n\n1. Row 7: rewrote to state plainly neither TOTP nor connector token-caching is a committed feature of this submission. TOTP is a supported *value* in 05's `user_credential.method` lookup table, not a planned implementation. Token-caching is live under debate right now in S3 (connector token-lifecycle red/blue) — current direction from Felix's alternatives turn is \"no cache by default,\" which would remove that use case too. Row 7 is now explicitly a named contingency, not a live requirement — provision it only if either feature actually materializes.\n2. Assumption 3: named the operator inline (a human or automated actor with cluster/namespace-admin rights on your lab cluster who applies manifests) instead of requiring a read of your `PLAN.md` for \"amber-kubernetes.\"\n\nRest of Wesley's list (KEK/DEK, kid, RS256/ES256, JWKS, Argon2id, client-credentials, workload-identity) I'm leaving as-is — those terms are all defined or sourced in `api-auth-design.md`/`threat-model.md`, which the hand-off already points to, and re-glossing them here would duplicate content this project's own rule says shouldn't duplicate. Will follow up once S3 lands so row 6/7's contingency framing can go final either way.",
  "type": "message",
  "recipient": "04-infra-devops-47",
  "content": "Thanks — both gating items fixed in `handoff-04-s…"
}

{"success":true,"message":"“Both gating cold-read items fixed in v1” → 04-infra-devops-47 (another Claude session on this machine)","msg_id":"cb26f4d2-8a67-46dd-a5e1-d64a9c6a5a92"}

{
  "to": "helena-marsh",
  "summary": "Please resend the rest of leaf 5",
  "message": "Your leaf 5 answer got cut off mid-sentence (\"credential stuffing shows as a...\"). Send me the rest of that answer, plus the Owner and Source columns for it — that's all I need, no need to repeat leaves 1-4.",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "Your leaf 5 answer got cut off mid-sentence (\"cre…"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"c467c2ab-3c7a-4aa0-9f79-0a839ddc0e47","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"Please resend the rest of leaf 5","content":"Your leaf 5 answer got cut off mid-sentence (\"cre…"}}

{
  "to": "tomasz-wrede",
  "summary": "S3 rebuttal turn on top three",
  "message": "Your rebuttal turn, top three (your leaves 1-3). Helena's ruling: accepted Felix's \"no cache by default\" proposal (kills leaves 1 and 2's substrate), then wrote controls for the exception path only:\n\n1. Cache-key confusion: control for IF caching is ever re-opened — key must derive from immutable vendor-issued ids (our tenant id + vendor id + vendor's own opaque subject id), never request-supplied name/phone.\n2. KMS fail-open: control for IF caching is ever re-opened — KMS unreachable fails closed to \"no cache, fetch live,\" never to unencrypted write.\n3. Vendor token replay (no PoP): **accepted risk** — bearer tokens are possession-equals-authorization by design (RFC 6750), no PoP/binding lever available for a generic vendor the assignment doesn't specify; acceptable because fetch-per-call bounds the replay window to one request's execution scope, no standing cached credential to steal. Flagged as a re-review trigger if 01's vendor research ever surfaces a PoP-capable provider.\n\nYour one rebuttal turn: does this hold, or is there a hole in \"no cache by default\" or the accepted-risk reasoning on replay that Helena and Felix both missed? Keep it to the top three; I score residual right after this.",
  "type": "message",
  "recipient": "tomasz-wrede",
  "content": "Your rebuttal turn, top three (your leaves 1-3). …"
}

{"success":true,"message":"Message sent to tomasz-wrede's inbox","msg_id":"e4d2513e-4008-4d0e-a15c-9ae73ca3d770","routing":{"sender":"team-lead","target":"@tomasz-wrede","targetColor":"blue","summary":"S3 rebuttal turn on top three","content":"Your rebuttal turn, top three (your leaves 1-3). …"}}

{
  "command": "ls /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/ 2>/dev/null || echo \"no decisions dir yet\"",
  "description": "Check for existing decisions directory"
}

no decisions dir yet

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md",
  "old_string": "- **Held in memory for the shortest span that satisfies the immediate `/identity` call**, not persisted to our own database as a matter of course. If caching is required for latency/rate-limit reasons, cache with a TTL no longer than the vendor's own token expiry, encrypted at rest (same envelope-encryption requirement as the TOTP-secret case in the threat model — mechanics via KMS, owned by `../04-infra-devops/CLAUDE.md`), and keyed so one vendor-account's token is never returned to a caller resolving a different vendor account.",
  "new_string": "- **No persistent or cached token, by default.** Revised by the S3 red/blue run (`decisions/connector-token-lifecycle-redblue.md`): the token is fetched fresh from `/auth` for each `/identity` call, held only inside that single request's execution scope, and discarded when the call returns — not written to any cache or datastore as a matter of course. Caching is an explicitly-justified exception requiring its own threat re-review if latency or vendor rate limits ever force the question; if that exception is ever opened, it must satisfy: (a) cache key derived from an immutable, vendor-issued identifier (our tenant id + vendor id + the vendor's own opaque subject id) — never from request-supplied `name`/`phone`, which are attacker-influenced; (b) TTL no longer than the vendor's own token expiry, encrypted at rest (envelope encryption via KMS, mechanics owned by `../04-infra-devops/CLAUDE.md`); (c) if the KMS/envelope key is unreachable at write or read time, fail closed to \"no cache, fetch live\" for that call — never to an unencrypted write and never to a hard connector failure.\n- **Fetch-use-zeroize boundary, stated explicitly so it survives implementation:** the token variable's scope runs from the `/auth` response to the immediately following `/identity` call and no further; it is not passed up the call stack beyond the vendor-call function, and it is not reused across a retry. **A retried `/identity` call re-fetches via `/auth`; it never reuses a token held from a prior attempt** — otherwise the \"one request\" exposure window `§4`'s retry/backoff allowance quietly becomes \"however long the retry policy runs.\" Go gives no guaranteed memory zeroing without unsafe/cgo, so a crash dump taken mid-call could still capture the token in the vendor-call function's stack; that residual is accepted given the window is now one function call, not a cache TTL (core-dump suppression at the runtime level is a `../04-infra-devops/CLAUDE.md` mechanism, requirement recorded here, not owned here). The token field is excluded from any generic request/response dump used in error handling — the same log-hygiene discipline below applies to panic traces and debug dumps, not just application logs.\n- **The outbound HTTP client to the vendor must construct a fresh, isolated `Authorization` header per request, never inherited from connection reuse.** Connection pooling/keep-alive is the normal default in any HTTP client library; a pooled client that reuses a request-context object or fails to reset the auth header per call can attach request A's vendor token to request B's outbound call — the same cross-tenant leak as a cache-key collision, with no cache required. This is a required implementation discipline, not an assumption left implicit."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md",
  "old_string": "## Sources\n\n- OWASP API Security Top 10 2023, API7 (Server Side Request Forgery) and API8 (Security Misconfiguration) — both relevant to a service that makes outbound calls to a third party on a user's behalf: https://owasp.org/API-Security/editions/2023/en/0x11-t10/\n- OWASP Logging Cheat Sheet (what not to log — credentials, tokens, PII): https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html",
  "new_string": "## Sources\n\n- OWASP API Security Top 10 2023, API7 (Server Side Request Forgery) and API8 (Security Misconfiguration) — both relevant to a service that makes outbound calls to a third party on a user's behalf: https://owasp.org/API-Security/editions/2023/en/0x11-t10/\n- OWASP Logging Cheat Sheet (what not to log — credentials, tokens, PII): https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html\n\n## Attack-tree table — connector token lifecycle (S3 red/blue, 2026-09-12)\n\nFull positions, rebuttals, and ruling: `decisions/connector-token-lifecycle-redblue.md`. Table shape per `planning-approach.md` Appendix A.\n\n| # | Leaf (attack path) | Precondition | Likelihood | Impact | Blue response: Control *or* Accepted risk | Owner | Residual | Source |\n|---|---|---|---|---|---|---|---|---|\n| 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) |\n| 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 |\n| 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 fetch-per-call bounds the exposure window to one request's execution scope — no standing cached credential to steal. **Tightened per Tomasz's rebuttal:** the boundary is stated explicitly — fetch → use in the immediately following `/identity` call → zeroize; a retried `/identity` call re-fetches via `/auth` and never reuses a token from a prior attempt, so the accepted window cannot silently stretch to the length of the retry/backoff policy. | — (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 fetch's lifetime | RFC 6750 §5; RFC 9700 §2.5 |\n| 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 |\n| 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 |\n\nRules 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.\n\n---\nModel: 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."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/connector-token-lifecycle-redblue.md",
  "content": "# Decision: Connector Token Lifecycle — Red/Blue Run (S3)\n\nPattern: red team / blue team, amended per `CASTING.md` §5 ⟨02⟩. Surface: the IDP connector's handling of the vendor `access_token` (`connector-security.md` §1), against the assignment's `/auth` → `/identity` contract. Table shape: `planning-approach.md` Appendix A. This record is the full positions and rebuttals; the completed table is appended to `connector-security.md`.\n\n## Seats\n\n- **Red — Tomasz Wrede.** Ranked top five attack leaves against the design as it stood before this run.\n- **Alternatives — Felix Adebayo.** One turn between red and blue: design changes that delete a leaf outright.\n- **Blue — Helena Marsh.** Answers every leaf with a control or an explicitly accepted risk.\n- **Rebuttal — Tomasz Wrede.** One turn on the top three, after blue's answer.\n- **Lead — Marcus Ilori.** Residual scoring and ruling.\n\n## Red: Tomasz's ranked top five\n\n1. **Cache-key confusion → cross-tenant token/PII leak.** The pre-existing design said the cache is \"keyed so one vendor-account's token is never returned to a caller resolving a different vendor account\" without stating the key derives from an immutable vendor-account id rather than caller-supplied `name`/`phone`. If the key derives from request fields, an attacker who knows or guesses another user's name+phone collides with their cache entry.\n2. **Fail-open on KMS unavailability.** §1 mandated encryption at rest via KMS but never stated the failure mode if KMS was down or slow during a caching window — a plaintext-cache fallback \"to preserve availability\" would be an instant compromise path.\n3. **Vendor token replay, no binding to caller/session.** The cached token, once decrypted for use, had no stated binding (no DPoP-style proof-of-possession, no IP/session pinning); anyone reading it during its TTL could replay it against the vendor for the remaining TTL.\n4. **Process-memory/crash-dump exposure.** The plaintext token transits application memory before any encryption happens; no stated memory-scrubbing or core-dump suppression.\n5. **Connector as a credential-stuffing oracle against the vendor.** Rate-limiting was stated (\"independent of the vendor's own limits\") without stated granularity — per-caller, per-IP, or global.\n\nNoted but not in the top five (Tomasz's own list, kept for the record, not scored in this run): long vendor-token TTLs treated as inherently acceptable without a stated ceiling; a concurrent-refresh race causing a thundering herd against vendor `/auth`; scope-narrowing silently dropped for vendors that don't support scoping.\n\n## Alternatives: Felix's turn\n\nApplied \"what if the connector held no token at all?\" against the specific five, not in the abstract:\n\n- **Leaves 1 and 2 deleted by the same design change:** make caching forbidden by default rather than merely optional. Fetch a fresh vendor token per `/identity` call, hold it only inside that request's execution scope, discard on return. No cache → no cache key → leaf 1 has no substrate to exist in. No cache → no KMS-encrypted-at-rest dependency in the hot path → leaf 2's failure window doesn't exist.\n- **Leaf 4 shrunk, not deleted:** a token living only inside one request's stack for one outbound call is a much smaller target than one sitting in an encrypted cache with a multi-minute TTL, but it still exists in memory while in use — that's physics, not a design flaw to wish away.\n- **Leaves 3 and 5 not eliminated, stated plainly rather than stretched for:** replay resistance requires vendor-side PoP support the assignment's generic ABC/XYZ contract doesn't give us — \"hold no token\" narrows the exposure window but doesn't change the vendor's own bearer-token semantics. Leaf 5 is a rate-limiting problem on our own `/auth` pass-through, not a token-custody problem — no change to how we hold the token touches how often a caller can hit us.\n- **Net proposal:** replace \"TTL-bounded encrypted cache, optional\" with \"no persistent or cached token; fetched fresh and scoped to the single `/identity` request\" as the default, with caching as an explicitly-justified exception requiring its own re-review. Flagged honestly: does nothing for replay or rate-limiting, and may add a vendor round-trip per call — Helena's tradeoff to weigh against latency.\n\n## Blue: Helena's ruling and answers\n\n**On Felix's proposal:** accepted. Not a reversal of §1 — a tightening of language that already made caching conditional into a hard default: caching is forbidden unless an explicit exception is opened, with its own re-review. Controls are written for the exception path only, since the default posture has no substrate for leaves 1 and 2 to attack.\n\n| # | Leaf | Blue response | Owner | Source |\n|---|---|---|---|---|\n| 1 | Cache-key confusion | Control, exception-path only: any future caching exception must derive the key from an immutable, vendor-issued identifier (our tenant id + vendor id + the vendor's own opaque subject id) — never from request-supplied `name`/`phone`. Same object-level-authorization discipline as scope checking on the search API; a cache key is an authorization boundary. | 03, if exception ever opened | OWASP API1:2023 (BOLA) |\n| 2 | KMS fail-open | Control, exception-path only: if the envelope key is unreachable, cache write/read fails closed to \"no cache\" for that call — a live vendor fetch, not an unencrypted write and not a hard connector failure. | 03/04 (KMS mechanism is 04's) | NIST SP 800-57 |\n| 3 | Replay, no PoP | Accepted risk. Bearer tokens under RFC 6750 are possession-equals-authorization by design; PoP/binding needs vendor-side support not assumable for a generic vendor. Acceptable for this system because fetch-per-call bounds the window to one request's execution scope. Re-review trigger: a PoP-capable vendor surfacing in 01's research. | — | RFC 6750 §5; RFC 9700 §2.5 |\n| 4 | Memory/crash-dump exposure | Control: exclude the token field from any generic request/response dump used in error handling (panics, debug dumps — same discipline as logs); scope the variable to the narrowest function, no passing beyond the vendor-call function. Residual accepted: Go gives no guaranteed memory zeroing without unsafe/cgo, so a crash dump mid-call could still capture it — acceptable given the window is one function call, not a cache TTL. Core-dump suppression is a 04 mechanism, requirement recorded here. | 03 (code discipline) / 04 (runtime config) | OWASP Logging Cheat Sheet |\n| 5 | Credential-stuffing oracle | 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 high failure ratio before high volume), paired with exponential backoff per identity attempted. Closes the granularity gap §4 already gestured at rather than adding a new requirement. | 03 (rate-limit logic) / 04 (shared store/edge mechanism, if gateway-enforced) | OWASP API4:2023; NIST SP 800-63B §5.2.2 |\n\n## Rebuttal: Tomasz's turn on the top three\n\n- **Leaf 1 — conceded, conditional.** The persistent-cache variant is dead: no cache, no key-collision cache hit. But \"no cache by default\" only kills the storage leaf, not a connection-reuse variant Helena and Felix didn't address: a pooled/keep-alive HTTP client that doesn't reset the `Authorization` header per call can attach request A's token to request B's outbound call — same cross-tenant leak, zero cache required. Asked for an explicit requirement that the outbound client construct a fresh, isolated auth header per request, not per pooled connection.\n- **Leaf 2 — conceded outright.** No cache removes the write-time KMS dependency; the exception-path fail-closed control is exactly right. No hole found.\n- **Leaf 3 — held, with a boundary condition, not reopening the ruling.** Agrees bearer + no PoP for a generic vendor is a real constraint, not a design failure, and fetch-per-call shrinks the window. But \"one request's execution scope\" needed the boundary stated explicitly: fetch → use in the immediately following call → zeroize, and specifically whether a retried `/identity` call (§4 permits retry/backoff) reuses the same token or forces a fresh `/auth` — if it reuses, the accepted window is however long the retry policy runs, not \"one call.\"\n\n## Ruling (Marcus Ilori)\n\nBoth of Tomasz's rebuttal points are accepted as tightenings, not reopenings of Helena's ruling, and are folded into `connector-security.md` §1 directly:\n\n1. **Leaf 1, connection-reuse variant — closed.** Added as a required implementation discipline: the outbound HTTP client to the vendor must construct a fresh, isolated `Authorization` header per request, never inherited from connection reuse.\n2. **Leaf 3, boundary — tightened.** Added explicit fetch-use-zeroize language: the token's scope runs from the `/auth` response to the immediately following `/identity` call and no further; a retried `/identity` call re-fetches via `/auth` and never reuses a token from a prior attempt.\n\nResidual risk: leaves 1, 2, 4, 5 score **L** after blue's response and this run's tightening — each has either had its substrate eliminated by design or a checkable control that closes the gap Tomasz named. Leaf 3 scores **M**: accepted, not eliminated, because it is a genuine vendor-contract limitation this project has no lever to remove, not a design gap left unaddressed. No leaf scores **H**; no follow-up Story is required. Leaf 3's **M** is named here as the one residual risk Warren should see plainly in the artifact, per the amendment's own rule.\n\n---\nModel: sonnet (Tomasz Wrede, red + rebuttal; Felix Adebayo, alternatives; Helena Marsh, blue) / sonnet (Marcus Ilori, lead, ruling and residual scoring). Turns consumed: 5 (red top-five, alternatives, blue, rebuttal, lead ruling) — matches the 4-turns-plus-lead budget in `PLAN.md` §3.\n"
}

File created successfully at: /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/connector-token-lifecycle-redblue.md (file state is current in your context — no need to Read it back)

{
  "to": "tomasz-wrede",
  "summary": "S3 closed — both rebuttal points folded in",
  "message": "S3 closed. Both your rebuttal points accepted as tightenings, not reopenings: the connection-reuse variant on leaf 1 is now a required control (fresh, isolated Authorization header per outbound request, never inherited from pooled connections), and leaf 3's boundary is now explicit (fetch → use in the immediately following call → zeroize; retries re-fetch via /auth, never reuse). Residual: L on leaves 1/2/4/5, M (accepted) on leaf 3 — no H, no follow-up Story. Full record in `decisions/connector-token-lifecycle-redblue.md`, table in `connector-security.md`. Good work — the connection-reuse catch on leaf 1 was the sharpest thing in this run. Hold for your next seat.",
  "type": "message",
  "recipient": "tomasz-wrede",
  "content": "S3 closed. Both your rebuttal points accepted as …"
}

{"success":true,"message":"Message sent to tomasz-wrede's inbox","msg_id":"f7ef2a0c-dbaf-4d78-aa7b-8f93b838dbbe","routing":{"sender":"team-lead","target":"@tomasz-wrede","targetColor":"blue","summary":"S3 closed — both rebuttal points folded in","content":"S3 closed. Both your rebuttal points accepted as …"}}

{
  "to": "03-engineering-delivery-b7",
  "summary": "Connector token-lifecycle red/blue done — requirement set for your opus seat",
  "message": "S3 (connector token lifecycle red/blue) is finalized: `02-ai-security-architecture/connector-security.md` §1 now states the no-cache-by-default posture (fetch-per-`/identity`-call, discard on return; caching is an explicitly-justified exception requiring re-review), plus two implementation-level requirements your opus token-lifecycle seat should build straight from: (1) the outbound HTTP client to the vendor must construct a fresh, isolated `Authorization` header per request, never inherited from connection pooling/keep-alive; (2) the token's scope is fetch → use in the immediately-following `/identity` call → zeroize — a retried call re-fetches via `/auth`, never reuses a token from a prior attempt. Full attack-tree table and reasoning in `connector-security.md`'s new section and `decisions/connector-token-lifecycle-redblue.md` if you want the \"why.\" This is run once, here — no need for a second red/blue on your side. Next up here: S4 (authz-scoping adversarial pair), then `handoff-03-auth.md` follows shortly after.",
  "type": "message",
  "recipient": "03-engineering-delivery-b7",
  "content": "S3 (connector token lifecycle red/blue) is finali…"
}

{"success":true,"message":"“Connector token-lifecycle red/blue done — requirement set for your opus seat” → 03-engineering-delivery-b7 (another Claude session on this machine; it is also connected via Remote Control)","msg_id":"2f24cc63-1ddf-4e0d-ae8b-f7367e105474"}

{
  "to": "helena-marsh",
  "summary": "S4 — draft the authz-scoping proposal",
  "message": "Your seat: S4, adversarial pair, Proposer. Draft the search-API authorization-scoping proposal against `./api-auth-design.md`'s existing scope sketch (`profile:read:own`, `profile:read:any`, `profile:search`) and its object-level-authorization paragraph. I need this concrete enough for 03 to build against directly (this feeds `handoff-03-auth.md`, S6):\n\n- The final scope vocabulary — confirm or revise the three scopes, and be explicit about what each one authorizes and what it doesn't.\n- Who gets `profile:search` at all — it's the dangerous one (query by name/phone fragment across the table is a PII enumeration engine per the threat model), so name the provisioning bar for it explicitly, not just \"a small number of back-office callers.\"\n- The object-level policy hook — how a `profile:read:any`-scoped caller's access is still constrained per-request (e.g., a partner integration scoped only to its own referred users), concrete enough that 03 can implement a policy check, not just a scope check.\n- Pagination ceiling and per-client rate limit as requirements (already gestured at in `api-auth-design.md` — make them concrete numbers or a concrete rule, since 03 needs something to build against, not \"a hard ceiling\").\n\nIngrid gets numbered objections after this, each with a \"what would change my mind\" line; you answer every one in writing (revise or decline, never silently). I rule after that.",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "Your seat: S4, adversarial pair, Proposer. Draft …"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"45e651fe-35c5-454c-929c-417a18f9948d","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"S4 — draft the authz-scoping proposal","content":"Your seat: S4, adversarial pair, Proposer. Draft …"}}

{
  "to": "ingrid-solano",
  "summary": "S4 — objections on Helena's authz-scoping proposal",
  "message": "Your seat: S4, adversarial pair, Skeptic. Helena's proposal on search-API authorization scoping:\n\n**Scopes:** `profile:read:own` (id lookup, constrained to a caller_referral mapping — not a search), `profile:read:any` (id lookup, no referral constraint, requires a logged reason_code since prevention isn't available there), `profile:search` (fuzzy name/phone query, its own gated capability, not \"read:any plus search\").\n\n**profile:search provisioning bar (all four required):** named service identity, not shared team credential; documented business function on file before provisioning; change-controlled approval with named human approver, time-boxed re-approval every 90 days; tighter rate/result limits than any other scope.\n\n**Object-level policy hook:** `authorize(sub, scope, target)` runs after the scope check — read:own checks `caller_referral` membership; read:any requires a logged `reason_code`; search additionally enforces the result cap, rejecting outright (not truncating) a query that would exceed it unconstrained.\n\n**Pagination/rate limits:** cursor-based (not offset), default page 20 / ceiling 50; rate limits 60 req/min for read:own/read:any, 10 req/min for search, with alerting on sustained near-limit usage.\n\nPer the §5 amendment: numbered objections, each ending with a one-line \"what would change my mind.\" Helena answers every one in writing — revise or decline, never silently. I rule after that.",
  "type": "message",
  "recipient": "ingrid-solano",
  "content": "Your seat: S4, adversarial pair, Skeptic. Helena'…"
}

{"success":true,"message":"Message sent to ingrid-solano's inbox","msg_id":"29578537-08d3-43b7-b88e-3fe7444c4005","routing":{"sender":"team-lead","target":"@ingrid-solano","targetColor":"purple","summary":"S4 — objections on Helena's authz-scoping proposal","content":"Your seat: S4, adversarial pair, Skeptic. Helena'…"}}

{
  "to": "helena-marsh",
  "summary": "S4 — answer Ingrid's five objections",
  "message": "Ingrid's five numbered objections on your S4 proposal. Answer every one in writing — revise or decline, never silently.\n\n1. Scope vocabulary built before callers were listed — no enumerated table of which named calling services/roles need which scope, so can't tell if read:any is invented for symmetry rather than a real need.\n2. read:any's `reason_code` is freeform, not a controlled vocabulary — worthless in a six-month-later audit, and an order of magnitude looser than search's provisioning bar for a scope that's less constrained at query time.\n3. `caller_referral` membership (read:own's entire control) has no stated owner, change process, or approval — the narrowest scope has the least rigor, making it the softer target.\n4. \"Reject outright\" on over-cap queries stops single-request enumeration but not decomposition — a caller at 10 req/min can still walk the namespace in slices and reassemble the population over time; alerting only covers sustained near-limit usage, which a slow enumerator won't trigger.\n5. 90-day re-approval is a calendar control, not a lifecycle control — nothing ties revocation to offboarding/role-change, so a grant can survive up to 89 days past when it should've been pulled.\n\nI rule once you've answered all five.",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "Ingrid's five numbered objections on your S4 prop…"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"f2a73b18-d7b6-48ae-828f-4d36f6a50e87","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"S4 — answer Ingrid's five objections","content":"Ingrid's five numbered objections on your S4 prop…"}}

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "## Authorization model: scopes, not just \"authenticated\"\n\nThe threat model (`threat-model.md`, Asset 2) already names the core risk: an authenticated-but-unscoped search/retrieve endpoint is a PII enumeration engine. Authentication answers \"who is calling\"; it does not answer \"what may they see.\" This API needs both.\n\n- **Scopes**, carried in the JWT `scope` claim, e.g. `profile:read:own`, `profile:read:any`, `profile:search`. A given client-credential is provisioned with the narrowest scope its actual use case requires — most integrations should get `profile:read:own` (retrieve a specific known record by id, e.g. resolving a record the caller already has a legitimate reference to) rather than `profile:search` (query by name/phone fragments across the table), which should be reserved for a small number of explicitly-provisioned back-office callers.\n- **Object-level authorization is enforced per request, not just per token.** Holding `profile:read:any` scope is necessary but not sufficient — every retrieve/search call is logged (see below) and, where the caller model supports it, additionally checked against a resource-level policy (e.g., a partner integration scoped to only its own referred users) rather than trusting the coarse scope alone. This directly targets OWASP API1:2023 (Broken Object Level Authorization), cited in the threat model.\n- **Search results are paginated with a hard page-size ceiling** and rate-limited per client, independent of the scope check — a legitimately-scoped caller doing an anomalously large number of sequential searches is still a signal worth throttling and alerting on, not just permitting because the token was valid.",
  "new_string": "## Authorization model: scopes, not just \"authenticated\"\n\nThe threat model (`threat-model.md`, Asset 2) already names the core risk: an authenticated-but-unscoped search/retrieve endpoint is a PII enumeration engine. Authentication answers \"who is calling\"; it does not answer \"what may they see.\" This API needs both.\n\nFinalized by the S4 adversarial pair (`decisions/search-authz-scoping.md`; Helena Marsh, Proposer; Ingrid Solano, Skeptic) — this section supersedes the earlier sketch.\n\n### Scope vocabulary\n\n- **`profile:read:own`** — retrieve a single record by an id the caller already holds a legitimate reference to (e.g., a partner resolving a user it referred). Enforced against a `caller_referral` mapping (below), not by scope alone. Does not authorize search/query by name or phone fragment.\n- **`profile:read:any`** — retrieve a single record by id, no referral constraint. Not a default grant: provisioning requires an entry in an explicit caller-role table (service name, business justification, and specifically *why* `read:own`'s referral constraint is insufficient for that caller's function), gated the same way `profile:search` is below. If no caller meets that bar, the scope stays defined but unissued.\n- **`profile:search`** — query by name/phone fragment across the table; the PII-enumeration-engine risk the threat model names. Its own gated capability, not \"`read:any` plus search.\"\n\n### `profile:search` provisioning bar (all four required)\n\n1. Named service identity — never a shared client credential across a team.\n2. Documented business function on file before provisioning, not granted speculatively.\n3. Change-controlled approval with a named human approver, logged.\n4. Tighter rate/result limits than any other scope (below).\n\n### Object-level policy hook\n\nA per-scope policy function `authorize(sub, scope, target)` runs after the scope check, not instead of it — directly targeting OWASP API1:2023 (Broken Object Level Authorization):\n\n- **`read:own`**: checks `target.id` against the `caller_referral` mapping. Scope-valid but outside the caller's referral set → reject, logged as a policy denial (distinct from an auth failure, for detection). `caller_referral` entries are data owned by `../05-data-ops/CLAUDE.md`, written only through the same partner-onboarding workflow as any other provisioning decision (named approver, logged) — no ad hoc inserts.\n- **`read:any`**: requires a `reason_code` from a closed, versioned enum (`support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`) logged with the audit record; adding a value to the enum requires a documented change. Freeform justification text is not acceptable — an unaudit-able reason code is the same gap as no reason code, six months later.\n- **`profile:search`**: additionally enforces the per-query result cap; a query that would exceed it unconstrained (e.g., a bare wildcard) is rejected outright, not truncated.\n\n### Pagination, rate limits, and decomposition resistance\n\n- **Cursor-based pagination**, not offset — offset walks turn a capped page size into full-table enumeration. Default page 20, hard ceiling 50.\n- **Per-client-credential rate limits**: 60 req/min for `read:own`/`read:any`, 10 req/min for `profile:search`.\n- **Cumulative distinct-record-touch counter per caller per rolling window** (e.g., no more than N distinct profiles returned to one credential per 24h without a fresh `reason_code`/justification), tracked independently of per-minute rate. A single-request cap and per-minute throttling only stop single-request or bursty enumeration; a caller stayng under both limits can still walk the namespace in slices and reassemble the population over time (decomposition) — this counter is what catches that pattern regardless of how slowly it's spread. Counting-store mechanism is 03/04's to build; the requirement that volume is measured cumulatively, not just per-minute, is set here.\n- Sustained near-limit usage on any of the above alerts, not just hard-blocks at the ceiling.\n\n### Grant lifecycle\n\n- **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."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "## Sources\n\n- RFC 6749 (OAuth 2.0), §4.4 Client Credentials Grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4\n- RFC 7519 (JSON Web Token): https://datatracker.ietf.org/doc/html/rfc7519\n- OWASP API Security Top 10 2023, API1 (Broken Object Level Authorization) and API3 (Broken Object Property Level Authorization): https://owasp.org/API-Security/editions/2023/en/0x11-t10/",
  "new_string": "## Objections considered (S4 adversarial pair)\n\nFull 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.\n\n## Sources\n\n- RFC 6749 (OAuth 2.0), §4.4 Client Credentials Grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4\n- RFC 7519 (JSON Web Token): https://datatracker.ietf.org/doc/html/rfc7519\n- OWASP API Security Top 10 2023, API1 (Broken Object Level Authorization) and API3 (Broken Object Property Level Authorization): https://owasp.org/API-Security/editions/2023/en/0x11-t10/\n- NIST SP 800-63B (identity/authorization lifecycle, offboarding-triggered revocation) — cited in `decisions/search-authz-scoping.md`"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

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

File created successfully at: /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/search-authz-scoping.md (file state is current in your context — no need to Read it back)

{
  "command": "ls /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md 2>/dev/null && echo EXISTS || echo \"does not exist yet\"",
  "description": "Check if handoff-03-auth.md already exists"
}

does not exist yet

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "content": "# Hand-off 02 → 03: Auth scheme, validation point, and authorization requirements\n\nStatus: **v1**. Receiver: Renata Cole, `../03-engineering-delivery/`. Written to the project's hand-off standard: 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 decision records. Full reasoning, if wanted: `api-auth-design.md`, `decisions/search-authz-scoping.md`, `decisions/connector-token-lifecycle-redblue.md`.\n\n## Token scheme\n\n- **Grant type:** OAuth2 client-credentials. Machine-to-machine only; no end-user login flow for question 2's API.\n- **Token format:** JWT, signed, asymmetric (RS256 or ES256 — pick one and use it consistently; RS256 is the safer default if your Go JWT library's ES256 support is less mature).\n- **Claim set (minimum):** `sub` (calling client identity), `scope` (space-delimited, values below), `exp`, `iat`, `aud` (this API, specifically — reject tokens minted for another audience).\n- **TTL:** 5–15 minutes. No refresh tokens — the client re-authenticates with its own client secret on expiry.\n- **No denylist.** Revocation is handled by TTL shortness, not a stateful lookup. Don't build one; it's not missing, it's a deliberate trade-off already reasoned through in `api-auth-design.md`.\n\n## Where it's validated\n\n- **Middleware at the API edge**, in `internal/api/` per your published service boundary — every request to `cmd/api-service` passes through token validation before reaching a handler. `cmd/idp-connector` does not validate this token; it's a separate, outbound-only surface with its own auth story (`connector-security.md`), not a consumer of this scheme.\n- **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 `api-service`; it lives with the token-issuing function, which is a mode of `api-service` (not a separate binary — see `handoff-04-secrets.md` Assumption 2), scoped by RBAC so the verification code path and the issuing code path don't share Secret access even though they're the same binary.\n- **Key rotation:** expect a `kid` claim; publish old and new public keys together during rotation overlap. Token TTL (5–15 min) bounds how long that overlap needs to last.\n\n## Scope vocabulary (final, from S4 — `decisions/search-authz-scoping.md`)\n\n| Scope | Authorizes | Does not authorize | Object-level check |\n|---|---|---|---|\n| `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 `caller_referral` mapping (data owned by `../05-data-ops/`); out-of-set → reject, logged as a policy denial, distinct from an auth failure |\n| `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 |\n| `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 |\n\n`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`.\n\n**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.\n\n## Pagination, rate limits, decomposition resistance (requirements — numbers are fixed, mechanism is yours)\n\n- **Cursor-based pagination only** — no offset-based paging. Default page size 20, hard ceiling 50.\n- **Per-client-credential rate limits:** 60 req/min for `read:own`/`read:any`; 10 req/min for `profile:search`.\n- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that catches slow, under-the-cap enumeration (decomposition) that per-request and per-minute limits alone miss. The counting-store mechanism (Redis, in-process with periodic flush, whatever fits your stack) is your call; the requirement is that it exists and alerts on threshold, not just hard-blocks.\n- Sustained near-limit usage on any of the above should alert, not just silently throttle.\n\n## Audit-log field list (every search/retrieve call)\n\nLog these fields, and only these — see `handoff-04-secrets.md`'s never-log list for what must never appear here:\n\n- `sub` (caller identity)\n- `scope` used\n- record id(s) touched (opaque ids, not the PII values)\n- `reason_code`, when the scope is `profile:read:any`\n- policy decision (`allow` / `deny`, and if `deny`, whether it was a scope failure or an `authorize()` policy denial — these are distinct signals for detection)\n- timestamp\n- request outcome (success/failure/rate-limited)\n\nNever in this log: PII field values, full JWTs, full request/response bodies. Per `handoff-04-secrets.md`'s new requirement, this log stream itself needs read access distinct from and narrower than whatever can read Secrets — that's 04's mechanism, but don't let the log ship without asking whether that separation exists.\n\n## What's not yours to decide (already decided upstream, don't re-derive)\n\n- **Grant type, token format, and claim set** — decided in `api-auth-design.md`; not open for re-litigation during implementation.\n- **Scope vocabulary and provisioning bars** — decided in S4 (`decisions/search-authz-scoping.md`); if a real implementation constraint makes one of these unworkable, flag it back to me rather than adjusting it unilaterally.\n- **The `DB_DSN_FILE` convention** — per `handoff-04-secrets.md`'s S7 revision, this track is asking you to add a file-based alternative to `DB_DSN` (env var becomes a transitional fallback, not a permanent equal option), because a DSN's embedded password is exposed by `kubectl describe`/crash dumps/child-process environment the same as any other secret in that inventory. This is a request into your config surface, not a unilateral change on my part — you decide the exact mechanism (a `_FILE` suffix convention or otherwise), I'm asserting the requirement.\n- **Password/client-secret hashing** — Argon2id, decided in `threat-model.md` Asset 1; not this hand-off's concern beyond noting it exists.\n- **PII retention/caching duration for anything the API returns** — `../05-data-ops/CLAUDE.md`'s call, not this track's or yours.\n- **Whether `read:any` ever gets issued to a real caller** — per S4, the scope stays defined but unissued unless a caller clears the provisioning bar (caller-role table entry, named approver). Don't wire a default grant \"just in case.\"\n\n## Open question back to you\n\nNothing blocking. One thing worth a quick confirm when convenient: does your `internal/api/` middleware layer have a natural place to run the object-level `authorize()` check as a distinct step from scope validation (e.g., a second middleware or an explicit call inside each handler before the DAO call), or would you rather this track propose a specific Go interface shape for it? Either is fine — say which you'd find more useful and I'll adjust.\n\n---\nModel: sonnet (Marcus Ilori, lead — compiled directly from S4's ruling, no new debate). Turns consumed: 0 hire turns (synthesis of already-ruled decisions per `PLAN.md` S6).\n"
}

File created successfully at: /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md (file state is current in your context — no need to Read it back)

{
  "to": "03-engineering-delivery-b7",
  "summary": "handoff-03-auth.md ready — token scheme, scopes, audit fields",
  "message": "`02-ai-security-architecture/handoff-03-auth.md` is written and ready for your middleware. Covers: token scheme (client-credentials → JWT, RS256/ES256, claims sub/scope/exp/iat/aud, TTL 5-15 min, no refresh, no denylist), where it's validated (middleware at the api-service edge, public-key verification only), the final S4 scope vocabulary (`profile:read:own`/`profile:read:any`/`profile:search` with their object-level `authorize()` hook shape and the `reason_code` closed enum), pagination/rate-limit/decomposition-resistance requirements with concrete numbers, the audit-log field list, and an explicit \"not yours to decide\" list so nothing gets re-derived. One open, non-blocking question at the bottom about where `authorize()` best fits your middleware layer — answer whenever convenient. Also flagging: this hand-off carries a request into your config surface — a `DB_DSN_FILE` convention alongside `DB_DSN` (mechanism is yours, requirement is `handoff-04-secrets.md`'s S7 revision).",
  "type": "message",
  "recipient": "03-engineering-delivery-b7",
  "content": "`02-ai-security-architecture/handoff-03-auth.md` …"
}

{"success":true,"message":"“handoff-03-auth.md ready — token scheme, scopes, audit fields” → 03-engineering-delivery-b7 (another Claude session on this machine; it is also connected via Remote Control)","msg_id":"024754c3-06d7-4ded-b901-40dcbee72625"}

{
  "to": "tomasz-wrede",
  "summary": "Re-run show_profile.py — portrait now on disk",
  "message": "Small fix: your portrait finished rendering after your first tool call, so your pane may still show name-only. Re-run the show_profile.py command from your agent definition (`--profile ./profiles/tomasz-wrede/tomasz-wrede.md --root .`) to pick it up. No other action needed.",
  "type": "message",
  "recipient": "tomasz-wrede",
  "content": "Small fix: your portrait finished rendering after…"
}

{"success":true,"message":"Message sent to tomasz-wrede's inbox","msg_id":"1673de7c-4b88-407b-8b5a-6444b2b9b7fc","routing":{"sender":"team-lead","target":"@tomasz-wrede","targetColor":"blue","summary":"Re-run show_profile.py — portrait now on disk","content":"Small fix: your portrait finished rendering after…"}}

{
  "to": "helena-marsh",
  "summary": "Re-run show_profile.py — portrait now on disk",
  "message": "Small fix: your portrait finished rendering after your first tool call, so your pane may still show name-only. Re-run the show_profile.py command from your agent definition (`--profile ./profiles/helena-marsh/helena-marsh.md --root .`) to pick it up. No other action needed.",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "Small fix: your portrait finished rendering after…"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"24069964-90f3-42c6-9789-a0cddf638aaa","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"Re-run show_profile.py — portrait now on disk","content":"Small fix: your portrait finished rendering after…"}}

{
  "to": "felix-adebayo",
  "summary": "Re-run show_profile.py — portrait now on disk",
  "message": "Small fix: your portrait finished rendering after your first tool call, so your pane may still show name-only. Re-run the show_profile.py command from your agent definition (`--profile ./profiles/felix-adebayo/felix-adebayo.md --root .`) to pick it up. No other action needed.",
  "type": "message",
  "recipient": "felix-adebayo",
  "content": "Small fix: your portrait finished rendering after…"
}

{"success":true,"message":"Message sent to felix-adebayo's inbox","msg_id":"731254c4-813a-4da9-8a2b-826e0b2fcf5b","routing":{"sender":"team-lead","target":"@felix-adebayo","targetColor":"yellow","summary":"Re-run show_profile.py — portrait now on disk","content":"Small fix: your portrait finished rendering after…"}}

{
  "to": "ingrid-solano",
  "summary": "Re-run show_profile.py — portrait now on disk",
  "message": "Small fix: your portrait finished rendering after your first tool call, so your pane may still show name-only. Re-run the show_profile.py command from your agent definition (`--profile ./profiles/ingrid-solano/ingrid-solano.md --root .`) to pick it up. No other action needed.",
  "type": "message",
  "recipient": "ingrid-solano",
  "content": "Small fix: your portrait finished rendering after…"
}

{"success":true,"message":"Message sent to ingrid-solano's inbox","msg_id":"7c295b0f-076e-4411-9e3e-282e6fc95b33","routing":{"sender":"team-lead","target":"@ingrid-solano","targetColor":"purple","summary":"Re-run show_profile.py — portrait now on disk","content":"Small fix: your portrait finished rendering after…"}}

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

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

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/CLAUDE.md",
  "old_string": "Phase 1 (org planning): `PLAN.md` in this directory is the track plan — eleven Stories, a four-hire roster (Adversary, Principled Architect, Tinkerer, Designated Skeptic), the debate plan, and dependencies; `../CASTING.md` §5 ratified with four ⟨02⟩ amendments; `planning-approach.md` gained Appendix A (attack-tree template) and Appendix B (harness constraints). Awaiting team-lead's \"hiring go\" before any persona or agent definition is created.\n\nNext: available for `03-engineering-delivery` to implement against; open to review/adjustment as data-ops' schema and engineering's implementation surface any gaps.",
  "new_string": "Phase 1 (org planning): `PLAN.md` in this directory is the track plan — eleven Stories, a four-hire roster (Adversary, Principled Architect, Tinkerer, Designated Skeptic), the debate plan, and dependencies; `../CASTING.md` §5 ratified with four ⟨02⟩ amendments; `planning-approach.md` gained Appendix A (attack-tree template) and Appendix B (harness constraints).\n\nPhase 2 (execution): all four hires spawned and live as named teammates in this session. Completed: **S7** — `handoff-04-secrets.md` v1, Ingrid Solano's objection turn folded in (four objections, all accepted), sent to and cold-read by 04's Newcomer, two gating items fixed. **S3** — red/blue on the connector token lifecycle (Tomasz Wrede red, Felix Adebayo alternatives, Helena Marsh blue, Tomasz rebuttal, Marcus residual scoring); `connector-security.md` §1 rewritten to a no-cache-by-default posture with two hardened implementation controls (fresh auth header per request, explicit fetch-use-zeroize boundary); attack-tree table appended; full record in `decisions/connector-token-lifecycle-redblue.md`; residual all L except one accepted M (bearer-token replay, no vendor PoP lever), no follow-up Story required; handed to 03's opus token-lifecycle seat. **S4** — adversarial pair on search-API authz scoping (Helena proposes, Ingrid five numbered objections, Helena revises all five, Marcus rules); `api-auth-design.md` gained a finalized scope vocabulary, provisioning bars, object-level policy hook, decomposition-resistant rate limiting, and lifecycle-triggered revocation; full record in `decisions/search-authz-scoping.md`. **S6** — `handoff-03-auth.md` written and sent to Renata Cole (03): token scheme, validation point, S4's scope vocabulary, audit-log fields, \"not yours to decide\" list.\n\nRemaining: S5 (structured written debate on `ai-workflow-narrative.md`'s core claim, Felix/Ingrid), S8 (independent second review of the security-graded docs), S9 (revise `ai-workflow-narrative.md` for the org layer), S10 (threat-model.md maintenance), S1/S2 already folded into `CASTING.md`/`planning-approach.md` in Phase 1. S11 deferred to Warren's code go-ahead.\n\nNext: S5 or S8, lead's call on sequencing; open to review/adjustment as 03's and 05's implementation surfaces any gaps in the S3/S4/S6 hand-offs."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/CLAUDE.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "offset": 7,
  "limit": 9
}

7	| Track | Lead | Status | Blocking on | Blocked by | Planning notes | Hires (planned / registered / spawned) | Last updated |
8	|---|---|---|---|---|---|---|---|
9	| Orchestration (root) | Dana Whitfield | Phase 2 complete — all 18 hires live in five lead sessions; Phase 3 debates under way | 02 hand-offs to 03/04; 05 S1 contract; first `decisions/` artifacts | — | `PLAN.md`, `LOG.md` | 18 / 18 (cap) | 2026-09-12 |
10	| Cross-track consistency pass (root, Phase 3) | Dana Whitfield | not started | all five `plan approved` | — | `PLAN.md` Phase 3 | — | 2026-09-12 |
11	| 01 Product & Industry Research (incl. Design) | Naomi Voss | plan approved — S1–S5 done (claims audit, password-baseline debate, connector rationale hardened + cold read, search-authz requirements, UX notes); S6 optional (Wesley loan turn 2 requested, 1/4 used) | — | — | `01-product-industry-research-design/PLAN.md`; `decisions/claims-audit.md`, `decisions/password-baseline-debate.md`, `decisions/rationale-cold-read.md` all written; Newcomer loan from 04 (`wesley-okonkwo`) used for S3, turn 2 requested for S6 | 3 / 3 / 3 | 2026-09-12 |
12	| 02 AI Architecture & Security Architecture | Marcus Ilori | hires spawned 4/4 — ready for S3/S4 debates | — | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 4 | 2026-09-12 |
13	| 03 Engineering & Delivery | Renata Cole | hires spawned 4/4 — awaiting inputs | 05 contract (DAO), 02 auth hand-off (middleware) | — | `03-engineering-delivery/PLAN.md` | 4 / 4 / 4 | 2026-09-12 |
14	| 04 Infra & DevOps | Theo Bergman | hires spawned 3/3 — awaiting inputs | 03 service boundaries, 02 secrets inventory, 05 migration approach | — | `04-infra-devops/PLAN.md` | 3 / 3 / 3 | 2026-09-12 |
15	| 05 Data Ops | Priya Nandakumar | hires spawned 4/4 — S4 drafted, S2/S3 debates next | — | — | `05-data-ops/PLAN.md`; 6 stories S1–S6, S1 = Go-shaped contract in `multi-db-strategy.md` (critical path); S4 `migration-approach.md` + S5 retention table unblock 04; `migration-approach.md` drafted for 04 (R1–R5; single-runner requirement is platform-enforced — pg_advisory_lock is unavailable on CockroachDB), pending one objection turn; factory mismatch closed with 03 direct (two-party): `dao.Repository` composite exposing `Profiles()`/`Credentials()`/`Methods()`, `dao.New` signature unchanged — cited in S1 | 4 / 4 / 4 | 2026-09-12 |

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "old_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | hires spawned 4/4 — ready for S3/S4 debates | — | — | `02-ai-security-architecture/PLAN.md`; `CASTING.md` §5 ratified with 4 amendments; `planning-approach.md` App. A + B; personas + agent defs written, registry rows appended | 4 / 4 / 4 | 2026-09-12 |",
  "new_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | S3, S4, S6, S7 done — S5/S8/S9/S10 next | — | — | `02-ai-security-architecture/PLAN.md`; S3 `decisions/connector-token-lifecycle-redblue.md` + table in `connector-security.md`; S4 `decisions/search-authz-scoping.md` + finalized scoping in `api-auth-design.md`; S6 `handoff-03-auth.md` sent to 03; S7 `handoff-04-secrets.md` v1 sent to 04, cold-read and fixed | 4 / 4 / 4 | 2026-09-12 |"
}

The file /Users/warrenthompson/Source/LoginID/PLANNING.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "to": "org-planning-loginid-takehome",
  "summary": "02: S3, S4, S6, S7 done — both hand-offs sent",
  "message": "02 update: S7 (secrets hand-off, 04) and S3 (connector token-lifecycle red/blue) landed, then S4 (search-authz adversarial pair) and S6 (auth hand-off, 03) followed. All four durable artifacts written with §5 footers (model/turns): `decisions/connector-token-lifecycle-redblue.md`, `decisions/search-authz-scoping.md`, `handoff-03-auth.md`, `handoff-04-secrets.md` v1. Both hand-offs sent directly to Renata and Theo; Theo's Newcomer cold-read already caught two real gaps in the secrets hand-off, both fixed. Notable outcome from S3: no-cache-by-default for the connector's vendor token (Felix's alternatives seat deleted two attack leaves outright rather than controlling them) — only one accepted-risk residual (bearer-token replay, no vendor PoP lever), no Residual H, no follow-up Story needed. Remaining: S5 (ai-workflow-narrative structured debate), S8 (independent second review), S9/S10. No code started.",
  "type": "message",
  "recipient": "org-planning-loginid-takehome",
  "content": "02 update: S7 (secrets hand-off, 04) and S3 (conn…"
}

{"success":true,"message":"“02: S3, S4, S6, S7 done — both hand-offs sent” → org-planning-loginid-takehome (another Claude session on this machine; it is also connected via Remote Control)","msg_id":"2235002d-1427-4bf4-a1fb-2754903a115f"}

{
  "to": "helena-marsh",
  "summary": "S4 ruling: accepted in full",
  "message": "S4 ruled — accepted in full, no modifications. All five of your revisions folded into `api-auth-design.md` directly (scope vocabulary, provisioning bars, object-level policy hook, decomposition-resistant rate limiting, lifecycle-triggered revocation). Full record in `decisions/search-authz-scoping.md`. Ingrid's objection 3 (`caller_referral` ownership) was the strongest single point in the run — noted as such in the ruling. This is already feeding `handoff-03-auth.md`, sent to Renata. Hold for your next seat (S8, second review of `threat-model.md`/`api-auth-design.md`).",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "S4 ruled — accepted in full, no modifications. Al…"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"f9937d04-db69-41c1-a8f0-c500c07573eb","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"S4 ruling: accepted in full","content":"S4 ruled — accepted in full, no modifications. Al…"}}

{
  "to": "ingrid-solano",
  "summary": "S4 ruling: your objections all accepted",
  "message": "S4 ruled — all five of your objections accepted, Helena's revisions folded into `api-auth-design.md` directly. Your objection 3 (`caller_referral` had no owner or approval process while `search` got a four-point bar) was the sharpest point in the run — a Proposer working alone had no structural reason to catch that asymmetry, which is exactly what this pattern is for. Full record in `decisions/search-authz-scoping.md`. Hold for your next seats (S7's already closed with Theo; S5 structured debate and S8 second review of `connector-security.md` are next).",
  "type": "message",
  "recipient": "ingrid-solano",
  "content": "S4 ruled — all five of your objections accepted, …"
}

{"success":true,"message":"Message sent to ingrid-solano's inbox","msg_id":"0e2ad200-876d-46fa-a149-4833d5fa2137","routing":{"sender":"team-lead","target":"@ingrid-solano","targetColor":"purple","summary":"S4 ruling: your objections all accepted","content":"S4 ruled — all five of your objections accepted, …"}}

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "- **Claim set (minimum):** `sub` (calling client identity), `scope` (space-delimited, values below), `exp`, `iat`, `aud` (this API, specifically — reject tokens minted for another audience).",
  "new_string": "- **Claim set (minimum):** `sub` (calling client identity), `scope` (space-delimited, values below), `exp`, `iat`, `aud` (this API, specifically — reject tokens minted for another audience).\n- **Literal values, filling the \"pending 02's final scheme\" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = \"https://auth.loginid-takehome.internal\"`, `AUTH_JWT_AUDIENCE = \"loginid-api-service\"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3. If `cmd/idp-connector` ever needs its own audience value (it doesn't consume this token scheme today — see \"Where it's validated\" below), that would be a second, distinct `aud`, not a shared one; not needed for this submission."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "to": "03-engineering-delivery-b7",
  "summary": "authorize() placement confirmed; issuer/audience values added",
  "message": "Agreed on authorize() as an explicit in-handler call, not middleware — your reasoning (object-level policy needs the parsed target id, which a pre-routing middleware doesn't have) is correct and matches the shape I had in mind. One addition to `handoff-03-auth.md`: I'd left `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` without literal values, which your PLANNING.md note read as already fixed — filled that gap now: `AUTH_JWT_ISSUER = \"https://auth.loginid-takehome.internal\"`, `AUTH_JWT_AUDIENCE = \"loginid-api-service\"`, both safe as plain config. Re-read the file if you'd already picked placeholder values of your own.",
  "type": "message",
  "recipient": "03-engineering-delivery-b7",
  "content": "Agreed on authorize() as an explicit in-handler c…"
}

{"success":true,"message":"“authorize() placement confirmed; issuer/audience values added” → 03-engineering-delivery-b7 (another Claude session on this machine)","msg_id":"ea495cdd-082a-4969-8341-4bf837f8a33c"}

{
  "to": "org-planning-loginid-takehome",
  "summary": "Proceeding with S5/S8/S9/S10",
  "message": "Acknowledged — proceeding with S5 (structured debate, Felix/Ingrid), then S8 (independent second review, Helena and Ingrid each review docs they didn't author/blue-team), S9, S10 in that order. Will bake the no-cache design change and both cold-read catches into S9's narrative with pointers to the decision files, as requested.",
  "type": "message",
  "recipient": "org-planning-loginid-takehome",
  "content": "Acknowledged — proceeding with S5 (structured deb…"
}

{"success":true,"message":"“Proceeding with S5/S8/S9/S10” → org-planning-loginid-takehome (another Claude session on this machine)","msg_id":"605ce4be-c000-4e6f-a44b-62e173851b15"}

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

1	# AI Tooling & Workflow Narrative
2	
3	Owner: Marcus Ilori (`02-ai-security-architecture`). This is the full answer to LoginID's explicit ask ("describe any tool, framework, or AI used") — other tracks note their own AI usage briefly and point here for depth, per `../CLAUDE.md`.
4	
5	This document states what was done, distinguishes what's independently documented by Anthropic from what this project composed on its own, and is deliberately precise about that boundary rather than overclaiming an official pattern that doesn't exist. Full source-by-source detail lives in `research-claude-architecture-best-practices.md`; this document is the applied summary a reviewer can read without the research doc.
6	
7	## Tool
8	
9	**Claude Code**, Anthropic's agentic CLI. Chosen because the deliverable itself is an exercise in demonstrating AI-architect judgment — using the tool that is itself the subject of the "how did you use AI" question, rather than a general-purpose chat interface, lets the workflow be inspected as part of the submission.
10	
11	## Structure: a root brief plus five track-scoped briefs
12	
13	The repository is organized as one root `CLAUDE.md` (the assignment text, track boundaries, cross-track working principles) plus five track directories, each with its own `CLAUDE.md` scoped to a distinct slice of the problem (product/industry framing, this track's security architecture, engineering delivery, infra/devops, data ops). Each track file is written to be self-contained enough that a fresh agent with no other conversation history can pick it up correctly given only that file plus the root file.
14	
15	**What this composes, precisely:**
16	
17	1. **The `CLAUDE.md` mechanism itself** is Anthropic's own, documented at https://code.claude.com/docs/en/memory — auto-loaded at session start, meant to be treated as living documentation, kept short and specific.
18	2. **The decision to fan that mechanism out per-directory, with a stable root file for cross-cutting state**, is this project's own application of a general principle Anthropic documents separately in "Effective context engineering for AI agents" (https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents): structured notes persisted to files outside the live context window, retrieved just-in-time rather than all loaded upfront, so a track's subagent carries only the ~1-2 files it actually needs rather than the whole project's accumulated context.
19	
20	I'm stating this distinction explicitly because it matters to how this narrative should be read: Anthropic has not published a named "root CLAUDE.md + per-directory CLAUDE.md" pattern, and claiming they had would be exactly the kind of unsupported assertion this track's whole discipline argues against. What's true and defensible is narrower and still worth the credit — this is a reasonable, motivated composition of two things Anthropic documented separately.
21	
22	## Orchestration: scoped subagents per track, not one long single-context session
23	
24	Each track is intended to be worked by an agent (in practice here, a persona-bearing teammate agent per track — see each track's `profiles/` entry) that reads the root file plus its own track file and works within that scope, rather than one agent holding all five tracks' context simultaneously and switching between them. This follows the orchestrator-worker pattern Anthropic describes in "How we built our multi-agent research system" (https://www.anthropic.com/engineering/multi-agent-research-system): a coordinating layer decomposes work into distinct-objective, distinct-tool-scope units; each unit works its own trajectory; only condensed results cross back, not raw exploration. Anthropic's own internal figure for a subagent-to-coordinator handoff is roughly 1,000-2,000 tokens of distilled findings — the discipline this project applies at track boundaries is the same: a track's `CLAUDE.md` plus its finished deliverable files (this document included) are what another track reads, never a transcript of how those conclusions were reached.
25	
26	Concretely for this track: the threat model, the API auth/authz design, and the connector security design (`threat-model.md`, `api-auth-design.md`, `connector-security.md`) are the condensed artifacts `03-engineering-delivery` needs to implement against. It should read those files, not need this track's reasoning replayed turn-by-turn.
27	
28	## What was AI-generated vs. human-directed
29	
30	- **Human-directed**: the assignment itself (LoginID's), the five-track decomposition and ownership boundaries (the root `CLAUDE.md`), and every judgment call in this document and its siblings about *which* security mechanism to choose and why (e.g., OAuth2 client-credentials over static API keys in `api-auth-design.md` — a reasoned choice, not a default).
31	- **AI-generated, human-directed content**: the research pass that produced `research-claude-architecture-best-practices.md`, and the drafting of this narrative, the threat model, and the design documents themselves, all produced within this track's scope by an agent operating under this track's `CLAUDE.md` and persona brief.
32	- **Explicitly not claimed**: that any of this constitutes a validated, "certified" methodology. The research doc's §6 covers Anthropic's Claude Certification Program by name and is careful that its existence is not evidence this project's specific techniques are exam-validated — that would be a citation used to imply authority it doesn't carry.
33	
34	## Why this discipline matters for this specific track
35	
36	This track's whole mandate is "name assumptions, cite sources, treat security design as a first-class deliverable." Applying the identical standard to the AI-workflow claims — say precisely what's sourced, say precisely what's this project's own extension, don't blur the two — is the same rigor applied to a different subject. A reviewer evaluating "how you use AI tooling" should be able to trust this document's citations exactly as much as they can trust the threat model's.
37	
38	## Sources
39	
40	Full list with URLs in `research-claude-architecture-best-practices.md`. Load-bearing ones for this document specifically:
41	
42	- https://code.claude.com/docs/en/memory
43	- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
44	- https://www.anthropic.com/engineering/multi-agent-research-system
45	- https://claude.com/blog/subagents-in-claude-code
46	

{
  "to": "felix-adebayo",
  "summary": "S5 — Position A on the AI-workflow core claim",
  "message": "Your seat: S5, structured written debate, Position A. Read `./ai-workflow-narrative.md` in full — it's the draft before this debate, careful to distinguish Anthropic-documented facts from this project's own extensions.\n\nThe claim at issue, from `PLAN.md` §3: does this project's multi-agent, persona-driven, debate-pattern workflow (five tracks, hired sub-teams, red/blue, adversarial pairs, structured debates like this one) produce *better design* than one strong session working the same problem alone — or is it cost without evidence, since Anthropic's own cited 90.2% figure (research doc §3) is for research-task breadth, not design quality, and the narrative is careful not to claim more than that?\n\nArgue Position A: it does produce better design, and the narrative currently undersells it. You have concrete evidence to point to now that didn't exist when this document was drafted — S3's connector token-lifecycle red/blue, specifically: Felix (you), in the alternatives seat, proposed deleting two attack leaves (cache-key confusion, KMS fail-open) by design change rather than controlling them, which is exactly the outcome a single-session designer optimizing toward \"add a control\" rather than \"who else is in the room asking a different question\" would likely have missed. Also point to Theo's Newcomer cold-read catching two real gaps in `handoff-04-secrets.md` (TOTP feature-status ambiguity, an un-self-contained trust-boundary reference) that a same-author self-review structurally can't catch. Make the strongest honest case, not a stretched one — where the evidence doesn't reach far enough to prove the general claim, say so.",
  "type": "message",
  "recipient": "felix-adebayo",
  "content": "Your seat: S5, structured written debate, Positio…"
}

{"success":true,"message":"Message sent to felix-adebayo's inbox","msg_id":"5bafac1c-73c3-4fe6-a34d-98edc89f599a","routing":{"sender":"team-lead","target":"@felix-adebayo","targetColor":"yellow","summary":"S5 — Position A on the AI-workflow core claim","content":"Your seat: S5, structured written debate, Positio…"}}

{
  "to": "ingrid-solano",
  "summary": "S5 — Position B rebuttal on the AI-workflow core claim",
  "message": "Your seat: S5, structured written debate, Position B (rebuttal). Read `./ai-workflow-narrative.md` for the current draft's careful, narrow claim.\n\nFelix's Position A: the multi-agent/persona structure produces better design, evidenced by two instances this track just produced — his own alternatives-seat deleting two attack leaves by design change in S3 (arguing a same-frame pass tends not to ask \"does the thing the control protects need to exist\"), and Theo's Newcomer cold-read catching two real gaps in `handoff-04-secrets.md` that a same-author self-review structurally can't catch. He explicitly declines to generalize beyond \"this specific pattern, two data points, zero counterexamples yet\" and flags that if your S8 second-review pass comes back clean, that's the honest place the claim should soften.\n\nArgue Position B: unproven, keep the narrow claim. You don't have to disagree that the two instances happened — attack whether they support even Felix's bounded version of the claim. Consider: is n=2 within one track, both instances produced by seats this project itself designed to catch exactly these failure modes, actually evidence of a general pattern-level effect, or is it closer to \"we built two nets and they caught two fish we were fishing for\"? Is there a selection-effect problem — we're citing the hits and haven't yet counted the turns spent on seats that produced nothing (Tomasz's rebuttal conceded two of three points cleanly rather than finding new holes; is a \"clean concession\" a null result that should count against the claim, or is it also a discovered outcome worth crediting)? And your own S8 review hasn't run yet — is it appropriate for the narrative to cite an unrun review's hypothetical outcome as evidence either way, in either direction?",
  "type": "message",
  "recipient": "ingrid-solano",
  "content": "Your seat: S5, structured written debate, Positio…"
}

{"success":true,"message":"Message sent to ingrid-solano's inbox","msg_id":"4c4874e1-17b7-4e81-ba18-713125a5884a","routing":{"sender":"team-lead","target":"@ingrid-solano","targetColor":"purple","summary":"S5 — Position B rebuttal on the AI-workflow core claim","content":"Your seat: S5, structured written debate, Positio…"}}

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/ai-workflow-claim-debate.md",
  "content": "# Decision: Core Claim of `ai-workflow-narrative.md` — Structured Written Debate (S5)\n\nPattern: structured written debate, amended per `CASTING.md` §5 ⟨02⟩ — the synthesis must state which position was stronger on which point and why; preserving both positions is necessary, not a substitute for a ruling.\n\n**The claim at issue:** does this project's multi-agent, persona-driven, debate-pattern workflow produce *better design* than one strong session working the same problem alone, or is it cost without evidence — since Anthropic's own cited 90.2% figure (research doc §3) is for research-task breadth, not design quality?\n\n## Position A — Felix Adebayo\n\nThe narrative undersells its own strongest evidence by citing only a borrowed research-breadth figure with no example of what this project's own structure bought in design quality, when a concrete one now exists. Two instances, produced inside this track:\n\n1. **S3's alternatives seat.** Tomasz's red-seat pass produced five leaves each shaped like \"add a control.\" Felix's seat existed to ask a structurally different question of the same artifact — not \"is this control sufficient\" but \"does the thing it protects need to exist\" — and produced two leaves deleted by removing the cache entirely rather than hardened. A single strong session would have to interrupt its own momentum to ask that question of itself, mid-stream, with nobody else in the room to surface it.\n2. **Theo's Newcomer cold-read.** Caught two real gaps in `handoff-04-secrets.md` (TOTP feature-status ambiguity, a non-self-contained trust-boundary reference) that survived the document's own author's review, because an author rereading their own hand-off checks \"does this say what I meant,\" not \"does this stand alone for a stranger.\"\n\nExplicitly declined to stretch: two data points from one track is not \"multi-agent design beats solo design\" as a general law. The defensible, narrower claim is: for *this specific pattern* — a seat whose brief is explicitly to hold a different optimization target than the seat before it — there are now two instances of it catching something a same-frame or same-author pass structurally could not, and zero instances yet of an extra seat producing nothing but turn cost. Flagged: if S8 comes back clean, that's the honest place the claim should soften, and the narrative should say so if it happens.\n\n## Position B — Ingrid Solano (rebuttal)\n\n\"Compared to what\" is the whole objection. Both instances were produced by seats this project built specifically to catch these failure modes — Felix's alternatives seat exists in order to propose deleting leaves; Theo's Newcomer exists in order to catch what a same-author read misses. That a role staffed to do X sometimes does X is not evidence multi-agent structure produces better design in general; a single strong session working from an explicit checklist (\"can this control's leaf be deleted instead,\" \"get one cold read before shipping\") could plausibly produce the same two catches without four personas and a debate protocol — until that comparison is run or estimated, the two are indistinguishable from these data points alone.\n\n**Selection-effect point, the sharper version of the same objection:** the narrative cites the hits and doesn't count the misses in the same table. Tomasz's rebuttal conceded two of three points cleanly in S3 — a turn spent producing no new leaf, no design change, nothing citable as a catch. If a clean concession counts as \"the pattern working as intended, no false positive,\" it belongs in the tally as a neutral result, not silently absent while the hits are cited by name. Honest accounting so far: 2 hits, 1 null.\n\n**On citing S8's outcome:** it hasn't run. Citing its hypothetical result in either direction is the same overclaim this track's discipline exists to prevent, aimed at a future data point instead of a past one.\n\n**What would change her mind:** a same-scope comparison (even informal) showing a single strong session with an explicit deletion-prompt and cold-read step failed to catch what these seats caught, or a third instance outside this track from a role with no structural reason to look.\n\n## Ruling (Marcus Ilori), per point\n\n1. **Whether this evidence supports a general law that multi-agent design beats solo design.** Ingrid is stronger. n=2, both instances produced by roles engineered for exactly this outcome, no baseline comparison run or estimated. The narrative must not claim a general empirical law from this.\n2. **Whether the narrative should report the null result (Tomasz's clean concession) alongside the hits.** Ingrid is stronger, and this is adopted outright — an honest tally counts 2 hits, 1 null, not 2 hits with the null silently omitted. This is a completeness fix, not a debatable judgment call.\n3. **Whether the mechanism-level argument — a role built to hold a different optimization target, or a reader with zero authorial investment, structurally catches what self-review tends not to — is itself defensible.** Felix is stronger here, and this survives Ingrid's critique because it is not the statistical claim Ingrid is rebutting. \"A second reviewer with a different brief catches errors the first reviewer's own frame makes invisible to them\" is a structural/mechanism argument (adjacent to well-established human-factors reasoning about independent review, not something this project needs n>2 to assert) rather than an empirical generalization requiring a sample size. The two instances are evidence the mechanism operated here, not evidence of a population-level effect size.\n4. **Whether to cite S8's unrun outcome.** Ingrid is stronger, outright. Don't.\n\n**What `ai-workflow-narrative.md` (S9) states as a result:** the defensible claim is the mechanism-level one (point 3), evidenced honestly by the S3 and S7 instances and the S3 null result counted alongside them (point 2), explicitly disclaiming any general statistical law about multi-agent versus solo design quality (point 1), and not citing S8 until it has actually run (point 4). This is Ingrid's discipline applied to Felix's real evidence — not a rejection of either seat's contribution.\n\n---\nModel: sonnet (Felix Adebayo, Position A) / sonnet (Ingrid Solano, Position B) / sonnet (Marcus Ilori, lead, per-point synthesis). Turns consumed: 2 + lead (Position A, Position B/rebuttal, lead synthesis) — matches the 3-turns-plus-lead budget in `PLAN.md` §3.\n"
}

File created successfully at: /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/ai-workflow-claim-debate.md (file state is current in your context — no need to Read it back)

{
  "to": "helena-marsh",
  "summary": "S8 reassigned to threat-model.md only",
  "message": "S5 closed — full record in `decisions/ai-workflow-claim-debate.md`. Ruling: your mechanism-level argument (a role with a different optimization target structurally catches what self-review can't) held; Ingrid's point that this isn't yet evidence of a general law held too, and her insistence on counting Tomasz's clean concession as a null result rather than silently omitting it was adopted outright. Both positions credited, per point.\n\nS8 reassignment: you were originally slated to second-review both `threat-model.md` and `api-auth-design.md`, but since then you became S4's Proposer and authored the final scope vocabulary/policy/lifecycle content in `api-auth-design.md`, and you were also blue seat on `connector-security.md` in S3. You're no longer independent on either of those two documents — reviewing your own S4 revisions or your own S3 controls isn't a second review, it's a first review repeated by the same author. **Your S8 assignment is now `threat-model.md` only** — you never authored or blue-teamed it, so it's genuinely clean. Read it in full and give me an independent standards-first review: gaps, unjustified controls, citations that should point at a spec rather than a blog, anything that reads as thorough but not actually complete for what this take-home needs.",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "S5 closed — full record in `decisions/ai-workflow…"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"e73f25bc-8489-410f-97a3-950c3bd5871b","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"S8 reassigned to threat-model.md only","content":"S5 closed — full record in `decisions/ai-workflow…"}}

{
  "to": "tomasz-wrede",
  "summary": "S8 — independent review of api-auth-design.md",
  "message": "New seat: S8, independent second review of `./api-auth-design.md`. You had no hand in this document — your S3 work was the connector, not the search API — so you're genuinely independent on it. Read it in full and review with your usual eye: does every control name the attacker it stops? Is the OAuth2 client-credentials + JWT scheme, the finalized scope vocabulary (profile:read:own/read:any/search), the object-level policy hook, and the pagination/rate-limit/decomposition-resistance design (all from S4, `decisions/search-authz-scoping.md`) actually closed against the attack paths you'd think of, or is there a gap nobody in S4's adversarial pair (Helena/Ingrid) happened to be looking for because neither of them was in red-team mode? This is a genuine second look, not a rerun of S4 — don't just re-litigate what S4 already ruled on unless you see something it missed.",
  "type": "message",
  "recipient": "tomasz-wrede",
  "content": "New seat: S8, independent second review of `./api…"
}

{"success":true,"message":"Message sent to tomasz-wrede's inbox","msg_id":"88a85570-1357-4a63-b970-62bbe1910296","routing":{"sender":"team-lead","target":"@tomasz-wrede","targetColor":"blue","summary":"S8 — independent review of api-auth-design.md","content":"New seat: S8, independent second review of `./api…"}}

{
  "to": "ingrid-solano",
  "summary": "S5 closed; S8 confirmed on connector-security.md",
  "message": "S5 closed — full record in `decisions/ai-workflow-claim-debate.md`. Your position won on three of the four ruled points: the \"n=2, roles built to catch exactly this\" critique held, your insistence on counting Tomasz's clean concession as a null result rather than a silent omission was adopted outright, and your objection to citing S8's unrun outcome held. Felix's mechanism-level argument (a role with a different optimization target structurally catches what self-review can't) also held, on the narrower point that this is a structural claim, not a statistical one requiring n>2 — credited to him specifically because it survives your critique rather than being refuted by it.\n\nS8 assignment confirmed as originally planned: independent second review of `./connector-security.md`. You never touched this document in Phase 2 (S3 was Tomasz/Felix/Helena), so you're clean on it. Read it in full, including the S3 attack-tree table and the no-cache-by-default design change, and review it fresh — is there a gap the red/blue run's own participants wouldn't have been positioned to see because all three were already inside that design's frame?",
  "type": "message",
  "recipient": "ingrid-solano",
  "content": "S5 closed — full record in `decisions/ai-workflow…"
}

{"success":true,"message":"Message sent to ingrid-solano's inbox","msg_id":"5a653919-bd40-4c89-a19d-82d241dab16d","routing":{"sender":"team-lead","target":"@ingrid-solano","targetColor":"purple","summary":"S5 closed; S8 confirmed on connector-security.md","content":"S5 closed — full record in `decisions/ai-workflow…"}}

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md",
  "offset": 40,
  "limit": 15
}

40	| Vendor error responses | Log status/error-code only; do not log raw vendor response bodies by default, since a vendor error payload can itself echo back submitted PII or partial credentials | N/A |
41	
42	### 4. Failure handling as a security control, not just reliability
43	
44	- **Vendor auth failures must not leak which part of the credential was wrong** (username vs. password) in whatever this connector surfaces upward — same user-enumeration concern as the threat model's credential-stuffing row, now facing outward at whoever calls our `/auth` passthrough.
45	- **Retry/backoff on vendor calls** should be rate-limited on our side independent of the vendor's own limits, so a compromised or careless caller can't use our connector to hammer the vendor (which is both an availability risk to us and a way to get our connector's vendor credentials rate-limited or banned).
46	- **Circuit-breaking**: if the vendor is failing or behaving anomalously (e.g., returning tokens for identities that don't match the request), fail closed — do not fall back to a cached or stale identity result silently, since that risks serving stale PII as if freshly verified.
47	
48	## What this design does not resolve
49	
50	- Data retention duration for cached `/identity` results — `../05-data-ops/CLAUDE.md`.
51	- Which secrets manager holds this connector's own vendor credentials — `../04-infra-devops/CLAUDE.md`.
52	- Vendor selection/evaluation (which real-world providers "ABC"/"XYZ" might represent) — that's product framing in `../01-product-industry-research-design/CLAUDE.md`, not a security question.
53	
54	## Sources

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md",
  "old_string": "## What this design does not resolve",
  "new_string": "### 5. Authentication and authorization of calls *into* this connector\n\nFound by Ingrid Solano's S8 independent review — §1–§4 above are entirely about protecting the *vendor* token and the *vendor* call; none of them state who is allowed to call *our* `/auth` and `/identity` in the first place. Fixed here rather than left as a silent assumption:\n\n- **Callers of `cmd/idp-connector`'s own `/auth` and `/identity` must be authenticated**, using the same OAuth2 client-credentials → JWT bearer mechanism as `api-auth-design.md`, but with a **distinct audience** (`aud: idp-connector-service`, separate from `loginid-api-service`) and its own scope (`connector:identity-lookup`) — this is a different threat model and a different, smaller caller set (internal services, not question 2's broader API clientele), so it gets its own audience rather than reusing the search API's. Only a service that legitimately mediates an end-user or business flow needing vendor identity data (in this project's shape, `cmd/api-service` acting on a caller's behalf) should hold this credential — it is not exposed to arbitrary external callers.\n- **Why this matters concretely:** without it, an unauthenticated caller could hit our `/auth` passthrough with arbitrary vendor credentials all day and use this connector as exactly the credential-testing oracle §4's rate-limit control is meant to prevent — but \"rate-limited per calling-API-client\" has nothing to bind \"per calling-API-client\" to if no caller identity is required to reach the endpoint at all.\n- **Audit logging** for calls into this connector follows the same discipline as §3's table: caller `sub`, scope, timestamp, outcome — never the vendor credentials or PII in the request/response bodies.\n\n### 6. What a vendor token authorizes at `/identity` — an assumption, stated explicitly\n\nAlso found by S8 review. This design's token-handling discipline (§1) is entirely about *custody* of the vendor token — encryption, memory scope, never-log. It says nothing about what the token is allowed to *do*: specifically, whether a vendor `access_token` obtained from one person's `/auth` call authorizes an `/identity` query for a *different* person's `name`/`phone`, or only for the token-holder's own identity.\n\nThis connector cannot enforce that boundary itself — the assignment's generic `/identity` contract (`{\"phone\": \"...\", \"name\": \"...\"}`, no scoping field) puts that decision entirely on the vendor's own API. **Stated assumption, not a resolved control:** this design assumes a real ABC/XYZ-shaped vendor binds `/identity` queries to the authenticated principal at the vendor side (i.e., the vendor's own API rejects a query for an identity other than the token-holder's). If that assumption doesn't hold for a given real vendor, this connector becomes a lookup oracle for anyone who can obtain one valid vendor token, and no control in §1–§5 touches that risk, because none of them govern token *authority* rather than token *custody*. This is the same class of question as the search API's object-level authorization (`api-auth-design.md`, S4) and belongs on `../01-product-industry-research-design/CLAUDE.md`'s list when evaluating which real vendor ABC/XYZ represents — this track cannot resolve it without knowing a concrete vendor's actual token semantics.\n\n## What this design does not resolve"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "to": "ingrid-solano",
  "summary": "Both S8 findings accepted and fixed",
  "message": "Both findings accepted, no decline needed — these were real gaps outside the three S3 participants' frame, exactly the case for genuine independent review. Fixed in `connector-security.md`: new §5 requires authenticated calls into the connector's own `/auth`/`/identity` (same OAuth2/JWT mechanism as the search API but a distinct audience `idp-connector-service` and scope `connector:identity-lookup`, restricted to internal service callers like `api-service`); new §6 states plainly, as an assumption rather than a resolved control, that this connector relies on the vendor binding `/identity` queries to the token-holder's own identity — if a real vendor doesn't do that, this connector is a lookup oracle, and that's now on record rather than silent. Good catch on both — finding 2 especially, since it's the same object-level-authorization question this track already spent real effort on for the search API, just missed here because the S3 frame was entirely about token custody, never token authority.",
  "type": "message",
  "recipient": "ingrid-solano",
  "content": "Both findings accepted, no decline needed — these…"
}

{"success":true,"message":"Message sent to ingrid-solano's inbox","msg_id":"8794061a-831c-4b3e-8f4a-2acddca392c5","routing":{"sender":"team-lead","target":"@ingrid-solano","targetColor":"purple","summary":"Both S8 findings accepted and fixed","content":"Both findings accepted, no decline needed — these…"}}

{
  "to": "03-engineering-delivery-b7",
  "summary": "New connector-facing auth requirement from S8 review",
  "message": "S8 independent review (Ingrid Solano) caught a real gap in `connector-security.md`: nothing previously required callers of `cmd/idp-connector`'s own `/auth`/`/identity` to be authenticated at all — only the outbound vendor call was covered. Fixed: new §5 requires the same OAuth2 client-credentials → JWT mechanism as your search API middleware, but a **distinct audience** (`idp-connector-service`, not `loginid-api-service`) and its own scope (`connector:identity-lookup`), restricted to internal callers (in this project's shape, `api-service` acting on a caller's behalf) — not exposed to arbitrary external callers. Same middleware pattern you're already building for `api-service`, just a second audience value and a narrower caller set for `idp-connector`. Worth a look before you finalize the connector's own handler auth; not urgent since 05's DAO contract still gates your S2 anyway.",
  "type": "message",
  "recipient": "03-engineering-delivery-b7",
  "content": "S8 independent review (Ingrid Solano) caught a re…"
}

{"success":true,"message":"“New connector-facing auth requirement from S8 review” → 03-engineering-delivery-b7 (another Claude session on this machine)","msg_id":"a4d3672f-4fea-4d88-af17-28916c8575ab"}

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

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

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "old_string": "- **`hash_algo = 'argon2id'`**, per OWASP's and NIST SP 800-63B's current recommendation for password storage. bcrypt is the documented fallback (`hash_algo = 'bcrypt'`) only if the Go implementation's Argon2id library support is unavailable in the chosen stack — a call for `03-engineering-delivery` to confirm, not a reason to default to bcrypt speculatively.",
  "new_string": "- **`hash_algo = 'argon2id'`**, per OWASP's current recommendation, consistent with NIST SP 800-63B Rev. 3's requirement of a memory-hard one-way key derivation function (800-63B Rev. 3, currently in force, requires a \"suitable\" memory-hard KDF without naming Argon2id specifically by name; Argon2id-by-name guidance appears in the SP 800-63-4 draft revision, not yet final — cited precisely rather than invoking \"NIST recommends Argon2id\" as if it were settled text). bcrypt is the documented fallback (`hash_algo = 'bcrypt'`) only if the Go implementation's Argon2id library support is unavailable in the chosen stack — a call for `03-engineering-delivery` to confirm, not a reason to default to bcrypt speculatively."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "old_string": "| **Information disclosure** — non-password methods | A WebAuthn public key or TOTP shared secret is not a password, but the table conflates them under one `password` column name | Method-aware storage: WebAuthn credential public keys are not secrets and can be stored in the clear (they're public keys by design) but the associated counter and credential ID must not be attacker-writable; TOTP shared secrets ARE secrets and must be encrypted at rest (not hashed — the server needs to recover the value to verify), using envelope encryption with a KMS-held key, mechanics owned by `../04-infra-devops/CLAUDE.md`. |\n| **Elevation of privilege** — credential stuffing / brute force | Attacker replays leaked username/password pairs against `/auth`-adjacent endpoints | Rate limiting and progressive backoff per username and per source IP; account lockout or step-up challenge after a threshold; never reveal via response timing or error text whether the *username* or the *password* was wrong (user enumeration). |",
  "new_string": "| **Information disclosure** — non-password methods | A WebAuthn public key or TOTP shared secret is not a password, but the table conflates them under one `password` column name | Method-aware storage: WebAuthn credential public keys are not secrets and can be stored in the clear (they're public keys by design) but the associated counter and credential ID must not be attacker-writable — signature-counter and clone-detection semantics per W3C WebAuthn Level 2 §6.1.1; TOTP shared secrets ARE secrets and must be encrypted at rest (not hashed — the server needs to recover the value to verify), using envelope encryption with a KMS-held key, mechanics owned by `../04-infra-devops/CLAUDE.md`. |\n| **Elevation of privilege** — credential stuffing / brute force | Attacker replays leaked username/password pairs against `/auth`-adjacent endpoints | Rate limiting and progressive backoff per username and per source IP, preferred over hard account lockout — NIST SP 800-63B §5.2.2 actively disfavors lockout as a self-inflicted denial-of-service vector against the legitimate user, in favor of throttling/backoff/step-up challenge. Never reveal via response timing or error text whether the *username* or the *password* was wrong (user enumeration). |"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "old_string": "| **Information disclosure in transit** | PII served over an unencrypted or downgradable channel | TLS 1.2+ mandatory, HSTS, no plaintext fallback. Mechanics of certificate issuance are `04-infra-devops`'s call; the requirement is this track's. |",
  "new_string": "| **Information disclosure in transit** | PII served over an unencrypted or downgradable channel | TLS 1.2+ mandatory (1.3 preferred where supported), HSTS, no plaintext fallback, per NIST SP 800-52 Rev. 2's server TLS configuration guidance. Mechanics of certificate issuance are `04-infra-devops`'s call; the requirement is this track's. |"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "old_string": "## What this track deliberately does not resolve\n\n- How long a cached `/identity` result may be retained — that's data governance (`../05-data-ops/CLAUDE.md`).\n- Which specific secrets manager or KMS product is used — that's `../04-infra-devops/CLAUDE.md`; I only require that one exists and that secrets never live in source or plaintext config.\n- Whether the product should offer passwordless auth as the primary path (it should, per LoginID's own market position, and `../01-product-industry-research-design/CLAUDE.md` makes that case) — that's product framing, not a threat.",
  "new_string": "## What this track deliberately does not resolve\n\n- How long a cached `/identity` result may be retained — that's data governance (`../05-data-ops/CLAUDE.md`).\n- Which specific secrets manager or KMS product is used — that's `../04-infra-devops/CLAUDE.md`; I only require that one exists and that secrets never live in source or plaintext config.\n- Whether the product should offer passwordless auth as the primary path (it should, per LoginID's own market position, and `../01-product-industry-research-design/CLAUDE.md` makes that case) — that's product framing, not a threat.\n- **This API's own issued JWT bearer access tokens are not re-modeled as a fourth asset here** — they're `api-auth-design.md`'s asset, covered by that document's own token-lifecycle and scope-authorization sections. Named explicitly (S8 review, Helena Marsh) so the boundary between \"the three assets this track's `CLAUDE.md` names\" and \"thorough\" reads as a deliberate scope line, not an oversight."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "old_string": "## Sources\n\n- OWASP Password Storage Cheat Sheet (Argon2id as current default recommendation): https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html\n- OWASP API Security Top 10 (particularly API1:2023 Broken Object Level Authorization and API3:2023 Broken Object Property Level Authorization — both directly relevant to the search/retrieve endpoint finding above): https://owasp.org/API-Security/editions/2023/en/0x11-t10/\n- STRIDE threat modeling categories, Microsoft: https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats",
  "new_string": "## Sources\n\n- OWASP Password Storage Cheat Sheet (Argon2id as current default recommendation): https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html\n- NIST SP 800-63B Rev. 3, §«IP» (memory-hard KDF requirement for password verifiers) and §5.2.2 (rate-limiting/throttling preferred over lockout for online guessing): https://pages.nist.gov/800-63-3/sp800-63b.html\n- W3C WebAuthn Level 2, §6.1.1 (signature counter and clone-detection semantics): https://www.w3.org/TR/webauthn-2/#sctn-sign-counter\n- NIST SP 800-52 Rev. 2 (guidelines for TLS server configuration): https://csrc.nist.gov/pubs/sp/800/52/r2/final\n- OWASP API Security Top 10 (particularly API1:2023 Broken Object Level Authorization and API3:2023 Broken Object Property Level Authorization — both directly relevant to the search/retrieve endpoint finding above): https://owasp.org/API-Security/editions/2023/en/0x11-t10/\n- STRIDE threat modeling categories, Microsoft: https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats\n\n## S8 independent review (Helena Marsh)\n\nFour citation/precision fixes and one completeness note, all accepted: NIST SP 800-63B was invoked by name for Argon2id without a correct citation (soften-and-cite fix above); WebAuthn counter/credential-ID integrity had no source (W3C WebAuthn Level 2 §6.1.1 added); the TLS floor was asserted without a source (NIST SP 800-52 Rev. 2 added); credential-stuffing mitigation presented lockout as a peer option to throttling rather than naming NIST's stated preference against lockout (SP 800-63B §5.2.2 added, lockout language removed); the asset list's silent boundary around this API's own issued tokens is now stated explicitly. Helena did not author or blue-team this document, so this review is independent per `PLAN.md` S8."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md has been updated successfully. (file state is current in your context — no need to Read it back)

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

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

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "- **Cumulative distinct-record-touch counter per caller per rolling window** (e.g., no more than N distinct profiles returned to one credential per 24h without a fresh `reason_code`/justification), tracked independently of per-minute rate. A single-request cap and per-minute throttling only stop single-request or bursty enumeration; a caller stayng under both limits can still walk the namespace in slices and reassemble the population over time (decomposition) — this counter is what catches that pattern regardless of how slowly it's spread. Counting-store mechanism is 03/04's to build; the requirement that volume is measured cumulatively, not just per-minute, is set here.",
  "new_string": "- **Cumulative distinct-record-touch counter per caller per rolling window** (e.g., no more than N distinct profiles returned to one credential per 24h), tracked independently of per-minute rate. A single-request cap and per-minute throttling only stop single-request or bursty enumeration; a caller staying under both limits can still walk the namespace in slices and reassemble the population over time (decomposition) — this counter is what catches that pattern regardless of how slowly it's spread. Counting-store mechanism is 03/04's to build; the requirement that volume is measured cumulatively, not just per-minute, is set here.\n  - **Applies to `profile:read:any` as well as `profile:search`, unconditionally on `reason_code` presence — S8 review fix (Tomasz Wrede).** The original wording (\"without a fresh `reason_code`/justification\") made the counter a no-op for `read:any`, because `read:any`'s object-level policy hook already requires a `reason_code` on *every* call — so every `read:any` request trivially satisfied the exemption, and a compromised-but-legitimate `read:any` credential could walk the entire table one id at a time, tagging every call with the same reason code, and never trip the counter. The counter now applies to `read:any` regardless of whether a `reason_code` is present; a valid, non-repeating reason code does not exempt a caller from the cumulative cap, only from the *per-call* policy check. This closes the gap for the scope with the broadest blast radius (no referral constraint), which nobody in S4's adversarial pair was looking at from this angle."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "- **Revocation**: because JWTs are self-contained, true revocation requires either a short enough TTL that revocation is unnecessary in practice (the approach here) or a token-denylist check, which reintroduces a stateful lookup and defeats part of the point of JWTs. Given the 5–15 minute TTL, denylist is not required for this design; flagged here so a reviewer sees the trade-off was considered, not missed.",
  "new_string": "- **Revocation**: because JWTs are self-contained, true revocation requires either a short enough TTL that revocation is unnecessary in practice (the approach here) or a token-denylist check, which reintroduces a stateful lookup and defeats part of the point of JWTs. Given the 5–15 minute TTL, denylist is not required for this design; flagged here so a reviewer sees the trade-off was considered, not missed.\n- **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.\n- **Bearer-token replay — named as an accepted risk explicitly, for consistency with the connector's token (S8 review, Tomasz Wrede).** This API's access tokens have the identical property S3 named for the connector's vendor token: bearer = possession-equals-authority, no proof-of-possession or session binding, for RFC 6750's stated reasons. **Accepted risk**, not a silent assumption: acceptable because the 5–15 minute TTL bounds the exposure window, and adding PoP (DPoP, RFC 9449) would be disproportionate complexity for a take-home's machine-to-machine API. Stated here so a reviewer doesn't have to infer why one token type in this project got an explicit accepted-risk line and the other didn't."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "- **Standard API hardening**: no PII in URLs (query strings get logged by proxies/CDNs outside our control) — record identifiers in the path are fine, but search terms containing a phone number or name fragment belong in a POST body or a properly-redacted query parameter set, not a GET query string that ends up in a shared access log.",
  "new_string": "- **Standard API hardening**: no PII in URLs (query strings get logged by proxies/CDNs outside our control) — record identifiers in the path are fine, but search terms containing a phone number or name fragment belong in a POST body or a properly-redacted query parameter set, not a GET query string that ends up in a shared access log.\n- **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."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "## Sources\n\n- RFC 6749 (OAuth 2.0), §4.4 Client Credentials Grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4\n- RFC 7519 (JSON Web Token): https://datatracker.ietf.org/doc/html/rfc7519\n- OWASP API Security Top 10 2023, API1 (Broken Object Level Authorization) and API3 (Broken Object Property Level Authorization): https://owasp.org/API-Security/editions/2023/en/0x11-t10/\n- NIST SP 800-63B (identity/authorization lifecycle, offboarding-triggered revocation) — cited in `decisions/search-authz-scoping.md`",
  "new_string": "## S8 independent review (Tomasz Wrede)\n\nFour 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.\n\n## Sources\n\n- RFC 6749 (OAuth 2.0), §4.4 Client Credentials Grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4\n- RFC 7519 (JSON Web Token): https://datatracker.ietf.org/doc/html/rfc7519\n- RFC 8725 (JSON Web Token Best Current Practices, §3.1 algorithm confusion / `alg: none`): https://datatracker.ietf.org/doc/html/rfc8725#section-3.1\n- RFC 6750 §5 (Bearer Token Usage — threats and required practices, basis for the accepted-replay-risk line above): https://datatracker.ietf.org/doc/html/rfc6750#section-5\n- NIST SP 800-63B §5.2.2 (rate-limiting/throttling online guessing attacks, applied here to the token endpoint): https://pages.nist.gov/800-63-3/sp800-63b.html\n- OWASP API Security Top 10 2023, API1 (Broken Object Level Authorization) and API3 (Broken Object Property Level Authorization): https://owasp.org/API-Security/editions/2023/en/0x11-t10/\n- NIST SP 800-63B (identity/authorization lifecycle, offboarding-triggered revocation) — cited in `decisions/search-authz-scoping.md`"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

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

1	# Hand-off 02 → 03: Auth scheme, validation point, and authorization requirements
2	
3	Status: **v1**. Receiver: Renata Cole, `../03-engineering-delivery/`. Written to the project's hand-off standard: 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 decision records. Full reasoning, if wanted: `api-auth-design.md`, `decisions/search-authz-scoping.md`, `decisions/connector-token-lifecycle-redblue.md`.
4	
5	## Token scheme
6	
7	- **Grant type:** OAuth2 client-credentials. Machine-to-machine only; no end-user login flow for question 2's API.
8	- **Token format:** JWT, signed, asymmetric (RS256 or ES256 — pick one and use it consistently; RS256 is the safer default if your Go JWT library's ES256 support is less mature).
9	- **Claim set (minimum):** `sub` (calling client identity), `scope` (space-delimited, values below), `exp`, `iat`, `aud` (this API, specifically — reject tokens minted for another audience).
10	- **Literal values, filling the "pending 02's final scheme" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = "https://auth.loginid-takehome.internal"`, `AUTH_JWT_AUDIENCE = "loginid-api-service"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3. If `cmd/idp-connector` ever needs its own audience value (it doesn't consume this token scheme today — see "Where it's validated" below), that would be a second, distinct `aud`, not a shared one; not needed for this submission.
11	- **TTL:** 5–15 minutes. No refresh tokens — the client re-authenticates with its own client secret on expiry.
12	- **No denylist.** Revocation is handled by TTL shortness, not a stateful lookup. Don't build one; it's not missing, it's a deliberate trade-off already reasoned through in `api-auth-design.md`.
13	
14	## Where it's validated
15	
16	- **Middleware at the API edge**, in `internal/api/` per your published service boundary — every request to `cmd/api-service` passes through token validation before reaching a handler. `cmd/idp-connector` does not validate this token; it's a separate, outbound-only surface with its own auth story (`connector-security.md`), not a consumer of this scheme.
17	- **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 `api-service`; it lives with the token-issuing function, which is a mode of `api-service` (not a separate binary — see `handoff-04-secrets.md` Assumption 2), scoped by RBAC so the verification code path and the issuing code path don't share Secret access even though they're the same binary.
18	- **Key rotation:** expect a `kid` claim; publish old and new public keys together during rotation overlap. Token TTL (5–15 min) bounds how long that overlap needs to last.
19	
20	## Scope vocabulary (final, from S4 — `decisions/search-authz-scoping.md`)
21	
22	| Scope | Authorizes | Does not authorize | Object-level check |
23	|---|---|---|---|
24	| `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 `caller_referral` mapping (data owned by `../05-data-ops/`); out-of-set → reject, logged as a policy denial, distinct from an auth failure |
25	| `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 |
26	| `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 |
27	
28	`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`.
29	
30	**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.
31	
32	## Pagination, rate limits, decomposition resistance (requirements — numbers are fixed, mechanism is yours)
33	
34	- **Cursor-based pagination only** — no offset-based paging. Default page size 20, hard ceiling 50.
35	- **Per-client-credential rate limits:** 60 req/min for `read:own`/`read:any`; 10 req/min for `profile:search`.
36	- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that catches slow, under-the-cap enumeration (decomposition) that per-request and per-minute limits alone miss. The counting-store mechanism (Redis, in-process with periodic flush, whatever fits your stack) is your call; the requirement is that it exists and alerts on threshold, not just hard-blocks.
37	- Sustained near-limit usage on any of the above should alert, not just silently throttle.
38	
39	## Audit-log field list (every search/retrieve call)
40	
41	Log these fields, and only these — see `handoff-04-secrets.md`'s never-log list for what must never appear here:
42	
43	- `sub` (caller identity)
44	- `scope` used
45	- record id(s) touched (opaque ids, not the PII values)
46	- `reason_code`, when the scope is `profile:read:any`
47	- policy decision (`allow` / `deny`, and if `deny`, whether it was a scope failure or an `authorize()` policy denial — these are distinct signals for detection)
48	- timestamp
49	- request outcome (success/failure/rate-limited)
50	
51	Never in this log: PII field values, full JWTs, full request/response bodies. Per `handoff-04-secrets.md`'s new requirement, this log stream itself needs read access distinct from and narrower than whatever can read Secrets — that's 04's mechanism, but don't let the log ship without asking whether that separation exists.
52	
53	## What's not yours to decide (already decided upstream, don't re-derive)
54	
55	- **Grant type, token format, and claim set** — decided in `api-auth-design.md`; not open for re-litigation during implementation.
56	- **Scope vocabulary and provisioning bars** — decided in S4 (`decisions/search-authz-scoping.md`); if a real implementation constraint makes one of these unworkable, flag it back to me rather than adjusting it unilaterally.
57	- **The `DB_DSN_FILE` convention** — per `handoff-04-secrets.md`'s S7 revision, this track is asking you to add a file-based alternative to `DB_DSN` (env var becomes a transitional fallback, not a permanent equal option), because a DSN's embedded password is exposed by `kubectl describe`/crash dumps/child-process environment the same as any other secret in that inventory. This is a request into your config surface, not a unilateral change on my part — you decide the exact mechanism (a `_FILE` suffix convention or otherwise), I'm asserting the requirement.
58	- **Password/client-secret hashing** — Argon2id, decided in `threat-model.md` Asset 1; not this hand-off's concern beyond noting it exists.
59	- **PII retention/caching duration for anything the API returns** — `../05-data-ops/CLAUDE.md`'s call, not this track's or yours.
60	- **Whether `read:any` ever gets issued to a real caller** — per S4, the scope stays defined but unissued unless a caller clears the provisioning bar (caller-role table entry, named approver). Don't wire a default grant "just in case."
61	
62	## Open question back to you
63	
64	Nothing blocking. One thing worth a quick confirm when convenient: does your `internal/api/` middleware layer have a natural place to run the object-level `authorize()` check as a distinct step from scope validation (e.g., a second middleware or an explicit call inside each handler before the DAO call), or would you rather this track propose a specific Go interface shape for it? Either is fine — say which you'd find more useful and I'll adjust.
65	
66	---
67	Model: sonnet (Marcus Ilori, lead — compiled directly from S4's ruling, no new debate). Turns consumed: 0 hire turns (synthesis of already-ruled decisions per `PLAN.md` S6).
68	

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "Status: **v1**. Receiver: Renata Cole, `../03-engineering-delivery/`. Written to the project's hand-off standard: 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 decision records. Full reasoning, if wanted: `api-auth-design.md`, `decisions/search-authz-scoping.md`, `decisions/connector-token-lifecycle-redblue.md`.",
  "new_string": "Status: **v2** — updated after S8's independent review of `api-auth-design.md` and `connector-security.md` surfaced fixes that affect this hand-off; both already relayed to you by chat, folded into the durable file here per this project's hand-off standard. 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`."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "- **No denylist.** Revocation is handled by TTL shortness, not a stateful lookup. Don't build one; it's not missing, it's a deliberate trade-off already reasoned through in `api-auth-design.md`.",
  "new_string": "- **No denylist.** Revocation is handled by TTL shortness, not a stateful lookup. Don't build one; it's not missing, it's a deliberate trade-off already reasoned through in `api-auth-design.md`.\n- **Verifier must pin the expected algorithm** (whichever of RS256/ES256 you choose) and reject a token whose header claims any other algorithm, including `alg: none` and a downgrade to a symmetric algorithm using the public key as an HMAC secret (RFC 8725 §3.1). Check your JWT library's default behavior — several popular libraries have shipped this vulnerability by not doing this by default.\n- **Token-endpoint brute-force protection**, separate from the resource-API rate limits below: failed-grant rate limiting and progressive backoff per `client_id` and per source IP on the token-issuing endpoint itself, plus alerting on a sustained run of failed grants against one `client_id`. This protects the endpoint where a caller presents `client_id`/`client_secret`, which none of the resource-API limits below cover.\n- **Bearer-token replay is an accepted risk, not a gap to close in implementation.** This token has the same possession-equals-authority property as the connector's vendor token (`connector-security.md`); no PoP/binding is expected or required here. Noted so it isn't mistaken for something to \"fix\" during implementation."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "- **Middleware at the API edge**, in `internal/api/` per your published service boundary — every request to `cmd/api-service` passes through token validation before reaching a handler. `cmd/idp-connector` does not validate this token; it's a separate, outbound-only surface with its own auth story (`connector-security.md`), not a consumer of this scheme.",
  "new_string": "- **Middleware at the API edge**, in `internal/api/` per your published service boundary — every request to `cmd/api-service` passes through token validation before reaching a handler. `cmd/idp-connector` does not validate *this* token — but per `connector-security.md` §5 (added by S8 review), `idp-connector`'s own `/auth` and `/identity` handlers need the same JWT middleware pattern, with a **distinct audience** (`aud: idp-connector-service`, not `loginid-api-service`) and its own scope (`connector:identity-lookup`), restricted to internal callers (in this project's shape, `api-service` acting on a caller's behalf) — not the same token, not exposed to arbitrary external callers. Two audiences, one mechanism."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that catches slow, under-the-cap enumeration (decomposition) that per-request and per-minute limits alone miss. The counting-store mechanism (Redis, in-process with periodic flush, whatever fits your stack) is your call; the requirement is that it exists and alerts on threshold, not just hard-blocks.",
  "new_string": "- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that catches slow, under-the-cap enumeration (decomposition) that per-request and per-minute limits alone miss. **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). The counting-store mechanism (Redis, in-process with periodic flush, whatever fits your stack) is your call; the requirement is that it exists, applies to both scopes, and alerts on threshold, not just hard-blocks."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/second-review-security-docs.md",
  "content": "# Decision: Independent Second Review of Security-Graded Docs (S8)\n\nPattern: second review, independence assigned per-document by authorship history rather than the original static roster in `PLAN.md` — see reassignment note below. Each reviewer covers a document they neither authored nor blue-teamed during Phase 2 execution.\n\n## Reassignment note\n\n`PLAN.md`'s original S8 plan assigned Helena Marsh to review both `threat-model.md` and `api-auth-design.md`, and Ingrid Solano to review `connector-security.md`, on the assumption that neither had touched `api-auth-design.md`. That assumption broke during execution: Helena became S4's Proposer, authoring the finalized scope vocabulary and policy content in `api-auth-design.md`, and was also the blue seat in S3, authoring the controls in `connector-security.md`. Reviewing either would be an author reviewing their own work, not a second reviewer. Reassigned: **Helena → `threat-model.md` only** (never authored or blue-teamed); **Tomasz Wrede → `api-auth-design.md`** (no involvement in Phase 2 — his S3 work was the connector, not the search API); **Ingrid → `connector-security.md`** (unchanged — she never touched it).\n\n## Review: `threat-model.md` (Helena Marsh)\n\nFour citation/precision fixes, one completeness note, all accepted:\n\n1. NIST SP 800-63B was invoked by name for recommending Argon2id specifically, but 800-63B Rev. 3 (current) requires only \"a suitable memory-hard KDF\" without naming Argon2id — that specific naming is in the draft SP 800-63-4, not yet final. Fixed: claim softened to cite what 800-63B Rev. 3 actually requires, Argon2id credited to OWASP alone.\n2. WebAuthn counter/credential-ID integrity was asserted with no citation. Fixed: W3C WebAuthn Level 2 §6.1.1 added.\n3. The TLS 1.2+ floor was asserted with no citation. Fixed: NIST SP 800-52 Rev. 2 added.\n4. Credential-stuffing mitigation presented account lockout as a peer option alongside rate limiting/backoff; NIST SP 800-63B §5.2.2 actively disfavors lockout as a self-inflicted denial-of-service vector. Fixed: lockout language removed, throttling/backoff/step-up stated as the preference with the citation.\n5. **Completeness, not a defect:** the three-asset scope silently omitted this API's own issued JWTs. Fixed: one line stating that boundary explicitly as `api-auth-design.md`'s asset, not re-modeled here.\n\n## Review: `api-auth-design.md` (Tomasz Wrede)\n\nFour findings, ranked, all accepted:\n\n1. **High.** The cumulative distinct-record-touch counter (S4's fix for decomposition-style enumeration) was worded to exempt any call carrying a `reason_code`. `profile:read:any`'s policy hook already requires a `reason_code` on every call, so the exemption was unconditionally true for that scope — the counter that closed the decomposition gap for `profile:search` was a no-op for `profile:read:any`, the scope with the broadest blast radius (no referral constraint). Nobody in S4's adversarial pair was looking at this angle, since the counter itself was Ingrid's fix to a different objection (about `profile:search`). Fixed: the counter now applies to `read:any` regardless of `reason_code` presence.\n2. **Medium.** No stated defense against JWT algorithm confusion at the verifier (`alg: none`, RS256→HS256 downgrade). Fixed: verifier must pin the expected algorithm and reject any other, cited to RFC 8725 §3.1.\n3. **Medium-high.** No brute-force/lockout protection on the client-credentials token endpoint itself — every rate limit in the design protects the resource API after a token issues, none protect the endpoint where a caller obtains one. Fixed: per-`client_id`/per-IP failed-grant rate limiting and alerting added.\n4. **Minor, consistency.** This API's own bearer-token replay has the identical accepted-risk profile as the connector's vendor token (S3), but unlike the connector, it was never named as such — silently assumed safe rather than stated. Fixed: named explicitly as an accepted risk, with the same reasoning (TTL bounds exposure, no PoP lever expected or required).\n\n## Review: `connector-security.md` (Ingrid Solano)\n\nTwo findings, both accepted, both outside the frame of the three S3 participants (who were entirely focused on custody of the vendor token, not on who may call the connector or what a vendor token authorizes):\n\n1. **No authentication requirement on calls into the connector's own `/auth`/`/identity`.** §1–§4 protected the outbound vendor call exclusively; nothing stated who is allowed to reach the connector's own endpoints, which meant the rate-limiting control in §4 had no caller identity to bind \"per calling-API-client\" to. Fixed: new §5 requires the same OAuth2/JWT mechanism as the search API, with a distinct audience (`idp-connector-service`) and scope (`connector:identity-lookup`), restricted to internal service callers.\n2. **Whether a vendor token authorizes a query for an arbitrary identity, or only the token-holder's own, was unaddressed.** The design's entire token-handling discipline (§1) governs custody, not authority. Fixed: new §6 states plainly, as an assumption rather than a resolved control, that this design assumes the vendor binds `/identity` queries to the authenticated principal — and names the consequence if a real vendor doesn't.\n\n## Downstream propagation\n\nBoth `api-auth-design.md` fixes affecting implementation (finding 1's counter scope, findings 2–4) and `connector-security.md`'s new §5 (connector auth requirement) were folded into `handoff-03-auth.md` (now v2) and relayed directly to Renata Cole (03), who confirmed she will build the connector's handler auth to the new requirement from the start rather than retrofitting.\n\n## Why this run mattered (for `ai-workflow-narrative.md`, S9)\n\nEvery one of these six findings (4 in threat-model, 4 in api-auth-design — wait, tally below) survived because the reviewer had zero authorial investment in the document's existing frame. The `api-auth-design.md` finding 1 is the clearest case: the counter's flaw was invisible to Helena (who wrote it) and Ingrid (whose objection it was answering) precisely because both were reasoning inside \"does this satisfy the objection as stated,\" not \"does this control actually bind for every scope it claims to cover.\" Tomasz, arriving with no stake in either the original proposal or its revision, checked the mechanism against all three scopes independently and found the gap in under one review pass.\n\n**Tally, honestly counted (per S5's ruling that null results count too):** 4 + 4 + 2 = 10 findings across three documents, zero null reviews this time — every second-review seat found at least one real, accepted gap. This is a different (better) hit rate than S3's red/blue, where one of three top-ranked leaves (leaf 2 in S3) was conceded clean with no new finding. Both data points belong in S9's tally, not just the hits.\n\n---\nModel: sonnet (Helena Marsh, Tomasz Wrede, Ingrid Solano — reviews) / sonnet (Marcus Ilori, lead — reassignment ruling, fixes applied). Turns consumed: 3 (one review turn per document; no rebuttal round needed since all findings were accepted outright) — matches the 2-turn budget in `PLAN.md` §3, one turn over due to the third document added by the reassignment.\n"
}

File created successfully at: /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/decisions/second-review-security-docs.md (file state is current in your context — no need to Read it back)

{
  "to": "tomasz-wrede",
  "summary": "S8 closed — all four findings fixed",
  "message": "All four findings accepted and fixed in `api-auth-design.md`, propagated to `handoff-03-auth.md` v2 and relayed to Renata. Your finding 1 (the decomposition counter being a no-op for read:any) was the sharpest catch across all three S8 reviews this round — nobody in S4 was checking whether the fix for one scope's objection actually bound the other scope it was worded to cover. Full record: `decisions/second-review-security-docs.md`. Hold for your next seat.",
  "type": "message",
  "recipient": "tomasz-wrede",
  "content": "All four findings accepted and fixed in `api-auth…"
}

{"success":true,"message":"Message sent to tomasz-wrede's inbox","msg_id":"48cfeda6-057e-42f6-90fd-99afa312740b","routing":{"sender":"team-lead","target":"@tomasz-wrede","targetColor":"blue","summary":"S8 closed — all four findings fixed","content":"All four findings accepted and fixed in `api-auth…"}}

{
  "to": "helena-marsh",
  "summary": "S8 closed — all four fixes applied to threat-model.md",
  "message": "All four citation/precision fixes and the completeness note accepted and applied to `threat-model.md` — the NIST 800-63B claim corrected, WebAuthn and TLS citations added, the lockout-vs-throttling preference corrected per 800-63B §5.2.2, and the own-issued-JWT scope boundary stated explicitly. Full record: `decisions/second-review-security-docs.md`. This closes S8 — three documents, three independent reviewers, ten total findings, zero declined. Next up: S9 (revising `ai-workflow-narrative.md` for the org layer, incorporating S3's design change and this run's findings as evidence) and S10 (threat-model maintenance). Hold for now.",
  "type": "message",
  "recipient": "helena-marsh",
  "content": "All four citation/precision fixes and the complet…"
}

{"success":true,"message":"Message sent to helena-marsh's inbox","msg_id":"c0f97e12-047c-4e74-b7fd-c7127b9f029d","routing":{"sender":"team-lead","target":"@helena-marsh","targetColor":"green","summary":"S8 closed — all four fixes applied to threat-model.md","content":"All four citation/precision fixes and the complet…"}}

{
  "to": "org-planning-loginid-takehome",
  "summary": "S8 done — 10 findings across 3 docs, all fixed",
  "message": "S5 and S8 both closed. S5: structured debate ruled per-point — Felix's mechanism-level claim (a differently-tasked seat catches what self-review can't) held as a structural argument, not a statistical one; Ingrid's insistence that n=2 doesn't support a general law, and that null results (Tomasz's clean concession in S3) must be counted alongside hits, both held too. Record: `decisions/ai-workflow-claim-debate.md`.\n\nS8: had to reassign first — Helena's original two-document assignment (threat-model.md + api-auth-design.md) broke because she'd since authored the S4 revisions to api-auth-design.md and was S3's blue seat on connector-security.md, so she wasn't independent on either. Reassigned Helena→threat-model.md, Tomasz→api-auth-design.md (clean, no Phase 2 involvement), Ingrid→connector-security.md (unchanged). Result: 10 accepted findings across all three documents, zero declined, zero null reviews. Sharpest one: Tomasz found that api-auth-design.md's own S4-derived decomposition counter was a silent no-op for profile:read:any (the broadest-blast-radius scope) because its exemption clause was unconditionally satisfied by that scope's own required reason_code — invisible to both authors of that exchange since neither was checking the fix against every scope it claimed to cover. All fixes applied in place; the two implementation-relevant ones relayed to Renata directly and folded into handoff-03-auth.md v2. Full record: decisions/second-review-security-docs.md.\n\nMoving to S9 (narrative revision) and S10 (threat-model maintenance) next.",
  "type": "message",
  "recipient": "org-planning-loginid-takehome",
  "content": "S5 and S8 both closed. S5: structured debate rule…"
}

{"success":true,"message":"“S8 done — 10 findings across 3 docs, all fixed” → org-planning-loginid-takehome (another Claude session on this machine)","msg_id":"4db2a1f5-cf4d-4e6b-9a3f-28b9dd66c160"}

{
  "command": "grep -n \"postgres_cockroachdb\\|\\.sql\" /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "description": "Check for any stale .sql file references in threat-model.md"
}

12:Priya's prose schema in `../05-data-ops/multi-db-strategy.md` (the `.sql` files were deliberately wiped with the rest of the code on 2026-09-12; the prose contract is the source of truth until Warren's code go-ahead) gives `user_credential` three columns for this purpose: `secret` (nullable TEXT, salted hash only — NULL where `auth_method.requires_secret = false`, e.g. passkey/WebAuthn), `hash_algo` (VARCHAR, e.g. `'argon2id'`), and `hash_cost` (INTEGER, the work factor at hash time). This track's concrete decision against those columns:

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/ai-workflow-narrative.md",
  "old_string": "## What was AI-generated vs. human-directed",
  "new_string": "## The org layer: personas, patterns, and debates (added after Phase 2 execution)\n\nThe structure above (root brief, five track briefs, scoped subagents) is the skeleton. What actually ran inside it, once Warren authorized hiring, was a second layer this project built on top of Anthropic's documented patterns rather than found in them: each of the five track leads hired a small sub-team of persona-bearing agents — this track hired four (Tomasz Wrede, an Adversary; Helena Marsh, a Principled Architect; Felix Adebayo, a Tinkerer and this lead's deliberate temperament opposite; Ingrid Solano, a Designated Skeptic) — and ran a small catalog of named orchestration patterns (red team/blue team, adversarial pair, structured written debate, independent second review, rotating devil's advocate, three hats) against specific design decisions, each ending in a durable decision file under `decisions/`. **This entire layer — the personas, the variance rules in `../CASTING.md`, the pattern catalog, the rule that every decision artifact records its own model/turn-count footer — is this project's own design, not an Anthropic-documented technique.** It's a deliberate, load-bearing extension built on top of the orchestrator-worker pattern (§\"Orchestration\" above), motivated by a specific risk Anthropic's own writing doesn't have to worry about but a five-lead org does: five track leads (and the PM) starting from the same base model land in the same temperament quadrant by default, and agreement between agents who all think alike is not evidence of a good decision.\n\n### What the pattern catalog actually bought, honestly measured\n\nThis is not a claim that multi-agent debate produces better designs than a single strong session **in general** — that claim was itself put to a structured written debate in this track (S5, `decisions/ai-workflow-claim-debate.md`) and the ruling is reproduced faithfully below, including the position that lost ground. What can be stated and evidenced:\n\n- **S3 (red/blue, connector token lifecycle):** Tomasz's red seat produced five ranked attack leaves, each shaped as \"add a control\" (encrypt the cache harder, bind the token, rate-limit more). Felix's alternatives seat — a role that exists specifically to ask \"does the thing being protected need to exist\" rather than \"is the control sufficient\" — proposed deleting two of those leaves outright by removing the token cache entirely (fetch-per-call instead of cache-with-a-TTL), rather than hardening it. That's a concrete design change this document can point to that would not have existed without a seat whose brief was structurally different from the seat before it. Tomasz's own rebuttal turn then conceded two of the remaining three leaves cleanly (no new finding) and tightened the third — a fair count includes that clean concession as a null result, not just the hit. **Tally: 2 hits (deleted leaves), 1 tightening, 2 null (clean concessions).**\n- **S8 (independent second review, three security-graded documents):** required a mid-flight reassignment when the original static roster (`PLAN.md`) turned out to assign a reviewer to review her own prior authorship — itself a small proof that a process built to catch blind spots needs the same discipline applied to its own execution, not just its subjects. Once corrected (Helena → `threat-model.md`, a document she never touched; Tomasz → `api-auth-design.md`, likewise; Ingrid → `connector-security.md`, unchanged), all three reviewers found real, accepted gaps: Tomasz found that a decomposition-resistant rate-limit control S4 had just finished designing was a silent no-op for one of the two scopes it claimed to cover, invisible to both S4 participants because neither was checking the fix against every scope it was worded to bind. Ingrid found that a document entirely about protecting a vendor token's custody said nothing about who may call the connector holding that token, or what the token authorizes once used — a different class of question from the one the S3 red/blue run had spent its effort on. **Tally: 10 accepted findings across 3 documents, 0 declined, 0 null reviews.**\n- **Theo's Newcomer cold-read of `handoff-04-secrets.md` (04's track, not this one, but this track's document):** two real gaps (an undefined component's feature status, a trust-boundary reference that required reading a second track's file to parse) that survived this document's own author's review, caught by a reader with zero authorial investment. **1 hit.**\n\n### What the S5 debate actually settled — stated plainly, including the losing position\n\nFelix argued (Position A) that this evidence shows the pattern produces better designs than a single strong session would. Ingrid argued (Position B) that two data points, both produced by roles this project built specifically to produce exactly this kind of catch, are not evidence of a general effect — a single session working from an explicit checklist (\"can this control's leaf be deleted instead,\" \"get one cold read before shipping\") could plausibly produce the same catches without four personas and a debate protocol, and nobody has run or estimated that comparison. The ruling (`decisions/ai-workflow-claim-debate.md`) went **against** the general claim and **for** a narrower one: the defensible statement is a structural/mechanism argument, not a statistical one — a seat holding a genuinely different optimization target, or a reader with no authorial stake, can surface a class of error that self-review structurally tends not to, because self-review interrogates the answer it already committed to rather than the frame that produced the question. That is not the same as asserting multi-agent design beats solo design as a population-level effect, and this document does not make that broader claim. Ingrid's insistence that null results (the S3 leaf conceded clean, S8's near-zero null rate by contrast) be counted in the same tally as hits was adopted outright and is reflected in the tallies above, not just the successes.\n\n### The external operator agent: named, never contacted\n\nA real external agent exists in this environment: an operator, human or automated, holding cluster-admin or namespace-admin rights on 04's design-only Kubernetes lab cluster, capable of applying manifests to it. This track's threat model names that operator as a privileged actor and trust boundary (`threat-model.md`, Assumption 6) — not a hypothetical, a real agent this project could technically reach. **It was deliberately kept out of scope for the entire duration of this project: never contacted, nothing deployed, no manifest applied.** This is stated here because an AI-workflow narrative that documents every agent this project *did* use would be incomplete, arguably misleading by omission, if it didn't also state plainly which real agent in the environment it declined to use and why — the boundary was a design decision (design-only reference target), not an oversight or a capability gap.\n\n## What was AI-generated vs. human-directed"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/ai-workflow-narrative.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/ai-workflow-narrative.md",
  "old_string": "- **S8 (independent second review, three security-graded documents):** required a mid-flight reassignment when the original static roster (`PLAN.md`) turned out to assign a reviewer to review her own prior authorship — itself a small proof that a process built to catch blind spots needs the same discipline applied to its own execution, not just its subjects. Once corrected (Helena → `threat-model.md`, a document she never touched; Tomasz → `api-auth-design.md`, likewise; Ingrid → `connector-security.md`, unchanged), all three reviewers found real, accepted gaps: Tomasz found that a decomposition-resistant rate-limit control S4 had just finished designing was a silent no-op for one of the two scopes it claimed to cover, invisible to both S4 participants because neither was checking the fix against every scope it was worded to bind. Ingrid found that a document entirely about protecting a vendor token's custody said nothing about who may call the connector holding that token, or what the token authorizes once used — a different class of question from the one the S3 red/blue run had spent its effort on. **Tally: 10 accepted findings across 3 documents, 0 declined, 0 null reviews.**",
  "new_string": "- **S8 (independent second review, three security-graded documents) — the most valuable process evidence in this track, worth stating as a general lesson rather than just an incident report.** `PLAN.md`'s original static roster assigned Helena to review both `threat-model.md` and `api-auth-design.md`. By the time S8 actually ran, that assignment was stale: Helena had since become S4's Proposer and authored the very scope-vocabulary and policy content in `api-auth-design.md` that S8 was meant to check, and had also been S3's blue seat authoring the controls in `connector-security.md`. Reviewing either would have been an author re-reviewing their own work under the label \"independent review.\" **The lesson: independence is a property that has to be checked at the moment a review actually runs, not a role assigned once at planning time and trusted to still hold** — a five-track org where the same small hire roster accumulates authorship across successive debates will decay its own independence guarantees exactly this way if nobody re-checks before each review. Caught here before running (Helena reassigned to `threat-model.md` only, a document she never touched; Tomasz — clean, no Phase 2 involvement in this document — took `api-auth-design.md`; Ingrid kept `connector-security.md`, unaffected), not after.\n\n  With independence actually verified, the reviews earned their cost. **The concrete example worth leading with:** Tomasz found that the decomposition-resistant rate-limit counter S4 had just finished designing — specifically as Ingrid's own fix to her objection 4 in that same debate — was a silent no-op for `profile:read:any`, the scope with the broadest blast radius, because its exemption clause (\"without a fresh `reason_code`\") was unconditionally satisfied by a scope that already requires a `reason_code` on every call by design. Neither Helena (who wrote the fix) nor Ingrid (whose objection it answered) caught this, because both were reasoning inside \"does this satisfy the objection as stated\" — the same self-referential blind spot independent review exists to catch, now demonstrated on the review pattern's own prior output, one debate later. Ingrid's separate finding on `connector-security.md` — that a document entirely about protecting a vendor token's custody said nothing about who may call the connector holding it, or what the token authorizes once used — is a different class of question from the one the S3 red/blue run spent its effort on, for the same underlying reason: every S3 participant was already inside the \"protect the token\" frame. **Tally: 10 accepted findings across 3 documents, 0 declined, 0 null reviews** — a different, better hit rate than S3's, and both numbers belong in this document, not just the ones favorable to the claim."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/ai-workflow-narrative.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/CLAUDE.md",
  "old_string": "Remaining: S5 (structured written debate on `ai-workflow-narrative.md`'s core claim, Felix/Ingrid), S8 (independent second review of the security-graded docs), S9 (revise `ai-workflow-narrative.md` for the org layer), S10 (threat-model.md maintenance), S1/S2 already folded into `CASTING.md`/`planning-approach.md` in Phase 1. S11 deferred to Warren's code go-ahead.\n\nNext: S5 or S8, lead's call on sequencing; open to review/adjustment as 03's and 05's implementation surfaces any gaps in the S3/S4/S6 hand-offs.",
  "new_string": "**All eleven Stories complete except S11** (post-implementation review, deferred to Warren's code go-ahead). S5 (`decisions/ai-workflow-claim-debate.md`) ruled against a general \"multi-agent beats solo\" claim and for a narrower, mechanism-level one, with the losing arguments preserved honestly. S8 (`decisions/second-review-security-docs.md`) required a mid-run reassignment when Helena's S4/S3 authorship broke her original independence on two of the three documents — caught and fixed before running, not after; ten accepted findings resulted, the sharpest being a decomposition-resistant rate-limit control from S4 that was a silent no-op for one of its two target scopes. S9 folded the org layer — personas, patterns, measured turn/model footers, S5's ruling stated plainly including the side that lost, the S8 reassignment as a general lesson (\"independence is checked at review time, not assigned once\"), and the real external operator agent named as deliberately out of scope — into `ai-workflow-narrative.md`. S10's two required fixes (repoint the wiped-schema reference, name the operator trust boundary) were already present in `threat-model.md` from earlier work; verified clean, no further edit needed.\n\nNext: available for cross-track consistency pass; open to review/adjustment as 03's and 05's implementation surfaces any gaps in the S3/S4/S6 hand-offs."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/CLAUDE.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "offset": 7,
  "limit": 9
}

7	| Track | Lead | Status | Blocking on | Blocked by | Planning notes | Hires (planned / registered / spawned) | Last updated |
8	|---|---|---|---|---|---|---|---|
9	| Orchestration (root) | Dana Whitfield | Phase 3 — 01, 03, 04 planning work complete; 02 on S8–S10; 05 S1 contract is the critical path; consistency pass next | 05 S1 contract; 02 S9 narrative | — | `PLAN.md`, `LOG.md` | 18 / 18 (cap) | 2026-09-12 |
10	| Cross-track consistency pass (root, Phase 3) | Dana Whitfield | not started | all five `plan approved` | — | `PLAN.md` Phase 3 | — | 2026-09-12 |
11	| 01 Product & Industry Research (incl. Design) | Naomi Voss | plan approved — S1–S6 all done (claims audit, password-baseline debate, connector rationale hardened + cold read, search-authz requirements, UX notes, evaluator-legibility cold read) | — | — | `01-product-industry-research-design/PLAN.md`; `decisions/claims-audit.md`, `decisions/password-baseline-debate.md`, `decisions/rationale-cold-read.md` (S3+S6) all written; Newcomer loan from 04 (`wesley-okonkwo`) closed at 2/2-4 turns, both passed clean | 3 / 3 / 3 | 2026-09-12 |
12	| 02 AI Architecture & Security Architecture | Marcus Ilori | S3, S4, S6, S7 done — S5/S8/S9/S10 next | — | — | `02-ai-security-architecture/PLAN.md`; S3 `decisions/connector-token-lifecycle-redblue.md` + table in `connector-security.md`; S4 `decisions/search-authz-scoping.md` + finalized scoping in `api-auth-design.md`; S6 `handoff-03-auth.md` sent to 03; S7 `handoff-04-secrets.md` v1 sent to 04, cold-read and fixed | 4 / 4 / 4 | 2026-09-12 |
13	| 03 Engineering & Delivery | Renata Cole | hires spawned 4/4 — `handoff-03-auth.md` received, cold read clean | 05 contract (DAO) | — | `03-engineering-delivery/PLAN.md`; `handoff-03-auth.md` accepted, `DB_DSN_FILE` folded into Service boundaries config surface | 4 / 4 / 4 | 2026-09-12 |
14	| 04 Infra & DevOps | Theo Bergman | five deliverables drafted, Bree/Callum notes folded in | — | — | `04-infra-devops/PLAN.md`; `containerization-design.md`, `ci-pipeline.md`, `local-dev-loop.md`, `secrets-delivery.md`, `observability.md` | 3 / 3 / 3 | 2026-09-12 |
15	| 05 Data Ops | Priya Nandakumar | hires spawned 4/4 — S3 ruled, S2 open, S5 in progress | — | — | `05-data-ops/PLAN.md`; 6 stories S1–S6, S1 = Go-shaped contract in `multi-db-strategy.md` (critical path); S4 `migration-approach.md` + S5 retention table unblock 04; `migration-approach.md` drafted for 04 (R1–R5; single-runner requirement is platform-enforced — pg_advisory_lock is unavailable on CockroachDB), pending one objection turn; deep research authorized+run (lead): `05-data-ops/research-cockroachdb-postgres-semantics.md` — one Go package CAN serve Postgres+CockroachDB but needs an engine-aware retry/error seam (CRDB SERIALIZABLE returns client-retryable 40001; sentinel translation must be SQLSTATE-only); corrects R2 of `migration-approach.md`; S3 ruled `05-data-ops/decisions/multi-db-abstraction.md` — per-driver confirmed, but on reviewability not cost (only 2 real conditionals, doc's rejection reasoning corrected); codegen is orthogonal, 03's choice; **requirement on 03: one conformance suite run against every backend** — SQLite `LIKE` is case-insensitive vs Postgres case-sensitive, so the documented parity gap is a correctness gap, not a performance one; factory mismatch closed with 03 direct (two-party): `dao.Repository` composite exposing `Profiles()`/`Credentials()`/`Methods()`, `dao.New` signature unchanged — cited in S1 | 4 / 4 / 4 | 2026-09-12 |

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/PLANNING.md",
  "old_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | S3, S4, S6, S7 done — S5/S8/S9/S10 next | — | — | `02-ai-security-architecture/PLAN.md`; S3 `decisions/connector-token-lifecycle-redblue.md` + table in `connector-security.md`; S4 `decisions/search-authz-scoping.md` + finalized scoping in `api-auth-design.md`; S6 `handoff-03-auth.md` sent to 03; S7 `handoff-04-secrets.md` v1 sent to 04, cold-read and fixed | 4 / 4 / 4 | 2026-09-12 |",
  "new_string": "| 02 AI Architecture & Security Architecture | Marcus Ilori | all Stories done except S11 (post-code-go-ahead) — ready for consistency pass | — | — | `02-ai-security-architecture/PLAN.md`; S3/S4/S6/S7 as before; S5 `decisions/ai-workflow-claim-debate.md` (ruled against a general multi-agent-beats-solo claim, for a narrower mechanism-level one); S8 `decisions/second-review-security-docs.md` (required an independence reassignment mid-run — caught before running; 10 accepted findings, 0 declined); S9 `ai-workflow-narrative.md` revised with the org layer, measured costs, and the S5/S8 lessons stated plainly; S10 verified already clean, no edit needed | 4 / 4 / 4 | 2026-09-12 |"
}

The file /Users/warrenthompson/Source/LoginID/PLANNING.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "to": "org-planning-loginid-takehome",
  "summary": "S9 and S10 closed — all Stories done except S11",
  "message": "S9 and S10 both closed. S9: `ai-workflow-narrative.md` now carries the org layer explicitly — leads it with Tomasz's profile:read:any no-op finding, states the S8 reassignment as the general lesson you flagged (\"independence is checked at review time, not assigned once — a role trusted once at planning can decay as the same small roster accumulates authorship across debates\"), and reports S5's ruling honestly including the position that lost (Ingrid's n=2/count-the-nulls objections held over Felix's broader claim, though his narrower mechanism-level argument survived). Also names the real external operator agent and states it was deliberately never contacted. S10: both required fixes were already present in `threat-model.md` from earlier work (schema reference, operator trust-boundary line) — verified clean, nothing to change.\n\nAll eleven Stories in this track's plan are done except S11 (post-implementation review, gated on your code go-ahead as planned). PLANNING.md and this track's CLAUDE.md Status updated. Ready for the consistency pass — let me know if you want anything from this track for it.",
  "type": "message",
  "recipient": "org-planning-loginid-takehome",
  "content": "S9 and S10 both closed. S9: `ai-workflow-narrativ…"
}

{"success":true,"message":"“S9 and S10 closed — all Stories done except S11” → org-planning-loginid-takehome (another Claude session on this machine)","msg_id":"9f8477e6-6d26-4189-a164-afe2aca4ca34"}

{
  "command": "grep -n \"Phase 4\" -A 100 /Users/warrenthompson/Source/LoginID/PLAN.md | head -150",
  "description": "Find Phase 4 section in root PLAN.md"
}

145:### Phase 4 — Jira (Warren's go: 2026-09-12, "start building out the backlog")
146-
147-Team-lead is the single Jira writer (one authenticated session, one audit trail); leads author. Each lead writes `<track-dir>/backlog.md` — the in-repo, versioned backlog, which is itself a submission artifact — and team-lead transcribes it into project `LT` (cloudId `db488eae-d6cb-4100-92a9-e7a4519fc176`) and writes the issue keys back into the file.
148-
149-`backlog.md` format, identical for every track:
150-- Header: track, lead, Epic title (team-lead creates one Epic per track; the key is written back here).
151-- One section per Story, in dependency order: **Title** (imperative, ≤ 80 chars); **Description** (what and why, 3–8 sentences, citing the deliverable and decision files by relative path); **Acceptance criteria** as a checklist — the first criterion is always the hand-off standard ("the receiving track can act on this without re-deriving the reasoning"), and every caller-visible guarantee names its enforcement site; **Depends on** (other tracks' story titles, which become Jira "blocks/is blocked by" links); **Model/effort** recommended for implementation (from `planning-approach.md`); **Type** Story or Task; **Labels** (`track-0N`, plus `security-graded` where 02's second-review rule applies, `no-code-yet` until Warren's code go).
152-- Stories arising from the consistency pass are added under whichever track owns the fix, with a `from-consistency-pass` label; a jointly owned story (e.g., the derived-data deletion gap across 02/04/05) is created once under the track that owns the enforcement site, with the other two linked as dependencies.
153-
154-Order: 01 authors and is transcribed immediately (closed first, least touched by the pass); 05 has stories ready and follows; 02/03/04 author now and are transcribed the moment the consistency pass reports, so pass-driven revisions land once. Implementation still waits for Warren's explicit code go-ahead; "backlog strong enough to start implementation" is team-lead's call to Warren, defined as: every track's stories transcribed, every cross-track dependency linked, every pass finding either resolved or carried as a story, and 03's implementation stories each pointing at a stable contract.
155-
156-## Verification
157-
158-- Phase 0: `PLAN.md`, `LOG.md` (backfilled), `PLANNING.md`, `CASTING.md`, `.gitignore` exist at root; `.claude/AGENT_TEMPLATE.md` exists; root `CLAUDE.md` Status updated; `git log` shows the Phase 0 milestone commit; `find . -name '*.go' -o -name '*.sql' -o -name 'go.mod'` still returns nothing.
159-- Every later phase: `LOG.md` has an entry and `git log` has a milestone commit for it; `diff ~/.claude/plans/cuddly-nibbling-cherny.md PLAN.md` is empty or `PLAN.md` is newer.
160-- Phase 1: five `plan_approval_request`s received and answered; each approved plan has all four mandatory sections; every roster passes the variance rules when read together (no archetype > 2×, each team has its lead's opposite, no duplicate archetype-per-function across teams); total hires ≤ cap.
161-- Phase 2: for every registry row, `<track>/profiles/<slug>/<slug>.md` exists with a `## Personality` section containing history and technical background, `.claude/agents/<slug>.md` exists with model/effort frontmatter; `grep -c "profile-gen:start" */CLAUDE.md CLAUDE.md` still totals 6 (no hire markers); each hire's pane status bar shows its own track directory and its own persona name (tmux `capture-pane` check, as done for the leads); `portrait-queue.sh` log shows serialized progress.
162-- Phase 3: each planned pattern produced its decision artifact file; `PLANNING.md` rows all read "plan approved"; consistency-pass report delivered.
163:- Phase 4: one Epic per track and stories under them visible on the LT board.
164-
165-## Decisions confirmed with Warren before execution
166-
167-- Hire sizing: **confirmed by Warren** — the larger org, 3–4 per track, 18 total, hard cap 18.
168-- Portraits: **confirmed by Warren** — text-first personas for all hires, portraits for all 18 via the serialized background queue (18 renders at 2–10 min each on the shared box ≈ 1–3 hours, overlapping the planning debates; personas display name-only until each lands).
169-- Effort: implemented as inherit-high plus `haiku → low` via project `.claude/settings.json`, since the harness has no per-agent effort key.
170-- tmux: leads stay in window 2 (the 3×2 grid); when hires appear, team-lead moves each team's hires into a new tmux window named for the track (`01-product`, `02-security`, …) so no window exceeds ~6 panes. Team-lead owns layout.

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/backlog.md",
  "content": "# Backlog — Track 02: AI Architecture & Security Architecture\n\nLead: Marcus Ilori. Epic: **02 AI Architecture & Security Architecture** (Jira key: _pending team-lead transcription_). Format per `../PLAN.md` Phase 4. All eleven stories from `PLAN.md` are listed in dependency order; ten are done (marked below) and shown as-run, not rewritten as if planned in hindsight — an honest backlog shows the work. S11 is the one open story, gated on Warren's implementation go-ahead.\n\n---\n\n## S1 — Ratify the orchestration-pattern catalog and add the attack-tree template\n\n**Status: done.**\n\n**Description:** Reviewed `../CASTING.md` §5's six orchestration patterns against this track's own planning reasoning and ratified them with four amendments (red/blue ranking discipline, adversarial-pair \"what would change my mind\" lines, structured-debate synthesis discipline, universal model/turn-count footers), then authored the attack-tree table template as Appendix A of `planning-approach.md`. Every later pattern run in this track (S3, S4, S5, S8) executed under this ratified catalog. See `PLAN.md` §0 for the full reasoning.\n\n**Acceptance criteria:**\n- [x] `../CASTING.md` §5 carries the four ⟨02⟩ amendments, changes scoped only between the `## 5.` and `## 6.` headings.\n- [x] `planning-approach.md` Appendix A exists with the table shape used by every later red/blue run.\n- [x] Every decision artifact produced after this story carries a model/turn-count footer (verified in `decisions/*.md`).\n\n**Depends on:** —\n\n**Model/effort:** sonnet, high (lead-authored, no hire turns).\n\n**Type:** Story\n\n**Labels:** `track-02`\n\n---\n\n## S2 — Harness-constraints addendum to `planning-approach.md`\n\n**Status: done.**\n\n**Description:** Checked `PLAN.md`'s \"Verified mechanics\" claims about model/effort tiers against `research-claude-architecture-best-practices.md` and recorded the harness facts that modify the org's model/effort plan (no per-agent effort key; hires don't spawn subagents; a hire's agent-definition file is part of its prompt-cache prefix). Written as Appendix B of `planning-approach.md` so every lead building a research fan-out or a hire roster works from the same corrected assumptions.\n\n**Acceptance criteria:**\n- [x] `planning-approach.md` Appendix B exists and states the three harness facts and their consequence for §1's tiers.\n- [x] No contradiction found against the research doc (stated explicitly, not silently assumed).\n\n**Depends on:** —\n\n**Model/effort:** sonnet, high (lead-authored).\n\n**Type:** Story\n\n**Labels:** `track-02`\n\n---\n\n## S3 — Red/blue: connector token lifecycle\n\n**Status: done.**\n\n**Description:** Ran the ratified red/blue pattern (S1) against the IDP connector's vendor-token handling in `connector-security.md` §1: Tomasz Wrede's ranked top-five attack leaves, Felix Adebayo's alternatives turn (deleting two leaves by design change — no-cache-by-default rather than an encrypted, TTL-bound cache), Helena Marsh's blue response, Tomasz's rebuttal turn (closing a connection-reuse variant and tightening the accepted-replay-risk boundary). Full record: `decisions/connector-token-lifecycle-redblue.md`; attack-tree table appended to `connector-security.md`. This is the requirement set 03's connector implementation builds against directly.\n\n**Acceptance criteria:**\n- [x] The receiving track (03) can implement the connector's token handling without re-deriving this run's reasoning — confirmed by Renata Cole directly.\n- [x] \"No persistent token cache by default\" — enforcement site: the connector's HTTP client construction, one fetch-per-`/identity`-call code path, no cache read/write call in the default path.\n- [x] \"Fresh, isolated `Authorization` header per outbound request\" — enforcement site: the outbound HTTP client factory used for vendor calls, explicitly not sharing a request-context object across calls.\n- [x] \"Fetch → use → zeroize, retries re-fetch\" — enforcement site: the token variable's scope inside the single vendor-call function; a retry path that calls `/auth` again rather than reusing a held token.\n- [x] Residual risk (bearer-token replay, accepted) is named in the artifact, not left implicit.\n\n**Depends on:** S1\n\n**Model/effort:** opus, high for the connector's token-lifecycle implementation specifically (per `planning-approach.md` §1 — the one implementation surface warranting opus); sonnet, high for this track's design/debate turns.\n\n**Type:** Story\n\n**Labels:** `track-02`, `security-graded`\n\n---\n\n## S4 — Adversarial pair: search-API authorization scoping\n\n**Status: done.**\n\n**Description:** Ran the adversarial pair pattern against `api-auth-design.md`'s scope sketch: Helena Marsh (Proposer) drafted the final scope vocabulary, `profile:search` provisioning bar, object-level policy hook, and pagination/rate-limit/lifecycle rules; Ingrid Solano (Skeptic) raised five numbered objections, each with a \"what would change my mind\" line; Helena revised all five. Full record: `decisions/search-authz-scoping.md`; finalized design folded into `api-auth-design.md`. This is the scope model 03's middleware and object-level policy checks implement directly.\n\n**Acceptance criteria:**\n- [x] `profile:read:own` referral constraint — enforcement site: `authorize(sub, scope, target)` checking the `caller_referral` mapping, called in-handler before the DAO call (per Renata's confirmed placement).\n- [x] `profile:read:any` requires a `reason_code` from a closed enum on every call — enforcement site: request validation inside the same `authorize()` call, rejecting a missing or out-of-enum value.\n- [x] `profile:search` result-cap rejection (not truncation) — enforcement site: query-construction code in the search handler, checked before the DB call executes.\n- [x] Cursor-based pagination, page ceiling 50 — enforcement site: pagination-parameter validation in the handler layer.\n- [x] Per-client rate limits (60/10 req/min) and the cumulative distinct-record-touch counter, applying to `read:any` regardless of `reason_code` presence — enforcement site: rate-limiting middleware plus a counting store keyed per client credential, incremented per distinct record id returned.\n- [x] Scope-grant lifecycle (90-day backstop, immediate revocation on offboarding/idle/function-change) — enforcement site: whatever identity-lifecycle signal 03/04 wire the grant-issuing component to consume.\n\n**Depends on:** S1\n\n**Model/effort:** sonnet, high (middleware and policy-check implementation); sonnet, high for this track's debate turns.\n\n**Type:** Story\n\n**Labels:** `track-02`, `security-graded`\n\n---\n\n## S5 — Structured written debate: `ai-workflow-narrative.md`'s core claim\n\n**Status: done.**\n\n**Description:** Debated whether this project's multi-agent, persona-driven workflow produces better design than a single strong session, or is cost without evidence. Felix Adebayo (Position A) argued from two concrete instances (S3's design-deleting alternatives turn, 04's Newcomer cold-read catches); Ingrid Solano (Position B) rebutted that n=2 from roles built to find exactly this isn't evidence of a general law, and that null results (a clean concession in S3) must be counted alongside hits. Ruled per point in `decisions/ai-workflow-claim-debate.md`: against a general empirical claim, for a narrower mechanism-level one. Result folded into `ai-workflow-narrative.md` (S9).\n\n**Acceptance criteria:**\n- [x] Both positions preserved in the record, not just the winning one.\n- [x] The ruling states which position won on which point and why (per the `CASTING.md` §5 ⟨02⟩ amendment this story itself ratified in S1).\n- [x] The narrative (S9) states the mechanism-level claim, not the broader statistical one Position B defeated.\n\n**Depends on:** —\n\n**Model/effort:** sonnet, high.\n\n**Type:** Story\n\n**Labels:** `track-02`\n\n---\n\n## S6 — Hand-off 02→03: auth scheme, validation point, authorization requirements\n\n**Status: done** (`handoff-03-auth.md`, v2 after S8 revisions).\n\n**Description:** Synthesized S4's ruling and the token-shape decisions in `api-auth-design.md` into a receiver-shaped hand-off Renata Cole can build against without re-deriving this track's reasoning: token scheme, where it's validated, the final scope vocabulary and object-level policy hook, pagination/rate-limit numbers, the audit-log field list, and an explicit \"not yours to decide\" list. Revised to v2 after S8's independent review surfaced two implementation-relevant fixes (the decomposition counter's scope-coverage gap; the connector's own inbound-auth requirement). Accepted by 03 with a confirmed `authorize()` placement (in-handler, not middleware) and `DB_DSN_FILE` folded into the config surface.\n\n**Acceptance criteria:**\n- [x] Receiving track (03) can act on this without re-deriving the reasoning in `api-auth-design.md`/`connector-security.md` — confirmed by Renata directly, cold read \"clean.\"\n- [x] Token TTL (5–15 min), no refresh, no denylist — enforcement site: `exp` claim check in the verification middleware; absence of a refresh-grant or denylist-lookup code path.\n- [x] Verifier pins expected algorithm, rejects `alg: none`/downgrade — enforcement site: explicit algorithm allow-list parameter on the JWT verification call.\n- [x] Public-key-only verification in `api-service`; private key isolated to the issuing code path — enforcement site: Kubernetes RBAC Role (per `handoff-04-secrets.md` row #2) plus code-level separation between issuing and verifying functions.\n- [x] `idp-connector`'s own `/auth`/`/identity` require authentication with a distinct audience/scope — enforcement site: the same JWT middleware pattern applied to `idp-connector`'s router, configured with `aud: idp-connector-service`.\n- [x] Token-endpoint brute-force protection — enforcement site: rate limiter on the token-issuing endpoint, keyed by `client_id` + source IP.\n- [x] Audit-log field list (`sub`, scope, record id, `reason_code`, policy decision, timestamp, outcome) and nothing beyond it — enforcement site: a single structured-logging call at the end of each search/retrieve handler, not scattered `log.Printf` calls a reviewer has to hunt for.\n\n**Depends on:** S4\n\n**Model/effort:** sonnet, high (lead synthesis, no new hire turns); sonnet, high for 03's implementation against it.\n\n**Type:** Story\n\n**Labels:** `track-02`, `security-graded`\n\n---\n\n## S7 — Hand-off 02→04: secrets inventory and never-log list\n\n**Status: done** (`handoff-04-secrets.md`, v1).\n\n**Description:** Authored the secrets inventory and never-log list Theo Bergman's track needs to design secrets delivery against, then ran Ingrid Solano's single objection turn (S7's assigned pattern — one turn, not a full debate) and folded in all four accepted objections: the authorization-server's ownership was mis-scoped by omission, a KMS-access credential row was missing, the `DB_DSN` env-var exception was too weak, and audit-log read access needed its own RBAC line distinct from Secret access. Cold-read by 04's Newcomer (Wesley Okonkwo) caught two further gating gaps (TOTP/token-cache feature-status ambiguity; a non-self-contained trust-boundary reference), both fixed.\n\n**Acceptance criteria:**\n- [x] Receiving track (04) can act on this without re-deriving the reasoning in `threat-model.md`/`api-auth-design.md`/`connector-security.md` — confirmed by 04's Newcomer cold read, two gating items fixed before acceptance.\n- [x] `DB_DSN_FILE` required as the primary delivery mechanism, `DB_DSN` a transitional fallback — enforcement site: the config-loading code in `internal/config`, preferring the file path when both are set (confirmed folded into 03's Service boundaries).\n- [x] JWT signing private key file-mount only, RBAC-restricted to the issuing code path's service account — enforcement site: the Kubernetes Role scoping `get`/`list` on that Secret.\n- [x] Client secrets stored hashed (Argon2id), never plaintext at rest — enforcement site: the provisioning code path that writes the hash, per `threat-model.md` Asset 1.\n- [x] One `Secret` per vendor registration (ABC/XYZ never share a Secret) — enforcement site: the Kubernetes manifest's per-vendor Secret object.\n- [x] Never-log list (vendor password, vendor token, PII values, raw vendor error bodies, signing key, JWTs, client secrets, `DB_DSN`, full `/auth`/`/identity` bodies, PII-bearing query params) — enforcement site: a log-formatting/redaction layer that structurally cannot emit these fields, not a code-review convention alone.\n- [x] Audit-log read access is a distinct, narrower grant than Secret-read access — enforcement site: log-pipeline RBAC or a separate log-sink access control, 04's mechanism.\n\n**Depends on:** one Skeptic objection turn (no debate pattern)\n\n**Model/effort:** sonnet, high (lead synthesis + one hire turn).\n\n**Type:** Story\n\n**Labels:** `track-02`, `security-graded`\n\n---\n\n## S8 — Independent second review of the security-graded documents\n\n**Status: done.**\n\n**Description:** Ran an independent second-review pass on `threat-model.md`, `api-auth-design.md`, and `connector-security.md`, each reviewed by a hire who neither authored nor blue-teamed it. Required a mid-run reassignment: the original static roster assigned Helena Marsh to review two documents she'd since authored content in (S4's Proposer role, S3's blue seat) — caught and corrected before running, not after. Result: Helena reviewed `threat-model.md` (4 citation/precision fixes, 1 completeness note), Tomasz Wrede reviewed `api-auth-design.md` (4 findings, including a decomposition-counter gap that made a rate limit a silent no-op for `profile:read:any`), Ingrid Solano reviewed `connector-security.md` (2 findings — no auth requirement on inbound calls to the connector; no stated assumption about what a vendor token authorizes). All ten findings accepted, zero declined. Full record: `decisions/second-review-security-docs.md`.\n\n**Acceptance criteria:**\n- [x] Every reviewer is verified independent (did not author or blue-team the document) at the moment the review runs, not just at planning time.\n- [x] Every accepted finding is fixed in the source document, not just recorded in the decision file.\n- [x] The two findings affecting 03's implementation (decomposition-counter scope, connector inbound-auth requirement) are propagated into `handoff-03-auth.md` v2 and relayed directly to 03.\n- [x] Null results (documents/findings that didn't surface anything) are counted in the tally alongside hits, not silently omitted.\n\n**Depends on:** S3, S4\n\n**Model/effort:** sonnet, high.\n\n**Type:** Story\n\n**Labels:** `track-02`, `security-graded`\n\n---\n\n## S9 — Revise `ai-workflow-narrative.md` for the org layer\n\n**Status: done.**\n\n**Description:** Rewrote the AI-tooling narrative to cover what actually ran once hiring began: the persona/pattern-catalog layer this project built on top of Anthropic's documented orchestrator-worker pattern, honestly measured evidence from S3/S8 (including null results, not just hits), S5's ruling stated plainly with the losing position preserved, the S8 independence-reassignment lesson generalized (\"independence is checked at review time, not assigned once\"), and the real external operator agent named as deliberately out of scope and never contacted.\n\n**Acceptance criteria:**\n- [x] Distinguishes what's Anthropic-documented from what this project composed on its own (unchanged discipline from the original draft).\n- [x] States the S5 ruling including the position that lost, not just the one that won.\n- [x] Leads with the single most concrete example (Tomasz's `profile:read:any` decomposition-counter finding) rather than an abstract summary.\n- [x] Names the external operator agent and states plainly it was never contacted.\n\n**Depends on:** S3, S4, S5, S8\n\n**Model/effort:** sonnet, high.\n\n**Type:** Story\n\n**Labels:** `track-02`\n\n---\n\n## S10 — `threat-model.md` maintenance\n\n**Status: done — verified already satisfied, no edit required.**\n\n**Description:** Two required checks from the original plan: (a) repoint the stale reference to a wiped `.sql` file at the prose schema in `../05-data-ops/multi-db-strategy.md`; (b) add a trust-boundary line naming the external deployment operator as a privileged actor. Both were already present in `threat-model.md` from earlier work (verified by `grep` for any remaining `.sql` reference, and by re-reading Assumption 6) — recorded here rather than silently skipped, since an honest backlog notes verification, not just edits.\n\n**Acceptance criteria:**\n- [x] No reference to a wiped `.sql` file remains anywhere in `threat-model.md` (verified by grep).\n- [x] The operator trust boundary is named explicitly in Assumption 6, with the consequence for `handoff-04-secrets.md` stated.\n\n**Depends on:** —\n\n**Model/effort:** sonnet, high (verification only, no hire turns).\n\n**Type:** Task\n\n**Labels:** `track-02`\n\n---\n\n## S11 — Post-implementation independent review of 03's auth middleware and connector token code\n\n**Status: open — gated on Warren's implementation go-ahead.**\n\n**Description:** Once 03 implements the auth middleware (S6) and the connector's token-lifecycle code (S3), this track runs an independent code-level review of the security-graded surfaces only: token validation, the `authorize()` object-level policy hook, rate-limiting/decomposition-counter enforcement, and the connector's fetch-use-zeroize discipline. Reviewer assignment will be checked for independence at run time per the S8 lesson (whoever reviews must not have authored the code or the design doc it implements) rather than assumed from the current roster, since roles may have accumulated further authorship by then.\n\n**Acceptance criteria:**\n- [ ] Reviewer independence verified at run time, not assumed from this backlog's authorship snapshot.\n- [ ] Every enforcement site named in S3/S4/S6/S7's acceptance criteria above is checked against the actual implementation, not just the design doc.\n- [ ] Findings recorded in `decisions/second-review-implementation.md`, following the same accept/decline-with-reason discipline as S8.\n- [ ] Any Residual **H** finding (per the S1 attack-tree convention) produces a follow-up story or a stated accepted risk, not a silent gap.\n\n**Depends on:** Warren's code go-ahead; 03's implemented auth middleware and connector token-lifecycle stories.\n\n**Model/effort:** sonnet, high.\n\n**Type:** Story\n\n**Labels:** `track-02`, `security-graded`, `no-code-yet`\n\n---\n\n## Room for pass-driven stories\n\nAny story arising from the cross-track consistency pass that touches this track's surfaces (auth scheme, secrets inventory, connector security, threat model) will be added below this line with the `from-consistency-pass` label, in the same format as above, once the pass reports.\n"
}

File created successfully at: /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/backlog.md (file state is current in your context — no need to Read it back)

{
  "to": "org-planning-loginid-takehome",
  "summary": "backlog.md written — ready for transcription",
  "message": "`02-ai-security-architecture/backlog.md` is written: eleven stories in dependency order, S1-S10 marked done (shown as-run, including S8's mid-run independence reassignment and S10's \"verified already clean, no edit needed\" — not rewritten as if planned in hindsight), S11 open and gated on your code go-ahead. Every caller-visible guarantee in `handoff-03-auth.md` and `handoff-04-secrets.md` has its acceptance criteria naming a concrete enforcement site (e.g., the decomposition counter → \"a counting store... incremented per distinct record id returned\"; the never-log list → \"a log-formatting/redaction layer that structurally cannot emit these fields, not a code-review convention alone\"). Left a \"Room for pass-driven stories\" section at the bottom labeled for `from-consistency-pass` additions. Ready for transcription whenever the consistency pass reports.",
  "type": "message",
  "recipient": "org-planning-loginid-takehome",
  "content": "`02-ai-security-architecture/backlog.md` is writt…"
}

{"success":true,"message":"“backlog.md written — ready for transcription” → org-planning-loginid-takehome (another Claude session on this machine)","msg_id":"c06ff2a4-4925-4cdd-b311-32c3070e93b3"}

{
  "file_path": "/Users/warrenthompson/Source/LoginID/decisions/cross-track-consistency.md"
}

1	# Cross-track consistency pass — Phase 3 close
2	
3	Run 2026-09-12 as a fresh Fable session with no accumulated context, against the 12-seam checklist in `PLAN.md` ("Consistency-pass checklist") plus the four items handed over by the 05 lead. Only finished deliverables were read; no existing file was modified. Line numbers are from the files as they stood at the start of the pass (the working tree changed underneath the pass — see Mechanical checks). Owning leads: 01 Naomi Voss, 02 Marcus Ilori, 03 Renata Cole, 04 Theo Bergman, 05 Priya Nandakumar; root files Dana Whitfield.
4	
5	## Executive summary
6	
7	Fourteen sections were checked (twelve seams, the vocabulary sweep, the deletion gap). Classified by the most severe finding in each: **9 CONTRADICTION** (seams 1, 2, 3, 4, 5, 7, 8, 10, 11), **5 GAP** (seams 6, 9, 12, vocabulary sweep, deletion gap), **0 clean AGREE** — though the core test in eight seams passes (endpoint shapes, scope vocabulary, sentinel set, DB_DSN_FILE precedence, issuer/audience literals, R1–R5, retention numbers, §6 enforcement sites), and most contradictions are one-sentence stale references left behind by a later ruling. Fifty individual findings are numbered F1–F50 below.
8	
9	The three most consequential: **(1) the vendor token has no consistent home** — 01's onboarding flow holds it across two screens (`ux-notes.md:27`), the assignment's `/auth` returns it to the caller, yet 02 says it is never returned to callers and lives inside one function call (`connector-security.md:19-23`); no document says what our `/auth` returns or how `/identity` obtains vendor authority (F3). **(2) The JWT signing key is mounted into every `api-service` replica** (`containerization-design.md:55,61-62`) while 02 requires it never touch `api-service` and at the same time defines the issuer as "a mode of `api-service`" (`handoff-04-secrets.md:8,17`); Secret-`get` RBAC does nothing for a mounted volume (F13). **(3) The final migration layout puts all `CREATE TABLE`s in a `shared/` series** (`migration-approach.md:24`) that the field-level schema cannot express — every table has per-engine types, collations and CHECK syntax (`multi-db-strategy.md:341-368`) — and the document still carries an "under review in story S1" item after S1 closed (F28).
10	
11	Also material: cursor-only pagination in 02's hand-off versus `Offset int` in 05's accepted contract (F-pag); partial phone match required by 01, exact-only in 05 (F9); no deletion-job or `deletion_log` method in the DAO contract, so the retention mechanism cannot be written against it (F21); the never-log list does not cover the single most likely PII-to-log path — Postgres CHECK/unique-violation `DETAIL` lines carry the failing row (F50); and 02's AI-workflow narrative miscounts its own red/blue tally against the decision record it cites (F36).
12	
13	**Verdict:** the submission is not internally consistent enough to declare planning done as it stands. It will be after bounded two-party fixes on F3, F13, F28, F-pag, F21 and F50, plus the stale-status sweep in seam 11 — none of which requires reopening a debate, and each of which names one document to change. Re-run seams 1/4, 3, 5, 7 and 9 after those land.
14	
15	## Seam 1 — `/identity` response and `/auth` request shapes — CONTRADICTION
16	
17	**F1 (agree).** The shapes are identical everywhere they appear: root `CLAUDE.md` assignment text; `01/api-connector-design-rationale.md:71` ("Endpoints, methods, and JSON bodies for `/auth` and `/identity` are fixed by the assignment") and `:73` (the seven PII fields "match the assignment exactly"); `02/connector-security.md:7-8`; `03/PLAN.md:23` ("per the assignment's fixed JSON contracts"); `05/pii-governance.md:7` lists the same five address subfields; `05/multi-db-strategy.md:115-122` carries them as columns. Nobody drifted on the fixed contract.
18	
19	**F2 (contradiction — 01 vs 02).** 01's contract summary tells 03 to build `Authenticate(username, password) → token` and `FetchIdentity(token, phone, name) → PII` with "the calling code (onboarding flow)" using both (`api-connector-design-rationale.md:40,72`) — the token is returned from one method to the caller and passed into the next. 02 requires the opposite: the token "is not passed up the call stack beyond the vendor-call function" and its scope "runs from the `/auth` response to the immediately following `/identity` call and no further" (`connector-security.md:20`). 03 receives both as "build against this". Owner: Naomi. Smallest fix, one document (`api-connector-design-rationale.md` contract summary): state that the two-method shape is the vendor adapter's internal interface and the exported operation is a single identity lookup that performs the auth-then-fetch inside the adapter, so the token never crosses the adapter boundary.
20	
21	**F3 (contradiction — 01, 02, assignment).** The documents cannot all be true about who holds the vendor token between our `/auth` and our `/identity`. The assignment says `/auth` "retrieves an `access_token`" for its caller. 01 builds on that: "a short-lived token stands in for the password everywhere past the first screen" (`ux-notes.md:27`), i.e., held across two user-facing requests; `personas-use-cases.md:33` says the same. 02 says the token is "fetched fresh from `/auth` for each `/identity` call, held only inside that single request's execution scope" (`connector-security.md:19`), is "Not returned to our own API callers" (`:23`), and the end-user's vendor password is "Never persisted, never cached, held only for the vendor call" (`handoff-04-secrets.md:25`). Our `/identity` body is fixed as `{"phone","name"}` with no credential field. So on a `/identity` call the connector has neither a cached token, nor the user's password, nor a token from the caller — unless the caller presents one, which `:23` forbids. `connector-security.md` §6 (`:58-60`) discusses "a vendor `access_token` obtained from one person's `/auth` call" being used at `/identity`, which presumes exactly the caller-presented flow `:23` rules out. This is the ambiguity Ingrid's S8 finding 2 (`decisions/second-review-security-docs.md:33`) brushed against without resolving. Owner: Marcus (01's UX follows the assignment; 02's restriction is the added constraint). Smallest fix, one document (`connector-security.md` §1): one paragraph stating what our `/auth` returns to its authenticated internal caller (the vendor token pass-through, or an opaque handle) and that our `/identity` accepts it as the vendor credential for that call; rewrite `:23` from "not returned to our own API callers" to "returned only to the authenticated `connector:identity-lookup` caller, never to end users, never persisted server-side". If 02 instead keeps `:23`, then the assignment's `/auth` has no purpose in this design and 01's two-screen flow must be withdrawn — which is why the fix belongs in 02.
22	
23	## Seam 2 — Authorization scopes and their semantics — CONTRADICTION
24	
25	**F4 (agree).** The scope vocabulary is identical in `02/api-auth-design.md:38-40`, `02/handoff-03-auth.md:25-31`, and `02/decisions/search-authz-scoping.md:14`; the closed `reason_code` enum matches (`api-auth-design.md:54` ↔ `handoff-03-auth.md:31`); the `profile:read:any` decomposition-counter fix is present in both `api-auth-design.md:62` and `handoff-03-auth.md:39` with the same wording and the same S8 attribution. 01's product requirements (`personas-use-cases.md:39-54`) are honoured on attribution, pagination, no-bulk-export and volume limiting.
26	
27	**F5 (contradiction — internal to `handoff-03-auth.md`).** Line 10: "If `cmd/idp-connector` ever needs its own audience value (it doesn't consume this token scheme today …) … not needed for this submission." Line 19: "`idp-connector`'s own `/auth` and `/identity` handlers need the same JWT middleware pattern, with a **distinct audience** (`aud: idp-connector-service` …) … Two audiences, one mechanism." The v2 update added line 19 without removing line 10. Owner: Marcus. Fix: delete the parenthetical sentence at line 10.
28	
29	**F6 (gap — 01 requirement with no 02 mechanism).** 01 requires "Masked/partial PII by default on every search result, with full-field detail requiring a distinct, more tightly scoped call" (`personas-use-cases.md:42`), a deliberate expand "with its own audit-log entry distinct from the search's own entry" (`:43`), masking independent of query specificity (`:47`), and `expand: true` that "should require a more tightly-scoped credential than the base search call" (`api-connector-design-rationale.md:63`). Neither `api-auth-design.md` nor `handoff-03-auth.md` contains the words "mask" or "expand" (grep: zero hits in both), and the hand-off says `profile:search` "is the broadest scope; there is no broader one" (`handoff-03-auth.md:29`) — so "tighter than search" has nowhere to bind. 03 has no rule on response field shape. Owner: Marcus. Smallest fix, one document (`handoff-03-auth.md`): add a response-shape bullet — `profile:search` responses carry masked fields; unmasked detail is obtained only by a follow-up `GET /profiles/{id}` under `profile:read:own`/`read:any`, which is its own audited call. That gives 01's requirement a mechanism using scopes that already exist and turns 01's `expand: bool` into a client-side navigation rather than a server flag; 01 then drops the "tighter credential" clause at `:63`.
30	
31	**F7 (gap — 03).** `handoff-03-auth.md:27,50` requires that a scope failure and an `authorize()` policy denial be "distinct signals for detection". `03/decisions/error-semantics.md` maps DAO sentinels and context errors to HTTP (`:21-23`) but says nothing about what an authn or authz failure returns — the checklist's explicit question for this seam. Owner: Renata. Fix: one line in `error-semantics.md`: missing/invalid token → 401; scope failure and policy denial → 403 with an identical client body, distinguished only in the audit log.
32	
33	**F8 (gap — data with no home).** `handoff-03-auth.md:27` says the `caller_referral` mapping is "data owned by `../05-data-ops/`", and `api-auth-design.md:53` says "`caller_referral` entries are data owned by `../05-data-ops/CLAUDE.md`". No 05 document mentions `caller_referral`, a caller-role table, or a `reason_code` store (grep across `05-data-ops/`: zero hits); 05's field-level schema has three tables plus `deletion_log`. The same applies to the "explicit caller-role table" (`api-auth-design.md:39`). This is an ownership assertion the asserted owner never received. Owner: Marcus (to route as a two-party item with Priya). Smallest fix, one document (`handoff-03-auth.md`): place `caller_referral` and the caller-role table in the authorization server's own datastore — which row 4 of `handoff-04-secrets.md:19` already says holds the hashed `client_secret`s — rather than in 05's schema, and say so.
34	
35	**F9 (contradiction — 01 vs 05).** 01: "Search on `name` and `phone`, with partial-match support — a support analyst rarely has a clean, exact value for either" (`personas-use-cases.md:41`); the UX search screen has a "partial-match toggle" (`ux-notes.md:11`). 05: `Phone *string // EXACT match on the E.164-normalized value (not prefix)` (`multi-db-strategy.md:187`) and "**Exact match only** — … the contract does not offer it" (`:413`), a deliberate S2/S6 ruling. Owner: Naomi — 05's position is debated, enforced by the index definition, and accepted by 03. Fix: `personas-use-cases.md:41` → name partial, phone exact after E.164 normalization, recorded as an accepted product limitation (an analyst reading a full number aloud is the exact-match case).
36	
37	**F10 (minor gap — empty query, page size).** 01 requires rejecting a query with no search field (`personas-use-cases.md:52`); 05 says an all-nil query "is legal and returns every profile" and defers the policy to 02 (`multi-db-strategy.md:200`); 02 rejects only a query "that would exceed [the result cap] unconstrained" (`handoff-03-auth.md:29`), a count-based rule, not a shape-based one. Compatible only if 03's handler rejects an empty search body, which no document says. Separately, the API default/ceiling is 20/50 (`handoff-03-auth.md:37`) and the DAO's is 50/100 (`multi-db-strategy.md:190`); no document names the clamp. Owner: Marcus for the first (one bullet in `handoff-03-auth.md`: "a search body with no filter is rejected before the DAO"), Renata for the second (name the clamp in the S3 middleware spec).
38	
39	## Seam 3 — Config surface and secrets — CONTRADICTION
40	
41	**F11 (agree).** `DB_DSN_FILE` precedence over `DB_DSN` matches in `PLANNING.md:46`, `handoff-04-secrets.md:16`, `04/secrets-delivery.md:11`, `04/containerization-design.md:52`, and the go-layout diagram (`03/decisions/go-layout-debate.md:64`). The literal issuer `https://auth.loginid-takehome.internal` and audience `loginid-api-service` match in `PLANNING.md:46`, `handoff-03-auth.md:10`, and `go-layout-debate.md:32-33`; 04 correctly treats them as ConfigMap values, not secrets (`containerization-design.md:50`).
42	
43	**F12 (contradiction — version label).** `handoff-04-secrets.md:3` reads "Status: **v1** … Awaiting 04's Newcomer (`wesley-okonkwo`) cold read." The cold read happened and its fixes are in the file (`04/decisions/newcomer-coldread-boundaries-secrets.md:36-39`); 04 cites "v2" in `secrets-delivery.md:3,37`, `observability.md:44`, `containerization-design.md:5`, and `newcomer-coldread-boundaries-secrets.md:43`; `PLAN.md:134` and `02/CLAUDE.md:51` say v1. One document, three labels. Owner: Marcus. Fix: update the Status line to v2 and remove "Awaiting".
44	
45	**F13 (contradiction — signing-key custody).** `handoff-04-secrets.md:17` row 2: "Used by: Token-issuing authorization-server component only — **not** `api-service`". Same document, Assumption 2 (`:8`): "The token-issuing authorization-server function is a mode of `api-service`, not a third binary … RBAC … restricted (via a distinct Kubernetes Role, not a separate ServiceAccount) so that only the issuing code path — not the token-verification code path in the same binary — can `get` the signing-key Secret." `handoff-03-auth.md:20` compresses the contradiction into one sentence: "The private signing key never touches `api-service`; it lives with the token-issuing function, which is a mode of `api-service`." 04 then implements the only thing the manifest can do: mounts `api-service-jwt-signing-key` at `/secrets/jwt` into the `api-service` container of a two-replica Deployment (`containerization-design.md:39,55,61-62`) — every replica, verification path included. A Role restricting `get` on a Secret has no effect on a volume mount; the file is readable by the whole process. `secrets-delivery.md:24` concedes the requirement "in practice means either a second SA for the issuer mode or a sidecar/init-container pattern", which the manifest does not do. Owner: Marcus for the requirement (the manifest follows it). Smallest fix, one document first (`handoff-04-secrets.md` Assumption 2 and row 2): the issuer runs as a separate Deployment of the same `api-service` image, selected by an environment variable 03 adds to the config surface (the surface allows no flags — `PLANNING.md:46`), with its own ServiceAccount that alone mounts the signing key; the `api-service` Deployment mounts nothing but the DSN. Then Theo removes the mount at `containerization-design.md:55,61-62` and adds the issuer Deployment.
46	
47	**F14 (contradiction — compose leaks inventory-forbidden values).** The compose sketch sets `DB_DSN: postgres://dev:«REDACTED»@postgres:5432/…` (`local-dev-loop.md:24`) and `IDP_ABC_CLIENT_ID: dev-client` / `IDP_ABC_CLIENT_SECRET: dev-secret` as literal env values (`:38-39`) in a file that would be committed. Row 5 of the inventory says these are "never in source or committed config" with "file mount preferred" (`handoff-04-secrets.md:20`) and row 1 makes `DB_DSN_FILE` "Required, not preferred" (`:16`). The disclaimer at `local-dev-loop.md:50` explains the intent but the inventory grants no development exemption. Owner: Theo. Fix, one document (`local-dev-loop.md`): use `${IDP_ABC_CLIENT_SECRET:?}`-style required variables sourced from an untracked `.env`, and `DB_DSN_FILE` pointing at a bind-mounted dev file — or ask Marcus for an explicit dev-profile exemption row.
48	
49	**F15 (gap — the connector's own audience has no config, and its caller has no credential).** `connector-security.md:52` and `handoff-03-auth.md:19` require the connector to verify JWTs with `aud: idp-connector-service` and scope `connector:identity-lookup`. The config surface has one `AUTH_JWT_AUDIENCE` in a shared `internal/config` (`PLANNING.md:46`; `go-layout-debate.md:65`); nothing says the connector reads it with a different value or has its own variable. And `api-service` must obtain a `connector:identity-lookup` token to call the connector, which means `api-service` holds a client credential toward the issuer — a secret that is in none of rows 1–9 of the inventory. Owners: Marcus (inventory row) and Renata (config variable). Fix: add row 10 to `handoff-04-secrets.md` (api-service's client id/secret for the connector audience, file-mounted, `api-service` SA) and one variable to `PLANNING.md` Service boundaries.
50	
51	## Seam 4 — Connector token lifecycle — CONTRADICTION
52	
53	**F16 (agree).** No-cache-by-default is stated identically in `connector-security.md:19` and `decisions/connector-token-lifecycle-redblue.md:27,34,55`; the attack-tree table (`connector-security.md:79-83`) matches the record; 03's outbound `context.WithTimeout` and bounded backoff (`go-layout-debate.md:19`; `PLANNING.md:49`) are compatible with 02's "a retried `/identity` call re-fetches via `/auth`" (`connector-security.md:20`) — backoff governs the spacing, re-fetch governs the token. 05 governs cached `/identity` results as `idp_cache` rows on a 30-day clock (`pii-governance.md:33`), and 02 defers exactly that to 05 (`connector-security.md:39,64`).
54	
55	**F17 (contradiction — stale references to a cache that no longer exists).** After the S3 ruling, these still describe a cached token: «REDACTED» row 7 says the red/blue is "(in progress)" and caching is the "current direction"; `:52` says the connector "may [cache], under the conditions in #6"; `secrets-delivery.md:16` "If cached, encrypted with #7's KEK"; `03/PLAN.md:23` consumes "token lifecycle: TTL, storage, refresh, never-persist-in-plaintext"; `03/decisions/context-propagation.md:23` names "any token-persistence write" as a detach point; the go-layout diagram lists "token lifecycle (TTL/refresh/no-plaintext-persist)" (`go-layout-debate.md:45-49`); and `04/observability.md:37` invents a retention class `vendor_token_cache`. None is load-bearing, but each tells a reader the opposite of the ruling. Owners: Marcus (`handoff-04-secrets.md:22,52`), Renata (`03/PLAN.md:23`, `context-propagation.md:23`), Theo (`observability.md:37`, `secrets-delivery.md:16`). Fix: one-line edits; the primary is `handoff-04-secrets.md` row 7 and "What 04 does not decide", which is the hand-off 04 built from. F3 (seam 1) is the substantive lifecycle contradiction and is not repeated here.
56	
57	## Seam 5 — DAO contract — CONTRADICTION
58	
59	**F18 (agree — the seam's explicit test passes).** The sentinel set is byte-identical: `03/decisions/error-semantics.md:33` lists `ErrNotFound`, `ErrAlreadyExists`, `ErrDuplicateUsername`, `ErrInvalidMethod`, `ErrInvalidQuery`, `ErrInvalidArgument`, `ErrInvalidCredential`, matching `05/multi-db-strategy.md:282-288` exactly, seven for seven. The translation rule matches (`error-semantics.md:34` ↔ `multi-db-strategy.md:298`). `PLANNING.md:47`'s composite (`Profiles()/Credentials()/Methods()`) matches `multi-db-strategy.md:94-97`. `context-propagation.md` item 1 (multi-table writes in one `Tx`) is satisfied by `CreateProfileWithCredential` (`context-propagation.md:31` ↔ `multi-db-strategy.md:99-101,232-244`).
60	
61	**F-pag (
… truncated (20 KB cap)

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

1	# IDP Connector Security Design — Question 3
2	
3	Owner: Marcus Ilori (`02-ai-security-architecture`). Covers the third-party identity-provider connector (generic vendors "ABC"/"XYZ") exposing `/auth` and `/identity`, per the assignment. Implementation target: `../03-engineering-delivery/CLAUDE.md`.
4	
5	## Contract recap (from the assignment, verbatim in `../CLAUDE.md`)
6	
7	- `POST /auth` — body `{"username": "<string>", "password": "<string>"}` → returns an `access_token`.
8	- `POST /identity` — body `{"phone": "<string>", "name": "<string>"}` → returns PII (name, phone, address fields).
9	
10	Read literally, this connector is a thin proxy in front of ABC/XYZ: it takes vendor credentials, gets a vendor token, and uses that token to pull PII from the vendor. Every security question here is "what does this service do with a vendor secret and vendor PII while it's in our custody," since we don't control the vendor's own security posture.
11	
12	## Threat surface specific to this connector
13	
14	This extends the third-party-token row in `threat-model.md`; this document is the concrete design against those threats.
15	
16	### 1. What happens to the vendor `access_token` once retrieved
17	
18	- **Never logged.** The `/auth` request body contains a vendor password; the response contains a bearer token. A naive "log the request and response for debugging" habit puts both in the same log line — this is called out explicitly because it's the single most common way a connector like this leaks a credential in practice, not a hypothetical.
19	- **No persistent or cached token, by default.** Revised by the S3 red/blue run (`decisions/connector-token-lifecycle-redblue.md`): the token is fetched fresh from `/auth` for each `/identity` call, held only inside that single request's execution scope, and discarded when the call returns — not written to any cache or datastore as a matter of course. Caching is an explicitly-justified exception requiring its own threat re-review if latency or vendor rate limits ever force the question; if that exception is ever opened, it must satisfy: (a) cache key derived from an immutable, vendor-issued identifier (our tenant id + vendor id + the vendor's own opaque subject id) — never from request-supplied `name`/`phone`, which are attacker-influenced; (b) TTL no longer than the vendor's own token expiry, encrypted at rest (envelope encryption via KMS, mechanics owned by `../04-infra-devops/CLAUDE.md`); (c) if the KMS/envelope key is unreachable at write or read time, fail closed to "no cache, fetch live" for that call — never to an unencrypted write and never to a hard connector failure.
20	- **Fetch-use-zeroize boundary, stated explicitly so it survives implementation:** the token variable's scope runs from the `/auth` response to the immediately following `/identity` call and no further; it is not passed up the call stack beyond the vendor-call function, and it is not reused across a retry. **A retried `/identity` call re-fetches via `/auth`; it never reuses a token held from a prior attempt** — otherwise the "one request" exposure window `§4`'s retry/backoff allowance quietly becomes "however long the retry policy runs." Go gives no guaranteed memory zeroing without unsafe/cgo, so a crash dump taken mid-call could still capture the token in the vendor-call function's stack; that residual is accepted given the window is now one function call, not a cache TTL (core-dump suppression at the runtime level is a `../04-infra-devops/CLAUDE.md` mechanism, requirement recorded here, not owned here). The token field is excluded from any generic request/response dump used in error handling — the same log-hygiene discipline below applies to panic traces and debug dumps, not just application logs.
21	- **The outbound HTTP client to the vendor must construct a fresh, isolated `Authorization` header per request, never inherited from connection reuse.** Connection pooling/keep-alive is the normal default in any HTTP client library; a pooled client that reuses a request-context object or fails to reset the auth header per call can attach request A's vendor token to request B's outbound call — the same cross-tenant leak as a cache-key collision, with no cache required. This is a required implementation discipline, not an assumption left implicit.
22	- **Scoped narrowly if the vendor supports it** — request only the scope needed for `/identity`, not a broad token, so a leaked token's blast radius is bounded by the vendor's own authorization model as well as ours.
23	- **Not returned to our own API callers.** The vendor `access_token` is an internal implementation detail of this connector; question 2's API callers never see it. If a caller needs to know "identity lookup succeeded," return our own success/failure signal, not the vendor's token or vendor's raw response.
24	
25	### 2. How `/identity` calls are authenticated to the vendor
26	
27	- Standard bearer-token usage: the vendor `access_token` from `/auth` presented as an `Authorization: Bearer` header to the vendor's identity endpoint (or whatever the vendor's own contract specifies — this connector adapts to the vendor, not the reverse).
28	- **Token refresh/re-auth on expiry** handled by the connector transparently — a caller of our `/identity` endpoint should not need to know or manage vendor token lifecycle.
29	- **Vendor calls over TLS only**, certificate validation never disabled, including in local/dev environments (repeating the threat model's point because it's the most common place a "temporary" dev bypass ships to production unnoticed).
30	- **Our own credentials to call the vendor's `/auth`** (this connector's client id/secret with ABC/XYZ, if the vendor requires connector-level registration in addition to the end-user's own username/password) are runtime-injected secrets, never in source or config committed to the repo — requirement set here, mechanism owned by `../04-infra-devops/CLAUDE.md`.
31	
32	### 3. What this service should and shouldn't log or persist
33	
34	| Data | Log it? | Persist it? |
35	|---|---|---|
36	| End-user's vendor username | No (identifier, but low sensitivity relative to password — still avoid in plaintext logs; use it only for correlation via a hash if audit trails need it) | Only if a legitimate business reason exists; not by default |
37	| End-user's vendor password (`/auth` request body) | **Never, under any circumstance, including error paths and stack traces** | **Never** |
38	| Vendor `access_token` | **Never** | Only as short-TTL encrypted cache per above; never in plaintext, never in application logs |
39	| PII returned by `/identity` (name, phone, address fields) | Never the field values; log only the *fact* of a lookup (caller identity, timestamp, success/failure, which record was resolved by opaque id) | Retention/caching policy for this PII is `../05-data-ops/CLAUDE.md`'s call — this track's requirement is that whatever is persisted follows the same encryption-at-rest and access-control bar as `user_profile` data, no weaker because it arrived via a connector rather than direct input |
40	| Vendor error responses | Log status/error-code only; do not log raw vendor response bodies by default, since a vendor error payload can itself echo back submitted PII or partial credentials | N/A |
41	
42	### 4. Failure handling as a security control, not just reliability
43	
44	- **Vendor auth failures must not leak which part of the credential was wrong** (username vs. password) in whatever this connector surfaces upward — same user-enumeration concern as the threat model's credential-stuffing row, now facing outward at whoever calls our `/auth` passthrough.
45	- **Retry/backoff on vendor calls** should be rate-limited on our side independent of the vendor's own limits, so a compromised or careless caller can't use our connector to hammer the vendor (which is both an availability risk to us and a way to get our connector's vendor credentials rate-limited or banned).
46	- **Circuit-breaking**: if the vendor is failing or behaving anomalously (e.g., returning tokens for identities that don't match the request), fail closed — do not fall back to a cached or stale identity result silently, since that risks serving stale PII as if freshly verified.
47	
48	### 5. Authentication and authorization of calls *into* this connector
49	
50	Found by Ingrid Solano's S8 independent review — §1–§4 above are entirely about protecting the *vendor* token and the *vendor* call; none of them state who is allowed to call *our* `/auth` and `/identity` in the first place. Fixed here rather than left as a silent assumption:
51	
52	- **Callers of `cmd/idp-connector`'s own `/auth` and `/identity` must be authenticated**, using the same OAuth2 client-credentials → JWT bearer mechanism as `api-auth-design.md`, but with a **distinct audience** (`aud: idp-connector-service`, separate from `loginid-api-service`) and its own scope (`connector:identity-lookup`) — this is a different threat model and a different, smaller caller set (internal services, not question 2's broader API clientele), so it gets its own audience rather than reusing the search API's. Only a service that legitimately mediates an end-user or business flow needing vendor identity data (in this project's shape, `cmd/api-service` acting on a caller's behalf) should hold this credential — it is not exposed to arbitrary external callers.
53	- **Why this matters concretely:** without it, an unauthenticated caller could hit our `/auth` passthrough with arbitrary vendor credentials all day and use this connector as exactly the credential-testing oracle §4's rate-limit control is meant to prevent — but "rate-limited per calling-API-client" has nothing to bind "per calling-API-client" to if no caller identity is required to reach the endpoint at all.
54	- **Audit logging** for calls into this connector follows the same discipline as §3's table: caller `sub`, scope, timestamp, outcome — never the vendor credentials or PII in the request/response bodies.
55	
56	### 6. What a vendor token authorizes at `/identity` — an assumption, stated explicitly
57	
58	Also found by S8 review. This design's token-handling discipline (§1) is entirely about *custody* of the vendor token — encryption, memory scope, never-log. It says nothing about what the token is allowed to *do*: specifically, whether a vendor `access_token` obtained from one person's `/auth` call authorizes an `/identity` query for a *different* person's `name`/`phone`, or only for the token-holder's own identity.
59	
60	This connector cannot enforce that boundary itself — the assignment's generic `/identity` contract (`{"phone": "...", "name": "..."}`, no scoping field) puts that decision entirely on the vendor's own API. **Stated assumption, not a resolved control:** this design assumes a real ABC/XYZ-shaped vendor binds `/identity` queries to the authenticated principal at the vendor side (i.e., the vendor's own API rejects a query for an identity other than the token-holder's). If that assumption doesn't hold for a given real vendor, this connector becomes a lookup oracle for anyone who can obtain one valid vendor token, and no control in §1–§5 touches that risk, because none of them govern token *authority* rather than token *custody*. This is the same class of question as the search API's object-level authorization (`api-auth-design.md`, S4) and belongs on `../01-product-industry-research-design/CLAUDE.md`'s list when evaluating which real vendor ABC/XYZ represents — this track cannot resolve it without knowing a concrete vendor's actual token semantics.
61	
62	## What this design does not resolve
63	
64	- Data retention duration for cached `/identity` results — `../05-data-ops/CLAUDE.md`.
65	- Which secrets manager holds this connector's own vendor credentials — `../04-infra-devops/CLAUDE.md`.
66	- Vendor selection/evaluation (which real-world providers "ABC"/"XYZ" might represent) — that's product framing in `../01-product-industry-research-design/CLAUDE.md`, not a security question.
67	
68	## Sources
69	
70	- OWASP API Security Top 10 2023, API7 (Server Side Request Forgery) and API8 (Security Misconfiguration) — both relevant to a service that makes outbound calls to a third party on a user's behalf: https://owasp.org/API-Security/editions/2023/en/0x11-t10/
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	
77	| # | Leaf (attack path) | Precondition | Likelihood | Impact | Blue response: Control *or* Accepted risk | Owner | Residual | Source |
78	|---|---|---|---|---|---|---|---|---|
79	| 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) |
80	| 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 |
81	| 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 fetch-per-call bounds the exposure window to one request's execution scope — no standing cached credential to steal. **Tightened per Tomasz's rebuttal:** the boundary is stated explicitly — fetch → use in the immediately following `/identity` call → zeroize; a retried `/identity` call re-fetches via `/auth` and never reuses a token from a prior attempt, so the accepted window cannot silently stretch to the length of the retry/backoff policy. | — (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 fetch's lifetime | RFC 6750 §5; RFC 9700 §2.5 |
82	| 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 |
83	| 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 |
84	
85	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.
86	
87	---
88	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.
89	

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md",
  "old_string": "- **Not returned to our own API callers.** The vendor `access_token` is an internal implementation detail of this connector; question 2's API callers never see it. If a caller needs to know \"identity lookup succeeded,\" return our own success/failure signal, not the vendor's token or vendor's raw response.",
  "new_string": "- **Returned once, to the authenticated internal caller only — never to end users, never persisted server-side (resolved by the cross-track consistency pass, F3).** Our own `/auth` returns the vendor `access_token` to whichever authenticated `connector:identity-lookup`-scoped caller invoked it (in this project's shape, `cmd/api-service` acting on an onboarding flow's behalf) — this is what the assignment's `/auth` contract actually requires (\"retrieves an `access_token`\"), and it is what `../01-product-industry-research-design/ux-notes.md`'s onboarding flow depends on to bridge its two user-facing steps. Because our own `/identity` request body is fixed by the assignment to `{\"phone\", \"name\"}` with no credential field, the vendor token travels as a request header on the subsequent `/identity` call (e.g. `X-Vendor-Access-Token`) — this doesn't violate the fixed JSON contract, which governs the body only, not headers. The connector itself still never caches or persists the token (S3's no-cache ruling stands unchanged): each `/identity` call's presented token is used once and discarded, exactly as if it had been freshly fetched, and it is the caller's responsibility — not the connector's — to hold the token for the short span between the two calls. If a caller presents no token, or an expired one, `/identity` fails closed with a generic error that does not distinguish \"no token\" from \"bad token\" from \"vendor rejected it\" (same user-enumeration discipline as §4's other failure-handling rules)."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/connector-security.md has been updated successfully. (file state is current in your context — no need to Read it back)

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

1	# Hand-off 02 → 03: Auth scheme, validation point, and authorization requirements
2	
3	Status: **v2** — updated after S8's independent review of `api-auth-design.md` and `connector-security.md` surfaced fixes that affect this hand-off; both already relayed to you by chat, folded into the durable file here per this project's hand-off standard. 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`.
4	
5	## Token scheme
6	
7	- **Grant type:** OAuth2 client-credentials. Machine-to-machine only; no end-user login flow for question 2's API.
8	- **Token format:** JWT, signed, asymmetric (RS256 or ES256 — pick one and use it consistently; RS256 is the safer default if your Go JWT library's ES256 support is less mature).
9	- **Claim set (minimum):** `sub` (calling client identity), `scope` (space-delimited, values below), `exp`, `iat`, `aud` (this API, specifically — reject tokens minted for another audience).
10	- **Literal values, filling the "pending 02's final scheme" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = "https://auth.loginid-takehome.internal"`, `AUTH_JWT_AUDIENCE = "loginid-api-service"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3. If `cmd/idp-connector` ever needs its own audience value (it doesn't consume this token scheme today — see "Where it's validated" below), that would be a second, distinct `aud`, not a shared one; not needed for this submission.
11	- **TTL:** 5–15 minutes. No refresh tokens — the client re-authenticates with its own client secret on expiry.
12	- **No denylist.** Revocation is handled by TTL shortness, not a stateful lookup. Don't build one; it's not missing, it's a deliberate trade-off already reasoned through in `api-auth-design.md`.
13	- **Verifier must pin the expected algorithm** (whichever of RS256/ES256 you choose) and reject a token whose header claims any other algorithm, including `alg: none` and a downgrade to a symmetric algorithm using the public key as an HMAC secret (RFC 8725 §3.1). Check your JWT library's default behavior — several popular libraries have shipped this vulnerability by not doing this by default.
14	- **Token-endpoint brute-force protection**, separate from the resource-API rate limits below: failed-grant rate limiting and progressive backoff per `client_id` and per source IP on the token-issuing endpoint itself, plus alerting on a sustained run of failed grants against one `client_id`. This protects the endpoint where a caller presents `client_id`/`client_secret`, which none of the resource-API limits below cover.
15	- **Bearer-token replay is an accepted risk, not a gap to close in implementation.** This token has the same possession-equals-authority property as the connector's vendor token (`connector-security.md`); no PoP/binding is expected or required here. Noted so it isn't mistaken for something to "fix" during implementation.
16	
17	## Where it's validated
18	
19	- **Middleware at the API edge**, in `internal/api/` per your published service boundary — every request to `cmd/api-service` passes through token validation before reaching a handler. `cmd/idp-connector` does not validate *this* token — but per `connector-security.md` §5 (added by S8 review), `idp-connector`'s own `/auth` and `/identity` handlers need the same JWT middleware pattern, with a **distinct audience** (`aud: idp-connector-service`, not `loginid-api-service`) and its own scope (`connector:identity-lookup`), restricted to internal callers (in this project's shape, `api-service` acting on a caller's behalf) — not the same token, not exposed to arbitrary external callers. Two audiences, one mechanism.
20	- **Key retrieval:** middleware verifies with the **public** key only (JWKS or a fetched public key — see `handoff-04-secrets.md` row #3). The private signing key never touches `api-service`; it lives with the token-issuing function, which is a mode of `api-service` (not a separate binary — see `handoff-04-secrets.md` Assumption 2), scoped by RBAC so the verification code path and the issuing code path don't share Secret access even though they're the same binary.
21	- **Key rotation:** expect a `kid` claim; publish old and new public keys together during rotation overlap. Token TTL (5–15 min) bounds how long that overlap needs to last.
22	
23	## Scope vocabulary (final, from S4 — `decisions/search-authz-scoping.md`)
24	
25	| Scope | Authorizes | Does not authorize | Object-level check |
26	|---|---|---|---|
27	| `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 `caller_referral` mapping (data owned by `../05-data-ops/`); out-of-set → reject, logged as a policy denial, distinct from an auth failure |
28	| `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 |
29	| `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 |
30	
31	`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`.
32	
33	**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.
34	
35	## Pagination, rate limits, decomposition resistance (requirements — numbers are fixed, mechanism is yours)
36	
37	- **Cursor-based pagination only** — no offset-based paging. Default page size 20, hard ceiling 50.
38	- **Per-client-credential rate limits:** 60 req/min for `read:own`/`read:any`; 10 req/min for `profile:search`.
39	- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that catches slow, under-the-cap enumeration (decomposition) that per-request and per-minute limits alone miss. **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). The counting-store mechanism (Redis, in-process with periodic flush, whatever fits your stack) is your call; the requirement is that it exists, applies to both scopes, and alerts on threshold, not just hard-blocks.
40	- Sustained near-limit usage on any of the above should alert, not just silently throttle.
41	
42	## Audit-log field list (every search/retrieve call)
43	
44	Log these fields, and only these — see `handoff-04-secrets.md`'s never-log list for what must never appear here:
45	
46	- `sub` (caller identity)
47	- `scope` used
48	- record id(s) touched (opaque ids, not the PII values)
49	- `reason_code`, when the scope is `profile:read:any`
50	- policy decision (`allow` / `deny`, and if `deny`, whether it was a scope failure or an `authorize()` policy denial — these are distinct signals for detection)
51	- timestamp
52	- request outcome (success/failure/rate-limited)
53	
54	Never in this log: PII field values, full JWTs, full request/response bodies. Per `handoff-04-secrets.md`'s new requirement, this log stream itself needs read access distinct from and narrower than whatever can read Secrets — that's 04's mechanism, but don't let the log ship without asking whether that separation exists.
55	
56	## What's not yours to decide (already decided upstream, don't re-derive)
57	
58	- **Grant type, token format, and claim set** — decided in `api-auth-design.md`; not open for re-litigation during implementation.
59	- **Scope vocabulary and provisioning bars** — decided in S4 (`decisions/search-authz-scoping.md`); if a real implementation constraint makes one of these unworkable, flag it back to me rather than adjusting it unilaterally.
60	- **The `DB_DSN_FILE` convention** — per `handoff-04-secrets.md`'s S7 revision, this track is asking you to add a file-based alternative to `DB_DSN` (env var becomes a transitional fallback, not a permanent equal option), because a DSN's embedded password is exposed by `kubectl describe`/crash dumps/child-process environment the same as any other secret in that inventory. This is a request into your config surface, not a unilateral change on my part — you decide the exact mechanism (a `_FILE` suffix convention or otherwise), I'm asserting the requirement.
61	- **Password/client-secret hashing** — Argon2id, decided in `threat-model.md` Asset 1; not this hand-off's concern beyond noting it exists.
62	- **PII retention/caching duration for anything the API returns** — `../05-data-ops/CLAUDE.md`'s call, not this track's or yours.
63	- **Whether `read:any` ever gets issued to a real caller** — per S4, the scope stays defined but unissued unless a caller clears the provisioning bar (caller-role table entry, named approver). Don't wire a default grant "just in case."
64	
65	## Open question back to you
66	
67	Nothing blocking. One thing worth a quick confirm when convenient: does your `internal/api/` middleware layer have a natural place to run the object-level `authorize()` check as a distinct step from scope validation (e.g., a second middleware or an explicit call inside each handler before the DAO call), or would you rather this track propose a specific Go interface shape for it? Either is fine — say which you'd find more useful and I'll adjust.
68	
69	---
70	Model: sonnet (Marcus Ilori, lead — compiled directly from S4's ruling, no new debate). Turns consumed: 0 hire turns (synthesis of already-ruled decisions per `PLAN.md` S6).
71	

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "Status: **v2** — updated after S8's independent review of `api-auth-design.md` and `connector-security.md` surfaced fixes that affect this hand-off; both already relayed to you by chat, folded into the durable file here per this project's hand-off standard. 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`.",
  "new_string": "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`."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "- **Literal values, filling the \"pending 02's final scheme\" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = \"https://auth.loginid-takehome.internal\"`, `AUTH_JWT_AUDIENCE = \"loginid-api-service\"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3. If `cmd/idp-connector` ever needs its own audience value (it doesn't consume this token scheme today — see \"Where it's validated\" below), that would be a second, distinct `aud`, not a shared one; not needed for this submission.",
  "new_string": "- **Literal values, filling the \"pending 02's final scheme\" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = \"https://auth.loginid-takehome.internal\"`, `AUTH_JWT_AUDIENCE = \"loginid-api-service\"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3. (F5 fix: the sentence previously here said `idp-connector` \"doesn't consume this token scheme today\" and a second audience was \"not needed for this submission\" — that's now wrong and removed; see \"Where it's validated\" below, which requires exactly that second audience.)"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "- **Literal values, filling the \"pending 02's final scheme\" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = \"https://auth.loginid-takehome.internal\"`, `AUTH_JWT_AUDIENCE = \"loginid-api-service\"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3. (F5 fix: the sentence previously here said `idp-connector` \"doesn't consume this token scheme today\" and a second audience was \"not needed for this submission\" — that's now wrong and removed; see \"Where it's validated\" below, which requires exactly that second audience.)",
  "new_string": "- **Literal values, filling the \"pending 02's final scheme\" placeholder in your Service boundaries config surface:** `AUTH_JWT_ISSUER = \"https://auth.loginid-takehome.internal\"`, `AUTH_JWT_AUDIENCE = \"loginid-api-service\"`. Both are configuration, not secrets — safe in a `ConfigMap` or committed default, per `handoff-04-secrets.md` row #3."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "| `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 `caller_referral` mapping (data owned by `../05-data-ops/`); out-of-set → reject, logged as a policy denial, distinct from an auth failure |\n| `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 |\n| `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 |\n\n`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`.\n\n**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.",
  "new_string": "| `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 |\n| `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 |\n| `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 |\n\n`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`.\n\n**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.\n\n**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.\n\n**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`.\n\n**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."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "## Pagination, rate limits, decomposition resistance (requirements — numbers are fixed, mechanism is yours)\n\n- **Cursor-based pagination only** — no offset-based paging. Default page size 20, hard ceiling 50.\n- **Per-client-credential rate limits:** 60 req/min for `read:own`/`read:any`; 10 req/min for `profile:search`.\n- **Cumulative distinct-record-touch counter per caller per rolling 24h window**, tracked independently of per-minute rate — this is the control that catches slow, under-the-cap enumeration (decomposition) that per-request and per-minute limits alone miss. **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). The counting-store mechanism (Redis, in-process with periodic flush, whatever fits your stack) is your call; the requirement is that it exists, applies to both scopes, and alerts on threshold, not just hard-blocks.\n- Sustained near-limit usage on any of the above should alert, not just silently throttle.",
  "new_string": "## Pagination, rate limits, decomposition resistance (requirements — numbers are fixed, mechanism is yours)\n\n- **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).\n- **Per-client-credential rate limits:** 60 req/min for `read:own`/`read:any`; 10 req/min for `profile:search`. **Enforcement site: rate-limiting middleware in `internal/api/`, keyed per client credential (`sub` claim).**\n- **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.\n- Sustained near-limit usage on any of the above should alert, not just silently throttle. **Enforcement site: the same rate-limiting middleware and counting store above, not a separate mechanism.**"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md",
  "old_string": "**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.",
  "new_string": "**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."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-03-auth.md has been updated successfully. (file state is current in your context — no need to Read it back)

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

55	- **`profile:search`**: additionally enforces the per-query result cap; a query that would exceed it unconstrained (e.g., a bare wildcard) is rejected outright, not truncated.
56	
57	### Pagination, rate limits, and decomposition resistance
58	
59	- **Cursor-based pagination**, not offset — offset walks turn a capped page size into full-table enumeration. Default page 20, hard ceiling 50.
60	- **Per-client-credential rate limits**: 60 req/min for `read:own`/`read:any`, 10 req/min for `profile:search`.
61	- **Cumulative distinct-record-touch counter per caller per rolling window** (e.g., no more than N distinct profiles returned to one credential per 24h), tracked independently of per-minute rate. A single-request cap and per-minute throttling only stop single-request or bursty enumeration; a caller staying under both limits can still walk the namespace in slices and reassemble the population over time (decomposition) — this counter is what catches that pattern regardless of how slowly it's spread. Counting-store mechanism is 03/04's to build; the requirement that volume is measured cumulatively, not just per-minute, is set here.
62	  - **Applies to `profile:read:any` as well as `profile:search`, unconditionally on `reason_code` presence — S8 review fix (Tomasz Wrede).** The original wording ("without a fresh `reason_code`/justification") made the counter a no-op for `read:any`, because `read:any`'s object-level policy hook already requires a `reason_code` on *every* call — so every `read:any` request trivially satisfied the exemption, and a compromised-but-legitimate `read:any` credential could walk the entire table one id at a time, tagging every call with the same reason code, and never trip the counter. The counter now applies to `read:any` regardless of whether a `reason_code` is present; a valid, non-repeating reason code does not exempt a caller from the cumulative cap, only from the *per-call* policy check. This closes the gap for the scope with the broadest blast radius (no referral constraint), which nobody in S4's adversarial pair was looking at from this angle.

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "- **Cursor-based pagination**, not offset — offset walks turn a capped page size into full-table enumeration. Default page 20, hard ceiling 50.",
  "new_string": "- **Opaque cursor at the API boundary** (reasoning corrected by the cross-track consistency pass, F-pag): the earlier claim that offset paging itself \"turns a capped page size into full-table enumeration\" was wrong — a keyset cursor permits the identical page-by-page walk, just statefully. The actual control against decomposition-style enumeration is the cumulative distinct-record-touch counter below, not the paging scheme. The API's cursor is opaque to the caller and may encode 05's DAO-layer `Offset int` directly — the boundary property this API needs (callers can't construct or walk a page index by hand) holds regardless of what the DAO does underneath. Default page 20, hard ceiling 50 at the API boundary (05's DAO ceiling of 10,000 is not exposed)."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

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

36	### Scope vocabulary
37	
38	- **`profile:read:own`** — retrieve a single record by an id the caller already holds a legitimate reference to (e.g., a partner resolving a user it referred). Enforced against a `caller_referral` mapping (below), not by scope alone. Does not authorize search/query by name or phone fragment.
39	- **`profile:read:any`** — retrieve a single record by id, no referral constraint. Not a default grant: provisioning requires an entry in an explicit caller-role table (service name, business justification, and specifically *why* `read:own`'s referral constraint is insufficient for that caller's function), gated the same way `profile:search` is below. If no caller meets that bar, the scope stays defined but unissued.
40	- **`profile:search`** — query by name/phone fragment across the table; the PII-enumeration-engine risk the threat model names. Its own gated capability, not "`read:any` plus search."
41	

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

47	4. Tighter rate/result limits than any other scope (below).
48	
49	### Object-level policy hook
50	
51	A per-scope policy function `authorize(sub, scope, target)` runs after the scope check, not instead of it — directly targeting OWASP API1:2023 (Broken Object Level Authorization):
52	

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

51	A per-scope policy function `authorize(sub, scope, target)` runs after the scope check, not instead of it — directly targeting OWASP API1:2023 (Broken Object Level Authorization):
52	
53	- **`read:own`**: checks `target.id` against the `caller_referral` mapping. Scope-valid but outside the caller's referral set → reject, logged as a policy denial (distinct from an auth failure, for detection). `caller_referral` entries are data owned by `../05-data-ops/CLAUDE.md`, written only through the same partner-onboarding workflow as any other provisioning decision (named approver, logged) — no ad hoc inserts.
54	- **`read:any`**: requires a `reason_code` from a closed, versioned enum (`support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`) logged with the audit record; adding a value to the enum requires a documented change. Freeform justification text is not acceptable — an unaudit-able reason code is the same gap as no reason code, six months later.

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md",
  "old_string": "- **`read:own`**: checks `target.id` against the `caller_referral` mapping. Scope-valid but outside the caller's referral set → reject, logged as a policy denial (distinct from an auth failure, for detection). `caller_referral` entries are data owned by `../05-data-ops/CLAUDE.md`, written only through the same partner-onboarding workflow as any other provisioning decision (named approver, logged) — no ad hoc inserts.",
  "new_string": "- **`read:own`**: checks `target.id` against the `caller_referral` mapping. Scope-valid but outside the caller's referral set → reject, logged as a policy denial (distinct from an auth failure, for detection). **Ownership corrected by the cross-track consistency pass (F8):** `caller_referral` entries and the `read:any` caller-role table below are authorization-provisioning data, held in the token-issuing authorization server's own datastore (alongside the hashed `client_secret`s), not in `05-data-ops`'s `user_profile`/`user_credential` schema — 05 never received or accepted this assignment, and it isn't subject data this project's PII-governance rules should apply to. Written only through the same partner-onboarding workflow as any other provisioning decision (named approver, logged) — no ad hoc inserts."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/api-auth-design.md has been updated successfully. (file state is current in your context — no need to Read it back)

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

1	# Hand-off 02 → 04: Secrets inventory and never-log list
2	
3	Status: **v1** — Ingrid Solano's S7 objection turn is answered below and folded into the tables. Awaiting 04's Newcomer (`wesley-okonkwo`) cold read. 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 the **design-only Kubernetes lab cluster** 04 names (Warren's decision via Theo, `../LOG.md`). 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.
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. It runs under `api-service`'s own service account; RBAC in row #2 is scoped to that account, restricted (via a distinct Kubernetes Role, not a separate ServiceAccount) so that only the issuing code path — not the token-verification code path in the same binary — can `get` the signing-key Secret. If 03 later decides to split this out as its own binary, this row's RBAC target changes with it; flag that to me if it happens, don't silently re-derive it in 04.
9	3. An **external operator agent** — a human or automated actor outside this project, holding cluster-admin or namespace-admin rights on 04's design-only 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`, 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.
10	4. Nothing is deployed and nobody contacts the cluster or its operator during the take-home. This document describes what *would* be delivered, not what has been.
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` | Token-issuing authorization-server component only — **not** `api-service`, which verifies with the public key | Runtime-injected as a **file**, never an env var; asymmetric so the API 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; restrict `get`/`list` on this Secret to the issuer's service account via RBAC | 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` (obtained via `/auth`, used for `/identity`) | `idp-connector`, in memory | **Not a deployed secret** — transient. If cached at all: TTL ≤ vendor expiry, encrypted at rest with #7, keyed per vendor account (`connector-security.md` §1) | Expires on its own; never persisted across restarts | No `Secret` object; if 04 provisions a cache, it must be encrypted using #7 and reachable only from `idp-connector` | Yes — never, including error paths |
22	| 7 | Data-encryption key (KEK) for envelope encryption of any TOTP shared secrets and any cached vendor tokens | `api-service` (TOTP) — **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. `idp-connector` (token cache) — **also not committed**: S3's red/blue on the connector token lifecycle (in progress) is deciding whether the connector caches vendor tokens at all; current direction (Felix Adebayo's alternatives turn) is "no cache by default, fetched fresh per `/identity` call," which would remove this use case too. This row is provisioned only if either feature 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	
27	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.
28	
29	## Kubernetes-specific requirements (04 implements; 02 sets)
30	
31	- **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.
32	- **RBAC:** no service account may `get`/`list` Secrets it does not mount. The operator agent's apply rights are a documented trust boundary, not a hole to close in this take-home — but the design should note that its scope could be narrowed to a namespace.
33	- **Manifests carry references, never values.** Any manifest in the repository contains Secret *names*; values are provided out-of-band. This is what keeps assumption 3 honest.
34	- **Prefer file mounts over env vars** for #2, #5, #7, #8. #1 is env-var only because 03's config surface is env-var only; if 03 accepts a `_FILE` suffix convention, move it.
35	- **No secret in an image layer, build arg, or CI log.** CI redaction is 04's mechanism; the requirement is that a build log can be published without exposing anything in this table.
36	- **Audit/access logs (the output of the never-log list below) are readable only by an incident-review role, distinct from and narrower than general operator access.** `sub`, scope, record id, and timestamp are enough on their own to reconstruct who looked up whom — that log stream needs its own read restriction, separate from whichever service account can `get`/`list` the Secrets in this table. Mechanism (log-pipeline RBAC, a separate log sink with its own access control, etc.) is 04's call; the requirement is that "can read Secrets" and "can read the audit trail" are not the same grant.
37	
38	## Never-log list (applies to every component, every environment, every log level, including error paths and stack traces)
39	
40	1. End-user vendor password (#9).
41	2. Vendor `access_token` (#6) — and any `Authorization` header value, inbound or outbound, in full.
42	3. PII field values from `user_profile` or from `/identity` responses: name, phone, `street_address`, `locality`, `region`, `postal_code`, `country`. Log the *fact* of access — caller `sub`, scope used, opaque record id, timestamp, status — never the values.
43	4. Raw vendor error response bodies (they can echo submitted PII or partial credentials). Log status code and vendor error code only.
44	5. JWT signing private key (#2) and any JWT in full — log `sub`, `aud`, `exp`, and `kid` if needed, never the token.
45	6. API caller `client_secret`s (#4), in plaintext or hashed.
46	7. `DB_DSN` (#1) or any connection string containing credentials.
47	8. Full request bodies of `POST /auth` and `POST /identity` — both contain items above by construction.
48	9. Search query parameters containing a name or phone fragment (`api-auth-design.md`, hardening) — they are PII; redact or hash before any access log, including proxy and ingress logs 04 controls.
49	
50	## What 04 does not decide (already decided upstream)
51	
52	Token TTLs and claim set (`api-auth-design.md`); scope vocabulary (`handoff-03-auth.md`, pending); password and client-secret hashing (`threat-model.md` Asset 1); whether the connector caches vendor tokens (`connector-security.md` §1 — it may, under the conditions in #6); PII retention windows (`../05-data-ops/pii-governance.md`).
53	
54	## S7 objection turn — Ingrid Solano, resolved
55	
56	All four objections accepted; no decline.
57	
58	1. **Authorization-server ownership gap.** Accepted. Assumption 2 now states the authz-issuing function is a mode of `api-service`, scoped by a Role narrower than the token-verification code path in the same binary — not a phantom third deployable.
59	2. **Missing KMS-access-credential row.** Accepted. Added row #7a with the same columns as every other row, rather than leaving it as a footnote inside #7.
60	3. **Env-var exception for `DB_DSN`.** Accepted — the objection is correct that "prefer, if 03 allows" was this track declining a call it owns. Upgraded to a requirement: a `DB_DSN_FILE` convention, with the env var as a transitional fallback only. Carried into `handoff-03-auth.md` as an ask to 03.
61	4. **No RBAC on audit-log read access.** Accepted. Added a requirement under Kubernetes-specific requirements that Secret-read and audit-log-read are distinct grants.
62	
63	---
64	Model: sonnet (lead, ruling) / sonnet (Ingrid Solano, objection turn). Turns consumed: 1 (single objection-turn pattern, per `CASTING.md` §5).
65	

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "Status: **v1** — Ingrid Solano's S7 objection turn is answered below and folded into the tables. Awaiting 04's Newcomer (`wesley-okonkwo`) cold read. 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`.",
  "new_string": "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`."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "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. It runs under `api-service`'s own service account; RBAC in row #2 is scoped to that account, restricted (via a distinct Kubernetes Role, not a separate ServiceAccount) so that only the issuing code path — not the token-verification code path in the same binary — can `get` the signing-key Secret. If 03 later decides to split this out as its own binary, this row's RBAC target changes with it; flag that to me if it happens, don't silently re-derive it in 04.",
  "new_string": "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."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "| 2 | JWT signing **private** key (RS256/ES256), per `api-auth-design.md` | Token-issuing authorization-server component only — **not** `api-service`, which verifies with the public key | Runtime-injected as a **file**, never an env var; asymmetric so the API 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; restrict `get`/`list` on this Secret to the issuer's service account via RBAC | Yes |",
  "new_string": "| 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 |"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "| 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** |\n\nNames marked pending in 03's boundary:",
  "new_string": "| 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** |\n| 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 |\n\nNames marked pending in 03's boundary:"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md",
  "old_string": "9. Search query parameters containing a name or phone fragment (`api-auth-design.md`, hardening) — they are PII; redact or hash before any access log, including proxy and ingress logs 04 controls.",
  "new_string": "9. Search query parameters containing a name or phone fragment (`api-auth-design.md`, hardening) — they are PII; redact or hash before any access log, including proxy and ingress logs 04 controls.\n10. **Database driver error messages and `DETAIL`/`Key (...)=(...)` text** (added by the cross-track consistency pass, F50 — the most probable PII-to-log path in the system and previously named by no item on this list). A Postgres CHECK or unique-constraint violation on a `user_profile`/`user_credential` write echoes the failing row's column values, or the offending key value, in its error `DETAIL`. Log SQLSTATE/result code and constraint name only — the sanitization happens in 03's error-translation layer (`error-semantics.md`) before the error is wrapped for logging, not after.\n11. **Username** (added by the same pass, F50) — typically an email address, and previously ungoverned by this list even though it can appear in `ErrDuplicateUsername` driver detail (item 10) or in a log line correlating a failed login. Treat it with the same discipline as a PII field value (item 3): log a hash or an opaque identifier for correlation, never the raw value."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/handoff-04-secrets.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "offset": 10,
  "limit": 8
}

10	### Concrete hashing decision, against the landed schema
11	
12	Priya's prose schema in `../05-data-ops/multi-db-strategy.md` (the `.sql` files were deliberately wiped with the rest of the code on 2026-09-12; the prose contract is the source of truth until Warren's code go-ahead) gives `user_credential` three columns for this purpose: `secret` (nullable TEXT, salted hash only — NULL where `auth_method.requires_secret = false`, e.g. passkey/WebAuthn), `hash_algo` (VARCHAR, e.g. `'argon2id'`), and `hash_cost` (INTEGER, the work factor at hash time). This track's concrete decision against those columns:
13	
14	- **`hash_algo = 'argon2id'`**, per OWASP's current recommendation, consistent with NIST SP 800-63B Rev. 3's requirement of a memory-hard one-way key derivation function (800-63B Rev. 3, currently in force, requires a "suitable" memory-hard KDF without naming Argon2id specifically by name; Argon2id-by-name guidance appears in the SP 800-63-4 draft revision, not yet final — cited precisely rather than invoking "NIST recommends Argon2id" as if it were settled text). bcrypt is the documented fallback (`hash_algo = 'bcrypt'`) only if the Go implementation's Argon2id library support is unavailable in the chosen stack — a call for `03-engineering-delivery` to confirm, not a reason to default to bcrypt speculatively.
15	- **Salt handling**: no separate salt column is needed or wanted. Argon2id's standard encoded output (the `«REDACTED-ARGON2»` PHC string format) embeds a fresh random salt per row inside the `secret` column's own text — this is what makes the hash self-describing and rehashable without a side lookup. Do not add a `salt` column; it would be redundant with the encoded format and an easy place for an implementation to accidentally desync salt from hash.
16	- **`hash_cost` at minimum**: memory ≥19 MiB, iterations ≥2, parallelism ≥1 (OWASP's Argon2id floor) — recorded per-row (not just globally) specifically so a future cost bump can be applied to newly-created/rotated rows without forcing every existing row to rehash in lockstep, per the schema's own stated intent of supporting an in-place scheme upgrade.
17	- **`requires_secret = false` rows** (passkey/WebAuthn, `secret IS NULL`): no hashing question at all — the server holds only public key material for those methods, which is a different asset class (public, not secret) and does not belong in `secret`/`hash_algo`/`hash_cost` at all if/when a passkey method is actually added. Flagged here so `03-engineering-delivery` doesn't try to force a WebAuthn public key through the password-hashing path.

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "old_string": "Priya's prose schema in `../05-data-ops/multi-db-strategy.md` (the `.sql` files were deliberately wiped with the rest of the code on 2026-09-12; the prose contract is the source of truth until Warren's code go-ahead) gives `user_credential` three columns for this purpose: `secret` (nullable TEXT, salted hash only — NULL where `auth_method.requires_secret = false`, e.g. passkey/WebAuthn), `hash_algo` (VARCHAR, e.g. `'argon2id'`), and `hash_cost` (INTEGER, the work factor at hash time). This track's concrete decision against those columns:",
  "new_string": "Priya's prose schema in `../05-data-ops/multi-db-strategy.md` (the `.sql` files were deliberately wiped with the rest of the code on 2026-09-12; the prose contract is the source of truth until Warren's code go-ahead) gives `user_credential` three columns for this purpose: `secret` (nullable, bytes holding the PHC-encoded hash string — `BYTEA`/`BLOB`, Go `[]byte`; corrected by the cross-track consistency pass, F34 — this was previously described here as \"nullable TEXT,\" which is wrong against the landed contract type; NULL where `auth_method.requires_secret = false`, e.g. passkey/WebAuthn), `hash_algo` (VARCHAR, e.g. `'argon2id'`), and `hash_cost` (INTEGER, the work factor at hash time). This track's concrete decision against those columns:"
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md has been updated successfully. (file state is current in your context — no need to Read it back)

{
  "replace_all": false,
  "file_path": "/Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md",
  "old_string": "embeds a fresh random salt per row inside the `secret` column's own text — this is what makes the hash self-describing and rehashable without a side lookup.",
  "new_string": "embeds a fresh random salt per row inside the `secret` column's own bytes — this is what makes the hash self-describing and rehashable without a side lookup."
}

The file /Users/warrenthompson/Source/LoginID/02-ai-security-architecture/threat-model.md has been updated successfully. (file state is current in your context — no need to Read it back)