README

A PHP library implementing core domain entities and services for the Nostr protocol, built with Clean Architecture principles.

Code is organised around domain concepts (events, identities, tags, messages) rather than NIP numbers: a single Event entity handles creation, signing, and verification regardless of which NIP defines the event kind. Domain entities and value objects are immutable, services are stateless, and the package provides building blocks for relays, clients, and web applications without imposing architectural decisions on consumers. See ADR-0019 for the organising rationale.

Important

Install the native libsecp256k1 library (via the ffi extension) for any server-side or long-lived signer. When it is absent, signing, public-key derivation, and ECDH fall back to a pure-PHP implementation that is not constant-time and cannot be made so. A local or co-located attacker able to measure signing/ECDH timing could in principle recover private-key material, so a relay, a NIP-46 remote signer/bunker, or any service that repeatedly signs with a fixed key should confirm the native path is active before deploying. The pure-PHP fallback is intended for portability and low-exposure client use, not a hardened signing oracle. See Security and SECURITY.md.

Features

• Complete Nostr protocol implementation
• Clean Architecture with strict layer separation
• Domain-driven design with pure business logic
• Comprehensive cryptographic support using secp256k1
• Native libsecp256k1 FFI acceleration covering BIP340 sign/verify, x-only pubkey derivation, and NIP-44 ECDH — automatic pure-PHP fallback when the C library is unavailable (the fallback is not constant-time; see Security)
• Bech32 and bech32m encoding/decoding via a single Bech32Codec (NIP-19 prefixes plus BIP-350 bech32m variants), selected through the Bech32Variant enum
• Content-reference extraction (event, pubkey, relay and quote references from tags and content) and reply-chain analysis
• Typed, immutable domain collections and a subscription model
• Full NIP compliance validation
• Type-safe message handling with domain objects at all boundaries
• Extensive test coverage with PHPStan level 9

Requirements

Declared in composer.json:

• PHP 8.4 or higher
• ext-gmp (bignum arithmetic for the pure-PHP secp256k1 signing and ECDH path; required transitively by paragonie/ecc, so the package cannot install without it even on a host that always uses the native libsecp256k1 path)
• ext-intl (NFKC password normalisation in NIP-49)
• ext-mbstring (search-filter matching on untrusted event content and EventContent::getLength)
• ext-sodium (NIP-44 and NIP-49 AEAD, sodium_memzero)
• paragonie/ecc (pure-PHP secp256k1 fallback)
• paragonie/sodium_compat (raw ChaCha20 keystream with explicit block counter for NIP-44, which ext-sodium does not expose)

Declared under suggest in composer.json:

• ext-ffi is needed by NIP-49 (unconditionally) and by the Secp256k1Signer::create() / Secp256k1Ecdh::create() factories (for the libsecp256k1 probe). Consumers who do not use NIP-49 and who construct the adapters directly with new Secp256k1Signer(null, ...) / new Secp256k1Ecdh(null) can run without ext-ffi at all and stay on the pure-PHP path.

Optional system libraries

• libsecp256k1 — when present, Schnorr signing, verification, public-key derivation, and NIP-44 ECDH use the native C library (reached via ext-ffi) for significantly faster performance. Without it, the library falls back to a pure-PHP implementation via paragonie/ecc automatically. That fallback is not constant-time, so installing the native library is a security measure as well as a performance one for any server-side or long-lived signer; see Security.
• libsodium — required by NIP-49 scrypt derivation, which calls crypto_pwhash_scryptsalsa208sha256_ll through ext-ffi. Typically already installed wherever ext-sodium is.

Installation

composer require innis/nostr-core

Quick Start

Cryptographic operations (signing, verification, public-key derivation, ECDH) are exposed as Domain service interfaces with Infrastructure implementations. The Secp256k1Signer and Secp256k1Ecdh pick an FFI-accelerated path when libsecp256k1 is available and fall back to pure PHP otherwise; both paths produce byte-identical results, so callers do not need to care which one runs for correctness. The two are not equivalent for timing side channels, though — see Security before running a server-side or long-lived signer on the pure-PHP path.

Key Generation

use Innis\Nostr\Core\Domain\ValueObject\Identity\KeyPair;
use Innis\Nostr\Core\Infrastructure\Crypto\Secp256k1Signer;

