Search by

nowo-tech / api-token-bundle

HecFranco

Personal API tokens for Symfony: hashed lookup tokens with per-module grants, a tenant reach, mandatory expiry, revocation, rate limits and audit events, one Bearer authenticator for every API and a UiKit account and operator UI.

Package info

github.com/nowo-tech/ApiTokenBundle

Documentation

Type:symfony-bundle

pkg:composer/nowo-tech/api-token-bundle

Fund package maintenance!

HecFranco

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.2.0 2026-11-18 22:57 UTC

README

CI Packagist Version Packagist Downloads License PHP Symfony GitHub stars Coverage

⭐ Found this useful? Install it from Packagist and give it a star on GitHub: it helps us maintain and improve the project.

Personal API tokens for Symfony: hashed lookup tokens with per-module grants, a tenant reach, mandatory expiry, revocation, rate limits and audit events, one Bearer authenticator for every API and a UiKit account and operator UI.

Standard Symfony by default, DDD / hexagonal opt-in: zero configuration in a standard project; public ports are interfaces and value objects, bundle-owned tables are mapped in XML and referenced by id, the bundle never flushes your EntityManager.

🚧 Status: S1 core, first tag 0.1.0 pending its security audit. The package is built slice by slice from its design contract (docs/CONTRACT.md, 221-A). S1 ships the token store, format and hash, the issuer, revoker, query and authenticator services, the module registry and the issue / purge-expired commands for standard and DDD hosts; the firewall, pages, bridges and HTTP API land with the next slices in docs/ROADMAP.md.

📋 Compatible with Symfony 7.4, 8.0 and 8.1 · PHP 8.2+ (Symfony 8.x requires PHP 8.4+)

FrankenPHP Friendly Worker Mode

This bundle is FrankenPHP worker mode friendly.

API Token Bundle demo: bundle status, configuration parameters and the Symfony WebProfiler

The demo shows the bundle registered, its container parameters and the MySQL connection.

Features

S1 (today) covers the token store, format, issuer, revoker, query and authenticator; the rest follows the roadmap.

  • FrankenPHP worker mode, kernel kept alive and not reset: no request state in services; a worker test (one kernel, 2,000 requests, two owners, revoke mid-run, flat memory) and the owner status read fresh on every request (docs/FRANKENPHP-WORKER-AUDIT.md).

  • Personal tokens issued to an owner (referenced by id): name, per-module grants (level + flags), a tenant reach, mandatory expiry (max 365 days), revoke, revoke all, erasure. Hash at rest (SHA-256), shown once, non-secret lookup id, CRC32 checksum for typo checks and secret scanning (nwt_<lookup>_<secret><checksum>).

  • One Bearer authenticator for Symfony firewalls (stateless), constant-time verification, owner status re-checked on every request, principal stamped on the request only.

  • Module registry: grants as data ({tasks: read, mcp: on + destructive}), modules from config and bridges; a token only narrows the person's real permissions, never widens them.

  • Security controls: one rate-limit bucket per token across every API, write sub-budget, failed tokens per IP, re-authentication before issue (password, or MFA through AuthKit), framing and no-store headers, audit events after commit (ids only).

  • UI on UiKit + FormKit: account page (list, New token dialog shown once, revoke, revoke all) and operator page.

  • Public API GET / DELETE <prefix>/tokens/v1/self with OpenAPI; optional leak-report endpoint (off by default).

  • Bridges (inside this bundle, active when installed): TaskBoard, Wiki, McpKit principals and rate limiters, HttpLog credential stamp, UserKit eraser / export / sessions listener, AuditKit, AuthKit re-auth.

Installation

composer require nowo-tech/api-token-bundle

See docs/INSTALLATION.md. Nothing is registered while nowo_api_token.enabled is false.

Requirements

  • PHP >= 8.2, < 8.6 (Symfony 8.x needs PHP 8.4+)
  • Symfony 7.4, 8.0 or 8.1
  • Doctrine DBAL 4 (doctrine/dbal ^4.0) and ORM 3.3+ (doctrine/orm ^3.3); DoctrineBundle once the bundle is enabled

Configuration

# config/packages/nowo_api_token.yaml
nowo_api_token:
    enabled: false

Every key of the contract is already accepted (strict tree): docs/CONFIGURATION.md.

Demo

demo/symfony8: Symfony 8.1, FrankenPHP worker mode, MySQL, UiKit shell, Web Profiler, Twig Inspector and Hot Reload, on http://localhost:8221 (make -C demo up). Playwright e2e: make -C demo/symfony8 test-e2e; refresh the screenshot above with make -C demo/symfony8 demo-screenshots. See docs/DEMO-FRANKENPHP.md.

Documentation

Additional documentation

Tests and coverage

make test               # PHPUnit in Docker
make test-coverage-100  # fails below 100 % of src/
make release-check      # every gate, demo included
  • PHP: 100 % of src/ (gate in CI).

License

MIT. See LICENSE.

Author

Created by Héctor Franco Aceituno at Nowo.tech.