ARCH-01 — Evidence attestations, typed subjects, digest binding, and immutability #825

New Issue

2026-07-22T19:43:08-05:00

jcwalker3 commented

2026-07-22 19:43:08 -05:00

Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.

Parents: #820, #821. Depends on: #822.

1. Summary / objective

Implement evidence records bound one-to-one to issuer attestations, each carrying exactly one typed subject whose canonical digest is bound into the attestation, all immutable.

2. Security/correctness problem

Downstream authority (repository external-id proof, operator approval, principal linkage, workspace probe) trusts evidence. If an evidence record does not bind the exact subject it claims to prove, a service can pair a correctly-typed subject with an attestation that authenticated different content.

3. Threat model / failure modes

Attestation reuse across records; an attestation appearing in multiple subject tables; subject_digest disagreeing with the actual subject; a record naming an attestation of a different store/generation/kind/reference/digest; failed-scan evidence promoted; digest recomputation trusted to a nonexistent DB SHA-256.

4. In-scope behavior

evidence_issuance_attestations with UNIQUE(store_id,store_reference_id) (one per reference) and a composite candidate key (attestation_id,store_id,config_generation,reference_kind,store_reference_id,content_digest). [SCHEMA].
evidence_records with UNIQUE(attestation_id) (single-use) and one composite FK to that candidate key (all six fields agree). [SCHEMA].
Exactly one typed subject per attestation across four tables (repository_external_id, operator_binding_approval, principal_linkage, workspace_probe); subject_kind must match the table; no attestation in two subject tables. [SCHEMA] via per-table triggers scanning the others.
subject_digest (sha256 over the canonical typed subject) stored on the attestation; subject_canon_version recorded. Digest computation is [TRUSTED-SERVICE] (or a named registered DB function if adopted — do not claim SQLite/PG recompute SHA-256 natively); digest equality at consume time is [SCHEMA].
Content/subject/proof digest CHECKs: 64 lowercase hex, true [0-9a-f] only. [SCHEMA].
Immutability of attestations and subject rows (reject UPDATE/DELETE); evidence-record fields immutable except status. [SCHEMA].
Lifecycle after the underlying object changes: a changed object requires new evidence; old evidence remains historical (never mutated).
Distinguish attested_by principal from the verifying service identity and session (verifying_service_session_id).
Retain failed verification attempts where security auditing requires (separate append log; failed scans never usable as current/valid).

5. Exclusions

No remote signature verification (→ issuer-proof issue), no store-config lifecycle beyond the FK to it (→ issuer-proof issue), no consumers' business logic.

6. Schema/operation contracts

Tables above + evidence_reference_kinds (subject_kind per kind) + evidence_subject_* (4). Operations: record_evidence (supervisor.verify or internal_service with capability), subject insert bundled into the same transaction.

7. SQLite behavior

Composite FK + unique indexes; per-table subject-exclusivity triggers scan the other three tables in the same statement.

8. PostgreSQL behavior

Same constraints; digest function is the service's, invoked before insert; EXECUTE restricted.

9. Concurrency / transaction requirements

Attestation + subject + record created in one transaction; a second record for the same attestation or a second subject fails on the unique/exclusivity checks.

10. Structured results

EVIDENCE_RECORDED, EVIDENCE_COMPOSITE_MISMATCH, SUBJECT_KIND_MISMATCH, SUBJECT_DIGEST_MISMATCH, ATTESTATION_REUSE, RECORD_EVIDENCE_UNAUTHORIZED.

11. Enforcement classification

Composite FK, single-use, subject exclusivity, digest hex-shape, immutability [SCHEMA]; digest computation [TRUSTED-SERVICE]; issuer signature [RUNTIME-ADAPTER] (deferred).

12. Acceptance criteria

Record identity agrees with its attestation on all six fields.
One attestation backs at most one record.
One attestation per store reference.
Exactly one typed subject per attestation, kind-matched.
An attestation cannot appear in two subject tables.
subject_digest disagreement → SUBJECT_DIGEST_MISMATCH.
Digests are true 64-hex.
Attestations/subjects immutable; record only status-transitions.
record_evidence limited to supervisor.verify or capable internal service.

13. Named tests

t_evid_store_mismatch(−), t_attestation_reuse(−), t_conflicting_attestation(−), t_two_subjects(−), t_wrong_subject_kind(−), t_subject_digest_mismatch(−), t_bad_digest(−), t_attestation_immutable(raw-bypass), t_record_evidence_unauth(−).

14. Audit events / evidence

evidence_recorded, evidence_subject_bound. Test output is evidence.

15. Dependencies / parent

Parents #820, #821; depends #822; consumes store_config_generations from the issuer-proof issue.

16. Definition of done

