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
2
3
A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol
4
5
6
## What does it do
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.
11
12
13
## Installation
···
15
gem install didkit
16
17
18
## Credits
19
20
-
Copyright © 2023 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
21
22
The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).
···
1
+
# DIDKit
2
3
A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol
4
5
6
## What does it do
7
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.
9
10
11
## Installation
···
13
gem install didkit
14
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
+
80
## Credits
81
82
+
Copyright © 2024 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
83
84
The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).