AI Governance

AI gives you speed. ai_governance gives you the receipts, at speed.

If your site talks to AI agents over the Model Context Protocol (MCP) — either as an MCP server that agents call tools on, or alongside an external MCP gateway that agents go through — you have two separate, incomplete pictures of what happened: Drupal knows what it authorized, and the gateway knows what actually ran. This module joins those two pictures into a single record per tool call, using the JWT jti from the OAuth access token as the correlation key, so you get one auditable answer to “what did this AI agent do, and was it allowed to?” instead of two logs you have to cross-reference by hand.

It’s part of the Outside AI workstream: the observability and provenance layer for Drupal as a trusted control plane in agentic workflows. You don’t need to be a Drupal expert to use it — once installed, it works quietly in the background and gives you one place to look.

Disclaimer: built with AI assistance. This module’s code, tests, and documentation were developed with substantial help from an AI coding assistant (Claude Code), under the direction and review of the maintainer. If that matters to your adoption decision — for licensing, security-review, or contribution-policy reasons — please factor it in, and feel free to ask questions or raise concerns in the issue queue.

Features

• Two-path correlation. Drupal’s own authorization decision (captured the moment an MCP client calls a tool through Drupal, via the mcp_server module) and an external gateway’s after-the-fact execution report (delivered as a signed webhook) are recorded as separate “legs” and automatically joined into one AuditCorrelation record per jti, with a status that moves from pending → correlated → approved/rejected as each leg arrives.
• Idempotent by design. Retried webhook deliveries and OAuth tokens reused across multiple calls don’t produce duplicate audit rows — each call is deduplicated on its own synthesized identifier, independent of the token it was made with.
• Signed, replay-protected ingestion. The external-gateway webhook endpoint verifies an HMAC-SHA256 signature and rejects stale payloads, with support for rotating the shared secret without downtime (old and new secrets both accepted during the overlap).
• Access-controlled by default. Audit records are entity-access-gated behind a dedicated view ai governance records permission — there is no anonymous read path.
• Self-service reporting. Ships an MCP tool an AI agent can call to look up its own governance history back through Drupal’s own MCP endpoint.
• Safe to uninstall around. A pre-uninstall check blocks removing the module while audit data still exists, rather than silently deleting your compliance trail.

Use it when you need a durable, queryable record of what an AI agent was authorized to do versus what an external gateway reports it actually did — for compliance reporting (see EU AI Act compliance below), incident investigation, or day-to-day visibility into agentic activity on your site.

EU AI Act compliance

ai_governance is not an EU AI Act compliance product. Installing it does not make an AI-agent deployment “EU AI Act compliant,” automatically satisfy Articles 12, 13, or 14, change an AI system’s risk classification, or substitute for legal advice. What it provides is evidence artifacts — correlated call records, server-verified executor identity, recorded oversight decisions, an AI-facing self-report tool, and (via an optional submodule) tamper-evident audit records — that can support an organization’s own AI governance, traceability, transparency, record-keeping, and human-oversight processes.

Module feature Article AuditCorrelation, jti-keyed records Article 12 — log-keeping executor_uid linked to a Drupal user Article 13 — transparency GovernanceLogEntry.approval_status (observational only — see caveat below) Article 14 — human oversight Hash chain via Heimdall (optional AI Governance — Midgard Integration submodule — see caveat below) Article 12 — tamper-evident JSON:API audit surface (opt-in, not shipped by default — see caveat below) Article 12 — accessible to authorities Self-report MCP tool (agent queries its own governance history) Article 14 — AI agent reports its own actions

Three things worth knowing before citing this module in a compliance narrative:

• Human oversight is observational, not enforced. approval_status records a decision made elsewhere (or defaults to auto_approved when nothing gated the call) — this module never blocks, scopes, or gates a tool call itself.
• The hash chain is tamper-evident, not tamper-proof, absent external anchoring, and only exists when the optional Midgard Integration submodule is installed — the core module alone makes no tamper-evidence claim.
• JSON:API exposure is opt-in and unredacted at the field level — it isn’t a shipped dependency of this module, and enabling it means restricting view ai governance records to trusted roles.

See the module’s SECURITY.md for the full field-by-article caveats, and GOVERNANCE.md for the fuller narrative behind this table.

Post-Installation

There’s no content type or field UI to configure — the module ships its own entities and admin surfaces:

1. Enable ai_governance (pulls in its required dependencies automatically).
2. Go to Configuration → AI → Safety & Compliance (/admin/config/ai/ai-governance) and set your webhook shared secret via the Key module, then point the module’s webhook_key setting at it.
3. The audit trail itself lives at Reports → AI Governance Log (/admin/reports/ai-governance) — a Views-powered listing with a per-row “Refresh governance status” action.
4. From the command line, drush ai-governance:status gives the same health snapshot shown on the settings form (useful in deploy scripts to confirm the webhook secret is set before pointing a gateway at the site); drush ai-governance:sync-governance and drush ai-governance:retention-sweep force the module’s cron-queued work to run immediately.

One thing to know up front: the module ships no bundled production gateway plugin. You implement a small McpGatewayInterface plugin that teaches the module the shape of your specific external gateway’s webhook payload, or use one of the optional submodules below if your stack already matches one.

Additional Requirements

• Drupal core ^11 (tested on 11.3.x/11.4.x)
• Key — stores the webhook shared secret
• Simple OAuth — supplies the JWT/jti this module correlates on
• MCP Server — Drupal’s MCP server implementation; this module observes its authorization event
• AI (Drupal AI)
• Core Views and User modules
• An external MCP gateway able to deliver signed webhook audit reports, unless you’re only using the in-Drupal authorization leg

Recommended modules/libraries

• AI Governance — Midgard Integration (bundled submodule) — pulls in tamper-evident, hash-chained governance decisions from Midgard/Heimdall instead of relying on cached fields alone.
• AI Governance — FlowDrop Integration (bundled submodule) — correlates FlowDrop pipeline executions that were triggered by an MCP tool call into this same audit trail.

Similar projects

We’re not aware of another Drupal module that correlates an in-Drupal MCP authorization decision with an external gateway’s execution report via JWT jti. At the protocol level, the closest prior art is the MCP community’s own audit-receipt schema discussion (MAAR) — this module’s SCHEMA.md engages with that discussion for field-naming alignment rather than reinventing it. If you know of overlapping work, please open an issue — we’d rather link to it than duplicate it.

Supporting this Module

No funding links at this time.

Community Documentation

In-repository docs (ARCHITECTURE.md, SECURITY.md, SCHEMA.md, GOVERNANCE.md) cover the entity model, the two capture paths in detail, the audit-record schema, and the EU AI Act governance narrative summarized above. A demo/walkthrough site and video documentation aren’t available yet — check back as the project approaches its 1.0.0-alpha1 tag.