@binary1702/auth 0.2.5 → 0.4.0

package/dist/core/pages.js

@@ -0,0 +1,73 @@
+// ─────────────────────────────────────────────────────────────
+// Where the sign-in and sign-up pages live. Pure.
+//
+// The package serves plain HTML pages under /auth/. An app that wants
+// its own design names its pages in b17_auth.yaml:
+//
+//   pages:
+//     signIn: /sign-in
+//     signUp: /sign-up
+//
+// Then every place the package sends a browser (the proxy, sign-out,
+// a verified email, "create the first account") goes to the app's page,
+// and GET /auth/sign-in redirects there too, so old links still land.
+// The protocol does not move: the app's page still POSTs to
+// /auth/sign-in and /auth/sign-up (JSON or a form). The package owns
+// the protocol; the app owns the pixels.
+// ─────────────────────────────────────────────────────────────
+// The built-in paths live here (not in config.ts, which imports options.ts,
+// which imports this file): no import cycle at module load.
+export const SIGN_IN_PATH = "/auth/sign-in";
+export const SIGN_UP_PATH = "/auth/sign-up";
+export const PAGE_KEYS = ["signIn", "signUp"];
+const BUILT_IN = { signIn: SIGN_IN_PATH, signUp: SIGN_UP_PATH };
+/** The app's path for a page, or undefined when the package serves it */
+export function pageOverride(pages, key) {
+    return pages?.[key];
+}
+/** Where a browser is sent for a page: the app's path if named, else the package's */
+export function pagePath(pages, key) {
+    return pageOverride(pages, key) ?? BUILT_IN[key];
+}
+/** The app's pages, for the proxy: they must open without a session */
+export function appPages(pages) {
+    return PAGE_KEYS.map((k) => pages?.[k]).filter((p) => typeof p === "string");
+}
+/**
+ * An app path is an absolute path on this site, outside /auth/ (which the
+ * package serves), with no pattern, query or fragment. Error text or null.
+ */
+export function validateAppPath(key, path) {
+    if (!path.startsWith("/"))
+        return `${key} must be a path starting with /, not "${path}"`;
+    if (/^\/auth(\/|$)/.test(path))
+        return `${key} cannot be under /auth/, which the package serves`;
+    if (/[*?#\s]/.test(path))
+        return `${key} is one plain path, no * ? # or spaces: "${path}"`;
+    return null;
+}
+export function validatePagePath(key, path) {
+    return validateAppPath(`pages.${key}`, path);
+}
+/**
+ * Where a signed-in visitor lands when nothing says otherwise: `home:` from
+ * b17_auth.yaml (the app's signed-in home, say /app), else the site root.
+ *   after sign-in with no `next`, or `next` reduced to "/" by safeNext
+ *   the admin page's "app" link
+ *   a signed-in visitor opening "/" (the proxy sends them home: the root is
+ *   the public site, the app is where they were going)
+ */
+export function landing(next, home) {
+    return next && next !== "/" ? next : (home ?? "/");
+}
+/** Should the proxy send this signed-in request home? Only the root, only when home is elsewhere. */
+export function sendsHome(pathname, home) {
+    return pathname === "/" && !!home && home !== "/";
+}
+/**
+ * The same URL on the app's page: GET /auth/sign-in?next=/x&error=1 becomes
+ * /sign-in?next=/x&error=1, so a bookmark or an old link keeps working.
+ */
+export function movedTo(path, search) {
+    return path + search;
+}

package/dist/core/password.d.ts

@@ -1,2 +1,18 @@
+export declare const SCRYPT_N: number;
+export declare const SCRYPT_R = 8;
+export declare const SCRYPT_P = 1;
 export declare function hashPassword(password: string): Promise<string>;
+type Parsed = {
+    n: number;
+    r: number;
+    p: number;
+    salt: Buffer;
+    hash: Buffer;
+};
+/** The parts of a stored hash, or null when it is not one of ours. Pure. */
+export declare function parseHash(stored: string): Parsed | null;
+/** False for a wrong password and for anything that is not a well-formed hash. Never throws. */
 export declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+/** True when the stored hash was made with weaker parameters than today's, or is not ours. Pure. */
+export declare function needsRehash(stored: string): boolean;
+export {};

package/dist/core/password.js

@@ -3,30 +3,59 @@
 //
 // 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.
+// without invalidating existing rows: needsRehash() spots a row
+// hashed under weaker parameters, and sign-in re-hashes it.
+//
+// N = 2^17 since 0.3.0 (about 0.3 s and 128 MB per hash): slow on
+// purpose, it is what makes a stolen table expensive to crack.
 // ─────────────────────────────────────────────────────────────
 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;
+export const SCRYPT_N = 2 ** 17;
+export const SCRYPT_R = 8;
+export const SCRYPT_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("$");
+    const hash = await run(password, salt, SCRYPT_N, SCRYPT_R, SCRYPT_P);
+    return ["scrypt", SCRYPT_N, SCRYPT_R, SCRYPT_P, salt.toString("base64url"), hash.toString("base64url")].join("$");
 }
-export async function verifyPassword(password, stored) {
+/** The parts of a stored hash, or null when it is not one of ours. Pure. */
+export function parseHash(stored) {
     const parts = stored.split("$");
     if (parts.length !== 6 || parts[0] !== "scrypt")
-        return false;
+        return null;
     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);
+    const num = (s) => (/^\d+$/.test(s) ? Number(s) : NaN);
+    const parsed = { n: num(n), r: num(r), p: num(p), salt: Buffer.from(saltB64, "base64url"), hash: Buffer.from(hashB64, "base64url") };
+    // N must be a power of two above 1; r and p positive; salt and hash present
+    if (!(parsed.n > 1 && Number.isInteger(parsed.n) && (parsed.n & (parsed.n - 1)) === 0))
+        return null;
+    if (!(parsed.r >= 1 && parsed.p >= 1))
+        return null;
+    if (parsed.salt.length === 0 || parsed.hash.length === 0)
+        return null;
+    return parsed;
+}
+/** False for a wrong password and for anything that is not a well-formed hash. Never throws. */
+export async function verifyPassword(password, stored) {
+    const h = parseHash(stored);
+    if (!h)
+        return false;
+    try {
+        const actual = await run(password, h.salt, h.n, h.r, h.p);
+        return actual.length === h.hash.length && timingSafeEqual(actual, h.hash);
+    }
+    catch {
+        return false;
+    }
+}
+/** True when the stored hash was made with weaker parameters than today's, or is not ours. Pure. */
+export function needsRehash(stored) {
+    const h = parseHash(stored);
+    return !h || h.n < SCRYPT_N || h.r < SCRYPT_R || h.p < SCRYPT_P;
 }

package/dist/core/rate.d.ts

@@ -0,0 +1,26 @@
+import { type Db } from "./db.ts";
+export type Bucket = "signin:ip" | "signin:email" | "signup:ip" | "forgot:email" | "verify:email";
+/** [limit, window in seconds] */
+export declare const LIMITS: Record<Bucket, readonly [number, number]>;
+export type Hit = {
+    count: number;
+    reset_at: string | Date;
+};
+export type Decision = {
+    allowed: boolean;
+    retryAfter: number;
+    count: number;
+    limit: number;
+};
+/** The rule. `hit` is the bucket's row after this request was counted. Pure. */
+export declare function decide(hit: Hit, limit: number, now?: Date): Decision;
+/** The client's address, as the first proxy saw it; "unknown" when no header says. Pure. */
+export declare function clientIp(headers: {
+    get(name: string): string | null;
+}): string;
+/** The row's key. Emails lowercased, so "Ben@" and "ben@" share a bucket. Pure. */
+export declare function bucketKey(bucket: Bucket, value: string): string;
+/** The message a refused request sees. Pure. */
+export declare function retryMessage(retryAfter: number): string;
+/** Count this request against the bucket and decide. One statement, plus housekeeping when a window starts. */
+export declare function rateLimit(bucket: Bucket, value: string, store?: Db, now?: Date): Promise<Decision>;

package/dist/core/rate.js

@@ -0,0 +1,70 @@
+// ─────────────────────────────────────────────────────────────
+// Rate limiting: a fixed window per bucket, stored in one row.
+//
+//   rateLimit("signin:email", "ben@x.y")   one INSERT … ON CONFLICT that
+//                                          starts or bumps the window and
+//                                          returns the count; decide() then
+//                                          says allowed or not, and for how
+//                                          long to wait.
+//
+// Buckets and limits (per window):
+//   signin:ip      20 / 15 min    stops guessing many accounts from one place
+//   signin:email   10 / 15 min    stops guessing one account from many places
+//   signup:ip      10 / 1 h       stops account spam
+//   forgot:email    3 / 1 h       stops reset-email spam
+//   verify:email    3 / 1 h       stops verification-email spam
+//
+// Refused requests get 429 with Retry-After. The decision is pure; the
+// storage is one function.
+// ─────────────────────────────────────────────────────────────
+import { db, ensureSchema } from "./db.js";
+/** [limit, window in seconds] */
+export const LIMITS = {
+    "signin:ip": [20, 15 * 60],
+    "signin:email": [10, 15 * 60],
+    "signup:ip": [10, 60 * 60],
+    "forgot:email": [3, 60 * 60],
+    "verify:email": [3, 60 * 60],
+};
+/** The rule. `hit` is the bucket's row after this request was counted. Pure. */
+export function decide(hit, limit, now = new Date()) {
+    const count = Number(hit.count);
+    const resetAt = new Date(hit.reset_at).getTime();
+    const retryAfter = Math.max(1, Math.ceil((resetAt - now.getTime()) / 1000));
+    return count <= limit ? { allowed: true, retryAfter: 0, count, limit } : { allowed: false, retryAfter, count, limit };
+}
+/** The client's address, as the first proxy saw it; "unknown" when no header says. Pure. */
+export function clientIp(headers) {
+    const fwd = headers.get("x-forwarded-for");
+    if (fwd) {
+        const first = fwd.split(",")[0].trim();
+        if (first)
+            return first;
+    }
+    return headers.get("x-real-ip")?.trim() || "unknown";
+}
+/** The row's key. Emails lowercased, so "Ben@" and "ben@" share a bucket. Pure. */
+export function bucketKey(bucket, value) {
+    return `${bucket}:${value.trim().toLowerCase()}`;
+}
+/** The message a refused request sees. Pure. */
+export function retryMessage(retryAfter) {
+    const m = Math.ceil(retryAfter / 60);
+    return retryAfter < 90 ? `Too many attempts. Try again in ${retryAfter} seconds.` : `Too many attempts. Try again in ${m} minutes.`;
+}
+/** Count this request against the bucket and decide. One statement, plus housekeeping when a window starts. */
+export async function rateLimit(bucket, value, store = db(), now = new Date()) {
+    const [limit, windowSeconds] = LIMITS[bucket];
+    await ensureSchema(store);
+    const [hit] = await store.query(`INSERT INTO rate_limits (bucket, count, reset_at)
+     VALUES ($1, 1, now() + ($2::int * interval '1 second'))
+     ON CONFLICT (bucket) DO UPDATE SET
+       count    = CASE WHEN rate_limits.reset_at <= now() THEN 1 ELSE rate_limits.count + 1 END,
+       reset_at = CASE WHEN rate_limits.reset_at <= now() THEN now() + ($2::int * interval '1 second') ELSE rate_limits.reset_at END
+     RETURNING count, reset_at`, [bucketKey(bucket, value), windowSeconds]);
+    if (Number(hit.count) === 1) {
+        // A window just started: a cheap moment to drop windows nobody will look at again
+        await store.query(`DELETE FROM rate_limits WHERE reset_at < now() - interval '1 day'`);
+    }
+    return decide(hit, limit, now);
+}

package/dist/core/reset.d.ts

@@ -0,0 +1,9 @@
+import type { EmailMessage } from "./email.ts";
+export declare const FORGOT_PATH = "/auth/forgot";
+export declare const RESET_PATH = "/auth/reset";
+export declare const RESET_TTL_SECONDS: number;
+export declare const FORGOT_SENT = "If that address has an account, we sent a link to reset the password.";
+export declare const RESET_LINK_INVALID = "This reset link is invalid, already used, or older than an hour.";
+/** The absolute link that goes in the email */
+export declare function resetLink(base: string, rawToken: string): string;
+export declare function resetEmail(to: string, link: string, site: string): EmailMessage;

package/dist/core/reset.js

@@ -0,0 +1,31 @@
+// ─────────────────────────────────────────────────────────────
+// Password reset. Pure: the link, the email, the constants.
+//
+//   POST /auth/forgot   always answers "if that address has an account,
+//                       we sent a link", so it never reveals who exists.
+//                       When the user exists: a `reset` token (1 h) in
+//                       an emailed link to /auth/reset?token=…
+//   POST /auth/reset    consumes the token, sets the password (which
+//                       bumps session_epoch: every old session dies),
+//                       marks the email verified (the link proved it),
+//                       signs the user in.
+// ─────────────────────────────────────────────────────────────
+export const FORGOT_PATH = "/auth/forgot";
+export const RESET_PATH = "/auth/reset";
+export const RESET_TTL_SECONDS = 60 * 60;
+export const FORGOT_SENT = "If that address has an account, we sent a link to reset the password.";
+export const RESET_LINK_INVALID = "This reset link is invalid, already used, or older than an hour.";
+/** The absolute link that goes in the email */
+export function resetLink(base, rawToken) {
+    const url = new URL(RESET_PATH, base);
+    url.searchParams.set("token", rawToken);
+    return url.toString();
+}
+export function resetEmail(to, link, site) {
+    return {
+        to,
+        subject: `Reset your password for ${site}`,
+        text: `Someone asked to reset the password for this address on ${site}. If that was you, open the link below. It works once and expires in one hour.\n\n${link}\n\nIf it was not you, ignore this email: nothing changes until the link is used.`,
+        html: `<p>Someone asked to reset the password for this address on ${site}. If that was you, open the link below. It works once and expires in one hour.</p><p><a href="${link}">${link}</a></p><p>If it was not you, ignore this email: nothing changes until the link is used.</p>`,
+    };
+}

package/dist/core/session.d.ts

@@ -6,9 +6,19 @@ export type User = {
 export type Claim = User & {
     epoch: number;
 };
+export declare const ISSUER = "@binary1702/auth";
+export declare const AUDIENCE = "session";
+/** Tokens issued at or after this moment must carry iss and aud (0.3.0's release day) */
+export declare const CLAIMS_REQUIRED_FROM: number;
 export declare function signSession(user: User & {
     epoch?: number;
-}, secret: string): Promise<string>;
+}, secret: string, days?: number): Promise<string>;
+/** The iss/aud rule: required for new tokens, forgiven for old ones. Pure. */
+export declare function claimsAcceptable(payload: {
+    iat?: number;
+    iss?: string;
+    aud?: string | string[];
+}): boolean;
 export declare function verifySession(token: string, secret: string): Promise<Claim | null>;
 /**
  * The revocation rule. `epoch` is the user's current session_epoch,

package/dist/core/session.js

@@ -5,30 +5,50 @@
 //   signature  verifySession()  needs the secret only, never the
 //              database. The proxy runs this on every request, free.
 //   epoch      isCurrent()      the token carries the user's
-//              session_epoch from when it was signed. getUser() looks
-//              the user up and compares. Deleting the user (no row) or
-//              bumping the epoch (password change, sign-out-everywhere)
-//              makes every older token stop matching: revocation.
+//              session_epoch from when it was signed. getSession()
+//              looks the user up and compares. Deleting the user (no
+//              row) or bumping the epoch (password change, sign-out-
+//              everywhere) makes every older token stop matching.
 //
 // So a revoked token still passes the proxy and loads a page shell,
-// but getUser()/requireUser() say no, and those guard the data.
+// but getSession()/requireSession() say no, and those guard the data.
+//
+// Since 0.3.0 tokens carry iss and aud, so a token minted by another
+// app that happens to share the secret is refused. Tokens from before
+// have neither; they are accepted only if signed before the cutoff.
 // ─────────────────────────────────────────────────────────────
 import { SignJWT, jwtVerify } from "jose";
 import { SESSION_DAYS } from "./config.js";
+export const ISSUER = "@binary1702/auth";
+export const AUDIENCE = "session";
+/** Tokens issued at or after this moment must carry iss and aud (0.3.0's release day) */
+export const CLAIMS_REQUIRED_FROM = Date.UTC(2026, 9, 22) / 1000;
 const key = (secret) => new TextEncoder().encode(secret);
