ometra/caronte-sdk

Caronte SDK

Maintainers

Package info

github.com/Ometra-Nyx/mx.ometra.caronte-sdk

pkg:composer/ometra/caronte-sdk

Statistics

Installs: 31

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

3.1.0 2026-05-04 20:10 UTC

Requires

Requires (Dev)

MIT 6443c3aa28fb16a3e3f04bbdd6012d613015e0ad

  • Gabriel Ruelas <gruelas.woop@gruelas.com>

This package is auto-updated.

Last update: 2026-05-05 19:15:35 UTC

README

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

Project Overview

ometra/caronte-client 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
  • 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

Item Value
Type Laravel Package (library)
PHP ^8.2
Laravel ^12.0
JWT library lcobucci/jwt ^5.3 + lcobucci/clock ^3.2
Database MySQL / any Laravel-supported driver (via host app)
Cache Host app cache (no package-level cache)
Queue None (all requests are synchronous)
External service Caronte authentication server (HTTP API)
Optional dependency inertiajs/inertia-laravel ^2.0

Quick Start

  1. Install the package

    composer require ometra/caronte-client

  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 management UI at /caronte/management (default).

Token Types

  • User JWTs authenticate humans and are checked by caronte.session.
  • 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