Skip to content

SPEC.md

Latest commit

 

History

History
114 lines (81 loc) · 3.39 KB

SPEC.md

File metadata and controls

114 lines (81 loc) · 3.39 KB

php-shield-middleware — Project Specification

13. php-shield-middleware

A unified PSR-15 security middleware pack for modern PHP.

Language PHP 8.1+

Distribution Packagist (composer require yourvendor/shield-middleware)

Build Time 10--14 days

License MIT

Category Security / Middleware / PHP

Problem

Individual PSR-15 security middleware packages on Packagist are mostly written for PHP 7.x, poorly maintained, and inconsistent in API design. Developers assembling a security middleware stack must find, evaluate, and configure 5--6 separate packages. Many have conflicting dependencies or duplicate functionality.

Solution

A single, modern PSR-15 middleware pack providing CSP builder, CORS handler, rate limiter, request sanitizer, security headers, and IP allow/deny list. Consistent API using PHP 8 attributes for configuration, shared middleware pipeline, and a unified config format.

Core Features

  • Security headers: Sets HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy with sensible defaults and full customization.

  • CSP builder: Fluent Content-Security-Policy builder with nonce generation, report-uri support, and per-route policies.

  • CORS handler: Full CORS middleware with origin whitelisting, credential support, preflight caching, and method/header configuration.

  • Rate limiter: Token bucket and sliding window algorithms. Configurable per-route, per-IP, or per-user. Backed by PSR-16 cache.

  • Request sanitizer: Strips XSS payloads, normalizes Unicode, trims whitespace, and removes null bytes from all input. Configurable per-field rules.

  • IP filter: Allow/deny lists supporting individual IPs, CIDR ranges, and named cloud provider ranges (AWS, GCP, Cloudflare).

Technical Architecture

Each middleware implements PSR-15 MiddlewareInterface. A ShieldStack class chains them in recommended order with sensible defaults. Configuration via PHP 8 attributes on route handlers or a shield.php config array. All middleware is stateless; rate limiting state is externalized to any PSR-16 cache. Cloud IP ranges are fetched at build time and cached as a PHP array.

CLI / API Surface

// Quick setup (all defaults)

$stack = Shield::defaults();

// Custom configuration

$stack = Shield::create()

->securityHeaders(hsts: true, frameOptions: 'DENY')

->cors(origins: ['https://app.example.com'])

->rateLimit(maxRequests: 100, windowSeconds: 60)

->sanitize(stripTags: true, trimWhitespace: true)

->ipFilter(allow: ['10.0.0.0/8']);

// Add to your PSR-15 pipeline

$app->pipe($stack);

Key Dependencies

  • psr/http-server-middleware

  • psr/http-message

  • psr/simple-cache

Scope Boundaries

In scope: Security headers, CSP, CORS, rate limiting, request sanitization, IP filtering. PSR-15 compatible. PHP 8 attributes for per-route config.

Out of scope: Authentication, authorization, session management, WAF-level protection, Bot detection.

Success Criteria

  • All middleware passes OWASP security header check

  • Works with Slim 4, Mezzio, and any PSR-15 dispatcher

  • Benchmark showing < 1ms overhead per request for the full stack