Module: Cybertrain::Token

Defined in:
cybertrain/token.rb

Overview

Signed, expiring tokens (see the file comment).

Class Method Summary collapse

Class Method Details

.id_from(token) ⇒ Integer

The id a token carries, read without verifying it (to find the record whose bound_to valid? then checks). 0 for a token that is not "<id>--<expires>--<64 lowercase hex>", each number 1 to 18 digits with no leading zero.

Examples:

Cybertrain::Token.id_from(params[:token].to_s)   # => 7, or 0

Parameters:

  • token (String)

Returns:



91
92
93
94
95
96
# File 'cybertrain/token.rb', line 91

def self.id_from(token)
  fields = Token.token_fields(token)
  return 0 if fields.empty?

  Token.digits_value(fields[0])
end

.issue(purpose, id, expires_in, bound_to, now = Clock.now.to_i) ⇒ String

A token for the record id, for purpose, valid for expires_in seconds from now and while bound_to keeps its value.

Examples:

Cybertrain::Token.issue("password_reset", user.id, 15 * 60, user.password_digest)
# => "7--1762861200--3f9c..." (64 hex digits at the end)

Parameters:

  • purpose (String) —

    what the token is for; non-empty, no :

  • id (Integer) —

    the record’s id, 1 to MAX_ID

  • expires_in (Integer) —

    seconds, positive

  • bound_to (String) —

    a value the token stops verifying without (the password digest, the address being confirmed)

  • now (Integer) (defaults to: Clock.now.to_i) —

    the current Unix time

Returns:

  • (String)

Raises:

  • (ArgumentError) —

    for a purpose, id or lifetime the token could not carry, or when Cybertrain.config.secret_key_base is empty



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
# File 'cybertrain/token.rb', line 55

def self.issue(purpose, id, expires_in, bound_to, now = Clock.now.to_i)
  label = purpose.to_s
  unless Token.purpose_ok?(label)
    message = "the token purpose must be non-empty and contain no \":\""
    raise ArgumentError, message
  end
  if id < 1 || id > MAX_ID
    message = "the token id must be from 1 to #{MAX_ID} (got #{id})"
    raise ArgumentError, message
  end
  if expires_in < 1
    message = "expires_in must be positive (got #{expires_in})"
    raise ArgumentError, message
  end
  expires = now + expires_in
  if expires < 1 || expires > MAX_ID
    message = "the token expiry must be from 1 to #{MAX_ID} (got #{expires})"
    raise ArgumentError, message
  end
  id_text = id.to_s
  expires_text = expires.to_s
  mac = Token.token_mac(label, id_text, expires_text, bound_to.to_s)
  out = String.new
  out << id_text << "--" << expires_text << "--" << mac
  out
end

.valid?(token, purpose, bound_to, now = Clock.now.to_i) ⇒ Boolean

Whether token was issued for purpose and bound_to under the current secret_key_base and has not expired at now: the MAC is compared first, in constant time (Crypto.secure_compare), then the expiry (now must be before it). A malformed token answers false.

Examples:

Cybertrain::Token.valid?(token, "password_reset", user.password_digest)

Parameters:

  • token (String)
  • purpose (String)
  • bound_to (String)
  • now (Integer) (defaults to: Clock.now.to_i) —

    the current Unix time

Returns:

  • (Boolean)

Raises:

  • (ArgumentError) —

    when Cybertrain.config.secret_key_base is empty



111
112
113
114
115
116
117
118
119
120
121
# File 'cybertrain/token.rb', line 111

def self.valid?(token, purpose, bound_to, now = Clock.now.to_i)
  label = purpose.to_s
  fields = Token.token_fields(token)
  return false if fields.empty?
  return false unless Token.purpose_ok?(label)

  expected = Token.token_mac(label, fields[0], fields[1], bound_to.to_s)
  return false unless Crypto.secure_compare(fields[2], expected)

  now < Token.digits_value(fields[1])
end