README

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.

🚧 Status: S0 scaffold, no release yet. The package is built slice by slice from its design contract (docs/CONTRACT.md, 221-A). S0 ships the bundle class, the strict configuration tree and every quality gate; the features below land with the 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+)

This bundle is built for FrankenPHP worker mode with the kernel kept alive and not reset between requests: no request state in services, a worker test (one kernel, 2,000 requests) from the first slice.

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.

Features (planned, see the roadmap)

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.

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.

Documentation

Installation
Configuration
Usage (incl. using it from a DDD / hexagonal application)
Roadmap (slices and open questions)
Contract
Security
FrankenPHP worker audit
Demo with FrankenPHP
Upgrading · Changelog · Release
Architecture · PSR · Spec-driven development · Spec Kit
Contributing · GitHub CI · Engram

Requirements

PHP >= 8.2, < 8.6
Symfony 7.4, 8.0 or 8.1

Demo

demo/symfony8: Symfony 8.1, FrankenPHP worker mode, MySQL, on http://localhost:8221 (make -C demo up).

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.

nowo-tech / api-token-bundle

Package info

Security

Fund package maintenance!

Statistics