@pithy-sh/auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @pithy-sh/auth
+
+Passwordless auth for Cloudflare. Magic link, email OTP, Google, Apple. Mobile and web, both first-class. Built on Better Auth. No email and password, ever.
+
+This capability fills core's identity seams. It mints sessions, issues short-lived JWT access tokens, registers devices, and validates every request — so other capabilities just call `requireAuth()`.
+
+```sh
+pithy add auth
+```
+
+**Documentation: [pithy.sh/docs/capabilities/auth](https://pithy.sh/docs/capabilities/auth).** Overview, adding it, using it, and the reference: the token model, sessions and devices, JWKS.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## The client surface
+
+Better Auth builds a client from its **own** plugin list. The server's type never crosses into a browser bundle, so composing `organization()` on the server is half of it — add `organizationClient()` beside it and `authClient.organization` is fully typed, with no cast:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { emailOTPClient, magicLinkClient, organizationClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  baseURL: "https://api.example.com",
+  basePath: "/auth",
+  plugins: [magicLinkClient(), emailOTPClient(), organizationClient()],
+});
+```
+
+The kit's own sign-in plugins have client halves too, and they go in the same list — nothing about the client is inherited from the server.
+
+The one thing that does need the server's type is `inferAdditionalFields`, which teaches the client about extra user and session fields. `AuthInstance` is parameterized in the plugin tuple for exactly that:
+
+```ts
+import type { AuthInstance } from "@pithy-sh/auth/src/instance/auth";
+import type { organization } from "better-auth/plugins/organization";
+
+type AppAuth = AuthInstance<[ReturnType<typeof organization>]>;
+// …then `inferAdditionalFields<AppAuth>()` in the plugins list above.
+```
+
+**This section stays here.** `src/http/routes.ts` and `src/client/api.ts` both explain a design decision by pointing a reader at it by name — the flat response shape is read rather than rewritten precisely because `createAuthClient` is a first-class surface, and that argument is only checkable against the client this documents.
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/docs/apple-signin.md

@@ -0,0 +1,139 @@
+# Apple sign-in
+
+_The reader's version of this page is [pithy.sh/docs/build/auth-and-accounts/apple-sign-in](https://pithy.sh/docs/build/auth-and-accounts/apple-sign-in). This copy ships in the package because `packages/auth/src/capability.ts` sends an adopter to it by name._
+
+Adding Sign in with Apple to `@pithy-sh/auth`. Step by step.
+
+Apple is first-class here because Pithy is mobile-first. Apple's App Store guidelines require you to offer Sign in with Apple once you offer another third-party sign-in like Google. If your app ships Google, it ships Apple too.
+
+## Why this part is manual
+
+Sign in with Apple credentials are created in the [Apple Developer portal](https://developer.apple.com) by a human with access to your Apple Developer account. Pithy cannot create them for you — there is no API to provision an App ID, a Services ID, or a signing key on your behalf. So this is a one-time manual setup. The rest of the flow is config.
+
+There is one extra wrinkle Google does not have: Apple's client secret is not a static string. It is a JWT you sign yourself, and it expires. More on that in [Generate the client secret](#4-generate-the-client-secret).
+
+## 1. Register an App ID
+
+Under **Certificates, Identifiers & Profiles** → **Identifiers** → **App IDs**, register an App ID for your iOS app. Enable the **Sign in with Apple** capability on it.
+
+The App ID's bundle id — for example `com.example.myapp` — is the `appBundleIdentifier`. The native iOS flow uses it as the id-token audience. Note it down.
+
+## 2. Create a Services ID
+
+Under **Identifiers** → **Services IDs**, create a Services ID. This is the OAuth `clientId` for the web and redirect sign-in flow — distinct from the App ID above.
+
+Enable **Sign in with Apple** on the Services ID and configure it. Add your web domain and the return URL from the next section. Apple requires the domain be verified.
+
+## 3. Create a Sign in with Apple key
+
+Under **Keys**, create a new key with **Sign in with Apple** enabled. On create you can download the private key once as a `.p8` file — download it and keep it safe. You cannot download it again.
+
+Note two values:
+
+- The **Key ID** shown on the key.
+- Your **Team ID** — the ten-character id in your Apple Developer account membership.
+
+You now hold three things: the `.p8` private key, its Key ID, and your Team ID.
+
+## 4. Generate the client secret
+
+Apple's client secret is not a string you copy. It is an **ES256 JWT** you sign with the `.p8` private key. The claims:
+
+| Claim | Value |
+| --- | --- |
+| `iss` | your Team ID |
+| `sub` | your Services ID (the `clientId`) |
+| `aud` | `https://appleid.apple.com` |
+| `exp` | an expiry **at most six months** out |
+
+That signed JWT **is** the `clientSecret`. Sign it with the `.p8`, the Key ID in the JWT header (`kid`), and `alg: ES256`.
+
+Because `exp` caps at six months, the secret expires. Regenerate and rotate it on a schedule — the secret is stored as **rotatable** so a fresh JWT can replace the old one without a config change. See [Where the credentials live](#where-the-credentials-live).
+
+## 5. The exact return URL
+
+Better Auth's Apple callback is always:
+
+```
+<baseURL><basePath>/callback/apple
+```
+
+With the default `basePath` of `/auth`, the path is `/auth/callback/apple`. Register one return URL per environment in the Services ID, each on that environment's `baseURL` host:
+
+| Environment | Return URL |
+| --- | --- |
+| dev | `http://localhost:8787/auth/callback/apple` |
+| staging | `https://staging.<your-domain>/auth/callback/apple` |
+| production | `https://<your-domain>/auth/callback/apple` |
+
+Apple requires the domain be verified and uses https. It does not accept plain http, so localhost generally will not work as a return URL — dev typically uses the native iOS flow or a tunneled https domain instead.
+
+Apple sends the callback as a **POST** (`form_post`), not a redirect GET. Better Auth handles that. You do not need to change anything for it.
+
+### Every environment — and why feature-branch previews won't work
+
+Each environment needs its **own** return URL registered on the Services ID, on that environment's exact `baseURL` host — and Apple additionally requires that host's domain be **verified**, over https. Apple only returns to a URL you have registered.
+
+Apple is the strictest here for feature branches. A branch deployed to a Cloudflare preview URL — an ephemeral `*.workers.dev` or preview alias, not your registered `staging.<your-domain>` — is neither registered nor domain-verified, so web Apple sign-in there simply cannot complete. Registering and verifying a throwaway preview domain per branch is impractical, so do not expect to test the web Apple flow from a preview URL.
+
+To exercise Apple on a branch, use the **native iOS flow** (which sends an id token straight to the Worker and needs no return URL), or run against your registered `staging`/`production` environment.
+
+Magic link and email OTP have no return URL — they work on any URL, preview or not. Only the OAuth providers need a registered callback.
+
+## 6. Mobile
+
+Native iOS uses Apple's own Sign in with Apple flow, not the web redirect. The app gets an identity token from Apple and sends it to the Worker. The `appBundleIdentifier` is the audience that id token is validated against — which is why it is part of the credential.
+
+You do **not** register a deep-link or custom-scheme URL in the Apple portal. Apple only ever returns to the Services ID's return URL or, for native, hands the id token straight to the app.
+
+The app passes its own deep link as the sign-in `callbackURL` — for example `myapp://auth/callback`. For that to be allowed, the scheme must be listed in `trustedOrigins` (prefix match):
+
+```ts
+auth({
+  trustedOrigins: ["myapp://", "https://app.example.com"],
+});
+```
+
+## Where the credentials live
+
+**All three values travel as one typed JSON secret.** The Services ID, the signed JWT, and the bundle id are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-apple-credentials`:
+
+```
+pithy secrets create auth-apple-credentials --json '{"clientId":"<services-id>","clientSecret":"<es256-jwt>","appBundleIdentifier":"<ios-bundle-id>"}'
+```
+
+`appBundleIdentifier` is optional. Omit it for web-only. The package reads the whole credential from the secrets store at request time and wires it into the provider. Enable Apple in config with `auth({ apple: { enabled: true } })` — no credential values in the config.
+
+The secret is **rotatable**. When the JWT nears its six-month expiry, generate a fresh one and rotate the secret. Read sites stay byte-identical.
+
+## Account linking
+
+A user who signed up with a magic link and later signs in with Apple is linked automatically when the verified emails match. Apple is configured as a **trusted provider**, and the local email is already verified — the magic link proved it — so the two accounts merge into one rather than colliding.
+
+Apple only returns the user's name on the **first** authorization. Better Auth persists it then. If you wipe the user and re-authorize, the name does not come back unless you remove the app from the Apple ID's signed-in apps first. There is nothing to configure; just know the name arrives once.
+
+`requireLocalEmailVerified` stays on. That is the secure default: it blocks account takeover where an attacker pre-registers an unverified row for a victim's email and waits for the victim's Apple sign-in to link into it. Leave it on.
+
+## When the credential will not read
+
+An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
+**that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
+
+A sign-in attempt with Apple then answers `503` with the code `auth/provider_unavailable` and a
+message naming apple, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
+are different facts and never share an answer. The attempt is recorded in the audit trail as
+`auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
+provisioning `auth-apple-credentials` for that environment, or turn the provider off in config.
+
+## Checklist
+
+- [ ] App ID registered with Sign in with Apple enabled; bundle id in hand.
+- [ ] Services ID created with Sign in with Apple configured; web domain verified.
+- [ ] Sign in with Apple key created; `.p8` downloaded, Key ID and Team ID noted.
+- [ ] Client secret JWT generated: ES256, `iss` = Team ID, `sub` = Services ID, `aud` = `https://appleid.apple.com`, `exp` ≤ 6 months.
+- [ ] Return URL registered per environment as `<baseURL><basePath>/callback/apple`.
+- [ ] Return URL host matches each environment's `baseURL`; domain verified and https.
+- [ ] Mobile deep-link scheme listed in `trustedOrigins` (no deep link in the Apple portal).
+- [ ] `clientId` + `clientSecret` + optional `appBundleIdentifier` stored together via `pithy secrets create auth-apple-credentials` (typed JSON); Apple enabled in config with `apple: { enabled: true }`.
+- [ ] A plan to regenerate and rotate the client secret before it expires.
+- [ ] `requireLocalEmailVerified` left on.

package/docs/facebook-oauth.md

@@ -0,0 +1,92 @@
+# Facebook sign-in
+
+_The reader's version of this page is [pithy.sh/docs/build/auth-and-accounts/facebook-sign-in](https://pithy.sh/docs/build/auth-and-accounts/facebook-sign-in). This copy ships in the package because `packages/auth/src/capability.ts` sends an adopter to it by name._
+
+Adding Facebook to `@pithy-sh/auth`. Step by step.
+
+## Why this part is manual
+
+Facebook Login credentials are minted in the Meta app dashboard by a human with access to your Meta developer account. Pithy cannot create them for you. So this is a one-time manual setup. The rest of the flow is config.
+
+## 1. Create a Meta app
+
+Open the [Meta app dashboard](https://developers.facebook.com/apps). Create an app, choose **Consumer** (or the type that fits), and add the **Facebook Login** product. One app covers all your environments; you register a redirect URI per environment below.
+
+## 2. The exact redirect URI
+
+Better Auth's OAuth `redirect_uri` is always:
+
+```
+<baseURL><basePath>/callback/facebook
+```
+
+With the default `basePath` of `/auth`, the path is `/auth/callback/facebook`. Under **Facebook Login → Settings → Valid OAuth Redirect URIs**, register one URI per environment, each on that environment's `baseURL` host:
+
+| Environment | Redirect URI |
+| --- | --- |
+| dev | `http://localhost:8787/auth/callback/facebook` |
+| staging | `https://staging.<your-domain>/auth/callback/facebook` |
+| production | `https://<your-domain>/auth/callback/facebook` |
+
+Use your actual local port for dev — `8787` is wrangler's default, not a guarantee. Facebook requires HTTPS for non-localhost redirect URIs.
+
+### Every environment — and why feature-branch previews won't work
+
+Each environment needs its **own** redirect URI in the app's **Valid OAuth Redirect URIs**, on that environment's exact `baseURL` host. Facebook only accepts a URL you have listed; anything else is blocked with *"URL blocked: This redirect failed because it's not in the app's allowed redirect URIs."*
+
+This bites feature-branch previews. A branch deployed to a Cloudflare preview URL — an ephemeral `*.workers.dev` or preview alias, not your registered `staging.<your-domain>` — is a host Facebook has never seen, so Facebook sign-in there fails. You cannot exercise Facebook sign-in from a preview URL until that exact URL is listed.
+
+To test Facebook on a branch, either add that deployment's own `<its-url>/auth/callback/facebook` to the Valid OAuth Redirect URIs **and** point that deployment's `baseURL` at the same host, or run the flow against your registered `staging` environment instead.
+
+Magic link and email OTP have no redirect URI — they work on any URL, preview or not. Only the OAuth providers need a registered callback.
+
+## 3. Scope
+
+Pithy requests the `email` scope. You do not configure scopes anywhere — Pithy sets it for you when Facebook is enabled.
+
+## 4. Mobile
+
+You do not register a deep-link URI with Facebook. Facebook only ever redirects to the Worker's `/auth/callback/facebook`. The mobile app passes its own deep link as the sign-in `callbackURL` (for example `myapp://auth/callback`); the Worker completes the exchange and redirects there. For that to be allowed, the scheme must be listed in `trustedOrigins` (prefix match):
+
+```ts
+auth({
+  trustedOrigins: ["myapp://", "https://app.example.com"],
+});
+```
+
+## Where the credentials live
+
+**Both credentials travel as one typed JSON secret.** The app id and app secret are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-facebook-credentials`:
+
+```
+pithy secrets create auth-facebook-credentials --json '{"clientId":"<your-app-id>","clientSecret":"<your-app-secret>"}'
+```
+
+Enable Facebook in config with `auth({ facebook: { enabled: true } })` — no credential values in the config.
+
+## Account linking
+
+One account per verified email. A Facebook sign-in whose email matches an existing user links into that account — no second account.
+
+Pithy trusts Facebook's email as verified. Facebook confirms a user's email before it will hand it back, and Pithy validates the OAuth access token against your app before reading the profile — so the email is genuinely the signed-in Facebook user's, verified by Facebook. That is the same trust Google and Apple get. Better Auth's own OAuth response carries no `email_verified` claim (and the Graph API exposes no such field), so without this Facebook would treat every email as unverified; Pithy asserts verification for Facebook's own email only.
+
+Facebook is **not** in `trustedProviders`. Trusting the returned email is not the same as trusting Facebook to link an *unverified* address — the assertion applies to the authenticated user's own Facebook email, which Facebook has verified.
+
+## When the credential will not read
+
+An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
+**that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
+
+A sign-in attempt with Facebook then answers `503` with the code `auth/provider_unavailable` and a
+message naming facebook, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
+are different facts and never share an answer. The attempt is recorded in the audit trail as
+`auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
+provisioning `auth-facebook-credentials` for that environment, or turn the provider off in config.
+
+## Checklist
+
+- [ ] Meta app created with the Facebook Login product.
+- [ ] Valid OAuth Redirect URI set to `<baseURL><basePath>/callback/facebook`, host matching each environment's `baseURL`.
+- [ ] App ID and app secret in hand.
+- [ ] Mobile deep-link scheme listed in `trustedOrigins` (no deep link in Facebook).
+- [ ] `clientId` + `clientSecret` stored together via `pithy secrets create auth-facebook-credentials` (typed JSON); Facebook enabled in config with `facebook: { enabled: true }`.

package/docs/github-oauth.md

@@ -0,0 +1,99 @@
+# GitHub sign-in
+
+_The reader's version of this page is [pithy.sh/docs/build/auth-and-accounts/github-sign-in](https://pithy.sh/docs/build/auth-and-accounts/github-sign-in). This copy ships in the package because `packages/auth/src/capability.ts` sends an adopter to it by name._
+
+Adding GitHub to `@pithy-sh/auth`. Step by step.
+
+## Why this part is manual
+
+GitHub OAuth credentials are minted in GitHub Developer settings by a human with access to your GitHub account or organization. Pithy cannot create them for you. So this is a one-time manual setup. The rest of the flow is config.
+
+## 1. Register an OAuth app
+
+Open **GitHub → Settings → Developer settings → OAuth Apps → New OAuth App** (for an org, use the organization's settings). One app per environment is cleanest, because each registers a single callback URL.
+
+- **Application name**: whatever your users should see on the consent screen.
+- **Homepage URL**: your app or site.
+- **Authorization callback URL**: the exact redirect URI from the next section.
+
+On create you get a **Client ID**. Generate a **Client Secret** on the same page. Where each goes is in [Where the credentials live](#where-the-credentials-live).
+
+## 2. The exact redirect URI
+
+Better Auth's OAuth `redirect_uri` is always:
+
+```
+<baseURL><basePath>/callback/github
+```
+
+With the default `basePath` of `/auth`, the path is `/auth/callback/github`. Register one URL per environment, each on that environment's `baseURL` host:
+
+| Environment | Callback URL |
+| --- | --- |
+| dev | `http://localhost:8787/auth/callback/github` |
+| staging | `https://staging.<your-domain>/auth/callback/github` |
+| production | `https://<your-domain>/auth/callback/github` |
+
+Use your actual local port for dev — `8787` is wrangler's default, not a guarantee. A GitHub OAuth app allows one callback URL, so register a separate app per environment.
+
+### Every environment — and why feature-branch previews won't work
+
+Each environment needs its **own** OAuth app, whose single **Authorization callback URL** is that environment's exact `baseURL` host. GitHub only accepts the one callback URL you registered on the app; anything else is rejected with *"The redirect_uri MUST match the registered callback URL for this application."*
+
+This bites feature-branch previews. A branch deployed to a Cloudflare preview URL — an ephemeral `*.workers.dev` or preview alias, not your registered `staging.<your-domain>` — is not the callback URL on any of your apps, so GitHub sign-in there fails. You cannot exercise GitHub sign-in from a preview URL until an app is pointed at that exact URL.
+
+To test GitHub on a branch, either register a throwaway OAuth app whose callback URL is that deployment's `<its-url>/auth/callback/github` (and point its credentials + `baseURL` at that deployment), or run the flow against your registered `staging` environment instead. Because a GitHub app allows only one callback URL, a per-branch app is the only way to test GitHub on an ephemeral URL.
+
+Magic link and email OTP have no callback URL — they work on any URL, preview or not. Only the OAuth providers need a registered callback.
+
+## 3. Scope
+
+Pithy requests `user:email`. That is what lets the sign-in read your primary email and its verified status from GitHub's emails API. You do not configure scopes anywhere — Pithy sets this for you when GitHub is enabled.
+
+## 4. Mobile
+
+You do not register a deep-link URI with GitHub. GitHub only ever redirects to the Worker's `/auth/callback/github`. The mobile app passes its own deep link as the sign-in `callbackURL` (for example `myapp://auth/callback`); the Worker completes the exchange and redirects there. For that to be allowed, the scheme must be listed in `trustedOrigins` (prefix match):
+
+```ts
+auth({
+  trustedOrigins: ["myapp://", "https://app.example.com"],
+});
+```
+
+## Where the credentials live
+
+**Both credentials travel as one typed JSON secret.** The client id and client secret are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-github-credentials`:
+
+```
+pithy secrets create auth-github-credentials --json '{"clientId":"<your-client-id>","clientSecret":"<your-client-secret>"}'
+```
+
+Enable GitHub in config with `auth({ github: { enabled: true } })` — no credential values in the config.
+
+## Account linking
+
+One account per verified email. GitHub is **not** a trusted provider, so it links only on a verified email — a deliberate choice, because GitHub lets an account hold unverified addresses.
+
+- **Verified email → automatic link.** A GitHub sign-in whose primary email is verified on GitHub, matching an existing user, links into that account. No second account.
+- **Unverified email → verify first.** If your GitHub primary email is not verified on GitHub, Pithy will not silently link it and will not create a second account. Verify the email on GitHub, or sign in with a magic link to that address first, then connect GitHub. This closes the takeover hole where an unverified address could be linked to an account you do not own.
+- **No seeding.** A GitHub sign-in whose email is unverified is refused rather than used to create a fresh account — so no one can seed a row at an address they have not proven they own.
+
+## When the credential will not read
+
+An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
+**that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
+
+A sign-in attempt with GitHub then answers `503` with the code `auth/provider_unavailable` and a
+message naming github, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
+are different facts and never share an answer. The attempt is recorded in the audit trail as
+`auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
+provisioning `auth-github-credentials` for that environment, or turn the provider off in config.
+
+## Checklist
+
+- [ ] GitHub OAuth app registered (one per environment).
+- [ ] Authorization callback URL set to `<baseURL><basePath>/callback/github`, host matching each environment's `baseURL`.
+- [ ] Client ID and a generated client secret in hand.
+- [ ] Mobile deep-link scheme listed in `trustedOrigins` (no deep link in GitHub).
+- [ ] `clientId` + `clientSecret` stored together via `pithy secrets create auth-github-credentials` (typed JSON); GitHub enabled in config with `github: { enabled: true }`.
+- [ ] GitHub primary email verified on GitHub (or plan for the magic-link verify-to-link step).

package/docs/google-oauth.md

@@ -0,0 +1,118 @@
+# Google sign-in
+
+_The reader's version of this page is [pithy.sh/docs/build/auth-and-accounts/google-sign-in](https://pithy.sh/docs/build/auth-and-accounts/google-sign-in). This copy ships in the package because `packages/auth/src/capability.ts` sends an adopter to it by name._
+
+Adding Google to `@pithy-sh/auth`. Step by step.
+
+## Why this part is manual
+
+Google OAuth credentials are minted in Google Cloud Console by a human with access to your Google account. Pithy cannot create them for you — there is no API to provision an OAuth client on your behalf. So this is a one-time manual setup. The rest of the flow is config.
+
+## 1. Create a Google Cloud project
+
+Open the [Google Cloud Console](https://console.cloud.google.com). Create a project, or pick an existing one. One project covers all your environments; you register a separate redirect URI per environment below.
+
+## 2. Configure the OAuth consent screen
+
+Under **APIs & Services** → **OAuth consent screen**:
+
+- User type: **External**.
+- Add the scopes `email`, `profile`, and `openid`. Nothing more — Pithy only needs identity.
+- Fill the app name, support email, and developer contact.
+
+While the app is in **Testing**, only test users you list can sign in. Publish it when you are ready for real users.
+
+## 3. Create OAuth client credentials
+
+Under **APIs & Services** → **Credentials** → **Create credentials** → **OAuth client ID** → **Web application**.
+
+Name it, then register the authorized redirect URIs from the next section. On create you get a **client ID** and a **client secret**. Where each goes is in [Where the credentials live](#where-the-credentials-live).
+
+## 4. The exact redirect URI
+
+Better Auth's OAuth `redirect_uri` is always:
+
+```
+<baseURL><basePath>/callback/google
+```
+
+With the default `basePath` of `/auth`, the path is `/auth/callback/google`. Register one URI per environment, each on that environment's `baseURL` host:
+
+| Environment | Redirect URI |
+| --- | --- |
+| dev | `http://localhost:8787/auth/callback/google` |
+| staging | `https://staging.<your-domain>/auth/callback/google` |
+| production | `https://<your-domain>/auth/callback/google` |
+
+Use your actual local port for dev — `8787` is wrangler's default, not a guarantee.
+
+Two rules. The path is `basePath` + `/callback/google` — if you set a custom `basePath`, the path changes to match it. The host must equal each environment's `baseURL` exactly. A mismatch is the most common cause of `redirect_uri_mismatch`.
+
+### Every environment — and why feature-branch previews won't work
+
+Each environment your app runs in needs its **own** redirect URI registered here, on that environment's exact `baseURL` host. Google only accepts a URL you have registered; anything else is a `redirect_uri_mismatch`.
+
+This is the gotcha with feature-branch previews. A branch deployed to a Cloudflare preview URL — an ephemeral `*.workers.dev` or preview alias, not your registered `staging.<your-domain>` — is a host Google has never seen, so Google sign-in there fails. You cannot exercise Google sign-in from a preview URL until that exact URL is registered.
+
+To test Google on a branch, either register that deployment's own `<its-url>/auth/callback/google` as an extra authorized redirect URI **and** point that deployment's `baseURL` at the same host, or run the flow against `dev` (localhost) or your registered `staging` environment instead.
+
+Magic link and email OTP have no redirect URI — they work on any URL, preview or not. Only the OAuth providers need a registered callback.
+
+## 5. Mobile
+
+You do **not** register a custom-scheme or deep-link URI in Google Console. Google only ever redirects to the Worker's `/auth/callback/google`. The Worker, not Google, is what hands control back to the app.
+
+The mobile app passes its own deep link as the sign-in `callbackURL` — for example `myapp://auth/callback`. The Worker completes the OAuth exchange, then redirects to that deep link. For this to be allowed, the scheme must be listed in `trustedOrigins` (prefix match):
+
+```ts
+auth({
+  trustedOrigins: ["myapp://", "https://app.example.com"],
+});
+```
+
+For native iOS or Android using the Google SDK's id-token flow (rather than the web redirect), register the platform-native **iOS** and **Android** OAuth client IDs in Google Console too, and pass all client IDs as an array:
+
+```ts
+auth({
+  google: { clientId: ["<web-id>", "<ios-id>", "<android-id>"] },
+});
+```
+
+## Where the credentials live
+
+**Both credentials travel as one typed JSON secret.** The client id and client secret are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-google-credentials`:
+
+```
+pithy secrets create auth-google-credentials --json '{"clientId":"<your-client-id>","clientSecret":"<your-client-secret>"}'
+```
+
+The pair stays atomic: the client id never splits off into config. The package reads the whole credential from the secrets store at request time and wires it into the provider. Enable Google in config with `auth({ google: { enabled: true } })` — no credential values in the config.
+
+## Account linking
+
+A user who signed up with a magic link and later signs in with Google is linked automatically when the verified emails match. Google is configured as a **trusted provider**, and the local email is already verified — the magic link proved it — so the two accounts merge into one rather than colliding.
+
+`requireLocalEmailVerified` stays on. That is the secure default: it blocks account takeover where an attacker pre-registers an unverified row for a victim's email and waits for the victim's Google sign-in to link into it. Leave it on.
+
+## When the credential will not read
+
+An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
+**that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
+
+A sign-in attempt with Google then answers `503` with the code `auth/provider_unavailable` and a
+message naming google, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
+are different facts and never share an answer. The attempt is recorded in the audit trail as
+`auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
+provisioning `auth-google-credentials` for that environment, or turn the provider off in config.
+
+## Checklist
+
+- [ ] Google Cloud project created.
+- [ ] OAuth consent screen: External, scopes `email` / `profile` / `openid`.
+- [ ] Web OAuth client created; client ID and secret in hand.
+- [ ] Redirect URI registered per environment, each as `<baseURL><basePath>/callback/google`.
+- [ ] Redirect host matches each environment's `baseURL`.
+- [ ] Mobile deep-link scheme listed in `trustedOrigins` (no deep link in Google Console).
+- [ ] Native id-token flow: iOS/Android client IDs registered, all IDs passed as an array.
+- [ ] `clientId` + `clientSecret` stored together via `pithy secrets create auth-google-credentials` (typed JSON); Google enabled in config with `google: { enabled: true }`.
+- [ ] `requireLocalEmailVerified` left on.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pithy-sh/auth",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/auth"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "docs",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.client.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@better-auth/i18n": "^1.7.1",
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/email": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "@pithy-sh/turnstile": "workspace:*",
+    "better-auth": "^1.7.1",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "miniflare": "^4.20260722.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}