did_resolver 0.1.0

data/lib/did_resolver/methods/key.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require "json"
+
+module DidResolver
+  module Methods
+    # DID Key Method Resolver
+    #
+    # Resolves did:key DIDs according to the DID Key Method Specification
+    # @see https://w3c-ccg.github.io/did-method-key/
+    #
+    # did:key is a self-describing DID that encodes the public key directly
+    # in the DID identifier using multibase + multicodec encoding.
+    #
+    # Supported key types:
+    #   - Ed25519 (multicodec: 0xed)
+    #   - X25519 (multicodec: 0xec)
+    #   - secp256k1 (multicodec: 0xe7)
+    #   - P-256 (multicodec: 0x1200)
+    #   - P-384 (multicodec: 0x1201)
+    #   - P-521 (multicodec: 0x1202)
+    #   - RSA (multicodec: 0x1205)
+    #   - jwk_jcs-pub (multicodec: 0xeb51) - EBSI/JCS encoded JWK
+    #
+    # @example
+    #   resolver = DidResolver::Resolver.new(DidResolver::Methods::Key.resolver)
+    #   result = resolver.resolve("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK")
+    #
+    class Key
+      # Multicodec prefixes for key types
+      # @see https://github.com/multiformats/multicodec/blob/master/table.csv
+      MULTICODEC = {
+        ed25519_pub: 0xed,
+        x25519_pub: 0xec,
+        secp256k1_pub: 0xe7,
+        p256_pub: 0x1200,
+        p384_pub: 0x1201,
+        p521_pub: 0x1202,
+        rsa_pub: 0x1205,
+        jwk_jcs_pub: 0xeb51  # EBSI jwk_jcs-pub codec
+      }.freeze
+
+      # Reverse lookup
+      MULTICODEC_TO_TYPE = MULTICODEC.invert.freeze
+
+      # Key type to verification method type mapping
+      KEY_TYPE_TO_VM_TYPE = {
+        ed25519_pub: "Ed25519VerificationKey2020",
+        x25519_pub: "X25519KeyAgreementKey2020",
+        secp256k1_pub: "EcdsaSecp256k1VerificationKey2019",
+        p256_pub: "JsonWebKey2020",
+        p384_pub: "JsonWebKey2020",
+        p521_pub: "JsonWebKey2020",
+        rsa_pub: "JsonWebKey2020",
+        jwk_jcs_pub: "JsonWebKey2020"
+      }.freeze
+
+      # Key type to JWK curve mapping
+      KEY_TYPE_TO_CURVE = {
+        ed25519_pub: "Ed25519",
+        x25519_pub: "X25519",
+        secp256k1_pub: "secp256k1",
+        p256_pub: "P-256",
+        p384_pub: "P-384",
+        p521_pub: "P-521"
+        # jwk_jcs_pub curve comes from the embedded JWK
+      }.freeze
+
+      class << self
+        # Get the resolver hash for registration
+        # @return [Hash] { "key" => resolve_proc }
+        def resolver
+          { "key" => method(:resolve) }
+        end
+
+        # Resolve a did:key DID
+        # @param did [String] The full DID string
+        # @param parsed [ParsedDID] Parsed DID components
+        # @param _resolver [Resolver] Parent resolver
+        # @param _options [Hash] Resolution options
+        # @return [ResolutionResult]
+        def resolve(did, parsed, _resolver, _options = {})
+          # Extract the method-specific identifier (without fragment)
+          method_specific_id = parsed.id
+
+          # Parse the multibase-encoded key
+          key_data = decode_multibase_key(method_specific_id)
+          return key_data if key_data.is_a?(ResolutionResult) # Error case
+
+          key_type = key_data[:type]
+          public_key_bytes = key_data[:bytes]
+
+          # Build the DID Document based on key type
+          did_document = if key_type == :jwk_jcs_pub
+            build_did_document_from_jwk_jcs(did, method_specific_id, public_key_bytes)
+          else
+            build_did_document(did, key_type, public_key_bytes)
+          end
+
+          return did_document if did_document.is_a?(ResolutionResult) # Error case
+
+          ResolutionResult.success(did_document)
+        rescue StandardError => e
+          ResolutionResult.error("invalidDid", "Failed to resolve did:key: #{e.message}")
+        end
+
+        private
+
+        # Decode a multibase-encoded public key
+        # @param multibase_key [String] The multibase-encoded key (e.g., z6Mk...)
+        # @return [Hash] { type: Symbol, bytes: String }
+        def decode_multibase_key(multibase_key)
+          # Check multibase prefix (z = base58btc)
+          unless multibase_key.start_with?("z")
+            return ResolutionResult.invalid_did(
+              "did:key:#{multibase_key}",
+              "Unsupported multibase encoding. Expected 'z' (base58btc)"
+            )
+          end
+
+          # Decode base58btc (without the 'z' prefix)
+          encoded = multibase_key[1..]
+          decoded = decode_base58(encoded)
+
+          # Extract multicodec prefix
+          multicodec, key_bytes = extract_multicodec(decoded)
+
+          key_type = MULTICODEC_TO_TYPE[multicodec]
+          unless key_type
+            return ResolutionResult.invalid_did(
+              "did:key:#{multibase_key}",
+              "Unsupported key type multicodec: 0x#{multicodec.to_s(16)}"
+            )
+          end
+
+          { type: key_type, bytes: key_bytes }
+        end
+
+        # Extract multicodec prefix from bytes
+        # Multicodec uses unsigned varint encoding (LEB128)
+        # @see https://github.com/multiformats/unsigned-varint
+        def extract_multicodec(bytes)
+          decode_uvarint(bytes)
+        end
+
+        # Decode an unsigned varint (LEB128) from the beginning of bytes
+        # @param bytes [String] Binary string
+        # @return [Array<Integer, String>] [value, remaining_bytes]
+        def decode_uvarint(bytes)
+          result = 0
+          shift = 0
+          offset = 0
+
+          loop do
+            raise "Varint too long" if offset >= 9 # Max 9 bytes for 64-bit
+            raise "Unexpected end of bytes" if offset >= bytes.bytesize
+
+            byte = bytes[offset].ord
+            offset += 1
+
+            # Add the lower 7 bits to result
+            result |= (byte & 0x7f) << shift
+            shift += 7
+
+            # If MSB is 0, we're done
+            break if (byte & 0x80).zero?
+          end
+
+          [result, bytes[offset..]]
+        end
+
+        # Build DID Document for the key
+        def build_did_document(did, key_type, public_key_bytes)
+          vm_type = KEY_TYPE_TO_VM_TYPE[key_type]
+          vm_id = "#{did}##{did.split(':').last}"
+
+          # Build verification method
+          verification_method = {
+            "id" => vm_id,
+            "type" => vm_type,
+            "controller" => did
+          }
+
+          # Add public key in appropriate format
+          case key_type
+          when :ed25519_pub, :x25519_pub
+            # Use multibase encoding for Ed25519/X25519
+            verification_method["publicKeyMultibase"] = "z" + encode_base58(
+              [MULTICODEC[key_type]].pack("C") + public_key_bytes
+            )
+          else
+            # Use JWK for other key types
+            verification_method["publicKeyJwk"] = build_jwk(key_type, public_key_bytes)
+          end
+
+          # Build verification relationships based on key type
+          authentication = []
+          assertion_method = []
+          key_agreement = []
+          capability_invocation = []
+          capability_delegation = []
+
+          case key_type
+          when :ed25519_pub
+            authentication << vm_id
+            assertion_method << vm_id
+            capability_invocation << vm_id
+            capability_delegation << vm_id
+          when :x25519_pub
+            key_agreement << vm_id
+          when :secp256k1_pub, :p256_pub, :p384_pub, :p521_pub
+            authentication << vm_id
+            assertion_method << vm_id
+            capability_invocation << vm_id
+            capability_delegation << vm_id
+          end
+
+          DIDDocument.new(
+            id: did,
+            context: [
+              "https://www.w3.org/ns/did/v1",
+              "https://w3id.org/security/suites/ed25519-2020/v1",
+              "https://w3id.org/security/suites/x25519-2020/v1"
+            ],
+            verification_method: [verification_method],
+            authentication: authentication.any? ? authentication : nil,
+            assertion_method: assertion_method.any? ? assertion_method : nil,
+            key_agreement: key_agreement.any? ? key_agreement : nil,
+            capability_invocation: capability_invocation.any? ? capability_invocation : nil,
+            capability_delegation: capability_delegation.any? ? capability_delegation : nil
+          )
+        end
+
+        # Build DID Document from jwk_jcs-pub encoded JWK
+        # This is the EBSI format where the key bytes are a JSON-encoded JWK
+        # @see https://github.com/multiformats/multicodec/pull/307
+        def build_did_document_from_jwk_jcs(did, method_specific_id, public_key_bytes)
+          # The bytes are UTF-8 encoded JSON of the JWK
+          jwk_json = public_key_bytes.force_encoding("UTF-8")
+
+          begin
+            public_key_jwk = JSON.parse(jwk_json)
+          rescue JSON::ParserError => e
+            return ResolutionResult.error("invalidDid", "Invalid JWK JSON in did:key: #{e.message}")
+          end
+
+          # Validate JWK has required fields
+          unless public_key_jwk["kty"]
+            return ResolutionResult.error("invalidDid", "JWK missing required 'kty' parameter")
+          end
+
+          # Verify the JWK is in canonical form (JCS - lexicographically sorted)
+          canonical_jwk = canonicalize_jwk(public_key_jwk)
+          if JSON.generate(public_key_jwk) != JSON.generate(canonical_jwk)
+            return ResolutionResult.error("invalidDid", "The JWK embedded in the DID is not correctly formatted (must be JCS canonical)")
+          end
+
+          # Build key ID using the method-specific identifier
+          key_id = "#{did}##{method_specific_id}"
+
+          verification_method = {
+            "id" => key_id,
+            "type" => "JsonWebKey2020",
+            "controller" => did,
+            "publicKeyJwk" => public_key_jwk
+          }
+
+          # Build verification relationships
+          # All signing-capable keys get all relationships
+          DIDDocument.new(
+            id: did,
+            context: [
+              "https://www.w3.org/ns/did/v1",
+              "https://w3id.org/security/suites/jws-2020/v1"
+            ],
+            verification_method: [verification_method],
+            authentication: [key_id],
+            assertion_method: [key_id],
+            capability_invocation: [key_id],
+            capability_delegation: [key_id]
+          )
+        end
+
+        # Canonicalize JWK according to JCS (only required members, lexicographically sorted)
+        # @see https://www.rfc-editor.org/rfc/rfc7638 (JWK Thumbprint)
+        def canonicalize_jwk(jwk)
+          case jwk["kty"]
+          when "EC"
+            { "crv" => jwk["crv"], "kty" => jwk["kty"], "x" => jwk["x"], "y" => jwk["y"] }
+          when "OKP"
+            { "crv" => jwk["crv"], "kty" => jwk["kty"], "x" => jwk["x"] }
+          when "RSA"
+            { "e" => jwk["e"], "kty" => jwk["kty"], "n" => jwk["n"] }
+          else
+            jwk
+          end
+        end
+
+        # Build JWK from public key bytes
+        def build_jwk(key_type, public_key_bytes)
+          curve = KEY_TYPE_TO_CURVE[key_type]
+
+          case key_type
+          when :secp256k1_pub, :p256_pub, :p384_pub, :p521_pub
+            # EC key - uncompressed point format (04 || x || y)
+            if public_key_bytes[0] == "\x04"
+              # Uncompressed
+              coord_length = (public_key_bytes.bytesize - 1) / 2
+              x = public_key_bytes[1, coord_length]
+              y = public_key_bytes[1 + coord_length, coord_length]
+            else
+              # Compressed - would need to decompress
+              # For now, just use the raw bytes
+              x = public_key_bytes
+              y = nil
+            end
+
+            jwk = {
+              "kty" => "EC",
+              "crv" => curve,
+              "x" => base64url_encode(x)
+            }
+            jwk["y"] = base64url_encode(y) if y
+            jwk
+          when :rsa_pub
+            # RSA public key (DER encoded)
+            {
+              "kty" => "RSA",
+              "n" => base64url_encode(public_key_bytes),
+              "e" => base64url_encode("\x01\x00\x01") # Common exponent 65537
+            }
+          else
+            # OKP keys (Ed25519, X25519)
+            {
+              "kty" => "OKP",
+              "crv" => curve,
+              "x" => base64url_encode(public_key_bytes)
+            }
+          end
+        end
+
+        # Base58 Bitcoin alphabet
+        BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+        def decode_base58(str)
+          int_val = 0
+          str.each_char do |c|
+            int_val = int_val * 58 + BASE58_ALPHABET.index(c)
+          end
+
+          # Convert to bytes
+          hex = int_val.to_s(16)
+          hex = "0" + hex if hex.length.odd?
+
+          # Handle leading zeros
+          leading_zeros = str.chars.take_while { |c| c == "1" }.count
+          ("\x00" * leading_zeros) + [hex].pack("H*")
+        end
+
+        def encode_base58(bytes)
+          # Count leading zeros
+          leading_zeros = bytes.bytes.take_while(&:zero?).count
+
+          # Convert to integer
+          int_val = bytes.unpack1("H*").to_i(16)
+
+          # Convert to base58
+          result = ""
+          while int_val > 0
+            int_val, remainder = int_val.divmod(58)
+            result = BASE58_ALPHABET[remainder] + result
+          end
+
+          # Add leading 1s for each leading zero byte
+          ("1" * leading_zeros) + result
+        end
+
+        def base64url_encode(bytes)
+          Base64.urlsafe_encode64(bytes, padding: false)
+        end
+      end
+    end
+  end
+end

