README

Laravel IAM — AI

AI that assists your access governance — and never holds the decision.
Advisory-only redaction, hallucination-guard and audit, on a sovereign EU / on-prem transport. Off by default.

Warning

Advisory only. This module never grants or denies access. It produces explanations and drafts that a human reviews and that the deterministic PDP (in laravel-iam-server) still adjudicates. The AI decorates evidence — it never replaces it, and it never decides.

Why this package

Bolting an LLM onto an IAM system is tempting and dangerous: models hallucinate identifiers, leak secrets into prompts, and — worst of all — get trusted to make the call. laravel-iam-ai gives you the useful half (natural-language explanations, least-privilege suggestions, access-review summaries) while making the dangerous half structurally impossible:

• The PDP, not the AI, decides. Every AI output is an Advisory — a proposal, flagged advisory_only.
• Nothing leaks. A mandatory redaction pipeline strips tokens, keys, passwords, OTPs, emails and IPs before any prompt leaves the process — and again on the model's output (defense-in-depth).
• No invented evidence. A hallucination-guard rejects any answer that cites an ID not present in the real evidence; the response falls back to deterministic text.
• Sovereign by default, off by default. Out of the box enabled=false and the transport is disabled — no data leaves your perimeter. When you turn it on, the recommended providers are Regolo (EU) or Ollama (on-prem). OpenAI is never a default.

"Deterministic first, AI second": if the AI is off, the transport fails, or the guard rejects the output, you always get the deterministic answer built from your tools.

Features

• AdvisoryClient — the governance orchestrator: redaction (pre) → transport → hallucination-guard (post) → audit, with a deterministic fallback on every failure path.
• Redactor — mandatory PII/secret redaction (Bearer/JWT/PEM keys, password|secret|token|otp|cookie, email, IPv4, long hex & base64 blobs). Fail-safe: when in doubt, redact.
• HallucinationGuard — the output may cite only identifiers found in the evidence (prefixed IDs, ULIDs, UUIDs). Anything invented is a violation.
• AccessExplainer — a Policy Copilot that rephrases the PDP's explanation[] in plain language, citing only real decision_id / grants. Fail-closed: only a true boolean allowed reads as allowed.
• DisabledProvider — the safe default transport: makes no network calls; the client falls back to deterministic text.
• Tamper-evident audit of every AI action (stream=ai), with store_prompts=false by default.

Use cases

• "Why was I denied?" Turn a terse PDP explanation[] into a clear sentence for a support agent or end user — without ever claiming the decision should have been different.
• Draft a least-privilege role. Let the AI propose a tightened role from observed usage; a human approves it and the PDP enforces it.
• Summarize an access review. Condense a campaign's signals into a digest for the reviewer — advisory, fully audited, with no secrets in the trail.

Installation

composer require padosoft/laravel-iam-ai

Requirements: PHP 8.3+, Laravel, and padosoft/laravel-iam-server (provides the audit recorder).

Note

Safe by default. After install the module is disabled (enabled=false) and the transport is disabled — it does nothing until you opt in and pick a sovereign provider. No OpenAI dependency is ever pulled in; real providers (Regolo/Ollama) are optional adapters you add explicitly.

Quick start

1. Publish the config

php artisan vendor:publish --tag=laravel-iam-ai-config

2. Explain a decision (works even with the AI off)

AccessExplainer takes the PDP decision array and returns an Advisory:

use Padosoft\Iam\Ai\Modules\AccessExplainer;

$decision = $pdp->check($query)->toArray(); // from laravel-iam-server

$advisory = app(AccessExplainer::class)->explain($decision, 'Why was this denied?');

$advisory->text;          // human-readable explanation (deterministic if AI is off)
$advisory->citations;     // only real refs: ['dec_01H…', 'orders:refund']
$advisory->aiUsed;        // false until you enable a provider
$advisory->toArray();     // includes 'advisory_only' => true

3. Turn on a sovereign provider (opt-in)

In .env — never wire OpenAI as a default:

IAM_AI_ENABLED=true
IAM_AI_PROVIDER=regolo        # sovereign EU — or 'ollama' for on-prem
IAM_AI_MODEL=your-model

Install the matching adapter (e.g. padosoft/laravel-ai-regolo); it rebinds the AiProvider transport. Redaction stays on, the guard stays on, and every call is audited.

4. The PDP still decides

The AI never gates anything. Authorization stays exactly where it was:

if ($pdp->check($query)->allowed) {
    // ... the PDP allowed it — the Advisory only explained it
}

Ecosystem

Documentation

A docmd doc-site lives in docs/: start at docs/index.md, then Getting started, Concepts, Configuration and the Reference.

Security

This module is fail-closed and privacy-first by design: redaction is mandatory and runs before and after the model, prompts are never stored, the hallucination-guard rejects unsupported claims, and the default transport makes no network calls. The AI is advisory-only — it can never escalate access. If you discover a security issue, please email security@padosoft.com rather than opening a public issue.

License

MIT © Padosoft. See LICENSE.