Module: DurableHuggingfaceHub::Utils::Auth

Defined in:
lib/durable_huggingface_hub/utils/auth.rb

Overview

Authentication token management utilities.

This module provides functions for retrieving, storing, and managing HuggingFace authentication tokens.

Constant Summary collapse

TOKEN_FILE_PERMISSIONS =

File permissions for token storage (owner read/write only)

0o600

Class Method Summary collapse

Class Method Details

.delete_token_file ⇒ Boolean

Deletes the token file.

Returns:

  • (Boolean) —

    True if file was deleted, false if it didn’t exist



98
99
100
101
102
103
104
105
106
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 98

def self.delete_token_file
  token_path = get_token_path
  return false unless token_path.exist?

  token_path.delete
  true
rescue Errno::EACCES, Errno::ENOENT
  false
end

.get_token(token: nil) ⇒ String?

Retrieves the authentication token from multiple sources.

Priority order:

  1. Explicitly provided token parameter

  2. HF_TOKEN environment variable

  3. HUGGING_FACE_HUB_TOKEN environment variable

  4. Token file (~/.cache/huggingface/token)

Examples:

Explicit token

Auth.get_token(token: "hf_...")

From environment or file

Auth.get_token  # Checks ENV then file

Parameters:

  • token (String, nil) (defaults to: nil) —

    Explicitly provided token

Returns:

  • (String, nil) —

    Authentication token or nil if not found



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 32

def self.get_token(token: nil)
  # Priority 1: Explicit parameter
  return token if token && !token.empty?

  # Priority 2: HF_TOKEN environment variable
  env_token = ENV["HF_TOKEN"]
  return env_token if env_token && !env_token.empty?

  # Priority 3: HUGGING_FACE_HUB_TOKEN environment variable
  legacy_token = ENV["HUGGING_FACE_HUB_TOKEN"]
  return legacy_token if legacy_token && !legacy_token.empty?

  # Priority 4: Token file
  read_token_from_file
end

.get_token!(token: nil) ⇒ String

Retrieves a token and raises an error if not found.

Examples:

token = Auth.get_token!  # Raises if not found

Parameters:

  • token (String, nil) (defaults to: nil) —

    Explicitly provided token

Returns:

  • (String) —

    Authentication token

Raises:



141
142
143
144
145
146
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 141

def self.get_token!(token: nil)
  result = get_token(token: token)
  return result if result

  raise LocalTokenNotFoundError.new
end

.get_token_path ⇒ Pathname

Returns the path to the token file.

Returns:

  • (Pathname) —

    Path to token file



111
112
113
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 111

def self.get_token_path
  Configuration.instance.token_path
end

.mask_token(token) ⇒ String

Masks a token for safe display.

Shows first 7 characters and last 4 characters, masking the middle.

Examples:

Auth.mask_token("hf_abc123def456ghi789")
# => "hf_abc1...h789"

Parameters:

  • token (String) —

    Token to mask

Returns:

  • (String) —

    Masked token



158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 158

def self.mask_token(token)
  return "" if token.nil? || token.empty?
  return token if token.length <= 11

  if token.length <= 15
    prefix = token[0, 4]
    suffix = token[-1]
    "#{prefix}...#{suffix}"
  else
    prefix = token[0, 7]
    suffix = token[-4..]
    "#{prefix}...#{suffix}"
  end
end

.read_token_from_file ⇒ String?

Reads the authentication token from the token file.

Returns:

  • (String, nil) —

    Token from file or nil if not found



51
52
53
54
55
56
57
58
59
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 51

def self.read_token_from_file
  token_path = get_token_path
  return nil unless File.exist?(token_path)

  token = File.read(token_path).strip
  token.empty? ? nil : token
rescue Errno::EACCES, Errno::ENOENT
  nil
end

.valid_token_format?(token) ⇒ Boolean

Validates a token format.

HuggingFace tokens typically start with “hf_” and are alphanumeric.

Examples:

Auth.valid_token_format?("hf_abc123")  # => true
Auth.valid_token_format?("invalid")     # => false

Parameters:

  • token (String) —

    Token to validate

Returns:

  • (Boolean) —

    True if token format appears valid



125
126
127
128
129
130
131
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 125

def self.valid_token_format?(token)
  return false if token.nil? || token.empty?

  # HuggingFace tokens start with "hf_" followed by alphanumeric characters
  # Minimum reasonable length is around 10 characters
  token.match?(/\Ahf_[A-Za-z0-9_-]{8,}\z/)
end

.write_token_to_file(token) ⇒ Boolean

Writes the authentication token to the token file.

Creates the cache directory if it doesn’t exist and sets appropriate file permissions for security.

Examples:

Auth.write_token_to_file("hf_...")

Parameters:

  • token (String) —

    Token to store

Returns:

  • (Boolean) —

    True if successful

Raises:

  • (IOError) —

    If unable to write token



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/durable_huggingface_hub/utils/auth.rb', line 72

def self.write_token_to_file(token)
  token_path = get_token_path

  # Ensure cache directory exists
  token_path.dirname.mkpath unless token_path.dirname.exist?

  # Write token atomically
  temp_path = Pathname.new("#{token_path}.tmp")
  temp_path.write(token)

  # Set restrictive permissions before moving
  File.chmod(TOKEN_FILE_PERMISSIONS, temp_path)

  # Atomic move
  File.rename(temp_path, token_path)

  true
rescue => e
  # Clean up temp file if it exists
  temp_path&.delete if temp_path&.exist?
  raise IOError, "Failed to write token: #{e.message}"
end