@deepraxis/app-template 0.0.0-stage → 0.1.0-dev.378725e

package/template/app/register/page.tsx

@@ -0,0 +1,25 @@
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export const dynamic = "force-dynamic";
+
+export default async function Register({ searchParams }: { searchParams: Promise<{ error?: string }> }) {
+  const { error } = await searchParams;
+  return (
+    <Card className="mx-auto max-w-sm">
+      <CardHeader><CardTitle>Create account</CardTitle></CardHeader>
+      <CardContent>
+        <form action="/api/auth/register" method="post" className="space-y-4">
+          <div className="space-y-1.5"><Label htmlFor="username">Username</Label><Input id="username" name="username" autoComplete="username" required /></div>
+          <div className="space-y-1.5"><Label htmlFor="password">Password</Label><Input id="password" name="password" type="password" autoComplete="new-password" required /></div>
+          {error && <p role="alert" className="text-sm text-red-600">{error}</p>}
+          <Button type="submit" className="w-full">Create account</Button>
+        </form>
+        <p className="mt-4 text-sm"><Link className="underline" href="/login">Already have an account?</Link></p>
+      </CardContent>
+    </Card>
+  );
+}

package/template/components/ui/button.tsx

@@ -0,0 +1,24 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-slate-900 text-white hover:bg-slate-800",
+        outline: "border border-slate-300 bg-white hover:bg-slate-50",
+        ghost: "hover:bg-slate-100",
+      },
+      size: { default: "h-9 px-4 py-2", sm: "h-8 px-3" },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  },
+);
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />;
+}

package/template/components/ui/card.tsx

@@ -0,0 +1,17 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+type DivProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function Card({ className, ...props }: DivProps) {
+  return <div className={cn("rounded-lg border border-slate-200 bg-white shadow-sm", className)} {...props} />;
+}
+export function CardHeader({ className, ...props }: DivProps) {
+  return <div className={cn("flex flex-col gap-1.5 p-6", className)} {...props} />;
+}
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h2 className={cn("text-lg font-semibold leading-none", className)} {...props} />;
+}
+export function CardContent({ className, ...props }: DivProps) {
+  return <div className={cn("p-6 pt-0", className)} {...props} />;
+}

package/template/components/ui/input.tsx

