# TenantPilot Package Governance

Status: 2026-05-15
Applies to: Composer, pnpm workspace, Filament plugins, Laravel packages, frontend tooling.

## Policy

New packages are allowed only when they solve a current release problem that existing Laravel/Filament/project patterns cannot reasonably solve.

Every new package requires:

- Maintenance check.
- License check.
- Security advisory check.
- Version compatibility check with PHP 8.4, Laravel 12, Filament 5, Livewire 4, Tailwind 4.
- Removal plan if it is experimental.
- Spec/plan update when it changes runtime behavior.

## Current Risk Matrix

| Package | Current | Risk | Recommendation |
|---|---:|---|---|
| `filament/filament` | 5.2.1 | High advisory via Filament Tables XSS range | Upgrade to >=5.3.5, preferably current 5.x, then run Filament/action/browser lanes. |
| `league/commonmark` | transitive | Medium advisories | Patch through Composer update. |
| `phpseclib/phpseclib` | transitive | High advisories | Patch through Composer update. |
| `phpunit/phpunit` | 12.5.4 | High dev advisory | Upgrade to >=12.5.8. |
| `psy/psysh` | transitive/dev | Medium advisory | Patch through Composer update. |
| `axios` | 1.14.0 | High/moderate SSRF/header/prototype pollution advisories | Upgrade to >=1.16.1. |
| `postcss` | 8.5.9 transitive | Moderate XSS | Upgrade transitive via package update. |
| `esbuild` | transitive via drizzle tooling | Moderate dev-server issue | Upgrade dependency chain to esbuild >=0.25.0. |
| `devalue` | workspace transitive | High DoS | Upgrade to >=5.8.1 through website/workspace dependency update. |
| `socialiteproviders/microsoft-azure` | 4.2.1 | Major version behind | Review 5.x migration separately with auth tests. |
| `barryvdh/laravel-debugbar` | 3.16.5 dev | Major behind | Keep dev-only; upgrade or remove if unused. |

## Approved Packages

- Laravel framework first-party packages already in use.
- Filament first-party v5 packages.
- Pest 4 and official Pest plugins used by the current test lanes.
- Tailwind CSS v4 and `@tailwindcss/vite`.
- Drizzle tooling for local PostgreSQL workflows when repo scripts require it.

## Packages Under Review

- `socialiteproviders/microsoft-azure` 4.x to 5.x.
- `torchlight/engine` 0.1 to 1.x.
- `barryvdh/laravel-debugbar` 3.x to 4.x or removal.
- Vite 7 to 8 and `laravel-vite-plugin` 2 to 3.

## Do Not Use Without Approval

- Unmaintained Filament plugins.
- Packages that require Filament v3/v4 APIs.
- Packages that bypass Laravel authorization, validation, storage, or queue systems.
- Packages that store secrets in plaintext.
- UI frameworks that duplicate Filament for admin workflows.
- SDKs that bypass `GraphClientInterface` for Microsoft Graph calls.

## CI Gates

Required before release:

```bash
cd apps/platform
composer validate --strict
composer audit
corepack pnpm audit --audit-level moderate
```

Advisory exceptions require:

- Advisory ID.
- Affected package/version.
- Reason not exploitable in TenantPilot.
- Expiry date.
- Owner.
- Compensating control.

## Upgrade Rules

- Patch security advisories before feature work when severity is high and package is runtime-exposed.
- Minor Laravel/Filament updates require Filament action tests and browser smoke on critical admin workflows.
- Major upgrades require a spec, upgrade guide review, staging validation, and rollback plan.
- Do not update lock files incidentally in feature PRs unless the feature is a dependency update.