Warlock Authentication

This guide explains how to enable and use authentication for the Warlock server.

Warlock supports four authentication methods:

1. none (default)
2. list (development use only)
3. basic (standalone, file-backed user database)
4. script (custom external authentication logic)

Where Authentication Is Configured

Authentication is configured under the Warlock server client.auth section.

PHP (Recommended)

<?php
return [
	'client' => [
		'auth' => [
			'method' => 'none',
		],
	],
];

JSON

{
	"client": {
		"auth": {
			"method": "none"
		}
	}
}

INI (Legacy)

[client.auth]
method = none

Authentication Methods

1) None (Default)

Method value: none

This is the default authentication method. It accepts all username/password pairs and is effectively the same as running without authentication.

Use cases:

• local development when security is not needed
• trusted internal test environments

Do not use this method in production.

Example:

PHP

<?php
return [
	'client' => [
		'auth' => [
			'method' => 'none',
		],
	],
];

JSON

{
	"client": {
		"auth": {
			"method": "none"
		}
	}
}

INI (Legacy)

[client.auth]
method = none

2) User List (Development Use Only)

Method value: list

This method stores users directly in configuration (users map of username => password). It is ideal for quick development setup because you only need a text editor.

Why this is development-only:

• credentials are stored in config
• credentials are harder to rotate and audit safely
• there is no CLI-backed user store management for this method

Example:

PHP

<?php
return [
	'client' => [
		'auth' => [
			'method' => 'list',
			'users' => [
				'dev-admin' => 'dev-pass-123',
				'qa-user' => 'qa-pass-456',
			],
		],
	],
];

JSON

{
	"client": {
		"auth": {
			"method": "list",
			"users": {
				"dev-admin": "dev-pass-123",
				"qa-user": "qa-pass-456"
			}
		}
	}
}

INI (Legacy)

[client.auth]
method = list

[client.auth.users]
dev-admin = dev-pass-123
qa-user = qa-pass-456

3) Basic (Standalone + CLI User Management)

Method value: basic

This method stores users in a Warlock authentication database file (dbFile). It is suitable for standalone environments where you want a simple built-in user store and CLI tooling.

Use this when:

• you want persistent users in a local file
• you want to manage users through the Warlock CLI
• you do not need external identity integration

Example:

PHP

<?php
return [
	'client' => [
		'auth' => [
			'method' => 'basic',
			'dbFile' => '/var/warlock/auth.db',
		],
	],
];

JSON

{
	"client": {
		"auth": {
			"method": "basic",
			"dbFile": "/var/warlock/auth.db"
		}
	}
}

INI (Legacy)

[client.auth]
method = basic
dbFile = /var/warlock/auth.db

4) Script (Custom/External Authentication)

Method value: script

This method executes a PHP script file and expects the script to return true or false.

Use this when:

• authenticating against your own database
• integrating external auth systems
• applying custom logic such as account status checks, tenant routing, or IP rules

Configuration example:

PHP

<?php
return [
	'client' => [
		'auth' => [
			'method' => 'script',
			'scriptPath' => 'configs/warlock-auth.php',
		],
	],
];

JSON

{
	"client": {
		"auth": {
			"method": "script",
			"scriptPath": "configs/warlock-auth.php"
		}
	}
}

INI (Legacy)

[client.auth]
method = script
scriptPath = configs/warlock-auth.php

Detailed Script Authentication Example

When using script, Warlock includes your script and expects a boolean return value.

Available variables in the script scope:

• $username (string): username from the client
• $password (string): password from the client
• $client (Hazaar\Warlock\Server\Client|null): current client connection context, if available

Your script must:

• return true for successful authentication
• return false for failed authentication
• always return a boolean value

Example script (configs/warlock-auth.php):

<?php

declare(strict_types=1);

use Hazaar\Warlock\Server\Client;

/**
 * Warlock script auth contract:
 * - $username: string
 * - $password: string
 * - $client: ?Client
 * - return bool
 *
 * This example validates users from a SQL table with password hashes
 * and optional client-origin checks.
 */

if (!is_string($username) || '' === trim($username)) {
	return false;
}

if (!is_string($password) || '' === $password) {
	return false;
}

try {
	$pdo = new PDO(
		'mysql:host=127.0.0.1;port=3306;dbname=app;charset=utf8mb4',
		'app_user',
		'app_password',
		[
			PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
			PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
		]
	);

	$stmt = $pdo->prepare(
		'SELECT username, password_hash, enabled, expires_at '
		.'FROM users '
		.'WHERE username = :username '
		.'LIMIT 1'
	);
	$stmt->execute(['username' => $username]);
	$user = $stmt->fetch();

	if (!$user) {
		return false;
	}

	if ((int) $user['enabled'] !== 1) {
		return false;
	}

	if (!empty($user['expires_at']) && strtotime((string) $user['expires_at']) < time()) {
		return false;
	}

	if (!password_verify($password, (string) $user['password_hash'])) {
		return false;
	}

	// Optional: inspect client details if available in your environment.
	if ($client instanceof Client) {
		// Add custom client-based checks here if required.
	}

	return true;
} catch (Throwable $e) {
	// Fail closed on any infrastructure or query error.
	return false;
}

Starting Warlock With Authentication

After configuring auth, start the server as normal:

vendor/bin/warlock run -c configs/warlock.json

Managing Users With the Warlock CLI

The warlock user commands manage users in the file-backed authentication database used by basic auth.

Default DB file:

• auth.db in the current working directory

Use --dbfile (or -f) to specify an explicit path.

List Users

vendor/bin/warlock user list --dbfile /var/warlock/auth.db

Add User

Non-interactive:

vendor/bin/warlock user add alice --password 'S3curePass!' --dbfile /var/warlock/auth.db

Interactive (prompts for password if omitted):

vendor/bin/warlock user add alice --dbfile /var/warlock/auth.db

Delete User

With confirmation:

vendor/bin/warlock user del alice --dbfile /var/warlock/auth.db

Without confirmation:

vendor/bin/warlock user del alice --yes --dbfile /var/warlock/auth.db

Check Credentials

vendor/bin/warlock user check alice 'S3curePass!' --dbfile /var/warlock/auth.db

Method Selection Guidance

• Use none only when authentication is intentionally disabled (default).
• Use list for development only, where fast text-editor changes are preferred.
• Use basic for standalone deployments that need built-in persistent user management.
• Use script when integrating external/custom authentication systems.

Security Notes

• Avoid storing production credentials in source-controlled config files.
• Prefer basic or script over list for production environments.
• If using script, implement fail-closed behavior and robust input validation.
• Keep your auth DB file and script files readable only by trusted users/processes.