@bskyprism/atproto-oauth-client-cloudflare-workers 0.2.2

package/lib/handle-resolver/atproto-doh-handle-resolver.js

@@ -0,0 +1,94 @@
+import { AtprotoHandleResolver, } from "./atproto-handle-resolver.js";
+import { HandleResolverError } from "./handle-resolver-error.js";
+export class AtprotoDohHandleResolver extends AtprotoHandleResolver {
+    constructor(options) {
+        super({
+            ...options,
+            resolveTxt: dohResolveTxtFactory(options),
+            resolveTxtFallback: undefined,
+        });
+    }
+}
+/**
+ * Resolver for DNS-over-HTTPS (DoH) handles. Only works with servers supporting
+ * Google Flavoured "application/dns-json" queries.
+ *
+ * @see {@link https://developers.google.com/speed/public-dns/docs/doh/json}
+ * @see {@link https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/}
+ * @todo Add support for DoH using application/dns-message (?)
+ */
+function dohResolveTxtFactory({ dohEndpoint, fetch = globalThis.fetch, }) {
+    return async (hostname) => {
+        const url = new URL(dohEndpoint);
+        url.searchParams.set("type", "TXT");
+        url.searchParams.set("name", hostname);
+        const response = await fetch(url, {
+            method: "GET",
+            headers: { accept: "application/dns-json" },
+            redirect: "follow",
+        });
+        try {
+            const contentType = response.headers.get("content-type")?.trim();
+            if (!response.ok) {
+                const message = contentType?.startsWith("text/plain")
+                    ? await response.text()
+                    : `Failed to resolve ${hostname}`;
+                throw new HandleResolverError(message);
+            }
+            else if (contentType?.match(/application\/(dns-)?json/i) == null) {
+                throw new HandleResolverError("Unexpected response from DoH server");
+            }
+            const result = asResult(await response.json());
+            return result.Answer?.filter(isAnswerTxt).map(extractTxtData) ?? null;
+        }
+        finally {
+            // Make sure to always cancel the response body as some engines (Node 👀)
+            // do not do this automatically.
+            // https://undici.nodejs.org/#/?id=garbage-collection
+            if (response.bodyUsed === false) {
+                // Handle rejection asynchronously
+                void response.body?.cancel().catch(onCancelError);
+            }
+        }
+    };
+}
+function onCancelError(err) {
+    if (!(err instanceof DOMException) || err.name !== "AbortError") {
+        console.error("An error occurred while cancelling the response body:", err);
+    }
+}
+function isResult(result) {
+    if (typeof result !== "object" || result === null)
+        return false;
+    if (!("Status" in result) || typeof result.Status !== "number")
+        return false;
+    if ("Answer" in result && !isArrayOf(result.Answer, isAnswer))
+        return false;
+    return true;
+}
+function asResult(result) {
+    if (isResult(result))
+        return result;
+    throw new HandleResolverError("Invalid DoH response");
+}
+function isArrayOf(value, predicate) {
+    return Array.isArray(value) && value.every(predicate);
+}
+function isAnswer(answer) {
+    return (typeof answer === "object" &&
+        answer !== null &&
+        "name" in answer &&
+        typeof answer.name === "string" &&
+        "type" in answer &&
+        typeof answer.type === "number" &&
+        "data" in answer &&
+        typeof answer.data === "string" &&
+        "TTL" in answer &&
+        typeof answer.TTL === "number");
+}
+function isAnswerTxt(answer) {
+    return answer.type === 16;
+}
+function extractTxtData(answer) {
+    return answer.data.replace(/^"|"$/g, "").replace(/\\"/g, '"');
+}

package/lib/handle-resolver/atproto-handle-resolver.d.ts

@@ -0,0 +1,21 @@
+import { ResolveTxt } from "./internal-resolvers/dns-handle-resolver.js";
+import { WellKnownHandleResolverOptions } from "./internal-resolvers/well-known-handler-resolver.js";
+import { HandleResolver, ResolveHandleOptions, ResolvedHandle } from "./types.js";
+export type { ResolveTxt };
+export type AtprotoHandleResolverOptions = WellKnownHandleResolverOptions & {
+    resolveTxt: ResolveTxt;
+    resolveTxtFallback?: ResolveTxt;
+};
+/**
+ * Implementation of the official ATPROTO handle resolution strategy.
+ * This implementation relies on two primitives:
+ * - HTTP Well-Known URI resolution (requires a `fetch()` implementation)
+ * - DNS TXT record resolution (requires a `resolveTxt()` function)
+ */
+export declare class AtprotoHandleResolver implements HandleResolver {
+    private readonly httpResolver;
+    private readonly dnsResolver;
+    private readonly dnsResolverFallback?;
+    constructor(options: AtprotoHandleResolverOptions);
+    resolve(handle: string, options?: ResolveHandleOptions): Promise<ResolvedHandle>;
+}

package/lib/handle-resolver/atproto-handle-resolver.js

@@ -0,0 +1,46 @@
+import { DnsHandleResolver, } from "./internal-resolvers/dns-handle-resolver.js";
+import { WellKnownHandleResolver, } from "./internal-resolvers/well-known-handler-resolver.js";
+const noop = () => { };
+/**
+ * Implementation of the official ATPROTO handle resolution strategy.
+ * This implementation relies on two primitives:
+ * - HTTP Well-Known URI resolution (requires a `fetch()` implementation)
+ * - DNS TXT record resolution (requires a `resolveTxt()` function)
+ */
+export class AtprotoHandleResolver {
+    constructor(options) {
+        this.httpResolver = new WellKnownHandleResolver(options);
+        this.dnsResolver = new DnsHandleResolver(options.resolveTxt);
+        this.dnsResolverFallback = options.resolveTxtFallback
+            ? new DnsHandleResolver(options.resolveTxtFallback)
+            : undefined;
+    }
+    async resolve(handle, options) {
+        options?.signal?.throwIfAborted();
+        const abortController = new AbortController();
+        const { signal } = abortController;
+        options?.signal?.addEventListener("abort", () => abortController.abort(), {
+            signal,
+        });
+        const wrappedOptions = { ...options, signal };
+        try {
+            const dnsPromise = this.dnsResolver.resolve(handle, wrappedOptions);
+            const httpPromise = this.httpResolver.resolve(handle, wrappedOptions);
+            // Prevent uncaught promise rejection
+            httpPromise.catch(noop);
+            const dnsRes = await dnsPromise;
+            if (dnsRes)
+                return dnsRes;
+            signal.throwIfAborted();
+            const res = await httpPromise;
+            if (res)
+                return res;
+            signal.throwIfAborted();
+            return this.dnsResolverFallback?.resolve(handle, wrappedOptions) ?? null;
+        }
+        finally {
+            // Cancel pending requests, and remove "abort" listener on incoming signal
+            abortController.abort();
+        }
+    }
+}

package/lib/handle-resolver/cached-handle-resolver.d.ts

@@ -0,0 +1,12 @@
+import { SimpleStore } from "@atproto-labs/simple-store";
+import { HandleResolver, ResolveHandleOptions, ResolvedHandle } from "./types.js";
+export type HandleCache = SimpleStore<string, ResolvedHandle>;
+export declare class CachedHandleResolver implements HandleResolver {
+    private getter;
+    constructor(
+    /**
+     * The resolver that will be used to resolve handles.
+     */
+    resolver: HandleResolver, cache?: HandleCache);
+    resolve(handle: string, options?: ResolveHandleOptions): Promise<ResolvedHandle>;
+}

package/lib/handle-resolver/cached-handle-resolver.js

@@ -0,0 +1,17 @@
+import { CachedGetter } from "@atproto-labs/simple-store";
+import { SimpleStoreMemory } from "@atproto-labs/simple-store-memory";
+export class CachedHandleResolver {
+    constructor(
+    /**
+     * The resolver that will be used to resolve handles.
+     */
+    resolver, cache = new SimpleStoreMemory({
+        max: 1000,
+        ttl: 10 * 60e3,
+    })) {
+        this.getter = new CachedGetter((handle, options) => resolver.resolve(handle, options), cache);
+    }
+    async resolve(handle, options) {
+        return this.getter.get(handle, options);
+    }
+}

package/lib/handle-resolver/handle-resolver-error.d.ts

@@ -0,0 +1,3 @@
+export declare class HandleResolverError extends Error {
+    name: string;
+}

package/lib/handle-resolver/handle-resolver-error.js

@@ -0,0 +1,6 @@
+export class HandleResolverError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "HandleResolverError";
+    }
+}

