mirror of
https://github.com/norandom/OpenUltraSAST.git
synced 2026-11-13 01:48:17 +00:00
docs(access-control-prover): approve installed authority ceremony
This commit is contained in:
Marius Ciepluch
@@ -118,6 +118,7 @@ src/openultrasast/
|
||||
│ ├── registry.py # strategy registration and dispatch
|
||||
│ ├── registration_sites.py # generic call-site registration adapter
|
||||
│ ├── fact_authority.py # authenticate installed reviewed authority
|
||||
│ ├── installed_fact_authority.py # closed JSON decoders and checked-in artifact resolver
|
||||
│ ├── entry_packs.py # compatibility projection and v2 structural adapter
|
||||
│ ├── fact_match_store.py # persist canonical observations and match artifacts
|
||||
│ ├── legacy.py # production caller migrates to authority-bearing adapter
|
||||
@@ -148,7 +149,12 @@ src/openultrasast/ruleset/entries/
|
||||
├── authority.json # reviewed bundle payload and immutable references
|
||||
├── express.javascript.v2.json # reviewed JavaScript FactPack
|
||||
├── express.typescript.v2.json # reviewed TypeScript FactPack
|
||||
└── express.json # authenticated non-authoritative compatibility projection
|
||||
├── express.json # authenticated non-authoritative compatibility projection
|
||||
├── identities/
|
||||
│ ├── generator.json # producer identity manifest
|
||||
│ ├── maintainer-reviewer.json # maintainer approval identity manifest
|
||||
│ └── custodian.json # installed-artifact custody identity manifest
|
||||
└── artifacts/sha256/<content-digest> # canonical review/disclosure/evidence bytes
|
||||
benchmarks/valid/
|
||||
├── prover_arm.py # records, stage funnel, gates and four-arm comparison
|
||||
└── prover_admission.py # frozen-manifest admission orchestration
|
||||
@@ -461,6 +467,62 @@ writer receives an explicit store root, store identity, and retention-policy dig
|
||||
writes content-addressed canonical bytes and returns a read-only resolver plus re-derivable
|
||||
storage receipts admitted by that bootstrap policy.
|
||||
|
||||
#### Installed authority wire and review ceremony
|
||||
|
||||
The checked-in authority uses closed canonical JSON records; decoders reject unknown or
|
||||
missing fields before constructing typed objects. `bootstrap.json` has schema
|
||||
`openultrasast.access-control.entry-authority-bootstrap.v2` and exactly the five
|
||||
`EntryAuthorityBootstrapPolicy` fields. `authority.json` has schema
|
||||
`openultrasast.access-control.installed-entry-authority.v1` and exactly:
|
||||
|
||||
- `pack_files`: the ordered pair `express.javascript.v2.json`,
|
||||
`express.typescript.v2.json`;
|
||||
- `recognition_projection`, lineages, custody policy, review policy, matcher revision,
|
||||
matcher behavior digest, matcher lineage digest, authority review, and bundle digest;
|
||||
- no trust-root, reviewer-admission, or store-admission fields.
|
||||
|
||||
Each v2 pack file is canonical JSON over every public `FactPack` field and the complete
|
||||
nested `SemanticFact`, structural-requirement, relation-effect, knowledge-evidence,
|
||||
attestation, and `ContentRef` values. Enum values use their public string values. The
|
||||
installed decoder accepts only `FACT_PACK_SCHEMA`, re-encodes the typed value, and requires
|
||||
byte equality so alternate/unknown encodings cannot share authority. `authority.json`
|
||||
embeds policies and lineages because those values participate directly in the typed bundle;
|
||||
review evidence and disclosures remain immutable `ContentRef` values.
|
||||
|
||||
All referenced bytes live under `artifacts/sha256/<content_digest>`. The installed resolver
|
||||
validates the lowercase SHA-256 digest first and derives the filesystem basename solely from
|
||||
`ContentRef.content_digest`; `artifact_id` is diagnostic metadata and is never interpreted as
|
||||
a path. The resolver verifies byte length and digest, and derives
|
||||
the `StorageReceipt` from the bootstrap-admitted store identity
|
||||
`openultrasast-installed-entry-artifacts-v1`, the reference retention-policy digest, content
|
||||
digest, and length. Receipts are derived, not separately mutable files. Pack filenames are
|
||||
fixed by the closed authority schema; their typed normalized identities are covered by the
|
||||
bundle digest, so substituting either pack changes authority even though the filenames are
|
||||
not trust roots.
|
||||
|
||||
The approved repo-local ceremony records three distinct canonical identity manifests under
|
||||
schema `openultrasast.access-control.authority-identity.v1`. Every manifest has exactly
|
||||
`schema_version`, `role`, `name`, and `approval_basis`; its identity is the digest of its
|
||||
canonical bytes, and the loader rejects unknown fields or noncanonical bytes. The fixed rows
|
||||
are:
|
||||
|
||||
| File | `role` | `name` | `approval_basis` |
|
||||
|---|---|---|---|
|
||||
| `generator.json` | `producer` | `openultrasast-entry-pack-generator-v1` | `generated-from-reviewed-entry-data` |
|
||||
| `maintainer-reviewer.json` | `reviewer` | `openultrasast-maintainer` | `maintainer-session-approval:2026-11-01` |
|
||||
| `custodian.json` | `custodian` | `openultrasast-installed-entry-custodian-v1` | `checked-in-artifact-custody` |
|
||||
|
||||
The ceremony loader requires bootstrap reviewer admission to equal the reviewer-manifest
|
||||
digest, custody-policy admission to equal the custodian-manifest digest, authority review
|
||||
producer/reviewer identities to equal the generator/reviewer digests, and pack evidence to
|
||||
use the same producer/reviewer identities. The maintainer explicitly approved this ceremony
|
||||
on 2026-11-01; that approval authorizes recording the reviewer identity but does not let the
|
||||
generator choose a different reviewer. Bootstrap admits only that reviewer digest and the
|
||||
installed store identity. Producer and reviewer must differ, the pair remains subject to the
|
||||
forbidden-pair policy, conflict disclosures must be canonical and resolved, and any identity
|
||||
field or approval-basis change creates a new digest and invalidates these bindings until a
|
||||
new human review.
|
||||
|
||||
The structural adapter consumes promoted recognition output and repository structure. For
|
||||
each fact it emits the complete typed requirement set (qualified target, AST shape,
|
||||
receiver, call target, argument shape, or configuration as declared), persists every
|
||||
|
||||
@@ -316,10 +316,10 @@ missing authority, not an unread input or broken validator.
|
||||
4. **Compatibility:** existing regex rows remain a byte-stable recognition projection during
|
||||
migration. They are explicitly non-authoritative; exact typed observations are required
|
||||
for complete fact evidence.
|
||||
5. **Task routing:** access-control-prover tasks 14.1–14.6 define the family contract,
|
||||
authenticate authority, migrate reviewed data, persist evidence, match structure, and
|
||||
publish the conformance handoff. Detection-core task 9.4 then runs the target-neutral
|
||||
handoff-acceptance gate. Access-control-prover task 14.7 subsequently migrates the
|
||||
5. **Task routing:** access-control-prover tasks 14.1–14.8 define the family contract,
|
||||
authenticate authority, implement installed codecs/resolution, record the approved review
|
||||
ceremony, migrate reviewed data, persist evidence, match structure, and publish the
|
||||
conformance handoff. Detection-core task 9.4 then runs the target-neutral handoff-acceptance gate. Access-control-prover task 14.9 subsequently migrates the
|
||||
production caller and proves zero bypasses before detection-core task 10.2 cuts over.
|
||||
|
||||
### Risks and mitigations
|
||||
@@ -332,3 +332,19 @@ missing authority, not an unread input or broken validator.
|
||||
reference to core; the reference is never part of match-digest construction.
|
||||
- **Admission contamination:** bind fact and matcher lineages to current custody and the
|
||||
evaluation population so label access refuses the same run.
|
||||
|
||||
### Approved repo-local review ceremony (2026-11-01)
|
||||
|
||||
- The maintainer approved a repo-local ceremony after Task 14.3 correctly refused to invent
|
||||
its own independent reviewer. Generator, maintainer reviewer, and custodian are separate
|
||||
canonical identity manifests; the maintainer-reviewer manifest records the explicit
|
||||
session approval as its basis.
|
||||
- The bootstrap file admits the maintainer reviewer and installed content-addressed store;
|
||||
the authenticated authority file cannot modify either admission list.
|
||||
- Closed canonical decoders, fixed pack filenames, embedded policies/lineages, and a
|
||||
digest-addressed artifact directory make installed bytes reproducible. Storage receipts
|
||||
are derived from verified bytes and bootstrap-admitted store identity rather than stored
|
||||
as independently mutable claims.
|
||||
- This resolves the external identity decision but adds two prerequisite implementation
|
||||
units: wire decoders/resolver first, then the closed identity/bootstrap manifests, before
|
||||
the Express data migration.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"feature_name": "access-control-prover",
|
||||
"created_at": "2026-10-14T13:48:18Z",
|
||||
"updated_at": "2026-11-01T14:01:30Z",
|
||||
"updated_at": "2026-11-01T15:44:59Z",
|
||||
"language": "en",
|
||||
"phase": "tasks-generated",
|
||||
"approvals": {
|
||||
@@ -11,5 +11,5 @@
|
||||
},
|
||||
"ready_for_implementation": true,
|
||||
"depends_on": ["authorization-obligations", "valid-detection-benchmark", "hunter-learning-loop", "detection-core"],
|
||||
"approval_note": "2026-10-14 maintainer directive in session: spec the prover and queue implementation with Codex (fast-track; the three gates were passed on that instruction, review the documents before the second delivery). 2026-10-29: requirements amended after the 2026-10-28 gates 1-5 measurements (trace resolution, programmatic entry facts, failure visibility). 2026-10-29 (later): maintainer instruction in session ('can you address the issues?') treated as requirements approval and as the directive to regenerate the design. 2026-10-29 (capability lift): per-target vocabulary became acquired data; engine/target split, pattern discipline and complexity caps were recorded in steering; all phases reopened. 2026-10-29 (abstract-interpretation amendment): the maintainer accepted the design-review recommendations by asking to make the amendments. Requirements and design were regenerated with a three-way judgment, explicit evidence algebra, stable symbols, resource/authority domains, label-blind acquisition and separate admission measurement; that directive is recorded as approval to regenerate tasks. The merged task plan passed an independent task-graph sanity review after two design repairs. Tasks await human approval before implementation. 2026-10-29 (implementation start): the maintainer invoked /kiro-impl access-control-prover in session; that directive is recorded as tasks approval. 2026-11-01: maintainer approved moving the production fact authority, matcher and artifact writer from detection-core into access-control-prover; Requirement 13, design ownership and the repaired tasks 14.1-14.7 are approved for implementation."
|
||||
"approval_note": "2026-10-14 maintainer directive in session: spec the prover and queue implementation with Codex (fast-track; the three gates were passed on that instruction, review the documents before the second delivery). 2026-10-29: requirements amended after the 2026-10-28 gates 1-5 measurements (trace resolution, programmatic entry facts, failure visibility). 2026-10-29 (later): maintainer instruction in session ('can you address the issues?') treated as requirements approval and as the directive to regenerate the design. 2026-10-29 (capability lift): per-target vocabulary became acquired data; engine/target split, pattern discipline and complexity caps were recorded in steering; all phases reopened. 2026-10-29 (abstract-interpretation amendment): the maintainer accepted the design-review recommendations by asking to make the amendments. Requirements and design were regenerated with a three-way judgment, explicit evidence algebra, stable symbols, resource/authority domains, label-blind acquisition and separate admission measurement; that directive is recorded as approval to regenerate tasks. The merged task plan passed an independent task-graph sanity review after two design repairs. Tasks await human approval before implementation. 2026-10-29 (implementation start): the maintainer invoked /kiro-impl access-control-prover in session; that directive is recorded as tasks approval. 2026-11-01: maintainer approved moving the production fact authority, matcher and artifact writer from detection-core into access-control-prover; Requirement 13, design ownership and the repaired tasks are approved for implementation. 2026-11-01 (repo-local review ceremony): maintainer approved recording the generator as producer, maintainer session approval as reviewer basis, and the checked-in digest-addressed directory as trusted store; Tasks 14.3-14.4 implement the wire/resolver and ceremony records before data migration in Task 14.5."
|
||||
}
|
||||
|
||||
@@ -345,46 +345,59 @@ its final resolution, dominance, fact-acquisition and measurement semantics with
|
||||
- _Requirements: 13.2, 13.3_
|
||||
- _Boundary: Fact Authority_
|
||||
- _Depends: 14.1_
|
||||
- [ ] 14.3 Migrate the installed entry knowledge into reviewed v2 packs
|
||||
- [ ] 14.3 Implement installed authority codecs and resolver
|
||||
- Implement closed canonical JSON decoders for the bootstrap policy, installed authority, v2 fact packs, nested policies/lineages/evidence and immutable content references.
|
||||
- Implement the checked-in digest-addressed resolver using only validated `content_digest` for filesystem addressing and re-derivable storage receipts under an injected bootstrap-admitted store identity.
|
||||
- Done when canonical synthetic installed fixtures round-trip to Task 14.2 typed values and unknown/missing fields, noncanonical bytes, traversal-like artifact IDs, digest paths or byte substitutions fail before authentication.
|
||||
- _Requirements: 13.2, 13.3_
|
||||
- _Boundary: Installed Fact Authority Wire_
|
||||
- _Depends: 14.2_
|
||||
- [ ] 14.4 Record the approved repo-local review ceremony
|
||||
- Write the three closed canonical identity manifests with the exact schema, role, name and approval-basis values declared by the design.
|
||||
- Bind bootstrap reviewer admission, custody policy, authority review and pack evidence identities to those manifest digests while keeping all trust/store admission outside `authority.json`.
|
||||
- Done when the approved manifests and bootstrap load through Task 14.3, all identity bindings validate, and changing any field or approval basis invalidates authentication.
|
||||
- _Requirements: 13.2, 13.3_
|
||||
- _Boundary: Installed Authority Review Ceremony_
|
||||
- _Depends: 14.3_
|
||||
- [ ] 14.5 Migrate the installed entry knowledge into reviewed v2 packs
|
||||
- Produce one language-scoped v2 pack per promoted language and a separately authenticated canonical compatibility projection from the existing reviewed entry data.
|
||||
- Map every migrated row to declared roles, typed structural requirements and relation effects without adding target vocabulary to engine modules.
|
||||
- Preserve legacy pattern recognition byte-for-byte while preventing the projection from constructing detection-core evidence or readiness.
|
||||
- Done when legacy recognition fixtures are unchanged, both reviewed language packs validate under task 14.2 authority, and projection-only input remains non-authoritative.
|
||||
- _Requirements: 1.1, 1.5, 1.7, 2.9, 2.10, 13.2, 13.4_
|
||||
- _Boundary: Entry Knowledge Migration_
|
||||
- _Depends: 14.1, 14.2_
|
||||
- _Blocked: the approved plan does not define installed v2 JSON decoders, bundle-reference and content-store/receipt layouts, or independently supplied production producer, reviewer, custodian and trusted-store identities; generating all of them inside this task would self-authorize the authority_
|
||||
- [ ] 14.4 Add canonical structural-observation and fact-match persistence
|
||||
- _Depends: 14.1, 14.2, 14.3, 14.4_
|
||||
- [ ] 14.6 Add canonical structural-observation and fact-match persistence
|
||||
- Provide the downstream write boundary that persists canonical `StructuralObservation` bytes and returns immutable references through a read-only resolver.
|
||||
- Persist completed `fact_match_bytes` only after its observation references exist, then return the match reference without inserting a circular self-reference into the match digest.
|
||||
- Done when stored observation and match bytes resolve canonically and byte or reference substitution is refused deterministically.
|
||||
- _Requirements: 13.5_
|
||||
- _Boundary: Fact-Match Artifact Writer_
|
||||
- [ ] 14.5 Implement the authority-bearing structural matcher
|
||||
- [ ] 14.7 Implement the authority-bearing structural matcher
|
||||
- Build typed observations from repository structure for the requirements declared by the selected reviewed fact; do not infer missing structure from a regex or name hit.
|
||||
- Use task 14.4 to persist every observation and completed `FactMatchEvidence`, then pass the immutable match reference with family contract, policies, lineages, custody and read-only resolver to detection-core.
|
||||
- Use task 14.6 to persist every observation and completed `FactMatchEvidence`, then pass the immutable match reference with family contract, policies, lineages, custody and read-only resolver to detection-core.
|
||||
- Bind matcher behavior and fact lineage to current custody and the evaluation population so same-population label influence is incomplete or refused.
|
||||
- Done when complete fixtures apply the declared relations, while name-only, partial, ambiguous, substituted and contaminated fixtures cannot produce complete evidence.
|
||||
- _Requirements: 1.1, 1.2, 1.3, 1.5, 7.2, 9.4, 13.5, 13.6_
|
||||
- _Boundary: Structural Matcher_
|
||||
- _Depends: 14.2, 14.3, 14.4_
|
||||
- [ ] 14.6 Produce the downstream conformance handoff
|
||||
- _Depends: 14.2, 14.5, 14.6_
|
||||
- [ ] 14.8 Produce the downstream conformance handoff
|
||||
- Run detection-core fact-pack, fact-match, application and full-evidence validators over target-owned fixtures after proving nonzero fixture reads.
|
||||
- Publish an immutable manifest naming every fixture, artifact digest, validator result and negative-case reason for detection-core task 9.4 to accept; do not add target fixtures to core.
|
||||
- Exercise authority substitution, producer/reviewer conflict, resolver byte substitution, lineage omission, custody contamination and deterministic replay.
|
||||
- Done when the complete target-owned fixture passes, every incomplete/self-authored/substituted/contaminated/legacy-only variant is refused with a stable reason, and the immutable handoff manifest is reproducible.
|
||||
- _Requirements: 7.2, 7.4, 12.2, 12.3, 13.7_
|
||||
- _Boundary: Downstream Adapter Conformance Handoff_
|
||||
- _Depends: 14.5_
|
||||
- [ ] 14.7 Migrate the production entry caller and prove zero bypasses
|
||||
- _Depends: 14.7_
|
||||
- [ ] 14.9 Migrate the production entry caller and prove zero bypasses
|
||||
- Wire the externally bootstrapped authority-bearing adapter into the target-aware `mapping/legacy.py` entry path while keeping `analyze_entry_points` stable for its callers.
|
||||
- Retain the legacy projection only for compatibility recognition; prohibit it from supplying v2 evidence, readiness or admission.
|
||||
- Run import/caller and artifact-writer censuses proving no production path bypasses authority or treats legacy projection output as v2 evidence.
|
||||
- Done when existing entry recognition remains byte-stable, explicit v2 matching uses the reviewed persisted path, and both production bypass censuses are zero.
|
||||
- _Requirements: 1.1, 1.5, 1.7, 13.4, 13.7, 13.8_
|
||||
- _Boundary: Production Mapping Integration_
|
||||
- _Depends: 14.6_
|
||||
- _Blocked: detection-core task 9.4 must accept the immutable handoff from task 14.6 before production caller migration_
|
||||
- _Depends: 14.8_
|
||||
- _Blocked: detection-core task 9.4 must accept the immutable handoff from task 14.8 before production caller migration_
|
||||
|
||||
## Task constraints
|
||||
|
||||
@@ -396,7 +409,7 @@ its final resolution, dominance, fact-acquisition and measurement semantics with
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- Task 14.3: the 963-byte legacy entry file is readable, but typed authority validation is not an installed-artifact format. Migration requires a separately approved wire/storage contract and real independently supplied trust identities before checked-in artifacts can be called reviewed.
|
||||
- Task 14.3 planning: the 963-byte legacy entry file was readable, but typed authority validation was not an installed-artifact format. The maintainer approved the repo-local review ceremony; Tasks 14.3–14.4 now separate wire/resolver implementation from the identity/bootstrap records before Task 14.5 migrates data.
|
||||
|
||||
## Baseline implementation record
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"feature_name": "detection-core",
|
||||
"created_at": "2026-10-30T13:55:30Z",
|
||||
"updated_at": "2026-11-01T13:57:54Z",
|
||||
"updated_at": "2026-11-01T15:44:59Z",
|
||||
"language": "en",
|
||||
"phase": "tasks-generated",
|
||||
"approvals": {
|
||||
|
||||
@@ -334,7 +334,7 @@
|
||||
- _Requirements: 10.2, 10.4, 11.1, 11.2, 11.3, 11.4, 11.5, 13.4, 14.3_
|
||||
- _Boundary: Fact Pack Adapter Conformance_
|
||||
- _Depends: 5.4_
|
||||
- _Blocked: consume the handoff only after access-control-prover tasks 14.1–14.6 produce the downstream artifacts and immutable conformance manifest_
|
||||
- _Blocked: consume the handoff only after access-control-prover tasks 14.1–14.8 produce the downstream artifacts and immutable conformance manifest_
|
||||
- [ ] 9.5 (P) Produce readiness and development records through benchmark-owned adapters
|
||||
- Construct canonical readiness results while leaving sequencing and persistence with benchmark workflows.
|
||||
- Emit development observations with v2 identities, evidence-use roles, instrument receipts, and prerequisite ancestry.
|
||||
@@ -368,7 +368,7 @@
|
||||
- Done when no production writer/import targets the v1 contract, historical fixtures remain unchanged, and all public writes use v2.
|
||||
- _Requirements: 14.3, 15.3_
|
||||
- _Depends: 9.4_
|
||||
- _Blocked: access-control-prover task 14.7 must migrate the production caller and prove a zero-bypass census after task 9.4 accepts the handoff_
|
||||
- _Blocked: access-control-prover task 14.9 must migrate the production caller and prove a zero-bypass census after task 9.4 accepts the handoff_
|
||||
|
||||
- [ ] 11. Validate readiness, failure visibility, and implementation boundaries
|
||||
- [ ] 11.1 Run both reference families through the complete synthetic readiness path
|
||||
|
||||
Reference in New Issue
Block a user