@atproto-labs/handle-resolver 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @atproto-labs/handle-resolver
+
+## 0.0.1
+
+### Patch Changes
+
+- [`e134c79a0`](https://github.com/bluesky-social/atproto/commit/e134c79a0ffb000b2cb36437815673fa6bda664b) Thanks [@devinivy](https://github.com/devinivy)! - Initial publish of experimental oauth packages to @atproto-labs
+
+- Updated dependencies [[`e134c79a0`](https://github.com/bluesky-social/atproto/commit/e134c79a0ffb000b2cb36437815673fa6bda664b)]:
+  - @atproto-labs/caching@0.0.1
+  - @atproto-labs/fetch@0.0.1
+  - @atproto-labs/did@0.0.1

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Dual MIT/Apache-2.0 License
+
+Copyright (c) 2022-2024 Bluesky PBC, and Contributors
+
+Except as otherwise noted in individual files, this software is licensed under the MIT license (<http://opensource.org/licenses/MIT>), or the Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>).
+
+Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

package/dist/atproto-lexicon-handle-resolver.d.ts

@@ -0,0 +1,36 @@
+import { Fetch } from '@atproto-labs/fetch';
+import z from 'zod';
+import { HandleResolveOptions, HandleResolver, ResolvedHandle } from './handle-resolver.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 AtprotoLexiconHandleResolverOptions = {
+    /**
+     * 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?: Fetch;
+    /**
+     * URL of the atproto lexicon server. This is the base URL where the
+     * `com.atproto.identity.resolveHandle` XRPC method is located.
+     *
+     * @default 'https://bsky.social'
+     */
+    url?: URL | string;
+};
+export declare class AtprotoLexiconHandleResolver implements HandleResolver {
+    protected readonly url: URL;
+    protected readonly fetch: Fetch;
+    constructor({ url, fetch, }?: AtprotoLexiconHandleResolverOptions);
+    resolve(handle: string, options?: HandleResolveOptions): Promise<ResolvedHandle>;
+}
+//# sourceMappingURL=atproto-lexicon-handle-resolver.d.ts.map

package/dist/atproto-lexicon-handle-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atproto-lexicon-handle-resolver.d.ts","sourceRoot":"","sources":["../src/atproto-lexicon-handle-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,CAAC,MAAM,KAAK,CAAA;AAEnB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,cAAc,EAEf,MAAM,sBAAsB,CAAA;AAE7B,eAAO,MAAM,eAAe;;;;;;;;;EAG1B,CAAA;AAEF,MAAM,MAAM,mCAAmC,GAAG;IAChD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb;;;;;OAKG;IACH,GAAG,CAAC,EAAE,GAAG,GAAG,MAAM,CAAA;CACnB,CAAA;AAED,qBAAa,4BAA6B,YAAW,cAAc;IACjE,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IAC3B,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;gBAEnB,EACV,GAA4B,EAC5B,KAAwB,GACzB,GAAE,mCAAwC;IAK9B,OAAO,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC;CAuC3B"}

package/dist/atproto-lexicon-handle-resolver.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtprotoLexiconHandleResolver = exports.xrpcErrorSchema = void 0;
+const zod_1 = __importDefault(require("zod"));
+const handle_resolver_js_1 = require("./handle-resolver.js");
+exports.xrpcErrorSchema = zod_1.default.object({
+    error: zod_1.default.string(),
+    message: zod_1.default.string().optional(),
+});
+class AtprotoLexiconHandleResolver {
+    constructor({ url = 'https://bsky.social/', fetch = globalThis.fetch, } = {}) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fetch", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.url = new URL(url);
+        this.fetch = fetch;
+    }
+    async resolve(handle, options) {
+        const url = new URL('/xrpc/com.atproto.identity.resolveHandle', this.url);
+        url.searchParams.set('handle', handle);
+        const headers = new Headers();
+        if (options?.noCache)
+            headers.set('cache-control', 'no-cache');
+        const request = new Request(url, { headers, signal: options?.signal });
+        const response = await this.fetch.call(null, request);
+        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 data = exports.xrpcErrorSchema.parse(payload);
+            if (data.error === 'InvalidRequest' &&
+                data.message === 'Unable to resolve handle') {
+                return null;
+            }
+        }
+        if (!response.ok) {
+            throw new Error('Invalid response from resolveHandle method');
+        }
+        const value = payload?.did;
+        if (!value || !(0, handle_resolver_js_1.isResolvedHandle)(value)) {
+            throw new Error('Invalid DID returned from resolveHandle method');
+        }
+        return value;
+    }
+}
+exports.AtprotoLexiconHandleResolver = AtprotoLexiconHandleResolver;
+//# sourceMappingURL=atproto-lexicon-handle-resolver.js.map

package/dist/atproto-lexicon-handle-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atproto-lexicon-handle-resolver.js","sourceRoot":"","sources":["../src/atproto-lexicon-handle-resolver.ts"],"names":[],"mappings":";;;;;;AACA,8CAAmB;AAEnB,6DAK6B;AAEhB,QAAA,eAAe,GAAG,aAAC,CAAC,MAAM,CAAC;IACtC,KAAK,EAAE,aAAC,CAAC,MAAM,EAAE;IACjB,OAAO,EAAE,aAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAA;AAoBF,MAAa,4BAA4B;IAIvC,YAAY,EACV,GAAG,GAAG,sBAAsB,EAC5B,KAAK,GAAG,UAAU,CAAC,KAAK,MACe,EAAE;QANxB;;;;;WAAQ;QACR;;;;;WAAY;QAM7B,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,KAAK,CAAC,OAAO,CAClB,MAAc,EACd,OAA8B;QAE9B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,0CAA0C,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACzE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QAEtC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;QAC7B,IAAI,OAAO,EAAE,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,CAAA;QAE9D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;QAEtE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACrD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;QAErC,gCAAgC;QAChC,0FAA0F;QAC1F,qDAAqD;QACrD,iFAAiF;QAEjF,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,uBAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;YAC3C,IACE,IAAI,CAAC,KAAK,KAAK,gBAAgB;gBAC/B,IAAI,CAAC,OAAO,KAAK,0BAA0B,EAC3C,CAAC;gBACD,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;QAC/D,CAAC;QAED,MAAM,KAAK,GAAY,OAAO,EAAE,GAAG,CAAA;QAEnC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAA,qCAAgB,EAAC,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;QACnE,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC;CACF;AAtDD,oEAsDC"}

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

@@ -0,0 +1,17 @@
+import { CachedGetter, GenericStore } from '@atproto-labs/caching';
+import { HandleResolveOptions, HandleResolver, ResolvedHandle } from './handle-resolver.js';
+export type CachedHandleResolverOptions = {
+    /**
+     * The resolver that will be used to resolve handles.
+     */
+    resolver: HandleResolver;
+    /**
+     * A store that will be used to cache resolved values.
+     */
+    cache?: GenericStore<string, ResolvedHandle>;
+};
+export declare class CachedHandleResolver extends CachedGetter<string, ResolvedHandle> implements HandleResolver {
+    constructor({ resolver, cache, }: CachedHandleResolverOptions);
+    resolve(handle: string, options?: HandleResolveOptions): Promise<ResolvedHandle>;
+}
+//# sourceMappingURL=cached-handle-resolver.d.ts.map

package/dist/cached-handle-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-handle-resolver.d.ts","sourceRoot":"","sources":["../src/cached-handle-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAe,MAAM,uBAAuB,CAAA;AAC/E,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,cAAc,EACf,MAAM,sBAAsB,CAAA;AAE7B,MAAM,MAAM,2BAA2B,GAAG;IACxC;;OAEG;IACH,QAAQ,EAAE,cAAc,CAAA;IAExB;;OAEG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAC7C,CAAA;AAED,qBAAa,oBACX,SAAQ,YAAY,CAAC,MAAM,EAAE,cAAc,CAC3C,YAAW,cAAc;gBAEb,EACV,QAAQ,EACR,KAGE,GACH,EAAE,2BAA2B;IAIxB,OAAO,CACX,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC;CAG3B"}

package/dist/cached-handle-resolver.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedHandleResolver = void 0;
+const caching_1 = require("@atproto-labs/caching");
+class CachedHandleResolver extends caching_1.CachedGetter {
+    constructor({ resolver, cache = new caching_1.MemoryStore({
+        max: 1000,
+        ttl: 10 * 60e3,
+    }), }) {
+        super((handle, options) => resolver.resolve(handle, options), cache);
+    }
+    async resolve(handle, options) {
+        return this.get(handle, options);
+    }
+}
+exports.CachedHandleResolver = CachedHandleResolver;
+//# sourceMappingURL=cached-handle-resolver.js.map

package/dist/cached-handle-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-handle-resolver.js","sourceRoot":"","sources":["../src/cached-handle-resolver.ts"],"names":[],"mappings":";;;AAAA,mDAA+E;AAmB/E,MAAa,oBACX,SAAQ,sBAAoC;IAG5C,YAAY,EACV,QAAQ,EACR,KAAK,GAAG,IAAI,qBAAW,CAAyB;QAC9C,GAAG,EAAE,IAAI;QACT,GAAG,EAAE,EAAE,GAAG,IAAI;KACf,CAAC,GAC0B;QAC5B,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,CAAA;IACtE,CAAC;IAED,KAAK,CAAC,OAAO,CACX,MAAc,EACd,OAA8B;QAE9B,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,CAAC;CACF;AApBD,oDAoBC"}

package/dist/handle-resolver.d.ts

@@ -0,0 +1,18 @@
+import { Did } from '@atproto-labs/did';
+export type HandleResolveOptions = {
+    signal?: AbortSignal;
+    noCache?: boolean;
+};
+export type ResolvedHandle = null | Did;
+export declare function isResolvedHandle<T = unknown>(value: T): value is T & 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 HandleResolveOptions.signal}).
+     */
+    resolve(handle: string, options?: HandleResolveOptions): Promise<ResolvedHandle>;
+}
+//# sourceMappingURL=handle-resolver.d.ts.map