package/lib/handle-resolver/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./handle-resolver-error.js";
+export * from "./types.js";
+export * from "./xrpc-handle-resolver.js";
+export * from "./atproto-doh-handle-resolver.js";
+export * from "./atproto-handle-resolver.js";
+export * from "./cached-handle-resolver.js";

package/lib/handle-resolver/index.js

@@ -0,0 +1,8 @@
+export * from "./handle-resolver-error.js";
+export * from "./types.js";
+// Main Handle Resolvers strategies
+export * from "./xrpc-handle-resolver.js";
+export * from "./atproto-doh-handle-resolver.js";
+export * from "./atproto-handle-resolver.js";
+// Handle Resolver Caching utility
+export * from "./cached-handle-resolver.js";

package/lib/handle-resolver/internal-resolvers/dns-handle-resolver.d.ts

@@ -0,0 +1,11 @@
+import { HandleResolver, ResolvedHandle } from "../types.js";
+/**
+ * DNS TXT record resolver. Return `null` if the hostname successfully does not
+ * resolve to a valid DID. Throw an error if an unexpected error occurs.
+ */
+export type ResolveTxt = (hostname: string) => Promise<null | string[]>;
+export declare class DnsHandleResolver implements HandleResolver {
+    protected resolveTxt: ResolveTxt;
+    constructor(resolveTxt: ResolveTxt);
+    resolve(handle: string): Promise<ResolvedHandle>;
+}

