triauth 0.0.1 → 1.0.0.beta.4

data/lib/triauth/verifiers/base.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 The Triauth Authors (https://www.triauth.org/)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+require 'openssl'
+
+module Triauth
+  module Verifiers
+    # The base abstract class from which all Verifiers inherit common functions.
+    class Base
+      # Constructs a verifier for a public key as it is published in an identity record.
+      #
+      # This is the abstract contract that concrete verifiers (e.g., Ecdsa, Ed25519, WebAuthn) implement.
+      #
+      # @param raw_public_key [String] The publishable key material, as read from the identity record.
+      # @param options [Hash] Key options as read from the DNS record that carried the key (e.g., `use`, `uv`). Defaults to `{}`.
+      # @param context [Hash] Per-verification context threaded through from `Triauth::IdentityKeys#verify`
+      #                       (e.g., `idx`, `mode`, `webAuthnOrigin`). Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      #
+      # @return [Base, nil] A verifier instance, or nil when the key
+      #         material cannot be imported. A key whose verifier cannot be constructed is skipped, never trusted.
+      def self.from_publishable_key(raw_public_key, options = {}, context = {}, config = {}) # rubocop:disable Lint/UnusedMethodArgument -- the abstract contract keeps its parameters
+        raise 'Triauth.Verifiers.Base.fromPublishableKey is abstract and must be implemented by a subclass'
+      end
+
+      # Verifies that a given signature matches the verifier's public key and the given message.
+      #
+      # This is the abstract contract that concrete verifiers (e.g., Ecdsa, Ed25519, WebAuthn) implement.
+      #
+      # @param message [String] The message to verify against.
+      # @param signature_base64url [String] Base64Url encoded signature.
+      # @param signed_data [Hash] Signature envelope's signedMetadata.
+      # @param unsigned_data [Hash] Signature envelope's unsignedMetadata.
+      #
+      # @return [Boolean] true or false basing on the verification result.
+      def verify(message, signature_base64url, signed_data, unsigned_data) # rubocop:disable Lint/UnusedMethodArgument -- the abstract contract keeps its parameters
+        raise 'Triauth.Verifiers.Base#verify is abstract and must be implemented by a subclass'
+      end
+
+      # Crypto encodings with no triauth-js counterpart (the profile's idiom table): byte conversions only, all math is OpenSSL's.
+
+      # The `SubjectPublicKeyInfo` prefix of an Ed25519 public key (`SEQUENCE { SEQUENCE { OID 1.3.101.112 }, BIT STRING }` ahead
+      # of the 32 raw key bytes): `OpenSSL::PKey` reads a raw key through this wrapper only.
+      ED25519_SPKI_PREFIX = ['302a300506032b6570032100'].pack('H*').freeze
+      private_constant :ED25519_SPKI_PREFIX
+
+      # The port of `crypto.subtle.importKey('raw', raw_bytes, algorithm, true, ['verify'])`: reads a raw public key through
+      # its SPKI DER wrapper, so that OpenSSL validates the key material (a P-256 point that is not on the curve is rejected).
+      #
+      # @param raw_bytes [String] The raw public key (a binary String): the 65-byte uncompressed point `04 || X || Y` for
+      #                           ECDSA P-256 (the verifiers decode a compressed point to this form first, with
+      #                           `Helpers.decode_p256_public_key`; the import itself still refuses every other form before
+      #                           OpenSSL sees it), the 32 raw bytes for Ed25519.
+      # @param algorithm [Hash] The WebCrypto import algorithm identifier, kept as data:
+      #                         `{name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256'}` or `{name: 'Ed25519'}`.
+      #
+      # @return [OpenSSL::PKey::PKey] the public key (an `OpenSSL::PKey::EC` for ECDSA).
+      #
+      # @raise [ArgumentError] when the bytes do not have the length (and prefix) of the algorithm's raw form, or the
+      #                        algorithm identifier is not one of the two above.
+      # @raise [OpenSSL::PKey::PKeyError] when OpenSSL rejects the key material (e.g., a point that is not on the curve).
+      def self.import_key(raw_bytes, algorithm)
+        case algorithm[:name]
+        when 'ECDSA'
+          raise ArgumentError, "Unsupported ECDSA curve: #{algorithm[:namedCurve]}" unless algorithm[:namedCurve] == 'P-256'
+          raise ArgumentError, 'ECDSA raw public key must be the 65-byte uncompressed point' unless raw_bytes.bytesize == 65 && raw_bytes.getbyte(0) == 0x04
+
+          # SPKI: SEQUENCE { SEQUENCE { id-ecPublicKey, prime256v1 }, BIT STRING point }
+          algorithm_identifier = OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId('id-ecPublicKey'), OpenSSL::ASN1::ObjectId('prime256v1')])
+          der = OpenSSL::ASN1::Sequence([algorithm_identifier, OpenSSL::ASN1::BitString(raw_bytes)]).to_der
+          return OpenSSL::PKey::EC.new(der)
+        when 'Ed25519'
+          raise ArgumentError, 'Ed25519 raw public key must be 32 bytes' unless raw_bytes.bytesize == 32
+
+          return OpenSSL::PKey.read(ED25519_SPKI_PREFIX + raw_bytes)
+        else
+          raise ArgumentError, "Unsupported algorithm: #{algorithm[:name]}"
+        end
+      end
+
+      # The port of `crypto.subtle.verify(algorithm, public_key, signature_bytes, data_bytes)`: verifies the raw signature of
+      # the wire (`r || s` for ECDSA, the 64 raw bytes for Ed25519) over the data bytes. The length is checked before any
+      # conversion, so a DER-encoded ECDSA signature is refused exactly as WebCrypto refuses it (no widened accept-set).
+      #
+      # @param algorithm [Hash] The WebCrypto verify algorithm identifier, kept as data:
+      #                         `{name: 'ECDSA', hash: 'SHA-256'}` or `{name: 'Ed25519'}`.
+      # @param public_key [OpenSSL::PKey::PKey] The public key, as returned by {Triauth::Verifiers::Base.import_key}.
+      # @param signature_bytes [String] The raw signature (a binary String): exactly 64 bytes for both algorithms.
+      # @param data_bytes [String] The signed data (a binary String).
+      #
+      # @return [Boolean] true when the signature verifies; false for a signature of another length, a signature that does
+      #                   not verify, or an operation OpenSSL refuses (`OpenSSL::PKey::PKeyError`).
+      #
+      # @raise [ArgumentError] when the algorithm identifier is not one of the two above.
+      def self.verify_signature(algorithm, public_key, signature_bytes, data_bytes)
+        case algorithm[:name]
+        when 'ECDSA'
+          raise ArgumentError, "Unsupported ECDSA hash: #{algorithm[:hash]}" unless algorithm[:hash] == 'SHA-256'
+          return false unless signature_bytes.bytesize == 64
+
+          return public_key.verify('SHA256', raw_to_der(signature_bytes), data_bytes)
+        when 'Ed25519'
+          return false unless signature_bytes.bytesize == 64
+
+          return public_key.verify(nil, signature_bytes, data_bytes)
+        else
+          raise ArgumentError, "Unsupported algorithm: #{algorithm[:name]}"
+        end
+      rescue OpenSSL::PKey::PKeyError
+        return false
+      end
+
+      # Converts a raw ECDSA signature `r || s` (two 32-byte big-endian unsigned integers) into the DER
+      # `SEQUENCE { INTEGER r, INTEGER s }` that OpenSSL verifies. `OpenSSL::ASN1::Integer` writes the minimal positive
+      # encodings (a leading zero byte ahead of a high bit, leading zero bytes dropped).
+      #
+      # @param signature_bytes [String] The 64-byte raw signature (a binary String).
+      #
+      # @return [String] the DER-encoded signature (a binary String).
+      #
+      # @raise [ArgumentError] when the signature is not 64 bytes.
+      def self.raw_to_der(signature_bytes)
+        raise ArgumentError, 'ECDSA raw signature must be 64 bytes' unless signature_bytes.bytesize == 64
+
+        r = OpenSSL::BN.new(signature_bytes.byteslice(0, 32), 2)
+        s = OpenSSL::BN.new(signature_bytes.byteslice(32, 32), 2)
+        return OpenSSL::ASN1::Sequence([OpenSSL::ASN1::Integer(r), OpenSSL::ASN1::Integer(s)]).to_der
+      end
+    end
+  end
+end

