Audit & privacy

Motivation

If an AI touches access governance, “what did it do, on what, and was anything sensitive involved?” must be
answerable — without the audit trail itself becoming a secret store. laravel-iam-ai resolves that tension
with privacy-by-default audit: every action is recorded, but prompts are never persisted and outputs
are persisted only when you opt in, and only after sanitization.

Theory: log the act, not the secret

For each advisory the module records a tuple of governance metadata $g$, never the raw prompt $u$:

where $\text{output}^{?}$ is present only if store_outputs = true, and then it is the redacted output
$\rho(o)$, never the raw one. The prompt $u$ appears in no branch — store_prompts = false is a hard
default with no env override in the shipped config.

Design: audit on every path

Every advise() outcome — AI off, transport threw, guard failed, or clean success — flows through one
record() call before returning. There is no path that returns an Advisory without auditing it.

The recorded fields are exactly:

The recorder is Padosoft\Iam\Domain\Audit\Pii\AuditRecorder from laravel-iam-server, so AI actions land in
the same tamper-evident audit stream as the rest of IAM — see
tamper-evident audit.

Fail-closed explanation

Privacy isn’t the only fail-safe in this area. AccessExplainer derives its verdict from a strict boolean
check, never from truthiness or model text:

$allowed = ($decision['allowed'] ?? false) === true;
$verdict = $allowed ? 'CONSENTITO' : 'NEGATO';

A string "false" (truthy in PHP), a missing key, or any unexpected value all collapse to NEGATO — the
explanation never spuriously reads as allowed. This mirrors the PDP’s own deny-overrides / fail-closed
posture.

Worked example: reading the trail

use Padosoft\Iam\Domain\Audit\Models\AuditEvent;

// after an advisory ran
$event = AuditEvent::query()
    ->where('event_type', 'iam.ai.advisory')
    ->latest()->first();

$event->metadata_json['ai_used'];      // false  (AI was off → deterministic)
$event->metadata_json['redacted'];     // true   (something was stripped)
$event->metadata_json['guard_passed']; // true
$event->metadata_json['violations'];   // 0
$event->metadata_json['output'];       // null   (store_outputs = false)

You can answer “did the AI run? was anything redacted? did the guard reject anything?” entirely from
metadata, with no secret ever written.

ADR

Gotchas

See also

• PRE-prompt redaction
• Observability & audit
• The advisory pipeline