$signatureService = Secp256k1Signer::create();
$keyPair = KeyPair::generate($signatureService);

echo $keyPair->getPrivateKey()->toBech32(); // nsec1...
echo $keyPair->getPublicKey()->toBech32();  // npub1...

Event Creation and Signing

use Innis\Nostr\Core\Domain\Factory\EventFactory;

$event = EventFactory::createTextNote(
    $keyPair->getPublicKey(),
    'Hello Nostr!'
);

$signedEvent = $event->sign($keyPair, $signatureService);

$signedEvent->verify($signatureService); // bool

NIP-44 Encryption

Deriving a conversation key needs an ECDH service. Secp256k1Ecdh::create() follows the same FFI-or-fallback pattern as the signature adapter:

use Innis\Nostr\Core\Domain\ValueObject\Identity\ConversationKey;
use Innis\Nostr\Core\Infrastructure\Crypto\Nip44Cipher;
use Innis\Nostr\Core\Infrastructure\Crypto\Secp256k1Ecdh;

$ecdhService = Secp256k1Ecdh::create();
$conversationKey = ConversationKey::derive(
    $senderPrivateKey,
    $recipientPublicKey,
    $ecdhService,
);

$encryption = new Nip44Cipher();
$ciphertext = $encryption->encrypt('Hello in private', $conversationKey);
$plaintext = $encryption->decrypt($ciphertext, $conversationKey);

