triauth 0.0.1 → 1.0.0.beta.4

data/lib/triauth/logger.rb

@@ -0,0 +1,156 @@
+# 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
+
+
+module Triauth
+  # An implementation of simple logger that is set as the default value for `Triauth.config[:logger]` with output to the console.
+  class Logger
+    # The port of the JS `console`, the default `output` of the logger that `Triauth.config[:logger]` is set to: `debug` and
+    # `info` write one line to `$stdout`, `warn` and `error` one line to `$stderr`. A line is the parts joined by a space,
+    # Strings as they are, other values via `inspect`.
+    module CONSOLE
+      # @param args [Array<Object>] The parts of one log line.
+      def self.debug(*args)
+        write($stdout, args)
+      end
+
+      # @param args [Array<Object>] The parts of one log line.
+      def self.info(*args)
+        write($stdout, args)
+      end
+
+      # @param args [Array<Object>] The parts of one log line.
+      def self.warn(*args)
+        write($stderr, args)
+      end
+
+      # @param args [Array<Object>] The parts of one log line.
+      def self.error(*args)
+        write($stderr, args)
+      end
+
+      # Writes the parts as one line to `io`: Strings as they are, other values via `inspect`.
+      def self.write(io, args)
+        io.puts(args.map { |part| part.is_a?(String) ? part : part.inspect }.join(' '))
+      end
+      private_class_method :write
+    end
+
+    # @return [Object, nil] The object to which log messages are sent (see {#initialize}).
+    attr_accessor :output
+    # @return [String] A minimal level of messages that get logged to output. One of `debug`, `info`, `warn`, `error`.
+    attr_accessor :log_level
+    # @return [String] A prefix to use when logging messages.
+    attr_accessor :prefix
+    # @return [String, false, nil] The correlation/context identifier shown in the `[cid:...]` tag.
+    attr_accessor :cid
+
+    # @param output [Object, nil] An object to which log messages will be sent, that should implement `debug`, `info`, `warn`, `error` methods, just like {CONSOLE} (the port of the native `console`). Defaults to nil.
+    # @param options [Hash] Additional configurations options. Defaults to `{}`.
+    # @option options [String] :logLevel ('warn') A minimal level of messages that get logged to output. One of `debug`, `info`, `warn`, `error`. Defaults to 'warn'.
+    # @option options [String] :prefix ('[triauth]') A prefix to use when logging messages. Defaults to '[triauth]'.
+    # @option options [String, false, nil] :cid (nil) A correlation/context identifier shown in the `[cid:...]` tag, to identify log lines belonging to a single API call. A nil value leaves the tag empty here; `false` explicitly suppresses it. (The `spawn` factory resolves nil into an auto-generated id.)
+    def initialize(output = nil, options = {})
+      @output = output
+      @log_level = options[:logLevel].nil? || options[:logLevel].empty? ? 'warn' : options[:logLevel]
+      @prefix = options[:prefix].nil? || options[:prefix].empty? ? '[triauth]' : options[:prefix]
+      @cid = options[:cid]
+    end
+
+    # Returns a child logger for a single API call, resolving the correlation id (`cid`):
+    #   - nil: "autofill" - inherit this logger's `cid` or mint a fresh one.
+    #   - `false`: explicit opt-out - stored as-is and suppressed by `format_message` (no `[cid:...]` tag).
+    #   - string: used verbatim as the correlation id.
+    #
+    # @param cid [String, false, nil] explicit id, `false` to opt out, or nil to autofill. Defaults to nil.
+    # @return [Logger]
+    def spawn(cid = nil)
+      return Logger.new(
+        @output,
+        {
+          logLevel: @log_level,
+          prefix: @prefix,
+          cid: if cid.nil?
+                 # `this.cid || this.#generateCid()`: the JS falsy set of the `string|false|null` cid (nil, false and '') mints a fresh id
+                 @cid.nil? || @cid == false || @cid == '' ? generate_cid : @cid
+               else
+                 cid
+               end
+        }
+      )
+    end
+
+    # Logs a message at the `debug` level, when the logger's `logLevel` admits it.
+    #
+    # @param args [Array<Object>] Values to log. Passed through verbatim to the output's `debug` function,
+    #                             behind the logger's prefix, correlation id (when set), and level tag.
+    def debug(*args)
+      if %w[debug].include?(@log_level)
+        @output&.debug(*format_message('debug', args))
+      end
+    end
+
+    # Logs a message at the `info` level, when the logger's `logLevel` admits it.
+    #
+    # @param args [Array<Object>] Values to log. Passed through verbatim to the output's `info` function,
+    #                             behind the logger's prefix, correlation id (when set), and level tag.
+    def info(*args)
+      if %w[debug info].include?(@log_level)
+        @output&.info(*format_message('info', args))
+      end
+    end
+
+    # Logs a message at the `warn` level, when the logger's `logLevel` admits it.
+    #
+    # @param args [Array<Object>] Values to log. Passed through verbatim to the output's `warn` function,
+    #                             behind the logger's prefix, correlation id (when set), and level tag.
+    def warn(*args)
+      if %w[debug info warn].include?(@log_level)
+        @output&.warn(*format_message('warn', args))
+      end
+    end
+
+    # Logs a message at the `error` level, when the logger's `logLevel` admits it.
+    #
+    # @param args [Array<Object>] Values to log. Passed through verbatim to the output's `error` function,
+    #                             behind the logger's prefix, correlation id (when set), and level tag.
+    def error(*args)
+      if %w[debug info warn error].include?(@log_level)
+        @output&.error(*format_message('error', args))
+      end
+    end
+
+    private
+
+    def format_message(log_level, args)
+      parts = [@prefix]
+
+      if @cid && @cid != ''
+        parts.push("[cid:#{@cid}]")
+      end
+
+      parts.push("[#{log_level}]")
+
+      return [*parts, *args]
+    end
+
+    def generate_cid
+      return rand(36**8).to_s(36).rjust(8, '0')
+    end
+  end
+end

