README

Enterprise Security Bundle

A standalone Symfony bundle providing reusable security primitives — two-factor authentication, passkeys (WebAuthn/FIDO2), magic-link login, OAuth (Google, Apple, Microsoft), account lockout with rate limiting, session tracking, IP whitelist/blacklist, password policy / history / expiration, per-user password-login control, GDPR self-service account deletion, and a runtime-configurable settings store.

The bundle is framework-agnostic (any Symfony 6.4 / 7.4 app) and is the engine powering the Sylius-flavored ThreeBRS Enterprise Security Plugin. It ships contracts and abstract flows, not a wired-up UI — you bind it to your app's entities, routes and templates. See the integration guide below for how to wire it into a non-Sylius Symfony project.

What the bundle provides

Authentication flows (abstract base controllers — you extend and bind to your app):

• Passkey login + registration (WebAuthn ceremony, browser-side navigator.credentials.*)
• Magic-link login request + verify
• OAuth login + callback + confirm-link (Google, Apple, Microsoft)
• Two-factor authentication setup wizard + recovery challenge

Self-service actions (abstract base controllers): session list / revoke / revoke-others · passkey list / delete · 2FA disable / regenerate recovery codes · OAuth account unlink · account deletion request (with grace period).

Admin actions (abstract base controllers): unlock user (after lockout) · cancel pending account deletion · locked users list.

Security engines & services (use directly via DI):

• 2FA: TotpSecretGenerator, QrCodeGenerator, RecoveryCodeGenerator, TwoFactorEnforcementChecker (+ TwoFactorMode enum), TwoFactorAwareAuthenticationSuccessHandler
• Magic link: MagicLinkTokenGenerator, MagicLinkTokenValidator
• Passkey: PasskeyValidatorFactory, PasskeyCeremonyStepManagerFactory, PasskeyRelyingPartyEntityFactory, PasskeyWebauthnSerializer, SessionPasskeyOptionsStorage
• OAuth: OAuthProviderRegistry + Google / Apple / Microsoft providers, AutoRegistrationPolicy
• Lockout & rate limiting: LockoutPolicy, RateLimitGuard, DynamicRateLimiterFactory
• Sessions: UserAgentParser, SessionFingerprintGenerator, GeoIpLookup (MaxMind + Null impls)
• Passwords: PasswordExpirationChecker, PasswordSimilarityChecker (history), PasswordPolicyFilteringValidator + PasswordPolicy / PasswordHistory Symfony constraints
• Network: CidrMatcher, CidrList constraint, AbstractIpRestrictionChecker / AbstractIpRestrictionListener (whitelist + blacklist enforcement)
• Per-user password-login control: AbstractPasswordLoginCheckListener (forces stronger methods)
• Account deletion (GDPR): GracePeriodCalculator, AbstractDueDeletionsProcessor (anonymization cron engine)
• Settings store: FeatureToggle, PolicyFactory, YamlConfigDefaultsProvider (runtime-configurable, scoped CUSTOMER / ADMIN / GLOBAL)
• Hardening: DeadlineTimingPadding — constant-time response padding against account enumeration
• Twig extensions: MagicLinkExtension, PasskeyExtension, SocialProvidersExtension

Contracts you implement (the bundle ships interfaces; you provide Doctrine-backed impls): persisted-record contracts (MagicLinkRecordInterface, SessionRecordInterface, SocialAccountLinkRecordInterface, CustomerDeletionRequestRecordInterface, PasskeyCredentialRecordInterface), repository contracts, the UserAnonymizerInterface, and per-feature user mixins (TwoFactorAuth*, Lockable*, PasswordExpiration*). See Entities & persistence and Interface implementations.

Mapping to the Sylius plugin features

The Sylius plugin is a complete, production integration of this bundle. Each of its 16 features is built on the bundle primitives below — follow the link for the feature-level narrative, screenshots, config options and defaults.

Requirements

• PHP 8.3+
• Symfony 6.4 or 7.4
• A Doctrine ORM (the bundle itself has no ORM dep, but your app needs one to persist sessions, passkey credentials, magic-link tokens, etc.)
• A user entity implementing Symfony\Component\Security\Core\User\UserInterface

Installation

composer require 3brs/enterprise-security-bundle

Then register the bundle in config/bundles.php:

return [
    // ... your existing bundles
    Scheb\TwoFactorBundle\SchebTwoFactorBundle::class => ['all' => true],
    ThreeBRS\EnterpriseSecurityBundle\ThreeBRSEnterpriseSecurityBundle::class => ['all' => true],
];

The bundle requires scheb/2fa-bundle for the 2FA flows; composer require pulls it in automatically.

Integration guide

The bundle is contract-first: you wire each feature you want. These pages walk through it (start at the top — each builds on the previous):

Running tests

The bundle is self-contained — clone it, install its own deps, and run the tooling directly (no Docker required):

composer install
vendor/bin/phpunit              # 326 unit tests (services + abstract controllers)
vendor/bin/phpstan analyse      # level max, generics + symfony extensions
vendor/bin/ecs check            # coding standard (--fix to apply)

make bundle-tests / make ci exist only in the parent monorepo (they wrap these commands plus the plugin's Behat suite via Docker) — they are not part of this standalone repository.

Reference implementation

The Sylius Enterprise Security Plugin is a complete, production-grade integration of this bundle for Sylius. Browse its src/ for end-to-end examples of:

• All bundle controllers extended with Sylius bindings
• Bundle service interfaces implemented over Doctrine
• Sylius admin UI (form types, templates, menu entries) on top of the bundle's primitives

If you build a Symfony-only or Laminas integration on top of this bundle, please open a PR to link it from this README.

License

MIT