ahmido
d43ebcb4ee
Added PDF generation service for management reports as per Spec 378, including Gotenberg integration in docker-compose and configuration updates. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #449
102 lines
5.5 KiB
Markdown
102 lines
5.5 KiB
Markdown
# 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.
|