@atcute/identity-resolver 0.1.0

package/dist/handle/methods/well-known.js

@@ -0,0 +1,35 @@
+import { isAtprotoDid } from '@atcute/identity';
+import { FailedResponseError, isResponseOk, pipe, readResponseAsText } from '@atcute/util-fetch';
+import * as err from '../../errors.js';
+const fetchWellKnownHandler = pipe(isResponseOk, readResponseAsText(2048 + 16));
+export class WellKnownHandleResolver {
+    #fetch;
+    constructor({ fetch: fetchThis = fetch } = {}) {
+        this.#fetch = fetchThis;
+    }
+    async resolve(handle, options) {
+        let text;
+        try {
+            const url = new URL('/.well-known/atproto-did', `https://${handle}`);
+            const response = await (0, this.#fetch)(url, {
+                signal: options?.signal,
+                cache: options?.noCache ? 'no-cache' : 'default',
+                redirect: 'error',
+            });
+            const handled = await fetchWellKnownHandler(response);
+            text = handled.text;
+        }
+        catch (cause) {
+            if (cause instanceof FailedResponseError && cause.status === 404) {
+                throw new err.DidNotFoundError(handle);
+            }
+            throw new err.FailedHandleResolutionError(handle, { cause });
+        }
+        const did = text.split('\n')[0].trim();
+        if (!isAtprotoDid(did)) {
+            throw new err.InvalidResolvedHandleError(handle, did);
+        }
+        return did;
+    }
+}
+//# sourceMappingURL=well-known.js.map

package/dist/handle/methods/well-known.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.js","sourceRoot":"","sources":["../../../lib/handle/methods/well-known.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAgC,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjG,OAAO,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAOvC,MAAM,qBAAqB,GAAG,IAAI,CAAC,YAAY,EAAE,kBAAkB,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;AAEhF,MAAM,OAAO,uBAAuB;IACnC,MAAM,CAAe;IAErB,YAAY,EAAE,KAAK,EAAE,SAAS,GAAG,KAAK,KAAqC,EAAE;QAC5E,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,OAA8B;QAC3D,IAAI,IAAY,CAAC;QAEjB,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,0BAA0B,EAAE,WAAW,MAAM,EAAE,CAAC,CAAC;YAErE,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE;gBAC5C,MAAM,EAAE,OAAO,EAAE,MAAM;gBACvB,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;gBAChD,QAAQ,EAAE,OAAO;aACjB,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAEtD,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,YAAY,mBAAmB,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAClE,MAAM,IAAI,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;YACxC,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,2BAA2B,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9D,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,CAAC,0BAA0B,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACvD,CAAC;QAED,OAAO,GAAG,CAAC;IACZ,CAAC;CACD"}

package/dist/handle/methods/xrpc.d.ts

@@ -0,0 +1,12 @@
+import { type AtprotoDid, type Handle } from '@atcute/identity';
+import type { HandleResolver, ResolveHandleOptions } from '../../types.js';
+export interface XrpcHandleResolverOptions {
+    serviceUrl: string;
+    fetch?: typeof fetch;
+}
+export declare class XrpcHandleResolver implements HandleResolver {
+    #private;
+    readonly serviceUrl: string;
+    constructor({ serviceUrl, fetch: fetchThis }: XrpcHandleResolverOptions);
+    resolve(handle: Handle, options?: ResolveHandleOptions): Promise<AtprotoDid>;
+}

package/dist/handle/methods/xrpc.js

