Download the PHP package clawdreyhepburn/aauth-php without Composer

aauth-php

PHP verifier for AAuth — the agent-authentication scheme being standardized in IETF. Drop a single file onto a shared host (Apache + PHP, no Composer needed) and your site can verify requests from AI agents end-to-end.

Status: v0.1.x — runs the live demo at wisdom.clawdrey.com. Public API may still shift before v1.0.

Why a PHP implementation

The two existing AAuth libraries target Node.js and Python. That covers modern services and ML stacks, but it leaves out the long tail of the web: WordPress, Drupal, every small-business CMS, every blog. If AAuth is going to be a web-scale identity layer for AI agents, it needs a PHP story. This is that.

This library is intentionally:

• Zero-dependency. Pure PHP, only the openssl and sodium extensions (both bundled in PHP 8+).
• Single-file deployable. dist/aauth-bundle.php is one file you require_once and you're done.
• Composer-friendly too. PSR-4 autoloading via the Clawdrey\AAuth namespace.

Sibling implementations

• TypeScript: aauth-dev/packages-js — Dick Hardt's reference implementation
• Python: christian-posta/aauth-full-demo — Christian Posta's aauth==0.3.3 on PyPI
• PHP: this repo

Cross-implementation interop tests live under tests/fixtures/ — the PHP verifier verifies signed requests captured from the TypeScript signer byte-for-byte.

Install

Single-file (shared hosting friendly)

Grab aauth-bundle.php from the latest release (it's also tracked at dist/aauth-bundle.php in the repo) and drop it next to your application:

No Composer, no autoloader, no other files. The bundle is ~50 KB of pure PHP and parses on any PHP 8.1+ host with the openssl and sodium extensions (both bundled with PHP since 7.2).

Composer

The package is published on Packagist: clawdreyhepburn/aauth-php.

You get PSR-4 autoloading under Clawdrey\AAuth\; no require_once needed.

Quickstart

That's the whole integration: ~20 lines in front of your handler.

What gets verified

Every successful call to RequestVerifier::verifyRequest proves all of:

1. The Signature-Key header carries a valid aa-agent+jwt issued by the agent's home origin (fetched live from https://<iss>/.well-known/jwks.json, cached on disk).
2. The JWT's cnf.jwk (proof-of-possession key) actually signed the HTTP request, with the signature base computed exactly per RFC 9421.
3. The signature's created timestamp is within ±60 s of server time (replay window).
4. The JWT itself is unexpired, untampered, and uses one of the algorithms AAuth permits (ES256 or EdDSA).

Algorithm support: ES256 (P-256) and EdDSA (Ed25519). RSA is intentionally not supported.

How it works

A verification has five stages, all driven by RequestVerifier::verifyRequest():

1. Parse the AAuth headers — Signature-Input, Signature, and Signature-Key. Extract the aa-agent+jwt token from Signature-Key, read its kid and iss.
2. Fetch the JWKS for the issuer over HTTPS, with on-disk caching. The fetcher refuses non-HTTPS endpoints by default (and always rejects file://, ftp://, javascript:, etc.).
3. Verify the JWT — ES256 or EdDSA, with iat/exp/nbf/typ checks and configurable leeway. Pull the proof-of-possession key out of cnf.jwk.
4. Verify the HTTP signature per RFC 9421: rebuild the signature base from the covered components, enforce the ±60 s replay window on created, and verify with the cnf.jwk. Raw r||s ↔ DER conversion happens transparently for ES256.
5. Return a VerifyResult with agentSub, agentIss, kid, alg, and the RFC 7638 thumbprint jkt. Any failure along the way throws an AAuthException you catch and turn into a 401.

Live demo

wisdom.clawdrey.com is a real public resource served by this library.

Documentation

• docs/COOKBOOK.md — ten practical recipes (single endpoint, reusable middleware, optional auth, allowlists, WordPress, Slim 4, Laravel, local dev, custom JWKS cache, error handling, TS-client smoke test).
• docs/DESIGN.md — architecture and design decisions.
• docs/PACKAGIST.md — publishing notes for maintainers.
• SECURITY.md — reporting policy and security defaults.
• CHANGELOG.md — release notes.

Repository layout

Tests

193 tests across the crypto primitives, signature-base construction, JWT verification, the full request-verification pipeline, JWKS-fetcher safety gates, and a single-file-bundle smoke test. The most important ones replay real signed requests captured from the TypeScript reference implementation, byte-equal against PHP's reconstructed signature base.

Contributing

One-command quality gate: composer check. That runs composer validate --strict, the test suite, every PHP code block in this README + the cookbook, and PHPStan at level 8. CI runs the same gate on PHP 8.1 / 8.2 / 8.3 / 8.4.

See CHANGELOG.md for release notes and SECURITY.md for the disclosure policy.

License

Copyright © 2026 Clawdrey Hepburn.

Licensed under the Apache License, Version 2.0 — a permissive, OSI-approved license that:

• lets you use, modify, distribute, and sublicense the code freely (commercial use included);
• requires preserving the copyright and license notices in source distributions;
• includes an explicit grant of any patent rights the contributors hold in the contributed code (important for a standards-track library like this one);
• ships the code “as is” with no warranty, and excludes the contributors from liability.

The full text is in LICENSE. When in doubt, prefer the file over this summary.