mackuba.eu
A library for handling DID identifiers used in Bluesky AT Protocol
added more info in readme
+67
-5
README.md
+67
-5
README.md
···
1
-
# DidKit
1
+
# DIDKit
2
2
3
3
A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol
4
4
5
5
6
6
## What does it do
7
7
8
-
**TODO** - not much yet :)
9
-
10
-
See the [did.rb](https://github.com/mackuba/didkit/blob/master/lib/didkit/did.rb) file for now.
8
+
Accounts on Bluesky use identifiers like [did:plc:oio4hkxaop4ao4wz2pp3f4cr](https://plc.directory/did:plc:oio4hkxaop4ao4wz2pp3f4cr) as unique IDs, and they also have assigned human-readable handles like [@mackuba.eu](https://bsky.app/profile/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.
11
9
12
10
13
11
## Installation
···
15
13
gem install didkit
16
14
17
15
16
+
## Usage
17
+
18
+
Use the `DIDKit::Resolver` class to look up DIDs and handles.
19
+
20
+
To look up a handle:
21
+
22
+
```rb
23
+
resolver = DIDKit::Resolver.new
24
+
resolver.resolve_handle('nytimes.com')
25
+
# => #<DIDKit::DID:0x00000001035956b0 @did="did:plc:eclio37ymobqex2ncko63h4r", @type=:plc, @resolved_by=:dns>
26
+
```
27
+
28
+
This returns an object of `DIDKit::DID` class (aliased as just `DID`), which tells you:
29
+
30
+
- the DID as a string (`#to_s` or `#did`)
31
+
- the DID type (`#type`, `:plc` or `:web`)
32
+
- if the handle was resolved via a DNS entry or a `.well-known` file (`#resolved_by`, `:dns` or `:http`)
33
+
34
+
To go in the other direction – to find an assigned and verified handle given a DID – use `get_validated_handle` (pass DID as a string or an object):
35
+
36
+
```rb
37
+
resolver.get_validated_handle('did:plc:ewvi7nxzyoun6zhxrhs64oiz')
38
+
# => "atproto.com"
39
+
```
40
+
41
+
You can also load the DID document using `resolve_did`:
42
+
43
+
```rb
44
+
doc = resolver.resolve_did('did:plc:ragtjsm2j2vknwkz3zp4oxrd')
45
+
# => #<DIDKit::Document:0x0000000105d751f8 @did=#<DIDKit::DID:...>, @json={...}>
46
+
47
+
doc.handles
48
+
# => ["pfrazee.com"]
49
+
50
+
doc.pds_endpoint
51
+
# => "https://morel.us-east.host.bsky.network"
52
+
```
53
+
54
+
There are also some helper methods in the `DID` class that create a `Resolver` for you to save you some typing:
55
+
56
+
```rb
57
+
did = DID.resolve_handle('jay.bsky.team')
58
+
# => #<DIDKit::DID:0x000000010615ed28 @did="did:plc:oky5czdrnfjpqslsw2a5iclo", @type=:plc, @resolved_by=:dns>
59
+
60
+
did.to_s
61
+
# => "did:plc:oky5czdrnfjpqslsw2a5iclo"
62
+
63
+
did.get_document
64
+
# => #<DIDKit::Document:0x00000001066d4898 @did=#<DIDKit::DID:...>, @json={...}>
65
+
66
+
did.get_validated_handle
67
+
# => "jay.bsky.team"
68
+
```
69
+
70
+
71
+
### Configuration
72
+
73
+
You can override the nameserver used for DNS lookups by setting the `nameserver` property in `Resolver`, e.g. to use Google's or CloudFlare's global DNS:
74
+
75
+
```
76
+
resolver.nameserver = '8.8.8.8'
77
+
```
78
+
79
+
18
80
## Credits
19
81
20
-
Copyright © 2023 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
82
+
Copyright © 2024 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
21
83
22
84
The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).