package/dist/handle-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-resolver.d.ts","sourceRoot":"","sources":["../src/handle-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAS,MAAM,mBAAmB,CAAA;AAE9C,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AACD,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,GAAG,CAAA;AAEvC,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,KAAK,EAAE,CAAC,GACP,KAAK,IAAI,CAAC,GAAG,cAAc,CAE7B;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAAA;CAC3B"}

package/dist/handle-resolver.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isResolvedHandle = void 0;
+const did_1 = require("@atproto-labs/did");
+function isResolvedHandle(value) {
+    return value === null || (typeof value === 'string' && (0, did_1.isDid)(value));
+}
+exports.isResolvedHandle = isResolvedHandle;
+//# sourceMappingURL=handle-resolver.js.map

package/dist/handle-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-resolver.js","sourceRoot":"","sources":["../src/handle-resolver.ts"],"names":[],"mappings":";;;AAAA,2CAA8C;AAQ9C,SAAgB,gBAAgB,CAC9B,KAAQ;IAER,OAAO,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAA,WAAK,EAAC,KAAK,CAAC,CAAC,CAAA;AACtE,CAAC;AAJD,4CAIC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './handle-resolver.js';
+export * from './universal-handle-resolver.js';
+export { UniversalHandleResolver as default } from './universal-handle-resolver.js';
+export * from './cached-handle-resolver.js';
+export * from './atproto-lexicon-handle-resolver.js';
+export * from './serial-handle-resolver.js';
+export * from './well-known-handler-resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA;AAGpC,cAAc,gCAAgC,CAAA;AAC9C,OAAO,EAAE,uBAAuB,IAAI,OAAO,EAAE,MAAM,gCAAgC,CAAA;AAGnF,cAAc,6BAA6B,CAAA;AAC3C,cAAc,sCAAsC,CAAA;AACpD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,kCAAkC,CAAA"}

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+__exportStar(require("./handle-resolver.js"), exports);
+// Main export
+__exportStar(require("./universal-handle-resolver.js"), exports);
+var universal_handle_resolver_js_1 = require("./universal-handle-resolver.js");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return universal_handle_resolver_js_1.UniversalHandleResolver; } });
+// Utilities
+__exportStar(require("./cached-handle-resolver.js"), exports);
+__exportStar(require("./atproto-lexicon-handle-resolver.js"), exports);
+__exportStar(require("./serial-handle-resolver.js"), exports);
+__exportStar(require("./well-known-handler-resolver.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uDAAoC;AAEpC,cAAc;AACd,iEAA8C;AAC9C,+EAAmF;AAA1E,uHAAA,uBAAuB,OAAW;AAE3C,YAAY;AACZ,8DAA2C;AAC3C,uEAAoD;AACpD,8DAA2C;AAC3C,mEAAgD"}

package/dist/serial-handle-resolver.d.ts

@@ -0,0 +1,7 @@
+import { HandleResolveOptions, HandleResolver, ResolvedHandle } from './handle-resolver.js';
+export declare class SerialHandleResolver implements HandleResolver {
+    protected readonly resolvers: readonly HandleResolver[];
+    constructor(resolvers: readonly HandleResolver[]);
+    resolve(handle: string, options?: HandleResolveOptions): Promise<ResolvedHandle>;
+}
+//# sourceMappingURL=serial-handle-resolver.d.ts.map

package/dist/serial-handle-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-handle-resolver.d.ts","sourceRoot":"","sources":["../src/serial-handle-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,cAAc,EACf,MAAM,sBAAsB,CAAA;AAE7B,qBAAa,oBAAqB,YAAW,cAAc;IAC7C,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE;gBAApC,SAAS,EAAE,SAAS,cAAc,EAAE;IAMtD,OAAO,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC;CAY3B"}

package/dist/serial-handle-resolver.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SerialHandleResolver = void 0;
+class SerialHandleResolver {
+    constructor(resolvers) {
+        Object.defineProperty(this, "resolvers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: resolvers
+        });
+        if (!resolvers.length) {
+            throw new TypeError('At least one resolver is required');
+        }
+    }
+    async resolve(handle, options) {
+        for (const resolver of this.resolvers) {
+            options?.signal?.throwIfAborted();
+            const value = await resolver.resolve(handle, options);
+            if (value)
+                return value;
+        }
+        // If no resolver was able to resolve the handle, assume there is no DID
+        // corresponding to the handle.
+        return null;
+    }
+}
+exports.SerialHandleResolver = SerialHandleResolver;
+//# sourceMappingURL=serial-handle-resolver.js.map

