PHP Implementation

The PHP implementation lives in the php-aihint/ directory and provides a full API, CLI tools, and a trust scoring engine.

Requirements: PHP 8.1+ (core library works on 7.4+, but scoring requires 8.1+ for enums)

Extensions: ext-json, ext-openssl

Setup

No external dependencies are required — just PHP 8.1+ with the openssl and json extensions (both are included in most PHP installations).

Include the source files directly:

require_once __DIR__ . '/php-aihint/src/AIHint.php';
require_once __DIR__ . '/php-aihint/src/KeyManager.php';

// For trust scoring
require_once __DIR__ . '/php-aihint/src/scoring/index.php';

CLI Usage

Protocol CLI

cd php-aihint
php bin/aihint <command> [options]

Generate RSA keys

php bin/aihint generate-keys --output-dir ./keys

Creates private_key.pem and public_key.pem in the specified directory.

Create a hint

php bin/aihint create \
  --target "https://example.com" \
  --issuer "https://trust.example.org" \
  --score 0.85 \
  --private-key keys/private_key.pem \
  --output aihint.json

Options:

Option	Required	Description
--target	Yes	Target domain URL
--issuer	Yes	Issuing authority URL
--score	Yes	Trust score (0.0–1.0)
--private-key	Yes	Path to private key for signing
--output	Yes	Output file path
--method	No	Scoring method (default: aihint-core-v1)
--comment	No	Optional comment
--expires-at	No	ISO 8601 expiration date

Verify a hint

# Verify using the public_key_url in the hint (fetches key via HTTP)
php bin/aihint verify aihint.json

# Verify with a local public key
php bin/aihint verify aihint.json --public-key keys/public_key.pem

# Verify from a URL
php bin/aihint verify https://example.com/.well-known/aihint.json

Validate structure

php bin/aihint validate aihint.json

Fetch a remote hint

php bin/aihint fetch https://example.com/.well-known/aihint.json

View hint info

php bin/aihint info aihint.json

Scoring CLI

cd php-aihint
php bin/aihint-scoring <command> [options]

Score a website

php bin/aihint-scoring score https://example.com --verbose

Batch scoring

php bin/aihint-scoring batch --urls "https://example.com,https://another.com"

Generate scoring config

php bin/aihint-scoring config --output scoring-config.json

Auto-loaded config files (checked in order):

1. ./aihint-scoring-config.json
2. ./.aihint-scoring-config.json
3. $HOME/.aihint-scoring-config.json

PHP API

Basic usage

require_once __DIR__ . '/php-aihint/src/AIHint.php';
require_once __DIR__ . '/php-aihint/src/KeyManager.php';

use AIHint\AIHint;
use AIHint\KeyManager;

// Generate keys
$km = new KeyManager();
$km->generateKeys('./keys');

// Create and sign a hint
$hint = new AIHint([
    'target' => 'https://example.com',
    'issuer' => 'https://trust.example.org',
    'score' => 0.85,
    'method' => 'aihint-core-v1',
    'publicKeyUrl' => 'https://example.com/.well-known/aihint-pubkey.pem',
    'expiresAt' => date('c', strtotime('+1 year')),
]);

$hint->sign('./keys/private_key.pem');
$hint->save('aihint.json');

// Load and verify
$loaded = new AIHint();
$loaded->load('aihint.json');
$isValid = $loaded->validate();
$isVerified = $loaded->verify();  // fetches public key from public_key_url

Static methods

use AIHint\AIHint;

// Sign a hint array
$hintArray = json_decode(file_get_contents('aihint.json'), true);
$signed = AIHint::signHint($hintArray, 'private_key.pem');

// Verify a hint array
$valid = AIHint::verifyHint($hintArray, 'public_key.pem');

// Validate structure
$valid = AIHint::validateHint($hintArray);

// Canonicalize for signing
$canonical = AIHint::canonicalize($hintArray);

Fetching from a URL

$hint = AIHint::fromUrl('https://example.com/.well-known/aihint.json');
$hint->verify();  // fetches public key and verifies signature

Trust scoring

require_once __DIR__ . '/php-aihint/src/scoring/index.php';

use AIHint\Scoring\TrustScoringEngine;

$engine = new TrustScoringEngine();
$result = $engine->scoreWebsite('https://example.com');

echo "Score: " . $result->finalScore . "\n";
echo "Trust: " . $result->trustLevel->getDescription() . "\n";
echo "Security: " . $result->securityScore . "\n";
echo "Reputation: " . $result->reputationScore . "\n";
echo "Compliance: " . $result->complianceScore . "\n";

// Export as JSON
echo $result->toJson();

Exported Classes

Core (AIHint\ namespace)

Class	Purpose
AIHint	Full protocol operations: create, sign, verify, validate, save, load
KeyManager	RSA key generation, loading, and validation

Scoring (AIHint\Scoring\ namespace)

Class	Purpose
TrustScoringEngine	Main scoring engine
ScoringResult	Result object with toArray(), toJson(), isTrusted()
TrustLevel	Enum: VERY_LOW, LOW, MODERATE, GOOD, HIGH
MetricResult	Individual metric result
MetricStatus	Enum: SUCCESS, WARNING, ERROR, SKIPPED

Scorer classes

All scorers implement score(string $url): array:

Scorer	Real network checks	Status
SSLTLSValidator	TLS cert, cipher, protocol, chain	Functional
SecurityHeadersAnalyzer	HTTP security headers	Functional
MalwareChecker	Heuristic + optional API integration	Partial
DomainReputationChecker	WHOIS, DNS, blacklists	Partial
DomainAgeAnalyzer	WHOIS-based age	Functional
IncidentTracker	Security incident checks	Heuristic
PrivacyPolicyAnalyzer	Privacy page detection + analysis	Functional
ContactValidator	Contact page detection	Functional
ComplianceChecker	ToS, cookies, accessibility	Heuristic

Environment Variables

Variable	Default	Description
AIHINT_TIMEOUT	30	HTTP timeout in seconds for remote key fetching

AIHint Constructor Note

The constructor accepts camelCase keys (publicKeyUrl, expiresAt), while the JSON file format uses snake_case (public_key_url, expires_at). The load() and save() methods handle the conversion automatically. When constructing an AIHint object manually, use camelCase.