familia 2.0.0.pre8 → 2.0.0.pre12

data/lib/familia/secure_identifier.rb

@@ -2,13 +2,14 @@
 
 require 'securerandom'
 
+# Provides a suite of tools for generating and manipulating cryptographically
+# secure identifiers in various formats and lengths.
 module Familia
   module SecureIdentifier
-
     # Generates a 256-bit cryptographically secure hexadecimal identifier.
     #
     # @return [String] A 64-character hex string representing 256 bits of entropy.
-    # @security Provides ~10^77 possible values, far exceeding UUID4's 128 bits.
+    # @security Provides ~10^77 possible values, far exceeding UUIDv4's 128 bits.
     def generate_hex_id
       SecureRandom.hex(32)
     end
@@ -26,13 +27,6 @@ module Familia
     #
     # @param base [Integer] The base for encoding the output string (2-36, default: 36).
     # @return [String] A secure identifier.
-    #
-    # @example Generate a 256-bit ID in base-36 (default)
-    #   generate_id # => "25nkfebno45yy36z47ffxef2a7vpg4qk06ylgxzwgpnz4q3os4"
-    #
-    # @example Generate a 256-bit ID in base-16 (hexadecimal)
-    #   generate_id(16) # => "568bdb582bc5042bf435d3f126cf71593981067463709c880c91df1ad9777a34"
-    #
     def generate_id(base = 36)
       target_length = SecureIdentifier.min_length_for_bits(256, base)
       generate_hex_id.to_i(16).to_s(base).rjust(target_length, '0')
@@ -43,87 +37,69 @@ module Familia
     #
     # @param base [Integer] The base for encoding the output string (2-36, default: 36).
     # @return [String] A secure short identifier.
-    #
-    # @example Generate a 64-bit short ID in base-36 (default)
-    #   generate_trace_id # => "lh7uap704unf"
-    #
-    # @example Generate a 64-bit short ID in base-16 (hexadecimal)
-    #   generate_trace_id(16) # => "94cf9f8cfb0eb692"
-    #
     def generate_trace_id(base = 36)
       target_length = SecureIdentifier.min_length_for_bits(64, base)
       generate_hex_trace_id.to_i(16).to_s(base).rjust(target_length, '0')
     end
 
-    # Truncates a 256-bit hexadecimal ID to 64 bits and encodes it in a given base.
-    # These short, deterministic IDs are useful for secure logging. By inputting the
-    # full hexadecimal string, you can generate a consistent short ID that allows
-    # tracking an entity through logs without exposing the entity's full identifier..
+    # Creates a deterministic 64-bit trace identifier from a longer hex ID.
     #
-    # @param hex_id [String] A 64-character hexadecimal string (representing 256 bits).
-    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
-    # @return [String] A 64-bit identifier, encoded in the specified base.
+    # This is a convenience method for `truncate_hex(hex_id, bits: 64)`.
+    # Useful for creating short, consistent IDs for logging and tracing.
+    #
+    # @param (see #truncate_hex)
+    # @return (see #truncate_hex)
     def shorten_to_trace_id(hex_id, base: 36)
-      target_length = SecureIdentifier.min_length_for_bits(64, base)
-      truncated = hex_id.to_i(16) >> (256 - 64) # Always 64 bits
-      truncated.to_s(base).rjust(target_length, '0')
+      truncate_hex(hex_id, bits: 64, base: base)
     end
 
-    # Truncates a 256-bit hexadecimal ID to 128 bits and encodes it in a given base.
-    # This function takes the most significant bits from the hex string to maintain
-    # randomness while creating a shorter, deterministic identifier that's safe for
-    # outdoor use.
-    #
-    # @param hex_id [String] A 64-character hexadecimal string (representing 256 bits).
-    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
-    # @return [String] A 128-bit identifier, encoded in the specified base.
-    #
-    # @example Create a shorter external ID from a full 256-bit internal ID
-    #   hex_id = generate_hex_id
-    #   external_id = shorten_to_external_id(hex_id)
-    #
-    # @note This is useful for creating shorter, public-facing IDs from secure internal ones.
-    # @security Truncation preserves the cryptographic properties of the most significant bits.
-    def shorten_to_external_id(hex_id, base: 36)
-      target_length = SecureIdentifier.min_length_for_bits(128, base)
-      truncated = hex_id.to_i(16) >> (256 - 128) # Always 128 bits
-      truncated.to_s(base).rjust(target_length, '0')
-    end
+    # Deterministically truncates a hexadecimal ID to a specified bit length.
+    #
+    # This function preserves the most significant bits of the input `hex_id` to
+    # create a shorter, yet still random-looking, identifier.
+    #
+    # @param hex_id [String] The input hexadecimal string.
+    # @param bits [Integer] The desired output bit length (e.g., 128, 64). Defaults to 128.
+    # @param base [Integer] The numeric base for the output string (2-36). Defaults to 36.
+    # @return [String] A new, shorter identifier in the specified base.
+    # @raise [ArgumentError] if `hex_id` is not a valid hex string, or if `input_bits`
+    #   is less than the desired output `bits`.
+    def truncate_hex(hex_id, bits: 128, base: 36)
+      target_length = SecureIdentifier.min_length_for_bits(bits, base)
+      input_bits = hex_id.length * 4
 
