README

This documentation follows the project's Coding Standards and PHPDoc Style Guide.

Project Overview

ometra/caronte-sdk is a Laravel package that integrates any Laravel host application with the Caronte centralised authentication server. It handles:

• JWT user authentication (login, logout, 2FA, password recovery)
• Automatic token validation and renewal on every request
• Role-based access control tied to a central role registry
• Application API permission declaration and application-token middleware
• A ready-to-use management UI for users and roles
• A server-side provisioning wrapper for Caronte tenant provisioning
• Server-to-server inter-app communication via application tokens

Primary audience: Internal development teams adding Caronte authentication to a Laravel application.

Project Type & Tech Summary

Quick Start

1. Install the package

   composer require ometra/caronte-sdk

2. Publish the configuration

   php artisan vendor:publish --tag=caronte:config

3. Add the three required environment variables

   CARONTE_URL=https://your-caronte-server.example.com
   CARONTE_APP_CN=your-app-canonical-name
   CARONTE_APP_SECRET=a-secret-at-least-32-characters-long

   Apps that belong to an internal application group can also share user tokens and app-to-app credentials:

   CARONTE_APPLICATION_GROUP_ID=core-suite
   CARONTE_APPLICATION_GROUP_SECRET=a-group-secret-at-least-32-characters-long

4. Run migrations (creates local user cache tables)

   php artisan migrate

5. Protect routes with the provided middleware:

   Route::middleware(['caronte.session', 'caronte.roles:admin'])->group(...);

6. Sync your configured roles with the Caronte server:

   php artisan caronte:roles:sync

7. Declare API permissions if external applications will consume your API:

   'permissions' => [
       'invoices.read' => 'Read invoices',
       'invoices.write' => 'Write invoices',
   ],

   php artisan caronte:permissions:sync

8. Protect external API routes with application-token middleware:

   Route::middleware(['caronte.app-token', 'caronte.app-permissions:invoices.read'])->get(...);

9. Visit the app-local management UI at /caronte/management (default).

Token Types

• User JWTs authenticate humans and are checked by caronte.session.
• User JWTs are read from phase-2 top-level claims first: sub, aud, jti, tenant_id, roles, metadata, app_id, and token_audience. The legacy nested user claim remains supported as a fallback.
• Logout routes in the SDK may be called with GET or POST, but the SDK always calls the Caronte server logout endpoint with POST.
• App-to-app credentials use X-Application-Token and are checked by caronte.application.
• Application-group credentials use base64(group_id:application_group_secret).
• ApplicationTokens authenticate external applications consuming this app's API and are checked by caronte.app-token plus caronte.app-permissions:*.

See Deployment Instructions for the full setup guide.

Documentation Index

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