Class: Cybertrain::Session

Inherits:
Object
  • Object
show all
Defined in:
cybertrain/session.rb

Overview

A cookie-store session: a flat Hash<String,String> that round-trips through an encrypted, base64-encoded cookie value. Design D8 restricts values to String – there is no marshalling format to smuggle other types through, so nothing else needs to be ruled out at the type level.

Controller#session in an action. Keys and values are Strings (a Symbol key is its name; a value is stored as value.to_s, so session[:user_id] = 5 reads back as "5").

The cookie is encrypted and authenticated with AES-256-GCM (spec section 5.1, as Rails’ cookie store), under a key derived from secret_key_base (Crypto.derive_key with the label "cybertrain session") and with "session" as the additional data: the client can neither read it nor change it. A cookie that does not decode, authenticate or parse (a changed, truncated or forged one, one sealed for another cookie, one under another secret, a 0.4 signed cookie) loads as an empty session, and so does one over 4096 bytes, without being decrypted. A session whose cookie would pass 4096 bytes raises CookieOverflow when SessionStore writes it: nothing is cut short. It is sent only when the session changed, as _cybertrain_session with Path=/; HttpOnly; SameSite=Lax, Secure in production or under force_ssl (Config#secure_cookies?) and a two-week Max-Age (the name, the Max-Age and Secure are Config settings), unless #stamp_lifetime! gave the session its own lifetime or made it a browser-session cookie. "_csrf_token", "_flash", "_issued_at", "_lifetime" and "_browser" are the framework’s keys.

Examples:

session[:user_id] = user.id
User.find(session[:user_id]) if session.key?(:user_id)
session.delete(:user_id)

Defined Under Namespace

Classes: CookieOverflow

Instance Method Summary collapse

Instance Method Details

#[](key) ⇒ String?

Parameters:

  • key (String, Symbol)

Returns:

  • (String, nil)


66
67
68
# File 'cybertrain/session.rb', line 66

def [](key)
  @data[key.to_s]
end

#[]=(key, value) ⇒ String

Parameters:

  • key (String, Symbol)
  • value (Object) —

    stored as value.to_s

Returns:

  • (String)


74
75
76
77
78
79
# File 'cybertrain/session.rb', line 74

def []=(key, value)
  k = key.to_s
  v = value.to_s
  @changed = true unless @data[k] == v
  @data[k] = v
end

#browser_session? ⇒ Boolean

Whether #stamp_lifetime! made this a browser-session cookie (no Max-Age, no Expires).

Returns:

  • (Boolean)


247
248
249
# File 'cybertrain/session.rb', line 247

def browser_session?
  @data[BROWSER_KEY] == "1"
end

#clear ⇒ Object

Empties the session, the CSRF token included, so forms rendered before it no longer submit (403). Use it on sign-out.



106
107
108
109
# File 'cybertrain/session.rb', line 106

def clear
  @changed = true unless @data.empty?
  @data.clear
end

#csrf_token! ⇒ String

Returns this session’s CSRF token, minting and storing one the first time it is asked for. Forms built with form_with and button_to already carry it; send it yourself as the X-CSRF-Token header or an authenticity_token parameter from JavaScript or a hand-written form.

This is a typed instance method (rather than a module method taking a Session argument) so Spinel resolves self statically at every call site: a free function taking session as a plain parameter widens it to an untyped poly value once it is called through a real SessionStore -> Context chain, and then session[TOKEN_KEY] = token silently does nothing (tests: test/csrf_chain.rb, test/csrf_conditional.rb).

Returns:

  • (String)


137
138
139
140
141
142
143
144
# File 'cybertrain/session.rb', line 137

def csrf_token!
  token = @data[CSRF_TOKEN_KEY]
  if token.nil? || token.empty?
    token = Crypto.random_token
    self[CSRF_TOKEN_KEY] = token
  end
  token
end

#delete(key) ⇒ String?

Returns the removed value.

Parameters:

  • key (String, Symbol)

Returns:

  • (String, nil) —

    the removed value



84
85
86
87
88
# File 'cybertrain/session.rb', line 84

def delete(key)
  k = key.to_s
  @changed = true if @data.key?(k)
  @data.delete(k)
end

#key?(key) ⇒ Boolean

Parameters:

  • key (String, Symbol)

Returns:

  • (Boolean)


93
94
95
# File 'cybertrain/session.rb', line 93

def key?(key)
  @data.key?(key.to_s)
end

#keys ⇒ Array<String>

Returns:

  • (Array<String>)


99
100
101
# File 'cybertrain/session.rb', line 99

def keys
  @data.keys
end

#lifetime_limit ⇒ Integer

The lifetime #stamp_lifetime! gave this session, in seconds, or 0 when it has none (Config#session_absolute_max_age then applies).

Returns:



239
240
241
# File 'cybertrain/session.rb', line 239

def lifetime_limit
  Session.epoch_seconds(@data[LIFETIME_KEY])
end

#restart_lifetime! ⇒ nil

Restarts the lifetime: SessionStore stamps the time of this request when it writes the cookie, so the session lasts its full lifetime from now. It also clears a #stamp_lifetime! stamp, so the session falls back to Config#session_absolute_max_age and Config#session_max_age. Call it at sign-in (the generated start_new_session_for does), so that a visitor who browsed for a while before signing in is not signed out early.

The order at sign-in is: restart_lifetime! first, then stamp_lifetime!. A restart after a stamp erases that stamp.

Returns:

  • (nil)


195
196
197
198
199
200
# File 'cybertrain/session.rb', line 195

def restart_lifetime!
  delete(ISSUED_AT_KEY)
  delete(LIFETIME_KEY)
  delete(BROWSER_KEY)
  nil
end

#stamp_lifetime!(seconds, persistent) ⇒ nil

Gives this session its own lifetime, seconds long, in place of Config#session_absolute_max_age. SessionStore ends the session once that many seconds have passed since its start (#issued_at). With persistent true, the cookie’s Max-Age is the time left, even past Config#session_max_age (“remember me” checked). With persistent false, the cookie has no Max-Age and no Expires, so the browser drops it when it closes (“remember me” unchecked). seconds 0 or less removes the lifetime and keeps the browser-session choice.

It does not move the start. Call #restart_lifetime! first, as the generated start_new_session_for does: the restart clears the old start and any old stamp, and this call then writes the new stamp, which counts from this request. A stamp without a restart counts from the start the cookie already records.

Parameters:

  • seconds (Integer)
  • persistent (Boolean)

Returns:

  • (nil)


221
222
223
224
225
226
227
228
229
230
231
232
233
# File 'cybertrain/session.rb', line 221

def stamp_lifetime!(seconds, persistent)
  if seconds > 0
    self[LIFETIME_KEY] = seconds
  else
    delete(LIFETIME_KEY)
  end
  if persistent
    delete(BROWSER_KEY)
  else
    self[BROWSER_KEY] = "1"
  end
  nil
end

#to_h ⇒ Hash{String => String}

Returns a copy.

Returns:

  • (Hash{String => String}) —

    a copy



113
114
115
# File 'cybertrain/session.rb', line 113

def to_h
  @data.dup
end