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

Delivery closeout belongs to Land: accepted TASK/current-doc closeout, exact live PR validation and eligible owned local Git/Docker/storage retirement. Human merge remains separate, without a tracked pending-merge queue or recurring post-merge planning chore. Historical acceptance/ publication checkpoints remain evidence; planning stays offline and releases stay separate.

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. Optional HTTP Permission admission now uses capability-first src/Adapter, pointing inward through Application, with separately qualified Slim/Yii 3 route composition and optional native Symfony admission and native CodeIgniter 4 before-filter/JSON-error composition. Native Laravel middleware has independent Review and behavioral QA acceptance for TASK-00105; consumer deployment qualification remains separate. Domain/Application retain their DDD structure; no consumer bindings or configuration are installed. Maintainers placing classes or naming collaborators should use the checkout-local architecture target and naming rules. These codify approved EPIC-00015 guidance. Agent MCP presentation/bindings now live in Adapter/Mcp/{Tool,Resource,Skill}/Agent (current composition); authentication, Permission policy and continuation stay inward. Agent authentication, credential lifecycle, delivery, maintenance and continuation now have cohesive Application homes, alongside Feature Discovery and authorization Admission; see the current composition map. User secret-bearing operations now use direct synchronous authentication, session, password and email-confirmation owners, without the retired broad service. Recoverable Agent issuance now uses registered void ProvisionAgent and RotateAgentCredential Commands plus independent authorized outcome Queries, including delayed/restarted execution; see current composition. No direct issuance service/result facade or publication warning remains. These unreleased changes supply no blanket persistence/framework support or consumer qualification.

The independently persisted AgentCredentialOperation now has its own Domain/Application aggregate home. Status, scheduler and maintenance readers inject AgentCredentialOperationReadRepository; material-bearing writers use the separate AgentCredentialOperationRepository with their existing UoW. Update imports/named arguments directly; wire shapes and atomic Agent/operation cancellation, cohort/restoration and recovery behavior are unchanged. See the operation ownership map. TASK-00114's integrated candidate with TASK-00112's advanced authentication base has independent Review ACCEPT and nonvisual QA PASS. Current delivery results are in its canonical Land handoff and PR #158. The integrated TASK-00182 Command conversion has independent Review ACCEPT and nonvisual QA PASS; publication and final delivery verification were pending at closeout. Current results are in its canonical Land handoff and actual PR; no consumer qualification is claimed.

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	Direct synchronous composition · 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 capabilities	Profile Tools · Tool authorization · Resource authorization · Skill authorization · Current continuation
Optional HTTP Permission admission (Unreleased)	Shared/Slim/Yii 3 composition · Native Symfony composition · Native CI4 composition · Native Laravel composition
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.

See local Docker, worktree and build-cache operations for explicit main/worktree selection, guarded teardown and fresh versus reused gate evidence.

johnnickell / fight-access-control

Package info

Security

Statistics