data/lib/triauth/multi_signature.rb

@@ -0,0 +1,177 @@
+# 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 'error'
+require_relative 'helpers'
+require_relative 'protocol'
+require_relative 'signature'
+
+module Triauth
+  # A multi-signature envelope, which is one or more `Triauth::Signature` segments joined and wrapped by the `|` character.
+  class MultiSignature
+    # @return [Hash{Symbol => Object}] The effective settings: the global `Triauth.config` with the constructor's overrides merged over it.
+    attr_reader :config
+    # @return [String] The multi-signature envelope this instance was parsed from.
+    attr_reader :raw_data
+    # @return [Array<Triauth::Signature>] The signature segments the envelope carries, in their order.
+    attr_reader :signatures
+
+    # Concatenates individual signature envelopes into one multi-signature envelope.
+    #
+    # @param signatures [Array<String>] Individual `Triauth::Signature` envelopes, each wrapped in `|`.
+    #
+    # @return [String] the multi-signature envelope carrying the given signatures, in the given order.
+    def self.generate(*signatures)
+      return Protocol::WRAPPER + signatures.map { |s| s[1...-1] }.join(Protocol::WRAPPER) + Protocol::WRAPPER
+    end
+
+    # Parses a multi-signature envelope into the individual `Triauth::Signature` segments it carries.
+    #
+    # @param raw_data [String] A multi-signature envelope: one or more signature segments wrapped in,
+    #   and delimited by, the `|` character.
+    # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+    #
+    # @raise [Triauth::Error] `invalid_signature` when the envelope is not a string, is not `|`-wrapped, exceeds
+    #   `LIMITS[:signatureBytesize]`, carries more than `LIMITS[:maxMultiSignatures]`
+    #   segments, or repeats a byte-identical segment.
+    def initialize(raw_data, config = {})
+      @config = Helpers.merge_config(config)
+
+      # Check the basic sanity and format of received arguments
+      if !Helpers.is_string(raw_data) ||
+         raw_data.length <= 3 ||
+         (raw_data[0] != Protocol::WRAPPER || raw_data[-1] != Protocol::WRAPPER) ||
+         Helpers.byte_size(raw_data) > Protocol::LIMITS[:signatureBytesize]
+        raise Triauth::Error.new({ code: 'invalid_signature', reason: 'invalid', message: 'Invalid signature' })
+      end
+
+      @raw_data = raw_data
+
+      segments = raw_data[1...-1].split(Protocol::WRAPPER, -1)
+
+      max_multi_signatures = Protocol::LIMITS[:maxMultiSignatures]
+      if segments.length < 1 || segments.length > max_multi_signatures
+        raise Triauth::Error.new({ code: 'invalid_signature', reason: 'invalid', message: 'Invalid signature' })
+      end
+
+      # Do not allow byte-identical duplicate segments
+      if segments.uniq.length != segments.length
+        raise Triauth::Error.new({ code: 'invalid_signature', reason: 'invalid', message: 'Invalid signature' })
+      end
+
+      # Extract and parse signature segments
+      @signatures = segments.map { |sig| Signature.new(Protocol::WRAPPER + sig + Protocol::WRAPPER, config) }
+    end
+
+    # Verifies that the signature is valid for the given message.
+    #
+    # @param message [String] Message, should be the same as originally signed.
+    # @param constraints [Hash] Optional constraints that the signature must satisfy. Defaults to `{}`.
+    # @option constraints [String] :type If given, passed through to each contributing `Signature#verify` for type matching.
+    # @option constraints [String] :identifier If given, must match the identifier for which it was created.
+    # @option constraints [String] :actor If given, passed through to each contributing `Signature#verify` for actor matching ('' = no actor).
+    # @option constraints [Integer] :ver If given, passed through to each contributing `Signature#verify` for version matching.
+    # @option constraints [String] :via If given, passed through to each contributing `Signature#verify` for client URL matching.
+    # @option constraints [Integer] :notBefore If given, must be a timestamp after which the signature was created.
+    # @option constraints [Integer] :notAfter If given, must be a timestamp before which the signature was created.
+    # @option constraints [Integer] :minSignatures If given, the multi-signature envelope must contain at least this many signatures.
+    # @option constraints [Integer] :maxSignatures If given, the multi-signature envelope must contain at most this many signatures.
+    #
+    # @return [Hash, false, nil] `{type: 'multisig', valid: Boolean, secure: (Boolean, nil), expires: (Integer, nil), verifiedAt: (Integer, nil), signatures: Array<Hash>}`, false or nil:
+    #   - `false` upon failed verification,
+    #   - `nil` upon time-related constraint failure (so callers can distinguish "expired" from generic failure),
+    #   - or a Hash with:
+    #     `type` - always the literal `'multisig'`,
+    #     `valid` - `true` when every contributing signature verified,
+    #     `secure` - `true` only when every contributing signature's identity was DNSSEC-validated; `nil` when there are no results to aggregate,
+    #     `expires` - the earliest defined per-signature expiry (ms timestamp), or `nil` if none of the contributing key groups had a TTL,
+    #     `verifiedAt` - the latest (max) per-signature verification timestamp (ms) - when the whole envelope finished verifying; `nil` when there are no results to aggregate,
+    #     `signatures` - array of per-signature verification results (see `Triauth::Signature#verify` for each entry's shape).
+    def verify(message, constraints = {})
+      verification_results = []
+
+      constraints = Helpers.object_assign({}, constraints)
+
+      if !Helpers.has_only_known_properties(
+        constraints,
+        [
+          :minSignatures, :maxSignatures, # enforced by this method
+          :type, :identifier, :actor, :ver, :via, :notBefore, :notAfter # enforced by Triauth.Signature.verify
+        ],
+        false
+      )
+        Helpers.log(@config, :error, 'Unrecognized constraint')
+        return false
+      end
+
+      # Fail if signature count constraints are provided in a non-numeric form
+      if (!constraints[:minSignatures].nil? && (!Helpers.is_number(constraints[:minSignatures]) || (constraints[:minSignatures].is_a?(Float) && constraints[:minSignatures].nan?))) ||
+         (!constraints[:maxSignatures].nil? && (!Helpers.is_number(constraints[:maxSignatures]) || (constraints[:maxSignatures].is_a?(Float) && constraints[:maxSignatures].nan?)))
+        Helpers.log(@config, :error, 'Invalid minSignatures/maxSignatures constraint')
+        return false
+      end
+
+      if !constraints[:minSignatures].nil? && @signatures.length < constraints[:minSignatures]
+        return false
+      end
+
+      constraints.delete(:minSignatures)
+
+      if !constraints[:maxSignatures].nil? && @signatures.length > constraints[:maxSignatures]
+        return false
+      end
+
+      constraints.delete(:maxSignatures)
+
+      @signatures.each do |signature|
+        sig_ver_res = signature.verify(message, constraints)
+
+        if !sig_ver_res || !sig_ver_res[:valid]
+          return sig_ver_res.nil? ? nil : false
+        end
+
+        verification_results.push(sig_ver_res)
+      end
+
+      valid = verification_results.length > 0 && verification_results.all? { |r| r && r[:valid] }
+      secure = verification_results.length > 0 ? verification_results.all? { |r| r && r[:secure] } : nil
+
+      # Combine expiries by taking the earliest defined value. An `undefined` expires on any single
+      # result means "no expiry constraint from this key" and should not poison the min.
+      # When no result carries an expiry, the combined expires is undefined.
+      expiries_with_values = verification_results.map { |r| r && r[:expires] }.select { |e| Helpers.is_number(e) }
+      expires = expiries_with_values.length > 0 ? expiries_with_values.min : nil
+
+      # Combine per-signature verification timestamps by taking the LATEST: the whole envelope is only
+      # fully verified once its slowest signature (e.g., one whose identity DNS blocked) has confirmed.
+      # Mirrors the expires filter above so a stray undefined cannot turn Math.max into NaN.
+      verified_at_values = verification_results.map { |r| r && r[:verifiedAt] }.select { |v| Helpers.is_number(v) }
+      verified_at = verified_at_values.length > 0 ? verified_at_values.max : nil
+
+      return {
+        type: 'multisig',
+        valid: valid,
+        secure: secure,
+        expires: expires,
+        verifiedAt: verified_at,
+        signatures: verification_results
+      }
+    end
+  end
+end

