adachsoft / auth-contracts
Framework-independent password login, server-side sessions and credential management that resolve a caller to an access-control account.
Requires
- php: ^8.3
- adachsoft/access-control-contracts: ^0.1
- adachsoft/collection: ^3.0
- psr/clock: ^1.0
Requires (Dev)
- adachsoft/php-code-style: ^0.7.2
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
- phpunit/phpunit: Required to run the repository contract tests in testing/.
Provides
None
Conflicts
None
Replaces
None
README
adachsoft/auth-contracts provides framework-independent password authentication, server-side session management, and credential management. It resolves a login session to an AccountId from adachsoft/access-control-contracts, separating identity verification from authorization.
The library does not handle HTTP requests, cookies, or account storage. Applications supply repository implementations and choose how session tokens are transported.
Features
- Login and password verification with generic invalid-credential responses.
- Opaque random session tokens and long-lived service API keys; only token hashes are stored.
- Session expiry, optional idle expiry, logout, and account-wide revocation.
- Configurable password policy, failed-attempt lockout, and password hash upgrades.
- Interfaces for credential storage, session storage, password hashing, token generation, and PSR-20 clocks.
- In-memory repositories for development and tests; repository contract tests are provided in
testing/.
Requirements and Installation
Requires PHP 8.3 or later.
composer require adachsoft/auth-contracts
Usage
<?php
declare(strict_types=1);
use AdachSoft\AccessControlContracts\ValueObject\AccountId;
use AdachSoft\AuthContracts\Dto\AuthPolicyDto;
use AdachSoft\AuthContracts\Factory\AuthFactory;
use AdachSoft\AuthContracts\InMemory\InMemoryCredentialRepository;
use AdachSoft\AuthContracts\InMemory\InMemorySessionRepository;
$credentials = new InMemoryCredentialRepository();
$sessions = new InMemorySessionRepository();
$policy = new AuthPolicyDto(sessionTtlSeconds: 8 * 3600);
$manager = AuthFactory::createCredentialManager($credentials, $sessions, $policy);
$authentication = AuthFactory::createAuthenticationService($credentials, $sessions, $policy);
$manager->create(new AccountId('anna'), 'anna@example.com', 'a long password');
$login = $authentication->login('anna@example.com', 'a long password');
// Send this bearer token to the client using your application's secure transport.
$token = $login->token;
$accountId = $authentication->authenticate($token)->accountId;
$authentication->logout($token);
See the examples for handling authentication failures and integrating a persistent repository.
API keys for services
API keys let a service authenticate as an account without a password-based login or a browser session. The key inherits the account's existing roles; it has no separate permission scopes.
<?php
declare(strict_types=1);
use AdachSoft\AccessControlContracts\ValueObject\AccountId;
use AdachSoft\AuthContracts\Dto\ApiKeyPolicyDto;
use AdachSoft\AuthContracts\Factory\AuthFactory;
use AdachSoft\AuthContracts\InMemory\InMemoryApiKeyRepository;
$apiKeyService = AuthFactory::createApiKeyService(
new InMemoryApiKeyRepository(),
new ApiKeyPolicyDto(prefix: 'ak_'),
);
$created = $apiKeyService->create(new AccountId('workflow'), 'workflow integration');
// Store this bearer secret securely; it is returned only by create().
$oneTimeToken = $created->token;
$accountId = $apiKeyService->authenticate($oneTimeToken)->accountId;
$apiKeyService->revoke($created->apiKey->id);
CreatedApiKeyDto exposes the clear token once. The repository stores only its SHA-256 hash and the last four characters. The in-memory repository is intended for tests and short-lived processes; production applications should provide a persistent ApiKeyRepositoryInterface implementation.
Integration
Implement CredentialRepositoryInterface and SessionRepositoryInterface for your storage backend, and ApiKeyRepositoryInterface when storing service keys. PasswordHasherInterface and TokenGeneratorInterface allow replacing the defaults; a PSR-20 ClockInterface can be supplied to the factory. The resulting AccountId can be passed to your access-control services.
Session and API key tokens are bearer secrets: use HTTPS and, in browser applications, consider secure, httpOnly cookies. HTTP transport, CSRF protection, and rate limiting by client or IP are responsibilities of the host application.
Development
composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse
vendor/bin/rector process --dry-run
vendor/bin/php-cs-fixer fix --dry-run
Documentation
- Reference: configuration, API, formats and commands in full
- Password login