package/lib/handle-resolver/internal-resolvers/dns-handle-resolver.js

@@ -0,0 +1,28 @@
+import { isResolvedHandle } from "../types.js";
+const SUBDOMAIN = "_atproto";
+const PREFIX = "did=";
+export class DnsHandleResolver {
+    constructor(resolveTxt) {
+        this.resolveTxt = resolveTxt;
+    }
+    async resolve(handle) {
+        const results = await this.resolveTxt.call(null, `${SUBDOMAIN}.${handle}`);
+        if (!results)
+            return null;
+        for (let i = 0; i < results.length; i++) {
+            // If the line does not start with "did=", skip it
+            if (!results[i].startsWith(PREFIX))
+                continue;
+            // Ensure no other entry starting with "did=" follows
+            for (let j = i + 1; j < results.length; j++) {
+                if (results[j].startsWith(PREFIX))
+                    return null;
+            }
+            // Note: No trimming (to be consistent with spec)
+            const did = results[i].slice(PREFIX.length);
+            // Invalid DBS record
+            return isResolvedHandle(did) ? did : null;
+        }
+        return null;
+    }
+}

package/lib/handle-resolver/internal-resolvers/well-known-handler-resolver.d.ts

@@ -0,0 +1,17 @@
+import { HandleResolver, ResolveHandleOptions, ResolvedHandle } from "../types.js";
+export type WellKnownHandleResolverOptions = {
+    /**
+     * Fetch function to use for HTTP requests. Allows customizing the request
+     * behavior, e.g. adding headers, setting a timeout, mocking, etc. The
+     * provided fetch function will be wrapped with a safeFetchWrap function that
+     * adds SSRF protection.
+     *
+     * @default `globalThis.fetch`
+     */
+    fetch?: typeof globalThis.fetch;
+};
+export declare class WellKnownHandleResolver implements HandleResolver {
+    protected readonly fetch: typeof globalThis.fetch;
+    constructor(options?: WellKnownHandleResolverOptions);
+    resolve(handle: string, options?: ResolveHandleOptions): Promise<ResolvedHandle>;
+}