-    # Calculate minimum string length to represent N bits in given base
-    #
-    # When generating random IDs, we need to know how many characters are required
-    # to represent a certain amount of entropy. This ensures consistent ID lengths.
-    #
-    # Formula: ceil(bits * log(2) / log(base))
-    #
-    # @example Common usage with SecureRandom
-    #   SecureRandom.hex(32)  # 32 bytes = 256 bits = 64 hex chars
-    #   SecureRandom.hex(16)  # 16 bytes = 128 bits = 32 hex chars
-    #
-    # @example Using the method
-    #   min_length_for_bits(256, 16)  # => 64 (hex)
-    #   min_length_for_bits(256, 36)  # => 50 (base36)
-    #   min_length_for_bits(128, 10)  # => 39 (decimal)
+      unless hex_id.match?(/\A[0-9a-fA-F]+\z/)
+        raise ArgumentError, "Invalid hexadecimal string: #{hex_id}"
+      end
 
-    # Fast lookup for hex (base 16) - our most common case
-    # Avoids calculation overhead for 99% of ID generation
-    HEX_LENGTHS = {
-      256 => 64,  # SHA-256 equivalent entropy
-      128 => 32,  # UUID equivalent entropy
-      64  => 16,  # Compact ID
-    }.freeze
+      if input_bits < bits
+        raise ArgumentError, "Input bits (#{input_bits}) cannot be less than desired output bits (#{bits})."
+      end
 
-    # Get minimum character length needed to encode `bits` of entropy in `base`
+      # Truncate by right-shifting to keep the most significant bits
+      truncated_int = hex_id.to_i(16) >> (input_bits - bits)
+      truncated_int.to_s(base).rjust(target_length, '0')
+    end
+
+    # Calculates the minimum string length required to represent a given number of
+    # bits in a specific numeric base.
+    #
+    # @private
     #
-    # @param bits [Integer] Number of bits of entropy needed
-    # @param base [Integer] Numeric base (2-36)
-    # @return [Integer] Minimum string length required
+    # @param bits [Integer] The number of bits of entropy.
+    # @param base [Integer] The numeric base (2-36).
+    # @return [Integer] The minimum string length required.
     def self.min_length_for_bits(bits, base)
-      return HEX_LENGTHS[bits] if base == 16 && HEX_LENGTHS.key?(bits)
+      # Fast lookup for hex (base 16) - our most common case
+      hex_lengths = {
+        256 => 64,  # SHA-256 equivalent entropy
+        128 => 32,  # UUID equivalent entropy
+        64  => 16,  # Compact ID
+      }.freeze
+      return hex_lengths[bits] if base == 16 && hex_lengths.key?(bits)
 
-      @length_cache ||= {}
-      @length_cache[[bits, base]] ||= (bits * Math.log(2) / Math.log(base)).ceil
+      @min_length_for_bits_cache ||= {}
+      @min_length_for_bits_cache[[bits, base]] ||= (bits * Math.log(2) / Math.log(base)).ceil
     end
   end
 end

data/lib/familia/verifiable_identifier.rb