@@ -0,0 +1,14 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export function Input({ className, ...props }: React.InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <input
+      className={cn(
+        "flex h-9 w-full rounded-md border border-slate-300 bg-white px-3 py-1 text-sm shadow-sm placeholder:text-slate-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/template/components/ui/label.tsx

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export function Label({ className, ...props }: React.LabelHTMLAttributes<HTMLLabelElement>) {
+  return <label className={cn("text-sm font-medium leading-none", className)} {...props} />;
+}

package/template/env.d.ts

@@ -0,0 +1,11 @@
+// Types of the bindings declared in wrangler.jsonc and the secrets declared in praxis.jsonc.
+// Read them with `import { env } from "cloudflare:workers"`; add a line here for every new one.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    IMAGES: R2Bucket;
+    ASSETS: Fetcher;
+    /** Signs session cookies; created by `praxis app deploy` ("generate" in praxis.jsonc). */
+    SESSION_SECRET?: string;
+  }
+}

package/template/lib/auth.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { credentialsSchema, hashPassword, MissingSecretError, newSessionToken, sha256Hex, signToken, verifyPassword, verifySignedToken } from "./auth";
+
+describe("passwords", () => {
+  test("hash has the documented format and verifies", async () => {
+    const stored = await hashPassword("correct horse");
+    expect(stored).toMatch(/^pbkdf2\$100000\$[A-Za-z0-9+/=]+\$[A-Za-z0-9+/=]+$/);
+    expect(await verifyPassword("correct horse", stored)).toBe(true);
+  });
+  test("wrong password is rejected", async () => {
+    expect(await verifyPassword("wrong horse", await hashPassword("correct horse"))).toBe(false);
+  });
+  test("same password hashes differently (random salt)", async () => {
+    expect(await hashPassword("same-password")).not.toBe(await hashPassword("same-password"));
+  });
+  test("malformed or over-limit stored values never verify", async () => {
+    expect(await verifyPassword("x", "garbage")).toBe(false);
+    expect(await verifyPassword("x", "pbkdf2$99999999$AAAA$AAAA")).toBe(false);
+  });
+});
+
+describe("signed session token", () => {
+  const secret = "test-secret";
+  test("round-trips", async () => {
+    const token = newSessionToken();
+    expect(await verifySignedToken(await signToken(token, secret), secret)).toBe(token);
+  });
+  test("tampered signature or token is rejected", async () => {
+    const token = newSessionToken();
+    const value = await signToken(token, secret);
+    const flipped = value.slice(0, -2) + (value.endsWith("AA") ? "BB" : "AA");
+    expect(await verifySignedToken(flipped, secret)).toBeNull();
+    expect(await verifySignedToken(`${newSessionToken()}.${value.split(".")[1]}`, secret)).toBeNull();
+  });
+  test("a signature made with another secret is rejected", async () => {
+    expect(await verifySignedToken(await signToken("tok", "other-secret"), secret)).toBeNull();
+  });
+  test("garbage cookie values are rejected, not thrown", async () => {
+    for (const v of ["", "nodot", ".sig", "tok.", "tok.%%%"]) expect(await verifySignedToken(v, secret)).toBeNull();
+  });
+  test("missing secret throws a clear error naming SESSION_SECRET and never signs", async () => {
+    await expect(signToken("tok", undefined)).rejects.toThrow(MissingSecretError);
+    await expect(signToken("tok", "")).rejects.toThrow(/SESSION_SECRET/);
+    await expect(verifySignedToken("tok.sig", undefined)).rejects.toThrow(MissingSecretError);
+  });
+  test("session id is the sha256 of the token", async () => {
+    expect(await sha256Hex("abc")).toBe("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
+  });
+});
+
+describe("validation", () => {
+  test("username and password bounds", () => {
+    const ok = (username: string, password: string) => credentialsSchema.safeParse({ username, password }).success;
+    expect(ok("alice_1", "12345678")).toBe(true);
+    expect(ok("ab", "12345678")).toBe(false);
+    expect(ok("Alice", "12345678")).toBe(false);
+    expect(ok("a".repeat(33), "12345678")).toBe(false);
+    expect(ok("alice", "1234567")).toBe(false);
+    expect(ok("alice", "x".repeat(129))).toBe(false);
+  });
+});

package/template/lib/auth.ts

@@ -0,0 +1,107 @@
+// Credentials and cookie signing, WebCrypto only. No framework or Cloudflare imports, so it runs under `bun test`.
+//
+// Password hash format: pbkdf2$<iterations>$<salt_b64>$<hash_b64> (PBKDF2-SHA256, 16-byte salt).
+// 100000 iterations is the maximum the Workers runtime accepts.
+// Cookie value: <token>.<signature>, signature = HMAC-SHA256(token) keyed by the SESSION_SECRET binding.
+// Rate limiting (per IP and per username on sign-in and sign-up) belongs in the two route handlers under app/api/auth/.
+import { z } from "zod";
+
+export const PBKDF2_ITERATIONS = 100000;
+
+export const usernameSchema = z.string().regex(/^[a-z0-9_]{3,32}$/, "Username: 3-32 characters of a-z, 0-9 and _");
+export const passwordSchema = z.string().min(8, "Password: at least 8 characters").max(128, "Password: at most 128 characters");
+export const credentialsSchema = z.object({ username: usernameSchema, password: passwordSchema });
+
+export class MissingSecretError extends Error {
+  readonly status = 500;
+  constructor() {
+    super("SESSION_SECRET is not configured: pass it as a secret_text binding when deploying. Refusing to sign sessions without it.");
+    this.name = "MissingSecretError";
+  }
+}
+
+export function requireSecret(secret: string | undefined): string {
+  if (!secret) throw new MissingSecretError();
+  return secret;
+}
+
+type Bytes = Uint8Array<ArrayBuffer>;
+const enc = new TextEncoder();
+
+function toB64(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+function fromB64(b64: string): Bytes {
+  const s = atob(b64);
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+const toB64Url = (bytes: Uint8Array) => toB64(bytes).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+const fromB64Url = (s: string) => fromB64(s.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - (s.length % 4)) % 4));
+
+/** Constant-time comparison of two byte arrays (length difference is not secret). */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ b[i]!;
+  return diff === 0;
+}
+
+async function pbkdf2(password: string, salt: Bytes, iterations: number): Promise<Uint8Array> {
+  const key = await crypto.subtle.importKey("raw", enc.encode(password), "PBKDF2", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits({ name: "PBKDF2", hash: "SHA-256", salt, iterations }, key, 256);
+  return new Uint8Array(bits);
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const hash = await pbkdf2(password, salt, PBKDF2_ITERATIONS);
+  return `pbkdf2$${PBKDF2_ITERATIONS}$${toB64(salt)}$${toB64(hash)}`;
+}
+
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [scheme, iterations, salt, hash] = stored.split("$");
+  const n = Number(iterations);
+  if (scheme !== "pbkdf2" || !Number.isInteger(n) || n < 1 || n > PBKDF2_ITERATIONS || !salt || !hash) return false;
+  const actual = await pbkdf2(password, fromB64(salt), n);
+  return timingSafeEqual(actual, fromB64(hash));
+}
+
+/** A fresh random session token (32 bytes, base64url). Only its sha256 is stored. */
+export function newSessionToken(): string {
+  return toB64Url(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+export async function sha256Hex(value: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", enc.encode(value)));
+  return [...digest].map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+const hmacKey = (secret: string, usage: "sign" | "verify") =>
+  crypto.subtle.importKey("raw", enc.encode(requireSecret(secret)), { name: "HMAC", hash: "SHA-256" }, false, [usage]);
+
+/** `token.signature` — the cookie value. Throws MissingSecretError when the secret is empty. */
+export async function signToken(token: string, secret: string | undefined): Promise<string> {
+  const key = await hmacKey(requireSecret(secret), "sign");
+  const sig = new Uint8Array(await crypto.subtle.sign("HMAC", key, enc.encode(token)));
+  return `${token}.${toB64Url(sig)}`;
+}
+
+/** The token when the signature is valid, otherwise null. Verification is constant-time (subtle.verify). */
+export async function verifySignedToken(value: string | null | undefined, secret: string | undefined): Promise<string | null> {
+  if (!value) return null;
+  const dot = value.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const token = value.slice(0, dot);
+  let sig: Bytes;
+  try {
+    sig = fromB64Url(value.slice(dot + 1));
+  } catch {
+    return null;
+  }
+  const key = await hmacKey(requireSecret(secret), "verify");
+  return (await crypto.subtle.verify("HMAC", key, sig, enc.encode(token))) ? token : null;
+}

package/template/lib/db.ts

@@ -0,0 +1,19 @@
+// Database access. `getDb()` applies pending migrations once per isolate, then returns a drizzle client.
+import { env } from "cloudflare:workers";
+import { drizzle } from "drizzle-orm/d1";
+import { runMigrations } from "./migrate";
+import { migrations } from "./migrations";
+import * as schema from "./schema";
+
+let ready: Promise<unknown> | undefined;
+
+export async function getDb() {
+  ready ??= runMigrations(env.DB, migrations).catch(e => {
+    ready = undefined; // retry on the next request instead of caching the failure
+    throw e;
+  });
+  await ready;
+  return drizzle(env.DB, { schema });
+}
+
+export type Db = Awaited<ReturnType<typeof getDb>>;

package/template/lib/guard.ts

@@ -0,0 +1,37 @@
+// Request-level helpers for pages and route handlers: who is signed in, and who may see what.
+import { env } from "cloudflare:workers";
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { getDb } from "./db";
+import { userFromCookie } from "./session";
+import type { User } from "./users";
+
+export async function getCurrentUser(cookieHeader?: string | null): Promise<User | null> {
+  if (!env.SESSION_SECRET) return null; // nobody can be signed in without the secret
+  const cookie = cookieHeader !== undefined ? cookieHeader : (await headers()).get("cookie");
+  return userFromCookie(await getDb(), cookie, env.SESSION_SECRET);
+}
+
+/** Only accept same-site relative paths as a post-login destination. */
+export function safeNext(next: string | null | undefined, fallback = "/account"): string {
+  return next && next.startsWith("/") && !next.startsWith("//") && !next.startsWith("/\\") ? next : fallback;
+}
+
+export async function requireUser(next: string): Promise<User> {
+  const user = await getCurrentUser();
+  if (!user) redirect(`/login?next=${encodeURIComponent(next)}`);
+  return user;
+}
+
+export async function requireAdmin(next: string): Promise<User> {
+  const user = await requireUser(next);
+  if (user.role !== "admin") redirect("/account");
+  return user;
+}
+
+/** 303 redirect for form posts, optionally setting a cookie. */
+export function redirectResponse(location: string, setCookie?: string): Response {
+  const h = new Headers({ Location: location });
+  if (setCookie) h.append("Set-Cookie", setCookie);
+  return new Response(null, { status: 303, headers: h });
+}

package/template/lib/migrate.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { fakeD1 } from "../test/fake-d1";
+import { runMigrations, type Migration } from "./migrate";
+
+const list: Migration[] = [
+  { name: "0001_a", sql: "CREATE TABLE IF NOT EXISTS a (id INTEGER); CREATE INDEX IF NOT EXISTS a_id ON a(id);" },
+  { name: "0002_b", sql: "CREATE TABLE IF NOT EXISTS b (id INTEGER);" },
+];
+const applied = (db: ReturnType<typeof fakeD1>["db"]) => db.query("SELECT name FROM _migrations ORDER BY applied_at, name").all().map((r: any) => r.name);
+
+describe("runMigrations", () => {
+  test("applies pending migrations in order and records them", async () => {
+    const { d1, db, log } = fakeD1();
+    expect(await runMigrations(d1, list)).toEqual(["0001_a", "0002_b"]);
+    expect(applied(db)).toEqual(["0001_a", "0002_b"]);
+    expect(log.findIndex(s => s.includes("TABLE IF NOT EXISTS a "))).toBeLessThan(log.findIndex(s => s.includes("TABLE IF NOT EXISTS b ")));
+    expect(db.query("SELECT name FROM sqlite_master WHERE name IN ('a','b','a_id')").all()).toHaveLength(3);
+  });
+
+  test("is idempotent: a second run applies nothing and runs no migration SQL", async () => {
+    const { d1, log } = fakeD1();
+    await runMigrations(d1, list);
+    const migrationWrites = () => log.filter(s => !s.includes("_migrations (name TEXT")).length;
+    const before = migrationWrites();
+    expect(await runMigrations(d1, list)).toEqual([]);
+    expect(migrationWrites()).toBe(before);
+  });
+
+  test("skips migrations already recorded and applies only the new one", async () => {
+    const { d1, db } = fakeD1();
+    await runMigrations(d1, [list[0]!]);
+    expect(await runMigrations(d1, list)).toEqual(["0002_b"]);
+    expect(applied(db)).toEqual(["0001_a", "0002_b"]);
+  });
+
+  test("a failing migration rolls back whole and is not recorded", async () => {
+    const { d1, db } = fakeD1();
+    await expect(runMigrations(d1, [{ name: "0001_bad", sql: "CREATE TABLE t (id INTEGER); SELECT nope FROM missing;" }])).rejects.toThrow();
+    expect(applied(db)).toEqual([]);
+    expect(db.query("SELECT name FROM sqlite_master WHERE name = 't'").all()).toHaveLength(0);
+  });
+
+  test("a race lost to another isolate that recorded the migration is not an error", async () => {
+    const { d1, db } = fakeD1();
+    await runMigrations(d1, []);
+    // The "other isolate" wins between our read and our batch: simulate by recording it from inside the first statement's failure.
+    const racing = { ...d1, batch: async (s: any[]) => { if (s.length > 1) { db.run("CREATE TABLE r (id INTEGER)"); db.run("INSERT INTO _migrations VALUES ('0001_r', 1)"); throw new Error("table r already exists"); } return d1.batch(s); } } as any;
+    expect(await runMigrations(racing, [{ name: "0001_r", sql: "CREATE TABLE r (id INTEGER);" }])).toEqual([]);
+  });
+});

package/template/lib/migrate.ts

@@ -0,0 +1,54 @@
+// Runtime migrator. The platform has no remote migrate command, so pending migrations are applied
+// by the app itself, once per isolate, before the first database use (see lib/db.ts).
+//
+// How to add a migration:
+//   1. Create migrations/000N_what_it_does.sql (next number). Plain SQL, statements ending in `;`.
+//   2. Import it with `?raw` and append `{ name: "000N_what_it_does", sql }` in lib/migrations.ts.
+//   3. Add the matching drizzle table or column to lib/schema.ts.
+// Never edit or reorder an applied migration; add a new one.
+//
+// Safety: each migration runs in one D1 batch (a transaction) together with the INSERT OR IGNORE
+// that records it in `_migrations`. Write statements so they are harmless to re-run
+// (CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS). If two isolates race on a first request
+// and one batch fails (for example a duplicate ALTER TABLE), the loser re-reads `_migrations` and
+// carries on when the winner already recorded the migration.
+
+export interface Migration {
+  name: string;
+  sql: string;
+}
+
+type Db = Pick<D1Database, "prepare" | "batch">;
+
+/** Split a migration file into single statements. Do not put `;` inside string literals or triggers. */
+export function splitStatements(sql: string): string[] {
+  return sql
+    .split(";")
+    .map(s => s.trim())
+    .filter(s => s.length > 0);
+}
+
+async function appliedNames(db: Db): Promise<Set<string>> {
+  const { results } = await db.prepare("SELECT name FROM _migrations").all<{ name: string }>();
+  return new Set(results.map(r => r.name));
+}
+
+/** Apply every pending migration in list order. Returns the names applied by this call. */
+export async function runMigrations(db: Db, migrations: Migration[], now: () => number = Date.now): Promise<string[]> {
+  await db.batch([db.prepare("CREATE TABLE IF NOT EXISTS _migrations (name TEXT PRIMARY KEY, applied_at INTEGER NOT NULL)")]);
+  const applied = await appliedNames(db);
+  const ran: string[] = [];
+  for (const m of migrations) {
+    if (applied.has(m.name)) continue;
+    try {
+      await db.batch([
+        ...splitStatements(m.sql).map(s => db.prepare(s)),
+        db.prepare("INSERT OR IGNORE INTO _migrations (name, applied_at) VALUES (?, ?)").bind(m.name, now()),
+      ]);
+      ran.push(m.name);
+    } catch (e) {
+      if (!(await appliedNames(db)).has(m.name)) throw e;
+    }
+  }
+  return ran;
+}

package/template/lib/migrations.ts

@@ -0,0 +1,5 @@
+// The bundled migration list. Add one import + one entry per new file in migrations/ (see lib/migrate.ts).
+import type { Migration } from "./migrate";
+import m0001 from "../migrations/0001_init.sql?raw";
+
+export const migrations: Migration[] = [{ name: "0001_init", sql: m0001 }];

package/template/lib/schema.ts

@@ -0,0 +1,30 @@
+// drizzle table definitions. Keep in step with migrations/*.sql (the SQL files are the source of truth).
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const users = sqliteTable("users", {
+  id: text("id").primaryKey(),
+  username: text("username").notNull().unique(),
+  passwordHash: text("password_hash").notNull(),
+  role: text("role", { enum: ["user", "admin"] }).notNull().default("user"),
+  createdAt: integer("created_at").notNull(),
+});
+
+export const sessions = sqliteTable("sessions", {
+  /** sha256 hex of the session token; the token itself is never stored. */
+  id: text("id").primaryKey(),
+  userId: text("user_id").notNull(),
+  expiresAt: integer("expires_at").notNull(),
+  createdAt: integer("created_at").notNull(),
+});
+
+export const images = sqliteTable("images", {
+  id: text("id").primaryKey(),
+  ownerId: text("owner_id").notNull(),
+  key: text("key").notNull().unique(),
+  contentType: text("content_type").notNull(),
+  size: integer("size").notNull(),
+  createdAt: integer("created_at").notNull(),
+});
+
+export type Schema = { users: typeof users; sessions: typeof sessions; images: typeof images };
+export type Role = "user" | "admin";

package/template/lib/session.ts

@@ -0,0 +1,48 @@
+// Sessions: D1 rows keyed by sha256(token), plus the cookie string. Pure over the db and secret passed in.
+import { and, eq, gt } from "drizzle-orm";
+import { newSessionToken, sha256Hex, signToken, verifySignedToken } from "./auth";
+import { sessions, users } from "./schema";
+import type { AnyDb, User } from "./users";
+
+export const SESSION_COOKIE = "session";
+export const SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Create a session row and return the signed cookie value. Throws MissingSecretError without a secret. */
+export async function createSession(db: AnyDb, userId: string, secret: string | undefined, now = Date.now()) {
+  const token = newSessionToken();
+  const value = await signToken(token, secret); // fails before anything is written when the secret is missing
+  await db.insert(sessions).values({ id: await sha256Hex(token), userId, expiresAt: now + SESSION_TTL_MS, createdAt: now });
+  return { value, expiresAt: now + SESSION_TTL_MS };
+}
+
+export function sessionCookie(value: string, expiresAt: number): string {
+  return `${SESSION_COOKIE}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Expires=${new Date(expiresAt).toUTCString()}`;
+}
+export const clearedSessionCookie = `${SESSION_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`;
+
+export function readCookie(header: string | null, name: string): string | null {
+  for (const part of (header ?? "").split(";")) {
+    const eq = part.indexOf("=");
+    if (eq > 0 && part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+  }
+  return null;
+}
+
+/** The signed-in user for a Cookie header, or null (no cookie, bad signature, unknown or expired session). */
+export async function userFromCookie(db: AnyDb, cookieHeader: string | null, secret: string | undefined, now = Date.now()): Promise<User | null> {
+  const raw = readCookie(cookieHeader, SESSION_COOKIE);
+  const token = await verifySignedToken(raw, secret);
+  if (!token) return null;
+  const [row] = await db
+    .select({ id: users.id, username: users.username, role: users.role, createdAt: users.createdAt })
+    .from(sessions)
+    .innerJoin(users, eq(users.id, sessions.userId))
+    .where(and(eq(sessions.id, await sha256Hex(token)), gt(sessions.expiresAt, now)))
+    .limit(1);
+  return row ?? null;
+}
+
+export async function destroySession(db: AnyDb, cookieHeader: string | null, secret: string | undefined) {
+  const token = await verifySignedToken(readCookie(cookieHeader, SESSION_COOKIE), secret);
+  if (token) await db.delete(sessions).where(eq(sessions.id, await sha256Hex(token)));
+}

package/template/lib/storage.ts

@@ -0,0 +1,32 @@
+// Image storage on R2 (binding IMAGES). Rules live here; pages and routes only call these functions.
+import { eq, desc } from "drizzle-orm";
+import { images } from "./schema";
+import type { AnyDb } from "./users";
+
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+export const IMAGE_TYPES: Record<string, string> = { "image/jpeg": "jpg", "image/png": "png", "image/webp": "webp" };
+
+/** An error message when the file is not an acceptable image, otherwise null. */
+export function checkImage(file: { type: string; size: number }): string | null {
+  if (!(file.type in IMAGE_TYPES)) return "Only JPEG, PNG and WebP images are accepted";
+  if (file.size === 0) return "The file is empty";
+  if (file.size > MAX_IMAGE_BYTES) return "The image is larger than 5 MB";
+  return null;
+}
+
+export async function saveImage(db: AnyDb, bucket: R2Bucket, ownerId: string, file: File) {
+  const id = crypto.randomUUID();
+  const key = `u/${ownerId}/${crypto.randomUUID().replaceAll("-", "")}.${IMAGE_TYPES[file.type]}`;
+  await bucket.put(key, await file.arrayBuffer(), { httpMetadata: { contentType: file.type } });
+  await db.insert(images).values({ id, ownerId, key, contentType: file.type, size: file.size, createdAt: Date.now() });
+  return { id, key };
+}
+
+export async function listImages(db: AnyDb, ownerId: string) {
+  return db.select().from(images).where(eq(images.ownerId, ownerId)).orderBy(desc(images.createdAt));
+}
+
+export async function findImage(db: AnyDb, key: string) {
+  const [row] = await db.select().from(images).where(eq(images.key, key)).limit(1);
+  return row ?? null;
+}

package/template/lib/users.test.ts

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { fakeD1 } from "../test/fake-d1";
+import { runMigrations } from "./migrate";
+import { createSession, sessionCookie, userFromCookie } from "./session";
+import * as schema from "./schema";
+import { createUser } from "./users";
+
+let db: ReturnType<typeof drizzle<typeof schema>>;
+beforeEach(async () => {
+  const fake = fakeD1();
+  await runMigrations(fake.d1, [{ name: "0001_init", sql: readFileSync(new URL("../migrations/0001_init.sql", import.meta.url), "utf8") }]);
+  db = drizzle(fake.db, { schema });
+});
+
+describe("createUser", () => {
+  test("the first user is admin, everyone after is user", async () => {
+    const a = await createUser(db, { username: "alice", passwordHash: "h" });
+    const b = await createUser(db, { username: "bob", passwordHash: "h" });
+    expect(a.ok && a.user.role).toBe("admin");
+    expect(b.ok && b.user.role).toBe("user");
+  });
+  test("a duplicate username is reported, not thrown", async () => {
+    await createUser(db, { username: "alice", passwordHash: "h" });
+    expect(await createUser(db, { username: "alice", passwordHash: "h" })).toEqual({ ok: false, error: "username-taken" });
+  });
+});
+
+describe("sessions", () => {
+  test("a signed cookie resolves to its user; tampering, expiry and a wrong secret do not", async () => {
+    const created = await createUser(db, { username: "alice", passwordHash: "h" });
+    if (!created.ok) throw new Error("setup");
+    const s = await createSession(db, created.user.id, "sec", 1000);
+    const cookie = `session=${s.value}`;
+    expect((await userFromCookie(db, cookie, "sec", 2000))?.username).toBe("alice");
+    expect(await userFromCookie(db, `session=${s.value}x`, "sec", 2000)).toBeNull();
+    expect(await userFromCookie(db, cookie, "other", 2000)).toBeNull();
+    expect(await userFromCookie(db, cookie, "sec", s.expiresAt + 1)).toBeNull();
+    expect(db.select().from(schema.sessions).all()[0]!.id).not.toContain(s.value.split(".")[0]!); // only the hash is stored
+  });
+  test("the cookie is HttpOnly, Secure, SameSite=Lax, Path=/", () => {
+    expect(sessionCookie("v", 0)).toMatch(/^session=v; Path=\/; HttpOnly; Secure; SameSite=Lax; Expires=/);
+  });
+  test("creating a session without a secret throws and writes nothing", async () => {
+    const created = await createUser(db, { username: "alice", passwordHash: "h" });
+    if (!created.ok) throw new Error("setup");
+    await expect(createSession(db, created.user.id, undefined)).rejects.toThrow(/SESSION_SECRET/);
+    expect(db.select().from(schema.sessions).all()).toHaveLength(0);
+  });
+});