package/dist/serial-handle-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-handle-resolver.js","sourceRoot":"","sources":["../src/serial-handle-resolver.ts"],"names":[],"mappings":";;;AAMA,MAAa,oBAAoB;IAC/B,YAA+B,SAAoC;QAAvD;;;;mBAAmB,SAAS;WAA2B;QACjE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YACtB,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAA;QAC1D,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,OAAO,CAClB,MAAc,EACd,OAA8B;QAE9B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;YAEjC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;YACrD,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAA;QACzB,CAAC;QAED,wEAAwE;QACxE,+BAA+B;QAC/B,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAtBD,oDAsBC"}

package/dist/universal-handle-resolver.d.ts

@@ -0,0 +1,32 @@
+import { GenericStore } from '@atproto-labs/caching';
+import { Fetch } from '@atproto-labs/fetch';
+import { CachedHandleResolver } from './cached-handle-resolver.js';
+import { HandleResolver, ResolvedHandle } from './handle-resolver.js';
+import { AtprotoLexiconHandleResolverOptions } from './atproto-lexicon-handle-resolver.js';
+export type HandleResolverCache = GenericStore<string, ResolvedHandle>;
+export type UniversalHandleResolverOptions = {
+    cache?: HandleResolverCache;
+    /**
+     * Fetch function to use for HTTP requests. Allows customizing the request
+     * behavior, e.g. adding headers, setting a timeout, mocking, etc.
+     *
+     * When using this library from a Node.js environment, you may want to use
+     * `safeFetchWrap()` from `@atproto-labs/fetch-node` to add SSRF protection.
+     *
+     * @default `globalThis.fetch`
+     */
+    fetch?: Fetch;
+    /**
+     * @see {@link AtprotoLexiconHandleResolverOptions.url}
+     */
+    atprotoLexiconUrl?: AtprotoLexiconHandleResolverOptions['url'];
+};
+/**
+ * A handle resolver that works in any environment that supports `fetch()`. This
+ * relies on the a public XRPC implementing "com.atproto.identity.resolveHandle"
+ * to resolve handles.
+ */
+export declare class UniversalHandleResolver extends CachedHandleResolver implements HandleResolver {
+    constructor({ fetch, cache, atprotoLexiconUrl, }?: UniversalHandleResolverOptions);
+}
+//# sourceMappingURL=universal-handle-resolver.d.ts.map

