Bond.sessions(app, options) keeps a small session in a cookie that Bond signs with HMAC-SHA256. There is no store on the server: the signature lets Bond see that the client did not change the cookie. A handler reads and changes the session as a map of text:

  • Bond.session(conn) is the session as a Map[String, String], empty for a visitor with none.
  • Bond.get_session(conn, "user") is one value, a plain error when it is not there (use unwrap_or or case, as with Bond.cookie).
  • Bond.set_session(conn, "user", "ana"), Bond.delete_session(conn, "user") and Bond.clear_session(conn) give a new Conn with the session changed, as Bond.status does. Keep the Conn they return.

The answer carries the new session in a Set-Cookie, and only when a handler changed it: a request that only reads sets no cookie. An empty session after a change (clear_session, or the last value deleted) deletes the cookie.

The options #

Bond.app() |> Bond.sessions(Bond.SessionOptions(secret: secret)) is the whole setup. secret is the only option you must give: at least 32 bytes (Bond checks the length, not that it is random). Make it once with OpenSSL.Random.hex(32), keep it in the environment or a file, and never put it in the source. The program stops at the call of sessions when an option is wrong (a short secret, an empty name, a max_age below 1, a same_site that is not Strict, Lax or None, or None without secure).

OptionDefault
secretthe key that signs the cookie
old_secrets[]keys that signed cookies before (see the rotation below)
name_bond_sessionthe name of the cookie
max_age1_209_600seconds that a session lasts (two weeks)
securefalseadds Secure: set it in production, over HTTPS
same_site"Lax""Strict", "Lax" or "None"
path, domain"/", ""those of the cookie

The cookie is always HttpOnly. In production use name: "__Host-session" with secure: true, the default path and no domain: a browser accepts a __Host- cookie only from a secure page for the exact host, so a sibling subdomain cannot plant a signed cookie with its own session (the first cookie of a name wins). Secure is off by default because a Secure cookie is dropped over plain HTTP, which breaks development.

The end date is inside the signed data, so a client that keeps an old cookie does not get a longer session. Every change writes a cookie that lasts max_age from then; a read does not extend it.

What is signed, and what is not #

The cookie is payload.signature, both in base64url. The signature covers the name of the cookie and the payload, with the secret. A cookie that is missing, malformed, changed, expired, or signed with a secret that Bond does not know is an empty session, never a 4xx.

The payload is not encrypted: anyone who has the cookie can read it. Keep an id or a name there, not a secret, and look up the rest on the server. A cookie over 3800 bytes would be dropped by browsers, so Bond makes that answer a 500 (through on_error) instead of sending it.

Log in with a new session: call clear_session before you set the user, so nothing of the earlier session is kept. A signed cookie cannot be revoked on the server before it expires: a logout deletes it in the visitor’s browser, but a copy stays valid until its max_age. Use a short max_age for what must end soon.

Rotating the secret #

Put the new secret in secret and the old one in old_secrets. Bond reads a cookie signed with any of them and writes it again with secret (and a new max_age) on the first request that has it, so a session in use outlives the rotation. Remove the old secret after max_age seconds.

Testing #

Testing.session_cookie(options, data) gives the name=value of a cookie signed as sessions would sign it, so a test of a route for logged-in users needs no login. It does not check the options as sessions does (a short secret, or a negative max_age, which gives an expired cookie, are accepted).

import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"

OPTIONS = Bond.SessionOptions(secret: "a-secret-of-at-least-32-bytes-ok")

def login(conn: Bond.Conn) -> Result[Bond.Conn]
  signed_in = Bond.set_session(Bond.clear_session(conn), "user", "ana")
  return ok(Bond.text(signed_in, 200, "welcome"))
end

def me(conn: Bond.Conn) -> Result[Bond.Conn]
  user = Bond.get_session(conn, "user").unwrap_or("nobody")
  return ok(Bond.text(conn, 200, "hello #{user}"))
end

def logout(conn: Bond.Conn) -> Result[Bond.Conn]
  return ok(Bond.text(Bond.clear_session(conn), 200, "bye"))
end

def main() -> Void
  app = (
    Bond.app()
    |> Bond.sessions(OPTIONS)
    |> Bond.get("/login", &login)
    |> Bond.get("/me", &me)
    |> Bond.get("/logout", &logout)
  )
  puts(Testing.text(Testing.request(app, "GET", "/me")).unwrap!)

  # The cookie of the answer goes back in the next request, as a browser does.
  answer = Testing.request(app, "GET", "/login")
  cookie = HTTP.header_values(answer.headers, "set-cookie").first.split(";").first
  headers = [HTTP.Header(name: "Cookie", value: cookie)]
  puts(Testing.text(Testing.request(app, "GET", "/me", headers)).unwrap!)

  # A visitor who is logged in, with no login in the test.
  made = Testing.session_cookie(OPTIONS, {"user": "bo"}).unwrap!
  puts(Testing.text(Testing.request(app, "GET", "/me", [HTTP.Header(name: "Cookie", value: made)])).unwrap!)

  # A changed cookie is an empty session.
  changed = "_bond_session=A" + cookie.split("=")[1].slice(1, 40) + ".AAAA"
  puts(Testing.text(Testing.request(app, "GET", "/me", [HTTP.Header(name: "Cookie", value: changed)])).unwrap!)

  gone = Testing.request(app, "GET", "/logout", headers)
  puts(HTTP.header_values(gone.headers, "set-cookie").first)
end
Output
hello nobody
hello ana
hello bo
hello nobody
_bond_session=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT

sessions adds a before and an after filter (see Filters), so call it before the filters that read the session. Without it, set_session changes the Conn and nothing is sent.