@@ -0,0 +1,162 @@
+# lib/familia/verifiable_identifier.rb
+
+require 'openssl'
+require_relative 'secure_identifier'
+
+module Familia
+  # Creates and verifies identifiers that contain an embedded HMAC signature,
+  # allowing for stateless verification of an identifier's authenticity.
+  module VerifiableIdentifier
+    # By extending SecureIdentifier, we gain access to its instance methods
+    # (like generate_hex_id) as class methods on this module.
+    extend Familia::SecureIdentifier
+
+    # The secret key for HMAC generation, loaded from an environment variable.
+    #
+    # This key is the root of trust for verifying identifier authenticity. It must be
+    # a long, random, and cryptographically strong string.
+    #
+    # @!attribute [r] SECRET_KEY
+    #   @return [String] The secret key.
+    #
+    # @note Security Considerations:
+    #   - **Secrecy:** This key MUST be kept secret and secure, just like a database
+    #     password or API key. Do not commit it to version control.
+    #   - **Consistency:** All running instances of your application must use the
+    #     exact same key, otherwise verification will fail across different servers.
+    #   - **Rotation:** If this key is ever compromised, it must be rotated. Be
+    #     aware that rotating the key will invalidate all previously generated
+    #     verifiable identifiers.
+    #
+    # @example Generating and Setting the Key
+    #     1. Generate a new secure key in your terminal:
+    #        $ openssl rand -hex 32
+    #        > cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d
+    #
+    #     2. Set it as an environment variable in your production environment:
+    #        export VERIFIABLE_ID_HMAC_SECRET="cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d"
+    #
+    SECRET_KEY = ENV.fetch('VERIFIABLE_ID_HMAC_SECRET', 'cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d')
+
+    # The length of the random part of the ID in hex characters (256 bits).
+    RANDOM_HEX_LENGTH = 64
+    # The length of the HMAC tag in hex characters (64 bits).
+    # 64 bits is strong enough to prevent forgery (1 in 18 quintillion chance).
+    TAG_HEX_LENGTH = 16
+
+    # Generates a verifiable, base-36 encoded identifier.
+    #
+    # The final identifier contains a 256-bit random component and a 64-bit
+    # authentication tag.
+    #
+    # @param base [Integer] The base for encoding the output string.
+    # @return [String] A verifiable, signed identifier.
+    def self.generate_verifiable_id(base_or_scope = nil, scope: nil, base: 36)
+      # Handle backward compatibility with positional base argument
+      if base_or_scope.is_a?(Integer)
+        base = base_or_scope
+        # scope remains as passed in keyword argument
+      elsif base_or_scope.is_a?(String) || base_or_scope.nil?
+        scope = base_or_scope if scope.nil?
+        # base remains as passed in keyword argument or default
+      end
+
+      # Re-use generate_hex_id from the SecureIdentifier module.
+      random_hex = generate_hex_id
+      tag_hex = generate_tag(random_hex, scope: scope)
+
+      combined_hex = random_hex + tag_hex
+
+      # Re-use the min_length_for_bits helper from the SecureIdentifier module.
+      total_bits = (RANDOM_HEX_LENGTH + TAG_HEX_LENGTH) * 4
+      target_length = Familia::SecureIdentifier.min_length_for_bits(total_bits, base)
+
+      combined_hex.to_i(16).to_s(base).rjust(target_length, '0')
+    end
+
+    # Verifies the authenticity of a given identifier using a timing-safe comparison.
+    #
+    # @param verifiable_id [String] The identifier string to check.
+    # @param base [Integer] The base of the input string.
+    # @return [Boolean] True if the identifier is authentic, false otherwise.
+    def self.verified_identifier?(verifiable_id, base_or_scope = nil, scope: nil, base: 36)
+      # Handle backward compatibility with positional base argument
+      if base_or_scope.is_a?(Integer)
+        base = base_or_scope
+        # scope remains as passed in keyword argument
+      elsif base_or_scope.is_a?(String) || base_or_scope.nil?
+        scope = base_or_scope if scope.nil?
+        # base remains as passed in keyword argument or default
+      end
+
+      return false unless plausible_identifier?(verifiable_id, base)
+
+      expected_hex_length = (RANDOM_HEX_LENGTH + TAG_HEX_LENGTH)
+      combined_hex = verifiable_id.to_i(base).to_s(16).rjust(expected_hex_length, '0')
+
+      random_part = combined_hex[0...RANDOM_HEX_LENGTH]
+      tag_part = combined_hex[RANDOM_HEX_LENGTH..]
+
+      expected_tag = generate_tag(random_part, scope: scope)
+      OpenSSL.secure_compare(expected_tag, tag_part)
+    end
+
+    # Checks if an identifier is plausible (correct format and length) without
+    # performing cryptographic verification.
+    #
+    # This can be used as a fast pre-flight check to reject obviously
+    # malformed identifiers.
+    #
+    # @param identifier_str [String] The identifier string to check.
+    # @param base [Integer] The base of the input string.
+    # @return [Boolean] True if the identifier has a valid format, false otherwise.
+    def self.plausible_identifier?(identifier_str, base = 36)
+      return false unless identifier_str.is_a?(::String)
+
+      # 1. Check length
+      total_bits = (RANDOM_HEX_LENGTH + TAG_HEX_LENGTH) * 4
+      expected_length = Familia::SecureIdentifier.min_length_for_bits(total_bits, base)
+      return false unless identifier_str.length == expected_length
+
+      # 2. Check character set
+      # The most efficient way to check for invalid characters is to attempt
+      # conversion and rescue the error.
+      Integer(identifier_str, base)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    class << self
+      private
+
+      # Generates the HMAC tag for a given message.
+      # @private
+      def generate_tag(message, scope: nil)
+        # Include scope in HMAC calculation for domain separation if provided.
+        # The scope parameter enables creating cryptographically isolated identifier
+        # namespaces (e.g., per-domain, per-tenant, per-application) while maintaining
+        # all security properties of the base system.
+        #
+        # Security considerations for scope values:
+        # - Any string content is cryptographically safe (HMAC handles arbitrary input)
+        # - No length restrictions (short scopes like "a" or long scopes work equally well)
+        # - UTF-8 encoding is handled consistently
+        # - Empty string "" vs nil produce different identifiers (intentional for security)
+        # - Different scope values guarantee different identifier spaces
+        #
+        # Examples of scope usage:
+        # - Customer isolation: scope: "tenant:#{tenant_id}"
+        # - Environment separation: scope: "production" vs scope: "staging"
+        # - Domain scoping: scope: "example.com"
+        # - Application scoping: scope: "#{app_name}:#{version}"
+        hmac_input = scope ? "#{message}:scope:#{scope}" : message
+
+        digest = OpenSSL::Digest.new('sha256')
+        hmac = OpenSSL::HMAC.hexdigest(digest, SECRET_KEY, hmac_input)
+        # Truncate to the desired length for the tag.
+        hmac[0...TAG_HEX_LENGTH]
+      end
+    end
+  end
+end

