waffle-commons / security

0.1.0-beta7 2026-11-05 01:39 UTC

Requires

• php: ^8.5
• psr/container: ^2.0
• psr/http-factory: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0
• waffle-commons/contracts: 0.1.0-beta7
• waffle-commons/utils: 0.1.0-beta7

Requires (Dev)

• carthage-software/mago: ^1.59
• cyclonedx/cyclonedx-php-composer: ^6.2
• igor-php/igor-php: ^0.10.1
• nyholm/psr7: ^1.8
• php-mock/php-mock-phpunit: ^2.16
• phpunit/phpunit: ^12.5
• vimeo/psalm: ^6.20

MIT

• Leslie Petrimaux

Published on Packagist.org on 2026-11-05 02:00 UTC

README

Waffle Security Component

Release: 0.1.0-beta7  |  CHANGELOG.md

Hierarchical Attribute-Based Access Control (ABAC) for the Waffle Framework with a fail-closed default (SEC-02), a fully stateless HMAC CSRF subsystem bound to a per-browser anonymous SID (SEC-01 option C), and a container decorator (SecureContainer) that hardens service retrieval. Security is enforced by PSR-15 middleware sitting between routing and dispatch.

🆕 Beta-7 — rate limiting (NET-01)

• Middleware\RateLimitMiddleware keys each call by the authenticated subject, else by the client IP resolved behind trusted proxies, and answers 429 with Retry-After when the bucket is empty. Enforced responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.
• RateLimit\RateLimiter implements RateLimiterInterface (a token bucket) over the shared LimiterStateStorageInterface; waffle-commons/data's RedisLimiterStateStorage keeps the buckets in Redis, so every worker and every instance shares them.
• A storage outage follows on_storage_failure (RateLimit\StorageFailureMode): open by default, which lets the call through unenforced with a warning, or closed, which answers 503. Given a MetricsRegistryInterface, RateLimiter counts each outage in waffle_ratelimit_storage_errors_total{mode} (RateLimiter::STORAGE_ERRORS_METRIC).

How-to: Rate-limit requests.

🆕 Beta-1 foundations (still current)

• Fail-closed ABAC — SecureContainer::analyze() rejects any action without a #[Voter] unless explicitly tagged #[PublicAccess]. Missing policy is denial, not silent allow.
• Stateless HMAC CSRF — CsrfTokenManager issues self-validating signed tokens; no cache, no Redis, no PHP sessions. The HMAC binds to (id, sessionId) so a token cannot be replayed across forms or across browsers.
• AnonymousSessionMiddleware — issues the WAFFLE_SID cookie (32 random bytes, base64url, 30-day Max-Age, HttpOnly, SameSite=Lax, Secure on HTTPS) that anchors CSRF binding. Stateless across requests (FrankenPHP-safe).

📦 Installation

composer require waffle-commons/security

🧱 Surface

Class	Role
Waffle\Commons\Security\Security	SecurityInterface implementation. Reads waffle.security.level from ConfigInterface at construction (defaults to 1).
Waffle\Commons\Security\Abstract\AbstractSecurity	Shared base storing the configured security level and providing the analyze() walk.
Waffle\Commons\Security\Middleware\SecurityMiddleware	PSR-15 middleware that runs SecureContainer::analyze($controller, $method) — fail-closed ABAC.
Waffle\Commons\Security\Middleware\AnonymousSessionMiddleware	PSR-15 middleware that issues / reuses the WAFFLE_SID cookie and publishes the SID as the _anon_sid request attribute. Required upstream of CsrfMiddleware.
Waffle\Commons\Security\Middleware\CsrfMiddleware	PSR-15 middleware enforcing #[RequiresCsrfToken]. Validates the signed token against (id, sessionId).
Waffle\Commons\Security\Csrf\CsrfTokenManager	final readonly stateless HMAC-SHA256 token manager. Constructor takes a 32+ byte secret.
Waffle\Commons\Security\Container\SecureContainer	Decorator over Waffle\Commons\Contracts\Container\ContainerInterface. Beta-1: analyze() is now fail-closed — empty voter list ⇒ SecurityException(403) unless #[PublicAccess] is present.
Waffle\Commons\Security\Rule\Level1Rule … Level10Rule	The ten built-in security levels (1 = public … 10 = god-mode).
Waffle\Commons\Security\Middleware\RateLimitMiddleware	PSR-15 rate limiting (Beta-7, NET-01): 429 + Retry-After on an empty bucket, RateLimit-* headers on enforced responses.
Waffle\Commons\Security\RateLimit\RateLimiter	RateLimiterInterface token bucket over the shared LimiterStateStorageInterface, with a StorageFailureMode (open / closed).

🚦 The security ladder

Each LevelNRule lives in src/Rule/. Levels are integer-coded via Waffle\Commons\Contracts\Constant\Constant::SECURITY_LEVEL1 … SECURITY_LEVEL10. The kernel reads waffle.security.level from the application's app.yaml and constructs Security with that level.

# config/app.yaml
waffle:
  security:
    level: 5  # Authenticated user with elevated permissions

use Waffle\Commons\Security\Security;
use Waffle\Commons\Contracts\Config\ConfigInterface;

$security = new Security($config); // reads waffle.security.level
$security->analyze($controller);   // throws SecurityExceptionInterface if rules fail