package/dist/universal-handle-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"universal-handle-resolver.d.ts","sourceRoot":"","sources":["../src/universal-handle-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrE,OAAO,EAEL,mCAAmC,EACpC,MAAM,sCAAsC,CAAA;AAI7C,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;AAEtE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,KAAK,CAAC,EAAE,mBAAmB,CAAA;IAE3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb;;OAEG;IACH,iBAAiB,CAAC,EAAE,mCAAmC,CAAC,KAAK,CAAC,CAAA;CAC/D,CAAA;AAED;;;;GAIG;AACH,qBAAa,uBACX,SAAQ,oBACR,YAAW,cAAc;gBAEb,EACV,KAAwB,EACxB,KAAK,EACL,iBAAiB,GAClB,GAAE,8BAAmC;CAUvC"}

package/dist/universal-handle-resolver.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniversalHandleResolver = void 0;
+const cached_handle_resolver_js_1 = require("./cached-handle-resolver.js");
+const atproto_lexicon_handle_resolver_js_1 = require("./atproto-lexicon-handle-resolver.js");
+const serial_handle_resolver_js_1 = require("./serial-handle-resolver.js");
+const well_known_handler_resolver_js_1 = require("./well-known-handler-resolver.js");
+/**
+ * A handle resolver that works in any environment that supports `fetch()`. This
+ * relies on the a public XRPC implementing "com.atproto.identity.resolveHandle"
+ * to resolve handles.
+ */
+class UniversalHandleResolver extends cached_handle_resolver_js_1.CachedHandleResolver {
+    constructor({ fetch = globalThis.fetch, cache, atprotoLexiconUrl, } = {}) {
+        const resolver = new serial_handle_resolver_js_1.SerialHandleResolver([
+            // Try the well-known method first, allowing to reduce the load on the
+            // XRPC.
+            new well_known_handler_resolver_js_1.WellKnownHandleResolver({ fetch }),
+            new atproto_lexicon_handle_resolver_js_1.AtprotoLexiconHandleResolver({ fetch, url: atprotoLexiconUrl }),
+        ]);
+        super({ resolver, cache });
+    }
+}
+exports.UniversalHandleResolver = UniversalHandleResolver;
+//# sourceMappingURL=universal-handle-resolver.js.map