Nonce generation is injected: Nip44Cipher accepts an optional RandomBytesGeneratorInterface, defaulting to NativeRandomBytesGenerator (PHP's random_bytes) for production. There is no public encryptWithNonce method — see ADR-0014.

Always construct the adapters through their ::create() factories. Direct instantiation via new Secp256k1Signer(null, ...) or new Secp256k1Ecdh(null) exists for dependency injection and testing but stays on the pure-PHP path regardless of whether libsecp256k1 is installed.

Message Handling

use Innis\Nostr\Core\Infrastructure\Encoding\JsonMessageDeserialiser;
use Innis\Nostr\Core\Domain\ValueObject\Protocol\Message\Client\EventMessage;

$deserialiser = new JsonMessageDeserialiser();

$eventMessage = new EventMessage($signedEvent);
$json = $eventMessage->toJson();

$deserialised = $deserialiser->deserialiseClientMessage($json);

Password-Encrypted Private Keys (NIP-49)

The NIP-49 adapter takes the password as a Closure(): string rather than a raw string. The adapter invokes the closure exactly once, sodium_memzeros the revealed password before the method returns, and the caller never has to maintain a password binding in its own scope:

use Innis\Nostr\Core\Domain\Enum\KeySecurityByte;
use Innis\Nostr\Core\Domain\ValueObject\Identity\Ncryptsec;
use Innis\Nostr\Core\Domain\ValueObject\Identity\PrivateKey;
use Innis\Nostr\Core\Infrastructure\Crypto\Nip49Cipher;

$adapter = Nip49Cipher::create();
$privateKey = PrivateKey::generate();

$ncryptsec = $adapter->encrypt(
    $privateKey,
    static fn (): string => readPasswordFromUser(),
    logN: 16,
    keySecurity: KeySecurityByte::ClientSideOnly,
);

$stored = (string) $ncryptsec; // ncryptsec1...

$decoded = Ncryptsec::fromString($stored);
$recovered = $adapter->decrypt($decoded, static fn (): string => readPasswordFromUser());

Build the adapter through Nip49Cipher::create(), which probes for libsodium scrypt via ext-ffi; the bare constructor (new Nip49Cipher(...)) is for dependency injection and tests. NIP-49 has no pure-PHP fallback — see ADR-0041 and ADR-0039.

Secret Key Lifecycle

PrivateKey and ConversationKey hold their raw bytes inside a SecretKeyMaterial value object. Callers that need to clear secret material from memory can call zero(); any subsequent operation on that key throws SecretKeyMaterialZeroedException. Infrastructure code that genuinely needs raw bytes uses the bounded expose callback, which hands the closure the secret bytes and sodium_memzeros them when it returns; see ADR-0028:

$derived = $privateKey->expose(static function (string $bytes): string {
    return derive_something($bytes);
});

$privateKey->zero();
$signatureService->sign($privateKey, $message); // throws SecretKeyMaterialZeroedException

Applications that require bounded key-material lifetimes — session-scoped bunker signers, for example — should call $privateKey->zero() explicitly at the end of the scope that owns the key. See ADR-0015 for why the destructor is not relied upon.

Examples

Runnable scripts live in examples/; run one with php examples/<name>.php:

• sign_and_verify.php — generate a key pair, create and sign a text note, verify it
• nip44_encrypt_decrypt.php — derive a NIP-44 conversation key via ECDH and encrypt/decrypt a message
• nip49_password_encrypt.php — encrypt a private key under a password to an ncryptsec and recover it (requires ext-ffi and libsodium)
• giftwrap_direct_message.php — seal and gift-wrap a NIP-17 private message, then unwrap it

The examples/ directory is covered by PHPStan and php-cs-fixer in CI, like src and tests.

Supported NIPs

Beyond the NIPs listed above, EventKind carries named constants for a broad range of registered kinds (metadata, channels, MLS messaging, polls, cashu wallet events, live events, web pages, and more) together with the replaceable / ephemeral / parameterised-replaceable range boundaries, so consumers can classify kinds the library does not otherwise model.

Performance

Native FFI Acceleration

The library can use the system's native libsecp256k1 C library via PHP's FFI extension for cryptographic operations. This provides significant performance gains for applications performing bulk signature verification (relays, indexers).

Operations routed through LibSecp256k1Ffi when the library is loaded:

• sign — BIP340 Schnorr sign
• verify — BIP340 Schnorr verify
• derivePublicKey — secret to 32-byte x-only pubkey
• computeSharedX — x-only ECDH for NIP-44 conversation keys

To install the native library:

# Ubuntu/Debian
sudo apt install libsecp256k1-1

# macOS (Homebrew)
brew install libsecp256k1

No code changes are required. The library detects and uses the native implementation automatically, falling back to pure PHP when unavailable.

Security

See SECURITY.md for the library's security properties, the responsibilities it leaves to the consumer, and the reasoning behind the non-obvious cryptographic decisions.

The most important operational caveat: the pure-PHP cryptography fallback used when native libsecp256k1 is unavailable is not constant-time and cannot be made so (the secret-dependent scalar arithmetic runs on variable-time GMP and the interpreted Zend engine). A local or co-located attacker able to measure signing/ECDH timing could in principle recover private-key material. Any server-side or long-lived signer — a relay, a NIP-46 remote signer/bunker, or any service that repeatedly signs attacker-influenced messages with a fixed key — should install libsecp256k1, enable the ffi extension, and confirm the native path is active before deploying. The pure-PHP fallback is intended for portability and low-exposure client use, not a hardened signing oracle. The full analysis is in SECURITY.md and ADR-0025.

Architecture

This package follows Clean Architecture principles with strict layer separation:

• Domain Layer: Pure business logic, immutable entities and value objects (cryptographic library is the sole external dependency, used directly by identity value objects)
• Application Layer: Port interfaces for external service integration
• Infrastructure Layer: Implementations of the domain and application interfaces, grouped by concern (Crypto/, Encoding/, Http/, Time/)

Architecture decisions

Design rationale lives in docs/adr/ as immutable, sequentially-numbered Architecture Decision Records — read these before "correcting" a choice that reads like a smell. Each record states the context, the decision, and what it forbids; the filenames are the index.

Dependencies

Testing

# Full suite: Unit + Integration + Compliance + PHPStan (ship gate)
composer test

# Unit suite only (fast inner loop; skips compliance property fuzz)
composer test-unit

# PHPStan analysis (level 9)
composer analyse

# Fix code style
composer fix-style

Filter-set hash

FilterHasher::hash computes a stable, order-independent identity for a NIP-01 REQ filter set, suitable as a subscription dedup key. Two filter sets that select the same events hash to the same digest regardless of input ordering, and the digest is byte-for-byte identical to the TypeScript sibling's hashFilters for every input — including non-ASCII search strings and tag-filter values.

$key = FilterHasher::hash(...$filters); // lowercase-hex SHA-256

The canonicalisation contract and the cross-language parity rationale are recorded in ADR-0020; the conformance anchors that lock the two runtimes together are asserted in both packages' test suites.

License

MIT License. See LICENSE file for details.