data/lib/familia/version.rb

@@ -2,5 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre8'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre12'.freeze unless defined?(Familia::VERSION)
 end

data/lib/familia.rb

@@ -81,6 +81,7 @@ end
 
 require_relative 'familia/base'
 require_relative 'familia/features'
+require_relative 'familia/features/autoloader'
 require_relative 'familia/data_type'
 require_relative 'familia/horreum'
 require_relative 'familia/encryption'

data/setup.cfg

@@ -0,0 +1,5 @@
+[scriv]
+categories = Added, Changed, Deprecated, Removed, Fixed, Security, Documentation, AI Assistance
+version = command: ruby -r ./lib/familia/version.rb -e "puts Familia::VERSION"
+main_branches = main, develop
+md_header_level = 2

data/try/core/secure_identifier_try.rb

@@ -56,22 +56,6 @@ hex_trace_id = Familia.generate_hex_trace_id
 [hex_trace_id.class, hex_trace_id.length == 16, hex_trace_id.match?(/^[a-f0-9]+$/)]
 #=> [String, true, true]
 
-## Familia.shorten_to_external_id
-Familia.respond_to?(:shorten_to_external_id)
-#=> true
-
-## Can shorten hex ID to external ID (128 bits)
-hex_id = Familia.generate_hex_id
-external_id = Familia.shorten_to_external_id(hex_id)
-[external_id.class, external_id.length < hex_id.length]
-#=> [String, true]
-
-## Can shorten hex ID to external ID with custom base (hex)
-hex_id = Familia.generate_hex_id
-hex_external_id = Familia.shorten_to_external_id(hex_id, base: 16)
-[hex_external_id.class, hex_external_id.length == 32]
-#=> [String, true]
-
 ## Familia.shorten_to_trace_id
 Familia.respond_to?(:shorten_to_trace_id)
 #=> true
@@ -88,10 +72,55 @@ hex_trace_id = Familia.shorten_to_trace_id(hex_id, base: 16)
 [hex_trace_id.class, hex_trace_id.length == 16]
 #=> [String, true]
 
