@binary1702/auth 0.2.5 → 0.3.0

package/PROMPT.md

@@ -4,77 +4,365 @@ Copy everything below the line into an AI coding agent running inside the Next.j
 
 ---
 
-Install `@binary1702/auth` in this project. It adds email + password auth to a Next.js App Router app. Follow these steps exactly and report the result of each.
+Install `@binary1702/auth` in this project. It adds email + password sign-in to a Next.js App Router app: a sign-in page, a session cookie, and a guard in front of every page and API route. Follow the steps in order. After each step, note what happened; you will report it at the end.
 
-## Before you start
+## How the package works (read first)
 
-Check these and stop if any fails:
+Knowing the moving parts lets you fix problems instead of guessing.
 
-- `app/` or `src/app/` exists (App Router). Pages Router is not supported.
-- A Postgres connection string is available. Look for `DATABASE_URL` or `NEON_DATABASE_URL` in `.env.local` or the environment. If none exists, ask me for one.
-- If the project already has auth (a `proxy.ts` or `middleware.ts` that checks sessions, or packages like next-auth, better-auth, clerk, `@neondatabase/auth`), tell me before continuing. This package will put its own sign-in in front of everything.
+```
+users, orgs, members,   the package's tables, created by migrations on first start. Do not create tables with
+tokens, auth_migrations these names in the app; the installer refuses a database whose users table is not its own
+AUTH_SECRET             signs the session cookie; anyone with it can forge sessions
+auth_session cookie     set on sign-in, httpOnly, 7 days; says WHO, nothing else
+proxy.ts                runs before every request: valid cookie or public path? continue : sign in
+getSession()            in your server code: cookie valid AND user still allowed? → { user, organization, authorization }
+b17_auth.yaml           the app's settings: name, sign-up policy, which paths need sign-in, email, roles → permissions
+.env.local              secrets only; the yaml references them as ${NAME}
+/auth/[...path] route   serves sign-in, sign-up, sign-out, session, verify, forgot, reset
+```
+
+Two gates:
+
+- **The proxy** checks only that the cookie is genuine. No database. It protects pages from being opened by signed-out visitors.
+- **`getSession()` / `requireSession()` / `requirePermission()`** also check the database, so a deleted user, a changed password or (when required) an unverified email is refused. They protect data. Anything that reads or writes data for a user must call one of them; the proxy alone is not enough. `getUser()` / `requireUser()` are the same check returning only the user.
+
+What the proxy lets through without a session:
+
+| Path | Why |
+|---|---|
+| `/auth/*` | the sign-in pages themselves |
+| `/_next/*` | Next.js internals |
+| files ending in `.png .jpg .jpeg .gif .svg .ico .webp .avif .css .js .map .woff .woff2 .ttf .otf .txt .xml .webmanifest` | static assets from `public/` |
+| everything not under `protected:` in `b17_auth.yaml`, when that key is set | the app decides what needs sign-in |
+
+Everything else needs a session, including every path under `/api/` (even `/api/report.csv`). Signed-out page requests are redirected to `/auth/sign-in?next=<path>`; signed-out `/api/*` requests get `401` JSON.
+
+POSTs to `/auth/*` that a browser marks as coming from another website are refused with `403`. Requests with no browser headers (curl, server code) are allowed.
+
+## Step 1: Check before you start
+
+Stop and tell me if any check fails. Do not work around a failed check on your own.
+
+1. **App Router.** `app/` or `src/app/` exists. Pages Router (`pages/` only) is not supported.
+2. **Next.js version.** Read `next` in `package.json`. Write it down: 16+ uses `proxy.ts`, 15 uses `middleware.ts` (Step 4).
+3. **Node 20 or newer.** Run `node --version`.
+4. **Database.** Look for `DATABASE_URL` or `NEON_DATABASE_URL` in `.env.local`, `.env`, or the environment. It must be a **Neon** connection string (host ends in `neon.tech`). The package talks to Postgres through Neon's HTTP driver, so plain Postgres (local Docker, RDS, Supabase) will not work. If there is none, ask me for one. Never invent one.
+5. **Existing auth.** If the project already has `proxy.ts` / `middleware.ts` that checks sessions, or packages like `next-auth`, `better-auth`, `@clerk/nextjs`, `@supabase/auth-helpers-nextjs`, `@neondatabase/auth`, tell me before continuing. This package puts its own sign-in in front of everything.
+6. **Pages that must stay public.** Ask me whether any page should be visible without signing in (landing page, pricing, a webhook under `/api/`). By default nothing is. If yes, you will add them in Step 4.
+7. **Package manager.** Look for `pnpm-lock.yaml`, `yarn.lock` or `bun.lock*`. If one exists, install with that tool first (`pnpm add @binary1702/auth`, `yarn add …`, `bun add …`). The CLI uses npm otherwise, which would create a second lockfile.
+8. **.gitignore.** Confirm `.env.local` (or `.env*`) is ignored. The CLI writes the secret there. If it is not ignored, add it before Step 2.
 
