Download the PHP package codemonster-ru/security without Composer

codemonster-ru/security

codemonster-ru/security is a set of reusable security components for the Annabel ecosystem:

• CSRF protection (VerifyCsrfToken) with a token from POST (_token) and/or headers (X-CSRF-TOKEN, X-XSRF-TOKEN)
• Rate limiting / brute-force protection (ThrottleRequests) with a configurable key and storage layer

No Laravel/Symfony dependencies. Compatible with codemonster-ru/http and codemonster-ru/session.

Installation

For monorepo development, you can use a path repository (as in annabel-skeleton/composer.local.json).

Quick Start (Annabel)

Annabel loads providers from bootstrap/providers/*.php.

1. Add a provider:

bootstrap/providers/SecurityServiceProvider.php

2. Add config:

config/security.php

By default, CSRF is enabled globally (via Kernel::addMiddleware), but throttling is not (so as not to surprise all routes).

CSRF

How is it checked?

Codemonster\Security\Csrf\VerifyCsrfToken:

• Skips methods from except_methods (GET/HEAD/OPTIONS by default)
• By default, does not validate JSON requests (if Accept: application/json) to avoid breaking the API
• Validates the token:
  • In the body: _token (configured via input_key)
  • Or in the headers: X-CSRF-TOKEN, X-XSRF-TOKEN
• On error, returns 419 (application/json or text/plain)

Security note: if your API uses cookies or other stateful auth, enable verify_json to protect JSON POST/PUT/PATCH/DELETE requests too.

Helpers

The package autoloads helpers:

• csrf_token(): string
• csrf_field(): string - ready-to-use <input type="hidden" name="_token" ...>

Example in the form:

Throttle / Rate limiting

Codemonster\Security\RateLimiting\ThrottleRequests:

• stores the attempt counter in storage via ThrottleStorageInterface
• the package contains at least one implementation: SessionThrottleStorage (without a database)
• for shared storages, prefer atomic increments (implement AtomicThrottleStorageInterface) to avoid race conditions
• returns 429 + headers:
  • Retry-After (seconds)
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • RateLimit-Limit
  • RateLimit-Remaining
  • RateLimit-Reset (unix timestamp)

Best practices

• Enable verify_json for stateful APIs (cookies, sessions) to avoid CSRF bypasses.
• Configure trusted_proxies when running behind a proxy; otherwise X-Forwarded-For should be ignored.
• Use database or Redis storage in multi-node deployments to avoid per-node limits.

Trusted proxies

If your app sits behind a reverse proxy or load balancer, configure trusted_proxies so the middleware can safely use X-Forwarded-For or X-Real-IP. When trusted_proxies is empty, only REMOTE_ADDR is trusted. Do not trust these headers unless the proxy is under your control.

Database storage (MySQL)

If you want atomic throttling across multiple nodes, use the database storage:

Register the package migrations path (Annabel):

Without Annabel/Database:

1. Copy migrations from vendor/codemonster-ru/security/migrations into your project migrations directory.
2. Run your migrations as usual.

Custom table name example:

Note: the bundled migration reads security.throttle.table to decide which table to create.

If you don't use migrations, create the table manually (adjust name if needed):

Redis storage

Provide a Redis client and set storage to redis:

Connection to the route

Router/Kernel in Annabel supports route-level middleware:

Preset example:

Restriction key

By default, the key is built from ip|method|path and hashed (sha1).

You can pass a callable instead of a role string:

Tests

Optional E2E env (tests are skipped if not set):

• MySQL: MYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE, MYSQL_USERNAME, MYSQL_PASSWORD
• Redis: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DB

Author

Kirill Kolesnikov

License

MIT