README

A lightweight, secure connector package for Laravel applications to connect to Laravel Ops central management platform.

Overview

The connector exposes a secure API that allows Laravel Ops to:

Monitor application health
Discover capabilities
Execute allowlisted operations (cache clear, migrations, etc.)

Architecture

Laravel Ops (Central) 
    ↓ HTTPS + HMAC Signed Request
Connector (This Package)
    ↓ Validates Signature
Laravel Application (Local)
    ↓ Executes Operation
    ↓ Returns Result
Laravel Ops (Displays Result)

Security Features

HMAC-SHA256 Request Signing - All requests are cryptographically signed
Timestamp Validation - Requests expire after 5 minutes
Replay Protection - Nonce-based protection against replay attacks
Allowlisted Operations - Only explicitly permitted operations can execute
No Shell Execution - Uses Laravel's Artisan API, never shell_exec

Installation

Install the package through Composer:

composer require laravel-ops/connector

The package is available through Packagist once its public source repository has been submitted there. For development against a local checkout, Composer can instead use a path repository in your application's composer.json.

Publish Configuration

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

Configure Credentials

Add to your .env file:

CONNECTOR_API_KEY=your_api_key_here
CONNECTOR_API_SECRET=your_api_secret_here

These credentials are provided by Laravel Ops when you register your application.

Register Service Provider

For Laravel 11+, the service provider is auto-discovered. For older versions, add to config/app.php:

'providers' => [
    // ...
    LaravelOps\Connector\ConnectorServiceProvider::class,
],

Enrollment Flow

Option A: Automatic Enrollment (Recommended)

In Laravel Ops, generate an enrollment token for your application
Run the enrollment command:

php artisan connector:enroll --token=enr_xxxxx --central-url=https://laravel-ops.test

This will:

Validate the token with Laravel Ops
Receive API credentials
Update your .env file automatically

Option B: Manual Configuration

Register your application in Laravel Ops
Copy the API credentials from the application detail page
Add them to your .env file:

CONNECTOR_API_KEY=lops_xxxxx
CONNECTOR_API_SECRET=xxxxx

API Endpoints

Health Check

GET /api/connector/v1/health

Returns application health status including:

Application info (name, URL, Laravel version, PHP version)
Database connection status
Cache functionality status
Connector version

Capability Discovery

GET /api/connector/v1/capabilities

Returns supported operations and features:

Connector version
Laravel version
List of allowed operations
Available features (queue, scheduler, etc.)

Enrollment

POST /api/connector/v1/enroll

Enrolls the connector with Laravel Ops using a short-lived enrollment token.

Request Signing

All requests (except enrollment) must include these headers:

X-Connector-Key: your_api_key
X-Connector-Timestamp: 2026-10-16T10:00:00Z
X-Connector-Nonce: random_unique_string
X-Connector-Signature: calculated_hmac_signature

Signature Calculation

$method = 'GET';
$path = '/api/connector/v1/health';
$timestamp = '2026-10-16T10:00:00Z';
$nonce = 'random_string';
$bodyHash = ''; // SHA256 hash of request body (empty for GET)

$stringToSign = "$method|$path|$timestamp|$nonce|$bodyHash";
$signature = hash_hmac('sha256', $stringToSign, $apiSecret);

Configuration

Allowed Operations

Edit config/connector.php to customize allowed operations:

'allowed_operations' => [
    'cache:clear',
    'config:clear',
    'route:clear',
    'view:clear',
    'event:clear',
    'optimize:clear',
    'migrate:status',
],

Security Settings

// Timestamp tolerance (seconds)
'timestamp_tolerance' => 300, // 5 minutes

// Nonce cache duration (seconds)
'nonce_cache_duration' => 300, // 5 minutes

// Enable/disable operations
'enable_operations' => true,

Testing the Connection

From Laravel Ops, you can test the connection:

Go to your application detail page
Click "Test Connection"
If successful, the status will change to "Connected"

Or via CLI:

# From Laravel Ops
php artisan connector:test-connection {application_id}

Troubleshooting

"Invalid API key" error

Check that CONNECTOR_API_KEY in .env matches the key in Laravel Ops
Ensure there are no extra spaces or line breaks

"Request timestamp is too old" error

Check that your server's clock is synchronized (NTP)
Increase timestamp_tolerance in config/connector.php if needed

"Request nonce has already been used" error

This indicates a possible replay attack
Each request must have a unique nonce
Check your HTTP client isn't retrying requests

"Invalid request signature" error

Verify CONNECTOR_API_SECRET is correct
Check signature calculation matches the expected format
Ensure body hash is included for POST requests

Connection timeout

Check firewall allows HTTPS connections
Verify the base URL in Laravel Ops is correct
Check SSL certificate validity

Security Best Practices

Keep secrets secure - Never commit .env to version control
Use HTTPS - Always use HTTPS in production
Rotate credentials - Regenerate API keys periodically
Monitor logs - Watch for authentication failures
Limit operations - Only enable operations you need
Revoke when needed - Use the revoke feature if a connector is compromised

Requirements

PHP 8.1 or higher
Laravel 10.x or 11.x
HTTPS connection to Laravel Ops
Valid API credentials

Version History

1.0.0 - Initial release
- Health check endpoint
- Capability discovery
- Request signing with HMAC
- Enrollment flow
- Replay protection

License

MIT License

Support

For issues and questions, please refer to the Laravel Ops documentation or open an issue in the main repository.

laravel-ops / connector

Package info

Security

Statistics