@@ -0,0 +1,38 @@
+import * as v from '@badrap/valita';
+import { isAtprotoDid } from '@atcute/identity';
+import { FailedResponseError, isResponseOk, parseResponseAsJson, pipe, validateJsonWith, } from '@atcute/util-fetch';
+import * as err from '../../errors.js';
+const response = v.object({
+    did: v.string().assert((input) => isAtprotoDid(input)),
+});
+const fetchXrpcHandler = pipe(isResponseOk, parseResponseAsJson(/^application\/json$/, 4 * 1024), validateJsonWith(response, { mode: 'passthrough' }));
+export class XrpcHandleResolver {
+    serviceUrl;
+    #fetch;
+    constructor({ serviceUrl, fetch: fetchThis = fetch }) {
+        this.serviceUrl = serviceUrl;
+        this.#fetch = fetchThis;
+    }
+    async resolve(handle, options) {
+        let json;
+        try {
+            const url = new URL(`/xrpc/com.atproto.identity.resolveHandle`, this.serviceUrl);
+            url.searchParams.set('handle', handle);
+            const response = await this.#fetch(url, {
+                signal: options?.signal,
+                cache: options?.noCache ? 'no-cache' : 'default',
+                headers: { accept: 'application/json' },
+            });
+            const handled = await fetchXrpcHandler(response);
+            json = handled.json;
+        }
+        catch (cause) {
+            if (cause instanceof FailedResponseError && cause.status === 400) {
+                throw new err.DidNotFoundError(handle);
+            }
+            throw new err.FailedHandleResolutionError(handle, { cause });
+        }
+        return json.did;
+    }
+}
+//# sourceMappingURL=xrpc.js.map

package/dist/handle/methods/xrpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrpc.js","sourceRoot":"","sources":["../../../lib/handle/methods/xrpc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gBAAgB,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAgC,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EACN,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,IAAI,EACJ,gBAAgB,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAGvC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,IAAI,CAC5B,YAAY,EACZ,mBAAmB,CAAC,qBAAqB,EAAE,CAAC,GAAG,IAAI,CAAC,EACpD,gBAAgB,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CACnD,CAAC;AAOF,MAAM,OAAO,kBAAkB;IACrB,UAAU,CAAS;IAC5B,MAAM,CAAe;IAErB,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,GAAG,KAAK,EAA6B;QAC9E,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,OAA8B;QAC3D,IAAI,IAA8B,CAAC;QAEnC,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,0CAA0C,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YACjF,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAEvC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE;gBACvC,MAAM,EAAE,OAAO,EAAE,MAAM;gBACvB,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;gBAChD,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;aACvC,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YAEjD,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,YAAY,mBAAmB,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAClE,MAAM,IAAI,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;YACxC,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,2BAA2B,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9D,CAAC;QAED,OAAO,IAAI,CAAC,GAAG,CAAC;IACjB,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './did/composite.js';
+export * from './did/methods/plc.js';
+export * from './did/methods/web.js';
+export * from './handle/composite.js';
+export * from './handle/methods/doh-json.js';
+export * from './handle/methods/well-known.js';
+export * from './handle/methods/xrpc.js';
+export * from './errors.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from './did/composite.js';
+export * from './did/methods/plc.js';
+export * from './did/methods/web.js';
+export * from './handle/composite.js';
+export * from './handle/methods/doh-json.js';
+export * from './handle/methods/well-known.js';
+export * from './handle/methods/xrpc.js';
+export * from './errors.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AAErC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+import type { AtprotoDid, Did, DidDocument, Handle } from '@atcute/identity';
+export interface ResolveDidDocumentOptions {
+    signal?: AbortSignal;
+    noCache?: boolean;
+}
+export interface DidDocumentResolver<TMethod extends string> {
+    resolve(did: Did<TMethod>, options?: ResolveDidDocumentOptions): Promise<DidDocument>;
+}
+export interface ResolveHandleOptions {
+    signal?: AbortSignal;
+    noCache?: boolean;
+}
+export interface HandleResolver {
+    resolve(handle: Handle, options?: ResolveHandleOptions): Promise<AtprotoDid>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":""}

package/lib/did/composite.ts

@@ -0,0 +1,27 @@
+import { extractDidMethod, type Did, type DidDocument } from '@atcute/identity';
+
+import * as err from '../errors.js';
+import type { DidDocumentResolver, ResolveDidDocumentOptions } from '../types.js';
+
+export interface CompositeDidDocumentResolverOptions<M extends string> {
+	methods: { [K in M]: DidDocumentResolver<K> };
+}
+
+export class CompositeDidDocumentResolver<M extends string> implements DidDocumentResolver<M> {
+	#methods: Map<string, DidDocumentResolver<M>>;
+
+	constructor({ methods }: CompositeDidDocumentResolverOptions<M>) {
+		this.#methods = new Map(Object.entries(methods));
+	}
+
+	async resolve(did: Did<M>, options?: ResolveDidDocumentOptions): Promise<DidDocument> {
+		const method = extractDidMethod(did);
+
+		const resolver = this.#methods.get(method);
+		if (resolver === undefined) {
+			throw new err.UnsupportedDidMethodError(did);
+		}
+
+		return await resolver.resolve(did, options);
+	}
+}

package/lib/did/methods/plc.ts

@@ -0,0 +1,51 @@
+import { type Did, type DidDocument } from '@atcute/identity';
+import { FailedResponseError } from '@atcute/util-fetch';
+
+import * as err from '../../errors.js';
+import type { DidDocumentResolver, ResolveDidDocumentOptions } from '../../types.js';
+import { fetchDocHandler } from '../utils.js';
+
+export interface PlcDidDocumentResolverOptions {
+	apiUrl?: string;
+	fetch?: typeof fetch;
+}
+
+export class PlcDidDocumentResolver implements DidDocumentResolver<'plc'> {
+	readonly apiUrl: string;
+	#fetch: typeof fetch;
+
+	constructor({
+		apiUrl = 'https://plc.directory',
+		fetch: fetchThis = fetch,
+	}: PlcDidDocumentResolverOptions = {}) {
+		this.apiUrl = apiUrl;
+		this.#fetch = fetchThis;
+	}
+
+	async resolve(did: Did<'plc'>, options?: ResolveDidDocumentOptions): Promise<DidDocument> {
+		let json: DidDocument;
+
+		try {
+			const url = new URL(`/${encodeURIComponent(did)}`, this.apiUrl);
+
+			const response = await (0, this.#fetch)(url, {
+				signal: options?.signal,
+				cache: options?.noCache ? 'no-cache' : 'default',
+				redirect: 'error',
+				headers: { accept: 'application/did+ld+json,application/json' },
+			});
+
+			const handled = await fetchDocHandler(response);
+
+			json = handled.json;
+		} catch (cause) {
+			if (cause instanceof FailedResponseError && cause.status === 404) {
+				throw new err.DocumentNotFoundError(did);
+			}
+
+			throw new err.FailedDocumentResolutionError(did, { cause });
+		}
+
+		return json;
+	}
+}

