Design an external authorization decision provider seam (bring your IAM/policy)

[dgenio]

Goal

Make Weaver Kernel usable as an execution-enforcement point without requiring teams to replace the identity / authorization system they already trust.

Target relationship:

authenticated principal / workload
        ↓
external or native policy decision
        ↓
Weaver Kernel
(bind authority → verify → execute → bounded result → ActionTrace)

The built-in policy engine remains first-class and dependency-free. This issue defines a narrow provider seam; it does not add hard dependencies on Cedar, OpenFGA, Auth0, OAP or any other vendor/project.

Why

Trying to win organization-wide policy authoring is strategically unnecessary. Mature IAM/policy systems already own principal/resource/action/context semantics for many adopters. Kernel's differentiated job should be enforcement at the mediated agent-action boundary plus scoped authority and evidence.

The architecture should therefore be able to accept a decision produced elsewhere while preserving Kernel's invariants.

Design requirements

Define a small protocol conceptually equivalent to:

class AuthorizationDecisionProvider(Protocol):
    def evaluate(
        self,
        *,
        principal: Principal,
        capability: Capability,
        request: CapabilityRequest,
        context: Mapping[str, Any],
    ) -> PolicyDecision: ...

The final API need not use this exact signature.

The seam must preserve:

• stable allow / deny / ask semantics where supported;
• reason codes / explanation mapping;
• constraints that are subsequently signed into the Kernel grant;
• policy/decision identity or digest for ActionTrace evidence;
• deterministic fail-closed behavior on provider errors / malformed decisions;
• no external system receiving raw tool results merely to make a pre-action decision;
• native DefaultPolicyEngine behavior unchanged for standalone users.

Interoperability spike

Before making the provider API stable, implement two tiny adapters/examples with different policy models, selected to test the abstraction rather than endorse vendors. For example:

• one principal/action/resource/context policy engine (Cedar/OpenFGA-style); and
• one agent-specific signed decision/artifact system (OAP-style), if its contract is stable enough.

Adapters can live under examples/experimental code initially.

The goal is to learn whether one neutral decision shape can faithfully carry what Kernel needs.

Security questions

The design note must answer:

• What identity has actually been authenticated, and by whom?
• Which resource/action/argument information is sent to the policy provider?
• Which returned constraints become cryptographically bound into the grant?
• What happens if the provider times out, returns unknown fields, or cannot map a decision?
• How is decision provenance represented in ActionTrace without pretending Kernel made the upstream decision?
• How does this interact with exact-transaction/action binding in [Design] Evaluate embedded IntentFlow v1 action-assurance enforcement #258?
• Can the same shared policy intent be enforced by AgentFence (coherence: consume the shared Policy + safety-class contract (weaver-spec#78 / agentfence#76) — write once, enforce embedded + at the edge #111/Add shared policy contract roadmap with AgentFence #116) without semantic drift?

Non-goals

• Do not implement another general-purpose policy language.
• Do not add one vendor as a required runtime dependency.
• Do not turn Kernel into an identity provider.
• Do not claim that accepting an upstream decision provides complete mediation.
• Do not standardize the provider seam until Gate 0 (Validate the execution-enforcement wedge against native guardrails and existing authz #278) shows that this interoperability is useful to real adopters.

Acceptance criteria

• Design note defines the neutral decision-provider boundary and fail-closed semantics.
• Native policy engine implements/uses the same conceptual seam without behavior regression, or the design explicitly explains why not.
• Two heterogeneous adapter spikes demonstrate whether the abstraction is genuinely neutral.
• External decision identity/digest can be carried into audit evidence.
• Constraints returned by a provider cannot widen after grant issuance.
• Provider error/malformed-decision tests fail closed.
• Interaction with [Design] Evaluate embedded IntentFlow v1 action-assurance enforcement #258 and coherence: consume the shared Policy + safety-class contract (weaver-spec#78 / agentfence#76) — write once, enforce embedded + at the edge #111/Add shared policy contract roadmap with AgentFence #116 is documented.

Sequencing

Medium priority until Gate 0 (#278) provides external evidence. This is the strategic hedge against betting Kernel adoption on any single policy ecosystem.