package/dist/universal-handle-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"universal-handle-resolver.js","sourceRoot":"","sources":["../src/universal-handle-resolver.ts"],"names":[],"mappings":";;;AAGA,2EAAkE;AAElE,6FAG6C;AAC7C,2EAAkE;AAClE,qFAA0E;AAwB1E;;;;GAIG;AACH,MAAa,uBACX,SAAQ,gDAAoB;IAG5B,YAAY,EACV,KAAK,GAAG,UAAU,CAAC,KAAK,EACxB,KAAK,EACL,iBAAiB,MACiB,EAAE;QACpC,MAAM,QAAQ,GAAG,IAAI,gDAAoB,CAAC;YACxC,sEAAsE;YACtE,QAAQ;YACR,IAAI,wDAAuB,CAAC,EAAE,KAAK,EAAE,CAAC;YACtC,IAAI,iEAA4B,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,iBAAiB,EAAE,CAAC;SACpE,CAAC,CAAA;QAEF,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5B,CAAC;CACF;AAlBD,0DAkBC"}

package/dist/well-known-handler-resolver.d.ts

@@ -0,0 +1,11 @@
+import { Fetch } from '@atproto-labs/fetch';
+import { HandleResolveOptions, HandleResolver, ResolvedHandle } from './handle-resolver.js';
+export type WellKnownHandleResolverOptions = {
+    fetch?: Fetch;
+};
+export declare class WellKnownHandleResolver implements HandleResolver {
+    protected readonly fetch: Fetch;
+    constructor({ fetch, }?: WellKnownHandleResolverOptions);
+    resolve(handle: string, options?: HandleResolveOptions): Promise<ResolvedHandle>;
+}
+//# sourceMappingURL=well-known-handler-resolver.d.ts.map

