didkit 0.3.3 → 0.5.0

data/lib/didkit/plc_importer.rb

@@ -1,28 +1,29 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
 require 'time'
 require 'uri'
 
+require_relative 'constants'
 require_relative 'errors'
 require_relative 'plc_operation'
 require_relative 'requests'
 
 #
-# NOTE: this class is pending a rewrite once new APIs are deployed to plc.directory.
-# Things will change here in v. 0.4.
+# NOTE: this class is pending a rewrite to handle updated plc.directory APIs.
+# Things will change here in v. 0.6.
 #
 
 module DIDKit
   class PLCImporter
-    PLC_SERVICE = 'plc.directory'
     MAX_PAGE = 1000
 
     include Requests
 
-    attr_accessor :ignore_errors, :last_date, :error_handler
+    attr_accessor :last_date
 
-    def initialize(since: nil)
+    def initialize(since: nil, service: nil)
       if since.to_s == 'beginning'
         @last_date = nil
       elsif since.is_a?(String)
@@ -35,24 +36,13 @@ module DIDKit
       end
 
       @last_page_cids = []
-    end
-
-    def plc_service
-      PLC_SERVICE
-    end
 
-    def ignore_errors=(val)
-      @ignore_errors = val
-
-      if val
-        @error_handler = proc { |e, j| "(ignore error)" }
-      else
-        @error_handler = nil
-      end
+      @plc_service = service || DIDKit::DEFAULT_PLC_DIRECTORY
+      @plc_service = "https://#{@plc_service}" unless @plc_service.include?('://')
     end
 
     def get_export(args = {})
-      url = URI("https://#{plc_service}/export")
+      url = URI("#{@plc_service}/export")
       url.query = URI.encode_www_form(args)
 
       data = get_data(url, content_type: 'application/jsonlines')
@@ -60,23 +50,16 @@ module DIDKit
     end
 
     def fetch_audit_log(did)
-      json = get_json("https://#{plc_service}/#{did}/log/audit", :content_type => :json)
+      json = get_json("#{@plc_service}/#{did}/log/audit", :content_type => :json)
       json.map { |j| PLCOperation.new(j) }
-    end      
+    end
 
     def fetch_page
-      request_time = Time.now
-
       query = @last_date ? { :after => @last_date.utc.iso8601(6) } : {}
       rows = get_export(query)
 
