Class: Cybertrain::Session
- Inherits:
-
Object
- Object
- Cybertrain::Session
- 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.
Defined Under Namespace
Classes: CookieOverflow
Instance Method Summary collapse
-
#[](key) ⇒ String?
-
#[]=(key, value) ⇒ String
-
#browser_session? ⇒ Boolean
Whether #stamp_lifetime! made this a browser-session cookie (no Max-Age, no Expires).
-
#clear ⇒ Object
Empties the session, the CSRF token included, so forms rendered before it no longer submit (403).
-
#csrf_token! ⇒ String
Returns this session’s CSRF token, minting and storing one the first time it is asked for.
-
#delete(key) ⇒ String?
The removed value.
-
#key?(key) ⇒ Boolean
-
#keys ⇒ Array<String>
-
#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).
-
#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.
-
#stamp_lifetime!(seconds, persistent) ⇒ nil
Gives this session its own lifetime,
secondslong, in place ofConfig#session_absolute_max_age. -
#to_h ⇒ Hash{String => String}
A copy.
Instance Method Details
#[](key) ⇒ String?
66 67 68 |
# File 'cybertrain/session.rb', line 66 def [](key) @data[key.to_s] end |
#[]=(key, value) ⇒ 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).
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).
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.
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
93 94 95 |
# File 'cybertrain/session.rb', line 93 def key?(key) @data.key?(key.to_s) end |
#keys ⇒ 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).
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.
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.
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.
113 114 115 |
# File 'cybertrain/session.rb', line 113 def to_h @data.dup end |