npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@atproto-labs/handle-resolver

v0.1.4

Published

Isomorphic ATProto handle to DID resolver

Downloads

3,066

Readme

Universal Handle Resolver implementation for ATPROTO

This package provides a handle resolver implementation for ATPROTO. It is used to resolve handles to their corresponding DID.

This package is meant to be used in any JavaScript environment that support the fetch() function. Because APTORO handle resolution requires DNS resolution, you will need to provide your own DNS resolution function when using this package.

There are two main classes in this package:

  • AtprotoHandleResolver This implements the official ATPROTO handle resolution algorithm (and requires a DNS resolver).
  • AppViewHandleResolver This uses HTTP requests to the Bluesky AppView (bsky.app) to provide handle resolution.

Usage

From a front-end app

Since the ATPROTO handle resolution algorithm requires DNS resolution, and the browser does not provide a built-in DNS resolver, this package offers two options:

  • Delegate handle resolution to an AppView (AppViewHandleResolver). This is the recommended approach for front-end apps.
  • Use a DNS-over-HTTPS (DoH) server (DohHandleResolver). Prefer this method if you don't own an AppView and already have a DoH server that you trust.

Using an AppView:

[!CAUTION] Use the Bluesky owned AppView (https://api.bsky.app/), or PDS (https://bsky.social/), at your own risk. Using these servers in a third-party application might expose your users' data (IP address) to Bluesky. Bluesky might log the data sent to it when your app is resolving handles. Bluesky might also change the API, or terms or use, at any time without notice. Make sure you are compliant with the Bluesky terms of use as well as any laws and regulations that apply to your use case.

import { AppViewHandleResolver } from '@atproto-labs/handle-resolver'

const resolver = new AppViewHandleResolver({
  service: 'https://my-app-view.com/',
})
const did = await resolver.resolve('my-handle.bsky.social')

Using DNS-over-HTTPS (DoH) for DNS resolution:

[!CAUTION] Using a DoH server that you don't own might expose your users' data to the DoH server provider. The DoH server provider might log the data sent to it by your app, allowing them to track which handles are being resolved by your users. In the browser, it is recommended to use a DoH server that you own and control. Or to implement your own AppView and use the AppViewHandleResolver class.

[!NOTE] Using the DohHandleResolver requires a DNS-over-HTTPS server that supports the DNS-over-HTTPS protocol with "application/dns-json" responses.

import { DohHandleResolver } from '@atproto-labs/handle-resolver'

// Also works with 'https://cloudflare-dns.com/dns-query'
const resolver = new DohHandleResolver('https://dns.google/resolve', {
  // Optional: Custom fetch function that will be used both for DNS resolution
  // and well-known resolution.
  fetch: globalThis.fetch.bind(globalThis),
})

const did = await resolver.resolve('my-handle.bsky.social')

From a Node.js app

[!NOTE] On a Node.js backend, you will probably want to use the "@atproto-labs/handle-resolver-node" package. The example below applies to Node.js code running on a user's machine (e.g. through Electron).

import { AtprotoHandleResolver } from '@atproto-labs/handle-resolver'
import { resolveTxt } from 'node:dns/promises'

const resolver = new AtprotoHandleResolver({
  // Optional: Custom fetch function (used for well-known resolution)
  fetch: globalThis.fetch.bind(globalThis),

  resolveTxt: async (domain: string) =>
    resolveTxt(domain).then((chunks) => chunks.join('')),
})

Caching

Using a default, in-memory cache, in which items expire after 10 minutes:

import {
  AppViewHandleResolver,
  CachedHandleResolver,
  HandleResolver,
  HandleCache,
} from '@atproto-labs/handle-resolver'

// See previous examples for creating a resolver
declare const sourceResolver: HandleResolver

const resolver = new CachedHandleResolver(sourceResolver)
const did = await resolver.resolve('my-handle.bsky.social')
const did = await resolver.resolve('my-handle.bsky.social') // Result from cache
const did = await resolver.resolve('my-handle.bsky.social') // Result from cache

Using a custom cache:

import {
  AppViewHandleResolver,
  CachedHandleResolver,
  HandleResolver,
  HandleCache,
} from '@atproto-labs/handle-resolver'

// See previous examples for creating a resolver
declare const sourceResolver: HandleResolver

const cache: HandleCache = {
  set(handle, did): Promise<void> {
    /* TODO */
  },
  get(handle): Promise<undefined | string> {
    /* TODO */
  },
  del(handle): Promise<void> {
    /* TODO */
  },
}

const resolver = new CachedHandleResolver(sourceResolver, cache)
const did = await resolver.resolve('my-handle.bsky.social')
const did = await resolver.resolve('my-handle.bsky.social') // Result from cache
const did = await resolver.resolve('my-handle.bsky.social') // Result from cache