Iwf Guide

Iwf Guide

Markdown source

Sessions, Cookies, Flash, and CSRF

Iwf sessions are signed-cookie-backed. In normal apps the runner and render own the lifecycle: every controller receives a ControllerContext, handlers update session state through context helpers, and rendered responses commit the signed cookie.

1. Session Storage Contract

Iwf's built-in session store is the signed session cookie. Session entries, flash messages, the framework session identity, and the CSRF token are serialized into the cookie value and verified with the configured SessionConfig.secret on every request.

There is no implicit server-side session table in the framework runtime. If an application needs revocation, server-side invalidation, large session payloads, or audit trails, store those records in application tables and keep only stable identifiers in the signed session. Production applications must use a non-default secret and secure cookie settings.

2. SessionConfig

sessionConfig : SessionConfig
sessionConfig =
  secureSessionConfig sessionSecret

Session config controls:

  • cookie name
  • signing secret
  • Secure
  • HttpOnly
  • SameSite

Use secure session cookies in production.

The framework provides two canonical cookie profiles:

  • defaultSessionConfig and defaultCookieOptions are local-development defaults: Secure = False, HttpOnly = True, SameSite = "Lax", and the session secret is intentionally unsafe.
  • secureSessionConfig secret and secureCookieOptions are production defaults: Secure = True, HttpOnly = True, SameSite = "Lax", and the application provides the secret.

Production deployments should fail configuration validation when they use the development session secret or non-secure session cookies.

4. Reading And Writing Session Data

response : Response
response =
  commitContextSession context
    (putSession "theme" "dark")
    (seeOther "/settings")

Helpers:

  • lookupSession
  • putSession
  • deleteSession
  • commitContextSession

Most handlers do not need to commit a session directly. render, renderFragment, validation rendering, flash helpers, and auth helpers commit the session they return.

5. Controller Session Lifecycle

render and renderFragment commit the controller session so rendered forms and the signed session cookie stay in sync.

loginUserInContext, loginUserWithFlashInContext, and logoutUserInContext start a fresh signed session, rotate the framework session id, and rotate the CSRF token. This prevents a pre-authentication cookie value from being promoted unchanged into an authenticated session.

6. Raw Cookies

Use raw cookie helpers for feature-specific cookies:

  • lookupCookie
  • withCookie
  • clearCookie

Cookie values are URL encoded and decoded by the HTTP layer. Signed session-cookie verification is framework lifecycle plumbing. Import the advanced cookie/session modules only when writing framework integrations or low-level tests.

7. Flash Messages

Flash messages are session entries with a framework-owned prefix:

let session = flashNotice "Article published" oldSession
let session = flashError "Could not save article" oldSession

Read and clear:

let (notice, sessionAfterFlash) = takeFlash "notice" session

The default shell has a stable flash host outside #main-content. HTMX fragment responses can update the flash host out-of-band.

8. CSRF

Controller rendering injects the hidden field into non-GET forms:

settingsForm : ControllerContext -> Html
settingsForm context =
  <form method="post" action="/settings">
    <input name={settingsFormEmailField} type="email" />
    <button type="submit">Save</button>
  </form>

Low-level helpers:

  • csrfInput
  • putSessionCsrfToken
  • validateSessionCsrf

Validate submitted forms before mutating state. CSRF tokens live in the signed session and are posted back as hidden form fields added by render or renderFragment. Controller helpers validate against the session token with validateSessionCsrf; there is no static controller-level CSRF token.

Next

Read Authentication and Authorization.