package/lib/handle-resolver/internal-resolvers/well-known-handler-resolver.js

@@ -0,0 +1,28 @@
+import { isResolvedHandle, } from "../types.js";
+export class WellKnownHandleResolver {
+    constructor(options) {
+        this.fetch = options?.fetch ?? globalThis.fetch;
+    }
+    async resolve(handle, options) {
+        const url = new URL("/.well-known/atproto-did", `https://${handle}`);
+        try {
+            const response = await this.fetch.call(null, url, {
+                // cache: options?.noCache ? "no-cache" : undefined,
+                signal: options?.signal,
+                redirect: "follow",
+                headers: { "cache-control": "no-cache" },
+            });
+            const text = await response.text();
+            const firstLine = text.split("\n")[0].trim();
+            if (isResolvedHandle(firstLine))
+                return firstLine;
+            return null;
+        }
+        catch (err) {
+            // The the request failed, assume the handle does not resolve to a DID,
+            // unless the failure was due to the signal being aborted.
+            options?.signal?.throwIfAborted();
+            return null;
+        }
+    }
+}

package/lib/handle-resolver/types.d.ts

@@ -0,0 +1,25 @@
+import { AtprotoDid } from "@atproto/did";
+export type { AtprotoDid, AtprotoIdentityDidMethods } from "@atproto/did";
+export type ResolveHandleOptions = {
+    signal?: AbortSignal;
+    noCache?: boolean;
+};
+/**
+ * @see {@link https://atproto.com/specs/did#blessed-did-methods}
+ */
+export type ResolvedHandle = null | AtprotoDid;
+/**
+ * @see {@link https://atproto.com/specs/did#blessed-did-methods}
+ */
+export declare function isResolvedHandle<T>(value: T): value is T & ResolvedHandle;
+export declare function asResolvedHandle(value: string): ResolvedHandle;
+export interface HandleResolver {
+    /**
+     * @returns the DID that corresponds to the given handle, or `null` if no DID
+     * is found. `null` should only be returned if no unexpected behavior occurred
+     * during the resolution process.
+     * @throws Error if the resolution method fails due to an unexpected error, or
+     * if the resolution is aborted ({@link ResolveHandleOptions}).
+     */
+    resolve(handle: string, options?: ResolveHandleOptions): Promise<ResolvedHandle>;
+}

package/lib/handle-resolver/types.js

@@ -0,0 +1,10 @@
+import { isAtprotoDid } from "@atproto/did";
+/**
+ * @see {@link https://atproto.com/specs/did#blessed-did-methods}
+ */
+export function isResolvedHandle(value) {
+    return value === null || isAtprotoDid(value);
+}
+export function asResolvedHandle(value) {
+    return isResolvedHandle(value) ? value : null;
+}

package/lib/handle-resolver/xrpc-handle-resolver.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { HandleResolver, ResolveHandleOptions, ResolvedHandle } from "./types.js";
+export declare const xrpcErrorSchema: z.ZodObject<{
+    error: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+    message?: string | undefined;
+}, {
+    error: string;
+    message?: string | undefined;
+}>;
+export type XrpcHandleResolverOptions = {
+    /**
+     * Fetch function to use for HTTP requests. Allows customizing the request
+     * behavior, e.g. adding headers, setting a timeout, mocking, etc.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof globalThis.fetch;
+};
+export declare class XrpcHandleResolver implements HandleResolver {
+    /**
+     * URL of the atproto lexicon server. This is the base URL where the
+     * `com.atproto.identity.resolveHandle` XRPC method is located.
+     */
+    protected readonly serviceUrl: URL;
+    protected readonly fetch: typeof globalThis.fetch;
+    constructor(service: URL | string, options?: XrpcHandleResolverOptions);
+    resolve(handle: string, options?: ResolveHandleOptions): Promise<ResolvedHandle>;
+}

