README

A processing ledger for AI traffic. It turns the requests Egress Guard observes into the AI-subprocessor portion of a GDPR Article 30 record of processing, so you can answer, with evidence, which personal data goes to which AI provider, processed where, under what contract, and for how long.

It records categories and hashes only, never the data itself. A record says "an email address and a payment card were sent to OpenAI (EU region), the card redacted before send, under SCCs, 30-day retention". It never stores the email or the card.

This is the free collector. The independent witness (tamper-evidence an auditor accepts) and the always-current subprocessor dataset are the hosted Ledger Cloud (paid).

This is an independent open-source package. It is not affiliated with, endorsed by, or sponsored by Laravel, Laravel LLC, or any AI provider. It documents and evidences processing; it does not make your app compliant. Have a DPO or privacy counsel own the legal content and review the output. This is not legal advice.

Requirements

• PHP 8.2+, Laravel 12 or 13
• laravelsecurityaudit/laravel-ai-egress-guard (it provides the AiRequestCaptured signal)

Installation

composer require laravelsecurityaudit/laravel-ai-ledger
php artisan migrate

It subscribes to Egress Guard automatically. Every captured AI request becomes a category-only processing record.

What it records

For each AI call: the subprocessor and its company, the processing region, sub-subprocessors, the purpose (configured per route), the categories of personal data detected, a pseudonymous data-subject reference, the legal basis, whether it is a third-country transfer and the safeguard, which categories were redacted before send, the provider retention, and a local hash chain. The provider facts come from the SubprocessorRegistry; the categories come from Egress Guard's findings.

Export

php artisan ai-ledger:export --type=ropa --format=markdown
php artisan ai-ledger:export --type=register --format=json --output=subprocessors.json

ropa is the Article 30 record grouped by subprocessor; register is the subprocessor register from the dataset.

Configuration

php artisan vendor:publish --tag=ai-ledger-config

Set your controller_ref, the default legal_basis, per-source purposes, the processing regions you actually use, the residency allowed_regions, the categories map, and the subprocessors dataset. Verify the dataset against each provider's current terms, or let Ledger Cloud maintain it.

Residency

Set residency.allowed_regions (for example ['EU']). A request to a provider whose region is not allowed is recorded with residency_ok = false. To also block it at runtime, enable Egress Guard's residency enforcement (egress-guard.residency), which blocks out-of-region calls at the wire.

The paid layer

Set AI_LEDGER_CLOUD_ENDPOINT and AI_LEDGER_CLOUD_TOKEN to enable the hosted witness: each record's hash is counter-signed by a party your app does not control, which is what makes the chain credible to an auditor. Without a token the cloud client is a no-op and everything runs locally.

Testing

composer test
composer analyse

The Laravel Security Audit family

One detection engine, guarding every place data leaves your app.

License

The MIT License (MIT). See LICENSE.