@binary1702/auth 0.0.0-stage → 0.1.0

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/README.md

@@ -1,3 +1,242 @@
-# 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.
+
+---
+
+## 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,66 @@
 {
   "name": "@binary1702/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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"
+  ],
+  "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"
+  }
+}