-      operations = rows.filter_map { |json|
-        begin
-          PLCOperation.new(json)
-        rescue FormatError => e
-          @error_handler ? @error_handler.call(e, json) : raise
-          nil
-        end
+      operations = rows.map { |json|
+        PLCOperation.new(json)
       }.reject { |op|
         # when you pass the most recent op's timestamp to ?after, it will be returned as the first op again,
         # so we need to use this CID list to filter it out (so pages will usually be 999 items long)
@@ -84,8 +67,11 @@ module DIDKit
         @last_page_cids.include?(op.cid)
       }
 
-      @last_date = operations.last&.created_at || request_time
-      @last_page_cids = Set.new(operations.map(&:cid))
+      unless operations.empty?
+        @last_date = operations.last.created_at
+        @last_page_cids = Set.new(operations.map(&:cid))
+      end
+
       @eof = (rows.length < MAX_PAGE)
 
       operations

data/lib/didkit/plc_operation.rb

@@ -4,6 +4,7 @@ require 'time'
 
 require_relative 'at_handles'
 require_relative 'errors'
+require_relative 'public_key'
 require_relative 'service_record'
 require_relative 'services'
 
@@ -35,19 +36,10 @@ module DIDKit
     attr_reader :created_at
 
     # Returns the `type` field of the operation (usually `"plc_operation"`).
-    # @return [String] the operation type
+    # @return [Symbol] the operation type
     attr_reader :type
 
-    # Returns a list of handles assigned to the DID in this operation.
-    #
-    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
-    # Use {DID#get_verified_handle} or {Document#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>, nil] service records like PDS details assigned to the DID
     attr_reader :services
 
 
@@ -84,24 +76,97 @@ module DIDKit
       raise FormatError, "Invalid operation type: #{type.inspect}" unless type.is_a?(String)
 
       @type = type.to_sym
-      return unless @type == :plc_operation
 
-      services = operation['services']
-      raise FormatError, "Missing services key: #{json}" if services.nil?
-      raise FormatError, "Invalid services data: #{services.inspect}" unless services.is_a?(Hash)
+      case @type
+      when :plc_operation
+        raise FormatError, "Missing services key: #{json}" if operation['services'].nil?
+
+        parse_services(operation['services'])
+        parse_also_known_as(operation['alsoKnownAs'])
+      when :create
+        parse_legacy_ops(operation)
+      end
+    end
+
+    # @return [Boolean] if the operation has been nullified through a rotation operation
+    def nullified?
+      @json['nullified'] == true
+    end
+
+    # Returns the account's public signing key listed in this PLC operation under `verificationMethods`.
+    #
+    # @return [PublicKey, nil] decoded signing key wrapped in {PublicKey}, or nil for `tombstone` operations
+    # @raise [FormatError] when a required field is missing or has a wrong type
+    # @raise [PublicKeyError] when the key is invalid, incorrectly encoded, or has unsupported type
+
+    def signing_key
+      case @type
+      when :plc_operation
+        methods = @json['operation']['verificationMethods']
+        raise FormatError, "Missing verificationMethods key: #{@json}" if methods.nil?
+        raise FormatError, "Invalid verificationMethods key: #{methods.inspect}" unless methods.is_a?(Hash)
+
+        key = methods['atproto']
+        raise FormatError, "Missing verificationMethods.atproto key: #{@json}" if key.nil?
+        raise FormatError, "Invalid verificationMethods.atproto key: #{key.inspect}" unless key.is_a?(String)
+        raise PublicKeyError, "Key should start with did:key: #{key.inspect}" unless key.start_with?('did:key:')
+
+        PublicKey.new(key[8..-1])
+      when :create
+        key = @json['operation']['signingKey']
+        raise FormatError, "Missing signingKey field: #{@json}" if key.nil?
+        raise FormatError, "Invalid signingKey field: #{key.inspect}" unless key.is_a?(String)
+        raise PublicKeyError, "Key should start with did:key: #{key.inspect}" unless key.start_with?('did:key:')
+
+        PublicKey.new(key[8..-1])
+      else
+        nil
+      end
+    end
 
-      @services = services.map { |k, x|
-        type, endpoint = x.values_at('type', 'endpoint')
+
+    private
+
+    def parse_services(service_data)
+      raise FormatError, "Invalid services data: #{service_data.inspect}" unless service_data.is_a?(Hash)
+
+      @services = []
+
+      service_data.each do |key, data|
+        type, endpoint = data.values_at('type', 'endpoint')
 
         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)
 
-        ServiceRecord.new(k, type, endpoint)
-      }
+        begin
+          @services << ServiceRecord.new(key, type, endpoint)
+        rescue FormatError => e
+          # ignore services with invalid URIs
+        end
+      end
+    end
+
+    def parse_legacy_ops(operation)
+      @handles = []
+      @services = []
+
+      if handle = operation['handle']
+        raise FormatError, "Handle should be a string" unless handle.is_a?(String)
+        @handles << handle
+      end
+
+      if service = operation['service']
+        raise FormatError, "Service should be a string" unless service.is_a?(String)
 
-      @handles = parse_also_known_as(operation['alsoKnownAs'])
+        begin
+          @services << ServiceRecord.new('atproto_pds', 'AtprotoPersonalDataServer', service)
+        rescue FormatError
+          # ignore services with invalid URIs
+        end
+      end
     end
   end
 end