Executable on SQLite (PostgreSQL parity via #8 issue); ACs pass incl. raw-bypass; bounded PR; no self-review/merge.

17. Known limitations / deferred

Remote signature verification and store-generation lifecycle → issuer-proof issue. Digest-function conformance vector required in readiness checks.

**Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.** Parents: #820, #821. Depends on: #822. ## 1. Summary / objective Implement evidence records bound one-to-one to issuer attestations, each carrying exactly one typed subject whose canonical digest is bound into the attestation, all immutable. ## 2. Security/correctness problem Downstream authority (repository external-id proof, operator approval, principal linkage, workspace probe) trusts evidence. If an evidence record does not bind the exact subject it claims to prove, a service can pair a correctly-typed subject with an attestation that authenticated different content. ## 3. Threat model / failure modes Attestation reuse across records; an attestation appearing in multiple subject tables; subject_digest disagreeing with the actual subject; a record naming an attestation of a different store/generation/kind/reference/digest; failed-scan evidence promoted; digest recomputation trusted to a nonexistent DB SHA-256. ## 4. In-scope behavior - `evidence_issuance_attestations` with `UNIQUE(store_id,store_reference_id)` (one per reference) and a composite candidate key `(attestation_id,store_id,config_generation,reference_kind,store_reference_id,content_digest)`. `[SCHEMA]`. - `evidence_records` with `UNIQUE(attestation_id)` (single-use) and **one composite FK** to that candidate key (all six fields agree). `[SCHEMA]`. - Exactly one typed subject per attestation across four tables (`repository_external_id`, `operator_binding_approval`, `principal_linkage`, `workspace_probe`); `subject_kind` must match the table; no attestation in two subject tables. `[SCHEMA]` via per-table triggers scanning the others. - `subject_digest` (sha256 over the canonical typed subject) stored on the attestation; `subject_canon_version` recorded. Digest **computation** is `[TRUSTED-SERVICE]` (or a named registered DB function if adopted — do not claim SQLite/PG recompute SHA-256 natively); digest **equality** at consume time is `[SCHEMA]`. - Content/subject/proof digest CHECKs: 64 lowercase hex, true `[0-9a-f]` only. `[SCHEMA]`. - Immutability of attestations and subject rows (reject UPDATE/DELETE); evidence-record fields immutable except `status`. `[SCHEMA]`. - Lifecycle after the underlying object changes: a changed object requires **new** evidence; old evidence remains historical (never mutated). - Distinguish `attested_by` principal from the verifying service identity and session (`verifying_service_session_id`). - Retain failed verification attempts where security auditing requires (separate append log; failed scans never usable as current/valid). ## 5. Exclusions No remote signature verification (→ issuer-proof issue), no store-config lifecycle beyond the FK to it (→ issuer-proof issue), no consumers' business logic. ## 6. Schema/operation contracts Tables above + `evidence_reference_kinds` (subject_kind per kind) + `evidence_subject_*` (4). Operations: `record_evidence` (supervisor.verify or internal_service with capability), subject insert bundled into the same transaction. ## 7. SQLite behavior Composite FK + unique indexes; per-table subject-exclusivity triggers scan the other three tables in the same statement. ## 8. PostgreSQL behavior Same constraints; digest function is the service's, invoked before insert; `EXECUTE` restricted. ## 9. Concurrency / transaction requirements Attestation + subject + record created in one transaction; a second record for the same attestation or a second subject fails on the unique/exclusivity checks. ## 10. Structured results `EVIDENCE_RECORDED`, `EVIDENCE_COMPOSITE_MISMATCH`, `SUBJECT_KIND_MISMATCH`, `SUBJECT_DIGEST_MISMATCH`, `ATTESTATION_REUSE`, `RECORD_EVIDENCE_UNAUTHORIZED`. ## 11. Enforcement classification Composite FK, single-use, subject exclusivity, digest hex-shape, immutability `[SCHEMA]`; digest computation `[TRUSTED-SERVICE]`; issuer signature `[RUNTIME-ADAPTER]` (deferred). ## 12. Acceptance criteria 1. Record identity agrees with its attestation on all six fields. 2. One attestation backs at most one record. 3. One attestation per store reference. 4. Exactly one typed subject per attestation, kind-matched. 5. An attestation cannot appear in two subject tables. 6. subject_digest disagreement → `SUBJECT_DIGEST_MISMATCH`. 7. Digests are true 64-hex. 8. Attestations/subjects immutable; record only status-transitions. 9. `record_evidence` limited to supervisor.verify or capable internal service. ## 13. Named tests `t_evid_store_mismatch`(−), `t_attestation_reuse`(−), `t_conflicting_attestation`(−), `t_two_subjects`(−), `t_wrong_subject_kind`(−), `t_subject_digest_mismatch`(−), `t_bad_digest`(−), `t_attestation_immutable`(raw-bypass), `t_record_evidence_unauth`(−). ## 14. Audit events / evidence `evidence_recorded`, `evidence_subject_bound`. Test output is evidence. ## 15. Dependencies / parent Parents #820, #821; depends #822; consumes `store_config_generations` from the issuer-proof issue. ## 16. Definition of done Executable on SQLite (PostgreSQL parity via #8 issue); ACs pass incl. raw-bypass; bounded PR; no self-review/merge. ## 17. Known limitations / deferred Remote signature verification and store-generation lifecycle → issuer-proof issue. Digest-function conformance vector required in readiness checks.

jcwalker3 referenced this issue

2026-07-22 19:43:54 -05:00

ARCH-01 — Issuer-proof adapters, replay resistance, and immutable store configuration generations #826

jcwalker3 referenced this issue

2026-07-22 19:44:38 -05:00

ARCH-01 — PostgreSQL actor context, roles, privileges, and connection-pool safety #827

jcwalker3 referenced this issue

2026-07-22 19:49:27 -05:00

ARCH-04 — Workspace configuration generations, immutable history, and current-evidence integrity #834

jcwalker3 referenced this issue

2026-07-22 19:51:24 -05:00

Architecture acceptance matrix — invariant, test, evidence, and backend traceability #837