package/lib/handle-resolver/xrpc-handle-resolver.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { HandleResolverError } from "./handle-resolver-error.js";
+import { isResolvedHandle, } from "./types.js";
+export const xrpcErrorSchema = z.object({
+    error: z.string(),
+    message: z.string().optional(),
+});
+export class XrpcHandleResolver {
+    constructor(service, options) {
+        this.serviceUrl = new URL(service);
+        this.fetch = options?.fetch ?? globalThis.fetch;
+    }
+    async resolve(handle, options) {
+        const url = new URL("/xrpc/com.atproto.identity.resolveHandle", this.serviceUrl);
+        url.searchParams.set("handle", handle);
+        const response = await this.fetch.call(null, url, {
+            cache: options?.noCache ? "no-cache" : undefined,
+            signal: options?.signal,
+            redirect: "follow",
+        });
+        const payload = await response.json();
+        // The response should either be
+        // - 400 Bad Request with { error: 'InvalidRequest', message: 'Unable to resolve handle' }
+        // - 200 OK with { did: NonNullable<ResolvedHandle> }
+        // Any other response is considered unexpected behavior an should throw an error.
+        if (response.status === 400) {
+            const { error, data } = xrpcErrorSchema.safeParse(payload);
+            if (error) {
+                throw new HandleResolverError(`Invalid response from resolveHandle method: ${error.message}`, { cause: error });
+            }
+            if (data.error === "InvalidRequest" &&
+                data.message === "Unable to resolve handle") {
+                return null;
+            }
+        }
+        if (!response.ok) {
+            throw new HandleResolverError("Invalid status code from resolveHandle method");
+        }
+        const value = payload?.did;
+        if (!isResolvedHandle(value)) {
+            throw new HandleResolverError("Invalid DID returned from resolveHandle method");
+        }
+        return value;
+    }
+}

package/lib/handle-resolver.d.ts

@@ -0,0 +1,20 @@
+import { AtprotoHandleResolver, HandleResolver } from "#handle-resolver";
+export type AtprotoHandleResolverWorkersOptions = {
+    /**
+     * List of backup nameservers to use in case the primary ones fail. Will
+     * default to no fallback nameservers.
+     */
+    fallbackNameservers?: string[];
+    /**
+     * Fetch function to use for HTTP requests. Allows customizing the request
+     * behavior, e.g. adding headers, setting a timeout, mocking, etc. The
+     * provided fetch function will be wrapped with a safeFetchWrap function that
+     * adds SSRF protection.
+     *
+     * @default `globalThis.fetch`
+     */
+    fetch?: (typeof globalThis)["fetch"];
+};
+export declare class AtprotoHandleResolverWorkers extends AtprotoHandleResolver implements HandleResolver {
+    constructor({ fetch, fallbackNameservers, }?: AtprotoHandleResolverWorkersOptions);
+}

package/lib/handle-resolver.js

@@ -0,0 +1,19 @@
+import { AtprotoHandleResolver } from "#handle-resolver";
+import { resolveTxtDefault, resolveTxtFactory } from "./resolve-txt-factory.js";
+export class AtprotoHandleResolverWorkers extends AtprotoHandleResolver {
+    constructor({ fetch = globalThis.fetch, fallbackNameservers, } = {}) {
+        super({
+            fetch: fetch,
+            // fetch: safeFetchWrap({
+            // 	fetch,
+            // 	timeout: 3000, // 3 seconds
+            // 	ssrfProtection: true,
+            // 	responseMaxSize: 10 * 1048, // DID are max 2048 characters, 10kb for safety
+            // }),
+            resolveTxt: resolveTxtDefault,
+            resolveTxtFallback: fallbackNameservers?.length
+                ? resolveTxtFactory(fallbackNameservers)
+                : undefined,
+        });
+    }
+}

