triauth 0.0.1 → 1.0.0.beta.4

data/lib/triauth/identity.rb

@@ -0,0 +1,301 @@
+# 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 'validator'
+require_relative 'authentication_endpoint'
+require_relative 'identity_domain'
+require_relative 'identity_keys'
+require_relative 'protocol'
+require_relative 'helpers'
+require_relative 'identity_includes'
+
+module Triauth
+  # Represents an entity that is identified by the provided `identifier`.
+  #
+  # Objects of this class start in unresolved state, and need to be resolved with a call to resolve() that queries the DNS.
+  class Identity
+    # A regexp for the reserved keywords that may appear in the identity records (DNS TXT records)
+    # and are recognized and returned as a part of publicProfile.
+    PUBLIC_PROFILE_KEYWORDS = /\A(name|initials)\z/
+    private_constant :PUBLIC_PROFILE_KEYWORDS
+
+    # @return [String] Identifier (e.g., `john@triauthdemo.org`) for which the Identity object is constructed.
+    attr_reader :identifier
+    # @return [Hash] Resolution options (`lookupCode`: the lookup code that addresses the identity records - required in private mode).
+    attr_reader :options
+    # @return [Hash{Symbol => Object}] The effective settings: the global `Triauth.config` with the constructor's overrides merged over it.
+    attr_reader :config
+    # The public profile entries published in the identity records (e.g., `name`, `initials`, and
+    # any `x-` prefixed key); a nil value marks a key that is published but carries no value.
+    # Populated by resolve().
+    # @return [Hash{Symbol => String, nil}]
+    attr_reader :public_profile
+    # Fully-qualified group names this identity claims membership in (e.g., ['admins@triauthdemo.org']);
+    # deduplicated and sorted, populated by resolve()
+    # @return [Array<String>]
+    attr_reader :groups
+    # @return [String] The domain name of the identifier.
+    attr_reader :domain_name
+    # @return [Triauth::AuthenticationEndpoint] The authentication endpoint of the identifier's domain. Resolved by resolve().
+    attr_reader :authentication_endpoint
+    # @return [Triauth::IdentityDomain] The identity domain of the identifier. Resolved by resolve().
+    attr_reader :identity_domain
+    # The public keys published for this identity, grouped by device. Populated by resolve().
+    # @return [Triauth::IdentityKeys]
+    attr_reader :keys
+    # The delegation grants published for this identity. Populated by resolve().
+    # @return [Triauth::IdentityIncludes]
+    attr_reader :includes
+    # Whether the identity resolved successfully; `nil` until resolve() has run.
+    # @return [Boolean, nil]
+    attr_reader :resolved
+    # Whether the whole identity resolution - the endpoint record and every identity record - was
+    # DNSSEC-validated; computed by resolve().
+    # @return [Boolean]
+    attr_reader :secure
+
+    # Constructs a new instance of Identity for the given identifier.
+    #
+    # Objects of this class start in an un-resolved state, and a call to the resolve() method that
+    # performs the DNS resolution needs to be made before most of the other methods can be used.
+    #
+    # @param identifier [String] Identifier (e.g., `john@triauthdemo.org`) for which the Identity object is constructed.
+    # @param options [Hash] Resolution options. Defaults to `{}`.
+    # @option options [String] :lookupCode The lookup code that addresses the identity records - required in private mode.
+    # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+    #
+    # @raise [Triauth::Error] carrying the first validation error when the identifier is malformed.
+    def initialize(identifier, options = {}, 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
+
+      @identifier = identifier
+      @options = options
+      @config = Helpers.merge_config(config)
+
+      # Ensure received identifier is valid
+      validation_result = Validator.validate_identifier(@identifier)
+      if !validation_result[:valid]
+        raise Triauth::Error.new(validation_result[:errors][0])
+      end
+
+      @public_profile = {}
+
+      @groups = []
+
+      @domain_name = @identifier.split('@', -1)[1]
+
+      @authentication_endpoint = AuthenticationEndpoint.new(@domain_name, @config)
+      @identity_domain = IdentityDomain.new(@identifier, @config)
+
+      @keys = IdentityKeys.new(@config)
+
+      @includes = IdentityIncludes.new(@config)
+
+      @resolved = nil
+
+      @secure = false
+    end
+
+    # Resolves the identity by querying the DNS.
+    # Identities must have at least one identity record present to be successfully resolved.
+    #
+    # The result is memoized, and subsequent calls to the `resolve` function do not perform DNS lookups.
+    # Rejections are currently memoized too.
+    #
+    # @return [Boolean] true if the identity 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.Identity for identifier #{@identifier}")
+
+            # Resolve the authenticationEndpoint to read triauth configuration, and then the identityDomain
+            #
+            # This will query the DNS for TXT records stored under the domain name of the identifier, looking for a TXT record starting with 'triauth' keyword.
+            # We start with this, to make sure domain is configured for triauth, and to get the mode in which identity domains should be derived from identifiers (e.g., public or private).
+            #
+            # Next, resolve the identity domain, using the options as read from the DNS TXT record defining the authentication endpoint, to obtain its identityRecords.
+            # This will query the DNS for TXT records stored at the domain name that is derived from the user's identifier (e.g., 'john._at.triauthdemo.org' (public mode), or '_4GIBDU53B3._at.private.triauthdemo.org' (private mode)).
+            if !@authentication_endpoint.resolve ||
+               !@identity_domain.set_options({ mode: @authentication_endpoint.options[:mode], lookupCode: @options[:lookupCode] }).resolve
+              @resolved = false
+              return [true, @resolved]
+            end
+
+            identity_records = @identity_domain.identity_records
+
+            # The endpoint record is a dependency of key discovery (its options select the identity domain
+            # the keys are read from), so keys can only be as secure as the endpoint record itself.
+            endpoint_secure = @authentication_endpoint.secure == true
+            include_policy = IdentityIncludes.parse_policy(@authentication_endpoint.options[:include])
+
+            public_profile_extension_count = 0
+            public_profile = {} # local copy, until object is resolved
+            groups = Set.new # local set of bare group names; qualified and assigned once resolved
+            identity_secure = endpoint_secure # identity can be only as secure as the endpoint answer
+            commitment = nil # the `commit` record value, if present
+
+            identity_records.each do |entry|
+              identity_secure &&= entry[:dnssec] == true
+
+              # DNS-derived freshness of this record: fresh until its TTL runs out
+              expires = (Helpers.is_integer(entry[:ttl]) ? Helpers.date_now + (entry[:ttl] * 1000) : nil)
+
+              # Profile values are the only record values that are percent-decoded
+              profile_value = PUBLIC_PROFILE_KEYWORDS.match?(entry[:key]) || entry[:key].start_with?('x-') ? Helpers.percent_decode(entry[:value]) : nil
+
+              # `key` record - add to this.keys (IdentityKeys)
+              if entry[:key] == 'key'
+                @keys.add(entry[:value], entry[:options], { expires: expires })
+
+              # `include` record - add to this.includes (IdentityIncludes)
+              elsif entry[:key] == 'include'
+                @includes.add(entry[:value], entry[:options], { expires: expires, includePolicy: include_policy, localDomainName: @domain_name })
+
+              # `groups` record - a comma-separated list of group names this identity claims membership in, later scoped to the identifier's domain
+              elsif entry[:key] == 'groups' && groups.size < Protocol::LIMITS[:maxGroups]
+
+                # No critical options are defined, so any critical option means the record is ignored ('x-' options are inert)
+                if !Helpers.verify_options_schema(entry[:options], {})
+                  Helpers.log(@config, :debug, 'Ignoring groups record due to unrecognized options', { identifier: @identifier })
+                  next
+                end
+
+                # Group names follow the device-name grammar; a record with any malformed name is ignored as a whole, never repaired.
+                names = Helpers.ascii_lowercase(entry[:value]).split(',', -1)
+                if !names.all? { |name| Validator.validate_group_name(name)[:valid] }
+                  Helpers.log(@config, :debug, 'Ignoring groups record with a malformed group name', { identifier: @identifier })
+                  next
+                end
+
+                names.each do |name|
+                  next if groups.include?(name) # duplicates never consume the cap
+
+                  if groups.size >= Protocol::LIMITS[:maxGroups]
+                    Helpers.log(@config, :debug, 'Ignoring groups and further group records over the limit', { limit: Protocol::LIMITS[:maxGroups] })
+                    break
+                  end
+                  groups.add(name)
+                end
+
+              # `commit` record - the commitment binding these records to the identity's derivation (its lookup code)
+              elsif entry[:key] == 'commit'
+
+                # No critical options are defined; the value is a 43-character base64url digest
+                if commitment.nil? &&
+                   Helpers.verify_options_schema(entry[:options], {}) &&
+                   Helpers.is_base64url_string(entry[:value])
+                  commitment = entry[:value]
+
+                else
+                  commitment = false
+                  Helpers.log(@config, :debug, 'Ignoring malformed or duplicated commit record(s)', { identifier: @identifier })
+
+                end
+
+              # publicProfile record - value is exposed raw, so it's the responsibility of API callers to escape it before rendering
+              # (the publicProfile keys are Symbols, the profile's key rule)
+              elsif PUBLIC_PROFILE_KEYWORDS.match?(entry[:key]) &&
+                    !profile_value.nil? &&
+                    Helpers.is_normal_string(profile_value, Protocol::LIMITS[:publicProfileMaxValueBytesize])
+
+                # Do not allow doubled keywords - drop the whole entry from publicProfile
+                if public_profile.key?(entry[:key].to_sym)
+                  public_profile[entry[:key].to_sym] = nil
+                  Helpers.log(@config, :debug, 'Ignoring doubled publicProfile entry', { keyword: entry[:key], identifier: @identifier })
+                  next
+                end
+
+                public_profile[entry[:key].to_sym] = profile_value
+
+              # Public profile extension / experimental keyword(s) in `x-` namespace
+              # - 'x-' namespace is open-ended, with a cap on the number of distinct extensions kept
+              # - similar as with recognized publicProfile entries - keys and values exposed raw, so must be escaped by callers before rendering
+              elsif entry[:key].start_with?('x-') &&
+                    Helpers.is_normal_string(entry[:key], Protocol::LIMITS[:publicProfileMaxKeyBytesize]) &&
+                    !profile_value.nil? &&
+                    Helpers.is_normal_string(profile_value, Protocol::LIMITS[:publicProfileMaxValueBytesize])
+
+                # Do not allow doubled keywords - drop the whole entry from publicProfile
+                if public_profile.key?(entry[:key].to_sym)
+                  public_profile[entry[:key].to_sym] = nil
+                  Helpers.log(@config, :debug, 'Ignoring doubled publicProfile entry', { keyword: entry[:key], identifier: @identifier })
+                  next
+                end
+
+                if public_profile_extension_count < Protocol::LIMITS[:publicProfileMaxExtensions]
+                  public_profile[entry[:key].to_sym] = profile_value
+                  public_profile_extension_count += 1
+
+                else
+                  Helpers.log(@config, :debug, 'Ignoring publicProfile extension over the limit', { keyword: entry[:key], identifier: @identifier })
+                end
+
+              else
+                Helpers.log(@config, :debug, 'Ignoring unrecognized identity record', { keyword: entry[:key], identifier: @identifier, domainName: @identity_domain.domain_name })
+
+              end
+            end
+
+            # When 'private' mode is set for the domain, identityRecords must carry a valid/matching 'commit ...' entry, for the identity to be resolved.
+            # The value of `commit ...` entry is supposed to be base64url(SHA-256(<untruncated base32 label>))
+            if !@identity_domain.expected_commitment.nil? &&
+               commitment != @identity_domain.expected_commitment
+              Helpers.log(@config, :info, 'Commit record missing, mismatched, or duplicated - identity unresolved', { identifier: @identifier })
+              @resolved = false
+              return [true, @resolved]
+            end
+
+            # Remove 'nil' records from local publicProfile and assign to this.publicProfile
+            @public_profile = public_profile.compact # `Object.fromEntries(Object.entries(publicProfile).filter(([, v]) => v !== null))`
+
+            # Sorted (DNS answer order is not stable) and qualified with the identifier's domain
+            @groups = groups.to_a.sort.map { |name| "#{name}@#{@domain_name}" }
+
+            @secure = identity_secure
+
+            Helpers.log(@config, :debug, "Parsed identity records for #{@identifier} - #{@keys.count} devices, #{@public_profile.size} profile entries, #{@groups.length} groups")
+
+            @resolved = identity_records.length > 0
+            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/identity_domain.rb

@@ -0,0 +1,212 @@
+# 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
+  # Derives a domain name under which identity records are stored, and reads the identity records from DNS
+  # (e.g., `john._at.triauthdemo.org` for `mode=public` domains or `_AXD3AKE8EX._at.triauthdemo.org` for `mode=private` domains).
+  #
+  # Objects of this class start in unresolved state, and need to be resolved with a call to resolve() that queries the DNS.
+  class IdentityDomain
+    # @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 identifier for which identity domain is constructed.
+    attr_reader :identifier
+    # The resolution options, as fixed by `set_options(...)`; `nil` until then.
+    # @return [Hash, nil]
+    attr_reader :options
+    # The domain name the identity records are published under, derived from the identifier and the
+    # resolution mode. `nil` until resolved.
+    # @return [String, nil]
+    attr_reader :domain_name
+    # The identity records as read from the DNS, in `Triauth::Resolvers::Base#resolve_config` form.
+    # `nil` until resolved.
+    # @return [Array<Hash>, nil] each record `{key: String, value: String, options: Hash, ttl: (Integer, nil), dnssec: (Boolean, nil)}`
+    attr_reader :identity_records
+    # The lookup code that addressed the records in private mode. `nil` in every other mode.
+    # @return [String, nil]
+    attr_reader :lookup_code
+    # The commitment a private-mode record set must carry to be accepted - the digest of the derived
+    # full label. `nil` in every other mode.
+    # @return [String, nil]
+    attr_reader :expected_commitment
+    # Whether the identity domain resolved successfully; `nil` until resolve() has run.
+    # @return [Boolean, nil]
+    attr_reader :resolved
+
+    # Returns the full derived label of a private-mode identity: the base32 encoding of the HMAC-SHA-256
+    # of the identifier, keyed by the identity's lookup code.
+    #
+    # The identifier needs to be in downcase, as results of this function are case-sensitive.
+    #
+    # @param identifier [String] the identifier to derive from
+    # @param lookup_code [String] the identity's lookup code, the HMAC key
+    # @return [String] the 52-character base32 string whose first PRIVATE_LABEL_LENGTH characters form the label of the identity domain, e.g., '4GIBDU53B3KGFSZUD5KRVUGITFQ2QAN2C55FNXO25S53WGT6CK6A'
+    def self.derive_full_label(identifier, lookup_code)
+      return Helpers.uint8_array_to_base32(
+        Helpers.hmac_sha256(Helpers.string_to_utf8_bytes(lookup_code), Helpers.string_to_utf8_bytes(identifier))
+      )
+    end
+
+    # Derives a domain name under which identity records are being kept for the passed identifier.
+    # Expects a pre-validated identifier (see Triauth::Validator.validate_identifier).
+    #
+    # @param identifier [String] a pre-validated user identifier
+    # @param options [Hash] options as read from the DNS TXT record specifying the authentication endpoint (`mode`), plus the identity's `lookupCode` under `mode=private`. Defaults to `{}`.
+    # @return [Hash, nil] the domain name (`{domainName: String}`, carrying the untruncated label as `fullLabel` under `mode=private`), or nil when no domain name can be derived (an unknown mode, or a missing/malformed lookup code under `mode=private`)
+    def self.derive(identifier, options = {})
+      # Extract the original domain name from the identifier
+      identifier_domain = identifier.split('@', -1)[1]
+
+      # The mode decides the way identity domain is derived
+      mode = options[:mode]
+
+      if mode == 'public'
+        return { domainName: identifier.sub('@', Protocol::AT_MARKER) }
+      end
+
+      if mode == 'private'
+        if !Helpers.is_lookup_code(options[:lookupCode])
+          return nil
+        end
+
+        # HMAC the identifier under the lookup code, base32 encode, and keep the fixed-length label
+        full_label = IdentityDomain.derive_full_label(identifier, options[:lookupCode])
+
+        return { domainName: "_#{full_label[0, Protocol::PRIVATE_LABEL_LENGTH]}#{Protocol::AT_MARKER}#{identifier_domain}", fullLabel: full_label }
+      end
+
+      # If an unknown mode is set, return `nil`
+      return nil
+    end
+
+    # Constructs a new instance of IdentityDomain basing on 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 identifier [String] The identifier for which identity domain is constructed.
+    # @param config [Hash] Optional overrides for the global Triauth.config settings. Defaults to `{}`.
+    def initialize(identifier, 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
+
+      @config = Helpers.merge_config(config)
+
+      @identifier = identifier
+
+      @options = nil
+
+      @domain_name = nil
+
+      @identity_records = nil
+
+      @lookup_code = nil
+
+      @expected_commitment = nil
+
+      @resolved = nil
+    end
+
+    # Sets the options for future `resolve` calls.
+    # May be called only once.
+    #
+    # @param options [Hash] Options read from the authentication endpoint DNS record (e.g., `{mode: 'public'|'private'}`), plus the identity's `lookupCode` where its mode consumes one.
+    #
+    # @return [IdentityDomain] this instance, so the call chains straight into resolve().
+    #
+    # @raise [RuntimeError] when the options have already been set.
+    def set_options(options)
+      if !@options.nil?
+        raise 'Options of a Triauth.IdentityDomain are already set'
+      end
+
+      @options = options
+
+      return self
+    end
+
+    # Resolves the identity domain by deriving the domain name from the identifier
+    # (using the authentication endpoint options) and querying the DNS for its identity records.
+    # Sets the `domain_name` and `identity_records` properties accordingly.
+    #
+    # Set resolution options with `set_options(...)` prior to the call.
+    #
+    # The result is memoized, and subsequent calls to `resolve` do not perform DNS lookups.
+    # Rejections are currently memoized too.
+    #
+    # @return [Boolean] true when identity records have been fetched, false when the domain name could not be derived.
+    #
+    # @raise [RuntimeError] when the resolution options have not been set yet - call `set_options(...)` first.
+    def resolve
+      if @options.nil?
+        raise 'Triauth.IdentityDomain options not set'
+      end
+
+      # 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
+            derived = IdentityDomain.derive(@identifier, @options)
+            # `derived?.domainName`: a nil `derived` prints empty here, where JS prints `undefined`
+            Helpers.log(@config, :debug, "Identity domain for identifier \"#{@identifier}\" is \"#{derived&.[](:domainName)}\"")
+
+            # A derivation that cannot be performed leaves the identity without an identity domain,
+            # which is like an identity that publishes no records.
+            if derived.nil?
+              @resolved = false
+              return [true, @resolved]
+            end
+
+            domain_name, full_label = derived.values_at(:domainName, :fullLabel)
+
+            if @options[:mode] == 'private'
+              @lookup_code = @options[:lookupCode]
+              @expected_commitment = Helpers.sha256(full_label)
+            end
+
+            @domain_name = domain_name
+            @identity_records = @config[:resolver].resolve_config(domain_name, @config)
+
+            @resolved = true
+            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