-## Install
+## Step 2: Run the installer
 
-Run, in the project root:
+In the project root:
 
 ```bash
 npx @binary1702/auth
 ```
 
-It is interactive. It asks for the Postgres connection string, then an email and a password for the first user. If you cannot answer prompts, run it and hand control to me.
+It asks, in this order, only for what is missing:
 
-It does the following, skipping anything already done:
+| Prompt | When it appears | Answer |
+|---|---|---|
+| `Postgres connection string (DATABASE_URL)` | no `DATABASE_URL` in `.env.local` | the Neon URL from Step 1; a suggestion in parentheses is used if you press Enter |
+| `Email transport (gmail / resend)` | first install, no `b17_auth.yaml` yet | press Enter to skip unless I gave you a Gmail service-account key file or a Resend key. Skipped: emails print to the dev console. |
+| `Email` | the user table is empty | the first user's email, from me |
+| `Password` / `Password again` | same | at least 8 characters, from me |
+
+**Passwords come from me.** Never make one up, never write it to a file, never print it in your report. The simplest path: run the command and hand the terminal to me for the prompts. If you cannot run interactive commands, the CLI also reads answers from piped input, one per line, in the order above (an empty line skips the email prompt; skip lines for prompts that will not appear). Only do that with values I gave you, and tell me it may be stored in shell history.
+
+What it does, skipping anything already done (safe to re-run):
 
 ```
 ✓ @binary1702/auth installed             → package.json
 ✓ DATABASE_URL → .env.local
-✓ AUTH_SECRET generated → .env.local
+✓ AUTH_SECRET generated → .env.local     → 43 random characters
+· email not configured                   → or ✓ AUTH_GMAIL_… / AUTH_RESEND_… → .env.local
 ✓ app/auth/[...path]/route.ts            → export { GET, POST } from "@binary1702/auth/next"
-✓ proxy.ts                               → guard in front of every route
-✓ auth_users table ready                 → in the database
+✓ proxy.ts                               → the guard
+✓ b17_auth.yaml written                  → the app's settings, name taken from package.json
+✓ database schema ready (N migrations)   → tables created in the database
 ✓ user "<email>" created
 ```
 
-If `proxy.ts` or `middleware.ts` already existed, the CLI does not touch it and prints a snippet instead. Merge the snippet into the existing file: call the package's `proxy` for the paths you want protected and keep the matcher inline. On Next 15 the file is `middleware.ts`, same content.
+With `src/app/`, the files go to `src/app/auth/[...path]/route.ts` and `src/proxy.ts`.
 
-## Verify
+If it fails:
 
-Start the dev server and check with real HTTP requests:
+| Message | Cause | Fix |
+|---|---|---|
+| `No package.json here` | wrong directory | `cd` to the project root |
+| `No app/ directory` | Pages Router | stop, tell me |
+| `That does not look like a postgres:// URL` | wrong value | re-run with the real URL |
+| `Could not reach the database: …` | bad URL, wrong password, not Neon | check the URL with me; quote the message |
+| `Input ended before all prompts were answered` | piped input too short | give one line per prompt |
 