The exact constructor, verbatim from src/Security.php:

final class Security extends AbstractSecurity
{
    public function __construct(ConfigInterface $cfg)
    {
        $this->level = $cfg->getInt(key: 'waffle.security.level', default: 1) ?? 1;
    }
}

🏷️ Levels are application-wide

The level is one setting for the whole application, waffle.security.level: there is no attribute that declares a level on a controller (there is no #[Rule] attribute). Security::analyze() walks the rule ladder up to the configured level and throws a SecurityExceptionInterface, which the ErrorHandlerMiddleware renders as an RFC 7807 403. Per-action authorization is the job of #[Voter], below.

🚪 Fail-closed ABAC + #[PublicAccess] (Beta-1 / SEC-02)

A controller action without any #[Voter] is now denied with HTTP 403 unless it explicitly carries #[PublicAccess]. Forgetting to attach a voter no longer silently grants access — missing policy is treated as denial.

use Waffle\Commons\Contracts\Security\Attribute\PublicAccess;
use Waffle\Commons\Routing\Attribute\Route;

final class HealthController
{
    #[Route(path: '/health', name: 'health')]
    #[PublicAccess]
    public function ping(): Response { /* … */ }
}

A method-level #[Voter] always wins over a class-level #[PublicAccess], so mixed-policy controllers stay safe.

🛂 CSRF — stateless signed double-submit with per-browser binding (Beta-1 / SEC-01)

CsrfMiddleware enforces #[RequiresCsrfToken] using HMAC-signed self-validating tokens. No cache, no Redis, no PHP sessions. Wire format (binary, then base64url):

nonce (16 bytes) || expiresAt (8 bytes BE uint64) || HMAC-SHA256(nonce || expiresAt || id || sessionId, secret)

Two pieces of context are folded into the HMAC:

• the logical id (e.g. form:login) — prevents cross-form replay;
• the anonymous session id (the WAFFLE_SID cookie value, published as the _anon_sid request attribute by AnonymousSessionMiddleware) — prevents cross-browser replay.

Operational requirements:

1. Provide a 32+ byte signing secret. Production refuses to boot without one. Config key waffle.security.csrf.secret, with env fallback WAFFLE_CSRF_SECRET.
2. Wire AnonymousSessionMiddleware before CsrfMiddleware in the pipeline. The skeleton's AppKernelFactory does this for you.

# config/app.yaml
waffle:
  security:
    level: 5
    csrf:
      secret: '%env(WAFFLE_CSRF_SECRET)%'

$csrfTokenManager = new CsrfTokenManager(secret: $csrfSecret);
$container->set(CsrfTokenManagerInterface::class, $csrfTokenManager);

$stack
    ->add(new AnonymousSessionMiddleware())
    ->add(new CoreRoutingMiddleware($router))
    ->add(new CsrfMiddleware($csrfTokenManager))
    ->add(new SecurityMiddleware($secureContainer, $logger));

🛡️ SecureContainer

Waffle\Commons\Security\Container\SecureContainer wraps any ContainerInterface and runs the security check before get($id) returns the service — preventing low-privilege code paths from pulling sensitive services out of the container.

analyze($controller, $method) is fail-closed as of Beta-1: an empty #[Voter] list throws SecurityException(403) unless the target carries #[PublicAccess]. Otherwise every voter must approve (consensus pattern) for the call to proceed.

🐘 PHP 8.5 features used

• Typed constructors throughout (Security takes ConfigInterface, level resolution is ?int ?? 1).
• Typed integer security levels declared as typed constants in Constant::SECURITY_LEVEL*.
• #[Voter] / #[RequiresCsrfToken] / #[PublicAccess] attributes from the contracts package.
• final readonly class CsrfToken value object; final readonly class CsrfTokenManager (no instance state across requests).
• #[\SensitiveParameter] on the CSRF signing secret to suppress its value from stack traces and error reports.

🧭 Architectural boundary (mago guard)

An active dependency perimeter is enforced on every CI run by vendor/bin/mago guard (bundled into composer mago; zero baselines). The rules live in mago.toml under [guard.perimeter] — a forbidden use statement fails the build, not a reviewer.

Production code under Waffle\Commons\Security may depend only on:

• Waffle\Commons\Security\** — itself
• Waffle\Commons\Contracts\** — the shared contracts package (#[PublicAccess], #[Voter], RequiresCsrfToken, the CSRF constants, etc.)
• Waffle\Commons\Utils\** — the ClassParser reflection helper used by SecureContainer
• Psr\** — PSR interfaces (PSR-7 / PSR-15)
• @global + Psl\** — PHP core and the PHP Standard Library

Test code under WaffleTests\Commons\Security is unrestricted (@all). Structural rules are guarded too: interfaces must be named *Interface, Exception\** classes must end in *Exception, and any Enum\** namespace may hold only enum declarations.

Contract-first, component-agnostic by construction: components compose through waffle-commons/contracts (plus the explicitly-permitted utils), never ad-hoc through one another.

🧪 Testing

docker exec -w /waffle-commons/security waffle-dev composer tests

📚 Documentation

Central framework docs live in the waffle-commons/documentation repository:

• Reference: security
• How-to: Rate-limit requests
• Explanation: Fail-closed ABAC
• Explanation: CSRF double-submit
• Explanation: Two-layer authorization

📄 License

MIT — see LICENSE.md.