+## Familia.truncate_hex
+Familia.respond_to?(:truncate_hex)
+#=> true
+
+## Can truncate hex ID to 128 bits by default
+hex_id = Familia.generate_hex_id
+truncated_id = Familia.truncate_hex(hex_id)
+[truncated_id.class, truncated_id.length < hex_id.length]
+#=> [String, true]
+
+## Can truncate hex ID to a custom bit length (64 bits)
+hex_id = Familia.generate_hex_id
+truncated_64 = Familia.truncate_hex(hex_id, bits: 64)
+[truncated_64.class, truncated_64.length < hex_id.length]
+#=> [String, true]
+
+## Can truncate with a custom base (hex)
+hex_id = Familia.generate_hex_id
+hex_truncated = Familia.truncate_hex(hex_id, bits: 128, base: 16)
+[hex_truncated.class, hex_truncated.length == 32]
+#=> [String, true]
+
+## Truncated IDs are deterministic
+hex_id = Familia.generate_hex_id
+id1 = Familia.truncate_hex(hex_id)
+id2 = Familia.truncate_hex(hex_id)
+id1 == id2
+#=> true
+
+## Raises error for invalid hex
+begin
+  Familia.truncate_hex("not-a-hex-string")
+rescue ArgumentError => e
+  e.message
+end
+#=> "Invalid hexadecimal string: not-a-hex-string"
+
+## Raises error if input bits are less than output bits
+begin
+  Familia.truncate_hex("abc", bits: 64)
+rescue ArgumentError => e
+  e.message
+end
+#=> "Input bits (12) cannot be less than desired output bits (64)."
+
 ## Shortened IDs are deterministic
 hex_id = Familia.generate_hex_id
-id1 = Familia.shorten_to_external_id(hex_id)
-id2 = Familia.shorten_to_external_id(hex_id)
+id1 = Familia.shorten_to_trace_id(hex_id)
+id2 = Familia.shorten_to_trace_id(hex_id)
 id1 == id2
 #=> true
 

data/try/core/verifiable_identifier_try.rb

