triauth 0.0.1 → 1.0.0.beta.4

data/lib/triauth/api/validation.rb

@@ -0,0 +1,162 @@
+# 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 '../config'
+require_relative '../helpers'
+require_relative '../validator'
+
+module Triauth
+  module Api
+    # Methods related to validation of various objects related to the triauth protocol
+    module Validation
+      # The validate method can be used to perform a basic format validation on the given objects.
+      # It is fast, synchronous, and does not perform any DNS requests.
+      #
+      # Currently, it supports validation of personal identifiers (`identifier`), device names (`deviceName`),
+      # group names (`groupName`, the bare name as published in a `groups` record, e.g., `admins`),
+      # lookup codes (`lookupCode`, the 16-character code of an identity under a `mode=private` domain),
+      # and device tags (`deviceTag`, as reported in results and passed to `Triauth.check`).
+      # At least one of the supported objects must be provided, and unrecognized (e.g., misspelled)
+      # keys are rejected, so that nothing silently passes as valid without being validated.
+      #
+      # Synopsis:
+      #
+      # ```ruby
+      # validation_result = Triauth.validate({ identifier?, deviceName?, groupName?, lookupCode?, deviceTag? })
+      # # returns {valid: true, errors: []} if all the objects passed validation
+      # # returns {valid: false, errors: [{code: ..., reason: ..., message: ...}, ...]} if at least one the objects failed validation
+      # # returns {valid: false, errors: [{code: 'invalid_arguments', ...}]} when objects is empty or not a Hash, or contains an unrecognized key
+      # # returns {valid: false, errors: [{code: 'invalid_config', ...}]} when config contains an unrecognized key
+      #
+      # ```
+      #
+      # Example:
+      #
+      # ```ruby
+      # Triauth.validate({ identifier: 'john@triauthdemo.org' })
+      # # {valid: true, errors: []}
+      #
+      # Triauth.validate({ identifier: 'john' })
+      # # {valid: false, errors: [{code: 'invalid_identifier', reason: 'invalid_format', message: 'Identifier must include one @ sign'}]}
+      #
+      # Triauth.validate({ groupName: 'admins@example.com' })
+      # # {valid: false, errors: [{code: 'invalid_group_name', reason: 'invalid_characters', message: 'Group name must include only letters, numbers, and hyphens'}]}
+      #
+      # Triauth.validate({ lookupCode: 'k7qj3fb9m2wzx0c4' })
+      # # {valid: false, errors: [{code: 'invalid_lookup_code', reason: 'invalid', message: 'Invalid lookup code'}]}
+      #
+      # Triauth.validate({ deviceTag: '3bi5oE_jXyjGY0WY5n6YqOuzRxfo40fuqDmLGaA5bKQ~K7QJ3FB9M2WZX0C4' })
+      # # {valid: true, errors: []}
+      # ```
+      #
+      # > [!NOTE]
+      # > `{valid: true}` confirms the *format* only - it is not input sanitization.
+      # > Callers must still encode or escape the value for whatever sink it flows into (SQL, shell, file paths, HTML, log lines).
+      #
+      # @param objects [Hash] one or more objects to validate. Defaults to nil (a missing argument is rejected with `invalid_arguments`).
+      # @option objects [String] :identifier an identifier to validate
+      # @option objects [String] :deviceName a deviceName to validate
+      # @option objects [String] :groupName a bare group name to validate (e.g., `admins`)
+      # @option objects [String] :lookupCode a lookup code to validate (e.g., `K7QJ3FB9M2WZX0C4`)
+      # @option objects [String] :deviceTag a device tag to validate, plain or composite (e.g., `3bi5oE_jXyjGY0WY5n6YqOuzRxfo40fuqDmLGaA5bKQ`)
+      # @param config [Hash] optional overrides for the global Triauth.config settings; unrecognized keys are rejected (`invalid_config`). Defaults to `{}`.
+      #
+      # @return [Hash] `{valid: Boolean, errors: Array<{code: String, reason?: String, message: String}>}`
+      #                A Hash with valid property containing the validation result,
+      #                and the errors property containing an array of errors (if any),
+      #                in the `{code, reason?, message}` format.
+      def self.validate(objects = nil, config = {})
+        # `objects` must be a plain object with at least one supported entry,
+        # so that e.g. validate(null) or validate({}) cannot pass as valid.
+        # (`!objects || typeof objects !== 'object' || Array.isArray(objects)` is "not a Hash": nil, false, strings, numbers, true and Arrays all take this branch, as in JS)
+        if !objects.is_a?(Hash) || objects.empty?
+          return {
+            valid: false,
+            errors: [{ code: 'invalid_arguments', message: 'Invalid or missing function arguments' }]
+          }
+        end
+
+        # Ensure only recognized objects with defined values are present to help avoid misspellings.
+        if !Helpers.has_only_known_properties(objects, %i[identifier deviceName groupName lookupCode deviceTag])
+          return {
+            valid: false,
+            errors: [{ code: 'invalid_arguments', message: 'Unrecognized function argument' }]
+          }
+        end
+
+        # Reject config overrides carrying unknown keys
+        if !Helpers.has_only_known_properties(Helpers.merge_config(config), Triauth::KNOWN_CONFIG_KEYS)
+          return {
+            valid: false,
+            errors: [{ code: 'invalid_config', message: 'Unrecognized configuration key' }]
+          }
+        end
+
+        retval = {
+          valid: true,
+          errors: []
+        }
+
+        keys = objects.keys
+
+        if keys.include?(:identifier)
+          vr = Validator.validate_identifier(objects[:identifier])
+          if !vr[:valid]
+            retval[:valid] = false
+            retval[:errors] = retval[:errors] + vr[:errors] # `concat` returns a new array (never `Array#concat`, which mutates)
+          end
+        end
+
+        if keys.include?(:deviceName)
+          vr = Validator.validate_device_name(objects[:deviceName])
+          if !vr[:valid]
+            retval[:valid] = false
+            retval[:errors] = retval[:errors] + vr[:errors]
+          end
+        end
+
+        if keys.include?(:groupName)
+          vr = Validator.validate_group_name(objects[:groupName])
+          if !vr[:valid]
+            retval[:valid] = false
+            retval[:errors] = retval[:errors] + vr[:errors]
+          end
+        end
+
+        if keys.include?(:lookupCode)
+          vr = Validator.validate_lookup_code(objects[:lookupCode])
+          if !vr[:valid]
+            retval[:valid] = false
+            retval[:errors] = retval[:errors] + vr[:errors]
+          end
+        end
+
+        if keys.include?(:deviceTag)
+          vr = Validator.validate_device_tag(objects[:deviceTag])
+          if !vr[:valid]
+            retval[:valid] = false
+            retval[:errors] = retval[:errors] + vr[:errors]
+          end
+        end
+
+        return retval
+      end
+    end
+  end
+end

