WS-AUTH-001-PREP: add prepared mutation authorization protocol

[Abiorh001]

WS-AUTH-001-PREP PR Trust Bundle

Chunk

WS-AUTH-001-PREP - Prepared Mutation Authorization Protocol (L1).

Goal And Human-Approved Intent

Provide one kernel-owned, single-use authorization preparation protocol for
mutation services that must lock authority before locking and changing their
product resource. The user explicitly asked to plan and fix consume() end to
end, while keeping the full suite on GitHub because the local machine is slow.

What Changed And Why

• Adds typed prepared input and authority scope plus an opaque, nonserializable,
  single-use handle.
• Makes the authorization kernel acquire canonical authority locks, derive all
  facts, seal authority to the exact service/session/root transaction, and
  register the only valid consumption capability.
• Requires the participant to consume inside the same transaction after its
  product lock; one shared AUTH completion path records the canonical decision
  and evidence. The participant command retains ownership of durable
  idempotency.
• Adds a FastAPI dependency that owns rollback on denial or failure and never
  stages or commits product state itself.
• Adds focused and real-PostgreSQL proof for all supported actions, both race
  orders, replay/forgery/substitution attacks, transaction failures, timeouts,
  cancellation, and the sole eligible administrative grant invariant.

This protocol was chosen to preserve the established authority-first lock
order without handing callers reusable or caller-constructed authorization
facts. A serializable token, public prelocked context, caller-provided grant,
or second authorization path would weaken the trust boundary and was rejected.

Scope And Product Behavior

The chunk adds authorization infrastructure and tests only. It activates no
planned action, changes no permission or role, adds no route-level product
consumer, performs no product mutation, and adds no migration. Ordinary
require() behavior remains unchanged.

Acceptance Proof And Test Delta

• Ruff passed for the backend application/tests and for all final changed
  modules.
• 18 focused non-database PREP cases pass locally.
• PostgreSQL tests cover successful atomic mutation, rollback and commit
  failures, authorization denial, evidence failure, timeout, cancellation,
  double consumption, supported lifecycle/admin races in both lock orders, and
  database enforcement of the sole eligible grant invariant.
• Stale wording, Markdown links, loop-memory, merge-intent, and diff checks pass.
• No test, assertion, threshold, workflow, dependency, or coverage source was
  removed or weakened. GitHub Backend remains the authoritative full-suite gate
  for the 78 percent global and 90 percent changed-subsystem floors.

Internal Review And CI Integrity

Final reviewed sync SHA 6c1e296fca8390aeeed9f5bdf63b649a783c5030, containing
implementation 38acb8f91d3ddd2edd4cc26fb1e36b67fa130fd9, against trusted main
c12ba1c8d4bbde86d0e2c19826f5791afc130489 passes senior engineering,
QA/test, security/auth, product/ops, architecture, CI integrity, docs,
reuse/dedup, and test-delta review after safety repairs and trusted-main sync.
No CI configuration, coverage threshold, dependency, or migration changed.

External Review And Remaining Risks

GitHub Backend, Agent Gates, and CodeRabbit remain pending until publication.
The primary remaining risk is an unforeseen transaction/cancellation behavior
under the hosted PostgreSQL matrix; the full hosted suite is the required gate.
Product integration risk is intentionally deferred because this chunk has no
consumer.

Follow-Up And Human Review Focus

The same-initiative successor is WS-AUTH-001-10, Project Qualification And
Contributor Role Grants. Human review should focus on the service-private
consumer capability, exact context/root-transaction binding, authority-first
lock order, terminal handle invalidation, cancellation rollback, real-service
race proof, absence of a product consumer/migration, and the database-backed
sole-grant invariant.

Human Merge Ownership

The agent may publish and repair this branch but may not merge it. Only the
human may approve this PR for merge. Trusted-main automation owns signed
post-merge memory generation.

Summary by CodeRabbit

• New Features
  • Added a transaction-bound, single-use prepared authorization flow for supported self-service and administrative mutations, with strict scope/request binding and consume-time validation.
• Bug Fixes
  • Improved request lifecycle handling so prepared authorization handles are properly closed and rolled back correctly when requests end early.
• Documentation
  • Expanded the authorization service docs with the PREP protocol contract, supported authority scopes, rollback/evidence behavior, and lock-order/limitations.