package/lib/did/methods/web.ts

@@ -0,0 +1,85 @@
+import { webDidToDocumentUrl, type Did, type DidDocument } from '@atcute/identity';
+import { FailedResponseError } from '@atcute/util-fetch';
+
+import * as err from '../../errors.js';
+import type { DidDocumentResolver, ResolveDidDocumentOptions } from '../../types.js';
+import { fetchDocHandler } from '../utils.js';
+
+export interface WebDidDocumentResolverOptions {
+	fetch?: typeof fetch;
+}
+
+export class WebDidDocumentResolver implements DidDocumentResolver<'web'> {
+	#fetch: typeof fetch;
+
+	constructor({ fetch: fetchThis = fetch }: WebDidDocumentResolverOptions = {}) {
+		this.#fetch = fetchThis;
+	}
+
+	async resolve(did: Did<'web'>, options?: ResolveDidDocumentOptions): Promise<DidDocument> {
+		let json: DidDocument;
+
+		try {
+			const url = webDidToDocumentUrl(did);
+
+			const response = await (0, this.#fetch)(url, {
+				signal: options?.signal,
+				cache: options?.noCache ? 'no-cache' : 'default',
+				redirect: 'error',
+				headers: { accept: 'application/did+ld+json,application/json' },
+			});
+
+			const handled = await fetchDocHandler(response);
+
+			json = handled.json;
+		} catch (cause) {
+			if (cause instanceof FailedResponseError && cause.status === 404) {
+				throw new err.DocumentNotFoundError(did);
+			}
+
+			throw new err.FailedDocumentResolutionError(did, { cause });
+		}
+
+		return json;
+	}
+}
+
+export class AtprotoWebDidDocumentResolver implements DidDocumentResolver<'web'> {
+	#fetch: typeof fetch;
+
+	constructor({ fetch: fetchThis = fetch }: WebDidDocumentResolverOptions = {}) {
+		this.#fetch = fetchThis;
+	}
+
+	async resolve(did: Did<'web'>, options?: ResolveDidDocumentOptions): Promise<DidDocument> {
+		const [host, ...paths] = did.slice(8).split(':').map(decodeURIComponent);
+		const url = new URL(`https://${host}/.well-known/did.json`);
+
+		if (paths.length > 0) {
+			throw new err.ImproperDidError(did);
+		}
+
+		let json: DidDocument;
+
+		try {
+			const response = await (0, this.#fetch)(url, {
+				signal: options?.signal,
+				cache: options?.noCache ? 'no-cache' : 'default',
+				redirect: 'error',
+				headers: { accept: 'application/did+ld+json,application/json' },
+			});
+
+			const handled = await fetchDocHandler(response);
+
+			json = handled.json;
+		} catch (cause) {
+			if (cause instanceof FailedResponseError && cause.status === 404) {
+				throw new err.DocumentNotFoundError(did);
+			}
+
+			throw new err.FailedDocumentResolutionError(did, { cause });
+		}
+
+		return json;
+	}
+}

