README

Fight AccessControl

Framework-neutral PHP identity and authorization for applications that own their infrastructure. Manage Users, Agent credentials, sessions, Roles, Permissions and account lifecycles without tying business rules to a framework.

Install · Integration · Capabilities · Contributing · Changelog

Release and installation

Release: v0.8.0

Status: published.

Requires PHP 8.5+ and Fight Common ^1.3 (resolved by Composer).

composer require johnnickell/fight-access-control:"~0.8.0"

Release overview · Tagged documentation

GitHub publication and Packagist source/dist references are verified for v0.8.0. The immutable tagged README retains its original preparation status; the release overview here records the verified publication. Registry availability is not proof of installation or qualification in your application.

The constraint stays on this minor line. Pre-v1 minors can break API and persistence contracts: read the Changelog and the target release overview before upgrading. Only the current contract is supported; there are no compatibility defaults, historical readers or package migration/backfill routes (policy).

Using develop or a release branch? Relative guides describe the checked-out code, including prepared changes. Use the matching published tag's documentation for an installed package. Installing this library does not supply endpoints, a database schema, a login UI, framework bindings or production configuration.

Integrate with your application

Core dependencies point inward: Application → Domain. Consumers supply infrastructure through package interfaces. Future optional permission/framework integrations are approved under capability-first src/Adapter, pointing inward through Application; they are planned, not implemented. Domain/Application retain their DDD structure; no framework bindings or production configuration are installed today.

This package owns	Your application owns
Identity, credentials, sessions and account state	Persistence, schema and repository implementations
Commands, Queries, Events and use-case coordination	Framework wiring, transports, HTTP responses and UI
Role/Permission rules and authenticated authority	Entry-point authorization, abuse controls and request context
Recoverable credential-delivery state and worker contracts	Keys, ciphers, providers, queues and scheduling

Choose a capability below. Read its composition guide and implement its required Domain repositories and Application ports. Do not treat the test doubles as production adapters.
Wire one atomic boundary. Supply Fight Common's TransactionalUnitOfWork on the shared persistence connection. Its commitTransactional() callback encloses package-owned atomic work; the deprecated standalone UnitOfWork contract is not supported. Follow the selected guide's concurrency, audit and failure semantics.
Bind fresh request authority. For User requests, supply AuthenticationContextProvider and create a new CurrentPrincipalProvider with AuthoritativePrincipalResolver per request. After resolving one authentication path, build SecurityContext from exactly one authenticated User or Agent principal. Never accept caller-supplied Role or Permission snapshots as authority; Agents have direct Permissions, not Roles.
Run recovery independently of notifications. Protect discovery and worker dispatch; schedule bounded recovery even when post-commit events trigger immediate work. Credential delivery is at-least-once, not exactly-once.
Qualify the real composition. Exercise authorization, transactions, concurrent writers, restart, keys and provider idempotency with your actual adapters. Package tests and a published version do not qualify a consumer deployment.

Choose a capability

Capability	Start here
User invitation, activation and credential delivery	Delivery composition · Expired-work cleanup
Optional User registration and administrator recovery	Registration · Recovery
Login, refresh, logout, passwords and current authority	Behavioral contract · Vocabulary and boundaries
Roles, Permission tiers and managed policy	Permission tiers · Operation outcomes
Recoverable Agent provisioning, rotation and delivery	Agent integration · Conformance and evidence
Agent profiles and protected MCP Tools	Profile Tools · MCP authorization
Permission-based Feature flags	Declarations · Provisioning · Preparation · Availability · Management · Retirement
Consumer-owned OpenAPI documents	Opt-in schema components

Feature availability is not authorization for the underlying action. Registration exposure and enablement are consumer choices. MCP support supplies neutral authorization and profile Tools, not a hosted server or endpoint.

Released in v0.8.0

This release includes breaking Role caller revisions and recovery composition requirements, plus operation-outcome and managed-policy consistency changes. Custom Role rename/remove bind the displayed expected_revision; stale intent requires a fresh read and reconfirmation, not automatic token substitution. See Role composition, operation outcomes and the v0.8.0 integration overview. These changes are not part of published v0.7.0.

Development and contributions

Docker is required for the repository-owned PHP 8.5 tooling. From a clone:

git clone https://github.com/johnnickell/fight-access-control.git
cd fight-access-control
./bin/build

./bin/build builds the isolated fight-access-control image, resolves latest-compatible dependencies into the ignored lockfile with composer update, then runs the canonical quality gate: syntax, planning, PHPCS, PHPStan, architecture, Rector, PHPUnit, exact statement coverage and documentation links. No application server or database is required for package tests. After that initial setup, focused commands include:

./bin/phpunit
./bin/phpcs
./bin/phpstan
./bin/planning-check
./bin/documentation-check

Start with CONTRIBUTING and AGENTS for branch selection, the Task Board, independent review and verification. Optional Fight Agent OS/Pi users can use /skill:next for a recommendation, then explicitly invoke /skill:build TASK-NNNNN for approved work. See the workflow binding; private tooling is not required. Keep scratch and evidence in ignored .runs/ subdirectories.

Releases

Follow the release runbook to update every current-version surface together and validate it with ./bin/release check-docs <version>. ./bin/release certify <version> additionally requires a clean committed candidate and records exact-commit local evidence; it never commits, merges, tags, pushes or publishes.

Version selection, independent acceptance, human signing, publication and consumer deployment remain distinct steps. A README version or a dated Changelog section is not publication proof. The separate stability review is still required before v1.0.0.

Security and license

Report suspected vulnerabilities privately through SECURITY.md, not public issues or pull requests. Fight AccessControl is available under the MIT License.

johnnickell / fight-access-control

Package info

Security

Statistics