Quick start

Let middleware own the auth routes

If your app uses Wisp or Mist, start here. Add core, a provider strategy, and the middleware package for your server layer. Use the advanced core path only when your app needs to own routing, session storage, and callback handling directly.

Vestibule is not yet 1.0, so install it from GitHub using the moving vestibule-v0.0 tag. Gleam 1.18 or later is required because companion packages use git path dependencies.

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

Route request and callback phases

Register strategies once, initialize the state store once, then pass request and callback routes to the middleware.

What to notice: the request route starts the redirect and stores transient callback data; the callback route returns an auth result only after state and PKCE checks pass.

import gleam/http
import wisp
import vestibule/config
import vestibule/registry
import vestibule/state_store
import vestibule_wisp
import vestibule_github

let assert Ok(registry) =
  registry.new()
  |> registry.register(
    vestibule_github.strategy(),
    config.new(
      client_id: "client_id",
      redirect_uri: "http://localhost:8000/auth/github/callback",
      auth: config.ClientSecret("client_secret"),
    ),
  )

let assert Ok(store) = state_store.try_init()

case wisp.path_segments(req), req.method {
  ["auth", provider], http.Get ->
    vestibule_wisp.request_phase(
      req,
      registry,
      provider,
      store,
      authorize_options: config.authorize_options(),
    )

  ["auth", provider, "callback"], http.Get
  | ["auth", provider, "callback"], http.Post ->
    case vestibule_wisp.callback_phase_auth_result(req, registry, provider, store) {
      // auth.uid(auth) identifies the user: map it to an account, then
      // start your own session.
      Ok(auth) -> start_session(auth)

      // Benign: a stale tab, back button, or already-used callback.
      Error(vestibule_wisp.SessionUnavailable) ->
        wisp.redirect("/login?error=expired")

      // Everything else (forged state, provider rejection, bad params).
      Error(_) ->
        wisp.redirect("/login?error=auth")
    }

  _, _ ->
    wisp.not_found()
}

• Initialize the state store once. Reusing it lets middleware bind callback data to the user flow.

• Delete callback data after success or failure. The middleware consumes one-time state; your app should not reuse a failed callback.

• Map auth.uid(auth) to your own account. Vestibule authenticates the provider identity; your app owns sessions.