package/lib/did/utils.ts

@@ -0,0 +1,8 @@
+import { defs } from '@atcute/identity';
+import { isResponseOk, parseResponseAsJson, pipe, validateJsonWith } from '@atcute/util-fetch';
+
+export const fetchDocHandler = pipe(
+	isResponseOk,
+	parseResponseAsJson(/^application\/(did\+ld\+)?json$/, 20 * 1024),
+	validateJsonWith(defs.didDocument, { mode: 'passthrough' }),
+);

package/lib/errors.ts

@@ -0,0 +1,86 @@
+import type { Did } from '@atcute/identity';
+
+// #region DID document resolution errors
+export class DidDocumentResolutionError extends Error {
+	override name = 'DidResolutionError';
+}
+
+export class UnsupportedDidMethodError extends DidDocumentResolutionError {
+	override name = 'UnsupportedDidMethodError';
+
+	constructor(public did: Did) {
+		super(`unsupported did method; did=${did}`);
+	}
+}
+
+export class ImproperDidError extends DidDocumentResolutionError {
+	override name = 'ImproperDidError';
+
+	constructor(public did: Did) {
+		super(`improper did; did=${did}`);
+	}
+}
+
+export class DocumentNotFoundError extends DidDocumentResolutionError {
+	override name = 'DocumentNotFoundError';
+
+	constructor(public did: Did) {
+		super(`did document not found; did=${did}`);
+	}
+}
+
+export class FailedDocumentResolutionError extends DidDocumentResolutionError {
+	override name = 'FailedDocumentResolutionError';
+
+	constructor(
+		public did: Did,
+		options?: ErrorOptions,
+	) {
+		super(`failed to resolve did document; did=${did}`, options);
+	}
+}
+// #endregion
+
+// #region Handle resolution errors
+export class HandleResolutionError extends Error {
+	override name = 'HandleResolutionError';
+}
+
+export class DidNotFoundError extends HandleResolutionError {
+	override name = 'DidNotFoundError';
+
+	constructor(public handle: string) {
+		super(`handle returned no did; handle=${handle}`);
+	}
+}
+
+export class FailedHandleResolutionError extends HandleResolutionError {
+	override name = 'FailedHandleResolutionError';
+
+	constructor(
+		public handle: string,
+		options?: ErrorOptions,
+	) {
+		super(`failed to resolve handle; handle=${handle}`, options);
+	}
+}
+
+export class InvalidResolvedHandleError extends HandleResolutionError {
+	override name = 'InvalidResolvedHandleError';
+
+	constructor(
+		public handle: string,
+		public did: string,
+	) {
+		super(`handle returned invalid did; handle=${handle}; did=${did}`);
+	}
+}
+
+export class AmbiguousHandleError extends HandleResolutionError {
+	override name = 'AmbiguousHandleError';
+
+	constructor(handle: string) {
+		super(`handle returned multiple did values; handle=${handle}`);
+	}
+}
+// #endregion

