Filament Spid Laravel Package

Product Decisions This Supports

• Go/no-go on building SPID login in-house. 1.0.0 is the first release with a SemVer commitment, so this is the first version a roadmap can safely pin. Choose between buying this package and hand-rolling SAML SP integration against italia/spid-laravel — the delta is the install/doctor/metadata tooling plus the Filament glue, not the SAML itself.
• Compliance scoping. SPID is a regulatory requirement for Italian public-facing services and a trust signal for private ones. The package now enforces a minimum SPID security level (filament-spid.minimum_level, default SpidL2) and refuses logins below it, which is a policy decision product has to make explicitly rather than inherit from a library default (spid-auth.sp_spid_level defaults to SpidL1 and must be raised).
• Privacy/data-minimisation review. filament-spid.store_spid_data and spid_data_attributes let you scope which of the eight SPID attributes persist; defaults preserve "store everything." This is the config a DPO reviews, and it should be settled before first login, not after.
• Onboarding/activation policy. auto_create_users now defaults to false: a SPID identity no longer silently creates an account. That is a product-visible funnel change — decide whether SPID is a self-service registration path (opt in) or a login-only path for pre-provisioned citizens.
• Build effort estimate. filament-spid:install publishes config/migration/assets, writes .env, edits the panel provider and CSRF exemption, and is idempotent with --dry-run; filament-spid:doctor gives read-only readiness checks with stable JSON and defined exit codes. That collapses a multi-day integration spike into a scripted step, and the JSON output is CI-usable.
• Audit evidence for AgID. filament-spid:metadata:validate records document SHA-256, plugin and tool versions, profile and timestamp. Usable as evidence artefacts — but the report itself states HOSTED_VALIDATOR_NOT_RUN and FORMAL_AGID_ACCEPTANCE_NOT_OBTAINED, so it does not substitute for the official hosted validator or AgID sign-off. Plan that as a separate workstream.
• Upgrade budgeting. If anything is already on 0.1.x, this is a breaking release: PHP 8.3+, Laravel 11 dropped, removed config keys (redirect_after_login, spid_level, providers), relocated ACS endpoint, changed fallback email domain (@spid.local → @spid.invalid), and registerRoutes() now defaults to false. Treat as a migration ticket with a regression pass on existing accounts.
• Platform currency. CI proves PHP 8.3–8.5 × Laravel 12–13 × Filament 3–5. Multi-tenant panels are supported via filament-spid.panel; plugin resolution returns null outside a SPID panel, so shared layouts are safe.

When to Consider This Package

Adopt when:

• You run one or more Filament panels in a Laravel app and need SPID as a login option for Italian citizens or businesses (public SP with IPA code, private SP with VAT number — both modelled in the installer).
• You need self-hosted authentication: nothing is uploaded anywhere, metadata validation runs locally against a pinned spid_sp_test. Fits environments that cannot route identity data through a third party.
• You want the SPID plumbing owned by config rather than application code: HandleSpidLogin/HandleSpidLogout listeners provision the user, authenticate on the panel guard, check canAccessPanel() and tear down the session, with register_listeners as the opt-out.
• You can accept the dependency contract: PHP 8.3+, Laravel 12+, a patched italia/spid-laravel fork, minimum-stability: beta-style patch enablement in composer.json, and a pinned onelogin/php-saml to get past CVE-2025-66475. This is the single biggest adoption gate — confirm with engineering and security that a forked dependency is acceptable in your supply chain and who owns tracking it.
• You need operational maturity, not just a login button: doctor checks, install idempotency, hourly-deduplicated boot warnings, HTTPS/session-cookie/key-pair checks, and a 111-response local lab including sentinels that must fail.

Look elsewhere when:

