Auth overview

Every app that has users has the same afternoon in front of it: a sign-in screen, a way to remember who is signed in, a way to sign them out, and — a week later — the discovery that the mobile app needs a different credential from the web one.

@pithy-sh/auth is that afternoon, done, in your own Worker. Magic link, email one-time code, Google, Apple, GitHub, Facebook and Microsoft. Sessions over a cookie or a bearer token, rotated with theft detection, a short-lived JWT for your other services, a device registry, and two tiers of rate limiting. It is built on Better Auth, and it fills core’s identity seam so that every other capability can write requireAuth() without knowing anything about how a token is checked.

There is no password

There never will be. Email-and-password is never enabled, and that is a security stance rather than a missing feature.

A user proves who they are with a magic link, a one-time code, or a social provider. There is no password database to leak, no password to phish, and no reset flow to build — which also means no forgot password email, no password strength rules, and no argument about bcrypt cost factors.

If your requirements name password sign-in, this capability says no rather than not yet.

The token model, in one paragraph

A successful sign-in mints a session. On web it is a CSRF-protected cookie. On mobile it is the raw session token, kept in secure device storage and sent as Authorization: Bearer <token>.

The session is what every request to your Worker carries, and the Worker resolves it on each one, so a revoked session stops working on the next request. A mobile client rotates it before it expires: POST /auth/token/rotate spends the token it is shown and hands back a successor. When the session expires, sign in again. Rotation also hands back a short-lived JWT access token — EdDSA — and that one is not for your Worker: the kit’s routes do not accept it. It is for a service outside your Worker that verifies it against the JWKS your Worker publishes.

The token model works through rotation and why a replayed token revokes a whole family, and JWKS and local verification covers the outside service.

Mobile and web are both first-class

Mobile uses bearer. There is no ambient credential to forge, so it is CSRF-exempt.

Web has two options: the same bearer flow, for a SPA that holds the token in memory; or a cookie session, CSRF-protected through an origin check and a SameSite=lax cookie. When cookie mode is on, CSRF protection is on with it. That pairing is not configurable apart, deliberately — a cookie session with CSRF disabled is a vulnerability with a config key in front of it.

Mobile reads the session token from the sign-in answer’s body and stores it, and a redirect sign-in hands it back through a one-time code the app trades at POST /auth/handoff. Web gets the session as a cookie automatically. Sign in on iOS and Android has the mobile half, and pithy ui add react-native scaffolds it.

A native app can prove itself instead of solving a widget. With an attestation block for the environment, the two send routes take an Apple App Attest or Google Play Integrity attestation in place of a Turnstile token, against a single-use challenge, and a test mode lets simulators and CI through outside production. Both platforms are verified. An iOS app registers its App Attest key once, and each send after that carries an assertion auth checks against Apple’s pinned root and the key’s counter. An Android app sends a Play Integrity token bound to the challenge and the body, and the Worker decodes it through Google with a service account you store as a secret, and requires a recognized app on a device that meets device integrity. The app pithy ui add react-native scaffolds speaks both: it attests on iOS and Android under enforce, and sends the test assertion from a simulator or an emulator. Native app attestation has the setup for each.

What you get without writing any of it

  • Seven sign-in methods. Magic link and one-time code are built in and fixed. Google, Apple, GitHub, Facebook and Microsoft each turn on with a config flag and a credential you take from that provider’s console.
  • A device registry. Opt in per request by sending device metadata headers at sign-in, and the session binds to that device. Two routes follow: list my devices, and revoke one — sign me out on that lost phone is a single call.
  • Two tiers of rate limiting. Cloudflare’s native rate limiter caps requests per client IP at the edge, in front of every auth route, with no storage round-trip. Better Auth’s own D1-backed limiter caps per action and identity — the magic-link and one-time-code caps. Two limiters because they do two jobs, and because in-memory limiting is per-isolate on Workers and therefore useless.
  • A recent sign-in, where a route needs one. requireRecentSignIn gates a route that reveals a secret or changes who can see something on a sign-in within the window the route names, and refuses an older session with one code every client answers the same way: sign in again, then retry. A rotation keeps the original sign-in time, so it never passes. Require a recent sign-in has the gate.
  • A ledger of every sign-in link and code. Each one sent is recorded with the mail that carried it, and whether it was used, expired or is still waiting, so a sign-in that failed because the mail never landed can be found. Never the token, never the address. The verification ledger has the read.
  • Suspended and deleted accounts, refused at every door. Every request, sign-in and token refresh refuses one with a code a client can render, every transition is recorded with its actor and reason, and the mail and the screens ship with it. An operator suspends, reinstates, deletes, restores and exports an account from the control plane, with a reason. A deletion is soft, with a window to restore it, unless the operator names hard.
  • Account deletion from inside your app. DELETE /auth/account is the route the App Store and Google Play require of an app with accounts, and a suspended person can still reach it.
  • A purge that reaches every capability. Once a deleted account’s window closes, a Workflow your Worker hosts erases it from every composed capability, one step each, and an export answers an access request from the same contributions. Payments, email and audit keep their rows instead, for tax records, a lasting unsubscribe and the record of who acted, and the export says so beside them. Suspended and deleted accounts has what each capability does.
  • A management surface, default-denied. Thirteen admin routes for a dashboard’s user panes, each behind its own scope. With the control-plane seam not composed they all answer controlplane/not_connected, and no app session opens any of them whatever it carries.
  • The seam that opens server-authoritative writes. Leaderboard, rating and ledger gate their backend-only routes on a scope, and resolveScopes is the one thing that fills it, per request, for a caller that proves it is your backend. Server-authoritative writes has the three ways to prove it.

