Mist middleware

vestibule_mist

Plain Mist request and callback routing with HMAC-SHA256 signed session cookies and the shared Vestibule state store.

When to use it

Use Mist middleware if your app runs directly on Mist and does not use Wisp.

Install

Vestibule packages are not available on Hex. Add them from GitHub with the moving v0 tag. Use Gleam 1.18 or later because companion packages use Git path dependencies.

[dependencies]
vestibule = { git = "https://github.com/tylerbutler/vestibule.git", ref = "v0" }
vestibule_mist = { git = "https://github.com/tylerbutler/vestibule.git", ref = "v0", path = "packages/vestibule_mist" }
vestibule_github = { git = "https://github.com/tylerbutler/vestibule.git", ref = "v0", path = "packages/vestibule_github" }

Setup

Load a high-entropy secret key base from configuration or a secrets manager.
Create Options with vestibule_mist.new_options(secret_key_base).
Initialize the shared state store once per BEAM VM.
Dispatch request and callback paths from your Mist handler.

Usage

import gleam/http
import gleam/http/request.{type Request}
import gleam/http/response.{type Response}
import mist.{type Connection, type ResponseData}
import vestibule/config
import vestibule/state_store
import vestibule_mist

let assert Ok(store) = state_store.create()
let assert Ok(options) = vestibule_mist.new_options(secret_key_base)

fn handle_request(http_request: Request(Connection)) -> Response(ResponseData) {
  case request.path_segments(http_request), http_request.method {
    ["auth", provider], http.Get ->
      vestibule_mist.request_phase(
        http_request,
        registry,
        provider,
        store,
        authorize_options: config.authorize_options(),
        options: options,
      )

    ["auth", provider, "callback"], http.Get
    | ["auth", provider, "callback"], http.Post ->
      vestibule_mist.callback_phase(
        http_request,
        registry,
        provider,
        store,
        options,
        on_success,
      )

    _, _ ->
      not_found()
  }
}

What Vestibule handles

Applications must supply a secret. The package has no unsafe default secret.
Sets HttpOnly, SameSite=Lax, Path=/, and Secure by default.
Supports GET and application/x-www-form-urlencoded POST callbacks.
Structured callback errors mirror the Wisp integration.

What you handle

Use with_cookie_security(AllowInsecure) only for local HTTP development.
A cookie-secret change invalidates OAuth callbacks that are in progress.