-| Request | Expect |
-|---|---|
-| `GET /` with no cookie | redirect to `/auth/sign-in` |
-| `GET /auth/sign-in` | 200, HTML form |
-| `GET /api/<any>` with no cookie | 401 JSON |
-| `POST /auth/sign-in` JSON `{ "email", "password" }` | 200 `{ user }` and `Set-Cookie: auth_session=…; HttpOnly` |
-| `GET /auth/session` with that cookie | `{ user: { id, email } }` |
-| `GET /auth/sign-out` | cookie cleared, redirect to sign-in |
+## Step 3: Check the two files it wrote
+
+**`app/auth/[...path]/route.ts`** must be exactly:
+
+```ts
+export { GET, POST } from "@binary1702/auth/next"
+```
+
+If `app/auth/` already had other files, keep them; a specific route like `app/auth/welcome/page.tsx` takes priority over the catch-all and is public.
+
+**`proxy.ts`** (or `src/proxy.ts`) must be:
+
+```ts
+import { proxy } from "@binary1702/auth/next/proxy"
+
+export default proxy
+
+// Everything except Next's build output. The proxy itself lets the
+// auth pages and static files through.
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+}
+```
+
+The matcher must be written inline. Next reads it from the file at build time and ignores an imported one.
+
+## Step 4: Adjust the guard for this project
+
+Pick the case that applies:
+
+```
+Next 15?
+  └─ rename proxy.ts → middleware.ts (same folder, same content) and add runtime: "nodejs"
+     to its config export (plus experimental.nodeMiddleware: true in next.config). Next 15
+     ignores proxy.ts, so without this nothing is protected.
+
+A proxy.ts / middleware.ts already existed?
+  ├─ CLI printed "has the old matcher"  → an older version of this package; replace only the
+  │                                       matcher line with the one in Step 3
+  └─ CLI printed "exists, not touched"  → merge by hand, see "Merging" below
+
+Some pages must stay public (Step 1.6)?
+  └─ list what DOES need sign-in under protected: in b17_auth.yaml. No code. See "Protected paths" below.
+
+Otherwise → nothing to do
+```
+
+**Merging into an existing proxy.** Keep the existing logic, call the package's proxy for the paths that need sign-in, and keep one inline matcher that covers both:
+
+```ts
+import { NextResponse, type NextRequest } from "next/server"
+import { proxy as auth } from "@binary1702/auth/next/proxy"
+
+export default async function proxy(request: NextRequest) {
+  // ...existing logic that must run first (redirects, headers, i18n)...
+  return auth(request)
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+}
+```
+
+If the existing logic builds its own response (adds headers, rewrites), run the auth check first and return its answer when it refuses; it lets a request through with status `200`:
+
+```ts
+export default async function proxy(request: NextRequest) {
+  const gate = await auth(request)
+  if (gate.status !== 200) return gate        // redirect to sign-in, or 401
+  // ...existing logic, returning its own response...
+}
+```
 
-Then open `/auth/sign-in` in the browser, sign in, confirm you land on `/`.
+Tell me what you merged.
 
-## Wire it into the code
+**Protected paths.** One line in `b17_auth.yaml` listing what needs sign-in, exact paths or `prefix/*`; everything else is open. `/app/*` covers `/app` and everything below it and nothing beside it (`/apps` stays open).
 