data/lib/didkit/public_key.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'base58'
+require 'openssl'
+require_relative 'errors'
+
+module DIDKit
+
+  #
+  # A public signing key of an ATProto account, decoded from its DID document or PLC operation.
+  #
+  # Both `k256` (`secp256k1`) and `p256` (`secp256r1`, `prime256v1`) keys are supported. Keys from
+  # legacy DID documents (before August 2023) without a `did:key:` prefix are intentionally *not* supported.
+  #
+  # Related documentation:
+  # - [ATProto: Cryptography](https://atproto.com/specs/cryptography)
+  # - [02, 03 or 04? So What Are Compressed and Uncompressed Public Keys?](https://medium.com/asecuritysite-when-bob-met-alice/02-03-or-04-so-what-are-compressed-and-uncompressed-public-keys-6abcb57efeb6)
+  # - [multicodec](https://github.com/multiformats/multicodec) & [multibase](https://github.com/multiformats/multibase)
+  #
+
+  class PublicKey
+
+    # Multicodec varint prefix for a compressed `k256` public key.
+    K256_PREFIX = "\xE7\x01".b.freeze
+
+    # Multicodec varint prefix for a compressed `p256` public key.
+    P256_PREFIX = "\x80\x24".b.freeze
+
+    # OpenSSL group name for the K-256 curve.
+    K256_GROUP_NAME = 'secp256k1'
+
+    # OpenSSL group name for the P-256 curve.
+    P256_GROUP_NAME = 'prime256v1'
+
+    # @return [String] a 33-byte binary string containing the raw compressed public key
+    attr_reader :compressed_key
+
+    # @return [String] the original multikey value, Base58-encoded with a `z` multibase prefix
+    attr_reader :multibase
+
+
+    # Decodes and validates an ATProto account public key.
+    #
+    # @param string [String] key in the multikey string form, without the `did:key:` prefix
+    # @raise [ArgumentError] when the argument is not a string
+    # @raise [PublicKeyError] when the key is invalid, incorrectly encoded, or has unsupported type
+
+    def initialize(string)
+      raise ArgumentError, "Expected a string argument" unless string.is_a?(String)
+
+      # both supported curve prefixes produce 48 Base58 characters, plus the multibase prefix;
+      # skip base58 decoding if the passed data is obviously wrong or too long
+      raise PublicKeyError, "Unsupported key encoding: #{string.inspect}" unless string.start_with?('z')
+      raise PublicKeyError, "Invalid encoded key length (#{string.bytesize})" unless string.bytesize == 49
+
+      @multibase = string
+
+      begin
+        key_decoded = Base58.base58_to_binary(string[1..-1], :bitcoin)
+      rescue ArgumentError
+        raise PublicKeyError, "Invalid Base58 encoding in key data"
+      end
+
+      prefix = key_decoded.byteslice(0, 2)
+
+      case prefix
+      when K256_PREFIX
+        @key_type = :k256
+      when P256_PREFIX
+        @key_type = :p256
+      else
+        raise PublicKeyError, "Unsupported key type: #{string.inspect}"
+      end
+
+      raise PublicKeyError, "Invalid key length (#{key_decoded.bytesize})" unless key_decoded.bytesize == 35
+
+      @compressed_key = key_decoded.byteslice(2, 33)
+
+      validate_ec_point
+    end
+
+    # Returns a short name of the key's elliptic curve.
+    # @return [Symbol] `:k256` or `:p256`
+
+    def type
+      @key_type
+    end
+
+    # Returns the OpenSSL elliptic curve group representing the given key's type.
+    # @return [OpenSSL::PKey::EC::Group] the `secp256k1` or `prime256v1` group
+
+    def ec_group
+      @ec_group ||= OpenSSL::PKey::EC::Group.new(@key_type == :k256 ? K256_GROUP_NAME : P256_GROUP_NAME)
+    end
+
+    # Returns the OpenSSL object representing the key's point on the elliptic curve.
+    #
+    # @return [OpenSSL::PKey::EC::Point] elliptic curve point for the key
+
+    def ec_point
+      @ec_point ||= OpenSSL::PKey::EC::Point.new(ec_group, @compressed_key)
+    end
+
+
+    private
+
+    def validate_ec_point
+      if !ec_point.on_curve?
+        # shouldn't generally happen because OpenSSL rejects such keys in Point initializer
+        raise PublicKeyError, "Invalid key data: #{@multibase.inspect}"
+      end
+    rescue OpenSSL::OpenSSLError
+      raise PublicKeyError, "Invalid key data: #{@multibase.inspect}"
+    end
+  end
+end

