Add identity-link lifecycle authorization

[Abiorh001]

Summary

• Add centralized, idempotent identity-link revoke/reactivate APIs for effective system Access Administrators.
• Preserve authorization-before-disclosure, final-admin safety, canonical lock ordering, privacy-safe evidence, caller-only timestamp updates, and atomic rollback.
• Activate exactly two actions; the catalogue is 65 actions with 17 active and 48 planned.
• Reconcile the AUTH sequence so the inactive contributor foundation follows 09D-B, while AUTH-13/14 consume its contributor_id fields instead of renaming them later.

Scope

No migration, fixed-service admission, grant restoration, feature action activation, compatibility path, or successor implementation is included. The contributor foundation remains inactive until this PR merges, signed memory passes, and the user explicitly starts it.

Verification

• 2 mandatory PostgreSQL lifecycle/concurrency tests passed in 241.09 seconds.
• 112 isolated authorization tests passed in 543.89 seconds at 90.11% branch coverage.
• Isolated real HTTP API contract drill passed.
• Ruff, stale wording scans, Markdown links, all 87 agent gates, merge-intent validation, internal-review evidence gate, and diff integrity passed.
• Senior engineering, QA/test, security/auth, product/ops, architecture, CI integrity, docs, reuse/dedup, and test-delta review passed after fixes.

Human Review Focus

Review authorization-before-disclosure, final-admin preservation, exact replay after later state changes, privacy-safe denial evidence, rollback atomicity, absence of grant/service restoration, and the inactive contributor-foundation boundary.

Summary by CodeRabbit

• New Features

  • Added administrative API operations to revoke and reactivate actor identity links.
  • Identity-link lifecycle actions are now active and protected by authorization checks.
  • Operations support idempotent retries, safe replay, conflict reporting, and privacy-preserving errors.
  • Reactivation restores only the specific identity binding and does not restore profiles, grants, or administrator access.

• Bug Fixes

  • Improved transaction locking and race-condition handling for concurrent lifecycle and authority changes.

• Documentation

  • Updated authorization specifications, architecture references, and operational guidance for the new behavior.

[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: 07889c4e-2a73-47a0-80f1-075125c02a40

📥 Commits

Reviewing files that changed from the base of the PR and between 1b5422f and 44ac09c.

📒 Files selected for processing (38)

• .agent-loop/LOOP_STATE.md
• .agent-loop/REVIEW_LOG.md
• .agent-loop/WORK_QUEUE.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/PLAN.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-09D-B-identity-link-lifecycle.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-09D-actor-identity-lifecycle.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-10-project-role-grants.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-12-project-mutation-cutover.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-13-task-assignment-cutover.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-14-submission-checker-cutover.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-15-worker-authority-removal.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-CONTRIBUTOR-FOUNDATION-contributor-fields-human-lineage.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-09D-B-internal-review-evidence.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-09D-B-pr-trust-bundle.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-09D-B-preimplementation-review-evidence.md
• .agent-loop/merge-intents/WS-AUTH-001-09D-B.json
• backend/app/modules/authorization/catalogue.py
• backend/app/modules/authorization/kernel.py
• backend/app/modules/authorization/lifecycle_schemas.py
• backend/app/modules/authorization/lifecycle_service.py
• backend/app/modules/authorization/repository.py
• backend/app/modules/authorization/router.py
• backend/app/modules/authorization/runtime.py
• backend/app/modules/authorization/service.py
• backend/scripts/api_contract_e2e.py
• backend/tests/test_api_controls.py
• backend/tests/test_audit.py
• backend/tests/test_auth.py
• backend/tests/test_authorization.py
• docs/architecture_data_model.md
• docs/operations_authorization_service.md
• docs/spec_authorization_service.md
• scripts/test_agent_gates.py

---

📝 Walkthrough

Walkthrough

AUTH-09D-B activates actor identity-link revoke/reactivate endpoints with authorization, locking, idempotency, evidence, and concurrency handling. The PR adds lifecycle contracts, implementation, integration tests, documentation updates, and revised AUTH contributor-foundation sequencing.

Changes

Identity-link lifecycle and AUTH rollout

Layer / File(s)	Summary
AUTH rollout state and review gates .agent-loop/..., reviews/*, .agent-loop/merge-intents/*	Updates AUTH-09D-B status, review evidence, merge metadata, contributor-foundation sequencing, and downstream migration planning.
Lifecycle and contributor-foundation contracts .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/*, DECISIONS.md, DISCOVERY.md, PLAN.md	Defines revoke/reactivate behavior, locking, failure semantics, evidence requirements, canonical contributor lineage, and trusted-main migration allocation.
Identity-link authorization and mutation flow backend/app/modules/authorization/*	Activates lifecycle actions, adds resource context and response schema, implements authorization guards, target locking, lifecycle transitions, idempotency, audit evidence, and two protected endpoints.
Lifecycle validation and published behavior backend/tests/*, backend/scripts/*, scripts/test_agent_gates.py, docs/*	Adds route, API-contract, failure-matrix, concurrency, catalogue, audit, gate-state, and documentation coverage.

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

Sequence Diagram(s)

sequenceDiagram
  participant AdminClient
  participant AuthorizationRouter
  participant AuthorizationService
  participant IdentityLinkLifecycleService
  participant PostgreSQL
  AdminClient->>AuthorizationRouter: POST revoke or reactivate
  AuthorizationRouter->>AuthorizationService: authorize transition
  AuthorizationService->>PostgreSQL: reserve idempotency and lock target
  AuthorizationRouter->>IdentityLinkLifecycleService: complete lifecycle mutation
  IdentityLinkLifecycleService->>PostgreSQL: update link and write evidence
  IdentityLinkLifecycleService-->>AuthorizationRouter: response or conflict
  AuthorizationRouter-->>AdminClient: HTTP 200, 409, or 503

Loading

Possibly related PRs

• Flow-Research/workstream#119: Adds the shared idempotent authority-mutation foundation used by identity-link lifecycle operations.
• Flow-Research/workstream#126: Establishes the closed authorization action catalogue and action-evidence parity used here.
• Flow-Research/workstream#148: Provides the AUTH-09D split foundations extended by this lifecycle implementation.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers summary, scope, verification, and review focus, but omits most required template sections.	Fill in the missing template sections, especially chunk/merge intent, design, alternatives, evidence, test delta, reviewer results, CI integrity, and ownership.
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.87% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the main change: adding identity-link lifecycle authorization APIs.
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-09d-b-identity-link-lifecycle

---

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