-Wherever the app needs the current user on the server:
+```yaml
+protected: /app/* /account /api/*
+```
+
+Without the key, everything needs sign-in (the default); then `public:` lists the exceptions instead. Never set both.
+
+With `protected:`, static files are open unless their folder is listed. In the default mode, files with an extension outside the list in "How the package works" (for example `.pdf`, `.mp4`) need a session; add their folder to `public:` if signed-out visitors must load them.
+
+## Step 5: Use the session in the code
+
+The proxy only protects pages from opening. Every place that reads or changes data for a user must check the session itself. The session is one JSON shape everywhere:
+
+```json
+{ "user": { "id", "email" }, "organization": { "id", "name" } | null, "authorization": { "role", "permissions": [] } }
+```
+
+**Route handlers (`app/api/**/route.ts`):**
 
 ```ts
-import { requireUser } from "@binary1702/auth/next"
+import { requireSession, requirePermission, unauthorized } from "@binary1702/auth/next"
 
-const user = await requireUser()   // { id, email } or throws AuthError (401)
+export async function GET() {
+  try {
+    const { user, organization } = await requireSession()        // or requirePermission("invoices.read")
+    // ...query data WHERE org_id = organization.id (or owner_id = user.id)...
+    return Response.json(data)
+  } catch (e) {
+    return unauthorized(e)                    // 401 / 403 for auth errors, rethrows anything else
+  }
+}
 ```
 
