Search by

adachsoft / auth-contracts

Arkadiusz Adach

Framework-independent password login, server-side sessions and credential management that resolve a caller to an access-control account.

Package info

gitlab.com/a.adach/auth-contracts

Issues

pkg:composer/adachsoft/auth-contracts

Statistics

Installs: 31

Dependents: 2

Suggesters: 0

Stars: 0

v0.2.0 2026-11-17 11:17 UTC

This package is auto-updated.

Last update: 2026-11-17 10:19:58 UTC


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