# TenantPilot Package Governance

Status: 2026-06-14
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.

## Approved Runtime Services / PDF Rendering

### Gotenberg 8 Chromium internal service

- **Decision**: approved with controls for Spec 378 and future report-style PDF rendering.
- **Scope**: internal PDF rendering infrastructure for server-generated report documents.
- **Runtime model**: separate Docker service reachable only from TenantPilot application/worker services over the internal deployment network.
- **Required integration boundary**: Laravel must call the service through a narrow `PdfRenderingGateway` / `PdfRendererClient`; production PDF generation must not install or execute Node, Puppeteer, Chrome, Chromium, or browser binaries in the Laravel app/queue containers.
- **Required image policy**: pin an explicit Gotenberg 8 Chromium image tag or immutable digest; never use `latest`.
- **Required controls**: internal network only, no public port, health check, explicit timeouts, request/output size limits, no user-provided URL rendering in v1, server-generated HTML payloads only, no signed URLs/secrets/raw provider payloads in HTML, outbound URL access denied or tightly restricted, structured renderer error mapping, and safe OperationRun/audit correlation.
- **Not approved for**: legal invoice generation, German B2B e-invoicing, XRechnung, ZUGFeRD/Factur-X, GoBD archival, tax calculation, invoice numbering, or billing compliance.
- **Owner**: Platform/runtime governance.
- **Rationale**: keeps Chromium isolated from Laravel runtime containers while preserving modern HTML/CSS rendering quality for customer-facing management reports.
- **Review date**: TODO before first production deployment that enables PDF generation, and at least once per major/minor Gotenberg upgrade.
- **Upgrade/patching expectation**: patch within the approved Gotenberg 8 line on security or Chromium base-image advisories; major-version upgrades require a spec/plan update, renderer smoke tests, and staging validation.
- **Spec decision record**: `specs/378-management-report-pdf-v1/artifacts/spec378-pdf-renderer-decision-matrix.md` and `specs/378-management-report-pdf-v1/artifacts/spec378-gotenberg-security-controls.md`.

## 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.