data/lib/triauth/api.rb

@@ -0,0 +1,33 @@
+# 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
+  # The API namespace holds methods that are a part of the official triauth-ruby API.
+  #
+  # Every API method is also aliased at the top level, so `Triauth::Api::Authentication.authenticate` and
+  # `Triauth.authenticate` are the same function.
+  module Api
+  end
+end
+
+require_relative 'api/authentication'
+require_relative 'api/attestation'
+require_relative 'api/identity'
+require_relative 'api/signing'
+require_relative 'api/validation'

data/lib/triauth/authentication_endpoint.rb

@@ -0,0 +1,196 @@
+# 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'
+require_relative 'protocol'
+
+module Triauth
+  # Holds information about authentication endpoint for a given domain.
+  #
+  # Authentication endpoint is the URL under which Triauth Authenticator application, for the given identifier and its domain,
+  # is available and can be communicated with.
+  #
+  # Objects of this class start in unresolved state, and need to be resolved with a call to resolve() that queries the DNS.
+  class AuthenticationEndpoint
+    # The option keys the `triauth` record defines. The endpoint keeps these and the `x-` extensions and ignores
+    # every other option of the record, so a record that spells a future option still configures a verifier that
+    # predates it, and no other published name reaches a result.
+    ENDPOINT_OPTIONS = %i[mode include].freeze
+    private_constant :ENDPOINT_OPTIONS
+
+    # @return [String] The domain name for which authentication endpoint shall be resolved.
+    attr_reader :domain_name
+    # @return [Hash{Symbol => Object}] The effective settings: the global `Triauth.config` with the constructor's overrides merged over it.
+    attr_reader :config
+    # The endpoint's lowercase host — the value of the domain's `triauth` DNS record.
+    # `nil` until resolved.
+    # @return [String, nil]
+    attr_reader :host
+    # The `mode` and `include` options as read from the `triauth` DNS record, with the defaults filled in when
+    # absent, and its `x-` extension options as published. Every other option of the record is ignored.
+    # Empty until resolved.
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+    # Whether the DNS record defining this authentication endpoint was protected by DNSSEC.
+    # `true` only when the resolver reported a validated (AD) response for the matched `triauth` record;
+    # `false` when it was not validated or the resolver did not report DNSSEC status;
+    # `nil` until resolved.
+    # @return [Boolean, nil]
+    attr_reader :secure
+    # Expiry of the resolved `triauth` record: the resolution time plus its TTL, in milliseconds;
+    # `nil` when the record carried no TTL. Every expiry reported for an identity is bounded by it.
+    # @return [Integer, nil]
+    attr_reader :expires
+    # @return [Boolean, nil] Whether the authentication endpoint resolved successfully; `nil` until resolve() has run.
+    attr_reader :resolved
+
+    # Constructs a new instance of AuthenticationEndpoint basing on the domain name extracted form the identifier.
+    #
+    # Objects of this class start in an un-resolved state, and a call to the resolve() that
+    # performs the DNS resolution needs to be made before most of the other methods can be used.
+    #
+    # @param domain_name [String] The domain name for which authentication endpoint shall be resolved.
+    # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+    def initialize(domain_name, config = {})
+      # Memoizes the resolution, so that concurrent and repeated `resolve()` calls share a single
+      # DNS round trip. A rejection is memoized too, and is replayed to every later caller.
+      # The memoized outcome of the first resolution: `[true, result]` or `[false, error]`, guarded by the mutex
+      # (the port of the `#resolvePromise` promise).
+      @resolve_mutex = Mutex.new
+      @resolve_promise = nil
+
+      @domain_name = domain_name
+      @config = Helpers.merge_config(config)
+
+      @host = nil
+
+      @options = {}
+
+      @secure = nil
+
+      @expires = nil
+
+      @resolved = nil
+    end
+
+    # Keeps the options the `triauth` record defines, `mode` and `include`, and its `x-` extensions, and
+    # leaves every other option of the record out.
+    #
+    # @param options [Hash{Symbol => Object}] The options of the record, as parsed.
+    #
+    # @return [Hash{Symbol => Object}] the kept options, in a fresh Hash (the JS map without a prototype).
+    def self.known_options(options)
+      known = {}
+
+      options.each do |key, value|
+        if ENDPOINT_OPTIONS.include?(key) || (key[0] == 'x' && key[1] == '-')
+          known[key] = value
+        end
+      end
+
+      return known
+    end
+
+    # Returns the URL of the authentication endpoint, with the passed action and parameters included.
+    #
+    # With an action, it is the final URL to which the user's web browser should be redirected in the challenge-response flow.
+    # The params are passed inside the URL fragment identifier for privacy reasons.
+    #
+    # @param action [String, nil] An action verb used to construct the URL - e.g., 'auth', 'sign', etc., or nil for the bare endpoint URL.
+    # @param params [Hash] Parameters that should be included in the URL, ignored when action is nil (and then omitted: defaults to nil).
+    #
+    # @return [String] an url of authentication endpoint with the given action and parameters.
+    #
+    # @raise [RuntimeError] when the endpoint has not been resolved yet - call `resolve()` first.
+    def url_for(action, params = nil)
+      if !@resolved
+        raise 'Unresolved AuthenticationEndpoint'
+      end
+
+      if action.nil?
+        return "https://#{@host}/"
+      end
+
+      # Parameter values are base64url by the time they get here
+      pairs = params.map { |key, value| "#{key}=#{value}" }
+
+      return "https://#{@host}/#{action}.html#?#{pairs.join('&')}"
+    end
+
+    # Resolves the authentication endpoint for the domain by querying the DNS,
+    # and sets the `host`, `options`, and `secure` properties accordingly basing on the DNS response.
+    #
+    # The result is memoized, and subsequent calls to `resolve` do not perform DNS lookups.
+    # Rejections are currently memoized too.
+    #
+    # @return [Boolean] true if the URL of authentication endpoint has been resolved, false otherwise.
+    def resolve
+      # Memoize the outcome so that multiple and/or concurrent calls return the same status.
+      @resolve_mutex.synchronize do
+        @resolve_promise ||= begin
+          # The body of the memoized resolution is a lambda, so that every JS `return` is a `return` of the lambda.
+          resolution = lambda do
+            Helpers.log(@config, :debug, "Resolving Triauth.AuthenticationEndpoint for domain #{@domain_name}")
+
+            domain_config = @config[:resolver].resolve_config(@domain_name, @config)
+
+            domain_config.each do |entry|
+              if entry[:key] == 'triauth' && Helpers.is_domain_name(entry[:value])
+                if !@host.nil? && !@host.empty?
+                  # Multiple triauth records published — refuse to choose
+                  Helpers.log(@config, :warn, 'Multiple triauth records found; refusing to choose', { domainName: @domain_name })
+                  @host = nil
+                  @options = {}
+                  @secure = nil
+                  @expires = nil
+                  break
+                end
+
+                @host = entry[:value].downcase
+                @options = AuthenticationEndpoint.known_options(entry[:options])
+                @secure = entry[:dnssec] == true
+                @expires = Helpers.is_integer(entry[:ttl]) ? Helpers.date_now + (entry[:ttl] * 1000) : nil
+
+                # Set defaults
+                @options[:mode] = Protocol::DEFAULT_MODE if @options[:mode].nil?
+                @options[:include] = Protocol::DEFAULT_INCLUDE if @options[:include].nil?
+              end
+            end
+
+            Helpers.log(@config, :debug, "Triauth.AuthenticationEndpoint for domain #{@domain_name} is #{@host}")
+
+            @resolved = !@host.nil? && !@host.empty?
+            return [true, @resolved]
+          end
+          resolution.call
+        rescue StandardError => err
+          Helpers.log(@config, :debug, err)
+
+          @resolved = false
+          [false, err]
+        end
+      end
+
+      ok, value = @resolve_promise
+      raise value if !ok
+
+      return value
+    end
+  end
+end

