README

Security middlewares for PivotPHP and any PSR-15 pipeline.

One middleware per concern: CORS, trusted proxies, security headers, CSRF, JWT, rate limiting.
Fail closed: a failed check returns 401/403/429 and never reaches your handler.
Validated configuration: unsafe settings (* origin with credentials, empty JWT secret, POST declared "safe"...) throw InvalidConfigurationException when the config is built.
No hand-rolled crypto: JWT, CSRF tokens, header building and rate limiting delegate to established libraries; this package provides the PSR-15 adapters.

The only required dependencies are the PSR interfaces. Each adapter needs its library, installed on demand:

Middleware	Library	Install
`Cors\CorsMiddleware`	—	—
`Proxy\TrustedProxyMiddleware`	—	—
`Headers\SecurityHeadersMiddleware`	bepsvpt/secure-headers	`composer require bepsvpt/secure-headers`
`Csrf\CsrfMiddleware`	yiisoft/csrf	`composer require yiisoft/csrf`
`Jwt\JwtAuthMiddleware`, `Jwt\JwtIssuer`	firebase/php-jwt	`composer require firebase/php-jwt`
`RateLimit\RateLimitMiddleware`	symfony/rate-limiter	`composer require symfony/rate-limiter`

Installation

composer require pivotphp/security

Middlewares that build responses take a PSR-17 ResponseFactoryInterface (e.g. PivotPHP\Http\Factory\Psr17Factory or Nyholm\Psr7\Factory\Psr17Factory).

Recommended order

TrustedProxy → SecurityHeaders → CORS → RateLimit → (body parsing) → CSRF → JWT → routes

TrustedProxy first, so every later middleware sees the real client IP.
SecurityHeaders and CORS before anything that rejects, so 401/403/429 responses still carry security and CORS headers (the browser can read the error).
CORS before authentication: preflight requests carry no credentials.
Body parsing before CSRF, so form fields are visible.

CORS

use PivotPHP\Security\Cors\CorsConfig;
use PivotPHP\Security\Cors\CorsMiddleware;

$cors = new CorsMiddleware($responseFactory, new CorsConfig(
    allowedOrigins: ['https://app.example.com'],
    allowCredentials: true,
));

Option	Default	Notes
`allowedOrigins`	`[]`	Exact `scheme://host[:port]`, lower case, no path. `['*']` allows any origin.
`allowedMethods`	`GET, POST, PUT, PATCH, DELETE`
`allowedHeaders`	`Content-Type, Authorization`	Request headers accepted in preflight.
`exposedHeaders`	`[]`	Response headers readable by the browser.
`allowCredentials`	`false`
`maxAge`	`600`	Preflight cache in seconds; `null` omits the header.

Behaviour:

Requests without Origin pass through untouched.
Preflight (OPTIONS + Access-Control-Request-Method) is answered by the middleware: 204 with Access-Control-Allow-* when origin, method and headers are allowed; 403 otherwise. The handler is never called.
Actual requests always reach the handler; Access-Control-Allow-Origin is added only for allowed origins. Vary: Origin is added whenever the response depends on the origin.

