TenantAtlas/docs/package-governance.md

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:

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.