data/lib/didkit/requests.rb

@@ -22,7 +22,6 @@ module DIDKit
       timeout = options[:timeout] || 15
 
       request_options = {
-        use_ssl: true,
         open_timeout: timeout,
         read_timeout: timeout
       }
@@ -34,13 +33,18 @@ module DIDKit
       loop do
         visited_urls << url
 
-        response = Net::HTTP.start(url.host, url.port, request_options) do |http|
+        request_options.update(use_ssl: (url.scheme == 'https'))
+
+        response = Net::HTTP.start(url.hostname, url.port, request_options) do |http|
           request = Net::HTTP::Get.new(url)
           http.request(request)
         end
 
         if response.is_a?(Net::HTTPRedirection) && redirects < max_redirects && (location = response['Location'])
-          url = URI(location.include?('://') ? location : (uri_origin(url) + location))
+          target = URI.join(url.to_s, location)
+          return response unless target.scheme == 'https' || (target.scheme == 'http' && url.scheme == 'http')
+
+          url = target
 
           if visited_urls.include?(url)
             return response
@@ -54,6 +58,7 @@ module DIDKit
     end
 
     def get_data(url, options = {})
+      options = options.dup
       content_type = options.delete(:content_type)
       response = get_response(url, options)
 
@@ -84,13 +89,5 @@ module DIDKit
         raise ArgumentError, "Invalid expected_type: #{expected_type.inspect}"
       end
     end
-
-    # backported from https://github.com/ruby/uri/pull/30/files for older Rubies
-    def uri_origin(uri)
-      uri = uri.is_a?(URI) ? uri : URI(uri)
-      authority = (uri.port == uri.default_port) ? uri.host : "#{uri.host}:#{uri.port}"
-
-      "#{uri.scheme}://#{authority}"
-    end
   end
 end

data/lib/didkit/resolver.rb

@@ -1,36 +1,50 @@
 # frozen_string_literal: true
 
+require 'ipaddr'
 require 'net/http'
 require 'resolv'
+require 'uri'
 
+require_relative 'constants'
 require_relative 'did'
 require_relative 'document'
 require_relative 'requests'
 
 module DIDKit
 
+  class << self
+    # Default shared resolver used when calling {DID}/{Document} methods directly.
+    # @return [DIDKit::Resolver]
+    def default_resolver
+      @default_resolver ||= Resolver.new
+    end
+
+    attr_writer :default_resolver
+  end
+
+
   #
   # A class which manages resolving of handles to DIDs and DIDs to DID documents.
   #
 
   class Resolver
-    # These TLDs are not allowed in ATProto handles, so the resolver returns nil for them
-    # without trying to look them up.
-    RESERVED_DOMAINS = %w(alt arpa example internal invalid local localhost onion test)
-
     include Requests
 
-    # @return [String, Array<String>] custom DNS nameserver(s) to use for DNS TXT lookups
-    attr_accessor :nameserver
+    # @return [String, Array<String>, nil] custom DNS nameserver(s) to use for DNS TXT lookups
+    attr_reader :nameserver
 
     # @param options [Hash] resolver options
     # @option options [String, Array<String>] :nameserver custom DNS nameserver(s) to use (IP or an array of IPs)
+    # @option options [String] :plc_directory URL or host[:port] of an alternate PLC directory,
+    #   without a path; defaults to HTTPS (HTTP allowed for localhost/loopback IPs only)
     # @option options [Integer] :timeout request timeout in seconds (default: 15)
     # @option options [Integer] :max_redirects maximum number of redirects to follow (default: 5)