package/lib/identity-resolver/atproto-identity-resolver.d.ts

@@ -0,0 +1,20 @@
+import { AtprotoDid, AtprotoIdentityDidMethods, DidDocument } from "@atproto/did";
+import { DidResolver, ResolveDidOptions } from "#did-resolver";
+import { HandleResolver, ResolveHandleOptions } from "#handle-resolver";
+import { IdentityInfo, IdentityResolver, ResolveIdentityOptions } from "./identity-resolver.js";
+/**
+ * Implementation of the official ATPROTO identity resolution strategy.
+ * This implementation relies on two primitives:
+ * - DID resolution (using the `DidResolver` interface)
+ * - Handle resolution (using the `HandleResolver` interface)
+ */
+export declare class AtprotoIdentityResolver implements IdentityResolver {
+    protected readonly didResolver: DidResolver<AtprotoIdentityDidMethods>;
+    protected readonly handleResolver: HandleResolver;
+    constructor(didResolver: DidResolver<AtprotoIdentityDidMethods>, handleResolver: HandleResolver);
+    resolve(input: string, options?: ResolveIdentityOptions): Promise<IdentityInfo>;
+    resolveFromDid(did: AtprotoDid, options?: ResolveDidOptions): Promise<IdentityInfo>;
+    resolveFromHandle(handle: string, options?: ResolveHandleOptions): Promise<IdentityInfo>;
+    getDocumentFromDid(did: AtprotoDid, options?: ResolveDidOptions): Promise<DidDocument<AtprotoIdentityDidMethods>>;
+    getDocumentFromHandle(input: string, options?: ResolveHandleOptions): Promise<DidDocument<AtprotoIdentityDidMethods>>;
+}

package/lib/identity-resolver/atproto-identity-resolver.js

@@ -0,0 +1,72 @@
+import { isAtprotoDid, } from "@atproto/did";
+import { HANDLE_INVALID } from "./constants.js";
+import { IdentityResolverError } from "./identity-resolver-error.js";
+import { asNormalizedHandle, extractNormalizedHandle } from "./util.js";
+// @TODO Move this to its own package as soon as we have a distinct
+// implementation based on XRPC calls to the
+// "com.atproto.identity.resolveIdentity" method.
+/**
+ * Implementation of the official ATPROTO identity resolution strategy.
+ * This implementation relies on two primitives:
+ * - DID resolution (using the `DidResolver` interface)
+ * - Handle resolution (using the `HandleResolver` interface)
+ */
+export class AtprotoIdentityResolver {
+    constructor(didResolver, handleResolver) {
+        this.didResolver = didResolver;
+        this.handleResolver = handleResolver;
+    }
+    async resolve(input, options) {
+        return isAtprotoDid(input)
+            ? this.resolveFromDid(input, options)
+            : this.resolveFromHandle(input, options);
+    }
+    async resolveFromDid(did, options) {
+        const document = await this.getDocumentFromDid(did, options);
+        options?.signal?.throwIfAborted();
+        // We will only return the document's handle alias if it resolves to the
+        // same DID as the input.
+        const handle = extractNormalizedHandle(document);
+        const resolvedDid = handle
+            ? await this.handleResolver
+                .resolve(handle, options)
+                .catch(() => undefined) // Ignore errors (temporarily unavailable)
+            : undefined;
+        return {
+            did: document.id,
+            didDoc: document,
+            handle: handle && resolvedDid === did ? handle : HANDLE_INVALID,
+        };
+    }
+    async resolveFromHandle(handle, options) {
+        const document = await this.getDocumentFromHandle(handle, options);
+        // @NOTE bi-directional resolution enforced in getDocumentFromHandle()
+        return {
+            did: document.id,
+            didDoc: document,
+            handle: extractNormalizedHandle(document) || HANDLE_INVALID,
+        };
+    }
+    async getDocumentFromDid(did, options) {
+        return this.didResolver.resolve(did, options);
+    }
+    async getDocumentFromHandle(input, options) {
+        const handle = asNormalizedHandle(input);
+        if (!handle) {
+            throw new IdentityResolverError(`Invalid handle "${input}" provided.`);
+        }
+        const did = await this.handleResolver.resolve(handle, options);
+        if (!did) {
+            throw new IdentityResolverError(`Handle "${handle}" does not resolve to a DID`);
+        }
+        options?.signal?.throwIfAborted();
+        // Note: Not using "return this.resolveDid(did, options)" to make the extra
+        // check for the handle in the DID document:
+        const document = await this.didResolver.resolve(did, options);
+        // Enforce bi-directional resolution
+        if (handle !== extractNormalizedHandle(document)) {
+            throw new IdentityResolverError(`Did document for "${did}" does not include the handle "${handle}"`);
+        }
+        return document;
+    }
+}