package/dist/well-known-handler-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known-handler-resolver.d.ts","sourceRoot":"","sources":["../src/well-known-handler-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE3C,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,cAAc,EAEf,MAAM,sBAAsB,CAAA;AAE7B,MAAM,MAAM,8BAA8B,GAAG;IAC3C,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAED,qBAAa,uBAAwB,YAAW,cAAc;IAC5D,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;gBAEnB,EACV,KAAwB,GACzB,GAAE,8BAAmC;IAIzB,OAAO,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC;CAyB3B"}

package/dist/well-known-handler-resolver.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WellKnownHandleResolver = void 0;
+const handle_resolver_js_1 = require("./handle-resolver.js");
+class WellKnownHandleResolver {
+    constructor({ fetch = globalThis.fetch, } = {}) {
+        Object.defineProperty(this, "fetch", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.fetch = fetch;
+    }
+    async resolve(handle, options) {
+        const url = new URL('/.well-known/atproto-did', `https://${handle}`);
+        const headers = new Headers();
+        if (options?.noCache)
+            headers.set('cache-control', 'no-cache');
+        const request = new Request(url, { headers, signal: options?.signal });
+        try {
+            const response = await (0, this.fetch)(request);
+            const text = await response.text();
+            const firstLine = text.split('\n')[0].trim();
+            if ((0, handle_resolver_js_1.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();
+            // TODO: propagate some errors as-is (?)
+            return null;
+        }
+    }
+}
+exports.WellKnownHandleResolver = WellKnownHandleResolver;
+//# sourceMappingURL=well-known-handler-resolver.js.map

package/dist/well-known-handler-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known-handler-resolver.js","sourceRoot":"","sources":["../src/well-known-handler-resolver.ts"],"names":[],"mappings":";;;AAEA,6DAK6B;AAM7B,MAAa,uBAAuB;IAGlC,YAAY,EACV,KAAK,GAAG,UAAU,CAAC,KAAK,MACU,EAAE;QAJnB;;;;;WAAY;QAK7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,KAAK,CAAC,OAAO,CAClB,MAAc,EACd,OAA8B;QAE9B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,0BAA0B,EAAE,WAAW,MAAM,EAAE,CAAC,CAAA;QAEpE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;QAC7B,IAAI,OAAO,EAAE,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,CAAA;QAC9D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;QAEtE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAA;YAC/C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;YAClC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAA;YAE7C,IAAI,IAAA,qCAAgB,EAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAA;YAEjD,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,uEAAuE;YACvE,0DAA0D;YAC1D,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;YAEjC,wCAAwC;YAExC,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;CACF;AArCD,0DAqCC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@atproto-labs/handle-resolver",
+  "version": "0.0.1",
+  "license": "MIT",
+  "description": "Isomorphic ATProto handle to DID resolver",
+  "keywords": [
+    "atproto",
+    "oauth",
+    "handle",
+    "identity",
+    "browser",
+    "node",
+    "isomorphic"
+  ],
+  "homepage": "https://atproto.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto",
+    "directory": "packages/handle-resolver"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "lru-cache": "^10.2.0",
+    "zod": "^3.22.4",
+    "@atproto-labs/caching": "0.0.1",
+    "@atproto-labs/did": "0.0.1",
+    "@atproto-labs/fetch": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json"
+  }
+}

package/src/atproto-lexicon-handle-resolver.ts

@@ -0,0 +1,88 @@
+import { Fetch } from '@atproto-labs/fetch'
+import z from 'zod'
+
+import {
+  HandleResolveOptions,
+  HandleResolver,
+  ResolvedHandle,
+  isResolvedHandle,
+} from './handle-resolver.js'
+
+export const xrpcErrorSchema = z.object({
+  error: z.string(),
+  message: z.string().optional(),
+})
+
+export type AtprotoLexiconHandleResolverOptions = {
+  /**
+   * 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?: Fetch
+
+  /**
+   * URL of the atproto lexicon server. This is the base URL where the
+   * `com.atproto.identity.resolveHandle` XRPC method is located.
+   *
+   * @default 'https://bsky.social'
+   */
+  url?: URL | string
+}
+
+export class AtprotoLexiconHandleResolver implements HandleResolver {
+  protected readonly url: URL
+  protected readonly fetch: Fetch
+
+  constructor({
+    url = 'https://bsky.social/',
+    fetch = globalThis.fetch,
+  }: AtprotoLexiconHandleResolverOptions = {}) {
+    this.url = new URL(url)
+    this.fetch = fetch
+  }
+
+  public async resolve(
+    handle: string,
+    options?: HandleResolveOptions,
+  ): Promise<ResolvedHandle> {
+    const url = new URL('/xrpc/com.atproto.identity.resolveHandle', this.url)
+    url.searchParams.set('handle', handle)
+
+    const headers = new Headers()
+    if (options?.noCache) headers.set('cache-control', 'no-cache')
+
+    const request = new Request(url, { headers, signal: options?.signal })
+
+    const response = await this.fetch.call(null, request)
+    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 data = xrpcErrorSchema.parse(payload)
+      if (
+        data.error === 'InvalidRequest' &&
+        data.message === 'Unable to resolve handle'
+      ) {
+        return null
+      }
+    }
+
+    if (!response.ok) {
+      throw new Error('Invalid response from resolveHandle method')
+    }
+
+    const value: unknown = payload?.did
+
+    if (!value || !isResolvedHandle(value)) {
+      throw new Error('Invalid DID returned from resolveHandle method')
+    }
+
+    return value
+  }
+}