⚠️ Security: * with allowCredentials: true is rejected at configuration. The null origin (sandboxed iframes, file://) cannot be allowed. CORS does not protect the server — it only tells browsers what other origins may read; authenticate and authorize every request.

Trusted proxies

use PivotPHP\Security\Proxy\TrustedProxyConfig;
use PivotPHP\Security\Proxy\TrustedProxyMiddleware;

$proxy = new TrustedProxyMiddleware(new TrustedProxyConfig(
    trustedProxies: ['10.0.0.0/8', '2001:db8::/32'],
));

// later: $request->getAttribute('client_ip')

Option	Default	Notes
`trustedProxies`	`[]`	IPv4/IPv6 addresses or CIDR ranges.
`header`	`X-Forwarded-For`	Comma-separated IP chain.
`attribute`	`client_ip`	Attribute receiving the resolved IP.

The forwarding header is honoured only when REMOTE_ADDR is a trusted proxy. The chain is read right to left, skipping trusted proxies; the first untrusted address is the client. A malformed entry stops the walk. The attribute is not set when REMOTE_ADDR is missing or invalid.

⚠️ Security: never trust X-Forwarded-For from the internet. List only the proxies you run (load balancer, reverse proxy).

Security headers

use PivotPHP\Security\Headers\SecurityHeadersConfig;
use PivotPHP\Security\Headers\SecurityHeadersMiddleware;

$headers = new SecurityHeadersMiddleware(); // API defaults

Default headers (JSON API, OWASP REST guidance):

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: default-src 'none'; frame-ancestors 'none'
X-Permitted-Cross-Domain-Policies: none

Option	Default	Notes
`hsts`, `hstsMaxAge`, `hstsIncludeSubDomains`, `hstsPreload`	`true`, `31536000`, `true`, `false`	Preload requires subdomains and max-age ≥ 1 year.
`frameOptions`	`deny`	`deny` or `sameorigin`.
`referrerPolicy`	`strict-origin-when-cross-origin`	Any standard value.
`contentSecurityPolicy`	`default-src 'none'; frame-ancestors 'none'`	`bepsvpt/secure-headers` CSP array; `null` disables.
`overrides`	`[]`	Raw `bepsvpt/secure-headers` config (Permissions-Policy, COOP/COEP/CORP, reporting...).

new SecurityHeadersConfig(contentSecurityPolicy: [
    'default-src' => ['self' => true],
    'img-src' => ['allow' => ['https://cdn.example.com']],
]);

Headers already set by the application are kept. The deprecated X-XSS-Protection is not sent. CSP nonces are not supported (the library keeps them in static state shared across requests).

⚠️ Security: an HTML application needs a CSP that matches its assets; the default is meant for APIs. Enable HSTS only on HTTPS-only hosts.

CSRF

Needed when the API authenticates with cookies (session or JWT in a cookie). Pure bearer-token APIs are not exposed to CSRF.

use PivotPHP\Security\Csrf\CsrfMiddleware;
use Yiisoft\Csrf\Hmac\HmacCsrfToken;
use Yiisoft\Csrf\MaskedCsrfToken;

$token = new MaskedCsrfToken(new HmacCsrfToken($identityGenerator, $secret, 'sha256', 3600));
$csrf = new CsrfMiddleware($responseFactory, $token);

// render: $request->getAttribute('csrf_token')->getValue()

Token strategies come from yiisoft/csrf: SynchronizerCsrfToken (random token in a storage, e.g. the session) or HmacCsrfToken (stateless, bound to an identity such as the session id). Wrap either in MaskedCsrfToken when the token is rendered in HTML (BREACH mitigation).

Option (`CsrfConfig`)	Default	Notes
`parameterName`	`_csrf`	Form field.
`headerName`	`X-CSRF-Token`	Header (SPA/AJAX).
`safeMethods`	`GET, HEAD, OPTIONS`	`POST/PUT/PATCH/DELETE` cannot be declared safe.
`attribute`	`csrf_token`	Attribute holding the token object.
`failureStatus`	`403`	Any 4xx.

Every other method needs a valid token in the body field or header; otherwise the response is the failure status and the handler is not called.

⚠️ Security: keep GET free of side effects — safe methods are never checked. Combine with SameSite cookies.

JWT authentication

use PivotPHP\Security\Jwt\JwtAuthMiddleware;
use PivotPHP\Security\Jwt\JwtConfig;

$auth = new JwtAuthMiddleware($responseFactory, new JwtConfig(
    key: $_ENV['JWT_SECRET'],          // ≥ 32 bytes for HS256
    algorithm: 'HS256',
    publicPaths: ['/health', '/docs/*'],
));

// in the handler: $request->getAttribute('user') — the claims as an array

Option	Default	Notes
`key`	—	Secret (HS) or public key / PEM (RS, PS256, ES*, EdDSA).
`algorithm`	`HS256`	Exactly one algorithm is accepted.
`publicPaths`	`[]`	`fnmatch` patterns that skip authentication.
`cookieName`	`null`	Cookie read when `Authorization` is absent.
`issuer`	`null`	Required `iss`.
`audience`	`[]`	Accepted `aud` values (any match).
`leeway`	`0`	Clock skew in seconds.
`attribute`	`user`	Attribute receiving the claims.

Signature, exp, nbf and iat are verified by firebase/php-jwt (non-numeric time claims are rejected); iss/aud are verified here. Failures return 401 with WWW-Authenticate: Bearer.

⚠️ Security: empty secrets, secrets shorter than the hash output (32/48/64 bytes) and unknown algorithms are rejected at configuration. Load keys from the environment or a secret store, never from source code.

Issuing tokens

JwtIssuer shares the JwtConfig used by the middleware, so issued tokens always match what is verified (algorithm, iss, aud):

use PivotPHP\Security\Jwt\JwtIssuer;

$issuer = new JwtIssuer($config);                     // HS*: signs with the configured secret
// $issuer = new JwtIssuer($config, $privateKeyPem);  // RS*/PS256/ES*/EdDSA: private key required

$token = $issuer->issue(['sub' => $userId, 'role' => 'admin'], ttl: 3600);

iat, nbf and exp come from the clock and iss/aud from the configuration; passing them in the claims throws InvalidConfigurationException. Generate HMAC secrets with bin2hex(random_bytes(32)). Refresh tokens are an application concern (issue a second token with a longer ttl and a typ claim, and check it in your refresh endpoint).

Rate limiting

use PivotPHP\Security\RateLimit\RateLimitConfig;
use PivotPHP\Security\RateLimit\RateLimitMiddleware;
use Symfony\Component\RateLimiter\RateLimiterFactory;

$limiter = new RateLimiterFactory(
    ['id' => 'login', 'policy' => 'sliding_window', 'limit' => 5, 'interval' => '1 minute'],
    $storage,      // e.g. CacheStorage over Redis
    $lockFactory,  // symfony/lock — required for correct counts under concurrency
);

$loginLimit = new RateLimitMiddleware($responseFactory, $limiter, new RateLimitConfig(keyPrefix: 'login:'));

Option (`RateLimitConfig`)	Default	Notes
`keyPrefix`	`''`	One prefix per limit/route group.
`clientIpAttribute`	`client_ip`	Set by `TrustedProxyMiddleware`; falls back to `REMOTE_ADDR`.
`exposeHeaders`	`true`	`X-RateLimit-Limit`/`X-RateLimit-Remaining` on accepted responses.

A fourth constructor argument accepts a custom key resolver (fn (ServerRequestInterface $r): ?string, e.g. an API key). Over the limit: 429 with Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining: 0; the handler is not called. Use one middleware instance per limit (e.g. a stricter one on /login).

⚠️ Security: with InMemoryStorage or without a LockFactory, limits are per process and concurrent requests can exceed them. Use a shared storage and a lock in production.

Testing

composer test           # PHPUnit
composer phpstan        # PHPStan level 9
composer cs:check       # PSR-12
composer quality:check  # all of the above

License

MIT — see LICENSE.

pivotphp / security

Package info

Security

Statistics