package/lib/identity-resolver/constants.d.ts

@@ -0,0 +1 @@
+export declare const HANDLE_INVALID = "handle.invalid";

package/lib/identity-resolver/constants.js

@@ -0,0 +1 @@
+export const HANDLE_INVALID = "handle.invalid";

package/lib/identity-resolver/identity-resolver-error.d.ts

@@ -0,0 +1,3 @@
+export declare class IdentityResolverError extends Error {
+    name: string;
+}

package/lib/identity-resolver/identity-resolver-error.js

@@ -0,0 +1,6 @@
+export class IdentityResolverError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "IdentityResolverError";
+    }
+}

package/lib/identity-resolver/identity-resolver.d.ts

@@ -0,0 +1,19 @@
+import { AtprotoDid, AtprotoIdentityDidMethods, DidDocument } from "@atproto/did";
+import { HANDLE_INVALID } from "./constants.js";
+export type IdentityInfo = {
+    did: AtprotoDid;
+    didDoc: DidDocument<AtprotoIdentityDidMethods>;
+    /**
+     * Will be 'handle.invalid' if the handle does not resolve to the
+     * same DID as the input, or if the handle is not present in the DID
+     * document.
+     */
+    handle: typeof HANDLE_INVALID | string;
+};
+export type ResolveIdentityOptions = {
+    signal?: AbortSignal;
+    noCache?: boolean;
+};
+export interface IdentityResolver {
+    resolve(identifier: string, options?: ResolveIdentityOptions): Promise<IdentityInfo>;
+}

package/lib/identity-resolver/identity-resolver.js

@@ -0,0 +1 @@
+export {};

package/lib/identity-resolver/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./atproto-identity-resolver.js";
+export * from "./constants.js";
+export * from "./identity-resolver-error.js";
+export * from "./identity-resolver.js";
+export * from "./util.js";

package/lib/identity-resolver/index.js

@@ -0,0 +1,5 @@
+export * from "./atproto-identity-resolver.js";
+export * from "./constants.js";
+export * from "./identity-resolver-error.js";
+export * from "./identity-resolver.js";
+export * from "./util.js";

package/lib/identity-resolver/util.d.ts

@@ -0,0 +1,12 @@
+import { AtprotoIdentityDidMethods, DidDocument } from "@atproto/did";
+/**
+ * Extract the raw, un-validated, Atproto handle from a DID document.
+ */
+export declare function extractAtprotoHandle(document: DidDocument<AtprotoIdentityDidMethods>): string | undefined;
+/**
+ * Extracts a validated, normalized Atproto handle from a DID document.
+ */
+export declare function extractNormalizedHandle(document: DidDocument<AtprotoIdentityDidMethods>): string | undefined;
+export declare function asNormalizedHandle(input: string): string | undefined;
+export declare function normalizeHandle(handle: string): string;
+export declare function isValidHandle(handle: string): boolean;