data/lib/triauth/verifiers/ecdsa.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 The Triauth Authors (https://www.triauth.org/)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+require_relative 'base'
+require_relative 'registry'
+require_relative '../helpers'
+
+module Triauth
+  module Verifiers
+    # The verifier for ECDSA signatures (P-256 curve with SHA-256).
+    # This is the default verifier in triauth.
+    class Ecdsa < Base
+      # @return [OpenSSL::PKey::EC] The public key the signatures are verified against.
+      attr_reader :public_key
+      # @return [Hash{Symbol => Object}] The effective settings: the global `Triauth.config` with the constructor's overrides merged over it.
+      attr_reader :config
+
+      # Constructs a new instance of ECDSA verifier for the given public crypto key and options.
+      #
+      # @param public_key [OpenSSL::PKey::EC] A public key in form of an `OpenSSL::PKey` object.
+      # @param options [Hash] Key options as read from the DNS record that contained the public_key. Defaults to `{}`.
+      # @param context [Hash] Per-verification context. Unused by this verifier. Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      def initialize(public_key, options = {}, context = {}, config = {}) # rubocop:disable Lint/UnusedMethodArgument -- `options` and `context` are the verifier constructor contract, unused here as in triauth-js
+        super()
+
+        @public_key = public_key
+        @config = Helpers.merge_config(config)
+      end
+
+      # Builds an instance of the Verifier from the raw key information read from the DNS.
+      #
+      # @param raw_public_key [String] A key as published in the DNS record (base64url of the 65-byte uncompressed or the 33-byte compressed P-256 point).
+      # @param options [Hash] Key options as read from the DNS record that contained the raw_public_key. Defaults to `{}`.
+      # @param context [Hash] Per-verification context. Unused by this verifier. Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      #
+      # @return [Ecdsa, nil] The instance of this verifier, or nil if key is invalid or other problem occurred.
+      def self.from_publishable_key(raw_public_key, options = {}, context = {}, config = {})
+        config = Helpers.merge_config(config)
+
+        begin
+          public_key = Base.import_key(Helpers.decode_p256_public_key(Helpers.base64url_to_uint8(raw_public_key)), { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' })
+          return new(public_key, options, context, config)
+        rescue StandardError => err
+          Helpers.log(config, :debug, err)
+          return nil
+        end
+      end
+
+      # Verifies that a given signature matches the verifier's public key and the given message.
+      #
+      # @param message [String] The message to verify against.
+      # @param signature_base64url [String] Base64Url encoded signature.
+      # @param signed_data [Hash] Signature envelope's signedMetadata. Unused by this verifier.
+      # @param unsigned_data [Hash] Signature envelope's unsignedMetadata. Unused by this verifier.
+      #
+      # @return [Boolean] true or false basing on the verification result.
+      def verify(message, signature_base64url, signed_data, unsigned_data) # rubocop:disable Lint/UnusedMethodArgument -- `signed_data` and `unsigned_data` are the verifier contract, unused here as in triauth-js
+        data = Helpers.string_to_utf8_bytes(message)
+        signature = Helpers.base64url_to_uint8(signature_base64url)
+        return Base.verify_signature({ name: 'ECDSA', hash: 'SHA-256' }, @public_key, signature, data)
+      rescue StandardError => err
+        Helpers.log(@config, :debug, err)
+        return false
+      end
+    end
+
+    Triauth::Verifiers.register('es256', Ecdsa)
+  end
+end

data/lib/triauth/verifiers/ed25519.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 The Triauth Authors (https://www.triauth.org/)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+require_relative 'base'
+require_relative 'registry'
+require_relative '../helpers'
+
+module Triauth
+  module Verifiers
+    # A verifier for Ed25519 (EdDSA over Curve25519) signatures.
+    #
+    # Support for Ed25519 keys in triauth is considered experimental: it needs the openssl gem 3.x over
+    # OpenSSL 1.1.1 or later (the Ruby 3.2 default gem over a current OpenSSL library has it).
+    class Ed25519 < Base
+      # @return [OpenSSL::PKey::PKey] The public key the signatures are verified against.
+      attr_reader :public_key
+      # @return [Hash{Symbol => Object}] The effective settings: the global `Triauth.config` with the constructor's overrides merged over it.
+      attr_reader :config
+
+      # Constructs a new instance of Ed25519 verifier for the given public crypto key and options.
+      #
+      # @param public_key [OpenSSL::PKey::PKey] A public key in form of an `OpenSSL::PKey` object.
+      # @param options [Hash] Key options as read from the DNS record that contained the public_key. Defaults to `{}`.
+      # @param context [Hash] Per-verification context. Unused by this verifier. Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      def initialize(public_key, options = {}, context = {}, config = {}) # rubocop:disable Lint/UnusedMethodArgument -- `options` and `context` are the verifier constructor contract, unused here as in triauth-js
+        super()
+
+        @public_key = public_key
+        @config = Helpers.merge_config(config)
+      end
+
+      # Builds an instance of the Verifier from the raw key information read from the DNS.
+      #
+      # @param raw_public_key [String] A key as published in the DNS record (base64url of the 32-byte raw public key).
+      # @param options [Hash] Key options as read from the DNS record that contained the raw_public_key. Defaults to `{}`.
+      # @param context [Hash] Per-verification context. Unused by this verifier. Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      #
+      # @return [Ed25519, nil] The instance of this verifier, or nil if key is invalid or other problem occurred.
+      def self.from_publishable_key(raw_public_key, options = {}, context = {}, config = {})
+        config = Helpers.merge_config(config)
+
+        begin
+          public_key = Base.import_key(Helpers.base64url_to_uint8(raw_public_key), { name: 'Ed25519' })
+          return new(public_key, options, context, config)
+        rescue StandardError => err
+          Helpers.log(config, :debug, err)
+          return nil
+        end
+      end
+
+      # Verifies that a given signature matches the verifier's public key and the given message.
+      #
+      # @param message [String] The message to verify against.
+      # @param signature_base64url [String] Base64Url encoded signature.
+      # @param signed_data [Hash] Signature envelope's signedMetadata. Unused by this verifier.
+      # @param unsigned_data [Hash] Signature envelope's unsignedMetadata. Unused by this verifier.
+      #
+      # @return [Boolean] true or false basing on the verification result.
+      def verify(message, signature_base64url, signed_data, unsigned_data) # rubocop:disable Lint/UnusedMethodArgument -- `signed_data` and `unsigned_data` are the verifier contract, unused here as in triauth-js
+        data = Helpers.string_to_utf8_bytes(message)
+        signature = Helpers.base64url_to_uint8(signature_base64url)
+        return Base.verify_signature({ name: 'Ed25519' }, @public_key, signature, data)
+      rescue StandardError => err
+        Helpers.log(@config, :debug, err)
+        return false
+      end
+    end
+
+    Triauth::Verifiers.register('ed25519', Ed25519)
+  end
+end

data/lib/triauth/verifiers/registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 The Triauth Authors (https://www.triauth.org/)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+require_relative '../helpers'
+
+module Triauth
+  # Holds information about registered digital signature verifiers.
+  # Each public key stored in the identity records in the DNS may be associated with a type of verifier that is to be used with it (e.g., `type=es256`).
+  module Verifiers
+    # the registry keys are wire values: the type String as published in the key record (`'es256'`), never a Symbol - like the LRU cache keys
+    @verifiers = {}
+
+    # Registers a verifier class that should be used for keys of the given type.
+    #
+    # @param type [String] the type of key, e.g., 'es256'
+    # @param verifier_class [Class] a class descending from `Triauth::Verifiers::Base` that should handle the keys of given type
+    def self.register(type, verifier_class)
+      @verifiers[type] = verifier_class
+    end
+
+    # Returns a verifier registered for the given key type.
+    #
+    # @param type [String] the type of the key for which verifier is being looked for
+    # @return [Class, nil] A class that descends from `Triauth::Verifiers::Base` (with a `from_publishable_key` factory) that is responsible for handling given keys, or nil if not found.
+    def self.get(type)
+      return @verifiers[type]
+    end
+
+    # Returns a list of registered verifier's types
+    #
+    # @return [Array<String>]
+    def self.list
+      return Helpers.ordered_entries(@verifiers).map(&:first) # `Object.keys`: an integer-like type lists first, in numeric order
+    end
+  end
+end

data/lib/triauth/verifiers/web_authn.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 The Triauth Authors (https://www.triauth.org/)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+require_relative 'base'
+require_relative 'registry'
+require_relative '../helpers'
+
+module Triauth
+  module Verifiers
+    # The base abstract verifier for WebAuthn signatures.
+    #
+    # Performs the WebAuthn-level assertion validation.
+    # Subclasses must define concrete import_algorithm, verify_algorithm, and register themselves (e.g., as `webauthn-es256`).
+    class WebAuthn < Base
+      # The Web Crypto parameters used to import the publishable key and to verify
+      # assertion signatures. Concrete subclasses MUST override these to bind a
+      # credential algorithm; left nil, the verifier fails closed.
+
+      # @return [Hash, nil] The import algorithm identifier a concrete subclass binds (`{name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256'}` or `{name: 'Ed25519'}`); nil here.
+      def self.import_algorithm = nil
+
+      # @return [Hash, nil] The verify algorithm identifier a concrete subclass binds (`{name: 'ECDSA', hash: 'SHA-256'}` or `{name: 'Ed25519'}`); nil here.
+      def self.verify_algorithm = nil
+
+      # Returns the bytes of a publishable key in the form that the `raw` import of `import_algorithm` accepts.
+      # Subclasses whose credential algorithm has more than one key form override it.
+      #
+      # @param raw_public_key [String] A key as published in the DNS record.
+      # @return [String] the key bytes (a binary String).
+      #
+      # @raise [TypeError] when the key is not in a form that the credential algorithm accepts.
+      def self.public_key_bytes(raw_public_key)
+        return Helpers.base64url_to_uint8(raw_public_key)
+      end
+
+      # @return [OpenSSL::PKey::PKey] The public key the assertion signatures are verified against.
+      attr_reader :public_key
+      # @return [Hash] Key options as read from the DNS record that contained the public key (see {#initialize}).
+      attr_reader :options
+      # @return [Hash] Per-verification context (see {#initialize}).
+      attr_reader :context
+      # @return [Hash{Symbol => Object}] The effective settings: the global `Triauth.config` with the constructor's overrides merged over it.
+      attr_reader :config
+
+      # Constructs a new instance of verifier for the given public crypto key and options.
+      #
+      # @param public_key [OpenSSL::PKey::PKey] A public key in form of an `OpenSSL::PKey` object.
+      # @param options [Hash] Key options as read from the DNS record that contained the public_key. Defaults to `{}`.
+      #        Supports `uv: 'required'` - assertions are then accepted only with the User Verified (UV) flag set
+      #        (i.e., the authenticator checked PIN/biometrics).
+      # @param context [Hash] Per-verification context (`idx`, `mode`, `webAuthnOrigin`). `idx` (key's index in its keyGroup) selects
+      #        which `unsignedData.sig[idx]` entry to verify against; `webAuthnOrigin`, if set, is enforced against `clientData.origin`.
+      #        Stored on `context`. Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      def initialize(public_key, options = {}, context = {}, config = {})
+        super()
+
+        @public_key = public_key
+        @options = options
+        @context = context
+        @config = Helpers.merge_config(config)
+      end
+
+      # Builds an instance of the Verifier from the raw key information read from the DNS.
+      #
+      # @param raw_public_key [String] A key as published in the DNS record.
+      # @param options [Hash] Key options as read from the DNS record that contained the raw_public_key. Defaults to `{}`.
+      # @param context [Hash] Per-verification context (`idx`, `mode`, `webAuthnOrigin`). `idx` (key's index in its keyGroup) selects
+      #        which `unsignedData.sig[idx]` entry to verify against; `webAuthnOrigin`, if set, is enforced against `clientData.origin`.
+      #        Stored on `context`. Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      #
+      # @return [WebAuthn, nil] The instance of this verifier, or nil if key is invalid or other problem occurred.
+      def self.from_publishable_key(raw_public_key, options = {}, context = {}, config = {})
+        config = Helpers.merge_config(config)
+
+        import_algorithm = self.import_algorithm
+        if import_algorithm.nil?
+          Helpers.log(config, :debug, 'WebAuthn is an algorithm-agnostic base verifier - use a concrete subclass (e.g., WebAuthnEs256)')
+          return nil
+        end
+
+        begin
+          public_key = Base.import_key(public_key_bytes(raw_public_key), import_algorithm)
+
+          return new(public_key, options, context, config)
+        rescue StandardError => err
+          Helpers.log(config, :debug, err)
+          return nil
+        end
+      end
+
+      # Verifies that a given signature matches the verifier's public key and the given message.
+      #
+      # @param message [String] The message that was signed; its SHA-256 digest must match `clientData.challenge`.
+      # @param signature_base64url [String] Base64Url encoded signature over `(authenticatorData || sha256(clientDataJSON))`.
+      # @param signed_data [Hash] Signature envelope's signedMetadata. Unused by this verifier.
+      # @param unsigned_data [Hash{Symbol => Object}] Signature envelope's unsignedMetadata. Must contain `sig[idx]` for this key's
+      #        index (set on `context[:idx]`; `sig` is an object keyed by the index string, or an array read by position),
+      #        carrying the original `clientDataJSON` (string) and `authenticatorData` (base64url, minimum 37 bytes, with the
+      #        User Present flag set - silent CTAP-level assertions are rejected).
+      #
+      # @return [Boolean] true or false basing on the verification result.
+      def verify(message, signature_base64url, signed_data, unsigned_data) # rubocop:disable Lint/UnusedMethodArgument -- `signed_data` is the verifier contract, unused here as in triauth-js
+        verify_algorithm = self.class.verify_algorithm
+        if verify_algorithm.nil?
+          Helpers.log(@config, :debug, 'WebAuthn is an algorithm-agnostic base verifier - use a concrete subclass (e.g., WebAuthnEs256)')
+          return false
+        end
+
+        idx = @context[:idx]
+        idx_key = idx.to_s.to_sym # the JS `sig[idx]` looks up the object key `"0"` for the index 0; the JSON key is the Symbol `:"0"` here
+        expected_challenge = Helpers.sha256(message)
+        expected_origin = @context[:webAuthnOrigin]
+
+        # SECURITY NOTE: `unsigned_data` is NOT covered by the triauth envelope's signature, but:
+        #   - clientData.challenge is checked to be the expected_challenge
+        #   - (authenticatorData + sha256(clientDataJSON)) is covered by the WebAuthn-signed payload
+        if !unsigned_data.is_a?(Hash)
+          return false
+        end
+
+        sig = unsigned_data[:sig]
+        # the JS `sig[idx]` reads an Array by position and an object by its "0" key; both shapes are accepted, as in triauth-js
+        entry = nil
+        if sig.is_a?(Array)
+          entry = sig[idx] if idx.is_a?(Integer) && idx >= 0 # a negative or non-integer index never reads an Array from its end
+        elsif sig.is_a?(Hash)
+          entry = sig[idx_key]
+        end
+        if !entry.is_a?(Hash) ||
+           !Helpers.is_string(entry[:clientDataJSON]) ||
+           !Helpers.is_base64url_string(entry[:authenticatorData])
+          return false
+        end
+
+        authenticator_data, client_data_json = entry.values_at(:authenticatorData, :clientDataJSON)
+
+        # Verify clientData structure, including that the clientData.challenge is an SHA-256 digest of the message
+        client_data = Helpers.safe_parse_json(client_data_json)
+        if client_data[:challenge] != expected_challenge ||               # <--- challenge MUST MATCH --- !!!
+           client_data_json.scan('"challenge":').length != 1 ||           # Ensure that "challenge" key appears exactly once in the clientDataJSON, as an extra safety precaution
+           client_data[:type] != 'webauthn.get' ||                        # type should always be 'webauthn.get'
+           (client_data.key?(:crossOrigin) && client_data[:crossOrigin] != false) || # if present, must be exactly false (a cross-origin <iframe> assertion carries true); the member is optional and absent means top-level same-origin (WebKit omits it) - `key?`, not `nil?`: an explicit null is present and rejected, as in triauth-js
+           (!expected_origin.nil? && !expected_origin.empty? && client_data[:origin] != expected_origin) # origin, if available from context, must match
+          return false
+        end
+
+        # Parse the authenticatorData: 32-byte rpIdHash, 1 flags byte, 4-byte signCount (37 bytes minimum)
+        authenticator_data_bytes = Helpers.base64url_to_uint8(authenticator_data)
+        if authenticator_data_bytes.bytesize < 37
+          Helpers.log(@config, :debug, 'WebAuthn assertion rejected - authenticatorData shorter than 37 bytes')
+          return false
+        end
+
+        # Require the User Present (UP) flag, as the W3C Web Authentication specification mandates for assertions.
+        # Browser-mediated assertions always carry UP=1 (the client performs a presence test before
+        # returning one); its absence indicates a CTAP-level "silent" assertion (options.up=false),
+        # e.g., minted by malware with direct access to a connected authenticator.
+        #
+        # The rpIdHash (bytes 0-31) is intentionally NOT checked: the public key is pinned in the
+        # DNS identity records and a WebAuthn credential only ever signs under its own rpId, so
+        # there is no cross-RP credential confusion to prevent; the phishing angle is covered by
+        # the clientData.origin check above. The signCount (bytes 33-36) is not checked either:
+        # clone detection requires server-side state that this stateless verifier does not have
+        # (and modern passkeys report a constant 0).
+        if (authenticator_data_bytes.getbyte(32) & 0x01) != 0x01
+          Helpers.log(@config, :debug, 'WebAuthn assertion rejected - User Present (UP) flag not set')
+          return false
+        end
+
+        # When the key record demands user verification (`uv=required`), also require the
+        # User Verified (UV) flag - i.e., the authenticator must have checked PIN/biometrics.
+        # Key records carrying any other `uv` value never reach this point - they taint their
+        # whole keyGroup during Triauth::IdentityKeys#add (fail closed, never silently weaker).
+        if @options[:uv] == 'required' && (authenticator_data_bytes.getbyte(32) & 0x04) != 0x04
+          Helpers.log(@config, :debug, 'WebAuthn assertion rejected - User Verified (UV) flag required by key options but not set')
+          return false
+        end
+
+        # Reconstruct the payload that was signed by webauthn
+        client_data_hash = OpenSSL::Digest::SHA256.digest(Helpers.string_to_utf8_bytes(client_data_json))
+
+        web_authn_payload = authenticator_data_bytes + client_data_hash
+
+        # Convert the signature being verified back to a binary String for verify_signature
+        signature = Helpers.base64url_to_uint8(signature_base64url)
+
+        # Verify the digital signature (may raise an exception if arguments are invalid)
+        return Base.verify_signature(verify_algorithm, @public_key, signature, web_authn_payload)
+      rescue StandardError => err
+        Helpers.log(@config, :debug, err)
+        return false
+      end
+    end
+
+    # A verifier for WebAuthn signatures backed by ECDSA P-256 (ES256) credentials.
+    #
+    # Shares all WebAuthn assertion validation with the WebAuthn base class; this subclass
+    # only binds the ES256 credential algorithm. The publishable key is the 65-byte uncompressed
+    # or the 33-byte compressed P-256 point (see `Triauth::Helpers.decode_p256_public_key`).
+    class WebAuthnEs256 < WebAuthn
+      # @return [Hash] `{name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256'}`
+      def self.import_algorithm = { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' }
+
+      # @return [Hash] `{name: 'ECDSA', hash: 'SHA-256'}`
+      def self.verify_algorithm = { name: 'ECDSA', hash: 'SHA-256' }
+
+      # Returns the publishable key as the 65-byte uncompressed P-256 point.
+      #
+      # @param raw_public_key [String] A key as published in the DNS record.
+      # @return [String] the 65-byte uncompressed point (a binary String).
+      #
+      # @raise [TypeError] when the key is not an uncompressed or a compressed P-256 point.
+      def self.public_key_bytes(raw_public_key)
+        return Helpers.decode_p256_public_key(Helpers.base64url_to_uint8(raw_public_key))
+      end
+    end
+
+    # A verifier for WebAuthn signatures backed by Ed25519 (EdDSA over Curve25519) credentials.
+    #
+    # Shares all WebAuthn assertion validation with the WebAuthn base class; this subclass
+    # only binds the Ed25519 credential algorithm. Like the plain Ed25519 verifier, it requires
+    # Ed25519 support in the openssl gem (3.x over OpenSSL 1.1.1 or later) - on runtimes without it,
+    # `from_publishable_key` returns nil and the keyGroup fails verification (fail closed).
+    class WebAuthnEd25519 < WebAuthn
+      # @return [Hash] `{name: 'Ed25519'}`
+      def self.import_algorithm = { name: 'Ed25519' }
+
+      # @return [Hash] `{name: 'Ed25519'}`
+      def self.verify_algorithm = { name: 'Ed25519' }
+    end
+
+    Triauth::Verifiers.register('webauthn-es256', WebAuthnEs256)
+    Triauth::Verifiers.register('webauthn-ed25519', WebAuthnEd25519)
+  end
+end

data/lib/triauth/verifiers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 The Triauth Authors (https://www.triauth.org/)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+require_relative 'verifiers/registry'
+require_relative 'verifiers/base'
+# Importing the concrete verifier modules for their side effects: each one calls
+# `register(...)` at module-load time so that `Triauth::Verifiers.get(...)` works
+# out of the box for 'es256', 'ed25519', 'webauthn-es256', and 'webauthn-ed25519'.
+require_relative 'verifiers/ecdsa'
+require_relative 'verifiers/ed25519'
+require_relative 'verifiers/web_authn'
+
+module Triauth
+  # A collection holding information about registered digital signature verifiers.
+  #
+  # Each public key stored in the identity records in the DNS may be associated with a type of verifier that is to be used with it.
+  module Verifiers
+    # the JS re-exports (`register`, `get`, `list`, `Base`, `Ecdsa`, `Ed25519`, `WebAuthn`, `WebAuthnEs256`, `WebAuthnEd25519`)
+    # have no counterpart: the module functions and the classes live on `Triauth::Verifiers` once their files are required
+  end
+end