# Auth

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

## 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](/systems/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](/systems/learn#feedback-sign-in) 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](/lore/bindings).
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-report.ts` fails the build if Better Auth reaches Mischief's graph. It reports each Worker's static startup size without failing on it.
- 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

1. [rat-stack/packages/auth/src/auth.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/auth/src/auth.ts)
   GitHub joelhooks/rat-stack. Auth composition; used for Better Auth and database adapter selection. Accessed 2026-10-01.

2. [rat-stack/packages/auth/src/current-person-middleware.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/auth/src/current-person-middleware.ts)
   GitHub joelhooks/rat-stack. Session middleware; used for CurrentPerson and failures sent to the client. Accessed 2026-10-01.

3. [rat-stack/packages/auth/test/auth.test.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/auth/test/auth.test.ts)
   GitHub joelhooks/rat-stack. Auth tests; used for sign-in, sessions, protected calls, and test people. Accessed 2026-10-01.

4. [rat-stack/apps/web/test/production-bundle.test.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/apps/web/test/production-bundle.test.ts)
   GitHub joelhooks/rat-stack. Production bundle test; used to verify devtools and test people stay out. Accessed 2026-10-01.

## Lore on this page

- [A cartridge owns one job and its resources](/lore/cartridges)
- [One schema, three surfaces](/lore/one-schema-three-surfaces)
- [Workers answer requests; Durable Objects own named state](/lore/workers-answer-requests-durable-objects-own-named-state)

## Linked from

- A cartridge owns one job and its resources → A cartridge owns one job and brings the infrastructure its service needs. → [Read page](https://ratstack.sh/lore/cartridges)

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Agent rules for rat-stack (AGENTS.md) → What you may change, which commands to run, and which changes need approval. → [Read page](https://ratstack.sh/AGENTS.md)

- An MCP your users want → Rhys Sullivan's practical guide gives rat-stack a checklist for useful MCP tools. → [Read page](https://ratstack.sh/lore/an-mcp-your-users-want)

- Build and run rat-stack (README.md) → What is in the repo, how the example works, and how to run it. → [Read page](https://ratstack.sh/README.md)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Database → One interface records action runs and their outcomes in either Cloudflare D1 or Postgres through Hyperdrive. → [Read page](https://ratstack.sh/systems/database)

- Effect + Alchemy peer patterns → Source-grounded patterns from repos on nearby Effect and Alchemy pins. → [Read page](https://ratstack.sh/resources/same-version-repos)

- Effect + Alchemy peers → Public repositories that share rat-stack's prerelease lines. → [Read page](https://ratstack.sh/resources/peers)

- Effect 4 study: September 2026 → Dated Effect 4 source studies from September 2026; current versions live in pins.md. → [Read page](https://ratstack.sh/resources/effect-4-reference-projects)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Interest signup → Agent-only applications start email confirmation through interfaces owned by core and delivery implemented in a separate package. → [Read page](https://ratstack.sh/systems/interest)

- 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. → [Read page](https://ratstack.sh/systems/learn)

- Lint and type escape ledger (debt.md) → A source-linked count of repo-owned lint and type escapes. → [Read page](https://ratstack.sh/debt.md)

- Rat Stack systems | rat-stack → The systems rat-stack ships, the standard each keeps, and how to check it. → [Read page](https://ratstack.sh/systems)

- rat-stack → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/)

- 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. → [Read page](https://ratstack.sh/skills/security-audit)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)
