Butter Auth

What is Butter?#

Butter is an agent-first, distributed authentication architecture. Rather than installing an all-in-one npm package with black-box internals, rigid database schemas, and framework lock-in, Butter provides security-critical auth primitives and business logic that you copy directly into your own codebase and own completely.

Guided by Pilcrow's Auth Book and built with Effect, Butter stops at Flows—pure functional workflows returning typed Effects, completely decoupled from HTTP routing frameworks and UI libraries.

With coding agents now capable of generating and maintaining application code, you no longer need an auth dependency that attempts to abstract every database and framework under a single polymorphic model. Butter gives your agent the foundation it needs to build and maintain an auth system tailored directly to your application.

How It Works#

Butter structures authentication around a small set of clear, composable principles:

• Slices, Not a Monolith: Auth capabilities (such as sessions, email and password, verification codes, and OAuth) are divided into independent Slices. Each slice contains its own data shapes, repository interfaces (Ports), and pure business logic (Flows).
• Pure Flows & Ports: Flows contain pure business logic and never touch HTTP requests, response headers, or database drivers directly. They interact with typed Ports—Stores for data access and Strategies for configurable behaviors like session transport or rate limiting.
• Atomic SQL Contracts: Concurrency guarantees and security invariants are enforced directly at the database level. Critical state transitions—such as single-use token consumption or session rotation—execute as single, atomic SQL operations, eliminating race conditions.
• Agent Guidance: Instead of configuring plugins and lifecycle hooks, your AI coding agent uses Butter skills to scaffold migrations, wire Adapters for your specific ORM and database, and integrate the flows directly into your app.
• Invariants & Advisories: Every slice is governed by strict, plain-language security invariants backed by automated tests shipped into your repository. Security fixes arrive as updated invariant tests that your agent adapts your code to satisfy, preserving your customizations.

Architecture at a Glance#

In an installed Butter system, data flows cleanly from primitives to your application:

Primitives  ──┐
Flows       ──┼──► Ports (Stores & Strategies) ◄── Adapters (User's Stack)
              │
              └──► Composition Root ──► Effect API / Application Handlers

• Primitives: Low-level cryptographic and encoding helpers built on standard libraries (@oslojs/*, arctic).
• Flows: Pure business logic using Effect v4.
• Ports: Context interfaces defining what the flows need to read, write, or hash.
• Adapters: Concrete implementations of Ports written for your chosen database and ORM.
• Composition Root: A single user-owned file in your project assembling the slices and adapters into a cohesive Auth service.

Project Status#

Butter is currently in active design and initial development. This site serves as an architectural overview and starting point—comprehensive documentation, an interactive slice configurator, dynamic registry distribution, and agent setup skills are in progress.

In the meantime, explore the repository on GitHub or review Pilcrow's Auth Book to understand the foundational principles Butter is built on.