Login & sessions (web auth)

Engine v0.5.5+.

Web auth in Synsema is a small set of primitives, each with the safe choice as the default. No framework, no middleware — a login flow is a handful of lines in a serve block.

-- Doc example: web auth primitives — password hashing, JWT, TOTP and the CSPRNG.
-- (Cookies/sessions ride on `serve`, which doesn't terminate — the serve page shows
-- the full login flow; this doctest asserts the primitives that flow is built from.)
intent: "doc example: web auth primitives"
require random

let phc be password_hash("hunter2")
print("phc → " + slice(phc, 0, 10) + "…  verify → " + text(password_verify("hunter2", phc)))
print("session id → " + token())

test "password_hash gives a PHC string; verify is strict, wrong password is false"
    let phc be password_hash("hunter2")
    assert(starts_with(phc, "$argon2id$"))
    assert_eq(password_verify("hunter2", phc), true)
    assert_eq(password_verify("wrong", phc), false)

test "token() is 43 chars of base64url — 32 CSPRNG bytes, fine for session ids"
    assert_eq(length(token()), 43)
    assert_eq(length(random_bytes(16)), 16)

test "jwt: sign/verify roundtrip; wrong key or tampering → nothing"
    let tok be jwt_sign({"sub": "u1", "role": "admin"}, "k", {"expires_in": 3600})
    let claims be jwt_verify(tok, "k")
    assert_eq(claims.sub, "u1")
    assert(claims.exp > claims.iat)
    assert_eq(jwt_verify(tok, "other-key"), nothing)
    assert_eq(jwt_verify(tok + "x", "k"), nothing)

test "totp matches the RFC 6238 vector and verifies within the window"
    let seed be bytes("12345678901234567890")
    assert_eq(totp(seed, {"digits": 8, "at": 59}), "94287082")
    assert_eq(totp_verify(seed, "94287082", {"digits": 8, "at": 59}), true)
    assert_eq(totp_verify(seed, "00000000", {"digits": 8, "at": 59}), false)

test "base64url differs from base64: URL-safe alphabet, no padding"
    assert_eq(decode(bytes([251, 255]), "base64url"), "-_8")
    assert_eq(decode(bytes([251, 255]), "base64"), "+/8=")
    assert_eq(bytes("-_8", "base64url"), bytes([251, 255]))

Session cookies

require serve(8080)
require random                          -- gates token()/random_bytes

task check_session(token, request)      -- 2 params → also receives the request
    let sid be request.cookies.sid
    when sid == nothing
        give nothing                    -- nothing → 401
    give state_get("sess:" + sid)       -- the value lands in request.user

serve on 8080
    auth with check_session
    route "POST /login"
        when password_verify(request.json.pw, stored_phc)
            let sid be token()
            state_set("sess:" + sid, {"name": request.json.user})
            give set_cookie(ok({"ok": true}), "sid", sid, {"max_age": 86400})
        give fail(401, "bad credentials")
    route "GET /me" requires auth
        give request.user
    route "POST /logout" requires auth
        give clear_cookie(ok({"bye": true}), "sid")

• set_cookie(resp, name, value, opts?) wraps any response value. Defaults are the safe ones: Path=/; Secure; HttpOnly; SameSite=Lax. Opts: max_age (seconds), path, domain, secure, http_only, same_site ("Strict"|"Lax"|"None" — None demands secure: true).
• clear_cookie(resp, name, opts?) — path/domain must match the ones used at set time.
• request.cookies — incoming cookies as a map (undecoded; no header → empty map).
• with_header(resp, name, value) — any extra response header; calls accumulate, repeated names emit separate lines (that's what multiple Set-Cookie needs). Framing/hop-by-hop headers and CR/LF are hard errors — header injection can't be written.
• An auth task with 1 parameter keeps the historical contract (bearer token only).

Passwords, tokens, 2FA

require random

let phc be password_hash(pw)            -- "$argon2id$…" (OWASP params) — store as-is
password_verify(pw, phc)                -- bool; corrupt/unknown hash → error, not false

let sid be token()                      -- 32 CSPRNG bytes as base64url (43 chars)
let tok be jwt_sign({"sub": id}, secret("JWT_KEY"), {"expires_in": 3600})
jwt_verify(tok, secret("JWT_KEY"))      -- claims map, or nothing on ANY failure

let seed be random_bytes(20)            -- TOTP enrolment
totp(seed)                              -- current 6-digit code (sha1/30s profile)
totp_verify(seed, submitted)            -- ±1 period window, constant-time

• random_bytes/token need require random — the same deny-by-default gate as random(). The pure transforms (password_hash, jwt_, totp) need no capability.
• jwt_verify pins the algorithm to HS256 — an alg: "none" or RS256 token is rejected, and every failure (signature, exp, malformed) is the same nothing. RS256/ES256 (third-party OIDC) is not supported yet.
• The TOTP secret is bytes: a base32 secret from a QR app decodes with bytes(s, "base32").
• CSRF for cookie-based POSTs: issue token() per session, embed it in the form, compare with constant_time_eq in the handler.
• Never store live API keys as-is: store sha256(key) and compare hashes.

Key/password arguments accept a sealed secret, text or bytes.