From 4db83ec26fd0e93ffcbd20f6ac5ae3d285b6a7ee Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sun, 2 Aug 2026 11:06:20 +0100 Subject: [PATCH 1/2] docs(auth): harden guide binding activation contract --- .../DISCOVERY.md | 28 +++++++++++++ ...T-002-04B-guide-read-binding-activation.md | 42 ++++++++++++++++--- ...S-XINT-002-04B-preimplementation-review.md | 38 +++++++++++++++++ 3 files changed, 103 insertions(+), 5 deletions(-) create mode 100644 .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/DISCOVERY.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/DISCOVERY.md index dff29a61a..505b691c8 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/DISCOVERY.md @@ -117,3 +117,31 @@ fencing proof is spread across artifact admission, verification, and recovery suites, so the corrected contract names the actual tests and permits a new focused activation test module rather than assuming a pre-existing file. + +## WS-XINT-002-04B preimplementation reconciliation + +- Trusted `main` at `9618b938c213a98e33772c04185a6e5d6b8c35f8` + contains the complete hidden ART-03B1 through ART-03B4 guide binding, + verified materialization, classification, extraction, and sufficiency + pipeline required by the 04B entry gate. +- `artifact.guide_source.binding.create` and `artifact.guide_source.read` + already exist in the closed catalogue with their correct permissions and + fixed service-matrix memberships, but both remain `planned` and retain the + historical `WS-AUTH-001-ART-03` owner. This is the observed preimplementation + state; the reviewed 04B acceptance criteria require replacing that owner with + `WS-XINT-002-04B` when the two actions activate. +- `GuideSourceBindingAuthorityFacts` and `GuideSourceReadAuthorityFacts` + already carry the exact reviewed ART resource manifests. The feature + services lock and validate canonical ART/project lineage before calling + their authorization seams. +- Production binding and read seams remain intentionally fail-closed through + `DenyGuideSourceBindingPreparedAuthorization` and + `DenyGuideSourceReadPreparedAuthorization`. Existing tests use test-only + allow adapters; no production 04B adapter is composed yet. +- The shared `PreparedAuthorizationHandle` and fixed-service PREP kernel must + be extended, not replaced. The implementation must activate only the two + guide actions, preserve process-local single-use handles, and keep all + Celery messages identifier-only. +- ART-03C remains blocked until 04B merges. XINT-003 policy mutation work is + independent but is not the immediate cross-initiative dependency while ART + is waiting for guide binding/read activation. diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md index 3fa4ad69a..eebc87860 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md @@ -2,8 +2,9 @@ ## Goal -Activate fixed-service guide binding and guide-read actions only after merged ART-03B1, -03B2, 03B3A, 03B3B, and 03B4 evidence, without weakening ART-03C. +Activate fixed-service guide binding and guide-read actions only after merged +ART-03B1, 03B2, 03B3A, 03B3B1, 03B3B2, 03B3B3A, 03B3B3B, 03B3B3C, +03B3B3D, 03B3B4, and 03B4 evidence, without weakening ART-03C. ## Risk class @@ -26,6 +27,7 @@ backend/app/modules/authorization/runtime.py backend/app/modules/artifacts/authorization.py backend/tests/test_authorization.py backend/tests/test_guide_artifacts.py +backend/tests/test_guide_bindings.py docs/spec_authorization_service.md docs/spec_artifact_storage_service.md .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-internal-review.md @@ -37,7 +39,8 @@ docs/spec_artifact_storage_service.md Human ingest behavior, ART byte/admission implementation, project lifecycle changes, submission/review behavior, provider redesign, token roles, generic -guide download, new catalogue values, or ART-03C legacy removal. +guide download, new ActionId or PermissionId values, worker/Celery payload or +orchestration changes, production route composition, or ART-03C legacy removal. This contract, the chunk map, and other planning files are not editable by the 04B implementation PR; any required scope change returns to planning review. @@ -48,6 +51,28 @@ This contract, the chunk map, and other planning files are not editable by the source item, and setup generation. - `artifact.guide_source.read` is available only to the fixed guide-reader identity for the exact bound guide content and setup generation. +- Catalogue ownership for both actions is reconciled from the obsolete + `WS-AUTH-001-ART-03` label to `WS-XINT-002-04B`; no alias, duplicate action, + PermissionId, or second activation path is retained. +- AUTH adds two closed typed resource contexts and extends only the existing + `PreparedAuthorizationService`, `_scope_from_resource`, and kernel service + branch. The guide actions must not reuse or broaden the generic put, + verification-job, or pending-work resource selectors. +- Binding authorization binds exactly `project_id`, `guide_id`, + `guide_source_snapshot_id`, `guide_source_item_id`, + `project_setup_run_id`, `setup_generation`, `content_id`, + `verified_replica_id`, `sha256`, `byte_count`, and fixed + `logical_role=guide_source_original`. +- Read authorization binds exactly `project_id`, `guide_id`, + `guide_source_snapshot_id`, `guide_source_item_id`, + `project_setup_run_id`, `setup_generation`, `binding_id`, `content_id`, + `verified_replica_id`, `storage_namespace_id`, `namespace_fingerprint`, + `verification_receipt_id`, `verification_generation`, `sha256`, + `byte_count`, and `media_type`. +- The production AUTH adapters are implemented in + `backend/app/modules/artifacts/authorization.py`. ART-03C owns the later live + worker/route composition and legacy cutover; 04B neither serializes a handle + nor changes Celery orchestration. - Both actions require exact prepared-authority validation and single-use consumption before any provider read or binding write. Stale, replayed, revoked, mismatched, cross-session, cross-action, or cross-resource authority @@ -56,6 +81,12 @@ This contract, the chunk map, and other planning files are not editable by the in the caller-owned root transaction before later provider reads. - Replaced binding, stale setup generation, wrong identity, cross-guide, cross-project, replay, and revoked service authority deny atomically. +- Copied handles and mismatched snapshot, item, setup run, generation, binding, + content, replica, namespace, namespace fingerprint, receipt, verification + generation, digest, size, media type, or logical role deny before provider + access or protected mutation and create no allowed decision evidence. +- Prepared handles remain opaque, process-local, transaction-bound, and absent + from Celery messages, logs, Pydantic models, and other serialization surfaces. - No generic artifact-download permission or human-to-service authority inheritance is introduced. - ART-03C remains a separate clean-cut gate. @@ -64,7 +95,7 @@ This contract, the chunk map, and other planning files are not editable by the ```bash (cd backend && .venv/bin/python -m ruff check app tests scripts) -(cd backend && WORKSTREAM_TEST_DATABASE_URL= .venv/bin/pytest tests/test_authorization.py tests/test_guide_artifacts.py -q --cov=app.modules.authorization --cov=app.modules.artifacts --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) +(cd backend && WORKSTREAM_TEST_DATABASE_URL= .venv/bin/pytest tests/test_authorization.py tests/test_guide_artifacts.py tests/test_guide_bindings.py -q --cov=app.modules.authorization --cov=app.modules.artifacts --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) python3 scripts/check_stale_authorization_docs.py python3 scripts/check_stale_artifact_contracts.py python3 scripts/check_markdown_links.py @@ -81,4 +112,5 @@ integrity, docs, reuse/dedup, and test delta. ## Human review focus Separate fixed identities, exact verified-content and generation binding, -least privilege, and preservation of the ART-03C clean cut. +least privilege, complete mismatch/no-I/O proof, and preservation of the +ART-03C clean cut. diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md new file mode 100644 index 000000000..f44b4b1ca --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md @@ -0,0 +1,38 @@ +# Preimplementation Review: WS-XINT-002-04B + +## Initial result + +Security, architecture, and QA returned `FAIL` against the original contract. +The direction was correct, but the contract did not enumerate the exact guide +binding/read resource facts, explicitly require closed AUTH resource contexts, +include the guide-binding behavior tests, or distinguish AUTH adapter delivery +from ART-03C live composition. + +## Corrections + +- Replaced the obsolete aggregate ART predecessor with the complete split-03B + merge list. +- Enumerated every binding and read resource fact from the merged ART handoff. +- Required two closed typed AUTH resource contexts and exact PREP/kernel + consume-time binding without broadening generic ART-internal selectors. +- Added copied, replayed, cross-session, cross-action, cross-service, + cross-resource, stale-lineage, and field-level mismatch denial proof before + provider I/O or protected mutation. +- Required handles to remain process-local and absent from Celery and all + serialization surfaces. +- Added `backend/tests/test_guide_bindings.py` to allowed scope and verification. +- Assigned production AUTH adapter delivery to 04B while retaining worker, + route, orchestration, and legacy cutover ownership in ART-03C. +- Required the obsolete `WS-AUTH-001-ART-03` owner label to be replaced by + `WS-XINT-002-04B` without aliases or duplicate action paths. + +## Final result + +- Security: `PASS`; no remaining blockers. +- QA/test: `PASS`; no missing blocking criteria. +- Architecture: `PASS WITH LOW RISKS`; no boundary or composition blocker. + The only wording observation about current versus future owner state was + clarified in discovery. + +The corrected contract is ready for human review. Runtime implementation must +not begin until this planning amendment merges. From fcfe04f6029959b835af668f5681e36acc872f91 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sun, 2 Aug 2026 11:23:37 +0100 Subject: [PATCH 2/2] docs(auth): resolve 04B external review --- .../REVIEW_LOG.md | 12 +++++++ ...T-002-04B-guide-read-binding-activation.md | 6 ++-- ...S-XINT-002-04B-external-review-response.md | 32 +++++++++++++++++++ ...S-XINT-002-04B-preimplementation-review.md | 2 +- 4 files changed, 48 insertions(+), 4 deletions(-) create mode 100644 .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-external-review-response.md diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/REVIEW_LOG.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/REVIEW_LOG.md index 04418fc3b..f2083cf9d 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/REVIEW_LOG.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/REVIEW_LOG.md @@ -36,3 +36,15 @@ claim/terminal capability consumption, terminal-only authority drift, and the accurate active custody-table header. The isolated four-test PostgreSQL rerun and QA, test-delta, and CI-integrity re-reviews passed. Details are in `reviews/WS-XINT-002-03-external-review-response.md`. + +## WS-XINT-002-04B planning amendment + +Preimplementation security, architecture, and QA review rejected the original +04B contract until it enumerated the exact guide binding/read manifests, closed +PREP resource contexts, fixed-service mismatch proof, no-I/O ordering, and the +ART-03C composition boundary. All three tracks passed after correction. + +PR #243 external review found one shell-invalid database placeholder and Agent +Gates found two unqualified background-executor terms. Both were valid and corrected without +changing the authorization boundary. The exact response is recorded in +`reviews/WS-XINT-002-04B-external-review-response.md`. diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md index eebc87860..053328b4e 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md @@ -39,7 +39,7 @@ docs/spec_artifact_storage_service.md Human ingest behavior, ART byte/admission implementation, project lifecycle changes, submission/review behavior, provider redesign, token roles, generic -guide download, new ActionId or PermissionId values, worker/Celery payload or +guide download, new ActionId or PermissionId values, Celery task payload or orchestration changes, production route composition, or ART-03C legacy removal. This contract, the chunk map, and other planning files are not editable by the 04B implementation PR; any required scope change returns to planning review. @@ -71,7 +71,7 @@ This contract, the chunk map, and other planning files are not editable by the `byte_count`, and `media_type`. - The production AUTH adapters are implemented in `backend/app/modules/artifacts/authorization.py`. ART-03C owns the later live - worker/route composition and legacy cutover; 04B neither serializes a handle + Celery task/route composition and legacy cutover; 04B neither serializes a handle nor changes Celery orchestration. - Both actions require exact prepared-authority validation and single-use consumption before any provider read or binding write. Stale, replayed, @@ -95,7 +95,7 @@ This contract, the chunk map, and other planning files are not editable by the ```bash (cd backend && .venv/bin/python -m ruff check app tests scripts) -(cd backend && WORKSTREAM_TEST_DATABASE_URL= .venv/bin/pytest tests/test_authorization.py tests/test_guide_artifacts.py tests/test_guide_bindings.py -q --cov=app.modules.authorization --cov=app.modules.artifacts --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) +(cd backend && WORKSTREAM_TEST_DATABASE_URL="${WORKSTREAM_TEST_DATABASE_URL:?Set WORKSTREAM_TEST_DATABASE_URL}" .venv/bin/pytest tests/test_authorization.py tests/test_guide_artifacts.py tests/test_guide_bindings.py -q --cov=app.modules.authorization --cov=app.modules.artifacts --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) python3 scripts/check_stale_authorization_docs.py python3 scripts/check_stale_artifact_contracts.py python3 scripts/check_markdown_links.py diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-external-review-response.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-external-review-response.md new file mode 100644 index 000000000..a9fe1faa1 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-external-review-response.md @@ -0,0 +1,32 @@ +# External Review Response: WS-XINT-002-04B Planning Amendment + +## Comments addressed + +- CodeRabbit correctly identified that the verification command's `` + placeholder is parsed by the shell as redirection. The command now requires + and reuses an existing `WORKSTREAM_TEST_DATABASE_URL` value through an + executable shell expansion. +- Agent Gates correctly rejected two unqualified background-executor references. They now use + the exact technical terms `Celery task payload` and `Celery task/route + composition`, preserving the separation from Workstream's human contributor + vocabulary. + +## Comments deferred + +None. + +## Human decisions needed + +Human review and merge of the corrected 04B security boundary remain required. + +## Commands rerun + +- `python3 scripts/check_stale_authorization_docs.py` +- `python3 scripts/check_stale_artifact_contracts.py` +- `python3 scripts/check_markdown_links.py` +- `git diff --check` + +## Remaining risks + +No runtime action is activated by this planning amendment. Exact-head Agent +Gates, Backend, and CodeRabbit must pass before merge. diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md index f44b4b1ca..b2bd3f263 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-preimplementation-review.md @@ -21,7 +21,7 @@ from ART-03C live composition. - Required handles to remain process-local and absent from Celery and all serialization surfaces. - Added `backend/tests/test_guide_bindings.py` to allowed scope and verification. -- Assigned production AUTH adapter delivery to 04B while retaining worker, +- Assigned production AUTH adapter delivery to 04B while retaining Celery task, route, orchestration, and legacy cutover ownership in ART-03C. - Required the obsolete `WS-AUTH-001-ART-03` owner label to be replaced by `WS-XINT-002-04B` without aliases or duplicate action paths.