data/lib/triauth/challenge.rb

@@ -0,0 +1,115 @@
+# 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 'json'
+require_relative 'helpers'
+require_relative 'identity'
+require_relative 'protocol'
+
+module Triauth
+  # Represents an authentication request (challenge) that is sent from client application to the Triauth Authenticator.
+  class Challenge
+    # @return [Triauth::Identity] The Identity the challenge is addressed to.
+    attr_reader :identity
+    # @return [Hash{Symbol => Object}] The challenge's wire fields - `type`, `identifier`, `nonce`, `iat` and `ver`, plus any per-flow additions.
+    attr_reader :data
+    # @return [Hash{Symbol => Object}] The effective settings: the global `Triauth.config` with the constructor's overrides merged over it.
+    attr_reader :config
+    # Populated by Challenge.from_string when re-hydrating a serialized challenge; left nil
+    # for freshly built challenges (use to_s to serialize on demand).
+    # @return [String, nil]
+    attr_accessor :challenge_string
+
+    # Recreates the Challenge from the given challenge.
+    #
+    # @param challenge_string [String] a challenge as sent to the authenticator: the part of the challenge stored during
+    #                                  stage 1 of the challenge-response flow before its `.` and decryption key.
+    # @param config [Hash] optional overrides for the global Triauth.config settings. Defaults to `{}`.
+    #
+    # @return [Triauth::Challenge]
+    # @raise [StandardError] upon problems with deserialization of the challenge or the format of personal identifier encoded within
+    def self.from_string(challenge_string, config = {})
+      decoded_challenge = Helpers.base64url_to_string(challenge_string)
+      challenge_data = Helpers.safe_parse_json(decoded_challenge)
+      identity = Identity.new(challenge_data[:identifier], {}, config)
+
+      retval = Challenge.new(identity, challenge_data, config)
+      retval.challenge_string = challenge_string
+
+      return retval
+    end
+
+    # Builds a new Challenge and populates the required request data fields with the default values,
+    # unless a value for them was provided through the data argument.
+    #
+    # @param type [String] the type of request associated with this challenge, e.g., 'auth', 'sign', etc.
+    # @param identity [Triauth::Identity] identity for which the authentication request is being built.
+    # @param data [Hash] data to include in the authentication request, may override the defaults
+    # @param config [Hash] optional overrides for the global Triauth.config settings. Defaults to `{}`.
+    #
+    # @return [Triauth::Challenge]
+    def self.build(type, identity, data, config = {})
+      config = Helpers.merge_config(config)
+
+      # Populate the data fields that must be present in the triauth authentication request with default values
+      data = Helpers.object_assign(
+        {},
+        data,
+        {
+          type: type,
+          identifier: identity.identifier, # the Identifier the request is addressed to
+          nonce: Helpers.random_string(24, config), # cryptographic nonce
+          iat: Helpers.date_now, # timestamp of when authentication request was created
+          ver: Protocol::VERSION
+        }
+      )
+
+      return Challenge.new(identity, data, config)
+    end
+
+    # Constructs a new instance of Challenge for the given identity and challenge data.
+    #
+    # Use the `build` factory to mint a fresh challenge, or `from_string` to re-hydrate a serialized
+    # one; this constructor stores what it is given and validates nothing on its own.
+    #
+    # @param identity [Triauth::Identity] The Identity the challenge is addressed to.
+    # @param data [Hash] The challenge's wire fields - `type`, `identifier`, `nonce`, `iat` and
+    #   `ver`, plus any per-flow additions such as `msg`, `attest` or `attachments`. Defaults to `{}`.
+    # @param config [Hash] optional overrides for the global Triauth.config settings. Defaults to `{}`.
+    def initialize(identity, data = {}, config = {})
+      @identity = identity
+      @data = data
+      @config = Helpers.merge_config(config)
+
+      # Populated by Challenge.from_string when re-hydrating a serialized challenge; left nil
+      # for freshly built challenges (use to_s to serialize on demand).
+      @challenge_string = nil
+    end
+
+    # Serializes this authentication request into a string that may be used as a challenge.
+    #
+    # The port of `toString()`.
+    #
+    # @return [String] a challenge which can be included in the redirect URL
+    def to_s
+      challenge_json = JSON.generate(@data)
+      return Helpers.string_to_base64url(challenge_json)
+    end
+  end
+end