@binary1702/auth 0.0.0-stage → 0.1.1

package/INSTALL.md

@@ -0,0 +1,47 @@
+# Install
+
+Inside a Next.js project (App Router):
+
+```bash
+npx @binary1702/auth
+```
+
+That is the whole install. It asks for your Postgres connection string once, then does everything else:
+
+```
+✓ @binary1702/auth installed
+✓ DATABASE_URL → .env.local
+✓ AUTH_SECRET generated → .env.local
+✓ app/auth/[...path]/route.ts
+✓ proxy.ts
+✓ auth_users table ready
+✓ user "ben" created
+```
+
+Safe to run again. It only does what is left.
+
+## Use it
+
+Every page and API route is now behind sign-in. Get the user anywhere on the server:
+
+```ts
+import { requireUser } from "@binary1702/auth/next"
+
+const user = await requireUser()   // { id, username } or throws 401
+```
+
+## URLs you get
+
+| URL | |
+|---|---|
+| `/auth/sign-in` | sign-in page |
+| `/auth/sign-out` | clears the session |
+| `/auth/session` | `{ user }` as JSON, for client code |
+
+## More users
+
+```bash
+npx @binary1702/auth add-user
+npx @binary1702/auth set-password
+npx @binary1702/auth list-users
+```

package/PROMPT.md

@@ -0,0 +1,80 @@
+# Agent prompt: install @binary1702/auth
+
+Copy everything below the line into an AI coding agent running inside the Next.js project.
+
+---
+
+Install `@binary1702/auth` in this project. It adds username + password auth to a Next.js App Router app. Follow these steps exactly and report the result of each.
+
+## Before you start
+
+Check these and stop if any fails:
+
+- `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.
+
+## Install
+
+Run, in the project root:
+
+```bash
+npx @binary1702/auth
+```
+
+It is interactive. It asks for the Postgres connection string, then a username and a password for the first user. If you cannot answer prompts, run it and hand control to me.
+
+It does the following, skipping anything already done:
+
+```
+✓ @binary1702/auth installed             → package.json
+✓ DATABASE_URL → .env.local
+✓ AUTH_SECRET generated → .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
+✓ user "<name>" 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.
+
+## Verify
+
+Start the dev server and check with real HTTP requests:
+
+| 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 `{ "username", "password" }` | 200 `{ user }` and `Set-Cookie: auth_session=…; HttpOnly` |
+| `GET /auth/session` with that cookie | `{ user: { id, username } }` |
+| `GET /auth/sign-out` | cookie cleared, redirect to sign-in |
+
+Then open `/auth/sign-in` in the browser, sign in, confirm you land on `/`.
+
+## Wire it into the code
+
+Wherever the app needs the current user on the server:
+
+```ts
+import { requireUser } from "@binary1702/auth/next"
+
+const user = await requireUser()   // { id, username } or throws AuthError (401)
+```
+
+`getUser()` returns `null` instead of throwing. Both work in route handlers, server components and server actions.
+
+For sign-out, link to `/auth/sign-out`. For client code, `fetch("/auth/session")`.
+
+Do not build a sign-up page. Users are created with `npx @binary1702/auth add-user`.
+
+## Deploy
+
+Copy `DATABASE_URL` and `AUTH_SECRET` from `.env.local` into the host's environment. Nothing else.
+
+## Report
+
+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.
+
+Docs: https://www.npmjs.com/package/@binary1702/auth

package/README.md