• Tests
  • Added end-to-end, concurrency, cancellation/rollback, double-consumption, and mismatch/forgery protection coverage (including PostgreSQL atomicity/real-db cases).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 11ecb409-3858-4883-b3a7-015f51bd29b8

📥 Commits

Reviewing files that changed from the base of the PR and between 8a705e5 and 917e920.

📒 Files selected for processing (5)

• .agent-loop/REVIEW_LOG.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-external-review-response.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-internal-review-evidence.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-pr-trust-bundle.md
• backend/tests/test_authorization.py

🚧 Files skipped from review as they are similar to previous changes (4)

• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-pr-trust-bundle.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-internal-review-evidence.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-external-review-response.md
• backend/tests/test_authorization.py

---

📝 Walkthrough

Walkthrough

Adds a transaction-bound, single-use prepared authorization protocol with canonical locking, strict request/session binding, rollback semantics, API dependency wiring, PostgreSQL race tests, and documentation. No product consumer or migration is added.

Changes

Prepared Authorization

Layer / File(s)	Summary
PREP contracts and scope .agent-loop/..., backend/app/modules/authorization/runtime.py, docs/..., .agent-loop/merge-intents/*	Defines prepared input and scope schemas, supported mutation boundaries, acceptance criteria, transaction semantics, lock ordering, and workflow metadata.
Prelocked authority and handle lifecycle backend/app/modules/authorization/kernel.py, backend/app/modules/authorization/prepared.py, backend/app/modules/authorization/repository.py	Adds canonical authority prelocking, immutable sealed facts, opaque single-use handles, strict transaction/request binding, prepared evaluation, and actor-self locking.
Request dependency composition backend/app/api/deps/authorization.py	Adds prepared-service dependency composition, repository injection, rollback handling, and guaranteed service cleanup.
Integration validation and review evidence backend/tests/test_authorization.py, .agent-loop/.../reviews/*, .agent-loop/REVIEW_LOG.md	Adds unit and PostgreSQL coverage for handle security, rollback, cancellation, concurrency, race ordering, scope validation, uniqueness, and dependency teardown; records review evidence and hosted-test repair status.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant PreparedAuthorizationService
  participant AuthorizationService
  participant PostgreSQL
  Caller->>PreparedAuthorizationService: prepare(...)
  PreparedAuthorizationService->>AuthorizationService: prelock authority
  AuthorizationService->>PostgreSQL: lock canonical rows
  PostgreSQL-->>AuthorizationService: locked facts
  AuthorizationService-->>PreparedAuthorizationService: sealed authority
  PreparedAuthorizationService-->>Caller: single-use handle
  Caller->>PreparedAuthorizationService: consume(...)
  PreparedAuthorizationService->>AuthorizationService: evaluate prelocked authority
  AuthorizationService-->>Caller: AuthorizationDecision

Loading

Possibly related PRs

• Flow-Research/workstream#126: Added shared action catalogue and action-evidence foundations used by prepared authorization.
• Flow-Research/workstream#131: Established authorization and administrative grant plumbing extended by the prepared flow.
• Flow-Research/workstream#157: Modified shared authorization kernel and service-context revalidation surfaces.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding the WS-AUTH-001-PREP prepared mutation authorization protocol.
Description check	✅ Passed	It covers the required PR bundle sections at a high level, but should add the explicit merge-intent line and more template-shaped evidence/review tables.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-auth-001-prep

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
@.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-pr-trust-bundle.md:
- Around line 59-76: Clarify the external-review status in the “External Review
And Remaining Risks” section: do not present Agent Gates and CodeRabbit as
validating merge candidate 9e926d04511e04122beeb1f88110f80b88c34907 unless their
results are tied to that exact repaired SHA or run. Otherwise mark the exact-SHA
repair review and hosted Backend rerun as pending, while preserving the existing
fixture-repair risk details.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d64c773b-4f76-491e-ae6e-cab19d25dc4b

📥 Commits

Reviewing files that changed from the base of the PR and between 479d3a3 and 8a705e5.

📒 Files selected for processing (5)

• .agent-loop/REVIEW_LOG.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-external-review-response.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-internal-review-evidence.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-PREP-pr-trust-bundle.md
• backend/tests/test_authorization.py

🚧 Files skipped from review as they are similar to previous changes (1)

• backend/tests/test_authorization.py

[Abiorh001]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.