README

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

Project Overview

ometra/caronte-sdk is a Laravel package that integrates a host Laravel application with a centralized Caronte authentication server.

Main capabilities:

• User authentication via Caronte (login, logout, 2FA, password recovery)
• User token validation and renewal middleware
• Management UI for users and role synchronization
• Suite access management for application groups with non-root role synchronization
• Application-to-application authentication middleware
• Protected API access token validation and scope checks
• Tenant-aware behavior for single-tenant and multi-tenant modes

Primary audience: internal development teams integrating Caronte into Laravel applications.

Project Type & Tech Summary

• Project type: Laravel package (library), not a standalone app
• PHP version: ^8.2
• Laravel version: ^12.0
• JWT stack: lcobucci/jwt ^5.3 and lcobucci/clock ^3.2
• HTTP integration: Laravel HTTP client via package support classes
• Database: uses host app database connection; publishes package migrations for local user cache tables
• Cache: host app cache (OIDC JWKS cache uses Laravel Cache)
• Queue: no package-owned queue workers required
• External services: Caronte server HTTP API, optional OIDC issuer endpoints

Quick Start (High-Level)

1. Install package dependencies in your host app with composer.
2. Publish package configuration and migrations.
3. Set required environment variables for CARONTE_URL, CARONTE_APP_CN, and CARONTE_APP_SECRET.
4. Run migrations in the host application.
5. Add package middleware to protected host routes.
6. Synchronize configured roles and protected API scopes.
7. Verify authentication and management routes in a local environment.

Full steps: see doc/deployment-instructions.md.

Suite Access

Applications that belong to a Caronte ApplicationGroup can use the SDK to manage tenant user access across the suite after the server grants these Caronte platform permissions to the application:

• groups.roles.read
• groups.users.read
• groups.user_roles.write

The SDK exposes Ometra\Caronte\Api\GroupApi with:

• showGroupRoles()
• showGroupUsers(string $search = '')
• syncGroupUserRoles(string $uriUser, string $appId, array $roleUris, ?string $actorToken = null)

The management UI includes a "Suite access" mode that lists tenant users, groups roles by application, and prevents selecting roles marked as non-manageable such as root.

Documentation Index

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

Standards Note

Examples and references in these docs follow the project instructions for coding conventions and PHPDoc style, using the package namespace and folder structure as the source of truth.