-export async function signSession(user, secret) {
+export async function signSession(user, secret, days = SESSION_DAYS) {
     return new SignJWT({ email: user.email, ep: user.epoch ?? 0 })
         .setProtectedHeader({ alg: "HS256" })
         .setSubject(user.id)
+        .setIssuer(ISSUER)
+        .setAudience(AUDIENCE)
         .setIssuedAt()
-        .setExpirationTime(`${SESSION_DAYS}d`)
+        .setExpirationTime(`${days}d`)
         .sign(key(secret));
 }
+/** The iss/aud rule: required for new tokens, forgiven for old ones. Pure. */
+export function claimsAcceptable(payload) {
+    const aud = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
+    const has = payload.iss === ISSUER && aud.includes(AUDIENCE);
+    if (has)
+        return true;
+    return typeof payload.iat === "number" && payload.iat < CLAIMS_REQUIRED_FROM;
+}
 export async function verifySession(token, secret) {
     try {
         const { payload } = await jwtVerify(token, key(secret), { algorithms: ["HS256"] });
         if (typeof payload.sub !== "string" || typeof payload.email !== "string")
             return null;
+        if (!claimsAcceptable(payload))
+            return null;
         // Tokens from before epochs existed carry no `ep`: they count as 0,
         // so upgrading the package signs nobody out
         const epoch = typeof payload.ep === "number" ? payload.ep : 0;

package/dist/core/signup.d.ts

@@ -1,3 +1,4 @@
+import type { SignupMode } from "./options.ts";
 export type SignupPolicy = {
     /** Can anyone reach the sign-up page right now? */
     allowed: boolean;
@@ -6,12 +7,18 @@ export type SignupPolicy = {
     /** Why it is allowed. "first" skips the invite code: there is nobody to invite you. */
     reason: "open" | "first" | "closed";
 };
-export declare function signupPolicy(env: {
-    AUTH_SIGNUP?: string;
-    AUTH_INVITE_CODE?: string;
-}, userCount: number): SignupPolicy;
+export declare function signupPolicy(mode: SignupMode, userCount: number): SignupPolicy;
 export declare const EMAIL_RE: RegExp;
+export declare const PASSWORD_MIN = 8;
+/** scrypt on a megabyte of password is a denial of service; cap before hashing */
+export declare const PASSWORD_MAX = 256;
+/** Returns an error message, or null when the password is acceptable. */
+export declare function validatePassword(password: string): string | null;
+/** Returns an error message, or null when the address is acceptable (shape, and the domain rule if any). */
+export declare function validateEmail(email: string, opts?: {
+    emailDomain?: string;
+}): string | null;
 /** Returns an error message, or null when the pair is acceptable. */
-export declare function validateCredentials(email: string, password: string, env?: {
-    AUTH_EMAIL_DOMAIN?: string;
+export declare function validateCredentials(email: string, password: string, opts?: {
+    emailDomain?: string;
 }): string | null;

package/dist/core/signup.js

@@ -1,30 +1,45 @@
 // ─────────────────────────────────────────────────────────────
-// Sign-up policy. One pure function, so it can be tested and read.
+// Sign-up policy. Pure functions, so they can be tested and read.
 //
-//   AUTH_SIGNUP=open          anyone may register at /auth/sign-up
-//   AUTH_INVITE_CODE=<code>   with "open": the form also needs this code
-//   (unset)                   closed, EXCEPT when there are no users yet,
-//                             so a fresh install can create its first
-//                             account in the browser instead of the CLI
+//   signup: open      anyone may register at /auth/sign-up
+//   signup: invite    anyone who knows inviteCode
+//   signup: closed    nobody, EXCEPT when there are no users yet, so a
+//                     fresh install can create its first account in the
+//                     browser instead of the CLI
+// (b17_auth.yaml keys; AUTH_SIGNUP=open and AUTH_INVITE_CODE map onto them)
 // ─────────────────────────────────────────────────────────────
-export function signupPolicy(env, userCount) {
+export function signupPolicy(mode, userCount) {
     if (userCount === 0)
         return { allowed: true, inviteRequired: false, reason: "first" };
-    if (env.AUTH_SIGNUP === "open") {
-        return { allowed: true, inviteRequired: Boolean(env.AUTH_INVITE_CODE), reason: "open" };
-    }
+    if (mode === "open")
+        return { allowed: true, inviteRequired: false, reason: "open" };
+    if (mode === "invite")
+        return { allowed: true, inviteRequired: true, reason: "open" };
     return { allowed: false, inviteRequired: false, reason: "closed" };
 }
 export const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-/** Returns an error message, or null when the pair is acceptable. */
-export function validateCredentials(email, password, env) {
+export const PASSWORD_MIN = 8;
+/** scrypt on a megabyte of password is a denial of service; cap before hashing */
+export const PASSWORD_MAX = 256;
+/** Returns an error message, or null when the password is acceptable. */
+export function validatePassword(password) {
+    if (password.length < PASSWORD_MIN)
+        return `Password must be at least ${PASSWORD_MIN} characters.`;
+    if (password.length > PASSWORD_MAX)
+        return `Password must be at most ${PASSWORD_MAX} characters.`;
+    return null;
+}
+/** Returns an error message, or null when the address is acceptable (shape, and the domain rule if any). */
+export function validateEmail(email, opts) {
     if (!EMAIL_RE.test(email))
         return "Please enter a valid email address.";
-    const domain = env?.AUTH_EMAIL_DOMAIN;
+    const domain = opts?.emailDomain;
     if (domain && !email.toLowerCase().endsWith(`@${domain.toLowerCase()}`)) {
         return `Only @${domain} emails are allowed.`;
     }
-    if (password.length < 8)
-        return "Password must be at least 8 characters.";
     return null;
 }
+/** Returns an error message, or null when the pair is acceptable. */
+export function validateCredentials(email, password, opts) {
+    return validateEmail(email, opts) ?? validatePassword(password);
+}

package/dist/core/tokens.d.ts

@@ -0,0 +1,29 @@
+import { type Db } from "./db.ts";
+export type TokenKind = "verify" | "reset" | "magic" | "invite";
+/** What a consumed token tells the handler */
+export type Token = {
+    id: string;
+    userId: string;
+    kind: TokenKind;
+    meta: Record<string, unknown>;
+};
+export type TokenRow = {
+    id: string;
+    user_id: string;
+    kind: TokenKind;
+    token_hash: string;
+    expires_at: string | Date;
+    used_at: string | Date | null;
+    meta: Record<string, unknown> | null;
+};
+/** 256 bits of randomness, URL-safe: 43 characters */
+export declare function newRawToken(): string;
+export declare function hashToken(raw: string): string;
+/** Constant-time equality of two hashes, false on a length mismatch instead of throwing */
+export declare function sameHash(a: string, b: string): boolean;
+/** Why a stored token may or may not be consumed right now */
+export declare function tokenState(row: Pick<TokenRow, "expires_at" | "used_at">, now?: Date): "ok" | "used" | "expired";
+/** Create a token for the user and return the raw value to put in a link. */
+export declare function issueToken(userId: string, kind: TokenKind, ttlSeconds: number, meta?: Record<string, unknown>, store?: Db): Promise<string>;
+/** Redeem a raw token of the given kind. Null for anything but a live, unused token; works once. */
+export declare function consumeToken(raw: string, kind: TokenKind, store?: Db, now?: Date): Promise<Token | null>;

package/dist/core/tokens.js

@@ -0,0 +1,64 @@
+// ─────────────────────────────────────────────────────────────
+// One-time tokens: the thing in an emailed link.
+//
+//   issueToken()    32 random bytes → base64url. Only the SHA-256 is
+//                   stored, so a database leak gives away no live link.
+//   consumeToken()  returns the row once: unknown, expired, used, or
+//                   wrong kind all come back null, and the claim is one
+//                   UPDATE ... WHERE used_at IS NULL, so two clicks at
+//                   the same instant cannot both succeed.
+//
+// Kinds in use: verify (email), reset (password).
+// Reserved for later versions: magic (sign-in link), invite (org).
+//
+// The rules are pure functions; the store is injected (see core/db.ts).
+// ─────────────────────────────────────────────────────────────
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { db, ensureSchema } from "./db.js";
+// ── pure ──────────────────────────────────────────────────────
+/** 256 bits of randomness, URL-safe: 43 characters */
+export function newRawToken() {
+    return randomBytes(32).toString("base64url");
+}
+export function hashToken(raw) {
+    return createHash("sha256").update(raw).digest("hex");
+}
+/** Constant-time equality of two hashes, false on a length mismatch instead of throwing */
+export function sameHash(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/** Why a stored token may or may not be consumed right now */
+export function tokenState(row, now = new Date()) {
+    if (row.used_at)
+        return "used";
+    if (new Date(row.expires_at).getTime() <= now.getTime())
+        return "expired";
+    return "ok";
+}
+// ── store ─────────────────────────────────────────────────────
+/** Create a token for the user and return the raw value to put in a link. */
+export async function issueToken(userId, kind, ttlSeconds, meta = {}, store = db()) {
+    await ensureSchema(store);
+    const raw = newRawToken();
+    const expiresAt = new Date(Date.now() + ttlSeconds * 1000).toISOString();
+    await store.query(`INSERT INTO tokens (user_id, kind, token_hash, expires_at, meta) VALUES ($1, $2, $3, $4, $5::jsonb)`, [userId, kind, hashToken(raw), expiresAt, JSON.stringify(meta)]);
+    // Housekeeping: rows nobody can use any more
+    await store.query(`DELETE FROM tokens WHERE expires_at < now() - interval '7 days'`);
+    return raw;
+}
+/** Redeem a raw token of the given kind. Null for anything but a live, unused token; works once. */
+export async function consumeToken(raw, kind, store = db(), now = new Date()) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(raw))
+        return null;
+    await ensureSchema(store);
+    const hash = hashToken(raw);
+    const [row] = await store.query(`SELECT id, user_id, kind, token_hash, expires_at, used_at, meta FROM tokens WHERE token_hash = $1 AND kind = $2`, [hash, kind]);
+    if (!row || !sameHash(hash, row.token_hash) || tokenState(row, now) !== "ok")
+        return null;
+    const claimed = await store.query(`UPDATE tokens SET used_at = now() WHERE id = $1 AND used_at IS NULL RETURNING id`, [row.id]);
+    if (claimed.length === 0)
+        return null;
+    return { id: row.id, userId: row.user_id, kind: row.kind, meta: row.meta ?? {} };
+}

package/dist/core/verify.d.ts

@@ -0,0 +1,8 @@
+import type { EmailMessage } from "./email.ts";
+export declare const VERIFY_PATH = "/auth/verify";
+export declare const VERIFY_TTL_SECONDS: number;
+/** The gate: may a user with this verification state have a session? */
+export declare function mayAccess(verified: boolean, requireVerified: boolean): boolean;
+/** The absolute link that goes in the email */
+export declare function verifyLink(base: string, rawToken: string, next?: string): string;
+export declare function verifyEmail(to: string, link: string, site: string): EmailMessage;

package/dist/core/verify.js

@@ -0,0 +1,33 @@
+// ─────────────────────────────────────────────────────────────
+// Email verification policy and the email itself. Pure.
+//
+//   requireVerified: true   (b17_auth.yaml, or AUTH_REQUIRE_VERIFIED=true)
+//                           an unverified user gets no session: getUser()
+//                           is null, sign-in says "check your email".
+//                           Default off, so existing installs change nothing.
+//
+// Sign-up always issues a `verify` token (24 h) and emails the link;
+// the flag only decides whether that gate is closed meanwhile.
+// ─────────────────────────────────────────────────────────────
+export const VERIFY_PATH = "/auth/verify";
+export const VERIFY_TTL_SECONDS = 24 * 60 * 60;
+/** The gate: may a user with this verification state have a session? */
+export function mayAccess(verified, requireVerified) {
+    return verified || !requireVerified;
+}
+/** The absolute link that goes in the email */
+export function verifyLink(base, rawToken, next) {
+    const url = new URL(VERIFY_PATH, base);
+    url.searchParams.set("token", rawToken);
+    if (next && next !== "/")
+        url.searchParams.set("next", next);
+    return url.toString();
+}
+export function verifyEmail(to, link, site) {
+    return {
+        to,
+        subject: `Verify your email for ${site}`,
+        text: `Confirm this is your address by opening the link below. It works once and expires in 24 hours.\n\n${link}\n\nIf you did not create an account, ignore this email.`,
+        html: `<p>Confirm this is your address by opening the link below. It works once and expires in 24 hours.</p><p><a href="${link}">${link}</a></p><p>If you did not create an account, ignore this email.</p>`,
+    };
+}

package/dist/core/yaml.d.ts

@@ -0,0 +1,10 @@
+export type YamlTree = {
+    [key: string]: string | YamlTree;
+};
+export declare class YamlError extends Error {
+    line: number;
+    constructor(message: string, line: number);
+}
+export declare function parseYaml(text: string): YamlTree;
+/** Words of a space-separated value. "" → []. */
+export declare function words(value: string | undefined): string[];