@@ -1,3 +1,244 @@
-# Temporary Holding Version
+# @binary1702/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Username + password auth for Next.js. Plug and play.
+
+```bash
+npx @binary1702/auth
+```
+
+One command. It installs itself, writes two env vars, writes two files, creates the table, creates your first user. Then you move on.
+
+Letting an AI agent do the install? Paste [PROMPT.md](./PROMPT.md) into it. Same steps, written for an agent, with the checks to run and what to report back. [INSTALL.md](./INSTALL.md) is the short human version.
+
+---
+
+## Quick start (new project)
+
+```bash
+npx create-next-app my-app
+cd my-app
+npx @binary1702/auth
+```
+
+You will be asked for one thing: your Postgres connection string (Neon). Everything else is automatic.
+
+```
+@binary1702/auth
+
+  ✓ @binary1702/auth installed
+  ✓ DATABASE_URL → .env.local
+  ✓ AUTH_SECRET generated → .env.local
+  ✓ app/auth/[...path]/route.ts
+  ✓ proxy.ts
+  ✓ auth_users table ready
+
+  Create the first user:
+  Username: ben
+  Password:
+  Password again:
+  ✓ user "ben" created
+
+Done. Start the dev server and open /auth/sign-in.
+```
+
+Run `npm run dev`, open the site, you are redirected to the sign-in page. Sign in. Done.
+
+**Safe to re-run.** Each step is skipped if it is already done. Running it again on a finished project just offers to add another user.
+
+---
+
+## Use it in your code
+
+Every page and API route is now behind sign-in. To know who the user is:
+
+```ts
+import { requireUser } from "@binary1702/auth/next"
+
+export async function GET() {
+  const user = await requireUser()   // { id, username }
+  // ...
+}
+```
+
+That is the only line you ever write by hand.
+
+```ts
+import { getUser } from "@binary1702/auth/next"
+
+const user = await getUser()   // { id, username } or null, never throws
+```
+
+Works in route handlers, server components, and server actions.
+
+---
+
+## What you get
+
+| URL | What it does |
+|---|---|
+| `/auth/sign-in` | The sign-in page. Served by the package, no React, no styling work. |
+| `/auth/sign-out` | Clears the session and sends you back to sign-in. Link to it. |
+| `/auth/session` | `{ user }` or `{ user: null }` as JSON, for client code. |
+
+Everything else on the site requires a session. Unauthenticated page requests redirect to `/auth/sign-in?next=<where they were going>`. Unauthenticated `/api/*` requests get a `401` JSON response.
+
+---
+
+## Managing users
+
+There is no sign-up page. Users are created from the terminal.
+
+```bash
+npx @binary1702/auth add-user           # prompts for username and password
+npx @binary1702/auth add-user gladys    # username given
+npx @binary1702/auth set-password ben
+npx @binary1702/auth list-users
+```
+
+---
+
+## The two files it wrote
+
+You do not need to touch these. Here is what they are, for when you are curious.
+
+**`app/auth/[...path]/route.ts`** mounts the handlers.
+
+```ts
+export { GET, POST } from "@binary1702/auth/next"
+```
+
+**`proxy.ts`** guards every request. (On Next 15 this file is called `middleware.ts`. Same content.)
+
+```ts
+import { proxy } from "@binary1702/auth/next/proxy"
+
+export default proxy
+
+export const config = {
+  matcher: ["/((?!auth|_next/static|_next/image|favicon.ico|.*\\..*).*)"],
+}
+```
+
+The matcher is inline because Next reads it statically at build time and ignores a re-exported one.
+
+If you already had a `proxy.ts`, the CLI leaves it alone and prints the snippet for you to merge.
+
+---
+
+## Env vars
+
+| Var | What | Who sets it |
+|---|---|---|
+| `DATABASE_URL` | Postgres connection string | You, once, when the CLI asks |
+| `AUTH_SECRET` | Signs the session cookie | The CLI generates it |
+
+Both live in `.env.local`. Copy both to your host (Vercel, etc.) when you deploy.
+
+Rotating `AUTH_SECRET` signs everyone out. That is the revoke-all button.
+
+---
+
+## How it works
+
+Five primitives around one cookie. Nothing else.
+
+```
+auth_users (id, username, password_hash, created_at)   identity   one table, owned by the package
+scrypt                                                  proof      node:crypto, no dependency
+signed JWT in an httpOnly cookie, 7 days                session    stateless, zero DB reads per request
+proxy.ts                                                guard      verifies the cookie signature only
+/auth/sign-in  /auth/sign-out  /auth/session            lifecycle  one route file
+```
+
+```
+Request
+  ├─ proxy.ts         cookie valid? → continue   else → redirect (page) or 401 (api)
+  ├─ /auth/sign-in    POST username+password → verify hash → set cookie → redirect
+  └─ your route       requireUser() → reads cookie → { id, username }
+```
+
+**Authentication only.** The package tells you `user.id`. What that user may see or edit is your app's job. Keeping that boundary is what keeps this package small enough to never break.
+
+**Trade-off you should know.** The session is a signed token, not a database row. That is why the proxy costs nothing per request. The cost is that one session cannot be revoked before it expires. Change `AUTH_SECRET` to revoke all of them.
+
+---
+
+## API reference
+
+### `@binary1702/auth/next`
+
+| Export | |
+|---|---|
+| `GET`, `POST` | Route handlers. Mount at `app/auth/[...path]/route.ts`. |
+| `requireUser()` | `Promise<{ id, username }>`. Throws `AuthError` (status 401) if signed out. |
+| `getUser()` | `Promise<{ id, username } \| null>`. Never throws. |
+| `unauthorized(err)` | Turns an `AuthError` into a 401 JSON response. Rethrows anything else. |
+| `AuthError` | The error class. Has `.status = 401`. |
+
+### `@binary1702/auth/next/proxy`
+
+| Export | |
+|---|---|
+| `proxy` | The guard function. Default export too. |
+| `MATCHER` | The matcher array, for reference. Next needs it written inline in your file. |
+
+### `@binary1702/auth` (framework-free core)
+
+For building your own handlers or using the primitives outside Next.
+
+| Export | |
+|---|---|
+| `hashPassword(pw)`, `verifyPassword(pw, hash)` | scrypt |
+| `signSession(user, secret)`, `verifySession(token, secret)` | JWT HS256 |
+| `ensureSchema()`, `findUser()`, `createUser()`, `countUsers()`, `listUsers()`, `setPassword()` | Database |
+| `signInPage({ error?, next?, title? })` | The HTML form as a string |
+| `COOKIE_NAME`, `SESSION_DAYS`, `SIGN_IN_PATH`, `SIGN_OUT_PATH` | Constants |
+
+---
+
+## Client-side usage
+
+No client library. Plain HTTP.
+
+```ts
+// who am I
+const { user } = await fetch("/auth/session").then((r) => r.json())
+
+// sign in from a custom form
+await fetch("/auth/sign-in", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ username, password }),
+})   // 200 { user } or 401 { error }
+
+// sign out
+await fetch("/auth/sign-out", { method: "POST" })
+```
+
+Or just link to `/auth/sign-out`.
+
+---
+
+## Custom sign-in page
+
+The built-in page is plain HTML with light and dark mode. If you want your own, make any page with a form that POSTs `username` and `password` to `/auth/sign-in`, and put it anywhere under `/auth/` so the proxy lets it through. Optional hidden field `next` for where to go after.
+
+---
+
+## Requirements
+
+- Next.js 15 or 16, App Router
+- Node 20+
+- A Postgres database (built for Neon, works with any Postgres that the Neon serverless driver can reach)
+
+---
+
+## Development
+
+```bash
+npm install
+npm test          # core primitives, no database needed
+npm run build     # tsc → dist/
+```
+
+Release: `npm version <patch|minor|major> && npm publish && git push --follow-tags`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────
+// npx @binary1702/auth
+//
+// One command. Each step is skipped if already done, so it is
+// safe to run again at any time.
+//
+//   1. install the package into the project
+//   2. DATABASE_URL  → prompt, write .env.local
+//   3. AUTH_SECRET   → generate, write .env.local
+//   4. app/auth/[...path]/route.ts
+//   5. proxy.ts
+//   6. create auth_users table
+//   7. create the first user
+//
+// Subcommands:
+//   add-user [name]       create another user
+//   set-password [name]   change a password
+//   list-users
+// ─────────────────────────────────────────────────────────────
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { stdin, stdout } from "node:process";
+const PKG = "@binary1702/auth";
+const cwd = process.cwd();
+// ── output ────────────────────────────────────────────────────
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+const done = (msg) => console.log(`  ${c.green("✓")} ${msg}`);
+const skip = (msg) => console.log(`  ${c.dim("·")} ${c.dim(msg)}`);
+const fail = (msg) => {
+    console.error(`\n  ${c.red("✗")} ${msg}\n`);
+    process.exit(1);
+};
+// ── prompts ───────────────────────────────────────────────────
+// One readline for the whole run, with every incoming line queued.
+// readline emits all buffered lines at once (piped stdin, pasted text),
+// so a question registered after that burst would otherwise see nothing.
+let _rl = null;
+let muted = false;
+let inputClosed = false;
+const lines = [];
+const waiters = [];
+function rl() {
+    if (_rl)
+        return _rl;
+    _rl = createInterface({ input: stdin, output: stdout, terminal: stdin.isTTY ?? false });
+    // Echo nothing while a password is being typed (terminal mode only).
+    const anyRl = _rl;
+    anyRl._writeToOutput = (s) => {
+        if (!muted)
+            stdout.write(s);
+    };
+    _rl.on("line", (line) => {
+        const w = waiters.shift();
+        w ? w(line) : lines.push(line);
+    });
+    _rl.on("close", () => {
+        inputClosed = true;
+        while (waiters.length)
+            waiters.shift()(null);
+    });
+    return _rl;
+}
+function closePrompts() {
+    _rl?.close();
+    _rl = null;
+}
+async function ask(question, opts = {}) {
+    rl();
+    const suffix = opts.default ? c.dim(` (${opts.default})`) : "";
+    stdout.write(`  ${question}${suffix}: `);
+    if (opts.hidden)
+        muted = true;
+    const line = lines.length > 0
+        ? lines.shift()
+        : inputClosed
+            ? null
+            : await new Promise((res) => waiters.push(res));
+    if (opts.hidden) {
+        muted = false;
+        stdout.write("\n");
+    }
+    if (line === null)
+        return fail("Input ended before all prompts were answered.");
+    return opts.hidden ? line : line.trim() || opts.default || "";
+}
+// ── env file ──────────────────────────────────────────────────
+const ENV_FILE = join(cwd, ".env.local");
+function readEnv() {
+    const out = {};
+    if (!existsSync(ENV_FILE))
+        return out;
+    for (const line of readFileSync(ENV_FILE, "utf8").split("\n")) {
+        const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+        if (m)
+            out[m[1]] = m[2].replace(/^["']|["']$/g, "");
+    }
+    return out;
+}
+function writeEnv(key, value) {
+    const prefix = existsSync(ENV_FILE) && !readFileSync(ENV_FILE, "utf8").endsWith("\n") && readFileSync(ENV_FILE, "utf8").length > 0 ? "\n" : "";
+    appendFileSync(ENV_FILE, `${prefix}${key}=${value}\n`);
+    process.env[key] = value;
+}
+// ── files the consumer needs ──────────────────────────────────
+const ROUTE_FILE = `export { GET, POST } from "${PKG}/next"\n`;
+const PROXY_FILE = `import { proxy } from "${PKG}/next/proxy"
+
+export default proxy
+
+// Everything except the auth pages, Next internals, and static files.
+export const config = {
+  matcher: ["/((?!auth|_next/static|_next/image|favicon.ico|.*\\\\..*).*)"],
+}
+`;
+function writeIfMissing(rel, content) {
+    const abs = join(cwd, rel);
+    if (existsSync(abs)) {
+        skip(`${rel} exists`);
+        return false;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    done(rel);
+    return true;
+}
+// ── steps ─────────────────────────────────────────────────────
+function stepProject() {
+    if (!existsSync(join(cwd, "package.json"))) {
+        fail(`No package.json here. Run this inside your Next.js project:\n    npx create-next-app my-app && cd my-app && npx ${PKG}`);
+    }
+    if (existsSync(join(cwd, "src", "app")))
+        return { appDir: "src/app", src: true };
+    if (existsSync(join(cwd, "app")))
+        return { appDir: "app", src: false };
+    return fail(`No app/ directory. ${PKG} needs the Next.js App Router.`);
+}
+function stepInstall() {
+    if (existsSync(join(cwd, "node_modules", ...PKG.split("/")))) {
+        skip(`${PKG} installed`);
+        return;
+    }
+    console.log(`  ${c.dim(`npm install ${PKG}`)}`);
+    const r = spawnSync("npm", ["install", PKG], { cwd, stdio: "inherit" });
+    if (r.status !== 0)
+        fail(`npm install ${PKG} failed`);
+    done(`${PKG} installed`);
+}
+async function stepEnv() {
+    const env = readEnv();
+    if (env.DATABASE_URL) {
+        process.env.DATABASE_URL = env.DATABASE_URL;
+        skip("DATABASE_URL set");
+    }
+    else {
+        const guess = process.env.DATABASE_URL ?? env.NEON_DATABASE_URL ?? process.env.NEON_DATABASE_URL;
+        const url = await ask("Postgres connection string (DATABASE_URL)", { default: guess });
+        if (!url.startsWith("postgres"))
+            fail("That does not look like a postgres:// URL.");
+        writeEnv("DATABASE_URL", url);
+        done("DATABASE_URL → .env.local");
+    }
+    if (env.AUTH_SECRET) {
+        process.env.AUTH_SECRET = env.AUTH_SECRET;
+        skip("AUTH_SECRET set");
+    }
+    else {
+        writeEnv("AUTH_SECRET", randomBytes(32).toString("base64url"));
+        done("AUTH_SECRET generated → .env.local");
+    }
+}
+function stepFiles(appDir, src) {
+    writeIfMissing(`${appDir}/auth/[...path]/route.ts`, ROUTE_FILE);
+    const proxyPath = src ? "src/proxy.ts" : "proxy.ts";
+    const legacy = [src ? "src/middleware.ts" : "middleware.ts", proxyPath].filter((p) => existsSync(join(cwd, p)));
+    if (legacy.length) {
+        skip(`${legacy[0]} exists, not touched. Add to it:`);
+        console.log(c.dim(PROXY_FILE.replace(/^/gm, "      ")));
+        return;
+    }
+    writeIfMissing(proxyPath, PROXY_FILE);
+}
+async function db() {
+    // Imported lazily: needs DATABASE_URL in process.env first.
+    return import("./core/db.js");
+}
+async function stepSchema() {
+    const { ensureSchema } = await db();
+    await ensureSchema().catch((e) => fail(`Could not reach the database: ${e.message}`));
+    done("auth_users table ready");
+}
+async function createUserInteractive(presetName) {
+    const { createUser, findUser } = await db();
+    const { hashPassword } = await import("./core/password.js");
+    const username = presetName ?? (await ask("Username"));
+    if (!username)
+        fail("Username is required.");
+    if (await findUser(username))
+        fail(`User "${username}" already exists.`);
+    const password = await ask("Password", { hidden: true });
+    if (password.length < 8)
+        fail("Password must be at least 8 characters.");
+    const again = await ask("Password again", { hidden: true });
+    if (password !== again)
+        fail("Passwords do not match.");
+    await createUser(username, await hashPassword(password));
+    done(`user "${username}" created`);
+}
+async function stepFirstUser() {
+    const { countUsers } = await db();
+    const n = await countUsers();
+    if (n > 0) {
+        skip(`${n} user${n === 1 ? "" : "s"} exist`);
+        return;
+    }
+    console.log("\n  Create the first user:");
+    await createUserInteractive();
+}
+function finish() {
+    console.log(`
+${c.bold("Done.")} Start the dev server and open ${c.bold("/auth/sign-in")}.
+
+Get the user in any route or server component:
+
+  import { requireUser } from "${PKG}/next"
+  const user = await requireUser()   // { id, username }
+
+Add users later:  npx ${PKG} add-user
+`);
+}
+// ── main ──────────────────────────────────────────────────────
+async function main() {
+    const [cmd, arg] = process.argv.slice(2);
+    console.log(`\n${c.bold(PKG)}\n`);
+    if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+        console.log(`  npx ${PKG}                    set up auth in this project (safe to re-run)
+  npx ${PKG} add-user [name]    create a user
+  npx ${PKG} set-password [name]
+  npx ${PKG} list-users
+`);
+        return;
+    }
+    stepProject();
+    if (cmd === "add-user" || cmd === "set-password" || cmd === "list-users") {
+        await stepEnv();
+        const d = await db();
+        if (cmd === "add-user")
+            await createUserInteractive(arg);
+        if (cmd === "list-users") {
+            for (const u of await d.listUsers())
+                console.log(`  ${u.username}  ${c.dim(u.id)}`);
+        }
+        if (cmd === "set-password") {
+            const username = arg ?? (await ask("Username"));
+            const password = await ask("New password", { hidden: true });
+            if (password.length < 8)
+                fail("Password must be at least 8 characters.");
+            const { hashPassword } = await import("./core/password.js");
+            const ok = await d.setPassword(username, await hashPassword(password));
+            ok ? done(`password updated for "${username}"`) : fail(`No user "${username}".`);
+        }
+        console.log();
+        return;
+    }
+    if (cmd)
+        fail(`Unknown command "${cmd}". Try: npx ${PKG} help`);
+    const { appDir, src } = stepProject();
+    stepInstall();
+    await stepEnv();
+    stepFiles(appDir, src);
+    await stepSchema();
+    await stepFirstUser();
+    finish();
+}
+main()
+    .catch((e) => fail(e instanceof Error ? e.message : String(e)))
+    .finally(closePrompts);

package/dist/core/config.d.ts

@@ -0,0 +1,7 @@
+export declare const COOKIE_NAME = "auth_session";
+export declare const SESSION_DAYS = 7;
+export declare const SIGN_IN_PATH = "/auth/sign-in";
+export declare const SIGN_OUT_PATH = "/auth/sign-out";
+export declare const TABLE = "auth_users";
+export declare function getSecret(): string;
+export declare function getDatabaseUrl(): string;

package/dist/core/config.js

@@ -0,0 +1,25 @@
+// ─────────────────────────────────────────────────────────────
+// Configuration. Two env vars, nothing else.
+//
+//   DATABASE_URL  Postgres connection string (Neon)
+//   AUTH_SECRET   signs the session cookie; generated by the CLI
+// ─────────────────────────────────────────────────────────────
+export const COOKIE_NAME = "auth_session";
+export const SESSION_DAYS = 7;
+export const SIGN_IN_PATH = "/auth/sign-in";
+export const SIGN_OUT_PATH = "/auth/sign-out";
+export const TABLE = "auth_users";
+export function getSecret() {
+    const secret = process.env.AUTH_SECRET;
+    if (!secret || secret.length < 16) {
+        throw new Error("AUTH_SECRET is missing. Run: npx @binary1702/auth");
+    }
+    return secret;
+}
+export function getDatabaseUrl() {
+    const url = process.env.DATABASE_URL;
+    if (!url) {
+        throw new Error("DATABASE_URL is missing. Run: npx @binary1702/auth");
+    }
+    return url;
+}

package/dist/core/db.d.ts

@@ -0,0 +1,16 @@
+import { TABLE } from "./config.ts";
+import type { User } from "./session.ts";
+export declare function ensureSchema(): Promise<void>;
+type Row = {
+    id: string;
+    username: string;
+    password_hash: string;
+};
+export declare function findUser(username: string): Promise<Row | null>;
+export declare function createUser(username: string, passwordHash: string): Promise<User>;
+export declare function countUsers(): Promise<number>;
+export declare function listUsers(): Promise<(User & {
+    created_at: string;
+})[]>;
+export declare function setPassword(username: string, passwordHash: string): Promise<boolean>;
+export { TABLE };

package/dist/core/db.js

@@ -0,0 +1,65 @@
+// ─────────────────────────────────────────────────────────────
+// Storage. One table, owned by this package.
+//
+//   auth_users (id, username, password_hash, created_at)
+//
+// ensureSchema() is idempotent and memoized per process, so route
+// handlers can call it on every request for free after the first.
+// ─────────────────────────────────────────────────────────────
+import { neon } from "@neondatabase/serverless";
+import { getDatabaseUrl, TABLE } from "./config.js";
+let _sql = null;
+function sql() {
+    return (_sql ??= neon(getDatabaseUrl()));
+}
+let _schema = null;
+export function ensureSchema() {
+    return (_schema ??= (async () => {
+        await sql() `
+      CREATE TABLE IF NOT EXISTS auth_users (
+        id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        username      TEXT NOT NULL UNIQUE,
+        password_hash TEXT NOT NULL,
+        created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+      )
+    `;
+    })().catch((err) => {
+        _schema = null; // let the next call retry
+        throw err;
+    }));
+}
+export async function findUser(username) {
+    await ensureSchema();
+    const rows = (await sql() `
+    SELECT id, username, password_hash FROM auth_users WHERE username = ${username}
+  `);
+    return rows[0] ?? null;
+}
+export async function createUser(username, passwordHash) {
+    await ensureSchema();
+    const [row] = (await sql() `
+    INSERT INTO auth_users (username, password_hash)
+    VALUES (${username}, ${passwordHash})
+    RETURNING id, username
+  `);
+    return row;
+}
+export async function countUsers() {
+    await ensureSchema();
+    const [row] = (await sql() `SELECT COUNT(*)::int AS n FROM auth_users`);
+    return row.n;
+}
+export async function listUsers() {
+    await ensureSchema();
+    return (await sql() `
+    SELECT id, username, created_at FROM auth_users ORDER BY created_at
+  `);
+}
+export async function setPassword(username, passwordHash) {
+    await ensureSchema();
+    const rows = (await sql() `
+    UPDATE auth_users SET password_hash = ${passwordHash} WHERE username = ${username} RETURNING id
+  `);
+    return rows.length > 0;
+}
+export { TABLE };

package/dist/core/html.d.ts

@@ -0,0 +1,5 @@
+export declare function signInPage(opts?: {
+    error?: string;
+    next?: string;
+    title?: string;
+}): string;

package/dist/core/html.js

@@ -0,0 +1,43 @@
+// ─────────────────────────────────────────────────────────────
+// The sign-in page. Plain HTML served by the route handler,
+// so the consumer never builds a form or a page.
+// ─────────────────────────────────────────────────────────────
+import { SIGN_IN_PATH } from "./config.js";
+const escape = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export function signInPage(opts = {}) {
+    const title = escape(opts.title ?? "Sign in");
+    const next = escape(opts.next ?? "/");
+    const error = opts.error ? `<p class="error">${escape(opts.error)}</p>` : "";
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+  :root { color-scheme: light dark; --fg: #111; --bg: #fff; --line: #ddd; --muted: #666; --err: #c0392b; }
+  @media (prefers-color-scheme: dark) { :root { --fg: #eee; --bg: #111; --line: #333; --muted: #999; --err: #ff6b6b; } }
+  * { box-sizing: border-box; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: var(--bg); color: var(--fg);
+         font: 15px/1.4 system-ui, -apple-system, sans-serif; }
+  form { width: 100%; max-width: 320px; padding: 16px; display: grid; gap: 12px; }
+  h1 { font-size: 18px; font-weight: 600; margin: 0 0 4px; }
+  label { display: grid; gap: 4px; font-size: 13px; color: var(--muted); }
+  input { font: inherit; padding: 8px 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--fg); }
+  input:focus { outline: 2px solid var(--fg); outline-offset: 1px; }
+  button { font: inherit; font-weight: 500; padding: 9px; border: 0; border-radius: 6px; background: var(--fg); color: var(--bg); cursor: pointer; }
+  .error { margin: 0; font-size: 13px; color: var(--err); }
+</style>
+</head>
+<body>
+<form method="post" action="${SIGN_IN_PATH}">
+  <h1>${title}</h1>
+  ${error}
+  <label>Username <input name="username" autocomplete="username" autofocus required></label>
+  <label>Password <input name="password" type="password" autocomplete="current-password" required></label>
+  <input type="hidden" name="next" value="${next}">
+  <button type="submit">Sign in</button>
+</form>
+</body>
+</html>`;
+}

package/dist/core/password.d.ts

@@ -0,0 +1,2 @@
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, stored: string): Promise<boolean>;

package/dist/core/password.js

@@ -0,0 +1,32 @@
+// ─────────────────────────────────────────────────────────────
+// Password hashing. scrypt from node:crypto, no dependency.
+//
+// Stored format:  scrypt$N$r$p$<salt b64url>$<hash b64url>
+// Parameters live in the string, so they can be raised later
+// without invalidating existing rows.
+// ─────────────────────────────────────────────────────────────
+import { randomBytes, scrypt as scryptCb, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+const scrypt = promisify(scryptCb);
+const N = 16384;
+const R = 8;
+const P = 1;
+const KEYLEN = 64;
+function run(password, salt, n, r, p) {
+    return scrypt(password, salt, KEYLEN, { N: n, r, p, maxmem: 256 * n * r });
+}
+export async function hashPassword(password) {
+    const salt = randomBytes(16);
+    const hash = await run(password, salt, N, R, P);
+    return ["scrypt", N, R, P, salt.toString("base64url"), hash.toString("base64url")].join("$");
+}
+export async function verifyPassword(password, stored) {
+    const parts = stored.split("$");
+    if (parts.length !== 6 || parts[0] !== "scrypt")
+        return false;
+    const [, n, r, p, saltB64, hashB64] = parts;
+    const salt = Buffer.from(saltB64, "base64url");
+    const expected = Buffer.from(hashB64, "base64url");
+    const actual = await run(password, salt, Number(n), Number(r), Number(p));
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}

package/dist/core/session.d.ts

@@ -0,0 +1,6 @@
+export type User = {
+    id: string;
+    username: string;
+};
+export declare function signSession(user: User, secret: string): Promise<string>;
+export declare function verifySession(token: string, secret: string): Promise<User | null>;

package/dist/core/session.js

@@ -0,0 +1,29 @@
+// ─────────────────────────────────────────────────────────────
+// Session token. A signed JWT (HS256) carried in an httpOnly cookie.
+//
+// Stateless: verifying needs the secret only, never the database.
+// That is what lets the proxy run on every request at zero cost.
+// Trade-off: a token cannot be revoked before it expires (7 days).
+// ─────────────────────────────────────────────────────────────
+import { SignJWT, jwtVerify } from "jose";
+import { SESSION_DAYS } from "./config.js";
+const key = (secret) => new TextEncoder().encode(secret);
+export async function signSession(user, secret) {
+    return new SignJWT({ username: user.username })
+        .setProtectedHeader({ alg: "HS256" })
+        .setSubject(user.id)
+        .setIssuedAt()
+        .setExpirationTime(`${SESSION_DAYS}d`)
+        .sign(key(secret));
+}
+export async function verifySession(token, secret) {
+    try {
+        const { payload } = await jwtVerify(token, key(secret), { algorithms: ["HS256"] });
+        if (typeof payload.sub !== "string" || typeof payload.username !== "string")
+            return null;
+        return { id: payload.sub, username: payload.username };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { hashPassword, verifyPassword } from "./core/password.ts";
+export { signSession, verifySession, type User } from "./core/session.ts";
+export { ensureSchema, findUser, createUser, countUsers, listUsers, setPassword } from "./core/db.ts";
+export { signInPage } from "./core/html.ts";
+export { COOKIE_NAME, SESSION_DAYS, SIGN_IN_PATH, SIGN_OUT_PATH, getSecret, getDatabaseUrl } from "./core/config.ts";

package/dist/index.js

@@ -0,0 +1,7 @@
+// Core primitives. Framework-free. Use these if you are not on Next.js
+// or want to build your own handlers.
+export { hashPassword, verifyPassword } from "./core/password.js";
+export { signSession, verifySession } from "./core/session.js";
+export { ensureSchema, findUser, createUser, countUsers, listUsers, setPassword } from "./core/db.js";
+export { signInPage } from "./core/html.js";
+export { COOKIE_NAME, SESSION_DAYS, SIGN_IN_PATH, SIGN_OUT_PATH, getSecret, getDatabaseUrl } from "./core/config.js";

package/dist/next/index.d.ts

@@ -0,0 +1,20 @@
+import { NextResponse, type NextRequest } from "next/server.js";
+import { type User } from "../core/session.ts";
+export type { User };
+export declare class AuthError extends Error {
+    status: number;
+    constructor(message?: string);
+}
+/** Current user from the session cookie, or null. Never touches the database. */
+export declare function getUser(): Promise<User | null>;
+/** Current user, or throw AuthError (status 401). */
+export declare function requireUser(): Promise<User>;
+/** A 401 JSON response for catch blocks: `catch (e) { return unauthorized(e) }` */
+export declare function unauthorized(err?: unknown): NextResponse;
+type Ctx = {
+    params: Promise<{
+        path: string[];
+    }>;
+};
+export declare function GET(req: NextRequest, ctx: Ctx): Promise<NextResponse>;
+export declare function POST(req: NextRequest, ctx: Ctx): Promise<NextResponse>;

package/dist/next/index.js

@@ -0,0 +1,135 @@
+// ─────────────────────────────────────────────────────────────
+// Next.js route handlers + helpers.
+//
+// Mount once:   app/auth/[...path]/route.ts
+//               export { GET, POST } from "@binary1702/auth/next"
+//
+// Serves:
+//   GET  /auth/sign-in    the sign-in page
+//   POST /auth/sign-in    verify, set cookie, redirect to ?next or /
+//   GET  /auth/sign-out   clear cookie, redirect to sign-in
+//   POST /auth/sign-out   same (for fetch callers)
+//   GET  /auth/session    { user } or { user: null }
+//
+// Use anywhere on the server:
+//   const user = await requireUser()   // { id, username } or throws AuthError(401)
+//   const user = await getUser()       // { id, username } or null
+// ─────────────────────────────────────────────────────────────
+import { cookies } from "next/headers.js";
+import { NextResponse } from "next/server.js";
+import { COOKIE_NAME, SESSION_DAYS, SIGN_IN_PATH, getSecret } from "../core/config.js";
+import { signSession, verifySession } from "../core/session.js";
+import { verifyPassword } from "../core/password.js";
+import { findUser } from "../core/db.js";
+import { signInPage } from "../core/html.js";
+export class AuthError extends Error {
+    status = 401;
+    constructor(message = "Unauthorized") {
+        super(message);
+        this.name = "AuthError";
+    }
+}
+/** Current user from the session cookie, or null. Never touches the database. */
+export async function getUser() {
+    const token = (await cookies()).get(COOKIE_NAME)?.value;
+    if (!token)
+        return null;
+    return verifySession(token, getSecret());
+}
+/** Current user, or throw AuthError (status 401). */
+export async function requireUser() {
+    const user = await getUser();
+    if (!user)
+        throw new AuthError();
+    return user;
+}
+/** A 401 JSON response for catch blocks: `catch (e) { return unauthorized(e) }` */
+export function unauthorized(err) {
+    if (err && !(err instanceof AuthError))
+        throw err;
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+}
+const cookieOptions = () => ({
+    httpOnly: true,
+    sameSite: "lax",
+    secure: process.env.NODE_ENV === "production",
+    path: "/",
+    maxAge: SESSION_DAYS * 24 * 60 * 60,
+});
+/** Only allow same-origin relative paths as a post-login destination. */
+function safeNext(value) {
+    if (!value || !value.startsWith("/") || value.startsWith("//"))
+        return "/";
+    return value;
+}
+function html(body, status = 200) {
+    return new NextResponse(body, { status, headers: { "content-type": "text/html; charset=utf-8" } });
+}
+async function readBody(req) {
+    const type = req.headers.get("content-type") ?? "";
+    if (type.includes("application/json")) {
+        const b = (await req.json().catch(() => ({})));
+        return { username: String(b.username ?? ""), password: String(b.password ?? ""), next: safeNext(String(b.next ?? "")), json: true };
+    }
+    const f = await req.formData();
+    return {
+        username: String(f.get("username") ?? ""),
+        password: String(f.get("password") ?? ""),
+        next: safeNext(String(f.get("next") ?? "")),
+        json: false,
+    };
+}
+function signOutResponse(req, json) {
+    const res = json
+        ? NextResponse.json({ ok: true })
+        : NextResponse.redirect(new URL(SIGN_IN_PATH, req.url), 303);
+    res.cookies.set(COOKIE_NAME, "", { ...cookieOptions(), maxAge: 0 });
+    return res;
+}
+// ── handlers ──────────────────────────────────────────────────
+export async function GET(req, ctx) {
+    const { path } = await ctx.params;
+    const route = path.join("/");
+    if (route === "sign-in") {
+        const next = safeNext(req.nextUrl.searchParams.get("next"));
+        const existing = req.cookies.get(COOKIE_NAME)?.value;
+        if (existing && (await verifySession(existing, getSecret()))) {
+            return NextResponse.redirect(new URL(next, req.url));
+        }
+        const error = req.nextUrl.searchParams.get("error") ? "Wrong username or password." : undefined;
+        return html(signInPage({ next, error }));
+    }
+    if (route === "sign-out")
+        return signOutResponse(req, false);
+    if (route === "session") {
+        const token = req.cookies.get(COOKIE_NAME)?.value;
+        const user = token ? await verifySession(token, getSecret()) : null;
+        return NextResponse.json({ user });
+    }
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+}
+export async function POST(req, ctx) {
+    const { path } = await ctx.params;
+    const route = path.join("/");
+    if (route === "sign-out")
+        return signOutResponse(req, true);
+    if (route !== "sign-in")
+        return NextResponse.json({ error: "Not found" }, { status: 404 });
+    const { username, password, next, json } = await readBody(req);
+    const row = username && password ? await findUser(username.trim()) : null;
+    const ok = row ? await verifyPassword(password, row.password_hash) : false;
+    if (!row || !ok) {
+        if (json)
+            return NextResponse.json({ error: "Wrong username or password" }, { status: 401 });
+        const url = new URL(SIGN_IN_PATH, req.url);
+        url.searchParams.set("error", "1");
+        if (next !== "/")
+            url.searchParams.set("next", next);
+        return NextResponse.redirect(url, 303);
+    }
+    const user = { id: row.id, username: row.username };
+    const token = await signSession(user, getSecret());
+    const res = json ? NextResponse.json({ user }) : NextResponse.redirect(new URL(next, req.url), 303);
+    res.cookies.set(COOKIE_NAME, token, cookieOptions());
+    return res;
+}

package/dist/next/proxy.d.ts

@@ -0,0 +1,5 @@
+import { NextResponse, type NextRequest } from "next/server.js";
+/** Paste this into proxy.ts as `export const config = { matcher: MATCHER }` */
+export declare const MATCHER: string[];
+export declare function proxy(request: NextRequest): Promise<NextResponse>;
+export default proxy;

package/dist/next/proxy.js

@@ -0,0 +1,35 @@
+// ─────────────────────────────────────────────────────────────
+// Proxy (Next 16) / middleware (Next 15). Runs before every route.
+//
+// Verifies the cookie signature only. No database, no network.
+//   no/invalid cookie + page request  → 302 to /auth/sign-in?next=<path>
+//   no/invalid cookie + /api request  → 401 JSON
+//   valid cookie                      → continue
+//
+// The CLI writes proxy.ts with an inline `config.matcher`, because
+// Next reads the matcher statically and ignores a re-exported one.
+// This function also guards those paths itself, so a missing matcher
+// degrades to "slightly slower", never to "static assets blocked".
+// ─────────────────────────────────────────────────────────────
+import { NextResponse } from "next/server.js";
+import { COOKIE_NAME, SIGN_IN_PATH, getSecret } from "../core/config.js";
+import { verifySession } from "../core/session.js";
+/** Paste this into proxy.ts as `export const config = { matcher: MATCHER }` */
+export const MATCHER = ["/((?!auth|_next/static|_next/image|favicon.ico|.*\\..*).*)"];
+const PUBLIC = /^\/(auth(\/|$)|_next\/|favicon\.ico$)|\.[a-z0-9]+$/i;
+export async function proxy(request) {
+    const { pathname, search } = request.nextUrl;
+    if (PUBLIC.test(pathname))
+        return NextResponse.next();
+    const token = request.cookies.get(COOKIE_NAME)?.value;
+    if (token && (await verifySession(token, getSecret())))
+        return NextResponse.next();
+    if (pathname.startsWith("/api/")) {
+        return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+    const url = new URL(SIGN_IN_PATH, request.url);
+    if (pathname !== "/")
+        url.searchParams.set("next", pathname + search);
+    return NextResponse.redirect(url);
+}
+export default proxy;

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@binary1702/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Username + password auth for Next.js. One command: npx @binary1702/auth",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/binary1702/auth.git"
+  },
+  "homepage": "https://github.com/binary1702/auth#readme",
+  "license": "MIT",
+  "bin": {
+    "binary1702-auth": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js"
+    },
+    "./next/proxy": {
+      "types": "./dist/next/proxy.d.ts",
+      "import": "./dist/next/proxy.js"
+    }
+  },
+  "files": [
+    "dist",
+    "INSTALL.md",
+    "PROMPT.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node --test tests/*.test.ts"
+  },
+  "dependencies": {
+    "@neondatabase/serverless": "^1.1.0",
+    "jose": "^6.2.5"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "next": "^16.3.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "nextjs",
+    "password",
+    "neon",
+    "postgres"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}