laravel-ai-act-compliance

The first Laravel-native toolkit for EU AI Act + GDPR compliance.
Plug it into any Laravel AI app. Audit-ready out of the box.

Official documentation

Why · Features · Killer modules · Quick start · AI Act mapping · Architecture · Host contracts · Extend · Testing · Vibe-coding pack

🚀 AI vibe-coding pack included

Every padosoft/* package ships with a .claude/ directory containing:

• Skills (.claude/skills/) — pre-loaded by Claude Code when trigger conditions match. The compliance package skills know how to wire DSAR contracts, register cohort metrics, gate consent middleware, and persist incident state transitions.
• Agents (.claude/agents/) — compliance-reviewer checks DSAR delete cascades + bias drift thresholds + state-machine transition coverage before you push.
• Rules (.claude/rules/) — codified review rules distilled from real Copilot findings (escape DSAR LIKE input, never log DSAR subject email at INFO, always audit-trail consent revocations).

Just composer require padosoft/laravel-ai-act-compliance and the pack is auto-discovered when you open the project in Claude Code. No setup required. If you don't use Claude Code, the pack is invisible — it never affects runtime behaviour.

📖 Table of contents

• Why this exists
• Features at a glance
• Killer modules
• Quick start (jr-proof, 5 minutes)
• Configuration
• AI Act + GDPR mapping
• Architecture
• Host contracts
• Modules in detail
• HTTP API surface
• Extension points
• Testing
• Companion package: admin SPA
• Roadmap
• Changelog
• Contributing
• Security
• Credits
• License

🎯 Why this exists

The EU AI Act enters full force in 2026–2027. Python has Lakera Guard, Fairlearn, Aequitas. Laravel has nothing.

If you ship a Laravel app that uses an LLM, you need:

• Disclosure to end users (AI Act Art. 50)
• A risk register that maps each use case to AI Act categories (Art. 6 + Annex III)
• DSAR (Data Subject Access Requests) per GDPR Art. 15 / 16 / 17 with 30-day SLA tracking
• Bias monitoring with cohort parity + drift (Art. 10 + Art. 15)
• Human review tracking with a state machine (Art. 14)
• Incident management with escalation routing (Art. 73)
• Consent ledger with revocation timeline (GDPR Art. 7)
• Cybersecurity middleware (rate limit, session anomaly, 2FA helper)
• Compliance attestation PDF generator for auditors (Art. 11 + Art. 30)

You can build all of this yourself in 2-3 months, or you can composer require padosoft/laravel-ai-act-compliance and ship next week.

Who's this for

Comparable products

✨ Features at a glance

Every module is config-gated (default safe) + migration-published + tested.

💎 Killer modules

These three are what make the package WOW:

1. DSAR queue that handles the regulatory ugliness for you

You implement two contracts:

The package handles everything else:

• Identity verification (SPID / OAuth / email link)
• 30-day SLA tracking + automatic warning at SLA - 5 days + breach escalation
• ZIP packaging + signed download URL
• Audit trail (immutable dsar_audit rows)
• Notification cascade (email + Slack webhook)
• Article reference annotations on every DSAR

2. Cohort-parity bias monitoring

BiasMonitorService then snapshots the metric on a schedule, alerts on drift > 0.05, and feeds the result to the admin SPA Bias Monitor screen — no chart code to write.

3. Incident manager with state-machine + escalation routing

State transitions are immutable, audit-trailed, and validated. Escalation routing (CISO → DPO → CEO) fires automatically based on severity × configured policy.

4. Real-time alerting cascade (v1.3)

What you get for free:

• Cascade-level throttle pre-check — a previously-delivered Slack alert for (tenant, cohort) ends the cascade so it never silently slides through to Discord.
• Severity-escalation bypass — a low inside the cooldown window never suppresses a subsequent critical. Art. 9 requires it.
• Per-channel circuit breaker that trips after N consecutive failures and self-resets on natural cooldown elapse.
• Email cascade is exempt from the throttle because it's the auditable backup trail — every drift event is recorded.

5. Regulatory-feed auto-flagger (v1.4)

What lands on the DPO desk:

• Every new EU AI Act amendment ingested as a regulatory_amendments row with the impacted article clauses pre-detected (AI Act Art. 5 → critical, Art. 10 / 14 / 15 / 27 → high, etc.).
• Case-insensitive regex map accepts plural Articles 5 and 9 / Arts. 9-15.
• XXE-safe parser (LIBXML_NONET blocks network access; we deliberately do NOT pass LIBXML_NOENT).
• Per-tenant composite UNIQUE (tenant_id, source_driver, external_id) — concurrent polls converge cleanly, no duplicate rows.
• RegulatoryAmendmentDetected event with SerializesModels so downstream listeners persist a model id, not the full payload.

6. DPO multi-org tenant management (v1.5)

Operationally:

• Request-scoped binding via $this->app->scoped(TenantContext::class) — Octane-safe.
• X-Tenant-Id header (or ?tenant= query) resolves the slug; unknown → 404, suspended → 423 Locked, archived → 410 Gone.
• CrossTenantOverviewService aggregates platform-wide KPIs in one GROUP BY tenant_id query per table — no N+1 as tenant count grows.

⚡ Quick start (jr-proof, 5 minutes)

Even if you've never installed a Laravel package before, you'll be running by the end of this section.

0. Prerequisites

You need:

• PHP 8.2+ — run php -v and confirm
• Laravel 11, 12 or 13 in your project — php artisan --version
• A database — MySQL / PostgreSQL / SQLite all work
• Composer — composer --version

If any of these are missing, install them first. We'll wait. ☕

1. Install the package

That's it for installation. The Laravel auto-discovery wires the service provider for you.

2. Publish the migrations + config

You should see new files appear under database/migrations/ (8 new migrations) and config/ai-act-compliance.php.

3. Run the migrations

Verify the tables landed:

If you see => 0 (not an error), you're golden.

4. Implement the two host contracts

Create app/Compliance/MyAppUserDataExporter.php:

Create app/Compliance/MyAppUserDataDeleter.php:

5. Bind the contracts in your service provider

Open app/Providers/AppServiceProvider.php and add to register():

6. Add the disclosure middleware (if you have an AI chat surface)

In bootstrap/app.php (Laravel 11+) or app/Http/Kernel.php (Laravel 10):

Then on any route group that renders an AI response:

7. Smoke-test it

If the DSAR row landed, you're compliant-ready.

8. (Optional) Install the admin SPA companion

Then visit /admin/ai-act-compliance — the full 8-screen React SPA (Overview / DSAR / Consent / Risks / Incidents / Bias / DPO / Settings) renders behind your Laravel auth.

See padosoft/laravel-ai-act-compliance-admin for screenshots and a complete tour.

⚙️ Configuration

Every knob lives in config/ai-act-compliance.php. The defaults are intentionally safe-by-default; nothing fires unless you explicitly enable it.

📜 AI Act + GDPR mapping

Every module maps explicitly to an article. This is the audit-trail your DPO + auditor will love.

🏗️ Architecture

The package never owns your domain data. It owns the compliance ledger (DSAR queue, risk register, incident tickets, consent records, bias snapshots, attestations) and the audit trail. Your domain models stay untouched — you just implement the two UserDataExporter / UserDataDeleter contracts to tell the package how to walk your tables.

📐 Host contracts

Two contracts only. Both live under Padosoft\AiActCompliance\DSAR\Contracts.

A third optional contract — Padosoft\AiActCompliance\BiasMonitoring\Contracts\CohortParityMetric — lets you plug arbitrary bias metrics into the monitor.

📚 Modules in detail

Disclosure

• Middleware: ai-act.disclosure — injects an X-AI-Disclosure response header + appends a disclosure footer to JSON / HTML responses.
• Blade directive: @aiDisclosure — renders the configured message inline.
• Locales: EN + IT shipped; publish + override for others.

Risk Register

• Models: RiskRegisterEntry (status, category, owner, mitigation, articles).
• Service: RiskRegisterService with add(), update(), close(), byCategory().
• Enum: AiActRiskCategory (unacceptable / high / limited / low) — directly maps to AI Act Art. 5 / 6 / 50 + Annex III.
• Controller: RiskRegisterController with full CRUD + filter by category / status.

DSAR

• Models: DsarRequest (subject, type, status, opened_at, due_at, articles, assignee).
• Enums: DsarType (export / delete / rectify) + DsarStatus (pending / in_progress / completed / rejected).
• Service: DsarService with open(), assign(), complete(), reject(), breachWarning().
• Jobs: ExportUserDataJob + DeleteUserDataJob — both invoke the host contracts.
• Controller: DsarController with queue + detail + actions + bulk + CSV export.

Bias Monitoring

• Contract: CohortParityMetric (host or 3rd-party implements) + the NamedCohortMetric extension (v1.2) for self-naming metrics.
• Service: BiasMonitorService — runs the registered metrics on a schedule, snapshots them into BiasSnapshot, fires BiasDriftDetected events on drift.
• v1.2 reference metrics under BiasMonitoring\Metrics\:
  • DemographicParityMetric (metric_name='demographic_parity', references AI Act Art. 10)
  • EqualizedOddsMetric (max of TPR-spread and FPR-spread; references AI Act Art. 10 + Art. 15)
  • CalibrationMetric (per-cohort calibration gap with 3-branch CI; references AI Act Art. 15)
• v1.2 registry: MetricRegistry::register($key, $fqcn) validates the FQCN at boot (R23) and rejects overlapping supports() predicates.
• Model: BiasSnapshot (metric_name, metric_version, cohort, cohort_dimension, score, delta, disparity_score, article_evidence_json, computed_at).
• Eval-harness integration: register your metric in the manifest, the harness will run it on every batch.

Alerting (v1.3)

• Models: AlertRoute (at-rest-encrypted webhook URLs via Crypt::encryptString) + AlertDispatch (immutable audit trail row per attempt).
• Channels: SlackWebhookChannel (200 success) + DiscordWebhookChannel (204 / 2xx) + EmailFallbackChannel (Mail::raw with permanent-vs-transient Symfony TransportException classification).
• Services: AlertDispatcher (cascade orchestration with throttle pre-check) + AlertThrottler (per-tenant + per-cohort + per-channel cooldown window with severity-escalation bypass) + CircuitBreaker (clamps misconfigured failures_to_trip=0; resets consecutive_failures after natural cooldown elapses).
• Event: BiasDriftDetected (uses SerializesModels so queued listeners persist a model id, not the full payload).
• Listener: BiasDriftDetectedListener implements ShouldQueue ($tries=1 so transient failures don't double-write audit rows).

RegulatoryFeed (v1.4)

• Contract: RegulatoryFeedDriver (host or 3rd-party implements fetch(array $sourceConfig): array<RegulatoryFeedEntry>).
• Reference driver: RssRegulatoryFeedDriver — RSS 2.0 + Atom 1.0, XXE-safe (LIBXML_NONET blocks network access), Atom <link> selection prefers rel="alternate" over rel="self", max_entries_per_poll=0 short-circuits.
• Service: ImpactedClauseDetector — config-driven regex map; severity ladder Art. 5 / 9 → critical; Art. 10 / 14 / 15 / 27 → high; else medium; throws InvalidArgumentException on invalid regex (no silent downgrade).
• Service: RegulatoryFeedPoller — orchestrator; per-driver Throwable isolation; bounded-column truncation (mb_substr to 191 / 1024 / 500); concurrent-poll race handled via QueryException catch on the composite UNIQUE (tenant_id, source_driver, external_id).
• Event: RegulatoryAmendmentDetected (uses SerializesModels).
• Artisan: ai-act:regulatory-poll (skips when disabled; exit 1 on driver failure).

MultiTenancy (v1.5)

• Model: Tenant (slug UNIQUE 50 chars, subscription_tier enum, status enum, config_overrides_json, suspended_at / archived_at first-transition audit stamps).
• Enums: SubscriptionTier (free / team / enterprise) + TenantStatus (active / suspended / archived).
• Service: TenantContext (bound as $this->app->scoped() — Octane-safe; set/get/activate(slug) with model caching).
• Service: TenantConfigResolver — flat-dotted keys ({"bias.disparity_threshold": 0.02}) AND nested maps; resolution order tenant override → host config → caller default.
• Service: CrossTenantOverviewService — aggregates per-tenant + platform totals in ONE GROUP BY tenant_id query per table (no N+1); safeCount narrows QueryException to cross-driver "table missing" signatures only.
• Middleware: ai-act.tenant-context — header / query resolve; defensive set(null) at start of every request; unknown slug → 404, suspended → 423, archived → 410.

Human Review Tracker

• Model: HumanReview (subject, decision_payload, state, reviewer, decided_at).
• State machine: pending → approved / rejected / escalated. Backed by spatie/laravel-model-states.
• Service: HumanReviewService::open(), approve(), reject(), escalate().

Incident

• Models: IncidentTicket (severity, status, articles, affected_users) + IncidentStateTransition (before, after, actor, reason).
• Enums: IncidentSeverity (low / medium / high / critical) + IncidentStatus (open / triage / mitigating / closed).
• Service: IncidentService::open(), triage(), transition(), close().
• Escalation routing: EscalationRouter — fires notifications per the configured escalation_map.

Consent

• Model: ConsentRecord (polymorphic — bind to any host entity).
• Middleware: ai-act.consent:feature_id — blocks the route until consent is recorded.
• Service: ConsentService::grant(), revoke(), historyFor().

Cybersecurity

• Middleware: PerUserRateLimitMiddleware + SessionAnomalyDetectionMiddleware.
• Helper: TwoFactorHelper — TOTP enrolment + verification.

Compliance Attestation

• Model: ComplianceAttestation (generated_at, signer_id, attached_pdf_path, scope_json).
• Service: ComplianceAttestationService::generate() — composes the Article 30 records of processing snapshot + signs it.
• PDF generator: AttestationPdfGenerator (DomPDF-backed; Browsershot supported via config).

🌐 HTTP API surface

Every endpoint sits behind your host's auth middleware (Sanctum / Passport / session) and is gated by the configured policy. Routes are auto-registered if ai-act-compliance.routes.enabled is true.

The admin SPA companion consumes this surface verbatim — your custom UI does too.

🔌 Extension points

🧪 Testing

Live testsuite (opt-in)

The package ships a tests/Live/ directory that exercises real regulatory reference systems (SPID handshake fixtures, EU AI Act API). It is disabled by default — CI runs Unit + Feature only.

Enable explicitly when you need it:

CI matrix

GitHub Actions tests against PHP 8.3 / 8.4 / 8.5 × Laravel 11 / 12 / 13.

🎨 Companion package: admin SPA

padosoft/laravel-ai-act-compliance-admin is the React 19 + TypeScript admin SPA. It cross-mounts into any Laravel app under /admin/ai-act-compliance and consumes the HTTP API surface above. 8 screens:

Then visit /admin/ai-act-compliance in your browser. Done.

🗺️ Roadmap

• [x] v1.0 — 9 backend modules + migrations + service provider + tests
• [x] v1.1 — Bias monitoring CohortParityMetric interface + extension points
• [x] v1.2 ✅ shipped 2026-05-15 — Pluggable bias-metric strategy registry + 3 reference metrics (DemographicParity, EqualizedOdds, Calibration)
• [x] v1.3 ✅ shipped 2026-05-15 — Cohort-drift real-time alerting (Slack + Discord + email cascade) with throttle, circuit breaker, severity-escalation bypass
• [x] v1.4 ✅ shipped 2026-05-15 — Regulatory change auto-flagger (RSS / Atom EU AI Act amendment feed, XXE-safe, ImpactedClauseDetector, idempotent RegulatoryFeedPoller)
• [x] v1.5 ✅ shipped 2026-05-15 — DPO multi-org tenant management (tenants registry, TenantContext request-scoped, TenantConfigResolver, ai-act.tenant-context middleware, CrossTenantOverviewService)
• [ ] v2.0 — padosoft/laravel-ai-act-compliance-enterprise (Pro add-on) with SLA-backed regulatory updates, SOC 2 / ISO 27001 / ISO 42001 audit-letter template generator

📋 Changelog

See CHANGELOG.md for the full release history.

Recent highlights:

• v1.5.0 (2026-05-15) — DPO multi-org tenant management: tenants registry, TenantContext (scoped), per-tenant TenantConfigResolver, ai-act.tenant-context middleware (404 / 423 / 410), CrossTenantOverviewService no-N+1; 192/192 PHPUnit
• v1.4.0 (2026-05-15) — Regulatory-feed auto-flagger: RSS 2.0 + Atom 1.0 driver (XXE-safe), ImpactedClauseDetector config-driven, RegulatoryFeedPoller idempotent + race-safe, ai-act:regulatory-poll Artisan; 168/168 PHPUnit
• v1.3.0 (2026-05-15) — Cohort-drift alerting cascade: Slack + Discord + email channels, AlertThrottler with severity-escalation bypass, CircuitBreaker with natural-cooldown self-reset, queued BiasDriftDetectedListener with SerializesModels; 130/130 PHPUnit
• v1.2.0 (2026-05-15) — Pluggable CohortParityMetric strategy registry + DemographicParity / EqualizedOdds / Calibration reference metrics; metric_name + metric_version + article_evidence_json on bias_snapshots
• v1.1.x (2026-05-13/14) — Cross-tenant FK gaps + decryption error paths + AI Act middleware tests + FRIA module; locked Laravel 13 compat constraints for AskMyDocs v6.0 integration
• v1.0.0 (2026-05-12) — Full module API surface (9 modules) + initial test pack + WOW README

🤝 Contributing

PRs welcome. Before opening one:

1. Run composer test locally and confirm it's green
2. Add a test for your change
3. Follow the existing code style (Laravel Pint default)
4. Update CHANGELOG.md under ## [Unreleased]

For major changes (new module, new contract, breaking API), open an issue first so we can discuss the design.

🔒 Security

If you discover a security vulnerability, please email [email protected] instead of opening a public issue. We'll acknowledge within 48 hours.

This package follows responsible disclosure. We publish security advisories at GitHub Security Advisories once the fix has shipped.

🙏 Credits

• Padosoft — design, implementation, ongoing maintenance
• Lorenzo Padovani (@lopadova) — product lead + DPO
• The Laravel community — for proving the framework can carry serious enterprise loads
• EU AI Act drafters — for giving us something to comply with 😉

📄 License

The MIT License (MIT). See LICENSE.md for details.

Made with 🇮🇹 by Padosoft · Powering AskMyDocs