data/lib/did_resolver/methods/web.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module DidResolver
+  module Methods
+    # DID Web Method Resolver
+    #
+    # Resolves did:web DIDs according to the DID Web Method Specification
+    # @see https://w3c-ccg.github.io/did-method-web/
+    #
+    # DID Web syntax:
+    #   did:web:<domain>                     -> https://<domain>/.well-known/did.json
+    #   did:web:<domain>:<path>              -> https://<domain>/<path>/did.json
+    #   did:web:<domain>%3A<port>            -> https://<domain>:<port>/.well-known/did.json
+    #
+    # @example
+    #   resolver = DidResolver::Resolver.new(DidResolver::Methods::Web.resolver)
+    #   result = resolver.resolve("did:web:example.com")
+    #
+    class Web
+      DEFAULT_TIMEOUT = 10
+
+      class << self
+        # Get the resolver hash for registration
+        # @return [Hash] { "web" => resolve_proc }
+        def resolver
+          { "web" => method(:resolve) }
+        end
+
+        # Resolve a did:web DID
+        # @param did [String] The full DID string
+        # @param parsed [ParsedDID] Parsed DID components
+        # @param _resolver [Resolver] Parent resolver (for recursive resolution)
+        # @param options [Hash] Resolution options
+        # @return [ResolutionResult]
+        def resolve(did, parsed, _resolver, options = {})
+          url = build_url(parsed.id)
+
+          response = fetch_did_document(url, options)
+
+          case response
+          when Net::HTTPSuccess
+            parse_response(did, response.body)
+          when Net::HTTPNotFound
+            ResolutionResult.not_found(did)
+          else
+            ResolutionResult.error("networkError", "HTTP #{response.code}: #{response.message}")
+          end
+        rescue URI::InvalidURIError => e
+          ResolutionResult.invalid_did(did, "Invalid domain in DID: #{e.message}")
+        rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH => e
+          ResolutionResult.error("networkError", "Connection failed: #{e.message}")
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          ResolutionResult.error("networkError", "Request timeout: #{e.message}")
+        rescue JSON::ParserError => e
+          ResolutionResult.error("invalidDidDocument", "Invalid JSON in DID Document: #{e.message}")
+        rescue StandardError => e
+          ResolutionResult.error("internalError", e.message)
+        end
+
+        private
+
+        # Build the HTTPS URL for the DID document
+        # @param method_specific_id [String] The method-specific identifier
+        # @return [String] The URL
+        #
+        # According to did:web spec:
+        # - Colons in the method-specific-id separate path segments
+        # - Percent-encoded colons (%3A) represent literal colons (for port numbers)
+        # - Example: did:web:example.com         -> https://example.com/.well-known/did.json
+        # - Example: did:web:example.com:users   -> https://example.com/users/did.json
+        # - Example: did:web:localhost%3A8080    -> https://localhost:8080/.well-known/did.json
+        #
+        def build_url(method_specific_id)
+          # First, split on unencoded colons to get path parts
+          parts = method_specific_id.split(":")
+
+          # Decode percent-encoded colons in each part (these are literal colons, e.g., port)
+          decoded_parts = parts.map { |p| p.gsub("%3A", ":").gsub("%3a", ":") }
+
+          # First part is the domain (possibly with port from decoded %3A)
+          domain = decoded_parts.first
+
+          # Remaining parts form the path
+          path_parts = decoded_parts[1..]
+
+          if path_parts.empty?
+            # No path -> use .well-known
+            "https://#{domain}/.well-known/did.json"
+          else
+            # Path specified -> use path/did.json
+            path = path_parts.join("/")
+            "https://#{domain}/#{path}/did.json"
+          end
+        end
+
+        # Fetch the DID document from the URL
+        def fetch_did_document(url, options = {})
+          uri = URI.parse(url)
+          timeout = options[:timeout] || DEFAULT_TIMEOUT
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == "https")
+          http.open_timeout = timeout
+          http.read_timeout = timeout
+
+          # Some servers require a proper User-Agent
+          headers = {
+            "Accept" => "application/did+ld+json, application/json",
+            "User-Agent" => "DidResolver/#{VERSION} Ruby/#{RUBY_VERSION}"
+          }
+
+          request = Net::HTTP::Get.new(uri.request_uri, headers)
+          http.request(request)
+        end
+
+        # Parse the response body as a DID Document
+        def parse_response(did, body)
+          data = JSON.parse(body)
+
+          # Validate the document ID matches the DID
+          doc_id = data["id"]
+          unless doc_id == did
+            return ResolutionResult.error(
+              "invalidDidDocument",
+              "DID Document id '#{doc_id}' does not match DID '#{did}'"
+            )
+          end
+
+          did_document = DIDDocument.from_hash(data)
+
+          ResolutionResult.success(
+            did_document,
+            document_metadata: extract_metadata(data)
+          )
+        end
+
+        def extract_metadata(data)
+          metadata = {}
+
+          # Extract common metadata fields if present
+          metadata[:created] = data["created"] if data["created"]
+          metadata[:updated] = data["updated"] if data["updated"]
+          metadata[:deactivated] = data["deactivated"] if data.key?("deactivated")
+
+          metadata
+        end
+      end
+    end
+  end
+end

