Download the PHP package karanshukla/php-atproto-identity without Composer

php-atproto-identity

Resolve an ATProto DID to its document, and turn the signing key that document publishes into something OpenSSL can verify with.

That is the whole package. It is the layer @atproto/identity occupies in the TypeScript world, and nothing framework-specific lives in it: the HTTP client, the cache and the PSR interfaces are all yours to supply.

Requires PHP 8.4 and ext-openssl, which ships enabled in virtually every PHP build. Nothing else: no bignum extension, no configuration.

What it does

Resolving a DID

A cached document is served for an hour without touching the network, and a stale one for up to a day if the fetch fails. Both bounds are constructor arguments. forceRefresh: true skips the cache, which is what you want after a signature fails to verify and you suspect a rotated key. Without a cache argument, nothing is cached at all.

Resolving a DID you do not trust

A DID that arrives from outside (a token's issuer, a record's subject) decides which URL this library fetches. By default the URL cannot be bent to another host or path, the host has to be a public domain, the document has to claim the DID it was fetched for, and the body is capped at 256 KiB.

If the DIDs you resolve come from a known set, name it. Nothing off the list is fetched, and listing a host is also how you reach one the public-domain rule refuses, like localhost:3000:

What this cannot bound is where a request ends up: DNS and redirects belong to the HTTP client, and the client is yours. docs/untrusted-dids.md has the rules in full and what to ask of the client.

Reading a published key

Only the #atproto keys that belong to the document's own subject come back, and a key that is not on its curve is never one of them. It is a list because a document may publish more than one, and during a rotation the one that verifies a given signature may not be listed first.

If you already have a key in hand, DidKey::fromMultibase() takes the publicKeyMultibase string and DidKey::fromDidKey() takes the did:key:z... form. docs/keys.md covers what is checked and how a compressed point becomes a PEM.

Verifying a service auth token

The package stops short of JWT verification on purpose, so you can bring whatever JWT library you already use. The shape is:

Try every key it hands back rather than stopping at the first, for the rotation reason above. If none of them verifies, resolve again with forceRefresh: true before rejecting the token. That is the one failure a fresher document can fix.

libphpsky wires this up into a full ServiceAuthVerifier with audience, expiry and lxm checks.

Errors

Everything throws IdentityException, which extends RuntimeException.

Development

The test suite generates its own keys with OpenSSL and asserts that the PEM this library derives from the compressed point is byte-for-byte what OpenSSL exports for the same key. No fixtures, no network.

License

MIT