Urchin.Auth.Plug (Urchin v0.2.0)

Copy Markdown View Source

A Plug that enforces a valid OAuth 2.1 bearer token on every request.

Mount it ahead of the MCP transport in a Plug/Phoenix pipeline:

plug Urchin.Auth.Metadata, auth: auth
plug Urchin.Auth.Plug, auth: auth
forward "/mcp", to: Urchin.Transport.StreamableHTTP, init_opts: [server: MyServer]

Most servers instead pass :auth directly to Urchin.Transport.StreamableHTTP (or Urchin.start_link/2), which runs the very same check internally. This standalone plug is for custom pipelines that want authorization as an explicit pipeline stage.

On success the validated Urchin.Auth.Claims are stored under conn.private[:urchin_auth]; the transport reads that key and surfaces it to handlers as ctx.auth, regardless of whether this plug or the transport performed the check. On failure the plug sends the appropriate 401/403/400/500 OAuth error with a WWW-Authenticate challenge and halts the pipeline.

Options

Summary

Functions

authenticate(conn, auth)

The shared authentication seam used by this plug and Urchin.Transport.StreamableHTTP.

fetch_claims(conn)

Returns the validated claims stored on the connection, or nil.

Functions

authenticate(conn, auth)

@spec authenticate(Plug.Conn.t(), Urchin.Auth.t() | nil) ::
  {:ok, Plug.Conn.t()} | {:sent, Plug.Conn.t()}

The shared authentication seam used by this plug and Urchin.Transport.StreamableHTTP.

Returns {:ok, conn} with the validated claims stored in conn.private[:urchin_auth], or {:sent, conn} after sending the OAuth error challenge. When auth is nil (authorization disabled) the connection passes through untouched.

fetch_claims(conn)

@spec fetch_claims(Plug.Conn.t()) :: Urchin.Auth.Claims.t() | nil

Returns the validated claims stored on the connection, or nil.