feat(auth): add privacy-safe project role reads

[Abiorh001]

Workstream PR Trust Bundle

Chunk

WS-AUTH-001-10B2 - Privacy-Safe Project Role Grant Reads

Merge intent: .agent-loop/merge-intents/WS-AUTH-001-10B2.json

Goal

Expose privacy-safe contributor-candidate and immutable project-role-grant reads through exactly three authenticated, rate-controlled project actions.

Human-Approved Intent

• Intent: .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/INTENT.md
• Chunk contract: .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-10B2-project-role-grant-reads.md

The user explicitly started this signed successor after 10B1 merged. Signed loop memory binds it to trusted main 14fa4316.

What Changed

• Added three project read routes for contributor candidates and role grants.
• Added strict signed keyset cursors, count-free minimal schemas, repository queries, typed authorization contexts, kernel guards, and action-aware concealment.
• Added PostgreSQL, OpenAPI, configuration, focused, audit-parity, and hosted API proof.
• Added operational/specification documentation and exactly one merge intent naming 10C as an explicit-start successor.

Why It Changed

Project managers and auditors need bounded authorization reads without disclosing identity-link facts, private identity data, row existence, or grant history outside their scope.

Design Chosen

Authorization runs before cursor or private-row lookup. One durable rate consumption precedes nonhuman concealment. Candidate lifecycle remains a kernel guard; grant history remains readable in every project state. HMAC-SHA256 keyset cursors bind action, project, filters, limit, ordering, timestamp, and UUID.

Alternatives Rejected

• Offset pagination and total counts, because they leak cardinality and do not provide stable progression.
• Reusing authentication or rate-limit secrets, because cursor signing requires independent rotation and blast-radius control.
• Filtering sensitive rows before authorization, because timing and existence could leak.

Scope Control

Allowed Files Changed

• Only files listed by the reviewed 10B2 chunk contract and its two narrow test-file amendments.

Files Outside Contract

• None.

No migration, workflow, dependency, PREP, mutation, frontend, or AUTH-10C implementation is included.

Product Behavior

• Product behavior changed: three exact privacy-safe project authorization read operations are activated.

Evidence

Commands Run

pytest backend/tests/test_config.py
pytest <focused cursor/rate/kernel/read-service selection>
pytest <isolated PostgreSQL candidate/grant selection>
ruff check backend/app backend/tests backend/scripts
python -m compileall backend/app backend/scripts/api_contract_e2e.py
gh run view 29892395881

Result Summary

148 configuration tests passed
42 focused cursor/rate/kernel/read-service tests passed
2 isolated PostgreSQL candidate/grant tests passed
Exact OpenAPI inventory passed
Ruff and compileall passed
Repository docstring coverage: 87.6% (80% floor)
Agent Gates passed
Hosted API E2E passed after project-scoped authority repair
GitHub full shards and aggregate coverage are the final CI authority

Acceptance Criteria Proof

• Exactly three routes/actions activated; 10C remains planned.
• Independent canonical Base64 32-byte cursor secret fails closed at startup.
• Authorization, rate, concealment, cursor binding, project scope, filtering, keyset progression, and no-count behavior are tested.
• Responses exclude identity-link, issuer/subject, contact, claims, totals, and keys.
• No migration or mutation/PREP behavior changed.

Test Delta

Tests Added

• Cursor integrity and startup-secret tests.
• Authorization ordering, concealment, kernel, repository, schema, PostgreSQL pagination, and hosted API tests.

Tests Modified

• Exact OpenAPI/protected-action inventory and closed audit active-action set were strengthened for the three activations.

Tests Removed Or Skipped

• None.

Internal Reviewer Results

Reviewed code SHA: 95c3ecf77afed2746a66f314d05eb547cfa15f3c

Reviewed at: 2026-07-22T04:55:55Z

Reviewer run IDs: /root/auth10b1_final_core, /root/auth10b1_final_security_qa, /root/auth10b1_final_ops_docs_ci

Reviewer	Result	Blocking Findings	Notes
Senior engineering	PASS AFTER FIXES	None	Exact repair SHA reviewed
QA/test	PASS AFTER FIXES	None	Exact repair SHA reviewed
Security/auth	PASS AFTER FIXES	None	Exact repair SHA reviewed
Product/ops	PASS AFTER FIXES	None	Exact repair SHA reviewed
Architecture	PASS AFTER FIXES	None	Exact repair SHA reviewed
CI integrity	PASS AFTER FIXES	None	Exact repair SHA reviewed
Docs	PASS AFTER FIXES	None	Exact repair SHA reviewed
Reuse/dedup	PASS AFTER FIXES	None	Exact repair SHA reviewed
Test delta	PASS AFTER FIXES	None	Exact repair SHA reviewed

No reviewer sessions remain open.

External Review

External review response: no actionable CodeRabbit inline comment exists on the current head; its latest run was rate-limited.

Source	Status	Notes
CodeRabbit	Rate-limited	No actionable inline findings; description warning addressed here; CI proves 87.6% docstrings
GitHub checks	PASS	Agent Gates, hosted E2E, all four shards, aggregate test, 78% global coverage, and 90% authorization coverage pass

CI And Gate Integrity

• No workflow weakening.
• No lint/test/docstring gate weakening.
• No coverage threshold weakening.
• No package script weakening.
• No unpinned new GitHub Action.
• Checkout credential persistence remains governed by unchanged workflows.

Remaining Risks

The authorization and privacy blast radius is L1. Full GitHub shard and aggregate coverage proof is green. CodeRabbit's displayed 37.61% is inconsistent with the unchanged repository CI command, which passes at 87.6%.

Follow-Up Work

AUTH-10C is only a declared same-initiative successor and requires a fresh explicit signed start after this PR merges.

