Governed AI actions

​

Motivation

1. The proposal is attacker-influenced text. Anything the model reads — a retrieved chunk, a web page, a tool result — can steer the arguments it proposes. If the same structure that carries the arguments also carries tenant_id, principal_id or grant, a prompt injection can ask for a different tenant or a stronger grant.
2. Approval and effect are separated in time. A person approves at 10:00 and the effect runs at 10:07, or on a queue worker at 14:00. In between, the arguments can be swapped, the approver’s grant can be revoked, the approval can lapse, and the worker can be running for another tenant. An approval that is merely “a token that was clicked” authorizes none of those cases correctly.

​

Theory & background

• The confused deputy. A privileged component (here: the server executing a tool) acts on instructions from a less-privileged one (the model). The cure is to make the authority — tenant, principal, grant, assurance level — a property the server attaches, never a field the proposer can set.
• Time-of-check to time-of-use (TOCTOU). Authorization checked at approval time is not authorization at effect time. The cure is to re-check at the last moment before the effect against current state, not to trust a stored decision.
• Canonical form. To say “this approval is for exactly this action” you need one byte-exact representation of the action, so equal actions hash equal and different actions hash different. The canonicalizer sorts object keys recursively, preserves list order and hashes UTF-8 JSON with SHA-256, in the spirit of JSON canonicalization schemes such as RFC 8785 (it is not a full implementation of that standard).

​

Design

​

Data model / contract

​

The intent

​

What the approval is bound to

• the arguments are digested from args itself each time; the public argsDigest field is not trusted, so an intent rebuilt with other arguments and the old digest does not match;
• the document is structured JSON, not a delimiter-joined string, so a character inside resource or target cannot slide into a neighbouring field.

​

The audit trail

​

Knobs

​

Decision rationale (ADR-style)

​

Worked example

use App\Actions\ActionApprovalService;
use App\Actions\ActionIntent;

$intent = ActionIntent::fromModelProposal(
    actionId: 'search_knowledge_base',
    tenantId: 'acme',
    principalId: 'user-42',
    proposal: [
        'resource' => 'knowledge_document',
        'effect' => 'read',
        'target' => 'project/hr',
        'args' => ['query' => 'retention policy'],
    ],
    grant: 'kb.read',
    assurance: 'mfa',
);

$acl = static fn (ActionIntent $i): bool => $user->can('kb.read');

// TenantContext must already be 'acme' and $runId must belong to 'acme'.
$pending = $service->request($intent, $runId);

// ...later, when the approver confirms with $pending->plainTextToken:
$receipt = $service->approve($pending->plainTextToken, $intent, $acl, actor: ['user_id' => 'approver-7']);

// ...immediately before the effect, possibly on another worker:
if ($service->verifyForExecution($receipt, $intent, $acl)) {
    // run the effect
}

{
  "event": "action_approval.denied",
  "step_name": "action-intent-approval",
  "payload": {
    "reason": "acl_denied",
    "approval_id": "…",
    "execution_id": "…",
    "action_id": "search_knowledge_base",
    "principal_id": "user-42",
    "attempt_tenant_id": "acme",
    "action_digest": "…"
  }
}

​

Gotchas & operations

• Not wired yet. No MCP, Flow or widget executor calls the service today. The only enforced piece in production is the classification gate on the widget /exec-tool path. Treat the approval service as a contract the gateway adopts.
• A receipt verifies repeatedly. Within its validity window the same receipt returns true every time. Until the gateway reserves execution_id under a database uniqueness constraint, no caller may treat one successful verification as permission to run an effect more than once.
• The ACL callback must return exactly true. Return a boolean from your policy check; do not return a Response object or a string.
• Match the ambient tenant. On a queue worker, set TenantContext from the job’s immutable tenant before calling approve or verifyForExecution; a mismatch is refused and audited as binding_mismatch.
• Pin the run and step in the gateway. Flow’s engine and cockpit consume path can replace an approval’s stored payload; the service then denies (fail closed) but the approval is spent.
• Do not wrap denials in a transaction you may roll back. The denial audit row is written on the same connection; a rollback discards it.
• Unknown tokens are not audited by the service. A token Flow does not know has no run to attribute a denial to; the gateway records that refusal.
• evidenceRefs and key order. Evidence references are not part of the digest, and object key order does not change it, but list order does.