DIDKit 🪪

A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol.

Note

Part of ATProto Ruby SDK: ruby.sdk.blue

What does it do

Accounts on Bluesky use identifiers like did:plc:oio4hkxaop4ao4wz2pp3f4cr as unique IDs, and they also have assigned human-readable handles like @mackuba.eu, which are verified either through a DNS TXT entry or a /.well-known/atproto-did file. This library allows you to look up any account's assigned handle using a DID string or vice versa, load the account's DID JSON document that specifies the handles and the PDS server hosting user's repo, and check if the assigned handle verifies correctly.

Installation

From the command line:

gem install didkit

Or, add this to your Gemfile:

gem 'didkit', '~> 0.3'

Usage

The simplest way to use the gem is through the DIDKit::DID class, aliased as just DID:

did = DID.resolve_handle('jay.bsky.team')
  # => #<DIDKit::DID:0x0... @did="did:plc:oky5czdrnfjpqslsw2a5iclo",
  #       @resolved_by=:dns, @type=:plc>

This returns a DID object, which tells you:

• the DID as a string (#to_s or #did)
• the DID type (#type, :plc or :web)
• if the handle was resolved via a DNS entry or a .well-known file (#resolved_by, :dns or :http)

To go in the other direction – to find an assigned and verified handle given a DID – create a DID from a DID string and call get_verified_handle:

DID.new('did:plc:ewvi7nxzyoun6zhxrhs64oiz').get_verified_handle
  # => "atproto.com"

You can also load the DID JSON document using #document, which returns a DIDKit::Document (DID caches the document, so don't worry about calling this method multiple times):

did = DID.new('did:plc:ragtjsm2j2vknwkz3zp4oxrd')

did.document.handles
  # => ["pfrazee.com"]

did.document.pds_host
  # => "morel.us-east.host.bsky.network"

Checking account status

DIDKit::DID also includes a few methods for checking the status of a given account (repo), which call the com.atproto.sync.getRepoStatus endpoint on the account's assigned PDS:

did = DID.new('did:plc:ch7azdejgddtlijyzurfdihn')
did.account_status
  # => :takendown
did.account_active?
  # => false
did.account_exists?
  # => true

did = DID.new('did:plc:44ybard66vv44zksje25o7dz')
did.account_status
  # => :active
did.account_active?
  # => true

Configuration

You can customize some things about the DID/handle lookups by using the DIDKit::Resolver class, which the methods in DID use behind the scenes.

Currently available options include:

• :nameserver - override the nameserver used for DNS lookups, e.g. to use Google's or CloudFlare's DNS
• :timeout - change the connection/response timeout for HTTP requests (default: 15 s)
• :max_redirects - change allowed maximum number of redirects (default: 5)

Example:

resolver = DIDKit::Resolver.new(nameserver: '8.8.8.8', timeout: 30)

did = resolver.resolve_handle('nytimes.com')
  # => #<DIDKit::DID:0x0... @did="did:plc:eclio37ymobqex2ncko63h4r",
  #       @resolved_by=:dns, @type=:plc>

resolver.resolve_did(did)
  # => #<DIDKit::Document:0x0... @did=#<DIDKit::DID:...>, @json={...}>

resolver.get_verified_handle(did)
  # => 'nytimes.com'

Credits

Copyright © 2025 Kuba Suder (@mackuba.eu).

The code is available under the terms of the zlib license (permissive, similar to MIT).