-`getUser()` returns `null` instead of throwing. Both work in route handlers, server components and server actions.
+Permissions are names the app chooses (`invoices.create`), mapped from roles in `b17_auth.yaml` under `permissions:`. `owner` has everything by default. Memberships come from the CLI (`add-org`, `add-member`). Do not invent a permission system in the app; use `requirePermission()`.
+
+**Server components (pages, layouts):**
+
+```ts
+import { redirect } from "next/navigation"
+import { getUser } from "@binary1702/auth/next"
+
+export default async function Page() {
+  const user = await getUser()
+  if (!user) redirect("/auth/sign-out")       // clears a revoked cookie, lands on sign-in
+  // ...
+}
+```
+
+Use `getUser()` + `redirect` in pages rather than `requireUser()`: `requireUser()` throws, which shows the error page instead of the sign-in page.
+
+**Server actions:** call `requireUser()` at the top of every action. Actions can be called directly, so do not rely on the page having checked.
+
+**Client components:** wrap the root layout once, then read the session anywhere without a request:
+
+```tsx
+// app/layout.tsx (server)
+import { getSession } from "@binary1702/auth/next"
+import { AuthProvider } from "@binary1702/auth/react"
+export default async function Layout({ children }) {
+  return <AuthProvider session={await getSession()}>{children}</AuthProvider>
+}
+
+// any client component
+import { useAuth } from "@binary1702/auth/react"
+const { user, organization, authorization } = useAuth()   // for rendering only; the server still checks
+```
+
+Without React: `fetch("/auth/session")` returns the same shape, or `401`.
+
+Sign-out: a link to `/auth/sign-out`, or `fetch("/auth/sign-out", { method: "POST" })`.
+
+**What the ids are:** `user.id` and `organization.id` are UUIDs and never change; use them as foreign keys in the app's own tables. The package authenticates and tells you the role. What rows a role may touch is the app's query: always filter by `organization.id` and/or `user.id`.
+
+**Do not:**
+- build a sign-in, sign-up, forgot-password or verification page (they exist under `/auth/`)
+- read or parse the `auth_session` cookie yourself; use `getSession()`
+- query or alter the package's tables (`users`, `orgs`, `members`, `tokens`); use the CLI commands below
+- put a secret in `b17_auth.yaml`; secrets go in `.env.local` and the yaml references them as `${NAME}`
+- edit anything in `node_modules/@binary1702/auth`
+
+After the install, `node_modules/@binary1702/auth/AGENTS.md` is the reference for working in the app day to day.
+
+**Custom sign-in form (only if I ask for one):** a page under `/auth/` with a form that POSTs `email`, `password` and optionally `next` to `/auth/sign-in`. It must be served from the same site; cross-site POSTs get `403`.
+
+## Step 6: Settings
+
+Only if I ask for them. All go in `b17_auth.yaml` (the CLI wrote it with comments showing every key). In development changes apply on the next request; in production restart.
+
+| Key | Effect |
+|---|---|
+| `name: Acme` | page titles and email subjects |
+| `signup: open` | anyone can create an account at `/auth/sign-up`; the sign-in page gets a "Create one" link |
+| `signup: invite` + `inviteCode: ${AUTH_INVITE_CODE}` | the sign-up form also requires the code from `.env.local` |
+| `emailDomain: example.com` | sign-up only accepts `@example.com` emails |
+| `requireVerified: true` | no session until the emailed link is clicked (needs email configured) |
+| `protected: /app/* /api/*` | only these need sign-in; everything else is open (default without it: everything needs sign-in, `public:` lists exceptions) |
+| `email:` | Gmail API or Resend; see the README's "Email" section. Keys stay in `.env.local`. |
+| `permissions:` / `organizations:` | role → permissions, and per-organization overrides |
+
+Without `signup`, sign-up is closed, except while the user table is empty: then `/auth/sign-in` sends visitors to create the first account.
+
+`admins: <email>` in `b17_auth.yaml` lets that user open `/auth/admin`, which does everything below from the browser.
+
+User and organization management from the terminal (each asks for anything not given):
+
+```bash
+npx @binary1702/auth add-user [email]
+npx @binary1702/auth set-password [email]          # also signs them out everywhere
+npx @binary1702/auth remove-user [email]           # asks to type the email again
+npx @binary1702/auth sign-out-everywhere [email]
+npx @binary1702/auth list-users
+npx @binary1702/auth add-org <name>
+npx @binary1702/auth add-member <email> <org> [role]   # role defaults to "member"
+npx @binary1702/auth remove-member <email> <org>
+npx @binary1702/auth list-orgs
+```
+
+## Step 7: Verify
+
+Start the dev server (`npm run dev`, or the project's script). Restart it if it was already running, so it loads `.env.local`. Then check with real HTTP requests. Replace `3000` with the actual port. Use the email and password I gave you; do not print the password in your report.
+
+```bash
+B=http://localhost:3000
+curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" $B/
+curl -s -o /dev/null -w "%{http_code}\n" $B/auth/sign-in
+curl -s -w " %{http_code}\n" $B/api/anything
+curl -s -c jar.txt -w " %{http_code}\n" -H "content-type: application/json" \
+  -d '{"email":"<email>","password":"<password>"}' $B/auth/sign-in
+curl -s -b jar.txt $B/auth/session
+curl -s -w " %{http_code}\n" $B/auth/session
+curl -s -b jar.txt -o /dev/null -w "%{http_code}\n" $B/
+curl -s -w " %{http_code}\n" -H "sec-fetch-site: cross-site" -H "content-type: application/json" \
+  -d '{"email":"x@x.com","password":"x"}' $B/auth/sign-in
+curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" "$B/auth/sign-in?next=/%5Cevil.com" -b jar.txt
+curl -s -b jar.txt -o /dev/null -w "%{http_code} %{redirect_url}\n" $B/auth/sign-out
+rm jar.txt
+```
+
+| # | Request | Expect |
+|---|---|---|
+| 1 | `GET /` no cookie | `307` to `/auth/sign-in` (or `200` if `/` is in your public list) |
+| 2 | `GET /auth/sign-in` | `200` (or `307` to `/auth/sign-up` if there are no users yet) |
+| 3 | `GET /api/anything` no cookie | `401` `{"error":"Unauthorized"}` |
+| 4 | `POST /auth/sign-in` JSON | `200` `{"user":{...}}`; `jar.txt` contains `auth_session` |
+| 5 | `GET /auth/session` with cookie | `{"user":{"id":"…","email":"…"},"organization":null,"authorization":{"role":null,"permissions":[]}}` (organization and role filled in once the user is in one) |
+| 5b | `GET /auth/session` no cookie | `401` `{"error":"Unauthorized"}` |
+| 6 | `GET /` with cookie | the page's normal status, not a redirect to sign-in |
+| 7 | cross-site `POST /auth/sign-in` | `403` `{"error":"Cross-site request refused"}` |
+| 8 | sign-in page with `next=/\evil.com`, signed in | redirect to `/` on this site, never to `evil.com` |
+| 9 | `GET /auth/sign-out` | `303` to `/auth/sign-in` |
+
+Also check, by request or in the browser:
+- each public page from Step 4 opens signed out; a page next to it that is not public redirects
+- an image from `public/` loads on the sign-in page and on public pages
+- open `/auth/sign-in` in a browser, sign in, confirm you land on `/` (or on the `next` page)
+
+If something does not match:
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| everything opens without signing in | Next 15 with `proxy.ts`; or proxy file in the wrong folder | Step 4; the file must be `src/proxy.ts` when the app is in `src/app/`, root `proxy.ts` when it is in `app/` |
+| `500` with `AUTH_SECRET is missing` | dev server started before `.env.local` was written | restart the dev server |
+| `500` with a database error | wrong `DATABASE_URL`, not a Neon URL | check the URL with me |
+| `403 Cross-site request refused` from the app's own form | form or fetch served from a different origin/port than the app | serve it from the same origin |
+| images or fonts redirect to sign-in | default mode and the extension is not in the static list | add the folder to `public:`, or switch to `protected:` |
+| page shows the error screen when signed out | page uses `requireUser()` / `requireSession()` | use `getUser()` / `getSession()` + `redirect` (Step 5) |
+| signed in, but pages still say signed out | user was removed or password changed after sign-in; or `requireVerified` is on and the email is unverified | sign out and in again; or follow the verification link |
+| `b17_auth.yaml line N: …` on start | a typo in the settings file | fix that line; the message names the key |
+| `… refers to ${NAME}, which is not set` | the yaml references a variable missing from `.env.local` | add it, restart |
+
+## Step 8: Deploy
 
-For sign-out, link to `/auth/sign-out`. For client code, `fetch("/auth/session")`.
+Copy every variable in `.env.local` (`DATABASE_URL`, `AUTH_SECRET`, the email variables such as `AUTH_GMAIL_CLIENT_EMAIL` + `AUTH_GMAIL_PRIVATE_KEY` or `AUTH_RESEND_API_KEY`, `AUTH_INVITE_CODE` if used) into the host's environment variables (Vercel: Project Settings → Environment Variables). `b17_auth.yaml` is committed with the code and needs nothing. Do not paste the values into your report or a commit.
 
-Do not build a sign-up page. One exists at `/auth/sign-up`. It is closed by default (except for the very first user on an empty install). To let people register, add `AUTH_SIGNUP=open` to `.env.local`, optionally with `AUTH_INVITE_CODE=<code>` to require a code on the form. Users can also be created with `npx @binary1702/auth add-user`.
+- Use the same `AUTH_SECRET` for every instance of the app; changing it signs everyone out.
+- If production uses a different database than development, the table is created on the first request but has no users, and while it is empty the first visitor can create the first account. Tell me right after the deploy, so I open `/auth/sign-in` on the live site and create my account before anyone else does. (Running `add-user` locally does not help: the CLI uses the `DATABASE_URL` in `.env.local`, which is the development database.)
+- In production the cookie is `__Host-auth_session`: `Secure`, path `/`, no domain. The site must be served over HTTPS, and the cookie cannot be shared with a subdomain (that is the point).
 
-## Deploy
+## Step 9: Report
 
-Copy `DATABASE_URL` and `AUTH_SECRET` from `.env.local` into the host's environment. Nothing else.
+Tell me, in order:
 
-## Report
+1. each check from Step 1 and its result
+2. each installer line from Step 2: done, skipped, or failed (error text verbatim)
+3. what you changed in Step 4 and why (Next 15 rename, merge, public paths)
+4. every file you changed in Step 5
+5. each row of the Step 7 table with the actual status code, and the extra checks
+6. anything that took more steps than this guide says, or did not match it
 
-Tell me, in order: each install step and whether it was done or skipped, each verify row with the actual status code, anything that failed with the error text verbatim, and anything that took more steps than it should. Do not modify the package itself, only this project.
+Never include `AUTH_SECRET`, `DATABASE_URL` or any password in the report. Do not modify the package itself, only this project.
 
 Docs: https://www.npmjs.com/package/@binary1702/auth