• You are not on Filament (plain Blade/Livewire, Nova, or a headless/API-only backend) — the value here is the panel integration.
• You are still on Laravel 11 or PHP 8.2 and cannot move: both are refused by Composer. The PHP 8.2 date cited is 31 December 2026, so this is a hard deadline on your platform roadmap.
• Your policy forbids forked/vendored dependencies or patch workflows, or you need an unmodified upstream-only dependency tree.
• You need CIE (Carta d'Identità Elettronica), eIDAS/SPID-as-a-Service, OIDC, or social login in the same surface. This is SPID SAML only; other providers via SpidPlugin::providers() is an allowlist over SPID IdPs, not a general federation layer.
• You need certified, turnkey AgID acceptance out of the box. The tooling produces evidence; it does not obtain acceptance.
• You need multi-IdP orchestration across non-Italian markets, where a hosted identity broker is cheaper than maintaining SAML metadata, key rotation and IdP test matrices.

How to Pitch It (Stakeholders)

For executives (one paragraph): SPID login is a compliance requirement and a trust signal for Italian users, and until now it was a bespoke integration risk each time. Version 1.0.0 is the first stable, SemVer-backed release: it converts the integration into a scripted install with a pre-flight readiness check and a local metadata validator that produces audit evidence — so we can scope SPID as a bounded workstream instead of an open-ended one. It also closes real security gaps by default: a minimum SPID security level is enforced, self-service account creation is off unless we opt in, stored SPID attributes are configurable for data minimisation, and panel access is checked before a session is established. The honest caveats are that it requires PHP 8.3+ and Laravel 12+, it depends on a patched fork of the upstream SPID library to sidestep a known CVE, and its validator explicitly does not replace AgID's hosted validator or formal acceptance — both are separate line items we should fund, not assume away.

For engineering (bullets):

• Stable API, SemVer from here; upgrade path documented in "Upgrading from 0.1.x". Breaking surface is large: PHP 8.3+, Laravel 11 dropped, three config keys and two env vars removed, ACS relocated to italia/spid-laravel, registerRoutes() now false by default, auto_create_users and the no-email fallback domain (@spid.invalid) both changed.
• One-command setup: filament-spid:install --panel= --input=setup.json --dry-run --migrate. Pre-validates inputs before any write, never overwrites published files, edits the panel provider and bootstrap/app.php via PHP's tokenizer, and is idempotent. Anything unsafe becomes a listed manual step with exit code 1. Use examples/setup.public.json / setup.private.json as templates.
• Pre-flight: filament-spid:doctor --json --strict. Read-only, no network or writes; checks dependency/advisory floors, the SPID patch (judged by the metadata php-saml actually builds, not PATCHES.txt), panel/guard, user model, gate and fillable columns, SPID columns and unique index, SP identity and level, published assets, HTTPS and session cookie, and the SP key pair (including detection of the example pair shipped by the library). CSRF and CSP report as skip — verify those in a browser test. Exit codes 0/1/2, stable schema_version: wire into CI.
• Evidence: filament-spid:metadata:validate --url=|--file= --profile= --report= --json --strict. HTTPS-only, TLS verified, no redirects, size and time bounded; a missing or wrong-version tool, crash, timeout, absent xmlsec1 or unreadable report is exit 2, never a pass. Never uploads. Pair with the spid-validation workflow and tools/spid local lab for regression coverage.
• Auth path: HandleSpidLogin/HandleSpidLogout own provisioning, guard authentication, canAccessPanel() enforcement (translated access_denied instead of a 403 with a live SPID session) and logout, including handing the session to IdP single logout. Opt out via filament-spid.register_listeners.
• Defaults to configure explicitly: spid-auth.sp_spid_level ≥ SpidL2, filament-spid.auto_create_users, filament-spid.panel, filament-spid.store_spid_data/spid_data_attributes, and filament-spid.sp_profile/deployment. Note password maps to RandomPassword so auto_create_users works on stock users tables.
• Ops hygiene: release automation tags from main on merge using release:* labels; SECURITY.md and CODE_OF_CONDUCT.md present; Laravel Boost guidelines and an spid-integration skill install on boost:install (dev-time only, not a runtime dependency); docs in docs/ plus an Italian guide, with the README quickstart executed in CI against a fresh app.
• Open dependency risk to assign an owner: the pinned onelogin/php-saml 4.1.0 CVE-2025-66475 forces the fork, and italia/spid-laravel now owns the ACS endpoint and after_login_url. Track upstream releases so we can return to the mainline package.