data/lib/triauth/protocol.rb

@@ -0,0 +1,74 @@
+# 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
+
+
+module Triauth
+  # Constants as defined by the triauth protocol.
+  module Protocol
+    # Protocol version, and its token form used in the signature envelope's version slot
+    VERSION = 1
+    VERSION_TOKEN = "v#{VERSION}"
+
+    # Signature envelope wrapper and field delimiter characters
+    WRAPPER = '|'
+    DELIMITER = ';'
+
+    # The marker that replaces '@' when deriving an identity domain from an identifier
+    AT_MARKER = '._at.'
+
+    # The default mode= and include= for domains that do not specify ones
+    DEFAULT_MODE = 'private'
+    DEFAULT_INCLUDE = 'any'
+
+    # Private-mode identity domains label length
+    PRIVATE_LABEL_LENGTH = 10
+
+    # The challenge-response flows: signature envelope `type` slots and key/include `use=` options
+    FLOWS = %w[attest auth ping sign stamp].freeze
+    FLOWS_USE_REGEXP = /\A(#{FLOWS.join('|')})(,(#{FLOWS.join('|')})){0,#{FLOWS.length - 1}}\z/
+
+    # The `include` record's `scope=` reserved values
+    SCOPE_ANY = 'any'
+    SCOPE_NONE = 'none'
+
+    # Shared validation/parsing limits.
+    LIMITS = {
+      identifierBytesize: 120,       # the maximal bytesize of a triauth identifier (`username@domain`)
+      domainNameBytesize: 253,       # the maximal bytesize of a DNS name (RFC 1035), bounding every host and domain name read from the wire
+      urlBytesize: 2048,             # the maximal bytesize of URLs (e.g., callbackUrl, attachment's sourceUrl, etc.)
+      challengeBytesize: 16 * 1024,  # the maximal bytesize of a base64url-encoded challenge string
+      signatureBytesize: 16 * 1024,  # the maximal bytesize of a Signature/MultiSignature envelope, also bounds the `response` string returned by the authenticator
+      extBytesize: 4 * 1024,         # the maximal bytesize of the JSON-serialized `ext` protocol-extensions object
+      messageBytesize: 2 * 1024,     # the maximal bytesize of a message to be signed or stamped
+      attachmentsCount: 10,          # the maximal number of attachments accepted by Triauth.sign
+      deviceNameBytesize: 20,        # the maximal bytesize of a device name, as visible in the identity records in DNS
+      maxDevices: 10,                # the maximal number of devices per user, as visible in the identity records in DNS
+      maxKeysPerDevice: 5,           # the maximal number of keys associated with a single device, as visible in the identity records in DNS
+      maxIncludes: 50,               # the maximal number of include statements per user, as visible in the identity records in DNS
+      maxGroups: 200,                # the maximal number of group names per user, as visible in the identity records in DNS
+      maxKeysPerSignature: 10,       # the maximal number of keys that may be used in a single Signature, defaults to 2 * maxKeysPerDevice (to allow for key rotation)
+      maxMultiSignatures: 5,         # the maximal number of individual Signatures inside MultiSignature (multi-signatures are typically used for attestations)
+      jsonMaxBytesize: 256 * 1024,   # the maximal allowable bytesize of JSON string that is considered safe for parsing
+      jsonMaxNestingDepth: 8,        # the maximal nesting depth of objects in JSON strings (root counts as depth 1, so `{}` is depth 1)
+      jsonMaxKeyLength: 255,         # the maximal length of a single object key in JSON strings
+      publicProfileMaxKeyBytesize: 64,    # per-key bytesize cap for publicProfile fields read from DNS, so a domain cannot bloat results
+      publicProfileMaxValueBytesize: 255, # per-value bytesize cap for publicProfile fields read from DNS, so a domain cannot bloat results
+      publicProfileMaxExtensions: 16      # max number of distinct `x-` extension fields kept in publicProfile (reserved keywords are not counted)
+    }.freeze
+  end
+end

data/lib/triauth/request_cipher.rb

@@ -0,0 +1,121 @@
+# 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'
+require 'securerandom'
+require_relative 'helpers'
+
+module Triauth
+  # Seals and opens the requests that follow a sign-in (ping, sign, stamp and attest), so that the redirect URL and
+  # the browser history show no identifier and no message.
+  #
+  # The client application seals the challenge with AES-128-GCM, under a request key that HKDF-SHA256 (RFC 5869)
+  # derives from the session key of the sign-in. The request also contains `skid`, a short hash of the session key,
+  # so that the authenticator can find the key. Only the client application and the authenticator know the session
+  # key, so a request that opens also proves where it comes from.
+  #
+  # A sealed request is `<iv>.<ciphertext>`, both base64url. The plaintext is the JSON of the challenge.
+  class RequestCipher
+    # The HKDF `info` of the request key
+    REQUEST_KEY_INFO = Helpers.string_to_utf8_bytes('triauth/request/v1')
+    private_constant :REQUEST_KEY_INFO
+
+    # Computes the session key ID, which the request contains readable so that the authenticator can find the key.
+    # It is the first 16 bytes of the SHA-256 of the 32 bytes of the session key.
+    #
+    # @param session_key [String] the session key, 43 base64url characters, without the domain of a delegated key.
+    #
+    # @return [String] the session key ID, 22 base64url characters.
+    def self.skid(session_key)
+      digest = OpenSSL::Digest::SHA256.digest(Helpers.base64url_to_uint8(session_key))
+      return Helpers.array_buffer_to_base64url(digest[0, 16])
+    end
+
+    # Seals a challenge under the session key. This is the client application's side.
+    #
+    # @param session_key [String] the session key, 43 base64url characters, without the domain of a delegated key.
+    # @param challenge [String] the challenge, base64url.
+    #
+    # @return [String] the sealed request, `<iv>.<ciphertext>`.
+    def self.seal(session_key, challenge)
+      # The IV comes from `SecureRandom` and never from `randomSource`. A repeated IV under one key breaks AES-GCM.
+      iv = SecureRandom.random_bytes(12)
+      key = request_key(session_key)
+      pt = Helpers.base64url_to_uint8(challenge)
+      cipher = OpenSSL::Cipher.new('aes-128-gcm').encrypt
+      cipher.key = key
+      cipher.iv = iv
+      # Web Crypto appends the 16-byte tag to the ciphertext. `Cipher#update` is never called with an empty string (some
+      # OpenSSL bindings refuse it), so an empty challenge seals to the tag alone, as Web Crypto gives.
+      ct = (pt.empty? ? ''.b : cipher.update(pt)) + cipher.final + cipher.auth_tag
+
+      return "#{Helpers.array_buffer_to_base64url(iv)}.#{Helpers.array_buffer_to_base64url(ct)}"
+    end
+
+    # Opens a sealed request with the session key. This is the authenticator's side.
+    #
+    # @param session_key [String] the session key, 43 base64url characters, without the domain of a delegated key.
+    # @param sealed_request [String] the sealed request, `<iv>.<ciphertext>`.
+    #
+    # @return [String] the challenge, base64url.
+    #
+    # @raise [TypeError] when the sealed request is malformed.
+    # @raise [OpenSSL::Cipher::CipherError] when the request does not open under this session key.
+    def self.open(session_key, sealed_request)
+      s = sealed_request.to_s
+      parts = s.empty? ? [''] : s.split('.', -1) # `String(x).split('.')`: JS splits `''` into `['']`, Ruby into `[]`
+      iv, ct, rest = parts
+
+      if !rest.nil? || iv.nil? || iv.length != 16 || ct.nil? || ct.empty?
+        raise TypeError, 'Malformed sealed request'
+      end
+
+      iv_bytes = Helpers.base64url_to_uint8(iv)
+      key = request_key(session_key)
+      ct_bytes = Helpers.base64url_to_uint8(ct)
+      # Web Crypto's decrypt throws for a ciphertext shorter than its 16-byte tag, while OpenSSL would check a truncated
+      # tag: the length is refused here.
+      if ct_bytes.bytesize < 16
+        raise TypeError, 'Malformed ciphertext'
+      end
+
+      cipher = OpenSSL::Cipher.new('aes-128-gcm').decrypt
+      cipher.key = key
+      cipher.iv = iv_bytes
+      cipher.auth_tag = ct_bytes[-16..] # the tag follows the ciphertext, as Web Crypto lays it out
+      # `Cipher#update` is never called with an empty string (see `seal`); a wrong tag raises `OpenSSL::Cipher::CipherError`
+      pt = (ct_bytes.bytesize == 16 ? ''.b : cipher.update(ct_bytes[0...-16])) + cipher.final
+
+      return Helpers.array_buffer_to_base64url(pt)
+    end
+
+    # Derives the AES-128-GCM request key from the session key with HKDF-SHA256 (RFC 5869). The empty salt acts as 32
+    # zero bytes, and the info label keeps this key apart from any other key of the session.
+    #
+    # @param session_key [String] the session key, 43 base64url characters.
+    #
+    # @return [String] the request key, 16 raw bytes (a binary String).
+    def self.request_key(session_key)
+      # the `usage` parameter (`encrypt` or `decrypt`, a Web Crypto key-usage flag) has no counterpart: the raw bytes are the key
+      ikm = Helpers.base64url_to_uint8(session_key)
+      return OpenSSL::KDF.hkdf(ikm, salt: ''.b, info: REQUEST_KEY_INFO, length: 16, hash: 'SHA256')
+    end
+    private_class_method :request_key
+  end
+end

data/lib/triauth/resolvers/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_relative '../error'
+require_relative '../helpers'
+
+module Triauth
+  module Resolvers
+    # A base class from which other DNS resolvers inherit common functions.
+    # Subclasses are expected to implement `resolve(domain_name, type, options = {}, config = {})`.
+    class Base
+      # Queries the DNS for resource records of a given type that are stored under a given domain name.
+      #
+      # This is the abstract contract that concrete subclasses (e.g., DnsJson, SystemDns, MultiResolver) implement.
+      #
+      # @param domain_name [String] A domain name to query the DNS for.
+      # @param type [String] A type of DNS resource record to look for (e.g., 'TXT', 'A').
+      # @param options [Hash] Per-call overrides for the resolver options passed to the constructor. Defaults to `{}`.
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      #
+      # @return [Array<Hash>] The array of retrieved DNS resource records in `{value, ttl, dnssec}` format
+      #   (`value` a String, `ttl` an Integer or nil, `dnssec` a Boolean or nil).
+      #
+      # @raise [RuntimeError] always - this method is abstract and carries no implementation of its own.
+      def resolve(domain_name, type, options = {}, config = {}) # rubocop:disable Lint/UnusedMethodArgument -- the abstract signature is the contract
+        raise 'Triauth.Resolvers.Base#resolve is abstract and must be implemented by a subclass'
+      end
+
+      # Returns configuration entries that are stored as DNS TXT records under a given domain name.
+      # Each configuration entry consist of a key, optional value, and any number of options.
+      #
+      # Options are the maximal trailing run of whole whitespace-separated `key=value` tokens;
+      # the text before that run is the entry's value, kept verbatim — `=`-containing text outside
+      # the trailing run is ordinary value text and needs no escaping. Option values and the value
+      # are percent-decoded; a record violating these rules is ignored as a whole.
+      #
+      # @example
+      #
+      #   # Given the following DNS TXT record of an example.com domain:
+      #   # `example.com IN TXT "app triauth-authenticator style=dark logo=none"`
+      #   resolve_config('example.com')
+      #   => [{key: "app", value: "triauth-authenticator", options: {style: "dark", logo: "none"}, ttl: 60, dnssec: false}]
+      #
+      # @param domain_name [String] a domain name for/of which configuration should be read from the DNS
+      # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+      #
+      # @return [Array<Hash>] The array of configuration entries/objects, as read from DNS, each in form of
+      #   `{key, value, options, ttl, dnssec}` (`key` and `value` Strings, `options` a Hash of Symbol keys to String
+      #   values, `ttl` an Integer or nil, `dnssec` a Boolean or nil).
+      #
+      # @raise [Triauth::Error] `dns_unavailable` when the underlying DNS query fails - intentionally propagated so that
+      #   API methods report a retryable error instead of treating the name as unconfigured.
+      def resolve_config(domain_name, config = {})
+        config = Helpers.merge_config(config)
+
+        Helpers.log(config, :debug, "[DNS] Querying DNS for config records of #{domain_name}")
+
+        rv = []
+
+        begin
+          txt_records = resolve(domain_name, 'TXT', {}, config)
+        rescue StandardError => err
+          Helpers.log(config, :debug, "DNS name resolution failed for #{domain_name}", { cause: err })
+          raise Triauth::Error.new({ code: 'dns_unavailable', message: 'DNS resolution failed, try again later' })
+        end
+
+        # A record is its key, a blank run, and a rest with no line terminator. An option is a whole
+        # whitespace-separated key=value token, so `a+b=c` never yields one. The `\S` stops the blank
+        # run and the rest from trading characters, so the parse stays linear in the record size.
+        record_regexp = /\A([A-Za-z0-9_-]+)#{Helpers::JS_WS}+(#{Helpers::JS_NOT_WS}#{Helpers::JS_DOT}*)\z/
+        option_token_regexp = /\A([A-Za-z0-9_\-\[\].@]+)=(#{Helpers::JS_NOT_WS}+)\z/
+
+        # The callback is a lambda, so that `return` leaves the record as in JS, from inside the option loop too (where it
+        # is spelled `return nil`, so the iterator lint sees it is deliberate); the block's `rescue` is the `try`/`catch`.
+        txt_records.each(&lambda do |record|
+          if (md = record[:value].match(record_regexp))
+            entry = { key: md[1], value: '', options: {}, ttl: record[:ttl], dnssec: record[:dnssec] }
+
+            if !Helpers.is_normal_string(entry[:key], 255)
+              return
+            end
+
+            # Split once, keeping the blank runs (odd indexes) so the value is reassembled verbatim.
+            # The option run is the maximal suffix of option tokens, collected right-to-left.
+            parts = Helpers.trim_end(md[2]).split(/(#{Helpers::JS_WS}+)/, -1)
+            option_matches = []
+            i = parts.length - 1
+            while i >= 0 && (option_md = parts[i].match(option_token_regexp))
+              option_matches.push(option_md)
+              i -= 2
+            end
+            entry[:value] = i < 0 ? '' : parts[0..i].join
+            option_matches.reverse!
+
+            # Process the run left to right; a repeated option key takes its last occurrence.
+            # Option values are consumed as published - no percent-decoding at this layer: options are
+            # machine vocabularies (and enter tag preimages), so their bytes stay those of the zone file.
+            option_matches.each do |m|
+              option_key = m[1]
+              option_value = m[2]
+
+              if !(Helpers.is_normal_string(option_key, 255) && Helpers.is_normal_string(option_value, nil))
+                return nil
+              end
+
+              # The map has no prototype, so a name such as `__proto__` is an ordinary key here, and the rules of
+              # each record family judge it like any other unknown option
+              entry[:options][option_key.to_sym] = option_value
+            end
+
+            # The text before the option run is the value. An options-only record has none and is ignored below.
+            entry[:value] = Helpers.trim(entry[:value])
+
+            if !Helpers.is_normal_string(entry[:value], nil)
+              return
+            end
+
+            return rv.push(entry)
+          end
+        rescue StandardError => err
+          Helpers.log(config, :debug, err)
+          # continue regardless of error
+        end)
+
+        Helpers.log(config, :debug, "[DNS] Parsed #{rv.length} DNS config record(s) from #{domain_name}")
+
+        return rv
+      end
+    end
+  end
+end