Module: Familia::VerifiableIdentifier

Extended by:
SecureIdentifier
Defined in:
lib/familia/verifiable_identifier.rb

Overview

Creates and verifies identifiers that contain an embedded HMAC signature, allowing for stateless verification of an identifier's authenticity.

Constant Summary collapse

RANDOM_HEX_LENGTH =

The length of the random part of the ID in hex characters (256 bits).

64
TAG_HEX_LENGTH =

The length of the HMAC tag in hex characters (64 bits). 64 bits is strong enough to prevent forgery (1 in 18 quintillion chance).

16

Class Method Summary collapse

Methods included from SecureIdentifier

generate_id, generate_lite_id, generate_trace_id, shorten_to_trace_id, truncate_hex

Class Method Details

.generate_verifiable_id(base_or_scope = nil, scope: nil, base: 36) ⇒ String

Generates a verifiable, base-36 encoded identifier.

The final identifier contains a 256-bit random component and a 64-bit authentication tag.

Parameters:

  • base (Integer) (defaults to: 36) —

    The base for encoding the output string.

Returns:

  • (String) —

    A verifiable, signed identifier.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/familia/verifiable_identifier.rb', line 93

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_id from the SecureIdentifier module.
  random_hex = generate_id(16)
  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

.plausible_identifier?(identifier_str, base = 36) ⇒ Boolean

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.

Parameters:

  • identifier_str (String) —

    The identifier string to check.

  • base (Integer) (defaults to: 36) —

    The base of the input string.

Returns:

  • (Boolean) —

    True if the identifier has a valid format, false otherwise.



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/familia/verifiable_identifier.rb', line 152

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

.reset_secret_key! ⇒ nil

Clears the memoized secret so the next secret_key call re-reads the environment. Intended for test suites that swap the configured secret (or exercise the missing-secret path) within a single process. Production code never needs this: the secret is fixed for a deployment, and rotating it requires a restart (and invalidates every previously generated identifier).

Returns:

  • (nil) 


76
77
78
 
# File 'lib/familia/verifiable_identifier.rb', line 76

def self.reset_secret_key!
  @secret_key = nil
end

.secret_key ⇒ String

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.
  • No committed fallback: There is intentionally NO default. A hardcoded secret in source would be public knowledge, letting anyone forge valid identifiers (issue #310, S1). A missing OR blank secret raises -- but lazily, the first time an identifier is actually minted or verified, so merely requiring this file (e.g. for introspection) never blows up.

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.

Examples:

Generating and Setting the Key

1. Generate a new secure key in your terminal:
   $ openssl rand -hex 32
   > <64 hex characters>

2. Set it as an environment variable in your production environment:
   export VERIFIABLE_ID_HMAC_SECRET="<the generated value>"

Returns:

  • (String) —

    the configured secret

Raises:

  • (KeyError) —

    if VERIFIABLE_ID_HMAC_SECRET is unset or blank



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/familia/verifiable_identifier.rb', line 45

def self.secret_key
  # Treat a present-but-blank value the same as absent. ENV.fetch only fires
  # its default block when the key is missing, so a blank
  # VERIFIABLE_ID_HMAC_SECRET="" (or a whitespace-only "   ", e.g. from a YAML
  # parser or templating tool) would otherwise sail through and HMAC every
  # identifier under an effectively empty key -- silently reintroducing the
  # forgeable-key weakness #310 S1 closed. This bites container setups that
  # inject `VERIFIABLE_ID_HMAC_SECRET=${VERIFIABLE_ID_HMAC_SECRET:-}`, which
  # supplies an empty string whenever the outer variable is unset. strip.empty?
  # fails closed on nil, "", and all-whitespace alike.
  @secret_key ||= begin
    value = ENV.fetch('VERIFIABLE_ID_HMAC_SECRET', nil)
    if value.nil? || value.strip.empty?
      raise KeyError, <<~MSG.strip
        VERIFIABLE_ID_HMAC_SECRET is not set (or is blank). Familia::VerifiableIdentifier
        refuses to fall back to a committed default or empty secret -- a known or empty
        key would let anyone forge valid identifiers. Generate one with `openssl rand -hex
        32` and export it before generating or verifying identifiers.
      MSG
    end
    value
  end
end

.verified_identifier?(verifiable_id, base_or_scope = nil, scope: nil, base: 36) ⇒ Boolean

Verifies the authenticity of a given identifier using a timing-safe comparison.

Parameters:

  • verifiable_id (String) —

    The identifier string to check.

  • base (Integer) (defaults to: 36) —

    The base of the input string.

Returns:

  • (Boolean) —

    True if the identifier is authentic, false otherwise.



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/familia/verifiable_identifier.rb', line 121

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