README

This documentation follows the coding conventions reflected throughout the codebase.

Project Overview

equidna/domain-token-auth is a Laravel package that provides secure, domain-scoped opaque token authentication. It issues cryptographically random tokens tied to a functional domain, a polymorphic owner model, a set of roles and fine-grained actions, optional custom data payload, and an optional validity window. Tokens are stored only as SHA-256 hashes; the plain-text value is shown exactly once at issuance time.

Who it is for:

• Laravel application developers who need API token authentication without depending on Laravel Sanctum or Passport.
• Multi-tenant SaaS platforms that must ensure a token issued for one tenant cannot be used in another tenant's context (via optional equidna/bee-hive integration).
• Integrators building machine-to-machine token pipelines with per-domain authorization rules.

Main use cases:

• Issuing short-lived or long-lived tokens for human users, application clients, services, or partner integrations, each in its own named domain.
• Protecting routes with per-domain middleware (domain-token:{domain}).
• Enforcing fine-grained action authorization with wildcard support (users.*, *).
• Attaching and consuming domain-specific metadata through token data after authentication.
• Revoking tokens immediately without modifying the consuming request flow.

Project Type & Tech Summary

Quick Start

1. Install via Composer:

   composer require equidna/domain-token-auth

2. Publish the configuration file:

   php artisan vendor:publish --tag=domain-token-auth:config

3. Publish and run migrations:

   php artisan vendor:publish --tag=domain-token-auth:migrations
   php artisan migrate

4. Implement TokenOwner on your owner model and add the HasDomainTokens trait:

   use Equidna\DomainTokenAuth\Concerns\HasDomainTokens;
   use Equidna\DomainTokenAuth\Contracts\TokenOwner;
   use Illuminate\Database\Eloquent\Model;
   
   class User extends Model implements TokenOwner
   {
       use HasDomainTokens;
   }

5. Configure your domains in config/domain-token-auth.php.

6. Protect routes with the domain-token middleware:

   Route::middleware('domain-token:user')->group(function () {
       Route::get('/profile', ProfileController::class);
   });

7. Issue tokens via the facade or Artisan command:

   use Equidna\DomainTokenAuth\Facades\DomainToken;
   
   $issued = DomainToken::issue(
      domain: 'user',
      owner: $user,
      roles: ['admin'],
      data: ['client' => 'mobile', 'region' => 'mx']
   );
   $plainToken = $issued->plainTextToken; // show once

8. Consume authenticated token data in protected routes:

   Route::middleware('domain-token:user')->get('/me', function () {
      return [
         'client' => DomainToken::data('client'),
         'all_data' => DomainToken::data(),
      ];
   });

For full details, see Deployment Instructions.

Documentation Index

• Deployment Instructions
• API Documentation
• Routes Documentation
• Artisan Commands
• Tests Documentation
• Architecture Diagrams
• Monitoring
• Business Logic & Core Processes
• Open Questions & Assumptions

License

MIT - see LICENSE.