package/lib/handle/composite.ts

@@ -0,0 +1,94 @@
+import type { AtprotoDid, Handle } from '@atcute/identity';
+
+import * as err from '../errors.js';
+import type { HandleResolver, ResolveHandleOptions } from '../types.js';
+
+export type CompositeStrategy = 'http-first' | 'dns-first' | 'race' | 'both';
+
+export interface CompositeHandleResolverOptions {
+	/** controls how the resolution is done, defaults to 'race' */
+	strategy?: CompositeStrategy;
+	/** the methods to use for resolving the handle. */
+	methods: Record<'http' | 'dns', HandleResolver>;
+}
+
+export class CompositeHandleResolver implements HandleResolver {
+	#methods: Record<'http' | 'dns', HandleResolver>;
+	strategy: CompositeStrategy;
+
+	constructor({ methods, strategy = 'race' }: CompositeHandleResolverOptions) {
+		this.#methods = methods;
+		this.strategy = strategy;
+	}
+
+	async resolve(handle: Handle, options?: ResolveHandleOptions): Promise<AtprotoDid> {
+		const { http, dns } = this.#methods;
+
+		const parentSignal = options?.signal;
+		const controller = new AbortController();
+		if (parentSignal) {
+			parentSignal.addEventListener('abort', () => controller.abort(), { signal: controller.signal });
+		}
+
+		const dnsPromise = dns.resolve(handle, { ...options, signal: controller.signal });
+		const httpPromise = http.resolve(handle, { ...options, signal: controller.signal });
+
+		switch (this.strategy) {
+			case 'race': {
+				return new Promise((resolve) => {
+					dnsPromise.then(
+						(did) => {
+							controller.abort();
+							resolve(did);
+						},
+						() => resolve(httpPromise),
+					);
+
+					httpPromise.then(
+						(did) => {
+							controller.abort();
+							resolve(did);
+						},
+						() => resolve(dnsPromise),
+					);
+				});
+			}
+			case 'dns-first': {
+				httpPromise.catch(noop);
+
+				const resolved = await dnsPromise.catch(noop);
+				if (resolved) {
+					controller.abort();
+					return resolved;
+				}
+
+				return httpPromise;
+			}
+			case 'http-first': {
+				dnsPromise.catch(noop);
+
+				const resolved = await httpPromise.catch(noop);
+				if (resolved) {
+					controller.abort();
+					return resolved;
+				}
+
+				return dnsPromise;
+			}
+			case 'both': {
+				const [dnsResponse, httpResponse] = await Promise.allSettled([dnsPromise, httpPromise]);
+
+				const dnsDid = dnsResponse.status === 'fulfilled' ? dnsResponse.value : undefined;
+				const httpDid = httpResponse.status === 'fulfilled' ? httpResponse.value : undefined;
+
+				if (dnsDid && httpDid && dnsDid !== httpDid) {
+					throw new err.AmbiguousHandleError(handle);
+				}
+
+				return dnsDid || httpDid || dnsPromise;
+			}
+		}
+	}
+}
+
+const noop = () => {};

package/lib/handle/methods/doh-json.ts