package/src/cached-handle-resolver.ts

@@ -0,0 +1,40 @@
+import { CachedGetter, GenericStore, MemoryStore } from '@atproto-labs/caching'
+import {
+  HandleResolveOptions,
+  HandleResolver,
+  ResolvedHandle,
+} from './handle-resolver.js'
+
+export type CachedHandleResolverOptions = {
+  /**
+   * The resolver that will be used to resolve handles.
+   */
+  resolver: HandleResolver
+
+  /**
+   * A store that will be used to cache resolved values.
+   */
+  cache?: GenericStore<string, ResolvedHandle>
+}
+
+export class CachedHandleResolver
+  extends CachedGetter<string, ResolvedHandle>
+  implements HandleResolver
+{
+  constructor({
+    resolver,
+    cache = new MemoryStore<string, ResolvedHandle>({
+      max: 1000,
+      ttl: 10 * 60e3,
+    }),
+  }: CachedHandleResolverOptions) {
+    super((handle, options) => resolver.resolve(handle, options), cache)
+  }
+
+  async resolve(
+    handle: string,
+    options?: HandleResolveOptions,
+  ): Promise<ResolvedHandle> {
+    return this.get(handle, options)
+  }
+}

package/src/handle-resolver.ts

@@ -0,0 +1,27 @@
+import { Did, isDid } from '@atproto-labs/did'
+
+export type HandleResolveOptions = {
+  signal?: AbortSignal
+  noCache?: boolean
+}
+export type ResolvedHandle = null | Did
+
+export function isResolvedHandle<T = unknown>(
+  value: T,
+): value is T & ResolvedHandle {
+  return value === null || (typeof value === 'string' && isDid(value))
+}
+
+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 HandleResolveOptions.signal}).
+   */
+  resolve(
+    handle: string,
+    options?: HandleResolveOptions,
+  ): Promise<ResolvedHandle>
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './handle-resolver.js'
+
+// Main export
+export * from './universal-handle-resolver.js'
+export { UniversalHandleResolver as default } from './universal-handle-resolver.js'
+
+// Utilities
+export * from './cached-handle-resolver.js'
+export * from './atproto-lexicon-handle-resolver.js'
+export * from './serial-handle-resolver.js'
+export * from './well-known-handler-resolver.js'

package/src/serial-handle-resolver.ts