-
+    # @raise [ArgumentError] if the PLC directory address is invalid
+    #
     def initialize(options = {})
       @nameserver = options[:nameserver]
-      @request_options = options.slice(:timeout, :max_redirects)
+      @plc_service = options.key?(:plc_directory) ? parse_plc_service(options[:plc_directory]) : DEFAULT_PLC_DIRECTORY
+      @request_options = options.slice(:timeout, :max_redirects).freeze
     end
 
     # Resolve a handle into a DID. Looks up the given ATProto domain handle using the DNS TXT method
@@ -41,46 +55,56 @@ 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 resolve_handle(handle)
-      if handle.is_a?(DID) || handle =~ DID::GENERIC_REGEXP
-        return DID.new(handle)
+    def resolve_handle(handle, verify: true)
+      if !(handle.is_a?(DID) || handle.is_a?(String))
+        raise ArgumentError, "handle argument should be a String or a DID object"
       end
 
-      domain = handle.gsub(/^@/, '')
+      if handle.is_a?(DID) || handle =~ DIDKit::GENERIC_DID_REGEXP
+        return DID.new(handle)
+      end
 
-      return nil if RESERVED_DOMAINS.include?(domain.split('.').last)
+      domain = handle.gsub(/^@/, '').downcase(:ascii)
+      return nil unless valid_handle_identifier?(domain)
 
       if dns_did = resolve_handle_by_dns(domain)
-        DID.new(dns_did, :dns)
+        referenced_did = DID.new(dns_did, :dns)
       elsif http_did = resolve_handle_by_well_known(domain)
-        DID.new(http_did, :http)
+        referenced_did = DID.new(http_did, :http)
       else
-        nil
+        return nil
+      end
+
+      if verify
+        document = self.resolve_did(referenced_did)
+        return nil unless document.handles.first&.downcase == domain
       end
+
+      referenced_did
     end
 
     # Tries to resolve a handle into DID using the DNS TXT method.
     #
     # Checks the DNS records for a given domain for an entry `_atproto.#{domain}` whose value is
-    # a correct DID string.
+    # a correct DID string. Records are rejected if there exists more than one valid entry and they
+    # are referencing two or more different DIDs.
     #
     # @param domain [String] a domain handle to look up
-    # @return [String, nil] resolved DID if found, nil otherwise
+    # @return [String, nil] resolved DID if one valid record is found, nil otherwise
 
     def resolve_handle_by_dns(domain)
       dns_records = Resolv::DNS.open(resolv_options) do |d|
         d.getresources("_atproto.#{domain}", Resolv::DNS::Resource::IN::TXT)
       end
 
-      if record = dns_records.first
-        if string = record.strings.first
-          return parse_did_from_dns(string)
-        end
-      end
+      dids = dns_records.map { |record| parse_did_from_dns(record.data) }.compact.uniq
 
-      nil
+      dids.length == 1 ? dids.first : nil
     end
 
     # Tries to resolve a handle into DID using the HTTP .well-known method.
@@ -100,14 +124,15 @@ module DIDKit
       end
 
       nil
-    rescue StandardError => e
+    rescue StandardError
       nil
     end
 
     # Resolve a DID to a DID document.
     #
     # Looks up the DID document with the DID's identity details from an appropriate source, i.e. either
-    # [plc.directory](https://plc.directory) for did:plc DIDs, or the did:web's domain for did:web DIDs.
+    # [plc.directory](https://plc.directory) or its mirror for did:plc DIDs, or the did:web's domain
+    # for did:web DIDs.
     #
     # @param did [String, DID] DID string or object
     # @return [Document] resolved DID document
@@ -119,11 +144,11 @@ module DIDKit
       did.type == :plc ? resolve_did_plc(did) : resolve_did_web(did)
     end
 
