didkit 0.3.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fae54f7c1e125655363ac9b8585f5622b87afb371b170fbe8d4d6d25091fd38
-  data.tar.gz: 9de4a4d69ef03399b9bed045b1647226fc92c547b3f017bb4127fa2cb674f9d5
+  metadata.gz: cf656ddc5c0b21d616657dc8f7d310c1f5aba7b77828542a1871c05d177ecbc0
+  data.tar.gz: b23f42ec6c434fa1ba7867976310fac7cfa006c0d093ef105141c0cd5c8b8543
 SHA512:
-  metadata.gz: a52a90e39e7fea15530a9a4e53e006fdbfde90cf919cad0f46552e3740e7a881ace83d1eaba8ca09ffd13fc57f60c20b018ce5779b4b8adf1d8a478d68fc58cf
-  data.tar.gz: fbfb3f01d8b56bc6dfe2f975995c6dc4da75901c43d177e85d0834b920b55036c53ccfc59f1b16e2f4f8f9e0c30b21f719fbecd2a1d28d893556a81f137f52f6
+  metadata.gz: c0227bd5bad67bba3086ac4cc3f766d8976cfd0f4d6a882039676b9792a9c1bcb8a9dd69015918b7c5100613d0689a3460fa0350a25c0ab63a1c54b7e3df7c22
+  data.tar.gz: '017428fc8d8cae144b57029f1547615788ab9fb097ab45403803e94e61954c72511cdf68412c053da40437ba6bdd0f3be86990146dcd142389167ebd4febd84e'

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [0.5.0] - 2026-10-26
+
+Breaking changes:
+
+- the [ATProto DID spec](https://atproto.com/specs/did#did-documents) now says that if there are multiple handles in a document, only the first one should be checked bi-directionally and the rest should be skipped:
+
+    > The first syntactically valid handle found in the ordered list is treated as the claimed handle, even if it fails to resolve bi-directionally. Any other handle URIs should be ignored.
+
+    - the `get_verified_handle` algorithm has been updated to match this behavior
+    - `Resolver#first_verified_handle` method has been removed
+- `DIDKit::PLCImporter::PLC_SERVICE` was moved to `DIDKit::DEFAULT_PLC_DIRECTORY`
+- `DIDKit::DID::GENERIC_REGEXP` was moved to `DIDKit::GENERIC_DID_REGEXP`
+- `DIDKit::Resolver#nameserver` has been changed to be read-only
+- `DIDKit::Resolver#resolve_handle` and `DID.resolve_handle` now verify the resolve handle bi-directionally, checking also if the matched DID has that handle assigned too; pass `verify: false` to skip this (default is true). This call can now raise an error if the DID document cannot be fetched.
+
+Added:
+
+- added support for decoding public (signing) keys – `Document#signing_key`, `PLCOperation#signing_key` and `DIDKit::PublicKey` class
+- `DIDKit::Resolver` now accepts a `:plc_directory` option that lets you use a PLC mirror server instead of `https://plc.directory`
+- added a shared global `DIDKit.default_resolver`, used internally by `DID` & `Document` – you can reassign it to one configured with a custom DNS nameserver or PLC mirror
+- added support for PLC servers returning `application/did+json` content type instead of `application/did+ld+json` (the spec allows it and the replica server implementation does that)
+- added support for PLC servers returning services with IDs in the absolute format `did:...#id` instead of just `#id`
+- added `DID#did_web_host`, which returns the did:web host URL together with `http(s)://` and a port if included (only for `localhost`), and raises a `DIDError` if the DID is not a did:web; `#web_domain` renamed to `#did_web_domain` and kept with the old behavior, `#web_domain` added as an alias
+
+Other:
+
+- more detailed validation of DID & handle strings and for service endpoint URLs
+- fixed DNS-based handle verification if there are multiple text chunks in a TXT record or multiple TXT records
+- make sure that handle verification is case-insensitive
+- the global `DID` alias is not reassigned if something else already defines it before DIDKit is loaded
+- fixed redirects to relative URLs, and disallowed redirects to non-HTTP URLs and from HTTPS to HTTP
+- fixed `:max_redirects` & `:timeout` options not being used when loading a DID document
+
+## [0.4.0] - 2026-07-02
+
+- added `#also_known_as` separate from `#handles` in `Document` and `PLCOperation`, which stores the original array of strings as listed in the JSON, not filtered and not stripped of the `at://` prefix
+- added `PLCOperation#nullified?`
+- added support for parsing `handle` and `service` fields from legacy (2022-23 era) `:create` PLC ops in `PLCOperation`
+- `PLCImporter` can be configured with a custom hostname of a PLC mirror to use instead of [plc.directory](https://plc.directory)
+- `PLCImporter` will no longer update cursor to local request time if an empty page is received, but will instead leave the cursor as is – local time might have some offset vs. server time if the clock isn't set right, and this could lead to skipped operations
+- in `DID#account_status` / `account_active?` / `account_exists?`, accept `getRepoStatus` endpoint returning responses with status 404 instead of 400 (since some PDS implementations do it this way)
+- tweaked parsing of services in `Document` and `PLCOperation`:
+  1. `Document` raises format errors if the fields are missing or not of expected type (since this shouldn't happen)
+  2. `Document` & `PLCOperation` silently ignore the service if its endpoint is not a valid URI (since this does happen)
+  3. Removed `ignore_errors` / `error_handler` from `PLCImporter`, since because of 2) no expected errors are emitted outside `PLCOperation`
+
 ## [0.3.3] - 2026-02-22
 
 - fixed old `FormatError` classes mentioned in `PLCImporter`
@@ -38,8 +84,6 @@ Also:
 - `PLCImporter` now removes duplicate operations at the edge of pages returned from the `/export` API
 - rewritten some networking code – all classes now use `Net::HTTP` with consistent options instead of `open-uri`
 
-Note: `PLCImporter` will be rewritten soon to add support for updated [plc.directory](https://plc.directory) APIs, so be prepared for some breaking changes there in v. 0.4.
-
 ## [0.2.3] - 2024-07-02
 
 - added a `DID#get_audit_log` method that fetches the PLC audit log for a DID

data/README.md

@@ -1,5 +1,7 @@
 # DIDKit 🪪
 
+[![Gem Version](https://badge.fury.io/rb/didkit.svg?icon=si%3Arubygems&icon_color=%23ff6251)](https://rubygems.org/gems/didkit) [![YARD Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/didkit)
+
 A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol.
 
 > [!NOTE]
@@ -13,7 +15,7 @@ Accounts on Bluesky use identifiers like [did:plc:oio4hkxaop4ao4wz2pp3f4cr](http
 
 ## Installation
 
-To use DIDKit, you need a reasonably new version of Ruby – it should run on Ruby 2.6 and above, although it's recommended to use a version that's still getting maintainance updates, i.e. currently 3.2+. A compatible version should be preinstalled on macOS Big Sur and above and on many Linux systems. Otherwise, you can install one using tools such as [RVM](https://rvm.io), [asdf](https://asdf-vm.com), [ruby-install](https://github.com/postmodern/ruby-install) or [ruby-build](https://github.com/rbenv/ruby-build), or `rpm` or `apt-get` on Linux (see more installation options on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/)).
+To use DIDKit, you need a reasonably new version of Ruby – it should run on Ruby 2.6 and above, although it's recommended to use a version that's still getting maintainance updates, i.e. currently 3.3+. A compatible version should be preinstalled on macOS Big Sur and above and on many Linux systems. Otherwise, you can install one using tools such as [RVM](https://rvm.io), [asdf](https://asdf-vm.com), [ruby-install](https://github.com/postmodern/ruby-install) or [ruby-build](https://github.com/rbenv/ruby-build), or `rpm` or `apt-get` on Linux (see more installation options on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/)).
 
 To install the gem, run in the command line:
 
@@ -21,7 +23,7 @@ To install the gem, run in the command line:
 
 Or add this to your app's `Gemfile`:
 
-    gem 'didkit', '~> 0.3'
+    gem 'didkit', '~> 0.5'
 
 
 ## Usage
@@ -40,6 +42,8 @@ This returns a `DID` object, which tells you:
 - 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`)
 
+The handle is automatically verified bi-directionally, i.e. the resolver loads the DID document for e.g. `did:plc:oky5czdrnfjpqslsw2a5iclo` and checks if the handle `jay.bsky.team` is listed there under `alsoKnownAs`. If you want to skip that second check, pass `verify: false` to `#resolve_handle`.
+
 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`:
 
 ```rb
@@ -86,9 +90,10 @@ You can customize some things about the DID/handle lookups by using the `DIDKit:
 
 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)
+- `:nameserver` – override the nameserver used for DNS lookups, e.g. to use Google's or CloudFlare's DNS
+- `:plc_directory` – hostname or URL of a PLC directory mirror to use instead of `plc.directory`
+- `:timeout` – change the connection/response timeout for HTTP requests (default: 15 s)
+- `:max_redirects` – change allowed maximum number of redirects (default: 5)
 
 Example:
 
@@ -106,6 +111,31 @@ resolver.get_verified_handle(did)
   # => 'nytimes.com'
 ```
 
+`DID` and `Document` use a shared global resolver instance at `DIDKit.default_resolver`, which you can overwrite with one using a custom config:
+
+```rb
+DIDKit.default_resolver = DIDKit::Resolver.new(plc_directory: 'plc.eurosky.network')
+
+did = DID.resolve_handle('mackuba.eu')
+puts did.document.pds_host
+# uses plc.eurosky.network to look up DID info
+```
+
+More info in the [YARD API docs](https://rubydoc.info/gems/didkit).
+
+
+### Global DID alias
+
+As mentioned earlier, DIDKit defines a global alias `DID` as a shorthand for `DIDKit::DID`. If this happens to conflict with another constant defined by your app or a different dependency, make sure to `require 'didkit'` *after* that constant is already defined, or alternatively, require e.g. `'didkit/did'` directly, which skips the `global_did.rb` file which defines the global `DID`.
+
+
+## Other resources
+
+- [YARD API documentation](https://rubydoc.info/gems/didkit) at rubydoc.info
+- [ruby.sdk.blue](https://ruby.sdk.blue)
+- [Example scripts](https://ruby.sdk.blue/examples/)
+
+
 ## Credits
 
 Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).

data/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## How To Report a Vulnerability
+
+If you find a potential vulnerability in one of my projects, it's recommended not to report it through a standard publicly-readable issue report, in order to avoid giving possible clues to any potential attackers who could abuse it before it's fixed (see: ["Just a rumour of a bug is enough to find a security exploit these days"](https://anil.recoil.org/notes/rumour-is-the-exploit)).
+
+You can use one of these to contact me instead:
+
+- [@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr) on Bluesky (my DMs should be open, or mention me discretely with a request for contact)
+- [@mackuba@martianbase.net](https://martianbase.net/@mackuba) on Mastodon (my personal instance)
+- email: mackuba `@` protonmail.ch (optionally with [this PGP key](https://mail-api.proton.me/pks/lookup?op=get&search=mackuba@protonmail.ch))
+- ["Report a vulnerability"](https://github.com/mackuba/didkit/security/advisories/new) form on GitHub
+
+I do not check my Twitter/X or LinkedIn accounts regularly.
+
+Note: please don't submit AI-reported issues that have not been verified manually :)

data/lib/didkit/at_handles.rb

@@ -1,22 +1,54 @@
 # frozen_string_literal: true
 
+require_relative 'constants'
 require_relative 'errors'
 
 module DIDKit
 
   #
-  # @private
+  # @api private
   #
 
   module AtHandles
 
+    # Returns a list of ATProto handles assigned to this DID in its DID document.
+    #
+    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
+    # Use {DID#get_verified_handle} to get a handle that is correctly verified.
+    #
+    # According to the current [ATProto DID spec](https://atproto.com/specs/did#did-documents),
+    # if a DID has more than one handle assigned, only the first one on the list should be
+    # considered and the rest should be ignored.
+    #
+    # @api public
+    # @return [Array<String>]
+
+    attr_reader :handles
+
+    # Returns a list of all identifiers assigned to this DID in its DID document through the
+    # `alsoKnownAs` field. This includes ATProto handles (in the format `at://example.com`) and
+    # potentially other URIs like `http` URLs (e.g. for Bridgy accounts), and even (technically
+    # invalid) non-URI strings. Use {#handles} to get just the ATProto handles.
+    #
+    # @api public
+    # @return [Array<String>]
+
+    attr_reader :also_known_as
+
     private
 
     def parse_also_known_as(aka)
       raise FormatError, "Invalid alsoKnownAs: #{aka.inspect}" unless aka.is_a?(Array)
       raise FormatError, "Invalid alsoKnownAs: #{aka.inspect}" unless aka.all? { |x| x.is_a?(String) }
 
-      aka.select { |x| x =~ %r(\Aat://[^/]+\z) }.map { |x| x.gsub('at://', '') }
+      @also_known_as = aka
+      @handles = extract_handles_from_aka(aka)
+    end
+
+    def extract_handles_from_aka(aka)
+      handles = aka.select { |x| x.start_with?('at://') }.map { |x| x.delete_prefix('at://') }
+
+      handles.select { |h| h =~ DIDKit::HANDLE_REGEXP && h.length <= DIDKit::MAX_HANDLE_LENGTH }
     end
   end
 end

data/lib/didkit/constants.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DIDKit
+  # URL of the standard PLC directory service.
+  DEFAULT_PLC_DIRECTORY = 'https://plc.directory'
+
+  DOMAIN_SEGMENT =      /[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?/
+  LAST_DOMAIN_SEGMENT =    /[a-zA-Z]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?/
+  private_constant :DOMAIN_SEGMENT, :LAST_DOMAIN_SEGMENT
+
+  # Pattern that matches any valid ATProto handle (without @)
+  HANDLE_REGEXP = /\A(#{DOMAIN_SEGMENT}\.)+#{LAST_DOMAIN_SEGMENT}\z/
+
+  # Pattern that matches any valid did:plc DID
+  DID_PLC_REGEXP = /\Adid\:plc\:[abcdefghijklmnopqrstuvwxyz234567]{24}\z/
+
+  # Pattern that matches a percent-decoded did:web DID
+  DID_WEB_REGEXP = /\Adid\:web\:((#{DOMAIN_SEGMENT}\.)+#{LAST_DOMAIN_SEGMENT}|localhost(:[1-9][0-9]{0,4})?)\z/
+
+  # Pattern that matches any valid DID (including methods unsupported in ATProto)
+  GENERIC_DID_REGEXP = /\Adid:[a-z]+:[a-zA-Z0-9_\.\:\%\-]*[a-zA-Z0-9_\.\-]\z/
+
+  # Maximum allowed DID length in ATProto
+  MAX_DID_LENGTH = 2048
+
+  # Maximum allowed handle length in ATProto
+  MAX_HANDLE_LENGTH = 253
+
+  # TLDs that are not allowed in ATProto handles
+  RESERVED_DOMAINS = %w(alt arpa example internal invalid local localhost onion test)
+end

data/lib/didkit/did.rb

@@ -3,7 +3,9 @@
 require 'json'
 require 'uri'
 
+require_relative 'constants'
 require_relative 'errors'
+require_relative 'plc_importer'
 require_relative 'requests'
 require_relative 'resolver'
 
@@ -19,8 +21,6 @@ module DIDKit
   #
 
   class DID
-    GENERIC_REGEXP = /\Adid\:\w+\:.+\z/
-
     include Requests
 
     # Resolve a handle into a DID. Looks up the given ATProto domain handle using the DNS TXT method
@@ -31,10 +31,13 @@ module DIDKit
     # check which one it is.
     #
     # @param handle [String, DID] a domain handle (may start with an `@`) or a DID string
+    # @param verify [Boolean] require the handle to be assigned to the DID in the DID document (default: true)
     # @return [DID, nil] resolved DID if found, nil otherwise
+    # @raise [APIError] if verification is enabled and the DID document request is unsuccessful
+    # @raise [FormatError] if verification is enabled and the DID document has invalid data
 
-    def self.resolve_handle(handle)
-      Resolver.new.resolve_handle(handle)
+    def self.resolve_handle(handle, verify: true)
+      DIDKit.default_resolver.resolve_handle(handle, verify: verify)
     end
 
     # @return [Symbol] DID type (`:plc` or `:web`)
@@ -60,14 +63,18 @@ module DIDKit
         did = did.to_s
       end
 
-      if did =~ GENERIC_REGEXP
-        @did = did
-        @type = did.split(':')[1].to_sym
-      else
-        raise DIDError.new("Invalid DID format")
-      end
+      raise ArgumentError.new("did should be a String or a DID object") unless did.is_a?(String)
+      raise DIDError.new("Invalid DID format") unless did =~ DIDKit::GENERIC_DID_REGEXP
+      raise DIDError.new("DID string too long") if did.length > DIDKit::MAX_DID_LENGTH
+
+      @did = did
+      @type = did.split(':')[1].to_sym
 
-      if @type != :plc && @type != :web
+      if @type == :plc
+        validate_did_plc(did)
+      elsif @type == :web
+        validate_did_web(did)
+      else
         raise DIDError.new("Unrecognized DID type: #{@type}")
       end
 
@@ -87,19 +94,19 @@ module DIDKit
     # @return [Document] resolved DID document
 
     def get_document
-      Resolver.new.resolve_did(self)
+      DIDKit.default_resolver.resolve_did(self)
     end
 
-    # Returns the first verified handle assigned to this DID.
+    # Returns the current primary handle assigned to the DID, if it verifies correctly.
     #
-    # Looks up the domain handles assigned to this DID in its DID document, checks if they are
-    # verified (i.e. assigned correctly to this DID using DNS TXT or .well-known) and returns
-    # the first handle that validates correctly, or nil if none matches.
+    # Looks up the first syntactically valid handle in the DID document and checks if it is assigned
+    # correctly to this DID using DNS TXT or .well-known. Any later handles are ignored, even if the
+    # first handle fails verification. Returns nil if the primary handle cannot be verified.
     #
     # @return [String, nil] verified handle domain, if found
 
     def get_verified_handle
-      Resolver.new.get_verified_handle(document)
+      DIDKit.default_resolver.get_verified_handle(document)
     end
 
     # Fetches the PLC audit log (list of all previous operations) for a did:plc DID.
@@ -115,12 +122,31 @@ module DIDKit
       end
     end
 
-    # Returns the domain portion of a did:web identifier.
+    # Returns the domain portion of a did:web identifier. If the DID uses `localhost` with port as the hostname,
+    # the port part is skipped.
     #
     # @return [String, nil] DID domain if the DID is a did:web, nil for did:plc
 
-    def web_domain
-      did.gsub(/^did\:web\:/, '') if type == :web
+    def did_web_domain
+      return nil unless type == :web
+
+      @did_web_host.gsub(/:.*/, '')
+    end
+
+    alias web_domain did_web_domain
+
+    # Returns the URL of the host that hosts a did:web identity, including the http/https scheme
+    # and the port if included.
+    #
+    # @return [String] root URL of the host referenced by the did:web domain
+    # @raise [DIDError] when the DID is not a did:web
+
+    def did_web_host
+      raise DIDError, "DID is not a did:web" unless type == :web
+
+      protocol = (@did_web_host =~ /^localhost(\:.*|$)/) ? 'http' : 'https'
+
+      "#{protocol}://#{@did_web_host}"
     end
 
     # Checks the status of the account/repo on its own PDS using the `getRepoStatus` endpoint.
@@ -136,8 +162,7 @@ module DIDKit
       doc = self.document
       return nil if doc.pds_endpoint.nil?
 
-      pds_host = uri_origin(doc.pds_endpoint)
-      url = URI("#{pds_host}/xrpc/com.atproto.sync.getRepoStatus")
+      url = URI.join(doc.pds_endpoint, "/xrpc/com.atproto.sync.getRepoStatus")
       url.query = URI.encode_www_form(:did => @did)
 
       response = get_response(url, request_options)
@@ -148,17 +173,19 @@ module DIDKit
         json = JSON.parse(response.body)
 
         if json['active'] == true
-          :active
+          return :active
         elsif json['active'] == false && json['status'].is_a?(String) && json['status'].length <= 100
-          json['status'].to_sym
-        else
-          raise APIError.new(response)
+          return json['status'].to_sym
+        end
+      elsif (status == 400 || status == 404) && is_json
+        json = JSON.parse(response.body)
+
+        if json['error'] == 'RepoNotFound'
+          return nil
         end
-      elsif status == 400 && is_json && JSON.parse(response.body)['error'] == 'RepoNotFound'
-        nil
-      else
-        raise APIError.new(response)
       end
+
+      raise APIError.new(response)
     end
 
     # Checks if the account is seen as active on its own PDS, using the `getRepoStatus` endpoint.
@@ -195,5 +222,34 @@ module DIDKit
         false
       end
     end
+
+
+    private
+
+    def validate_did_plc(did)
+      raise DIDError.new("Invalid did:plc") unless did =~ DIDKit::DID_PLC_REGEXP
+    end
+
+    def validate_did_web(did)
+      identifier_part = did.delete_prefix('did:web:')
+
+      # literal colons delimit paths in did:web - a port separator must be percent-encoded
+      raise DIDError.new("Invalid did:web") if identifier_part.include?(':')
+
+      decoded_host = URI::DEFAULT_PARSER.unescape(identifier_part).b
+      raise DIDError.new("Invalid did:web") unless "did:web:#{decoded_host}" =~ DIDKit::DID_WEB_REGEXP
+
+      if decoded_host.include?(':')
+        hostname, port = decoded_host.split(':')
+        raise DIDError.new("Invalid did:web server port") unless port.to_i.between?(1, 65535)
+      else
+        hostname = decoded_host
+      end
+
+      tld = hostname.split('.').last.downcase
+      raise DIDError.new("Invalid did:web TLD: #{tld}") if RESERVED_DOMAINS.include?(tld) && hostname != 'localhost'
+
+      @did_web_host = decoded_host
+    end
   end
 end

data/lib/didkit/document.rb

@@ -2,6 +2,7 @@
 
 require_relative 'at_handles'
 require_relative 'errors'
+require_relative 'public_key'
 require_relative 'resolver'
 require_relative 'service_record'
 require_relative 'services'
@@ -9,30 +10,29 @@ require_relative 'services'
 module DIDKit
 
   #
-  # Parsed DID document from a JSON file loaded from [plc.directory](https://plc.directory) or a did:web domain.
+  # Parsed DID document from a JSON file loaded from the PLC directory ([plc.directory](https://plc.directory)
+  # or a mirror) or from a did:web domain.
   #
   # Use {DID#document} or {Resolver#resolve_did} to fetch a DID document and return this object.
   #
+  # Related specifications:
+  # - [ATProto DID](https://atproto.com/specs/did)
+  #
 
   class Document
     include AtHandles
     include Services
 
+    SERVICE_REGEXP = /\A(did:[^#]+)?#[^#]+\z/
+    private_constant :SERVICE_REGEXP
+
     # @return [Hash] the complete JSON data of the DID document
     attr_reader :json
 
     # @return [DID] the DID that this document describes
     attr_reader :did
 
-    # Returns a list of handles assigned to this DID in its DID document.
-    #
-    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
-    # Use {#get_verified_handle} to find a handle that is correctly verified.
-    #
-    # @return [Array<String>]
-    attr_reader :handles
-
-    # @return [Array<ServiceRecords>] service records like PDS details assigned to the DID
+    # @return [Array<ServiceRecord>] service records like PDS details assigned to the DID
     attr_reader :services
 
     # Creates a DID document object.
@@ -42,6 +42,9 @@ module DIDKit
     # @raise [FormatError] when required fields are missing or invalid.
 
     def initialize(did, json)
+      raise ArgumentError, "did should be a DID object" unless did.is_a?(DID)
+      raise ArgumentError, "json should be a Hash" unless json.is_a?(Hash)
+
       raise FormatError, "Missing id field" if json['id'].nil?
       raise FormatError, "Invalid id field" unless json['id'].is_a?(String)
       raise FormatError, "id field doesn't match expected DID" unless json['id'] == did.to_s
@@ -49,20 +52,46 @@ module DIDKit
       @did = did
       @json = json
 
-      @services = parse_services(json['service'] || [])
-      @handles = parse_also_known_as(json['alsoKnownAs'] || [])
+      parse_services(json['service'] || [])
+      parse_also_known_as(json['alsoKnownAs'] || [])
     end
 
-    # Returns the first verified handle assigned to the DID.
+    # Returns the current primary handle assigned to the DID, if it verifies correctly.
     #
-    # Looks up the domain handles assigned to this DID in the DID document, checks if they are
-    # verified (i.e. assigned correctly to this DID using DNS TXT or .well-known) and returns
-    # the first handle that validates correctly, or nil if none matches.
+    # Looks up the first syntactically valid handle in the DID document and checks if it is assigned
+    # correctly to this DID using DNS TXT or .well-known. Any later handles are ignored, even if the
+    # first handle fails verification. Returns nil if the primary handle cannot be verified.
     #
     # @return [String, nil] verified handle domain, if found
 
     def get_verified_handle
-      Resolver.new.get_verified_handle(self)
+      DIDKit.default_resolver.get_verified_handle(self)
+    end
+
+    # Returns the account's public signing key parsed from the DID document's `verificationMethod`.
+    #
+    # @return [PublicKey, nil] decoded signing key wrapped in {PublicKey}, or nil if no matching verification
+    #   method is found
+    # @raise [FormatError] when `verificationMethod` or one of its entries has an invalid type
+    # @raise [ArgumentError] when selected key data is not a string
+    # @raise [PublicKeyError] when the key is invalid, incorrectly encoded, or has unsupported type
+
+    def signing_key
+      keys = @json['verificationMethod']
+      return nil if keys.nil?
+
+      raise FormatError, "verificationMethod is not an array: #{keys.inspect}" unless keys.is_a?(Array)
+
+      keys.each do |data|
+        raise FormatError, "verificationMethod item is invalid: #{data.inspect}" unless data.is_a?(Hash)
+
+        next unless data['id'] == "#{@did}#atproto" || data['id'] == "#atproto"
+        next unless data['controller'] == @did.to_s && data['type'] == 'Multikey' && !data['publicKeyMultibase'].nil?
+
+        return PublicKey.new(data['publicKeyMultibase'])
+      end
+
+      nil
     end
 
 
@@ -71,17 +100,36 @@ module DIDKit
     def parse_services(service_data)
       raise FormatError, "Invalid service data" unless service_data.is_a?(Array) && service_data.all? { |x| x.is_a?(Hash) }
 
-      services = []
+      @services = []
 
       service_data.each do |x|
         id, type, endpoint = x.values_at('id', 'type', 'serviceEndpoint')
 
-        if id.is_a?(String) && id.start_with?('#') && type.is_a?(String) && endpoint.is_a?(String)
-          services << ServiceRecord.new(id.gsub(/^#/, ''), type, endpoint)
+        raise FormatError, "Missing service id" unless id
+        raise FormatError, "Invalid service id: #{id.inspect}" unless id.is_a?(String)
+        next unless id =~ SERVICE_REGEXP
+
+        if id.start_with?('did:')
+          did, rest = id.split('#')
+          next unless did == @did.to_s
+
+          id = rest
+        else
+          id = id.gsub(/^#/, '')
         end
-      end
 
-      services
+        raise FormatError, "Missing service type" unless type
+        raise FormatError, "Invalid service type: #{type.inspect}" unless type.is_a?(String)
+
+        raise FormatError, "Missing service endpoint" unless endpoint
+        raise FormatError, "Invalid service endpoint: #{endpoint.inspect}" unless endpoint.is_a?(String)
+
+        begin
+          @services << ServiceRecord.new(id, type, endpoint)
+        rescue FormatError => e
+          # ignore services with invalid URIs
+        end
+      end
     end
   end
 end

data/lib/didkit/errors.rb

@@ -38,4 +38,10 @@ module DIDKit
   #
   class FormatError < StandardError
   end
+
+  #
+  # Raised when an account's public key is invalid or unsupported.
+  #
+  class PublicKeyError < StandardError
+  end
 end

data/lib/didkit/global_did.rb

@@ -0,0 +1,5 @@
+require_relative 'did'
+
+unless defined?(::DID)
+  DID = DIDKit::DID
+end