Define account fixture-credential semantics

[Brad-Edwards]

Gap

The top-level SDL account model exposes account posture such as password_strength, but it cannot bind a deliberate plaintext exercise fixture to the account it authenticates. Runtime values can already carry a secret_fixture value under ADR-057, yet the canonical relationship between that value and an account is undefined.

This conflates three different things:

1. the existence and posture of an account;
2. a deliberately disclosed scenario fixture credential; and
3. an operator-managed secret that must not appear in the artifact.

Current ownership boundary

RAES owns the typed semantic distinction and the canonical binding between an account and a credential value or reference.

• Packs/catalogs own concrete exercise fixture values.
• env-packs owns pack validation and authoring workflows around those values.
• Backends own secret injection and realization.
• Hub may explain or edit the contract but does not define credential meaning.

Decision required

Choose and specify one canonical model:

• a typed account credential binding that can carry an explicitly classified secret_fixture; or
• an account-to-runtime-value reference with equivalent type safety and inspectability.

The decision must not make arbitrary runtime placement the implicit convention.

Acceptance criteria

• Account posture, fixture credentials, and operator secrets are represented as distinct concepts.
• A fixture value is bound unambiguously to the account and authentication purpose it serves.
• Literal values are permitted only under the governed fixture classification and information-flow rules.
• Operator secrets are absent or referenced, never embedded as fixture values.
• Validation rejects ambiguous, unclassified, or cross-account credential bindings.
• Redaction, normalization, provenance, generated contracts, and participant-visible inspection are specified.
• Examples include a deliberate weak exercise credential and an operator-secret reference.

Non-goals

• Building an operator secret store.
• Defining backend-specific injection mechanisms.
• Treating password_strength as a credential value.

Requirements

• DSL-439

Refs: #637, #471, and ADR-057.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 673-account-fixture-credentials, 2026-08-02T21:13:21.240Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #673). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #673). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #673). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan

Requirement anchor: DSL-439 (DRAFT). This source-bearing change adds structural schema, semantic, plan-admission, and disclosure gates; traceability will be reconciled after merge.

1. Drive the contract with focused failing tests. Add issue-673 tests for the nested account credential-binding model, closed fixture/operator material union, governed purpose/method normalization, safe operator-reference shape, portable IDs, duplicate and primary-method rejection, cross-account/extra-field rejection, variable instantiation and provenance, compiler preservation, unsupported-provisioner failure, generic plan-output redaction, backend-result/snapshot/diagnostic/details redaction, input-free HTTP 422 responses, generated schema parity, vocabularies, and the deliberate weak-fixture/operator-reference examples. Run each focused group red before production changes and green afterward.
2. Add the canonical typed account semantics. Extend implementations/python/packages/raes/accounts.py with stable credential IDs, governed authentication purposes and methods, and a discriminated secret_fixture / operator_secret material union nested under Account.credential_bindings. Reuse portable identifiers, whole-field variables, SDLModel(extra="forbid"), and a shared safe secret-reference identity extracted from the existing experiment-binding contract. Extend SemanticValidator._verify_accounts() with value-free duplicate and primary-method diagnostics; composition and instantiation keep using the existing recursive lifecycle and concrete revalidation.
3. Fail closed across planning and runtime boundaries. Extend the canonical provisioner_account_features() extractor with credential_bindings; keep existing backend manifests unchanged so unsupported backends reject the feature. Reconstruct and validate credential-bearing account specs on direct plan submission, verify the account/address join, and reject unsupported provisioners before side effects. Reuse one value-free projection for generic CLI plan output and backend-return sanitization so fixture values and operator reference IDs cannot persist or appear in snapshots, diagnostics, apply details, or generic inspection. Install a bounded input-free request-validation envelope for HTTP 422 responses.
4. Publish the normative contract and guidance. Add a normative account-credential-binding specification and update the SDL explanation/index/reference surfaces. Update the controlled vocabularies for credential purposes, authentication methods, and the provisioner feature; update the scenario-account reference model and language metadata. Regenerate all Account-embedding schemas (authoring, instantiated, instantiated snapshot, and satisfiability), update their v2 publication entries with summaries and content hashes, and keep schema_bundle() byte-equivalent. Preserve the architecture-preflight note as the design record. No backend realization, secret store, resolver, participant route, changelog, or version edit is introduced.
5. Verify clause by clause and repository-wide. Map every DSL-439 clause and issue acceptance criterion to code/tests/docs. Run focused pytest throughout, then with RAES_REQUIREMENT_UID=DSL-439 run implementations/python/.venv/bin/python tools/check_repo_policy.py, implementations/python/.venv/bin/python tools/check_requirement_governance.py, implementations/python/.venv/bin/python tools/verify_all.py, and the configured completion/policy gates. Ground Control will reconcile IMPLEMENTS/TESTS links and transition DSL-439 only after merge.

Design checks

