stack/docs/scratchpads/1045-mosaic-cred.md

MC-CRED-01 / stack #1045 scratchpad

Last updated: 2026-08-05

Objective

Deliver the governed mosaic cred identity boundary for issue, scope, validation, rotation, and revocation across explicitly declared estates. Interim merge target is next; terminal status remains believed-fixed, pending validation AND pending promotion to main.

Requirements sources

• Charter: /home/hermes/agent-work/tl-mosaic/CHARTER-MC-CRED-01-be-coder-06.md
• Stack issues: #1045, #1043, #1044, #1047, #1049, #1013, #1007; promotion #1037; consumer #1051
• Remote spec: jason.woltje/jarvis-brain origin/main b7687d51f4efe52e43dbcd6dc95b5554b3332957
• Greenfield PRD v3 addenda: INV-B durable journal, INV-C visible failure diagnostics, INV-D supported fixture
• Binding doctrine: /src/jarvis-brain/infra/fleet/FLEET-DOCTRINE.md

Plan

1. Publish grant/validate v1 caller contract for MB-BRAIN-01.
2. Add repo PRD requirements and preregister acceptance tests.
3. Implement explicit estate registry, secure current file-store adapter, durable operation journal/audit, provider transport, and terminal result types.
4. Implement grant and side-effect-free validate; then provision/wire/get/whoami/list/rotate/revoke/audit.
5. Make git and API resolver refusals identical and fail closed under fleet context.
6. Reconcile live HOMELAB seats through each subject credential's own /user; #1044 hold is lifted, and its fail-closed change carries the pre-registered mechanism evidence (resolver refusal marker, same-run marker positive control, confirmed-lane negative arm).
7. Run baseline/situational tests, independent code review and mandatory independent security review, CI on exact head, then open PR against next without closing issues or claiming completion.
8. After C1 merges first, rebase/refresh the base and re-take head-bound CI/provider measurements only.

Budget

No explicit token cap supplied. Working cap: keep implementation in one package plus shipped framework resolver changes and required docs/tests; avoid unrelated wrapper defect fixes and VaultWarden redesign. Escalate only if a charter requirement is technically unsatisfiable.

Decisions

• VaultWarden is out for the agent tier per the charter verdict; phase 1 governs the existing per-identity file store.
• Estate is explicit input and must match a configured host mapping; target host is never inferred from machine location.
• Grant authority and basic-auth provisioning material are delegated control-plane credentials, never caller bearer material and never CLI argument/output.
• ok, refused, error, and indeterminate are distinct machine outcomes. Security callers fail closed on all but ok, while retaining the semantic distinction.
• Gitea write-differential resolves the subject once and binds provider identity, repository permission, and receive-pack to the same in-memory credential handle. It adds a distinct provider-confirmed read-only-principal control plus the unauthenticated control, with no ref update. The live HOMELAB negative-control subject is tl-mosaic, verified read-only on mosaicstack/stack; code and contract remain principal-agnostic.

Progress

• Mode/intake/core guides/skills/doctrine loaded.
• Spec repository READ confirmed under be-coder-06 from provider object.
• Target-branch completion conflict raised; lead ruled work may proceed to PR/CI on next but not completion/closure.
• Canonical remote PRD v3 addenda re-read at new head.
• Required issues read via Mosaic wrapper.
• Early grant/validate contract v1 published at docs/credentials/GRANT-VALIDATE-CONTRACT.md.
• Contract v1.1 binds transport to the same resolved principal and adds a provider-confirmed read-only-principal control.
• Contract v1.2 distinguishes provider outage, absent identity, and rejected credential.
• Contract v1.3 positive-controlled anonymous visibility; subsequently withdrawn as unsound for private identities.
• Contract v1.4 implements ruling (b): subject credential's own /user, no admin/inventory authority, no implemented identity-not-found path.
• PRD update.
• Red-first principal-bound validate, estate-registry, file-store, provider-transport, and journal tests.
• Implementation (validate core/CLI, direct/team grant core, and protected delegated-authority fd reader in progress; provider team adapter, CLI grant integration, remaining lifecycle commands, and separately sequenced fail-closed resolver evidence open).
• Independent code/security reviews.
• CI and provider evidence.

Tests and evidence

Baseline after workspace build: package typecheck passed; Vitest 81/81 files and 1,514/1,514 tests passed. The package shell suite reached a pre-existing tracked #973 Bash 5.2 BASH_LINENO incompatibility and exited 97 before wake tests; this is baseline, not introduced by MC-CRED.

Red-first evidence:

• principal-bound validate module absent → focused suite red;
• incremental v1.1 run: write-capable, identity-mismatched, and receive-pack-admitted read-only controls each returned ok, causing 3/13 tests to fail for the exact control defect; after the control checks, 13/13 passed;
• read validation absent → 2 tests failed evaluateGiteaReadValidation is not a function; after implementation, 15/15 validate tests passed;
• estate registry, secure file resolver, Gitea transport, and audit journal each failed first because the module did not exist, then passed focused behavior suites.

Current focused evidence after v1.4: provider + validate 23/23, durable correction journal 5/5, delegated credential fd 2/2, direct grant 2/2, team grant 1/1; package typecheck green.

Live validation v1.4 (subject credential's own /user, no admin): population 13; CONFIRMED 8; CREDENTIAL-REJECTED 4 (coder-mos1, coder-mos2, f10-coder, merge-gate); MISMATCH 1 (mos-admin token authenticates as Mos); NOT-MEASURED 0. The four false v1.2 identity-not-found sealed journals remain immutable and are explicitly superseded by four sealed correction journals. Evidence: /home/hermes/agent-work/be-coder-06/live-validation-v1.4/.

Write differential for be-coder-06 passed with the configured read-only control and unauthenticated arm. Unit evidence proves the control arm invalidates validation when write-capable, identity-mismatched, or receive-pack-admitted.

Risks/blockers

• The full CLI surface is broad; protect scope by sharing one provider/registry/journal core rather than per-command scripts.
• Gitea exact token-scope read-back may require delegated Basic Auth. If a bearer-only validation path cannot obtain an exact provider token object, return indeterminate rather than claim a scope.
• #1044 hold is LIFTED: the four credentials are already rejected and fail-open preserves silent misattribution. Re-mint is separate fleet task #19. The fail-closed change still requires normal review/green plus mechanism evidence proving resolver refusal, a same-run marker-emission positive control, and unaffected confirmed lanes; tl-mosaic independently verifies.
• Branch model compatibility remains escalated above this lane. Do not claim completion at next.