Your users’ agents, as your users. Compose mcp({ floor }) beside auth() — pithy add mcp --floor <floor> writes it, from this same package — and the Worker serves an MCP endpoint of its own: an agent signs in through your consent screen and calls the routes you opted in as tools, as the person who approved it, with that person’s role and nothing more. Letting your users’ agents in is the walkthrough.

What it deliberately does not do

No impersonation. Sign in as this user mints a credential indistinguishable from the person’s own, so every action taken with it reads in the audit trail as theirs. It is excluded on purpose and it is not reachable by composing what is here — no route mints a session, and no read projects a session token. If it is ever built it gets its own design and its own security review.

No roles or permissions of its own. Auth answers who is this, and, through resolveScopes, did this come from your backend. What they may do is your application’s question, or payments’ entitlement seam, or the roles you declare in organization.

No user profile beyond identity. Your users’ names, avatars and preferences are your tables. Auth owns identity, sessions, accounts, verifications, JWKS, rate limits, devices, the account-lifecycle record and the verification ledger — all prefixed pithy_auth_*, sitting in the same database as your own tables and joinable with plain SQL.

A scope per admin operation, not one admin flag. Reading a user is a privacy operation; revoking their sessions is an availability one. A support tool that looks people up should never be able to sign the whole customer base out, and an incident-response tool that kills a stolen session has no business reading every address in the user table. Suspending an account, deleting one and exporting one are three more grants, and none implies another.

It is Better Auth, and the ecosystem is open

Four plugins are composed and fixed — bearer, JWT, magic link, one-time code — and they are composed first. They are fixed because the rest of the kit depends on them and cannot see your config: magic link and one-time code are the sign-in this product promises, JWT mints the JWKS every Worker verifies against, and bearer is how a mobile client presents its credential. A config that names one of the four is refused by name.

Everything else composes. organization, passkey, twoFactor, apiKey, admin, a generic OAuth provider — pass any of them in and pithy migrate creates whatever tables they declare, contributed as ordinary migrations with tested rollbacks. pithy doctor prints every composed plugin and the tables it introduced, because an extension has no package.json for the capability listing to name it from and it still adds routes and tables.

mcp() brings an OAuth provider of its own, and refuses a second. Composing mcp() beside auth() adds Better Auth’s OAuth 2.1 provider to this same instance, as the authorization server your users’ agents sign in through, with its tables migrated beside auth’s. So a Worker that composes mcp() refuses oauthProvider() in auth({ plugins }), naming the line to remove: the endpoint’s provider is the one. A generic OAuth client for social sign-in is a different plugin and is unaffected.

An API key stands for its owner when you say so. Compose apiKey({ enableSessionForAPIKeys: true }) and a request carrying a key in x-api-key resolves to the key owner’s session, so requireAuth() in every capability accepts it — the way a CI job reaches the git credential helper. Send it as x-api-key, the plugin’s default header, never as Authorization: Bearer, which Better Auth reads as a session token and refuses. A renamed header never reaches the kit. The plugin limits each key to ten requests a day unless you change its rateLimit.

When you would reach for it

Almost always, and almost first. Storage objects belong to an owner, ledger balances belong to a player, ratings bind to a player, and payments has no public routes at all — each of those denies every request without auth composed.

The exception is a backend with no end users at all: a machine-to-machine API, or an internal service reached with a bearer token you issue yourself. Choosing a client credential covers that shape.

What it needs

It requires secrets — its session signing key is read through the registry rather than an environment literal — and email, because magic-link and one-time-code delivery enqueues a durable job rather than sending inline. Both compose automatically with pithy add auth --with-prerequisites.

It gets better with turnstile, which auto-gates the magic-link and one-time-code send routes with zero configuration, and with audit, which records sign-in, token refresh and device revocation when composed. A native app that attests is judged by its attestation in place of Turnstile.

ESC