data/lib/did_resolver/methods.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Load method resolvers
+require_relative "methods/web"
+require_relative "methods/key"
+require_relative "methods/jwk"
+
+module DidResolver
+  # Methods namespace for DID method resolvers
+  module Methods
+  end
+end

data/lib/did_resolver/resolver.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module DidResolver
+  # Universal DID Resolver
+  #
+  # Resolves DIDs by delegating to registered method resolvers.
+  # Inspired by https://github.com/decentralized-identity/did-resolver
+  #
+  # @example
+  #   resolver = Resolver.new(
+  #     DidResolver::Methods::Web.resolver,
+  #     DidResolver::Methods::Key.resolver
+  #   )
+  #   result = resolver.resolve("did:web:example.com")
+  #
+  class Resolver
+    attr_reader :registry
+
+    # @param method_resolvers [Array<Hash>] Method resolver hashes { method_name => resolve_proc }
+    # @param cache [Cache, Boolean, nil] Cache implementation or true for default cache
+    # @param logger [Logger, nil] Optional logger for error messages
+    def initialize(*method_resolvers, cache: nil, logger: nil)
+      @registry = {}
+      @cache = build_cache(cache)
+      @logger = logger
+
+      # Register all provided method resolvers
+      method_resolvers.flatten.each do |resolver_hash|
+        register(resolver_hash)
+      end
+    end
+
+    # Register a method resolver
+    # @param resolver_hash [Hash] { method_name => resolve_proc }
+    def register(resolver_hash)
+      resolver_hash.each do |method_name, resolve_proc|
+        @registry[method_name.to_s] = resolve_proc
+      end
+    end
+
+    # Resolve a DID to its DID Document
+    # @param did [String] The DID or DID URL to resolve
+    # @param options [Hash] Resolution options
+    # @option options [Boolean] :no_cache Skip cache lookup
+    # @return [ResolutionResult]
+    def resolve(did, **options)
+      # Parse the DID
+      parsed = ParsedDID.parse(did)
+
+      # Check cache first (unless no_cache is set)
+      if @cache && !options[:no_cache] && !parsed.params["no-cache"]
+        cached = @cache.get(parsed.did)
+        return cached if cached
+      end
+
+      # Find method resolver
+      method_resolver = @registry[parsed.method]
+      unless method_resolver
+        return ResolutionResult.method_not_supported(parsed.method)
+      end
+
+      # Resolve
+      result = method_resolver.call(parsed.did, parsed, self, options)
+
+      # Cache successful results
+      if @cache && !result.error? && result.did_document
+        @cache.set(parsed.did, result)
+      end
+
+      result
+    rescue InvalidDIDError => e
+      ResolutionResult.invalid_did(did, e.message)
+    rescue NotFoundError => e
+      ResolutionResult.not_found(did)
+    rescue NetworkError => e
+      ResolutionResult.error("networkError", e.message)
+    rescue StandardError => e
+      @logger&.error("[DID Resolver] Unexpected error: #{e.message}")
+      ResolutionResult.error("internalError", e.message)
+    end
+
+    # Check if a method is supported
+    # @param method [String] DID method name
+    # @return [Boolean]
+    def supports?(method)
+      @registry.key?(method.to_s)
+    end
+
+    # List supported methods
+    # @return [Array<String>]
+    def supported_methods
+      @registry.keys
+    end
+
+    private
+
+    def build_cache(cache_option)
+      case cache_option
+      when true
+        Cache.new
+      when Cache
+        cache_option
+      when nil, false
+        nil
+      else
+        # Assume it's a custom cache implementation with get/set methods
+        cache_option
+      end
+    end
+
+    class << self
+      # Default resolver with common methods registered
+      # @return [Resolver]
+      def default
+        @default ||= new(
+          Methods::Web.resolver,
+          Methods::Key.resolver,
+          Methods::Jwk.resolver,
+          cache: true
+        )
+      end
+
+      # Reset the default resolver (useful for testing)
+      def reset_default!
+        @default = nil
+      end
+
+      # Shortcut to resolve using default resolver
+      def resolve(did, **options)
+        default.resolve(did, **options)
+      end
+    end
+  end
+end

data/lib/did_resolver/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DidResolver
+  VERSION = "0.1.0"
+end