04-duress-authentication.php

<?php

/**
 * PPS-PHP Example 04: Silent Duress Authentication
 *
 * Demonstrates the Honey-Pulse duress mechanism:
 * 1. User authenticates under duress using hidden duress key
 * 2. Server detects duress but returns normal-looking response
 * 3. Server internally triggers silent alert
 *
 * Usage:
 *   php examples/04-duress-authentication.php
 */

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use Pps\Crypto\Base64Url;
use Pps\Crypto\Ed25519;
use Pps\Crypto\Random;
use Pps\Encoding\CborEncoder;
use Pps\Key\KeyManager;
use Pps\Payload\PulsePayload;
use Pps\Storage\InMemoryStorage;
use Pps\Util\SystemTimeProvider;
use Pps\Verification\PulseVerifier;

echo "=== PPS-PHP Example 04: Silent Duress Authentication ===\n\n";

$timeProvider = new SystemTimeProvider();
$storage = new InMemoryStorage();
$rpId = 'example.com';

// ---------------------------------------------------------------
// Setup: Register device with normal and duress keys
// ---------------------------------------------------------------

echo "Setup: Registering device with duress key...\n";

$clientState = KeyManager::createClientState($rpId);
$kid = $clientState['kid'];

$normalSeed = Base64Url::decode($clientState['current_seed']);
$duressSeed = Base64Url::decode($clientState['duress_seed']);

$normalKey = KeyManager::keyPairFromSeed($normalSeed);
$duressKey = KeyManager::keyPairFromSeed($duressSeed);

$storage->saveDeviceState($kid, [
    'kid' => $kid,
    'current_pk' => $normalKey->publicKeyB64u(),
    'key_seq' => 0,
    'last_counter' => 0,
    'duress_pk' => $duressKey->publicKeyB64u(),
    'duress_key_seq' => 0,
    'duress_last_counter' => 0,
    'revoked' => false,
]);

echo "  Normal PK: " . $normalKey->publicKeyB64u() . "\n";
echo "  Duress PK: " . $duressKey->publicKeyB64u() . "\n\n";

// ---------------------------------------------------------------
// Step 1: User authenticates under duress
// ---------------------------------------------------------------

echo "Step 1: User authenticates under duress\n";
echo "  (Using hidden duress key instead of normal key)\n\n";

$epoch = $timeProvider->epoch();
$counter = 1;
$exp = $epoch + 2;
$nonce = Random::nonce();
$nonceB64u = Base64Url::encode($nonce);

// Generate next duress key for rotation
$nextDuressKey = KeyManager::rotateKeyPair($duressSeed, $epoch, $counter, duress: true);

// Build Pulse payload signed with duress key
$payload = new PulsePayload($rpId, $epoch, $counter, $exp);
$payload->singleDevice(
    kid: Base64Url::decode($kid),
    pk: $duressKey->publicKey,
    nextPk: $nextDuressKey->publicKey,
    rotSeq: 1
);
$payload->nonce($nonce);

$message = $payload->encode();
$signature = Ed25519::sign($message, $duressKey->secretKey);

$envelope = CborEncoder::encode([
    1 => $message,
    2 => [
        $kid => Base64Url::encode($signature),
    ],
]);

$pulseToken = Base64Url::encode($envelope);

echo "  Pulse created with duress key.\n\n";

// ---------------------------------------------------------------
// Step 2: Server verifies Pulse
// ---------------------------------------------------------------

echo "Step 2: Server verifies Pulse\n";

$verifier = new PulseVerifier($storage, $timeProvider);
$result = $verifier->verify(
    pulseToken: $pulseToken,
    rpId: $rpId,
    nonceB64u: $nonceB64u
);

// ---------------------------------------------------------------
// Step 3: Server handles result
// ---------------------------------------------------------------

echo "Step 3: Server handles result\n\n";

// Outward response is IDENTICAL to normal success
$outwardResponse = json_encode(['status' => 'ok']);
echo "  Outward response: $outwardResponse\n";

// Internal handling
if ($result->ok && $result->honey) {
    echo "\n  [INTERNAL] Duress detected!\n";
    echo "  [INTERNAL] Mode: " . $result->mode . "\n";
    echo "  [INTERNAL] Actions:\n";
    echo "    - Restrict account capabilities\n";
    echo "    - Block high-value transactions\n";
    echo "    - Trigger silent security alert\n";
    echo "    - Delay settlement\n";
    echo "    - Notify security team\n";

    // Apply state updates
    $storage->updateDeviceState($kid, $result->updates);
} elseif ($result->ok) {
    echo "\n  [INTERNAL] Normal authentication.\n";
    $storage->updateDeviceState($kid, $result->updates);
} else {
    echo "\n  Verification FAILED: " . $result->error . "\n";
    exit(1);
}

echo "\n=== Example 04 Complete ===\n";