• Security: authored YAML/schema closure, semantic and instantiated admission, direct-plan shape/capability admission, authenticated control-plane submission, host/OS non-exposure, backend-return sanitation, persistence, diagnostics/audits, generic CLI output, HTTP error envelopes, and participant/publication boundaries all receive explicit value-free or authorized-carrier behavior.
• Maintainability: reuse Account, SemanticValidator, portable IDs, whole-field variables, existing experiment safe-reference syntax, AccountPlacement.spec, provisioner_account_features(), plan contracts, backend-call adapters, and schema/publication tooling; add no parallel DTO, resolver, logger, exception hierarchy, or redaction registry.
• Extensibility: the stable seam is a binding list keyed by credential ID and parameterized by governed purpose, method, and a closed material variant. New purposes/methods use governed terms; a new material kind requires a reviewed union member and information-flow policy.
• Whole-repo view: SDL models/parser/instantiation/validator/compiler, provisioner manifests and direct submission, CLI/runtime/control-plane persistence and errors, contract generation/publication, concept authority, normative specs/explanations, fixtures, and policy/traceability checks are in scope.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #673 (branch 673-account-fixture-credentials)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: don't-ship

The core domain shape is sound: credential bindings live under Account, reuse a shared authentication vocabulary and secret-reference identity, use a closed material union, participate in semantic validation and capability admission, and move through the published contracts together. The faulty seam is the cross-cutting value-free projection: it discovers credential values and then rewrites every string in complete plan, result, API, and persistence carriers. That couples credential handling to unrelated identities and can corrupt otherwise valid state. The tests prove absence of sentinel values but do not prove that projection preserves non-credential semantics when values collide with ordinary strings.

Blocking findings (1):

1. [class] Code-quality: Whole-carrier token substitution corrupts valid structured data — implementations/python/packages/raes_contracts/account_credentials.py:62
   Fixture values are unconstrained and operator reference IDs can also be ordinary words, so a legal token such as admin, create, or web is replaced wherever it occurs—not only in credential material. The current call sites apply this to complete plans and snapshots, allowing account names, actions, addresses, node identities, and other fields to be mutated. Mapping keys are not transformed, so a snapshot entry key can also diverge from its embedded address, breaking validation or persisted-state reconstruction. Project canonical credential-material nodes structurally; restrict token scrubbing to explicitly untrusted prose carriers such as backend messages/details, and fail closed rather than rewriting typed identity fields that echo material.

Security review

Verdict: ship-with-fixes

The change is shaped around the correct seams: a closed credential-material union nested under accounts, canonical validation for compiled and directly submitted plans, fail-closed backend capability admission, and one shared value-free projection used at output and persistence boundaries. That preserves account ownership and leaves a reviewed union member as the obvious extension point. The security boundary is incomplete, however, because the central projection does not sanitize every JSON string position.

Blocking findings (1):

1. [one-off] Credential material is emitted unchanged when used as a mapping key — implementations/python/packages/raes_contracts/account_credentials.py:54
   Attacker model: a caller permitted to read generic operation results or snapshots but not credential material. A provisioner can return a submitted fixture value or operator reference as a key in ApplyResult.details, snapshot metadata, or another nested mapping. This projection recursively sanitizes mapping values but copies str(key) unchanged, so the credential survives as a JSON object member name and reaches the API or persisted snapshot. Sanitize or reject sensitive tokens in mapping keys as well as values, handling redaction collisions fail-closed, and cover a credential-bearing key through backend-result, persistence, and API tests.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #673 on branch '673-account-fixture-credentials'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #673)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The core domain shape is sound: credential bindings live under Account, reuse a shared authentication vocabulary and secret-reference identity, use a closed material union, participate in semantic validation and capability admission, and move through the published contracts together. The faulty seam is the cross-cutting value-free projection: it discovers credential values and then rewrites every string in complete plan, result, API, and persistence carriers. That couples credential handling to unrelated identities and can corrupt otherwise valid state. The tests prove absence of sentinel values but do not prove that projection preserves non-credential semantics when values collide with ordinary strings.

Security reviewer: The change is shaped around the correct seams: a closed credential-material union nested under accounts, canonical validation for compiled and directly submitted plans, fail-closed backend capability admission, and one shared value-free projection used at output and persistence boundaries. That preserves account ownership and leaves a reviewed union member as the obvious extension point. The security boundary is incomplete, however, because the central projection does not sanitize every JSON string position.

Blocking findings: 2

Finding 1 — class (8 instances)

• ID: F1
• Title: [core] Code-quality: Whole-carrier token substitution corrupts valid structured data
• Location: implementations/python/packages/raes_contracts/account_credentials.py:62
• Decision: fix
• Rationale: Fixture values are unconstrained and operator reference IDs can also be ordinary words, so a legal token such as admin, create, or web is replaced wherever it occurs—not only in credential material. The current call sites apply this …
• Instances:
  • implementations/python/packages/raes_contracts/account_credentials.py:62
  • implementations/python/packages/raes_cli/processor.py:147
  • implementations/python/packages/raes_runtime/backend_calls.py:238
  • implementations/python/packages/raes_runtime/backend_calls.py:239
  • implementations/python/packages/raes_runtime/backend_calls.py:250
  • implementations/python/packages/raes_runtime/backend_calls.py:260
  • implementations/python/packages/raes_runtime/control_plane_api_models.py:215
  • implementations/python/packages/raes_runtime/control_plane_store.py:263

