Skip to content

Commit

Permalink
added more info in readme
Browse files Browse the repository at this point in the history
  • Loading branch information
mackuba committed Mar 12, 2024
1 parent a3411ad commit affd0f0
Showing 1 changed file with 49 additions and 4 deletions.
53 changes: 49 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,63 @@ A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Pro

## What does it do

**TODO** - not much yet :)

See the [did.rb](https://github.com/mackuba/didkit/blob/master/lib/didkit/did.rb) file for now.
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.


## Installation

gem install didkit


## Usage

Use the `DIDKit::Resolver` class to look up DIDs and handles.

To look up a handle:

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

This returns an object of `DIDKit::DID` class (aliased as just `DID`), which tells you:

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

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)

```
> resolver.get_validated_handle('did:plc:ewvi7nxzyoun6zhxrhs64oiz')
=> "atproto.com"
```

You can also load the DID document using `resolve_did` (or `DID#get_document`):

```
> doc = resolver.resolve_did('did:plc:ragtjsm2j2vknwkz3zp4oxrd')
=> #<DIDKit::Document:0x0000000105d751f8 @did=#<DIDKit::DID:...>, @json={...}>
> doc.handles
=> ["pfrazee.com"]
> doc.pds_endpoint
=> "https://morel.us-east.host.bsky.network"
```


### Configuration

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:

```
resolver.nameserver = '8.8.8.8'
```


## Credits

Copyright © 2023 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
Copyright © 2024 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).

The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).

0 comments on commit affd0f0

Please sign in to comment.