@@ -0,0 +1,138 @@
+import * as v from '@badrap/valita';
+
+import { isAtprotoDid, type AtprotoDid, type Handle } from '@atcute/identity';
+import { isResponseOk, parseResponseAsJson, pipe, validateJsonWith } from '@atcute/util-fetch';
+
+import * as err from '../../errors.js';
+import type { HandleResolver, ResolveHandleOptions } from '../../types.js';
+
+const uint32 = v.number().assert((input) => Number.isInteger(input) && input >= 0 && input <= 2 ** 32 - 1);
+
+const question = v.object({
+	name: v.string(),
+	type: v.literal(16), // TXT
+});
+
+const answer = v.object({
+	name: v.string(),
+	type: v.literal(16), // TXT
+	TTL: uint32,
+	data: v.string().chain((input) => {
+		return v.ok(input.replace(/^"|"$/g, '').replace(/\\"/g, '"'));
+	}),
+});
+
+const authority = v.object({
+	name: v.string(),
+	type: uint32,
+	TTL: uint32,
+	data: v.string(),
+});
+
+const result = v.object({
+	/** DNS response code */
+	Status: uint32,
+	/** Whether response is truncated */
+	TC: v.boolean(),
+	/** Whether recursive desired bit is set, always true for Google and Cloudflare DoH */
+	RD: v.boolean(),
+	/** Whether recursive available bit is set, always true for Google and Cloudflare DoH */
+	RA: v.boolean(),
+	/** Whether response data was validated with DNSSEC */
+	AD: v.boolean(),
+	/** Whether client asked to disable DNSSEC validation */
+	CD: v.boolean(),
+	/** Requested records */
+	Question: v.tuple([question]),
+	/** Answers */
+	Answer: v.array(answer).optional(() => []),
+	/** Authority */
+	Authority: v.array(authority).optional(),
+	/** Comment from the DNS server */
+	Comment: v.string().optional(),
+});
+
+const SUBDOMAIN = '_atproto';
+const PREFIX = 'did=';
+
+const fetchDohJsonHandler = pipe(
+	isResponseOk,
+	parseResponseAsJson(/^application\/(dns-)?json$/, 16 * 1024),
+	validateJsonWith(result, { mode: 'passthrough' }),
+);
+
+export interface DohJsonHandleResolverOptions {
+	dohUrl: string;
+	fetch?: typeof fetch;
+}
+
+export class DohJsonHandleResolver implements HandleResolver {
+	readonly dohUrl: string;
+	#fetch: typeof fetch;
+
+	constructor({ dohUrl, fetch: fetchThis = fetch }: DohJsonHandleResolverOptions) {
+		this.dohUrl = dohUrl;
+		this.#fetch = fetchThis;
+	}
+
+	async resolve(handle: Handle, options?: ResolveHandleOptions): Promise<AtprotoDid> {
+		let json: v.Infer<typeof result>;
+
+		try {
+			const url = new URL(this.dohUrl);
+			url.searchParams.set('name', `${SUBDOMAIN}.${handle}`);
+			url.searchParams.set('type', 'TXT');
+
+			const response = await (0, this.#fetch)(url, {
+				signal: options?.signal,
+				cache: options?.noCache ? 'no-cache' : 'default',
+				headers: { accept: 'application/dns-json' },
+			});
+
+			const handled = await fetchDohJsonHandler(response);
+
+			json = handled.json;
+		} catch (cause) {
+			throw new err.FailedHandleResolutionError(handle, { cause });
+		}
+
+		const status = json.Status;
+		const answers = json.Answer;
+
+		if (status !== 0 /* NOERROR */) {
+			if (status === 3 /* NXDOMAIN */) {
+				throw new err.DidNotFoundError(handle);
+			}
+
+			throw new err.FailedHandleResolutionError(handle, {
+				cause: new TypeError(`dns returned ${status}`),
+			});
+		}
+
+		for (let i = 0, il = answers.length; i < il; i++) {
+			const answer = answers[i];
+			const data = answer.data;
+
+			if (!data.startsWith(PREFIX)) {
+				continue;
+			}
+
+			for (let j = i + 1; j < il; j++) {
+				const data = answers[j].data;
+				if (data.startsWith(PREFIX)) {
+					throw new err.AmbiguousHandleError(handle);
+				}
+			}
+
+			const did = data.slice(PREFIX.length);
+			if (!isAtprotoDid(did)) {
+				throw new err.InvalidResolvedHandleError(handle, did);
+			}
+
+			return did;
+		}
+
+		// theoretically this shouldn't happen, it should've returned NXDOMAIN
+		throw new err.DidNotFoundError(handle);
+	}
+}