[phoebus-84]

Summary

First authorization slice for Zenflows: CRUD enforced; events pending. It fixes the architecture review's F01 finding (a valid signature did not imply the right to the object) on resource, organization, relationship, role and person CRUD.

• ExecutionContext built from the verified signer (req_user), the admin key, or fixed-scope service accounts, and passed into domain functions.
• Pure, deny-by-default Zenflows.Authz.Policy, evaluated inside the same Ecto.Multi transaction as the write, on facts loaded with row locks.
• zf_resource_control: administrative control of a resource, kept separate from ValueFlows primaryAccountable/custodian. Existing resources are backfilled from primaryAccountable with source: backfill.
• Organization roles as ValueFlows AgentRelationships with seeded system roles (org.admin, org.member, scoped by in_scope_of):
  • grant and revoke under a per-organization advisory lock;
  • the last admin cannot be revoked;
  • revoked relationships are kept (revokedAt), never deleted.
• Append-only zf_permission_log (a DB trigger rejects UPDATE and DELETE), written in the same transaction as every permission change.
• GraphQL:
  • FORBIDDEN/UNAUTHENTICATED error codes;
  • new resourceControl query;
  • admin-key assignOrganizationAdmin mutation;
  • new fields AgentRelationship.inScopeOf/revokedAt and AgentRelationshipRole.systemKey.
• Guard tests: every mutation must either declare an authz action or sit on an explicit pending allowlist, and privileged helpers may only be called from allowlisted places.

Design and rationale: docs/authz-foundation-design.md (see §14 for how it differs from the original draft). Release notes, including behaviour changes, operations steps and known limitations: docs/authz-release-notes.md.

Before deploying

• Existing organizations have no admin after the upgrade. Assign admins with assignOrganizationAdmin before users need to edit them.
• Hard delete is no longer possible for organizations created after this change, or for persons who created organizations or resources. An archive path is still to be decided.
• Event authorization (F02) is out of scope. createEconomicEvent can still affect another agent's resource.
• New env vars: AUTHZ_ENFORCE and AUTHZ_ALLOW_UNCHECKED. The server refuses to start in production with either one set to its permissive value.

Test plan

• Full suite: 684 tests, 7 failures, none caused by this branch:

  • 4 fail on master too: restroom.test.exs:25,35,41 and economic_resource/domain.test.exs:81.
  • 3 are admin-key GraphQL tests failing with "you are not an admin" against the local zenflows-crypto image: person/type.test.exs:94,155 (already failing on master) and the new authz/organization.test.exs:79.

• Alice/Bob negative tests at domain and GraphQL level, including aliases and several root fields in one document.

• Concurrency tests:

  • a revoke racing an update;
  • two admins revoking each other;
  • a grant racing a revoke;
  • two-organization mutual revokes.

  The race trials hit Postgres deadlocks (40P01) on the earlier code and pass now.

• Migrate, roll back and re-migrate on a fresh database; every seeded resource gets a backfilled controller.

• Run test/authz/organization.test.exs and test/vf/person/type.test.exs against a working Restroom/zenflows-crypto (admin-key path).

🤖 Generated with Claude Code

Cross-repository integration

Workstream: #74
Shared label: workstream:authz-integration. This is a non-closing backlink; merging one slice must not close the overall integration.