Auth

What it does

The auth cartridge³⁸, packages/auth, is a package for one job with its implementation and required infrastructure. It runs Better Auth, a library for sign-in and sessions, through @alchemy.run/better-auth. It uses the implementation chosen by the database¹¹ cartridge. People sign in with email and password under /auth.¶

RPC means remote procedure call: a client calls a named operation on the server. CurrentPersonMiddleware checks each call’s session before it runs and provides CurrentPerson, the signed-in person’s id. This check is middleware: code that runs around a call.¶

A capability is one named action with shared value definitions and a server-side implementation. @rat-stack/auth/devtools adds runAsPerson, the dev-only rat_test_person capability, and in-memory test people.¶

The public sign-in surface²⁶ is gated by AUTH_ENABLED, which defaults to false. When enabled, learn feedback¹⁰ uses phone approval and a separate feedback-only credential.¶

The phone page signs in through Better Auth. The agent never receives a sign-in session. The stock device-token exchange is disabled.¶

Mischief serves the phone page and the public feedback projections. It calls the private LearnFeedbackAuth Worker⁶⁰ through a Worker binding²⁵. That Worker owns Better Auth, the D1 database, and the signing secret. It has no public route and sets workersDev to false.¶

The web app’s dev server also uses auth, where devtools calls can run as test people.¶

The standard

An RPC call without a valid session fails as Unauthenticated. That is the only auth failure sent to the client.¶
Feedback credentials permit learnFeedback only. They cannot provide CurrentPerson to another capability.¶
Off keeps only the database and signing-secret foundation. It exposes no auth route, feedback tool, or private Worker.¶
Mischief contains no Better Auth implementation. apps/site/scripts/startup-budget.ts enforces a separate static-startup ceiling for each Worker. Total JavaScript above 2,500,000 bytes warns; it does not fail the build.¶
A session whose user id fails the person-id schema check also fails as Unauthenticated.¶
Test people and rat_test_person never reach production. Lint keeps @rat-stack/auth/devtools inside dev folders, the CLI, and tests (rat-stack-boundaries/no-devtools-in-production).¶
A production build of the web app contains no dev module, no devtools code, and no test person.¶

How to check

pnpm --filter @rat-stack/auth test signs up, signs in, reads a session, protects an RPC call, and runs devtools calls as a test person.¶
pnpm --filter @rat-stack/site exec vitest run test/feedback-auth.test.ts checks phone approval and feedback storage through a separate private server.¶
The same tests check flag-off routes and tool discovery.¶
pnpm --filter @rat-stack/site startup:check measures both uploads and rejects auth implementation modules in Mischief.¶
pnpm --filter @rat-stack/web exec vitest run test/production-bundle.test.ts builds the web app for production and checks the bundle.¶

Sources

rat-stack/packages/auth/src/auth.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Auth composition; used for Better Auth and database adapter selection. Accessed 2026-10-01.
rat-stack/packages/auth/src/current-person-middleware.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Session middleware; used for CurrentPerson and failures sent to the client. Accessed 2026-10-01.
rat-stack/packages/auth/test/auth.test.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Auth tests; used for sign-in, sessions, protected calls, and test people. Accessed 2026-10-01.
rat-stack/apps/web/test/production-bundle.test.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Production bundle test; used to verify devtools and test people stay out. Accessed 2026-10-01.

Last changed 2026-11-08 in c11e293. Source on GitHub. Change log.

Linked from

Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Auth — Email and password sign-in through Better Auth, with the signed-in person provided to each RPC call.
Agent rules for rat-stack (AGENTS.md). What you may change, which commands to run, and which changes need approval.
Role: Better Auth cartridge over the chosen DatabaseVendor: Auth, CurrentPerson, and the RPC middleware that provides it; only Unauthenticated crosses the wire.
An MCP your users want. Rhys Sullivan's practical guide gives rat-stack a checklist for useful MCP tools.
: rat-stack today: The auth cartridge supports Better Auth sessions for an app, but ratstack.sh says it has no OAuth or access tokens.¶
Build and run rat-stack (README.md). What is in the repo, how the example works, and how to run it.
No account auth or database ( auth and database, with protected feedback and browser dev identity):
Cartridges. A cartridge owns one job and brings the infrastructure its service needs.
ts picks Better Auth’s D1 or Hyperdrive adapter.¶
Change log. What changed in the files served here, newest first.
Auth — new page: Initial commit from joelhooks/rat-stack template
Database. One interface records action runs and their outcomes in either Cloudflare D1 or Postgres through Hyperdrive.
Auth uses the selected database vendor in the web development backend and the optional private LearnFeedbackAuth Worker.
Effect + Alchemy peer patterns. Source-grounded patterns from repos on nearby Effect and Alchemy pins.
These peer patterns guide the web client, Alchemy resources, database, Better Auth, Worker tests, and boundary enforcement.
Effect + Alchemy peers. Public repositories that share rat-stack's prerelease lines.
Why this tier: Upstream infrastructure reference; the study cites its RPC and Better Auth patterns.
Effect 4 study: September 2026. Dated Effect 4 source studies from September 2026; current versions live in pins.md.
Alchemy and its Better Auth adapter use beta.81.
Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Interest signup. Agent-only applications start email confirmation through interfaces owned by core and delivery implemented in a separate package.
List signup is separate from account authentication.¶
Learn mode presents concepts at useful depths. An agent presents source-derived concepts during real work and keeps learning events in a private local log.
A person signs in through Better Auth and approves an agent’s code on their phone.
Lint and type escape ledger (debt.md). A source-linked count of repo-owned lint and type escapes.
Reason: Better Auth intentionally retains per-request RuntimeContext requirements.
Rat Stack systems | rat-stack. The systems rat-stack ships, the standard each keeps, and how to check it.
Auth — Email and password sign-in through Better Auth, with the signed-in person provided to each RPC call.
rat-stack. An Effect stack so pure (aspirational) Kit Langton will blush.
security-audit. Security guidance and vulnerability review for codebases, APIs, services, CLI tools, libraries, and daemons. Use for security questions, focused reviews, vulnerability research, security audits, or pen tests. Run the complete workflow only for explicit codebase audit or pen-test requests, full/comprehensive/end-to-end reviews, or requested report artifacts.
ts provides Better Auth over the selected database vendor.
Source change history (log.md). The generated change log as Markdown.
Auth — new page: Initial commit from joelhooks/rat-stack template