@@ -0,0 +1,171 @@
+# try/core/verifiable_identifier_try.rb
+
+require_relative '../helpers/test_helpers'
+require 'familia/verifiable_identifier'
+
+## Module is available
+defined?(Familia::VerifiableIdentifier)
+#=> "constant"
+
+## Uses the development secret key by default when ENV is not set
+Familia::VerifiableIdentifier::SECRET_KEY
+#=> "cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d"
+
+# --- Verifiable ID Generation and Verification ---
+
+## Generates a non-empty string ID
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+id.is_a?(String) && !id.empty?
+#=> true
+
+## Generated ID is URL-safe (base36)
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+id.match?(/[a-z0-9]+/ix)
+#=> true
+
+## Generates unique identifiers on subsequent calls
+Familia::VerifiableIdentifier.generate_verifiable_id
+#=/> Familia::VerifiableIdentifier.generate_verifiable_id
+
+## A genuinely generated ID successfully verifies
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+Familia::VerifiableIdentifier.verified_identifier?(id)
+#=> true
+
+## Fails verification for a completely random garbage string
+Familia::VerifiableIdentifier.verified_identifier?('this-is-not-a-valid-id-at-all')
+#=> false
+
+## Fails verification for a string with invalid characters for the base
+# A plus sign is not a valid base-36 character.
+Familia::VerifiableIdentifier.verified_identifier?('this+is+invalid', 36)
+#=> false
+
+## Fails verification if the random part of the ID is tampered with
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+tampered_id = id.dup
+tampered_id[0] = (tampered_id[0] == 'a' ? 'b' : 'a') # Flip the first character
+Familia::VerifiableIdentifier.verified_identifier?(tampered_id)
+#=> false
+
+## Fails verification if the tag part of the ID is tampered with
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+tampered_id = id.dup
+idx = tampered_id.length - 1
+tampered_id[idx] = (tampered_id[idx] == 'a' ? 'b' : 'a') # Flip the last character
+Familia::VerifiableIdentifier.verified_identifier?(tampered_id)
+#=> false
+
+## Works correctly with a different base (hexadecimal)
+id_hex = Familia::VerifiableIdentifier.generate_verifiable_id(16)
+Familia::VerifiableIdentifier.verified_identifier?(id_hex, 16)
+#=> true
+
+## Base 16 ID has the correct hex length (64 random + 16 tag = 80 chars)
+id_hex = Familia::VerifiableIdentifier.generate_verifiable_id(16)
+id_hex.length
+#=> 80
+
+# --- Plausibility Checks ---
+
+## A genuinely generated ID is plausible
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+Familia::VerifiableIdentifier.plausible_identifier?(id)
+#=> true
+
+## A well-formed but fake ID is still plausible
+# A string of the correct length (62 for base 36) and charset is plausible
+total_bits = (Familia::VerifiableIdentifier::RANDOM_HEX_LENGTH + Familia::VerifiableIdentifier::TAG_HEX_LENGTH) * 4
+fake_id = 'a' * Familia::SecureIdentifier.min_length_for_bits(total_bits, 36)
+Familia::VerifiableIdentifier.plausible_identifier?(fake_id)
+#=> true
+
+## Fails plausibility check if too short
+short_id = 'a' * 60
+Familia::VerifiableIdentifier.plausible_identifier?(short_id)
+#=> false
+
+## Fails plausibility check if too long
+long_id = 'a' * 66
+Familia::VerifiableIdentifier.plausible_identifier?(long_id)
+#=> false
+
+## Fails plausibility check for invalid characters
+invalid_char_id = 'a' * 61 + '+'
+Familia::VerifiableIdentifier.plausible_identifier?(invalid_char_id)
+#=> false
+
+## Fails plausibility check for nil input
+Familia::VerifiableIdentifier.plausible_identifier?(nil)
+#=> false
+
+# --- Scoped Identifier Generation and Verification ---
+
+## Scoped identifier generation produces different results than unscoped
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+unscoped_id = Familia::VerifiableIdentifier.generate_verifiable_id
+scoped_id != unscoped_id
+#=> true
+
+## Scoped identifiers verify successfully with correct scope
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+Familia::VerifiableIdentifier.verified_identifier?(scoped_id, scope: "example.com")
+#=> true
+
+## Scoped identifiers fail verification with wrong scope
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+Familia::VerifiableIdentifier.verified_identifier?(scoped_id, scope: "different.com")
+#=> false
+
+## Scoped identifiers fail verification without scope parameter
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+Familia::VerifiableIdentifier.verified_identifier?(scoped_id)
+#=> false
+
+## Unscoped identifiers fail verification with scope parameter
+unscoped_id = Familia::VerifiableIdentifier.generate_verifiable_id
+Familia::VerifiableIdentifier.verified_identifier?(unscoped_id, scope: "example.com")
+#=> false
+
+## Empty string scope produces different identifier than nil scope
+id_nil = Familia::VerifiableIdentifier.generate_verifiable_id(scope: nil)
+id_empty = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "")
+id_nil != id_empty
+#=> true
+
+## Empty string scope verifies correctly
+id_empty = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "")
+Familia::VerifiableIdentifier.verified_identifier?(id_empty, scope: "")
+#=> true
+
+## Short scope values work correctly
+id_short = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "a")
+Familia::VerifiableIdentifier.verified_identifier?(id_short, scope: "a")
+#=> true
+
+## Long scope values work correctly
+long_scope = "x" * 1000
+id_long = Familia::VerifiableIdentifier.generate_verifiable_id(scope: long_scope)
+Familia::VerifiableIdentifier.verified_identifier?(id_long, scope: long_scope)
+#=> true
+
+## Unicode scope values work correctly
+unicode_scope = "测试🔒🔑"
+id_unicode = Familia::VerifiableIdentifier.generate_verifiable_id(scope: unicode_scope)
+Familia::VerifiableIdentifier.verified_identifier?(id_unicode, scope: unicode_scope)
+#=> true
+
+## Scoped identifiers work with different bases
+id_hex = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "test", base: 16)
+Familia::VerifiableIdentifier.verified_identifier?(id_hex, scope: "test", base: 16)
+#=> true
+
+## Backward compatibility: existing method signatures still work
+id = Familia::VerifiableIdentifier.generate_verifiable_id(36)
+Familia::VerifiableIdentifier.verified_identifier?(id, 36)
+#=> true
+
+## Mixed parameter styles work correctly
+id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "test", base: 16)
+Familia::VerifiableIdentifier.verified_identifier?(id, scope: "test", base: 16)
+#=> true