@@ -0,0 +1,29 @@
+import {
+  HandleResolveOptions,
+  HandleResolver,
+  ResolvedHandle,
+} from './handle-resolver.js'
+
+export class SerialHandleResolver implements HandleResolver {
+  constructor(protected readonly resolvers: readonly HandleResolver[]) {
+    if (!resolvers.length) {
+      throw new TypeError('At least one resolver is required')
+    }
+  }
+
+  public async resolve(
+    handle: string,
+    options?: HandleResolveOptions,
+  ): Promise<ResolvedHandle> {
+    for (const resolver of this.resolvers) {
+      options?.signal?.throwIfAborted()
+
+      const value = await resolver.resolve(handle, options)
+      if (value) return value
+    }
+
+    // If no resolver was able to resolve the handle, assume there is no DID
+    // corresponding to the handle.
+    return null
+  }
+}

package/src/universal-handle-resolver.ts

@@ -0,0 +1,58 @@
+import { GenericStore } from '@atproto-labs/caching'
+import { Fetch } from '@atproto-labs/fetch'
+
+import { CachedHandleResolver } from './cached-handle-resolver.js'
+import { HandleResolver, ResolvedHandle } from './handle-resolver.js'
+import {
+  AtprotoLexiconHandleResolver,
+  AtprotoLexiconHandleResolverOptions,
+} from './atproto-lexicon-handle-resolver.js'
+import { SerialHandleResolver } from './serial-handle-resolver.js'
+import { WellKnownHandleResolver } from './well-known-handler-resolver.js'
+
+export type HandleResolverCache = GenericStore<string, ResolvedHandle>
+
+export type UniversalHandleResolverOptions = {
+  cache?: HandleResolverCache
+
+  /**
+   * Fetch function to use for HTTP requests. Allows customizing the request
+   * behavior, e.g. adding headers, setting a timeout, mocking, etc.
+   *
+   * When using this library from a Node.js environment, you may want to use
+   * `safeFetchWrap()` from `@atproto-labs/fetch-node` to add SSRF protection.
+   *
+   * @default `globalThis.fetch`
+   */
+  fetch?: Fetch
+
+  /**
+   * @see {@link AtprotoLexiconHandleResolverOptions.url}
+   */
+  atprotoLexiconUrl?: AtprotoLexiconHandleResolverOptions['url']
+}
+
+/**
+ * A handle resolver that works in any environment that supports `fetch()`. This
+ * relies on the a public XRPC implementing "com.atproto.identity.resolveHandle"
+ * to resolve handles.
+ */
+export class UniversalHandleResolver
+  extends CachedHandleResolver
+  implements HandleResolver
+{
+  constructor({
+    fetch = globalThis.fetch,
+    cache,
+    atprotoLexiconUrl,
+  }: UniversalHandleResolverOptions = {}) {
+    const resolver = new SerialHandleResolver([
+      // Try the well-known method first, allowing to reduce the load on the
+      // XRPC.
+      new WellKnownHandleResolver({ fetch }),
+      new AtprotoLexiconHandleResolver({ fetch, url: atprotoLexiconUrl }),
+    ])
+
+    super({ resolver, cache })
+  }
+}

package/src/well-known-handler-resolver.ts

@@ -0,0 +1,51 @@
+import { Fetch } from '@atproto-labs/fetch'
+
+import {
+  HandleResolveOptions,
+  HandleResolver,
+  ResolvedHandle,
+  isResolvedHandle,
+} from './handle-resolver.js'
+
+export type WellKnownHandleResolverOptions = {
+  fetch?: Fetch
+}
+
+export class WellKnownHandleResolver implements HandleResolver {
+  protected readonly fetch: Fetch
+
+  constructor({
+    fetch = globalThis.fetch,
+  }: WellKnownHandleResolverOptions = {}) {
+    this.fetch = fetch
+  }
+
+  public async resolve(
+    handle: string,
+    options?: HandleResolveOptions,
+  ): Promise<ResolvedHandle> {
+    const url = new URL('/.well-known/atproto-did', `https://${handle}`)
+
+    const headers = new Headers()
+    if (options?.noCache) headers.set('cache-control', 'no-cache')
+    const request = new Request(url, { headers, signal: options?.signal })
+
+    try {
+      const response = await (0, this.fetch)(request)
+      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()
+
+      // TODO: propagate some errors as-is (?)
+
+      return null
+    }
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig/isomorphic.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "include": [],
+  "references": [{ "path": "./tsconfig.build.json" }]
+}