Human Review Focus

Please inspect authorization ordering, Project Manager/Audit scope and lifecycle boundaries, cursor binding, response minimization, identical concealment, and the exact three-action activation.

Human Merge Ownership

• I can explain what changed.
• I can explain why it changed.
• I know what could break.
• I accept the remaining risks.
• The user explicitly approved this specific PR for merge.

Do not merge without the user's explicit approval of PR #178.

Summary by CodeRabbit

• New Features
  • Added project authorization read APIs for contributor candidates and project role grant history (list and detail), with filtering and count-free keyset pagination using signed cursors.
  • Promoted the three project role read actions to active availability, reflected in API inventory.
• Documentation
  • Documented the new endpoints, response shapes, cursor requirements, and shared 404/error behavior.
• Bug Fixes
  • Strengthened privacy and ordering guarantees: non-human/unauthorized access is concealed before project lookup, with consistent handling of invalid or replayed cursors.

[coderabbitai]

📝 Walkthrough

Walkthrough

AUTH-10B2 adds three project authorization read endpoints for contributor candidates and role grants. It introduces signed keyset pagination, human-only rate-gated authorization, filtered repository reads, strict response schemas, startup secret validation, API contract tests, and rollout documentation.

Changes

Project authorization read rollout

Layer / File(s)	Summary
Cursor, settings, and read contracts backend/app/core/config.py, backend/app/main.py, backend/app/modules/authorization/pagination.py, backend/app/modules/authorization/runtime.py, backend/app/modules/authorization/schemas.py	Adds required 32-byte cursor HMAC secret handling, strict signed cursors, project resource contexts, and count-free paginated response schemas.
Authorization activation and concealment backend/app/api/deps/authorization.py, backend/app/modules/authorization/catalogue.py, backend/app/modules/authorization/kernel.py	Activates three project read actions, routes them through admin authorization, enforces human-only rate-gated access, and maps denied reads to concealed 404 responses.
Repositories, service, and routes backend/app/modules/actors/repository.py, backend/app/modules/authorization/repository.py, backend/app/modules/authorization/read_service.py, backend/app/modules/authorization/router.py	Adds candidate and grant keyset queries, authorized read orchestration, qualification snapshot mapping, and three project GET endpoints.
Database, API, and security verification backend/tests/*, backend/scripts/api_contract_e2e.py	Validates cursor integrity, startup secret behavior, authorization ordering, PostgreSQL pagination, OpenAPI inventories, response shapes, filtering, and concealed missing-resource behavior.
Rollout contract and review records .agent-loop/..., docs/operations_authorization_service.md, docs/spec_authorization_service.md	Updates AUTH-10B2 contracts, review evidence, trust records, merge intent, action totals, endpoint documentation, and rollout constraints.

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

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant authorization_router
  participant enforce_human_authorization_read
  participant ProjectRoleReadService
  participant AdminAuthorizationRepository
  Client->>authorization_router: Request project read
  authorization_router->>enforce_human_authorization_read: Apply rate and human-subject gates
  authorization_router->>ProjectRoleReadService: Resolve authorized read
  ProjectRoleReadService->>AdminAuthorizationRepository: Query candidates or grants
  AdminAuthorizationRepository-->>ProjectRoleReadService: Return paginated rows
  ProjectRoleReadService-->>Client: Return typed response or concealed error

Loading

Possibly related PRs

• Flow-Research/workstream#126: Updates the shared action catalogue and audit parity used by this activation.
• Flow-Research/workstream#131: Extends the authorization kernel and admin authorization routing used by these project read actions.
• Flow-Research/workstream#170: Provides related project-role grant authorization and audit groundwork.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly matches the main change: adding privacy-safe project role reads.
Description check	✅ Passed	The description covers the required template sections, including intent, scope, evidence, test delta, reviews, and risks.

✨ 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-10b2-project-role-grant-reads

---

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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-10B2-project-role-grant-reads.md (1)

221-226: 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Split the 503 ordering rule. Keep lines 221-226 limited to the pre-admission/rate-gate 429/503 path. The evidence-persistence 503 in 238-243 is a separate post-decision failure mode and shouldn’t be folded into the same “before the identical nonhuman 404” guarantee; define separate ordering or narrow the wording.

🤖 Prompt for 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.

In
@.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-10B2-project-role-grant-reads.md
around lines 221 - 226, The dependency-precedence statement around “verified
token” and “exhausted 429 or private retryable 503” must cover only
pre-admission/rate-gate failures. Narrow that wording so the
evidence-persistence 503 described later is explicitly treated as a separate
post-decision failure mode, without applying the “before the identical nonhuman
404” ordering guarantee to it.

🤖 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.

Outside diff comments:
In
@.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-10B2-project-role-grant-reads.md:
- Around line 221-226: The dependency-precedence statement around “verified
token” and “exhausted 429 or private retryable 503” must cover only
pre-admission/rate-gate failures. Narrow that wording so the
evidence-persistence 503 described later is explicitly treated as a separate
post-decision failure mode, without applying the “before the identical nonhuman
404” ordering guarantee to it.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ac2a18bc-c229-4673-a2d1-e88a878888c0

📥 Commits

Reviewing files that changed from the base of the PR and between 5365f19 and 7dbff62.

📒 Files selected for processing (7)

• .agent-loop/REVIEW_LOG.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-10B2-project-role-grant-reads.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-10B2-external-review-response.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-10B2-internal-review-evidence.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-10B2-pr-trust-bundle.md
• backend/scripts/api_contract_e2e.py
• backend/tests/test_audit.py

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

• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-10B2-internal-review-evidence.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-10B2-pr-trust-bundle.md
• backend/scripts/api_contract_e2e.py