@atcute/identity-resolver

handle and DID document resolution for AT Protocol.

npm install @atcute/identity-resolver

in AT Protocol, handles (like alice.bsky.social) need to be resolved to DIDs, and DIDs need to be resolved to DID documents (which contain the user's PDS location and keys). this package provides resolvers for both.

usage

resolving handles

handles can be resolved via DNS TXT records or HTTP well-known endpoints. use the composite resolver to try both:

import {
    CompositeHandleResolver,
    DohJsonHandleResolver,
    WellKnownHandleResolver,
} from '@atcute/identity-resolver';

const handleResolver = new CompositeHandleResolver({
    methods: {
        dns: new DohJsonHandleResolver({ dohUrl: 'https://mozilla.cloudflare-dns.com/dns-query' }),
        http: new WellKnownHandleResolver(),
    },
});

const did = await handleResolver.resolve('bsky.app');
// -> "did:plc:z72i7hdynmk6r22z27h6tvur"

resolution strategies

the composite resolver supports different strategies for combining DNS and HTTP resolution:

const handleResolver = new CompositeHandleResolver({
    strategy: 'race', // default - first successful response wins
    methods: { dns: dnsResolver, http: httpResolver },
});

available strategies:

• race - returns whichever method succeeds first (default)
• dns-first - try DNS first, fall back to HTTP if it fails
• http-first - try HTTP first, fall back to DNS if it fails
• both - require both methods to agree (throws AmbiguousHandleError if they differ)

resolving DID documents

DID documents can be resolved for did:plc and did:web methods:

import {
    CompositeDidDocumentResolver,
    PlcDidDocumentResolver,
    WebDidDocumentResolver,
} from '@atcute/identity-resolver';

const didResolver = new CompositeDidDocumentResolver({
    methods: {
        plc: new PlcDidDocumentResolver(),
        web: new WebDidDocumentResolver(),
    },
});

const doc = await didResolver.resolve('did:plc:z72i7hdynmk6r22z27h6tvur');
// -> { '@context': [...], id: 'did:plc:...', service: [...], ... }

resolving actors

the ActorResolver interface provides a way to resolve an actor identifier (handle or DID) to the essential info needed to interact with them: their DID, verified handle, and PDS endpoint.

LocalActorResolver implements this by combining handle and DID document resolution locally:

import { LocalActorResolver } from '@atcute/identity-resolver';

const actorResolver = new LocalActorResolver({
    handleResolver,
    didDocumentResolver: didResolver,
});

// resolve from handle
const actor = await actorResolver.resolve('bsky.app');
// -> { did: "did:plc:...", handle: "bsky.app", pds: "https://..." }

// resolve from DID
const actor2 = await actorResolver.resolve('did:plc:z72i7hdynmk6r22z27h6tvur');
// -> { did: "did:plc:...", handle: "bsky.app", pds: "https://..." }

the local resolver performs bidirectional verification: it checks that the handle in the DID document resolves back to the same DID.

other implementations of ActorResolver can get this info from dedicated identity services (like Slingshot) without needing to fetch and parse full DID documents.

handling errors

each resolver throws specific error types for different failure cases:

import {
    DidNotFoundError,
    InvalidResolvedHandleError,
    AmbiguousHandleError,
    FailedHandleResolutionError,
    HandleResolutionError,
} from '@atcute/identity-resolver';

try {
    const did = await handleResolver.resolve('nonexistent.invalid');
} catch (err) {
    if (err instanceof DidNotFoundError) {
        // handle has no DID record
        console.log('handle not found');
    } else if (err instanceof InvalidResolvedHandleError) {
        // handle returned an invalid DID format
        console.log('invalid DID:', err.did);
    } else if (err instanceof AmbiguousHandleError) {
        // multiple different DIDs found (with 'both' strategy)
        console.log('ambiguous handle');
    } else if (err instanceof FailedHandleResolutionError) {
        // network or other unexpected error
        console.log('resolution failed:', err.cause);
    } else if (err instanceof HandleResolutionError) {
        // catch-all for any handle resolution error
    }
}

DID document resolution errors:

import {
    DocumentNotFoundError,
    UnsupportedDidMethodError,
    ImproperDidError,
    FailedDocumentResolutionError,
    DidDocumentResolutionError,
} from '@atcute/identity-resolver';

try {
    const doc = await didResolver.resolve('did:example:123');
} catch (err) {
    if (err instanceof DocumentNotFoundError) {
        // DID document doesn't exist
    } else if (err instanceof UnsupportedDidMethodError) {
        // resolver doesn't support this DID method
    } else if (err instanceof ImproperDidError) {
        // DID format is invalid for this method
    } else if (err instanceof FailedDocumentResolutionError) {
        // network or other unexpected error
    } else if (err instanceof DidDocumentResolutionError) {
        // catch-all for any DID resolution error
    }
}

caching and abort signals

all resolvers accept options for cache control and cancellation:

// skip cache
const did = await handleResolver.resolve('bsky.app', { noCache: true });

// with abort signal
const controller = new AbortController();
const did = await handleResolver.resolve('bsky.app', { signal: controller.signal });

// cancel the request
controller.abort();

custom fetch function

all resolvers accept a custom fetch implementation:

const dnsResolver = new DohJsonHandleResolver({
    dohUrl: 'https://mozilla.cloudflare-dns.com/dns-query',
    fetch: customFetch,
});

const httpResolver = new WellKnownHandleResolver({
    fetch: customFetch,
});

const plcResolver = new PlcDidDocumentResolver({
    fetch: customFetch,
});

server-side resolution and SSRF

resolving untrusted identities on a server can expose internal services to server-side request forgery (SSRF). for example, did:web:localhost%3a6379 targets a loopback address over HTTP, and did:web:169.254.169.254 targets a link-local address.

the resolvers do not restrict destination IPs. pass a custom fetch that rejects non-public addresses at connection time. checking the hostname alone is insufficient: DNS can resolve a public hostname to a private IP.

const didResolver = new CompositeDidDocumentResolver({
    methods: {
        plc: new PlcDidDocumentResolver({ fetch: safeFetch }),
        web: new WebDidDocumentResolver({ fetch: safeFetch }),
    },
});

on Cloudflare Workers, enable global_fetch_strictly_public in the Wrangler configuration. on Node.js, use a fetch dispatcher that checks destination IPs at connection time.

custom PLC directory

by default, did:plc resolution uses https://plc.directory. you can specify a different directory:

const plcResolver = new PlcDidDocumentResolver({
    apiUrl: 'https://plc.wtf', // mirror of plc.directory
});

resolver classes

handle resolvers

DID document resolvers

actor resolvers