xamxam/docs/de-librairisation.md

De-librairisation Plan

Why

XAMXAM currently contains ~3,300 lines of custom code implementing common infrastructural concerns that well-maintained ecosystem libraries have already solved — correctly, securely, and with years of security audits and edge-case hardening behind them. By replacing these bespoke implementations with off-the-shelf packages we:

• Eliminate attack surface — we stop maintaining our own SMTP client, HTTP client, and Markdown parser.
• Reduce maintenance burden — each line of infrastructure code we own is a line we must understand, debug, and keep secure. Off-the-shelf libs shift that to dedicated maintenance teams.
• Gain features for free — DKIM signing, TLS 1.3, connection pooling, async I/O, proper content security — all things we would never build ourselves.
• Make the codebase smaller and more readable — the remaining code is actual application logic, not protocol plumbing.

What we replace

#	Component	Current size	Replaced by	Why
1	Markdown parser	~1770 lines	league/commonmark 2.x	Parsedown 1.8.0 is unmaintained since 2019. It has known XSS vulnerabilities fixed in later versions that never shipped. league/commonmark is the de-facto standard, actively maintained, security-audited, and supports GFM extensions (tables, strikethrough, autolinks).
2	SMTP client	~680 lines	phpmailer/phpmailer 6.x	Raw socket SMTP with manual STARTTLS negotiation is one of the hardest things to get right in application code. PHPMailer handles TLS 1.3, DKIM, MIME encoding, character sets, connection pooling — all things our custom code does not.
3	HTTP client	~200 lines	guzzlehttp/guzzle 7.x	PeerTubeService::httpRequest() uses file_get_contents() with stream_context_create(). Manual JSON parsing, no retry logic, no connection reuse, fragile error handling. Guzzle is the PHP HTTP standard.
4	Encryption	~86 lines	defuse/php-encryption 2.x	Our AES-256-GCM implementation is actually correct, but home-rolled crypto is never recommended. defuse/php-encryption is the recommended library by the PHP security community. Requires migration of existing encrypted data.

What we keep (and why)

Component	Why keep
password_hash() / password_verify()	Already the correct approach — PHP's built-in bcrypt. No library needed.
CSRF (App.php)	Implementation is correct: 256-bit random token, hash_equals() verification, rotated after mutations. A Symfony CSRF component would be an upgrade but not urgent.
Rate limiter (RateLimit.php)	Adequate for current scale. A concurrent-safe Symfony rate-limiter would be better but the file race condition is low-risk at our traffic levels.
PHP templates	Plain PHP include with extract() is fast, simple, and well-understood. Auto-escaping (Twig) would be a security upgrade but the migration cost is high and content is mostly admin-controlled.
Logging	error_log() with JSON-lines is sufficient. Monolog would be cleaner but adds no security benefit.

Composer setup

The project currently has no composer.json. PHP CS Fixer and PHPStan were installed manually into vendor/bin/. We will:

1. Create composer.json with the four packages above.
2. Run composer install to populate vendor/.
3. Keep existing PHP CS Fixer and PHPStan configs — they already work.

Migration order (by risk)

Phase 1: Markdown parser (low risk, high payoff)

• Surface: 4 files import Parsedown
• API similarity: $pd->text($input) → $converter->convert($input)
• SafeMode equivalent: league/commonmark is safe by default (no raw HTML in safe mode)
• No data migration needed: input is Markdown strings, output is HTML — both are ephemeral and regenerated on each page load
• Files to change:
  • app/src/Controllers/AboutController.php
  • app/src/Controllers/LicenceController.php
  • app/templates/partials/form/form-help-block.php
  • app/public/admin/form-help-inline-fragment.php

Phase 2: HTTP client (low risk, PeerTube-specific)

• Surface: app/src/PeerTubeService.php only
• No data migration needed: purely a transport layer replacement
• Can be done independently of Phase 1

Phase 3: SMTP client (medium risk, needs testing)

• Surface: app/src/SmtpRelay.php
• API change: SmtpRelay::send($db, $to, $subject, $htmlBody) signature stays, but internals replaced with PHPMailer
• No data migration needed: SMTP settings in DB are read identically
• Must test: actual email sending to a real SMTP server before deploying

Phase 4: Encryption (highest risk, requires migration)

• Surface: app/src/Crypto.php, app/src/ShareLink.php, app/src/AdminAuth.php
• Affects: encrypted passwords in share_links.encrypted_password, SMTP password in site_settings
• Migration required: decrypt all values with old Crypto, re-encrypt with defuse/php-encryption, write migration script
• Do last, and only if the risk/reward is worth it (our current implementation is actually correct)

Target state

After all phases, the codebase loses ~2,700 lines of infrastructure code and gains four well-maintained dependencies with known security postures and upgrade paths.