Finding 2 — one-off

• ID: F2
• Title: [security] Credential material is emitted unchanged when used as a mapping key
• Location: implementations/python/packages/raes_contracts/account_credentials.py:54
• Decision: fix
• Rationale: Attacker model: a caller permitted to read generic operation results or snapshots but not credential material. A provisioner can return a submitted fixture value or operator reference as a key in ApplyResult.details, snapshot metadata, or …

[Brad-Edwards]

gc_codex_review — cycle 2 of 1 (pre-push) on issue #673 (branch 673-account-fixture-credentials)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: don't-ship

The change is directionally shaped around the right seams: credentials remain nested under Account, reuse a shared reference-id type and governed vocabulary, travel through account placement, and meet the incumbent capability-admission and runtime-projection boundaries. The closed material union also preserves the obvious extension path. Two cross-cutting contracts remain incoherent, however: the satisfiability evidence reopens authoring variables at an instantiated boundary, and runtime projection identifies credential data globally by discriminator and matching text rather than by the canonical account-credential path. Those systemic boundary errors make the change not yet production-ready.

Blocking findings (2):

1. [class] Instantiated satisfiability witnesses admit unresolved credential variables — contracts/schemas/satisfiability/scenario-satisfiability-evidence-v1.json:99
   This schema describes the canonical instantiated witness, but the new Account and AccountCredentialBinding definitions retain authoring-phase ${...} alternatives for account method, binding method, purpose, and operator reference; the fixture value is likewise unrestricted. The dedicated instantiated-scenario schemas correctly exclude those references. Consequently, satisfiability evidence can validate while carrying credential semantics that were never concretized or revalidated. Generate these definitions from the concrete phase contract and add negative conformance cases for unresolved method, purpose, fixture value, and reference ID.
2. [class] Credential sanitization rejects legitimate colliding state — implementations/python/packages/raes_contracts/account_credentials.py:106
   After projecting material nodes, this scans every key and string for each submitted credential token using substring matching. A valid weak fixture such as admin therefore collides with an account name, username, address, or unrelated status and makes snapshot persistence/publication raise or converts a successful backend apply into a contract failure. The companion projection also collapses any mapping anywhere whose classification happens to equal a credential discriminator. Traverse the canonical account-placement credential-material paths structurally, and restrict token redaction to explicitly untrusted prose carriers; independent typed fields must remain valid when their text happens to match a fixture. Extend the existing collision test across backend-result, store, and snapshot-API paths.

Security review

Verdict: don't-ship

The nested account binding and closed fixture/operator material union are the correct semantic seam, and the change appropriately carries it through schema publication, direct-plan admission, capability negotiation, backend execution, persistence, and generic projections. The security-critical design seam is backend egress, however, and it remains open: value-free enforcement is based on discovering and blacklisting submitted strings rather than validating a closed result projection. That cannot safely support the intended next variation—an operator-secret-resolving backend—because the resolved value is never known to the scanner.

Blocking findings (1):

1. [class] Exact-token redaction does not enforce the credential egress boundary — implementations/python/packages/raes_contracts/account_credentials.py:64
   Attacker model: a user who may read generic operation or snapshot output but is not authorized to see fixture material or resolved operator secrets, with a provisioner that accidentally returns credential data. The egress gate only searches for exact fixture literals and reference IDs collected from the submitted plan. A resolved operator secret is absent from that token set, while an encoded, hashed, or split fixture also does not match, so any of those values can pass through backend details, diagnostics, or snapshot fields and be persisted or published. There is also a direct exact-value bypass: sanitize_account_credential_result examines entry payload/status and only top-level RuntimeSnapshot fields whose Python value is a dict; credential material copied into realization_provenance, realization_observations, realization_envelope, or another non-dict carrier survives. Persistence and API projection then rediscover tokens from the already-projected snapshot, where the canonical material value has been removed, and therefore cannot detect the surviving copy. Replace token blacklisting with a closed, typed value-free projection for credential-bearing backend results—admitting only binding identity, classification/presence posture, and approved realization evidence—and reject unexpected carriers before persistence or publication. The protected resolver sink must likewise guarantee that resolved or material-derived bytes cannot enter ApplyResult.

[Brad-Edwards]

gc_codex_review pre-push cycle 2 (USER-AUTHORIZED OVERRIDE past cap 1) complete for issue #673 on branch '673-account-fixture-credentials'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.
Override reason: User explicitly authorized one additional Codex review cycle in this session on 2026-08-03.