RFC: define Handoff access control and RBAC interoperability

[Teingi]

Feature description

Define a resource-level Access Control boundary for PowerContext, using Handoff transfer as the first concrete profile.

The design should answer how user A can transfer work to user B while controlling which Handoff, evidence, and follow-up operations B can access. It should also provide an integration boundary for open-source authorization systems without putting users, roles, or ACLs into Handoff content or scope_id.

Problem and proposed solution

The current Server supports an optional global static Bearer token. A valid token authenticates a caller but does not distinguish users, Workstreams, exact Handoff Revisions, or actions. The existing Handoff Receipt authorization observation records whether a receiver believes it can continue; it is not authentication or an ACL.

The proposed RFC should define:

• a trusted PrincipalRef established by authentication;
• one Server Policy Enforcement Point shared by HTTP, MCP, and the Dashboard;
• a replaceable AuthorizationProvider using subject, action, resource, and context decisions;
• an optional RelationshipWriter for systems that support grant mutation;
• scope roles for long-term collaboration;
• an exact handoff.receiver grant for one committed immutable Handoff Revision;
• citation-manifest evidence access that does not expose the complete scope;
• public Access APIs for self-checks, safe resource listing, role and Binding management, and audit;
• fail-closed 401, 403, and 503 behavior;
• adapters or conformance profiles for Casbin, OpenFGA, and AuthZEN-compatible PDPs such as OPA or Cerbos.

An exact Handoff receiver should be able to read, inspect evidence, and acknowledge only the granted Revision. This grant must not imply access to latest, adjacent Revisions, aggregate Handoff Reports, general Memory or Source queries, Handoff commits, Task Outcomes, tools, networks, or credentials. Continuing the Workstream requires a separate scope role.

scope_id remains a business partition and must not become an authorization credential or tenant proof. Runtime domain APIs should remain free of Principal, role, and permission parameters; enforcement belongs at the Server boundary.

Alternatives considered

• ACL fields on Handoff or scope: couples immutable domain data to identity lifecycle and external policy management.
• Scope roles only: exposes more Workstream history and evidence than a one-off receiver needs.
• Anonymous bearer share links: make possession of a URL the identity and are difficult to audit or revoke safely.
• Dashboard-only visibility controls: do not protect direct HTTP or MCP calls.
• One mandatory policy engine: limits embedded and enterprise deployment choices.

Acceptance direction

• The RFC includes a complete A-to-B user flow, permission matrix, public API shapes, adapter boundaries, migration behavior, and observable acceptance tests.
• HTTP, MCP, and Dashboard calls produce equivalent decisions for the same Principal, action, resource, and policy revision.
• Unauthorized list operations do not query and then filter a complete repository page.
• Revocation and expiration deny future access without deleting immutable Handoff or Receipt history.
• Authorization failures and audit records do not expose tokens, Handoff content, Memory, Source bodies, configured PDP URLs, or raw provider errors.

Contribution

• I am willing to contribute the bilingual RFC and design validation.

[tlyyxjz]

Really solid RFC — I especially like that scope_id is explicitly kept out of the authorization path and that enforcement sits at the Server boundary so HTTP / MCP / Dashboard all hit one PEP. We've been working through similar integration questions for Casbin-style embedded engines, so this is right in my wheelhouse.

One thing I'm curious about: for the one-off handoff.receiver grant (single immutable Revision, read + inspect + acknowledge only), do you see that mapping to a flat policy row in the Casbin conformance profile, or to a role relationship via g? In practice we found one-shot grants fit better as explicit policy entries with a TTL/revocation hook than as roles, because roles tend to stick around longer than the grant should. Would be interested in how you're thinking about modeling that in the RFC — and whether the RelationshipWriter abstraction is meant to handle that lifecycle.