-    # Returns the first verified handle assigned to the given DID.
+    # Returns the current primary handle assigned to the given DID, if it verifies correctly.
     #
-    # Looks up the domain handles assigned to the 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.
     #
     # @param subject [String, DID, Document] a DID or its DID document
     # @return [String, nil] verified handle domain, if found
@@ -131,44 +156,87 @@ module DIDKit
     def get_verified_handle(subject)
       document = subject.is_a?(Document) ? subject : resolve_did(subject)
 
-      first_verified_handle(document.did, document.handles)
-    end
+      primary_handle = document.handles.first
 
-    # Returns the first handle from the list that resolves back to the given DID.
-    #
-    # @param did [DID, String] DID to verify the handles against
-    # @param handles [Array<String>] handles to check
-    # @return [String, nil] a verified handle, if found
+      return nil if primary_handle.nil?
+      return nil unless resolve_handle(primary_handle, verify: false) == document.did.to_s
 
-    def first_verified_handle(did, handles)
-      handles.detect { |h| resolve_handle(h) == did.to_s }
+      primary_handle
     end
 
 
     private
 
+    def valid_handle_identifier?(handle)
+      return false unless handle =~ DIDKit::HANDLE_REGEXP && handle.length <= DIDKit::MAX_HANDLE_LENGTH
+      return false if DIDKit::RESERVED_DOMAINS.include?(handle.split('.').last)
+
+      true
+    end
+
     def resolv_options
       options = Resolv::DNS::Config.default_config_hash.dup
       options[:nameserver] = nameserver if nameserver
       options
     end
 
+    def parse_plc_service(url)
+      raise ArgumentError, 'PLC directory URL must be a string' unless url.is_a?(String)
+
+      url = "https://#{url}" unless url.include?('://')
+      uri = URI.parse(url.chomp('/'))
+
+      unless uri.is_a?(URI::HTTP) && uri.host && !uri.host.empty? && uri.path.empty?
+        raise ArgumentError, 'PLC directory must be a hostname or a HTTP(S) URL without a path'
+      end
+
+      unless !uri.userinfo && !uri.query && !uri.fragment
+        raise ArgumentError, 'PLC directory URL must not include user credentials, query, or fragment part'
+      end
+
+      if uri.scheme == 'http' && !loopback_host?(uri.hostname)
+        raise ArgumentError, 'http:// URLs are allowed only with localhost or a loopback IP'
+      end
+
+      uri.to_s
+    rescue URI::InvalidURIError
+      raise ArgumentError, 'Invalid PLC directory URL'
+    end
+
+    def loopback_host?(host)
+      host.downcase(:ascii) == 'localhost' || IPAddr.new(host).loopback?
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    def valid_did?(did)
+      DID.new(did)
+      true
+    rescue DIDError
+      false
+    end
+
     def parse_did_from_dns(txt)
-      txt =~ /\Adid\=(did\:\w+\:.*)\z/ ? $1 : nil
+      return nil unless txt.start_with?('did=')
+
+      did = txt.delete_prefix('did=')
+
+      valid_did?(did) ? did : nil
     end
 
     def parse_did_from_well_known(text)
       text = text.strip
-      text.lines.length == 1 && text =~ DID::GENERIC_REGEXP ? text : nil
+      text.lines.length == 1 && valid_did?(text) ? text : nil
     end
 
     def resolve_did_plc(did)
-      json = get_json("https://plc.directory/#{did}", content_type: /^application\/did\+ld\+json(;.+)?$/)
+      options = @request_options.merge(content_type: /^application\/did(\+ld)?\+json(;.+)?$/)
+      json = get_json("#{@plc_service}/#{did}", options)
       Document.new(did, json)
     end
 
     def resolve_did_web(did)
-      json = get_json("https://#{did.web_domain}/.well-known/did.json")
+      json = get_json("#{did.did_web_host}/.well-known/did.json", @request_options)
       Document.new(did, json)
     end
   end