fix: address review findings on postgres backend

- PostgresMigrator: run JS migration parts on the transactional client
  (WrappedPgTx) instead of the pool, preserving migration atomicity
- pool.ts: guard ROLLBACK so a failing rollback no longer masks the
  original error (also applied in the migrator loop)
- pool.ts: share all/get/run between WrappedPool and WrappedPgTx via a
  common base class
- sql.ts: document that toPositional precludes JSONB ?/?|/?& operators
- PostgresInterface: implement deleteSession, required by
  BackendDbInterface since the logout-invalidation change on master

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

package.json

@@ -19,7 +19,13 @@
     "abode-tui": "tsx --import ./src/meta/dev/register.ts --import ./src/meta/dev/silenthot.ts src/bin/abode-tui.ts",
     "abode-sources": "tsx --import ./src/meta/dev/register.ts src/bin/abode-sources.ts",
     "build": "NODE_ENV=production npm run build:impl",
-    "build:impl": "rm -rf dist && tsx node_modules/.bin/webpack && chmod +x dist/bin/* && chmod -x dist/bin/*.*"
+    "build:impl": "rm -rf dist && tsx node_modules/.bin/webpack && chmod +x dist/bin/* && chmod -x dist/bin/*.*",
+    "test": "node --import tsx/esm --import ./src/meta/dev/register.ts --test $(find test -name '*.test.ts' | sort)",
+    "test:backends": "node --import tsx/esm --import ./src/meta/dev/register.ts --test $(find test/backends -name '*.test.ts' | sort)",
+    "test:shared": "node --import tsx/esm --import ./src/meta/dev/register.ts --test $(find test/backends -name 'index.test.ts' | sort)",
+    "test:tools": "node --import tsx/esm --import ./src/meta/dev/register.ts --test $(find test/tools -name '*.test.ts' | sort)",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json"
   },
   "dependencies": {
     "@koa/bodyparser": "^6.0.0",

src/db/api/ApiInterface.ts

@@ -55,7 +55,7 @@ export class ApiInterface implements DbInterface {
         .map((part) => {
           if (part.startsWith(":")) {
             const value = remaining.get(part.slice(1));
-            remaining.delete(part);
+            remaining.delete(part.slice(1));
             if (value === undefined)
               throw new Error(`Missing ${part} in params`);
             return encodeURIComponent(value);
@@ -113,6 +113,7 @@ export class ApiInterface implements DbInterface {
           throw new Error(`${res.status} ${res.statusText} ${text}`);
       }
     }
+    if (res.status === 204) return undefined as T;
     return res.json();
   }
 
@@ -266,24 +267,33 @@ export class ApiInterface implements DbInterface {
   }
 
   async listNotes(): Promise<PartialNote[]> {
-    throw new Error("Unimplemented");
+    return this.#call("GET", "/notes");
   }
   async getNoteById(nid: string): Promise<Note> {
-    throw new Error("Unimplemented");
+    return this.#call("GET", "/notes/:nid", { params: { nid } });
   }
   async deleteNoteById(nid: string): Promise<void> {
-    throw new Error("Unimplemented");
+    this.#checkReadonly();
+    await this.#call("DELETE", "/notes/:nid", { params: { nid } });
   }
-  async createNote(note: CreateNote): Promise<Note> {
-    throw new Error("Unimplemented");
+  async createNote(note: CreateNote, _ctx: { uid: string }): Promise<Note> {
+    this.#checkReadonly();
+    return this.#call("POST", "/abodes/:aid/notes", {
+      params: { aid: note.aid },
+      body: note,
+    });
   }
-  async updateNote(note: UpdateNote): Promise<Note> {
-    throw new Error("Unimplemented");
+  async updateNote(note: UpdateNote, _ctx: { uid: string }): Promise<Note> {
+    this.#checkReadonly();
+    return this.#call("PATCH", "/notes/:nid", {
+      params: { nid: note.nid },
+      body: note,
+    });
   }
   async listNotesByAbodeId(aid: string): Promise<PartialNote[]> {
-    throw new Error("Unimplemented");
+    return this.#call("GET", "/abodes/:aid/notes", { params: { aid } });
   }
   async listNotesByUserId(uid: string): Promise<PartialNote[]> {
-    throw new Error("Unimplemented");
+    return this.#call("GET", "/users/:uid/notes", { params: { uid } });
   }
 }

src/db/postgres/PostgresInterface.ts

@@ -408,6 +408,14 @@ export class PostgresInterface implements BackendDbInterface {
     `);
   }
 
+  async deleteSession(token: `as_${string}`): Promise<void> {
+    this.#checkReadonly();
+    await this.#db.run(sql`
+      DELETE FROM "sessions"
+      WHERE "token" = ${{ text: token }}
+    `);
+  }
+
   async #getApikeyByToken(
     token: `at_${string}`,
     db: WrappedPgClient

src/db/postgres/PostgresMigrator.ts

@@ -5,7 +5,7 @@ import type {
 } from "../types/Migrator.js";
 import { init, migrations } from "./migrations/index.js";
 import { pgToDate } from "./cast.js";
-import { WrappedPool } from "./pool.js";
+import { rollbackQuietly, WrappedPgTx, WrappedPool } from "./pool.js";
 import { sql, toPositional } from "./sql.js";
 
 export class PostgresMigrator implements Migrator {
@@ -97,6 +97,7 @@ export class PostgresMigrator implements Migrator {
     for (const migration of toApply) {
       console.log(`Applying migration ${migration.id} (${migration.name})`);
       const client = await this.#pool._pool.connect();
+      const tx = new WrappedPgTx(client, false);
       try {
         await client.query("BEGIN");
         for (const part of migration.parts) {
@@ -104,7 +105,7 @@ export class PostgresMigrator implements Migrator {
           if ("sql" in part) {
             await client.query(part.sql);
           } else {
-            await part.apply(this.#pool);
+            await part.apply(tx);
           }
         }
         const recordSql = sql`
@@ -114,7 +115,7 @@ export class PostgresMigrator implements Migrator {
         await client.query(toPositional(recordSql._sql), recordSql._vars);
         await client.query("COMMIT");
       } catch (e) {
-        await client.query("ROLLBACK");
+        await rollbackQuietly(client);
         throw e;
       } finally {
         client.release();

src/db/postgres/pool.ts

@@ -29,12 +29,22 @@ async function rethrow<R>(fn: () => Promise<R>): Promise<R> {
   }
 }
 
-class WrappedPgTx implements WrappedPgClient {
-  #client: pg.PoolClient;
+// Rollback on a broken connection can itself throw; the original error is
+// the one worth surfacing.
+export async function rollbackQuietly(
+  client: pg.PoolClient
+): Promise<void> {
+  try {
+    await client.query("ROLLBACK");
+  } catch {}
+}
+
+abstract class WrappedPgBase implements WrappedPgClient {
+  #queryable: pg.Pool | pg.PoolClient;
   #readonly: boolean;
 
-  constructor(client: pg.PoolClient, readonly_: boolean) {
-    this.#client = client;
+  constructor(queryable: pg.Pool | pg.PoolClient, readonly_: boolean) {
+    this.#queryable = queryable;
     this.#readonly = readonly_;
   }
 
@@ -42,10 +52,14 @@ class WrappedPgTx implements WrappedPgClient {
     return this.#readonly;
   }
 
-  async destroy(): Promise<void> {}
+  abstract destroy(): Promise<void>;
+  abstract multi<R>(fn: (tx: WrappedPgClient) => Promise<R>): Promise<R>;
 
   async all<R>(stmt: SqlCode): Promise<R[]> {
-    const result = await this.#client.query(toPositional(stmt._sql), stmt._vars);
+    const result = await this.#queryable.query(
+      toPositional(stmt._sql),
+      stmt._vars
+    );
     return result.rows as R[];
   }
 
@@ -56,72 +70,61 @@ class WrappedPgTx implements WrappedPgClient {
   }
 
   async run(stmt: SqlCode): Promise<{ changes: number }> {
-    const result = await this.#client.query(toPositional(stmt._sql), stmt._vars);
+    const result = await this.#queryable.query(
+      toPositional(stmt._sql),
+      stmt._vars
+    );
     return { changes: result.rowCount ?? 0 };
   }
 
-  multi<R>(_fn: (tx: WrappedPgClient) => Promise<R>): Promise<R> {
-    throw new Error("Nested transactions not supported");
-  }
-
   rethrow = rethrow;
 }
 
-export class WrappedPool implements WrappedPgClient {
+export class WrappedPgTx extends WrappedPgBase {
+  constructor(client: pg.PoolClient, readonly_: boolean) {
+    super(client, readonly_);
+  }
+
+  async destroy(): Promise<void> {}
+
+  multi<R>(_fn: (tx: WrappedPgClient) => Promise<R>): Promise<R> {
+    throw new Error("Nested transactions not supported");
+  }
+}
+
+export class WrappedPool extends WrappedPgBase {
   #pool: pg.Pool;
-  #readonly: boolean;
 
   constructor(connectionStringOrPool: string | pg.Pool, readonly_ = false) {
-    this.#pool =
+    const pool =
       typeof connectionStringOrPool === "string"
         ? new pg.Pool({ connectionString: connectionStringOrPool })
         : connectionStringOrPool;
-    this.#readonly = readonly_;
+    super(pool, readonly_);
+    this.#pool = pool;
   }
 
   get _pool(): pg.Pool {
     return this.#pool;
   }
 
-  get readonly(): boolean {
-    return this.#readonly;
-  }
-
   async destroy(): Promise<void> {
     await this.#pool.end();
   }
 
-  async all<R>(stmt: SqlCode): Promise<R[]> {
-    const result = await this.#pool.query(toPositional(stmt._sql), stmt._vars);
-    return result.rows as R[];
-  }
-
-  async get<R>(stmt: SqlCode): Promise<R | null> {
-    const rows = await this.all<R>(stmt);
-    if (rows.length > 1) throw new Error("Multiple results");
-    return rows[0] ?? null;
-  }
-
-  async run(stmt: SqlCode): Promise<{ changes: number }> {
-    const result = await this.#pool.query(toPositional(stmt._sql), stmt._vars);
-    return { changes: result.rowCount ?? 0 };
-  }
-
   async multi<R>(fn: (tx: WrappedPgClient) => Promise<R>): Promise<R> {
     const client = await this.#pool.connect();
-    const tx = new WrappedPgTx(client, this.#readonly);
+    const tx = new WrappedPgTx(client, this.readonly);
     try {
       await client.query("BEGIN");
       const result = await fn(tx);
       await client.query("COMMIT");
       return result;
     } catch (e) {
-      await client.query("ROLLBACK");
+      await rollbackQuietly(client);
       throw e;
     } finally {
       client.release();
     }
   }
-
-  rethrow = rethrow;
 }

src/db/postgres/sql.ts

@@ -73,6 +73,9 @@ export function calcUpdates<T extends object>(updater: {
   };
 }
 
+// Rewrites every literal `?` into a numbered placeholder, so queries must
+// not contain Postgres's JSONB `?` / `?|` / `?&` operators (use
+// `jsonb_exists`, `jsonb_exists_any`, `jsonb_exists_all` instead).
 export function toPositional(sql: string): string {
   let i = 0;
   return sql.replace(/\?/g, () => `$${++i}`);

src/db/sqlite/SqliteInterface.ts

@@ -33,6 +33,8 @@ import {
   selectClientApikeys,
   selectClientUser,
   selectClientUsers,
+  selectNote,
+  selectPartialNotes,
   selectResident,
   selectResidents,
 } from "./query.js";
@@ -319,7 +321,7 @@ export class SqliteInterface implements BackendDbInterface {
             UPDATE "residents"
             SET
               "updated_at" = datetime('now', 'localtime', 'subsec'),
-              "updated_by" = ${{ uuid: ctx.uid }}
+              "updated_by" = ${{ uuid: ctx.uid }},
               ${joinSql(updates, sql`, `)}
             WHERE
               "uid" = ${{ uuid: resident.uid }}
@@ -392,6 +394,13 @@ export class SqliteInterface implements BackendDbInterface {
       WHERE "uid" = ${{ uuid: uid }}
     `);
   }
+  async deleteSession(token: `as_${string}`): Promise<void> {
+    this.#checkReadonly();
+    this.#db.run(sql`
+      DELETE FROM "sessions"
+      WHERE "token" = ${{ text: token }}
+    `);
+  }
 
   #getApikeyByToken(token: `at_${string}`): ClientApikey {
     const apikey = selectClientApikey(
@@ -458,24 +467,71 @@ export class SqliteInterface implements BackendDbInterface {
   }
 
   async listNotes(): Promise<PartialNote[]> {
-    throw new Error("Unimplemented");
+    return selectPartialNotes(this.#db);
+  }
+  #getNoteById(nid: string): Note {
+    const note = selectNote(this.#db, sql`n."nid" = ${{ uuid: nid }}`);
+    if (!note) throw new NotFoundAbodeError();
+    return note;
   }
   async getNoteById(nid: string): Promise<Note> {
-    throw new Error("Unimplemented");
+    return this.#getNoteById(nid);
   }
   async deleteNoteById(nid: string): Promise<void> {
-    throw new Error("Unimplemented");
+    this.#checkReadonly();
+    const { changes } = this.#db.run(
+      sql`DELETE FROM "notes" WHERE "nid" = ${{ uuid: nid }}`
+    );
+    if (!changes) throw new NotFoundAbodeError();
   }
   async createNote(note: CreateNote, ctx: { uid: string }): Promise<Note> {
-    throw new Error("Unimplemented");
+    this.#checkReadonly();
+    const nid = crypto.randomUUID();
+    return this.#db.rethrow(() =>
+      this.#db.multi(() => {
+        this.#db.run(sql`
+          INSERT INTO "notes"("nid", "aid", "name", "content", "properties", "created_by", "updated_by")
+          VALUES(
+            ${{ uuid: nid }},
+            ${{ uuid: note.aid }},
+            ${{ text: note.name }},
+            ${{ text: note.content ?? "" }},
+            ${{ jsonb: note.properties }},
+            ${{ uuid: ctx.uid }},
+            ${{ uuid: ctx.uid }}
+          )
+        `);
+        return this.#getNoteById(nid);
+      })
+    );
   }
   async updateNote(note: UpdateNote, ctx: { uid: string }): Promise<Note> {
-    throw new Error("Unimplemented");
+    this.#checkReadonly();
+    const updates = calcUpdates({
+      name: (value: string) => sql`"name" = ${{ text: value }}`,
+      content: (value: string) => sql`"content" = ${{ text: value }}`,
+      properties: (value: object) => sql`"properties" = ${{ jsonb: value }}`,
+    })(note);
+    if (!updates.length) throw new InvalidAbodeError();
+    return this.#db.rethrow(() =>
+      this.#db.multi(() => {
+        const { changes } = this.#db.run(sql`
+          UPDATE "notes"
+          SET
+            "updated_at" = datetime('now', 'localtime', 'subsec'),
+            "updated_by" = ${{ uuid: ctx.uid }},
+            ${joinSql(updates, sql`, `)}
+          WHERE "nid" = ${{ uuid: note.nid }}
+        `);
+        if (!changes) throw new NotFoundAbodeError();
+        return this.#getNoteById(note.nid);
+      })
+    );
   }
   async listNotesByAbodeId(aid: string): Promise<PartialNote[]> {
-    throw new Error("Unimplemented");
+    return selectPartialNotes(this.#db, sql`n."aid" = ${{ uuid: aid }}`);
   }
   async listNotesByUserId(uid: string): Promise<PartialNote[]> {
-    throw new Error("Unimplemented");
+    return selectPartialNotes(this.#db, sql`n."created_by" = ${{ uuid: uid }}`);
   }
 }

src/db/sqlite/cast.ts

@@ -1,5 +1,12 @@
 import type { Abode } from "../types/Abode.js";
 import type { ApikeyPermissions, ClientApikey } from "../types/Apikey.js";
+import type {
+  Note,
+  NoteProperties,
+  NoteType,
+  PartialNote,
+  PartialNoteProperties,
+} from "../types/Note.js";
 import type { Resident, ResidentFlags } from "../types/Resident.js";
 import type { ClientUser, PartialUser, UserFlags } from "../types/User.js";
 
@@ -160,3 +167,71 @@ export function sqliteToClientApikey(apikey: {
     expires_at: apikey.expires_at ? sqliteToDate(apikey.expires_at) : null,
   };
 }
+
+const validNoteTypes = new Set<NoteType>(["note"]);
+export function sqliteToNoteProperties(props: string): NoteProperties {
+  const parsed = JSON.parse(props);
+  const out: NoteProperties = {};
+  if (
+    typeof parsed === "object" &&
+    parsed &&
+    !Array.isArray(parsed) &&
+    validNoteTypes.has(parsed.type)
+  ) {
+    out.type = parsed.type;
+  }
+  return out;
+}
+
+export function sqliteToPartialNoteProperties(
+  props: string
+): PartialNoteProperties {
+  const base = sqliteToNoteProperties(props);
+  return { type: base.type ?? "note" };
+}
+
+export function sqliteToNote(note: {
+  nid: Buffer | Uint8Array;
+  aid: Buffer | Uint8Array;
+  name: string;
+  content: string;
+  properties: string;
+  created_at: string;
+  created_by: Buffer | Uint8Array | null;
+  updated_at: string;
+  updated_by: Buffer | Uint8Array | null;
+}): Note {
+  return {
+    nid: sqliteToUuid(note.nid),
+    aid: sqliteToUuid(note.aid),
+    name: note.name,
+    content: note.content,
+    properties: sqliteToNoteProperties(note.properties),
+    created_at: sqliteToDate(note.created_at),
+    created_by: note.created_by ? sqliteToUuid(note.created_by) : null,
+    updated_at: sqliteToDate(note.updated_at),
+    updated_by: note.updated_by ? sqliteToUuid(note.updated_by) : null,
+  };
+}
+
+export function sqliteToPartialNote(note: {
+  nid: Buffer | Uint8Array;
+  aid: Buffer | Uint8Array;
+  name: string;
+  properties: string;
+  created_at: string;
+  created_by: Buffer | Uint8Array | null;
+  updated_at: string;
+  updated_by: Buffer | Uint8Array | null;
+}): PartialNote {
+  return {
+    nid: sqliteToUuid(note.nid),
+    aid: sqliteToUuid(note.aid),
+    name: note.name,
+    properties: sqliteToPartialNoteProperties(note.properties),
+    created_at: sqliteToDate(note.created_at),
+    created_by: note.created_by ? sqliteToUuid(note.created_by) : null,
+    updated_at: sqliteToDate(note.updated_at),
+    updated_by: note.updated_by ? sqliteToUuid(note.updated_by) : null,
+  };
+}

src/db/sqlite/impl/better-sqlite3.ts

@@ -10,6 +10,7 @@ function getDatabase(
 ): sqlite.Database {
   if (!natives.sqlite) throw new Error("No natives found for better-sqlite3");
   options = { ...options };
+  if (typeof options.readonly !== "boolean") delete options.readonly;
   if (typeof options.timeout !== "number") delete options.timeout;
   const db = new Sqlite(path, { ...options, nativeBinding: natives.sqlite });
   db.exec(pragma);

src/db/sqlite/query.ts

@@ -1,11 +1,14 @@
 import type { Abode } from "../types/Abode.js";
 import type { ClientApikey } from "../types/Apikey.js";
+import type { Note, PartialNote } from "../types/Note.js";
 import type { Resident } from "../types/Resident.js";
 import type { ClientUser } from "../types/User.js";
 import {
   sqliteToAbode,
   sqliteToClientApikey,
   sqliteToClientUser,
+  sqliteToNote,
+  sqliteToPartialNote,
   sqliteToResident,
 } from "./cast.js";
 import type { WrappedDb } from "./impl/types.js";
@@ -122,3 +125,46 @@ export function selectClientApikeys(
   );
   return rawApikeys.map(sqliteToClientApikey);
 }
+
+type RawNote = {
+  nid: Buffer | Uint8Array;
+  aid: Buffer | Uint8Array;
+  name: string;
+  content: string;
+  properties: string;
+  created_at: string;
+  created_by: Buffer | Uint8Array | null;
+  updated_at: string;
+  updated_by: Buffer | Uint8Array | null;
+};
+const sqlNote = sql`
+  SELECT n."nid", n."aid", n."name", n."content", json(n."properties") AS "properties",
+         n."created_at", n."created_by", n."updated_at", n."updated_by"
+  FROM "notes" n
+`;
+
+type RawPartialNote = Omit<RawNote, "content">;
+const sqlPartialNote = sql`
+  SELECT n."nid", n."aid", n."name", json(n."properties") AS "properties",
+         n."created_at", n."created_by", n."updated_at", n."updated_by"
+  FROM "notes" n
+`;
+
+export function selectNote(db: WrappedDb, where: SqlCode): Note | null {
+  const raw = db.get<RawNote>(sql`${sqlNote} WHERE ${where}`);
+  if (raw) return sqliteToNote(raw);
+  return null;
+}
+export function selectNotes(db: WrappedDb, where?: SqlCode): Note[] {
+  const raws = db.all<RawNote>(where ? sql`${sqlNote} WHERE ${where}` : sqlNote);
+  return raws.map(sqliteToNote);
+}
+export function selectPartialNotes(
+  db: WrappedDb,
+  where?: SqlCode
+): PartialNote[] {
+  const raws = db.all<RawPartialNote>(
+    where ? sql`${sqlPartialNote} WHERE ${where}` : sqlPartialNote
+  );
+  return raws.map(sqliteToPartialNote);
+}

src/db/types/DbInterface.ts

@@ -85,6 +85,7 @@ export interface BackendDbInterface extends DbInterface {
   // auth by session
   getUserBySession(token: `as_${string}`): Promise<ClientUser>;
   createSession(uid: string): Promise<`as_${string}`>;
+  deleteSession(token: `as_${string}`): Promise<void>;
 
   // auth by apikey
   getUserByApikey(token: `at_${string}`): Promise<[ClientUser, ClientApikey]>;
@@ -98,6 +99,7 @@ export function isBackendInterface(db: DbInterface): db is BackendDbInterface {
         "getUserByLogin",
         "getUserBySession",
         "createSession",
+        "deleteSession",
         "getUserByApikey",
       ] as const
     ).every(

src/webapi/apirouter.ts

@@ -11,6 +11,7 @@ import {
   loginuser,
   updateabode,
   updateresident,
+  updatenote,
   updateuser,
 } from "../schema/validators.js";
 import { authenticate } from "./middleware/authenticate.js";
@@ -28,6 +29,8 @@ export function apirouter(db: BackendDbInterface): KoaRouter {
   });
   router.post("/auth/logout", authenticate(db), async (ctx) => {
     if (ctx.session!.source !== "session") throw new InvalidAbodeError();
+    const token = ctx.cookies.get("abode_session");
+    if (token) await db.deleteSession(token as `as_${string}`);
     ctx.cookies.set("abode_session", "", { expires: new Date("1970-01-01") });
     ctx.status = 204;
   });
@@ -92,11 +95,11 @@ export function apirouter(db: BackendDbInterface): KoaRouter {
     await db.deleteApikeyById(ctx.params.kid);
     ctx.status = 204;
   });
-  router.post("/user/:uid/auth/clear-sessions", async (ctx) => {
+  router.post("/users/:uid/auth/clear-sessions", async (ctx) => {
     await db.deleteSessionsByUser(ctx.params.uid);
     ctx.status = 204;
   });
-  router.get("/user/:uid/notes", async (ctx) => {
+  router.get("/users/:uid/notes", async (ctx) => {
     ctx.body = await db.listNotesByUserId(ctx.params.uid);
   });
 
@@ -186,7 +189,7 @@ export function apirouter(db: BackendDbInterface): KoaRouter {
   });
   router.patch(
     "/notes/:nid",
-    jsonBody({ includeParams: ["nid"] }),
+    jsonBody({ validate: updatenote, includeParams: ["nid"] }),
     async (ctx) => {
       ctx.body = await db.updateNote(ctx.request.body, { uid: ctx.user!.uid });
     }

test/backends/api/api-interface.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { ApiInterface } from "../../../src/db/api/ApiInterface.js";
+import { apiProtocols, isApiUrl, parseApiUrl } from "../../../src/db/api/url.js";
+import {
+  NotFoundAbodeError,
+  NotAuthorizedAbodeError,
+  ReadonlyAbodeError,
+  InvalidAbodeError,
+  ConflictAbodeError,
+} from "../../../src/db/types/errors.js";
+
+describe("ApiInterface static properties", () => {
+  it("name is 'api'", () => {
+    const api = new ApiInterface("http://localhost:9999");
+    assert.equal(api.name, "api");
+  });
+
+  it("backend is false", () => {
+    const api = new ApiInterface("http://localhost:9999");
+    assert.equal(api.backend, false);
+  });
+
+  it("readonly defaults to false", () => {
+    const api = new ApiInterface("http://localhost:9999");
+    assert.equal(api.readonly, false);
+  });
+
+  it("readonly is set from options", () => {
+    const api = new ApiInterface("http://localhost:9999", { readonly: true });
+    assert.equal(api.readonly, true);
+  });
+});
+
+describe("apiProtocols and isApiUrl", () => {
+  it("apiProtocols includes expected protocols", () => {
+    assert.ok(apiProtocols.includes("https:"));
+    assert.ok(apiProtocols.includes("http:"));
+    assert.ok(apiProtocols.includes("abode+https:"));
+    assert.ok(apiProtocols.includes("abode+http:"));
+  });
+
+  it("isApiUrl returns true for http/https urls", () => {
+    assert.equal(isApiUrl("http://example.com"), true);
+    assert.equal(isApiUrl("https://example.com/api"), true);
+    assert.equal(isApiUrl("abode+http://example.com"), true);
+    assert.equal(isApiUrl("abode+https://example.com"), true);
+  });
+
+  it("isApiUrl returns false for non-http urls", () => {
+    assert.equal(isApiUrl("sqlite:///db.sqlite"), false);
+    assert.equal(isApiUrl("not-a-url"), false);
+    assert.equal(isApiUrl("ftp://example.com"), false);
+  });
+});
+
+describe("parseApiUrl", () => {
+  it("strips abode+ prefix from protocol", () => {
+    const [root] = parseApiUrl("abode+http://example.com");
+    assert.ok(root.startsWith("http://"), `expected http:// got ${root}`);
+  });
+
+  it("extracts Basic auth from URL credentials", () => {
+    const [, { headers }] = parseApiUrl("http://user:pass@example.com");
+    assert.ok(headers["Authorization"]?.startsWith("Basic "), "has Basic auth");
+    const decoded = atob(headers["Authorization"]!.slice("Basic ".length));
+    assert.equal(decoded, "user:pass");
+  });
+
+  it("strips credentials from root URL", () => {
+    const [root] = parseApiUrl("http://user:pass@example.com");
+    assert.ok(!root.includes("user"), "credentials stripped from root");
+  });
+
+  it("extracts readonly flag from query", () => {
+    const [, { readonly }] = parseApiUrl("http://example.com?readonly=1");
+    assert.equal(readonly, true);
+  });
+
+  it("defaults readonly to false", () => {
+    const [, { readonly }] = parseApiUrl("http://example.com");
+    assert.equal(readonly, false);
+  });
+
+  it("extra query params become headers", () => {
+    const [, { headers }] = parseApiUrl(
+      "http://example.com?X-Custom-Header=value"
+    );
+    assert.equal(headers["X-Custom-Header"], "value");
+  });
+
+  it("throws for non-api protocol", () => {
+    assert.throws(
+      () => parseApiUrl("sqlite:///db.sqlite"),
+      /Not an \{abode\+,\}http\{s,\}: protocol/
+    );
+  });
+});
+
+describe("ApiInterface HTTP error mapping", () => {
+  let serverUrl: string;
+  let closeServer: () => Promise<void>;
+  let respondWith: (status: number) => void;
+
+  before(async () => {
+    let nextStatus = 500;
+    respondWith = (s) => { nextStatus = s; };
+
+    const server = createServer((req, res) => {
+      res.writeHead(nextStatus, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: false, error: "test" }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address() as AddressInfo;
+    serverUrl = `http://127.0.0.1:${port}`;
+    closeServer = () =>
+      new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve()))
+      );
+  });
+
+  after(() => closeServer());
+
+  it("404 response throws NotFoundAbodeError", async () => {
+    respondWith(404);
+    const api = new ApiInterface(serverUrl);
+    await assert.rejects(
+      () => api.listUsers(),
+      (err) => {
+        assert.ok(err instanceof NotFoundAbodeError);
+        return true;
+      }
+    );
+  });
+
+  it("401 response throws NotAuthorizedAbodeError", async () => {
+    respondWith(401);
+    const api = new ApiInterface(serverUrl);
+    await assert.rejects(
+      () => api.listUsers(),
+      (err) => {
+        assert.ok(err instanceof NotAuthorizedAbodeError);
+        return true;
+      }
+    );
+  });
+
+  it("403 response throws ReadonlyAbodeError", async () => {
+    respondWith(403);
+    const api = new ApiInterface(serverUrl);
+    await assert.rejects(
+      () => api.listUsers(),
+      (err) => {
+        assert.ok(err instanceof ReadonlyAbodeError);
+        return true;
+      }
+    );
+  });
+
+  it("400 response throws InvalidAbodeError", async () => {
+    respondWith(400);
+    const api = new ApiInterface(serverUrl);
+    await assert.rejects(
+      () => api.listUsers(),
+      (err) => {
+        assert.ok(err instanceof InvalidAbodeError);
+        return true;
+      }
+    );
+  });
+
+  it("409 response throws ConflictAbodeError", async () => {
+    respondWith(409);
+    const api = new ApiInterface(serverUrl);
+    await assert.rejects(
+      () => api.listUsers(),
+      (err) => {
+        assert.ok(err instanceof ConflictAbodeError);
+        return true;
+      }
+    );
+  });
+});
+
+describe("ApiInterface._ internal helpers", () => {
+  it("_.url builds correct URL for path params (no leftover query param)", () => {
+    const api = new ApiInterface("http://example.com");
+    const url = api._.url("/users/:uid", { uid: "abc-123" });
+    assert.equal(url, "http://example.com/users/abc-123");
+  });
+
+  it("_.url puts remaining params as query string", () => {
+    const api = new ApiInterface("http://example.com");
+    const url = api._.url("/users/by-email", { email: "a@b.com" });
+    assert.ok(url.includes("email="), `expected query param in ${url}`);
+  });
+
+  it("_.root matches the constructor argument", () => {
+    const api = new ApiInterface("http://example.com/api");
+    assert.equal(api._.root, "http://example.com/api");
+  });
+
+  it("_.headers includes Authorization when set", () => {
+    const api = new ApiInterface("http://example.com", {
+      headers: { Authorization: "Basic dGVzdA==" },
+    });
+    assert.equal(api._.headers["Authorization"], "Basic dGVzdA==");
+  });
+});

test/backends/api/auth-http.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "../../helpers/sqlite.js";
+import { createTestServer, type TestServer } from "../../helpers/koa.js";
+import { hashPassword } from "../../../src/util/hash.js";
+import type { SqliteInterface } from "../../../src/db/sqlite/SqliteInterface.js";
+
+const EMAIL = "auth-http@test.example";
+const PASSWORD = "auth-http-password";
+
+function getCookie(res: Response, name: string): string | undefined {
+  const raw = res.headers.getSetCookie?.() ?? [];
+  for (const entry of raw) {
+    const [pair] = entry.split(";");
+    const [key, value] = pair.split("=");
+    if (key === name) return value;
+  }
+  return undefined;
+}
+
+describe("api backend: auth over HTTP", async () => {
+  let db: SqliteInterface;
+  let closeDb: () => void;
+  let server: TestServer;
+  let uid: string;
+
+  before(async () => {
+    ({ db, close: closeDb } = await createTestDb());
+    server = await createTestServer(db);
+    const pw = await hashPassword(PASSWORD);
+    const user = await db.createUser({
+      email: EMAIL,
+      name: "Auth HTTP User",
+      password: pw,
+      flags: {},
+    });
+    uid = user.uid;
+  });
+
+  after(async () => {
+    await server.close();
+    closeDb();
+  });
+
+  it("POST /auth/login sets a session cookie", async () => {
+    const res = await fetch(`${server.url}/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
+    });
+    assert.equal(res.status, 200);
+    const cookie = getCookie(res, "abode_session");
+    assert.ok(cookie, "session cookie set");
+  });
+
+  it("session cookie authenticates GET /auth/self", async () => {
+    const login = await fetch(`${server.url}/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
+    });
+    const cookie = getCookie(login, "abode_session");
+
+    const self = await fetch(`${server.url}/auth/self`, {
+      headers: { Cookie: `abode_session=${cookie}` },
+    });
+    assert.equal(self.status, 200);
+    const body = (await self.json()) as { uid: string };
+    assert.equal(body.uid, uid);
+  });
+
+  it("GET /auth/self without credentials returns 401", async () => {
+    const res = await fetch(`${server.url}/auth/self`);
+    assert.equal(res.status, 401);
+  });
+
+  it("POST /auth/logout clears the cookie and invalidates the session server-side", async () => {
+    const login = await fetch(`${server.url}/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
+    });
+    const cookie = getCookie(login, "abode_session");
+
+    const logout = await fetch(`${server.url}/auth/logout`, {
+      method: "POST",
+      headers: { Cookie: `abode_session=${cookie}` },
+    });
+    assert.equal(logout.status, 204);
+    assert.equal(getCookie(logout, "abode_session"), "");
+
+    const self = await fetch(`${server.url}/auth/self`, {
+      headers: { Cookie: `abode_session=${cookie}` },
+    });
+    assert.equal(self.status, 401, "session was invalidated server-side, not just the cookie cleared");
+  });
+
+  it("POST /auth/clear-sessions invalidates outstanding session cookies", async () => {
+    const login = await fetch(`${server.url}/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
+    });
+    const cookie = getCookie(login, "abode_session");
+
+    const clear = await fetch(`${server.url}/auth/clear-sessions`, {
+      method: "POST",
+      headers: { Cookie: `abode_session=${cookie}` },
+    });
+    assert.equal(clear.status, 204);
+
+    const self = await fetch(`${server.url}/auth/self`, {
+      headers: { Cookie: `abode_session=${cookie}` },
+    });
+    assert.equal(self.status, 401);
+  });
+
+  it("Bearer apikey token authenticates protected routes", async () => {
+    const [, token] = await db.createApikey({
+      uid,
+      name: "HTTP Test Key",
+      permissions: { all: true },
+    });
+
+    const res = await fetch(`${server.url}/users`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    assert.equal(res.status, 200);
+  });
+
+  it("invalid Bearer apikey token returns 401 invalid_apikey", async () => {
+    const res = await fetch(`${server.url}/users`, {
+      headers: { Authorization: `Bearer at_${"0".repeat(32)}` },
+    });
+    assert.equal(res.status, 401);
+    const body = (await res.json()) as { error: string };
+    assert.equal(body.error, "invalid_apikey");
+  });
+});

test/backends/api/index.test.ts

@@ -0,0 +1,52 @@
+import { createTestDb } from "../../helpers/sqlite.js";
+import { createTestServer } from "../../helpers/koa.js";
+import { ApiInterface } from "../../../src/db/api/ApiInterface.js";
+import { hashPassword } from "../../../src/util/hash.js";
+import { runUserTests } from "../../shared/users.js";
+import { runAbodeTests } from "../../shared/abodes.js";
+import { runResidentTests } from "../../shared/residents.js";
+import { runApikeyTests } from "../../shared/apikeys.js";
+
+const AUTH_EMAIL = "api-auth@test.example";
+const AUTH_PASSWORD = "api-auth-password";
+
+async function getApiDb() {
+  const { db: sqliteDb, close: closeSqlite } = await createTestDb();
+  const pw = await hashPassword(AUTH_PASSWORD);
+  await sqliteDb.createUser({
+    email: AUTH_EMAIL,
+    name: "API Auth User",
+    password: pw,
+    flags: {},
+  });
+  const server = await createTestServer(sqliteDb);
+  const authHeader = "Basic " + btoa(`${AUTH_EMAIL}:${AUTH_PASSWORD}`);
+  const api = new ApiInterface(server.url, {
+    headers: { Authorization: authHeader },
+  });
+  return {
+    db: api,
+    close: async () => {
+      await server.close();
+      closeSqlite();
+    },
+  };
+}
+
+async function getReadonlyApiDb() {
+  const { db: sqliteDb, close: closeSqlite } = await createTestDb();
+  const server = await createTestServer(sqliteDb);
+  const api = new ApiInterface(server.url, { readonly: true });
+  return {
+    db: api,
+    close: async () => {
+      await server.close();
+      closeSqlite();
+    },
+  };
+}
+
+runUserTests("api", getApiDb, getReadonlyApiDb);
+runAbodeTests("api", getApiDb);
+runResidentTests("api", getApiDb);
+runApikeyTests("api", getApiDb);

test/backends/sqlite/index.test.ts

@@ -0,0 +1,38 @@
+import type { BackendDbInterface } from "../../../src/db/types/DbInterface.js";
+import { SqliteInterface } from "../../../src/db/sqlite/SqliteInterface.js";
+import { createTestDb, createReadonlyTestDb } from "../../helpers/sqlite.js";
+import { runUserTests } from "../../shared/users.js";
+import { runAbodeTests } from "../../shared/abodes.js";
+import { runResidentTests } from "../../shared/residents.js";
+import { runApikeyTests } from "../../shared/apikeys.js";
+import { runSessionTests } from "../../shared/sessions.js";
+import { runAuthTests } from "../../shared/auth.js";
+
+async function createExpiredApikey(
+  db: BackendDbInterface,
+  uid: string
+): Promise<`at_${string}`> {
+  const si = db as SqliteInterface;
+  const token = (`at_${"e".repeat(32)}`) as `at_${string}`;
+  const kid = crypto.randomUUID();
+  const { sql } = si._;
+  si._.db.run(sql`
+    INSERT INTO "apikeys"("uid", "kid", "token", "name", "permissions", "expires_at")
+    VALUES(
+      ${{ uuid: uid }},
+      ${{ uuid: kid }},
+      ${{ text: token }},
+      ${{ text: "Expired Key" }},
+      ${{ jsonb: {} }},
+      ${{ date: new Date(Date.now() - 10000).toISOString() }}
+    )
+  `);
+  return token;
+}
+
+runUserTests("sqlite", createTestDb, createReadonlyTestDb);
+runAbodeTests("sqlite", createTestDb);
+runResidentTests("sqlite", createTestDb);
+runApikeyTests("sqlite", createTestDb);
+runSessionTests("sqlite", createTestDb);
+runAuthTests("sqlite", createTestDb, createExpiredApikey);

test/backends/sqlite/migrator.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { WrappedNodeSqliteDb } from "../../../src/db/sqlite/impl/node-sqlite.js";
+import { SqliteMigrator } from "../../../src/db/sqlite/SqliteMigrator.js";
+import { migrations } from "../../../src/db/sqlite/migrations/index.js";
+
+describe("SqliteMigrator", () => {
+  it("listAvailableMigrations returns all known migrations", () => {
+    const db = new WrappedNodeSqliteDb(":memory:");
+    const migrator = new SqliteMigrator(db);
+    const available = migrator.listAvailableMigrations();
+    assert.ok(Array.isArray(available));
+    assert.ok(available.length >= 3, "at least 3 migrations");
+    const ids = available.map((m) => m.id);
+    assert.ok(ids.includes(1), "migration 1 present");
+    assert.ok(ids.includes(2), "migration 2 present");
+    assert.ok(ids.includes(3), "migration 3 present");
+    db.destroy();
+  });
+
+  it("listAppliedMigrations returns empty array on fresh db", async () => {
+    const db = new WrappedNodeSqliteDb(":memory:");
+    const migrator = new SqliteMigrator(db);
+    const applied = await migrator.listAppliedMigrations();
+    assert.deepEqual(applied, []);
+    db.destroy();
+  });
+
+  it("migrateTo(1) applies first migration", async () => {
+    const db = new WrappedNodeSqliteDb(":memory:");
+    const migrator = new SqliteMigrator(db);
+    await migrator.migrateTo(1);
+    const applied = await migrator.listAppliedMigrations();
+    assert.equal(applied.length, 1);
+    assert.equal(applied[0].id, 1);
+    assert.ok(applied[0].name, "migration has a name");
+    assert.ok(applied[0].applied_at, "migration has applied_at");
+    db.destroy();
+  });
+
+  it("migrateTo(3) applies all three migrations in order", async () => {
+    const db = new WrappedNodeSqliteDb(":memory:");
+    const migrator = new SqliteMigrator(db);
+    await migrator.migrateTo(3);
+    const applied = await migrator.listAppliedMigrations();
+    assert.equal(applied.length, 3);
+    assert.deepEqual(
+      applied.map((m) => m.id),
+      [1, 2, 3]
+    );
+    db.destroy();
+  });
+
+  it("migrateTo(3) twice is idempotent (nothing to do)", async () => {
+    const db = new WrappedNodeSqliteDb(":memory:");
+    const migrator = new SqliteMigrator(db);
+    await migrator.migrateTo(3);
+    await migrator.migrateTo(3);
+    const applied = await migrator.listAppliedMigrations();
+    assert.equal(applied.length, 3);
+    db.destroy();
+  });
+
+  it("migrateTo with unknown id throws", async () => {
+    const db = new WrappedNodeSqliteDb(":memory:");
+    const migrator = new SqliteMigrator(db);
+    await assert.rejects(
+      () => migrator.migrateTo(9999),
+      /No known migration with id 9999/
+    );
+    db.destroy();
+  });
+
+  it("listAvailableMigrations names match migration objects", () => {
+    const db = new WrappedNodeSqliteDb(":memory:");
+    const migrator = new SqliteMigrator(db);
+    const available = migrator.listAvailableMigrations();
+    for (const { id, name } of available) {
+      const migration = migrations.find((m) => m.id === id);
+      assert.ok(migration, `migration ${id} exists`);
+      assert.equal(migration.name, name);
+    }
+    db.destroy();
+  });
+});

test/backends/sqlite/sql.test.ts

@@ -0,0 +1,134 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { sql, catSql, joinSql, calcUpdates, unsafeSql } from "../../../src/db/sqlite/sql.js";
+
+describe("sql template tag", () => {
+  it("produces correct sql and empty vars for plain text", () => {
+    const result = sql`SELECT 1`;
+    assert.equal(result._sql, "SELECT 1");
+    assert.deepEqual(result._vars, []);
+  });
+
+  it("binds text args with ?", () => {
+    const result = sql`WHERE name = ${{ text: "alice" }}`;
+    assert.equal(result._sql, "WHERE name = ?");
+    assert.deepEqual(result._vars, ["alice"]);
+  });
+
+  it("binds uuid args with ? and converts to Buffer", () => {
+    const uuid = "12345678-1234-1234-1234-123456789abc";
+    const result = sql`WHERE uid = ${{ uuid }}`;
+    assert.equal(result._sql, "WHERE uid = ?");
+    assert.equal(result._vars.length, 1);
+    assert.ok(result._vars[0] instanceof Buffer, "uuid is stored as Buffer");
+  });
+
+  it("binds jsonb args with jsonb(?) wrapper", () => {
+    const result = sql`SET flags = ${{ jsonb: { admin: true } }}`;
+    assert.equal(result._sql, "SET flags = jsonb(?)");
+    assert.deepEqual(result._vars, [JSON.stringify({ admin: true })]);
+  });
+
+  it("binds date args with datetime(?, ...) wrapper", () => {
+    const date = "2024-01-01T00:00:00.000Z";
+    const result = sql`SET ts = ${{ date }}`;
+    assert.ok(result._sql.startsWith("SET ts = datetime("), result._sql);
+    assert.equal(result._vars.length, 1);
+  });
+
+  it("binds int args with ?", () => {
+    const result = sql`LIMIT ${{ int: 10 }}`;
+    assert.equal(result._sql, "LIMIT ?");
+    assert.deepEqual(result._vars, [10]);
+  });
+
+  it("throws for non-integer int value", () => {
+    assert.throws(() => sql`LIMIT ${{ int: 10.5 }}`, /Not an integer/);
+  });
+
+  it("emits NULL for null args", () => {
+    const result = sql`= ${{ null: true }}`;
+    assert.equal(result._sql, "= NULL");
+    assert.deepEqual(result._vars, []);
+  });
+
+  it("splices nested SqlCode", () => {
+    const inner = sql`AND x = ${{ text: "foo" }}`;
+    const outer = sql`WHERE 1=1 ${inner}`;
+    assert.equal(outer._sql, "WHERE 1=1 AND x = ?");
+    assert.deepEqual(outer._vars, ["foo"]);
+  });
+
+  it("handles multiple args", () => {
+    const result = sql`INSERT INTO t(a,b) VALUES(${{ text: "x" }}, ${{ int: 42 }})`;
+    assert.equal(result._sql, "INSERT INTO t(a,b) VALUES(?, ?)");
+    assert.deepEqual(result._vars, ["x", 42]);
+  });
+});
+
+describe("catSql", () => {
+  it("concatenates sql and vars", () => {
+    const a = sql`SELECT * FROM t`;
+    const b = sql` WHERE x = ${{ text: "y" }}`;
+    const result = catSql(a, b);
+    assert.equal(result._sql, "SELECT * FROM t WHERE x = ?");
+    assert.deepEqual(result._vars, ["y"]);
+  });
+});
+
+describe("joinSql", () => {
+  it("joins multiple parts with separator", () => {
+    const parts = [
+      sql`a = ${{ text: "1" }}`,
+      sql`b = ${{ text: "2" }}`,
+      sql`c = ${{ text: "3" }}`,
+    ];
+    const result = joinSql(parts, sql`, `);
+    assert.equal(result._sql, "a = ?, b = ?, c = ?");
+    assert.deepEqual(result._vars, ["1", "2", "3"]);
+  });
+
+  it("returns single part unchanged (no separator)", () => {
+    const result = joinSql([sql`x = ${{ int: 1 }}`], sql`, `);
+    assert.equal(result._sql, "x = ?");
+    assert.deepEqual(result._vars, [1]);
+  });
+});
+
+describe("calcUpdates", () => {
+  it("returns only keys present in the object", () => {
+    const calc = calcUpdates({
+      name: (v: string) => sql`name = ${{ text: v }}`,
+      email: (v: string) => sql`email = ${{ text: v }}`,
+    });
+    const updates = calc({ name: "alice" });
+    assert.equal(updates.length, 1);
+    assert.equal(updates[0]._sql, "name = ?");
+    assert.deepEqual(updates[0]._vars, ["alice"]);
+  });
+
+  it("returns all keys when all are present", () => {
+    const calc = calcUpdates({
+      a: (v: string) => sql`a = ${{ text: v }}`,
+      b: (v: string) => sql`b = ${{ text: v }}`,
+    });
+    const updates = calc({ a: "x", b: "y" });
+    assert.equal(updates.length, 2);
+  });
+
+  it("returns empty array when no keys match", () => {
+    const calc = calcUpdates({
+      name: (v: string) => sql`name = ${{ text: v }}`,
+    });
+    const updates = calc({});
+    assert.equal(updates.length, 0);
+  });
+});
+
+describe("unsafeSql", () => {
+  it("wraps a raw sql string with no vars", () => {
+    const result = unsafeSql("CREATE TABLE t (id INTEGER)");
+    assert.equal(result._sql, "CREATE TABLE t (id INTEGER)");
+    assert.deepEqual(result._vars, []);
+  });
+});

test/backends/sqlite/wrapped-db.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { WrappedNodeSqliteDb } from "../../../src/db/sqlite/impl/node-sqlite.js";
+import { sql, unsafeSql } from "../../../src/db/sqlite/sql.js";
+import type { WrappedDb } from "../../../src/db/sqlite/impl/types.js";
+
+function runWrappedDbSuite(name: string, makeDb: () => WrappedDb) {
+  describe(`${name}: WrappedDb`, () => {
+    let db: WrappedDb;
+
+    before(() => {
+      db = makeDb();
+      db.run(unsafeSql("CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY, val TEXT NOT NULL)"));
+    });
+
+    after(() => db.destroy());
+
+    it("run INSERT returns changes count", () => {
+      const { changes } = db.run(sql`INSERT INTO test(val) VALUES(${{ text: "hello" }})`);
+      assert.equal(changes, 1);
+    });
+
+    it("all SELECT returns all rows", () => {
+      db.run(unsafeSql("DELETE FROM test"));
+      db.run(sql`INSERT INTO test(val) VALUES(${{ text: "a" }})`);
+      db.run(sql`INSERT INTO test(val) VALUES(${{ text: "b" }})`);
+      const rows = db.all<{ val: string }>(unsafeSql("SELECT val FROM test ORDER BY val"));
+      assert.equal(rows.length, 2);
+      assert.equal(rows[0].val, "a");
+      assert.equal(rows[1].val, "b");
+    });
+
+    it("get returns single row or null", () => {
+      db.run(unsafeSql("DELETE FROM test"));
+      db.run(sql`INSERT INTO test(val) VALUES(${{ text: "one" }})`);
+      const row = db.get<{ val: string }>(unsafeSql("SELECT val FROM test"));
+      assert.ok(row !== null);
+      assert.equal(row.val, "one");
+
+      const none = db.get<{ val: string }>(
+        sql`SELECT val FROM test WHERE val = ${{ text: "none" }}`
+      );
+      assert.equal(none, null);
+    });
+
+    it("get throws when multiple rows match", () => {
+      db.run(unsafeSql("DELETE FROM test"));
+      db.run(sql`INSERT INTO test(val) VALUES(${{ text: "dup1" }})`);
+      db.run(sql`INSERT INTO test(val) VALUES(${{ text: "dup2" }})`);
+      assert.throws(
+        () => db.get<{ val: string }>(unsafeSql("SELECT val FROM test")),
+        /Multiple results/
+      );
+    });
+
+    it("multi commits on success", () => {
+      db.run(unsafeSql("DELETE FROM test"));
+      db.multi(() => {
+        db.run(sql`INSERT INTO test(val) VALUES(${{ text: "in-tx" }})`);
+      });
+      const rows = db.all<{ val: string }>(unsafeSql("SELECT val FROM test"));
+      assert.equal(rows.length, 1);
+      assert.equal(rows[0].val, "in-tx");
+    });
+
+    it("multi rolls back on error", () => {
+      db.run(unsafeSql("DELETE FROM test"));
+      assert.throws(() =>
+        db.multi(() => {
+          db.run(sql`INSERT INTO test(val) VALUES(${{ text: "rollback" }})`);
+          throw new Error("abort!");
+        })
+      );
+      const rows = db.all<{ val: string }>(unsafeSql("SELECT val FROM test"));
+      assert.equal(rows.length, 0);
+    });
+
+    it("rethrow passes through return value", () => {
+      const result = db.rethrow(() => 42);
+      assert.equal(result, 42);
+    });
+
+    it("rethrow propagates non-SQLite errors unchanged", () => {
+      const err = new Error("custom error");
+      assert.throws(() => db.rethrow(() => { throw err; }), (e) => e === err);
+    });
+  });
+}
+
+runWrappedDbSuite("node-sqlite", () => new WrappedNodeSqliteDb(":memory:"));
+
+describe("better-sqlite3 WrappedDb", async () => {
+  let bs3Ctor: (new (path: string) => WrappedDb) | null = null;
+
+  try {
+    const mod = await import(
+      "../../../src/db/sqlite/impl/better-sqlite3.js"
+    );
+    bs3Ctor = mod.WrappedBetterSqlite3Db;
+  } catch {
+    // better-sqlite3 not available, skip
+  }
+
+  if (bs3Ctor) {
+    runWrappedDbSuite("better-sqlite3", () => new bs3Ctor!(":memory:"));
+  } else {
+    it("better-sqlite3 is not available - skipped", (t) => {
+      t.skip("better-sqlite3 optional dependency not found");
+    });
+  }
+});

test/helpers/koa.ts

@@ -0,0 +1,29 @@
+import Koa from "koa";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { apirouter } from "../../src/webapi/apirouter.js";
+import type { BackendDbInterface } from "../../src/db/types/DbInterface.js";
+
+export interface TestServer {
+  url: string;
+  close(): Promise<void>;
+}
+
+export async function createTestServer(
+  db: BackendDbInterface
+): Promise<TestServer> {
+  const app = new Koa();
+  const router = apirouter(db);
+  app.use(router.routes());
+  app.use(router.allowedMethods());
+  const server = createServer(app.callback());
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    close: () =>
+      new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve()))
+      ),
+  };
+}

test/helpers/sqlite.ts

@@ -0,0 +1,24 @@
+import { getWrappedDb } from "../../src/db/sqlite/impl/index.js";
+import { SqliteMigrator } from "../../src/db/sqlite/SqliteMigrator.js";
+import { SqliteInterface } from "../../src/db/sqlite/SqliteInterface.js";
+import type { WrappedDb } from "../../src/db/sqlite/impl/types.js";
+
+export interface TestDb {
+  db: SqliteInterface;
+  wrapped: WrappedDb;
+  close(): void;
+}
+
+export async function createTestDb(): Promise<TestDb> {
+  const wrapped = getWrappedDb("node", ":memory:", {});
+  const migrator = new SqliteMigrator(wrapped);
+  await migrator.migrateTo(3);
+  const db = new SqliteInterface(wrapped);
+  return { db, wrapped, close: () => wrapped.destroy() };
+}
+
+export async function createReadonlyTestDb(): Promise<TestDb> {
+  const wrapped = getWrappedDb("node", ":memory:", { readonly: true });
+  const db = new SqliteInterface(wrapped);
+  return { db, wrapped, close: () => wrapped.destroy() };
+}

test/shared/abodes.ts

@@ -0,0 +1,109 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import type { DbInterface } from "../../src/db/types/DbInterface.js";
+import { NotFoundAbodeError, InvalidAbodeError } from "../../src/db/types/errors.js";
+import { hashPassword } from "../../src/util/hash.js";
+
+export function runAbodeTests(
+  name: string,
+  getDb: () => Promise<{ db: DbInterface; close(): void }>
+): void {
+  describe(`${name}: abodes`, async () => {
+    let db: DbInterface;
+    let close: () => void;
+    let ctxUid: string;
+
+    before(async () => {
+      ({ db, close } = await getDb());
+      const pw = await hashPassword("abode-ctx");
+      const user = await db.createUser({
+        email: `abode-ctx-${Date.now()}@test.example`,
+        name: "Abode Ctx User",
+        password: pw,
+        flags: {},
+      });
+      ctxUid = user.uid;
+    });
+
+    after(() => close());
+
+    it("createAbode returns an Abode with expected fields", async () => {
+      const abode = await db.createAbode({ name: "Test Abode" }, { uid: ctxUid });
+      assert.ok(abode.aid, "has aid");
+      assert.equal(abode.name, "Test Abode");
+      assert.ok(abode.created_at);
+      assert.ok(abode.updated_at);
+    });
+
+    it("getAbodeById returns the created abode", async () => {
+      const created = await db.createAbode({ name: "ById Abode" }, { uid: ctxUid });
+      const found = await db.getAbodeById(created.aid);
+      assert.equal(found.aid, created.aid);
+      assert.equal(found.name, "ById Abode");
+    });
+
+    it("getAbodeById throws NotFoundAbodeError for unknown aid", async () => {
+      await assert.rejects(
+        () => db.getAbodeById("00000000-0000-0000-0000-000000000000"),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("listAbodes includes the created abode", async () => {
+      const created = await db.createAbode(
+        { name: `Listed Abode ${Date.now()}` },
+        { uid: ctxUid }
+      );
+      const abodes = await db.listAbodes();
+      assert.ok(Array.isArray(abodes));
+      const found = abodes.find((a) => a.aid === created.aid);
+      assert.ok(found, "created abode appears in listAbodes");
+    });
+
+    it("updateAbode updates the name", async () => {
+      const created = await db.createAbode({ name: "Before" }, { uid: ctxUid });
+      const updated = await db.updateAbode(
+        { aid: created.aid, name: "After" },
+        { uid: ctxUid }
+      );
+      assert.equal(updated.aid, created.aid);
+      assert.equal(updated.name, "After");
+    });
+
+    it("updateAbode with no fields throws InvalidAbodeError", async () => {
+      const created = await db.createAbode({ name: "No Update" }, { uid: ctxUid });
+      await assert.rejects(
+        () => db.updateAbode({ aid: created.aid }, { uid: ctxUid }),
+        (err) => {
+          assert.ok(err instanceof InvalidAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteAbodeById removes the abode", async () => {
+      const created = await db.createAbode({ name: "To Delete" }, { uid: ctxUid });
+      await db.deleteAbodeById(created.aid);
+      await assert.rejects(
+        () => db.getAbodeById(created.aid),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteAbodeById throws NotFoundAbodeError for unknown aid", async () => {
+      await assert.rejects(
+        () => db.deleteAbodeById("00000000-0000-0000-0000-000000000000"),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+}

test/shared/apikeys.ts

@@ -0,0 +1,102 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import type { DbInterface } from "../../src/db/types/DbInterface.js";
+import { NotFoundAbodeError } from "../../src/db/types/errors.js";
+import { hashPassword } from "../../src/util/hash.js";
+
+export function runApikeyTests(
+  name: string,
+  getDb: () => Promise<{ db: DbInterface; close(): void }>
+): void {
+  describe(`${name}: apikeys`, async () => {
+    let db: DbInterface;
+    let close: () => void;
+    let uid: string;
+
+    before(async () => {
+      ({ db, close } = await getDb());
+      const pw = await hashPassword("apikey-password");
+      const user = await db.createUser({
+        email: `apikey-user-${Date.now()}@test.example`,
+        name: "Apikey User",
+        password: pw,
+        flags: {},
+      });
+      uid = user.uid;
+    });
+
+    after(() => close());
+
+    it("createApikey returns [ClientApikey, at_token]", async () => {
+      const [apikey, token] = await db.createApikey({
+        uid,
+        name: "Test Key",
+        permissions: {},
+      });
+      assert.ok(apikey.kid, "has kid");
+      assert.equal(apikey.uid, uid);
+      assert.equal(apikey.name, "Test Key");
+      assert.ok(!("token" in apikey), "ClientApikey has no token field");
+      assert.ok(token.startsWith("at_"), `token starts with at_: ${token}`);
+    });
+
+    it("listApikeysByUser returns created key", async () => {
+      const [created] = await db.createApikey({
+        uid,
+        name: "List Key",
+        permissions: {},
+      });
+      const keys = await db.listApikeysByUser(uid);
+      assert.ok(Array.isArray(keys));
+      const found = keys.find((k) => k.kid === created.kid);
+      assert.ok(found, "created key appears in listApikeysByUser");
+    });
+
+    it("getApikeyById returns the key", async () => {
+      const [created] = await db.createApikey({
+        uid,
+        name: "GetById Key",
+        permissions: {},
+      });
+      const found = await db.getApikeyById(created.kid);
+      assert.equal(found.kid, created.kid);
+      assert.equal(found.name, "GetById Key");
+    });
+
+    it("getApikeyById throws NotFoundAbodeError for unknown kid", async () => {
+      await assert.rejects(
+        () => db.getApikeyById("00000000-0000-0000-0000-000000000000"),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteApikeyById removes the key", async () => {
+      const [created] = await db.createApikey({
+        uid,
+        name: "Delete Key",
+        permissions: {},
+      });
+      await db.deleteApikeyById(created.kid);
+      await assert.rejects(
+        () => db.getApikeyById(created.kid),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteApikeyById throws NotFoundAbodeError for unknown kid", async () => {
+      await assert.rejects(
+        () => db.deleteApikeyById("00000000-0000-0000-0000-000000000000"),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+}

test/shared/auth.ts

@@ -0,0 +1,136 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import type { BackendDbInterface } from "../../src/db/types/DbInterface.js";
+import {
+  NotFoundAbodeError,
+  NotAuthorizedAbodeError,
+  ConflictAbodeError,
+} from "../../src/db/types/errors.js";
+import { hashPassword } from "../../src/util/hash.js";
+
+export function runAuthTests(
+  name: string,
+  getDb: () => Promise<{ db: BackendDbInterface; close(): void }>,
+  createExpiredApikey?: (db: BackendDbInterface, uid: string) => Promise<`at_${string}`>
+): void {
+  describe(`${name}: auth`, async () => {
+    let db: BackendDbInterface;
+    let close: () => void;
+    let email: string;
+    const password = "auth-test-password";
+
+    before(async () => {
+      ({ db, close } = await getDb());
+      email = `auth-user-${Date.now()}@test.example`;
+      const pw = await hashPassword(password);
+      await db.createUser({ email, name: "Auth User", password: pw, flags: {} });
+    });
+
+    after(() => close());
+
+    it("getUserByLogin returns user on correct credentials", async () => {
+      const user = await db.getUserByLogin({ email, password });
+      assert.equal(user.email, email);
+      assert.ok(!("password" in user));
+    });
+
+    it("getUserByLogin throws NotAuthorizedAbodeError for wrong password", async () => {
+      await assert.rejects(
+        () => db.getUserByLogin({ email, password: "wrong-password" }),
+        (err) => {
+          assert.ok(err instanceof NotAuthorizedAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("getUserByLogin throws NotFoundAbodeError for unknown email", async () => {
+      await assert.rejects(
+        () =>
+          db.getUserByLogin({
+            email: "nobody@nowhere.example",
+            password: "any",
+          }),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("getUserByLogin throws ConflictAbodeError for #unset password", async () => {
+      const unsetEmail = `unset-${Date.now()}@test.example`;
+      await db.createUser({
+        email: unsetEmail,
+        name: "Unset User",
+        password: "#unset",
+        flags: {},
+      });
+      await assert.rejects(
+        () => db.getUserByLogin({ email: unsetEmail, password: "any" }),
+        (err) => {
+          assert.ok(err instanceof ConflictAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+
+  describe(`${name}: auth apikey`, async () => {
+    let db: BackendDbInterface;
+    let close: () => void;
+    let uid: string;
+
+    before(async () => {
+      ({ db, close } = await getDb());
+      const pw = await hashPassword("apikey-auth-password");
+      const user = await db.createUser({
+        email: `apikey-auth-${Date.now()}@test.example`,
+        name: "Apikey Auth User",
+        password: pw,
+        flags: {},
+      });
+      uid = user.uid;
+    });
+
+    after(() => close());
+
+    it("getUserByApikey returns [user, apikey] for valid token", async () => {
+      const [, token] = await db.createApikey({
+        uid,
+        name: "Auth Key",
+        permissions: {},
+      });
+      const [user, apikey] = await db.getUserByApikey(token);
+      assert.equal(user.uid, uid);
+      assert.ok(apikey.kid);
+      assert.equal(apikey.uid, uid);
+    });
+
+    it("getUserByApikey throws NotAuthorizedAbodeError for expired key", async (t) => {
+      if (!createExpiredApikey) {
+        t.skip("createExpiredApikey helper not provided for this backend");
+        return;
+      }
+      const token = await createExpiredApikey(db, uid);
+      await assert.rejects(
+        () => db.getUserByApikey(token),
+        (err) => {
+          assert.ok(err instanceof NotAuthorizedAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("getUserByApikey throws NotFoundAbodeError for unknown token", async () => {
+      const fakeToken = `at_${"0".repeat(32)}` as `at_${string}`;
+      await assert.rejects(
+        () => db.getUserByApikey(fakeToken),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+}

test/shared/residents.ts

@@ -0,0 +1,154 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import type { DbInterface } from "../../src/db/types/DbInterface.js";
+import { NotFoundAbodeError, InvalidAbodeError } from "../../src/db/types/errors.js";
+import { hashPassword } from "../../src/util/hash.js";
+
+export function runResidentTests(
+  name: string,
+  getDb: () => Promise<{ db: DbInterface; close(): void }>
+): void {
+  describe(`${name}: residents`, async () => {
+    let db: DbInterface;
+    let close: () => void;
+    let uid: string;
+    let aid: string;
+    let ctxUid: string;
+
+    before(async () => {
+      ({ db, close } = await getDb());
+      const pw = await hashPassword("resident-pw");
+      // ctx user (creator of abode)
+      const ctx = await db.createUser({
+        email: `res-ctx-${Date.now()}@test.example`,
+        name: "Resident Ctx",
+        password: pw,
+        flags: {},
+      });
+      ctxUid = ctx.uid;
+      // the resident user
+      const resUser = await db.createUser({
+        email: `resident-${Date.now()}@test.example`,
+        name: "Resident User",
+        password: pw,
+        flags: {},
+      });
+      uid = resUser.uid;
+      const abode = await db.createAbode(
+        { name: `Resident Abode ${Date.now()}` },
+        { uid: ctxUid }
+      );
+      aid = abode.aid;
+      await db.createResident({ uid, aid, flags: {} }, { uid: ctxUid });
+    });
+
+    after(() => close());
+
+    it("getResidentById returns the created resident", async () => {
+      const found = await db.getResidentById(uid, aid);
+      assert.equal(found.uid, uid);
+      assert.equal(found.aid, aid);
+      assert.ok(found.created_at);
+    });
+
+    it("getResidentById throws NotFoundAbodeError for unknown pair", async () => {
+      await assert.rejects(
+        () =>
+          db.getResidentById(
+            "00000000-0000-0000-0000-000000000000",
+            "00000000-0000-0000-0000-000000000001"
+          ),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("listResidents includes the created resident", async () => {
+      const residents = await db.listResidents();
+      assert.ok(Array.isArray(residents));
+      const found = residents.find((r) => r.uid === uid && r.aid === aid);
+      assert.ok(found, "created resident appears in listResidents");
+    });
+
+    it("listResidentsByUserId filters by uid", async () => {
+      const results = await db.listResidentsByUserId(uid);
+      assert.ok(results.every((r) => r.uid === uid));
+      assert.ok(results.some((r) => r.aid === aid));
+    });
+
+    it("listResidentsByAbodeId filters by aid", async () => {
+      const results = await db.listResidentsByAbodeId(aid);
+      assert.ok(results.every((r) => r.aid === aid));
+      assert.ok(results.some((r) => r.uid === uid));
+    });
+
+    it("listUsersByAbodeId returns users in the abode", async () => {
+      const users = await db.listUsersByAbodeId(aid);
+      assert.ok(Array.isArray(users));
+      const found = users.find((u) => u.uid === uid);
+      assert.ok(found, "resident user appears in listUsersByAbodeId");
+    });
+
+    it("listAbodesByUserId returns abodes for user", async () => {
+      const abodes = await db.listAbodesByUserId(uid);
+      assert.ok(Array.isArray(abodes));
+      const found = abodes.find((a) => a.aid === aid);
+      assert.ok(found, "abode appears in listAbodesByUserId");
+    });
+
+    it("updateResident updates flags", async () => {
+      const updated = await db.updateResident(
+        { uid, aid, flags: { admin: true } },
+        { uid: ctxUid }
+      );
+      assert.equal(updated.uid, uid);
+      assert.deepEqual(updated.flags, { admin: true });
+    });
+
+    it("updateResident with no fields throws InvalidAbodeError", async () => {
+      await assert.rejects(
+        () => db.updateResident({ uid, aid }, { uid: ctxUid }),
+        (err) => {
+          assert.ok(err instanceof InvalidAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteResidentById removes the resident then throws on re-fetch", async () => {
+      const pw = await hashPassword("del-res-pw");
+      const user2 = await db.createUser({
+        email: `del-res-${Date.now()}@test.example`,
+        name: "Del Res User",
+        password: pw,
+        flags: {},
+      });
+      const abode2 = await db.createAbode({ name: "Del Abode" }, { uid: ctxUid });
+      await db.createResident({ uid: user2.uid, aid: abode2.aid, flags: {} }, { uid: ctxUid });
+      await db.deleteResidentById(user2.uid, abode2.aid);
+      await assert.rejects(
+        () => db.getResidentById(user2.uid, abode2.aid),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteResidentById throws NotFoundAbodeError for unknown pair", async () => {
+      await assert.rejects(
+        () =>
+          db.deleteResidentById(
+            "00000000-0000-0000-0000-000000000002",
+            "00000000-0000-0000-0000-000000000003"
+          ),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+}

test/shared/sessions.ts

@@ -0,0 +1,65 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import type { BackendDbInterface } from "../../src/db/types/DbInterface.js";
+import { NotFoundAbodeError } from "../../src/db/types/errors.js";
+import { hashPassword } from "../../src/util/hash.js";
+
+export function runSessionTests(
+  name: string,
+  getDb: () => Promise<{ db: BackendDbInterface; close(): void }>
+): void {
+  describe(`${name}: sessions`, async () => {
+    let db: BackendDbInterface;
+    let close: () => void;
+    let uid: string;
+
+    before(async () => {
+      ({ db, close } = await getDb());
+      const pw = await hashPassword("session-password");
+      const user = await db.createUser({
+        email: `session-user-${Date.now()}@test.example`,
+        name: "Session User",
+        password: pw,
+        flags: {},
+      });
+      uid = user.uid;
+    });
+
+    after(() => close());
+
+    it("createSession returns an as_ token", async () => {
+      const token = await db.createSession(uid);
+      assert.ok(token.startsWith("as_"), `token starts with as_: ${token}`);
+      assert.equal(token.length, 35, "as_ + 32 hex chars");
+    });
+
+    it("getUserBySession returns the correct user", async () => {
+      const token = await db.createSession(uid);
+      const user = await db.getUserBySession(token);
+      assert.equal(user.uid, uid);
+    });
+
+    it("getUserBySession throws NotFoundAbodeError for unknown token", async () => {
+      const fakeToken = `as_${"0".repeat(32)}` as `as_${string}`;
+      await assert.rejects(
+        () => db.getUserBySession(fakeToken),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteSessionsByUser invalidates all sessions for user", async () => {
+      const token = await db.createSession(uid);
+      await db.deleteSessionsByUser(uid);
+      await assert.rejects(
+        () => db.getUserBySession(token),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+}

test/shared/users.ts

@@ -0,0 +1,185 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import type { DbInterface } from "../../src/db/types/DbInterface.js";
+import {
+  NotFoundAbodeError,
+  InvalidAbodeError,
+  ReadonlyAbodeError,
+} from "../../src/db/types/errors.js";
+import { hashPassword } from "../../src/util/hash.js";
+
+export function runUserTests(
+  name: string,
+  getDb: () => Promise<{ db: DbInterface; close(): void }>,
+  getReadonlyDb?: () => Promise<{ db: DbInterface; close(): void }>
+): void {
+  describe(`${name}: users`, async () => {
+    let db: DbInterface;
+    let close: () => void;
+    let hashedPw: Awaited<ReturnType<typeof hashPassword>>;
+
+    before(async () => {
+      ({ db, close } = await getDb());
+      hashedPw = await hashPassword("test-password");
+    });
+
+    after(() => close());
+
+    it("createUser returns a ClientUser without password", async () => {
+      const user = await db.createUser({
+        email: `user-create-${Date.now()}@test.example`,
+        name: "Test User",
+        password: hashedPw,
+        flags: {},
+      });
+      assert.ok(user.uid, "has uid");
+      assert.equal(user.name, "Test User");
+      assert.ok(!("password" in user), "no password field");
+      assert.ok(user.created_at);
+      assert.ok(user.updated_at);
+    });
+
+    it("getUserById returns the created user", async () => {
+      const created = await db.createUser({
+        email: `user-byid-${Date.now()}@test.example`,
+        name: "ById User",
+        password: hashedPw,
+        flags: {},
+      });
+      const found = await db.getUserById(created.uid);
+      assert.equal(found.uid, created.uid);
+      assert.equal(found.name, "ById User");
+    });
+
+    it("getUserById throws NotFoundAbodeError for unknown uid", async () => {
+      await assert.rejects(
+        () => db.getUserById("00000000-0000-0000-0000-000000000000"),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("getUserByEmail returns the created user", async () => {
+      const email = `user-byemail-${Date.now()}@test.example`;
+      await db.createUser({ email, name: "ByEmail User", password: hashedPw, flags: {} });
+      const found = await db.getUserByEmail(email);
+      assert.ok("email" in found, "result includes email");
+      assert.equal(found.email, email);
+    });
+
+    it("getUserByEmail throws NotFoundAbodeError for unknown email", async () => {
+      await assert.rejects(
+        () => db.getUserByEmail("nobody@nowhere.example"),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("listUsers includes the created user", async () => {
+      const email = `user-list-${Date.now()}@test.example`;
+      const created = await db.createUser({
+        email,
+        name: "Listed User",
+        password: hashedPw,
+        flags: {},
+      });
+      const users = await db.listUsers();
+      assert.ok(Array.isArray(users));
+      const found = users.find((u) => u.uid === created.uid);
+      assert.ok(found, "created user appears in listUsers");
+    });
+
+    it("updateUser updates the name", async () => {
+      const created = await db.createUser({
+        email: `user-update-${Date.now()}@test.example`,
+        name: "Before Update",
+        password: hashedPw,
+        flags: {},
+      });
+      const updated = await db.updateUser({ uid: created.uid, name: "After Update" });
+      assert.equal(updated.uid, created.uid);
+      assert.equal(updated.name, "After Update");
+    });
+
+    it("updateUser with no fields throws InvalidAbodeError", async () => {
+      const created = await db.createUser({
+        email: `user-noupdate-${Date.now()}@test.example`,
+        name: "No Update",
+        password: hashedPw,
+        flags: {},
+      });
+      await assert.rejects(
+        () => db.updateUser({ uid: created.uid }),
+        (err) => {
+          assert.ok(err instanceof InvalidAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteUserById removes the user", async () => {
+      const created = await db.createUser({
+        email: `user-delete-${Date.now()}@test.example`,
+        name: "To Delete",
+        password: hashedPw,
+        flags: {},
+      });
+      await db.deleteUserById(created.uid);
+      await assert.rejects(
+        () => db.getUserById(created.uid),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+
+    it("deleteUserById throws NotFoundAbodeError for unknown uid", async () => {
+      await assert.rejects(
+        () => db.deleteUserById("00000000-0000-0000-0000-000000000000"),
+        (err) => {
+          assert.ok(err instanceof NotFoundAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+
+  describe(`${name}: users readonly`, async () => {
+    let db: DbInterface;
+    let close: () => void;
+    let hashedPw: Awaited<ReturnType<typeof hashPassword>>;
+
+    before(async () => {
+      if (getReadonlyDb) ({ db, close } = await getReadonlyDb());
+      hashedPw = await hashPassword("test-password");
+    });
+
+    after(() => close?.());
+
+    it("createUser on readonly db throws ReadonlyAbodeError", async (t) => {
+      if (!getReadonlyDb) {
+        t.skip("getReadonlyDb helper not provided for this backend");
+        return;
+      }
+      assert.ok(db.readonly, "test db is readonly");
+      await assert.rejects(
+        () =>
+          db.createUser({
+            email: "readonly@test.example",
+            name: "Readonly",
+            password: hashedPw,
+            flags: {},
+          }),
+        (err) => {
+          assert.ok(err instanceof ReadonlyAbodeError);
+          return true;
+        }
+      );
+    });
+  });
+}

test/tools/authenticate.test.ts

@@ -0,0 +1,274 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { authenticate } from "../../src/webapi/middleware/authenticate.js";
+import type { BackendDbInterface } from "../../src/db/types/DbInterface.js";
+import type { ClientUser } from "../../src/db/types/User.js";
+import type { ClientApikey } from "../../src/db/types/Apikey.js";
+import {
+  ConflictAbodeError,
+  NotAuthorizedAbodeError,
+  NotFoundAbodeError,
+} from "../../src/db/types/errors.js";
+
+const MOCK_USER: ClientUser = {
+  uid: "11111111-1111-1111-1111-111111111111",
+  email: "test@example.com",
+  name: "Test User",
+  flags: {},
+  created_at: "2024-01-01T00:00:00Z",
+  updated_at: "2024-01-01T00:00:00Z",
+};
+
+const MOCK_APIKEY: ClientApikey = {
+  kid: "22222222-2222-2222-2222-222222222222",
+  uid: MOCK_USER.uid,
+  name: "Test Key",
+  permissions: {},
+  created_at: "2024-01-01T00:00:00Z",
+  expires_at: null,
+};
+
+function makeMockDb(
+  overrides: Partial<BackendDbInterface> = {}
+): BackendDbInterface {
+  return {
+    readonly: false,
+    backend: true,
+    name: "mock",
+    close: async () => {},
+    listUsers: async () => [],
+    getUserById: async () => { throw new NotFoundAbodeError(); },
+    deleteUserById: async () => {},
+    createUser: async () => MOCK_USER,
+    updateUser: async () => MOCK_USER,
+    getUserByEmail: async () => { throw new NotFoundAbodeError(); },
+    listAbodes: async () => [],
+    getAbodeById: async () => { throw new NotFoundAbodeError(); },
+    deleteAbodeById: async () => {},
+    createAbode: async () => ({ aid: "a", name: "A", created_at: "", created_by: null, updated_at: "", updated_by: null }),
+    updateAbode: async () => ({ aid: "a", name: "A", created_at: "", created_by: null, updated_at: "", updated_by: null }),
+    listResidents: async () => [],
+    getResidentById: async () => { throw new NotFoundAbodeError(); },
+    deleteResidentById: async () => {},
+    createResident: async () => ({ uid: "", aid: "", flags: {}, created_at: "", created_by: null, updated_at: "", updated_by: null }),
+    updateResident: async () => ({ uid: "", aid: "", flags: {}, created_at: "", created_by: null, updated_at: "", updated_by: null }),
+    listResidentsByUserId: async () => [],
+    listResidentsByAbodeId: async () => [],
+    listUsersByAbodeId: async () => [],
+    listAbodesByUserId: async () => [],
+    listNotes: async () => [],
+    getNoteById: async () => { throw new NotFoundAbodeError(); },
+    deleteNoteById: async () => {},
+    createNote: async () => { throw new Error("unimplemented"); },
+    updateNote: async () => { throw new Error("unimplemented"); },
+    listNotesByAbodeId: async () => [],
+    listNotesByUserId: async () => [],
+    deleteSessionsByUser: async () => {},
+    listApikeysByUser: async () => [],
+    getApikeyById: async () => { throw new NotFoundAbodeError(); },
+    createApikey: async () => [MOCK_APIKEY, "at_" + "0".repeat(32) as `at_${string}`],
+    deleteApikeyById: async () => {},
+    getUserByLogin: async () => { throw new NotFoundAbodeError(); },
+    getUserBySession: async () => { throw new NotFoundAbodeError(); },
+    createSession: async () => `as_${"0".repeat(32)}`,
+    deleteSession: async () => {},
+    getUserByApikey: async () => { throw new NotFoundAbodeError(); },
+    ...overrides,
+  };
+}
+
+type MockCtx = {
+  headers: Record<string, string>;
+  cookieJar: Record<string, string>;
+  clearedCookies: Set<string>;
+  status: number;
+  body: unknown;
+  user?: ClientUser;
+  session?: unknown;
+  get(header: string): string;
+  cookies: {
+    get(name: string): string | undefined;
+    set(name: string, value: string, opts?: unknown): void;
+  };
+};
+
+function makeMockCtx(headerOverrides: Record<string, string> = {}, cookieOverrides: Record<string, string> = {}): MockCtx {
+  const clearedCookies = new Set<string>();
+  const ctx: MockCtx = {
+    headers: headerOverrides,
+    cookieJar: cookieOverrides,
+    clearedCookies,
+    status: 200,
+    body: null,
+    user: undefined,
+    session: undefined,
+    get(header: string) {
+      return this.headers[header] ?? this.headers[header.toLowerCase()] ?? "";
+    },
+    cookies: {
+      get(name: string) {
+        return cookieOverrides[name];
+      },
+      set(name: string, value: string, opts?: unknown) {
+        if (value === "" || (opts && (opts as { expires?: Date }).expires?.getFullYear()! < 2000)) {
+          clearedCookies.add(name);
+        }
+      },
+    },
+  };
+  return ctx;
+}
+
+async function runMiddleware(
+  db: BackendDbInterface,
+  ctx: MockCtx
+): Promise<boolean> {
+  let nextCalled = false;
+  const mw = authenticate(db);
+  await mw(ctx as any, async () => { nextCalled = true; });
+  return nextCalled;
+}
+
+describe("authenticate middleware", () => {
+  describe("Basic auth", () => {
+    it("valid credentials → sets user and session, calls next", async () => {
+      const db = makeMockDb({ getUserByLogin: async () => MOCK_USER });
+      const encoded = btoa("test@example.com:password");
+      const ctx = makeMockCtx({ Authorization: `Basic ${encoded}` });
+      const next = await runMiddleware(db, ctx);
+      assert.equal(next, true);
+      assert.deepEqual(ctx.user, MOCK_USER);
+      assert.deepEqual(ctx.session, { source: "basic" });
+    });
+
+    it("malformed base64 → 400", async () => {
+      const db = makeMockDb();
+      const ctx = makeMockCtx({ Authorization: "Basic !!not-base64!!" });
+      await runMiddleware(db, ctx);
+      assert.equal(ctx.status, 400);
+    });
+
+    it("missing colon in decoded value → 400", async () => {
+      const db = makeMockDb();
+      const ctx = makeMockCtx({ Authorization: "Basic " + btoa("nocolon") });
+      await runMiddleware(db, ctx);
+      assert.equal(ctx.status, 400);
+    });
+
+    it("wrong password (NotAuthorizedAbodeError) → 401 invalid_password", async () => {
+      const db = makeMockDb({
+        getUserByLogin: async () => { throw new NotAuthorizedAbodeError(); },
+      });
+      const ctx = makeMockCtx({ Authorization: "Basic " + btoa("user:wrong") });
+      await runMiddleware(db, ctx);
+      assert.equal(ctx.status, 401);
+      assert.deepEqual((ctx.body as any)?.error, "invalid_password");
+    });
+
+    it("unknown user (NotFoundAbodeError) → 401 unknown_user", async () => {
+      const db = makeMockDb({
+        getUserByLogin: async () => { throw new NotFoundAbodeError(); },
+      });
+      const ctx = makeMockCtx({ Authorization: "Basic " + btoa("nobody:pass") });
+      await runMiddleware(db, ctx);
+      assert.equal(ctx.status, 401);
+      assert.deepEqual((ctx.body as any)?.error, "unknown_user");
+    });
+
+    it("ConflictAbodeError (#unset password) → 401 user_not_loggable", async () => {
+      const db = makeMockDb({
+        getUserByLogin: async () => { throw new ConflictAbodeError(); },
+      });
+      const ctx = makeMockCtx({ Authorization: "Basic " + btoa("user:pass") });
+      await runMiddleware(db, ctx);
+      assert.equal(ctx.status, 401);
+      assert.deepEqual((ctx.body as any)?.error, "user_not_loggable");
+    });
+
+    it("uses X-Abode-Authorization header when Authorization is absent", async () => {
+      const db = makeMockDb({ getUserByLogin: async () => MOCK_USER });
+      const encoded = btoa("test@example.com:password");
+      const ctx = makeMockCtx({ "X-Abode-Authorization": `Basic ${encoded}` });
+      const next = await runMiddleware(db, ctx);
+      assert.equal(next, true);
+      assert.ok(ctx.user);
+    });
+  });
+
+  describe("Bearer (API key)", () => {
+    const validToken = `at_${"a".repeat(32)}` as `at_${string}`;
+
+    it("valid at_ token → sets user and apikey session, calls next", async () => {
+      const db = makeMockDb({
+        getUserByApikey: async () => [MOCK_USER, MOCK_APIKEY],
+      });
+      const ctx = makeMockCtx({ Authorization: `Bearer ${validToken}` });
+      const next = await runMiddleware(db, ctx);
+      assert.equal(next, true);
+      assert.deepEqual(ctx.user, MOCK_USER);
+      assert.deepEqual(ctx.session, { source: "apikey", key: MOCK_APIKEY });
+    });
+
+    it("invalid/expired at_ token → 401 invalid_apikey", async () => {
+      const db = makeMockDb({
+        getUserByApikey: async () => { throw new NotFoundAbodeError(); },
+      });
+      const ctx = makeMockCtx({ Authorization: `Bearer ${validToken}` });
+      await runMiddleware(db, ctx);
+      assert.equal(ctx.status, 401);
+      assert.deepEqual((ctx.body as any)?.error, "invalid_apikey");
+    });
+
+    it("bearer token without at_ prefix → 401 unrecognized_bearer", async () => {
+      const db = makeMockDb();
+      const ctx = makeMockCtx({ Authorization: "Bearer not-an-apikey-token" });
+      await runMiddleware(db, ctx);
+      assert.equal(ctx.status, 401);
+      assert.deepEqual((ctx.body as any)?.error, "unrecognized_bearer");
+    });
+  });
+
+  describe("session cookie", () => {
+    const validToken = `as_${"b".repeat(32)}`;
+
+    it("valid session cookie → sets user and session, calls next", async () => {
+      const db = makeMockDb({
+        getUserBySession: async () => MOCK_USER,
+      });
+      const ctx = makeMockCtx({}, { abode_session: validToken });
+      const next = await runMiddleware(db, ctx);
+      assert.equal(next, true);
+      assert.deepEqual(ctx.user, MOCK_USER);
+      assert.deepEqual(ctx.session, { source: "session" });
+    });
+
+    it("invalid session token format clears cookie and falls through to 401", async () => {
+      const db = makeMockDb();
+      const ctx = makeMockCtx({}, { abode_session: "not-a-session-token" });
+      await runMiddleware(db, ctx);
+      assert.ok(ctx.clearedCookies.has("abode_session"), "cookie should be cleared");
+      assert.equal(ctx.status, 401);
+    });
+
+    it("expired/unknown session token clears cookie and returns 401", async () => {
+      const db = makeMockDb({
+        getUserBySession: async () => { throw new NotFoundAbodeError(); },
+      });
+      const ctx = makeMockCtx({}, { abode_session: validToken });
+      await runMiddleware(db, ctx);
+      assert.ok(ctx.clearedCookies.has("abode_session"), "cookie should be cleared");
+      assert.equal(ctx.status, 401);
+    });
+  });
+
+  describe("no auth", () => {
+    it("no credentials → 401 not_authenticated", async () => {
+      const db = makeMockDb();
+      const ctx = makeMockCtx();
+      const next = await runMiddleware(db, ctx);
+      assert.equal(next, false);
+      assert.equal(ctx.status, 401);
+      assert.deepEqual((ctx.body as any)?.error, "not_authenticated");
+    });
+  });
+});

test/tools/convertError.test.ts

@@ -0,0 +1,74 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { convertError } from "../../src/webapi/middleware/convertError.js";
+import {
+  NotFoundAbodeError,
+  NotAuthorizedAbodeError,
+  ConflictAbodeError,
+  InvalidAbodeError,
+  ReadonlyAbodeError,
+} from "../../src/db/types/errors.js";
+
+function makeCtx() {
+  return { status: 200, body: null as unknown };
+}
+
+async function runWithError(err: unknown) {
+  const ctx = makeCtx();
+  await convertError(ctx as any, async () => {
+    throw err;
+  });
+  return ctx;
+}
+
+describe("convertError middleware", () => {
+  it("does not interfere when next succeeds", async () => {
+    const ctx = makeCtx();
+    let nextCalled = false;
+    await convertError(ctx as any, async () => { nextCalled = true; });
+    assert.equal(nextCalled, true);
+    assert.equal(ctx.status, 200);
+  });
+
+  it("NotFoundAbodeError → 404 not_found", async () => {
+    const ctx = await runWithError(new NotFoundAbodeError());
+    assert.equal(ctx.status, 404);
+    assert.deepEqual(ctx.body, { ok: false, error: "not_found" });
+  });
+
+  it("NotAuthorizedAbodeError → 401 not_authorized", async () => {
+    const ctx = await runWithError(new NotAuthorizedAbodeError());
+    assert.equal(ctx.status, 401);
+    assert.deepEqual(ctx.body, { ok: false, error: "not_authorized" });
+  });
+
+  it("ConflictAbodeError → 409 conflict", async () => {
+    const ctx = await runWithError(new ConflictAbodeError());
+    assert.equal(ctx.status, 409);
+    assert.deepEqual(ctx.body, { ok: false, error: "conflict" });
+  });
+
+  it("InvalidAbodeError → 400 invalid", async () => {
+    const ctx = await runWithError(new InvalidAbodeError());
+    assert.equal(ctx.status, 400);
+    assert.deepEqual(ctx.body, { ok: false, error: "invalid" });
+  });
+
+  it("ReadonlyAbodeError → 403 readonly", async () => {
+    const ctx = await runWithError(new ReadonlyAbodeError());
+    assert.equal(ctx.status, 403);
+    assert.deepEqual(ctx.body, { ok: false, error: "readonly" });
+  });
+
+  it("unknown Error → 500 unknown", async () => {
+    const ctx = await runWithError(new Error("something went wrong"));
+    assert.equal(ctx.status, 500);
+    assert.deepEqual(ctx.body, { ok: false, error: "unknown" });
+  });
+
+  it("non-Error thrown → 500 unknown", async () => {
+    const ctx = await runWithError("string error");
+    assert.equal(ctx.status, 500);
+    assert.deepEqual(ctx.body, { ok: false, error: "unknown" });
+  });
+});

test/tools/hash.test.ts

@@ -0,0 +1,39 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { hashPassword, validatePassword } from "../../src/util/hash.js";
+
+describe("hashPassword", () => {
+  it("returns a string in PHC/argon2 format", async () => {
+    const hash = await hashPassword("secret");
+    assert.ok(hash.startsWith("$argon2"), `expected argon2 hash, got: ${hash}`);
+    assert.ok(hash.includes("$"), "has delimiter");
+  });
+
+  it("two hashes of the same password differ (random salt)", async () => {
+    const [h1, h2] = await Promise.all([
+      hashPassword("same-password"),
+      hashPassword("same-password"),
+    ]);
+    assert.notEqual(h1, h2, "hashes should differ due to random salt");
+  });
+});
+
+describe("validatePassword", () => {
+  it("returns true for matching password and hash", async () => {
+    const hash = await hashPassword("correct-password");
+    const result = await validatePassword("correct-password", hash);
+    assert.equal(result, true);
+  });
+
+  it("returns false for wrong password", async () => {
+    const hash = await hashPassword("correct-password");
+    const result = await validatePassword("wrong-password", hash);
+    assert.equal(result, false);
+  });
+
+  it("returns false for a completely different password", async () => {
+    const hash = await hashPassword("original-password");
+    const result = await validatePassword("different-password", hash);
+    assert.equal(result, false);
+  });
+});

test/tools/jsonBody.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import Koa from "koa";
+import KoaRouter from "@koa/router";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { jsonBody } from "../../src/webapi/middleware/jsonBody.js";
+
+async function request(
+  url: string,
+  opts: { method?: string; body?: unknown; contentType?: string } = {}
+): Promise<{ status: number; body: unknown }> {
+  const method = opts.method ?? "POST";
+  const bodyStr =
+    opts.body !== undefined ? JSON.stringify(opts.body) : undefined;
+  const headers: Record<string, string> = {};
+  if (bodyStr !== undefined) {
+    headers["Content-Type"] = opts.contentType ?? "application/json";
+    headers["Content-Length"] = String(bodyStr.length);
+  }
+  const res = await fetch(url, { method, headers, body: bodyStr });
+  const text = await res.text();
+  let parsed: unknown;
+  try { parsed = JSON.parse(text); } catch { parsed = text; }
+  return { status: res.status, body: parsed };
+}
+
+async function makeTestServer() {
+  const failValidator = Object.assign(
+    (_obj: unknown): _obj is never => false,
+    {
+      errors: [{ message: "required" }] as unknown[],
+      schema: { $id: "test-schema", title: "Test", description: "" },
+    }
+  );
+
+  const app = new Koa();
+  const router = new KoaRouter();
+
+  router.post("/echo", jsonBody(), async (ctx) => {
+    ctx.status = 200;
+    ctx.body = { ok: true, received: ctx.request.body };
+  });
+
+  router.post(
+    "/fail-validate",
+    jsonBody({ validate: failValidator as any }),
+    async (ctx) => {
+      ctx.status = 200;
+      ctx.body = { ok: true };
+    }
+  );
+
+  router.post(
+    "/with-params/:uid",
+    jsonBody({ includeParams: ["uid"] }),
+    async (ctx) => {
+      ctx.status = 200;
+      ctx.body = { ok: true, body: ctx.request.body };
+    }
+  );
+
+  app.use(router.routes());
+  app.use(router.allowedMethods());
+
+  const server = createServer(app.callback());
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  const url = `http://127.0.0.1:${port}`;
+  const close = () =>
+    new Promise<void>((resolve, reject) =>
+      server.close((err) => (err ? reject(err) : resolve()))
+    );
+  return { url, close };
+}
+
+describe("jsonBody middleware", () => {
+  let url: string;
+  let closeServer: () => Promise<void>;
+
+  before(async () => {
+    ({ url, close: closeServer } = await makeTestServer());
+  });
+
+  after(() => closeServer());
+
+  it("no Content-Type → 200 with empty body (bodyparser sets body to {})", async () => {
+    const res = await fetch(url + "/echo", { method: "POST" });
+    const json = await res.json();
+    assert.equal(res.status, 200);
+    assert.deepEqual(json.received, {});
+  });
+
+  it("invalid JSON with Content-Type: application/json → 400 from bodyparser", async () => {
+    const res = await fetch(url + "/echo", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "not-valid-json",
+    });
+    assert.equal(res.status, 400);
+  });
+
+  it("valid JSON body → 200 with echoed body", async () => {
+    const res = await request(url + "/echo", { body: { hello: "world" } });
+    assert.equal(res.status, 200);
+    assert.deepEqual((res.body as any).received, { hello: "world" });
+  });
+
+  it("failing validator → 400 jsonchema_validation_failed with schema and errors", async () => {
+    const res = await request(url + "/fail-validate", { body: { any: "thing" } });
+    assert.equal(res.status, 400);
+    assert.equal((res.body as any).error, "jsonchema_validation_failed");
+    assert.ok((res.body as any).schema, "response includes schema");
+    assert.ok(Array.isArray((res.body as any).errors), "response includes errors");
+  });
+
+  it("includeParams: param absent from body → merged in", async () => {
+    const res = await request(url + "/with-params/user-42", {
+      body: { other: "field" },
+    });
+    assert.equal(res.status, 200);
+    assert.equal((res.body as any).body?.uid, "user-42");
+  });
+
+  it("includeParams: param present with matching value → ok", async () => {
+    const res = await request(url + "/with-params/user-42", {
+      body: { uid: "user-42" },
+    });
+    assert.equal(res.status, 200);
+  });
+
+  it("includeParams: mismatching param value → 400 mismatch_params", async () => {
+    const res = await request(url + "/with-params/user-42", {
+      body: { uid: "different-uid" },
+    });
+    assert.equal(res.status, 400);
+    assert.equal((res.body as any).error, "mismatch_params");
+    assert.equal((res.body as any).param, "uid");
+  });
+});

test/tools/token.test.ts

@@ -0,0 +1,86 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  createSessionToken,
+  createApikeyToken,
+  isSessionToken,
+  isApikeyToken,
+} from "../../src/util/token.js";
+
+describe("createSessionToken", () => {
+  it("starts with 'as_'", () => {
+    const token = createSessionToken();
+    assert.ok(token.startsWith("as_"), `expected as_ prefix, got: ${token}`);
+  });
+
+  it("has 35 chars total (as_ + 32 hex)", () => {
+    const token = createSessionToken();
+    assert.equal(token.length, 35);
+  });
+
+  it("suffix is all hex characters", () => {
+    const token = createSessionToken();
+    const hex = token.slice(3);
+    assert.ok(/^[0-9a-f]{32}$/.test(hex), `not all hex: ${hex}`);
+  });
+
+  it("produces different tokens on each call", () => {
+    const tokens = new Set(Array.from({ length: 10 }, createSessionToken));
+    assert.equal(tokens.size, 10, "all tokens should be unique");
+  });
+});
+
+describe("createApikeyToken", () => {
+  it("starts with 'at_'", () => {
+    const token = createApikeyToken();
+    assert.ok(token.startsWith("at_"), `expected at_ prefix, got: ${token}`);
+  });
+
+  it("has 35 chars total (at_ + 32 hex)", () => {
+    const token = createApikeyToken();
+    assert.equal(token.length, 35);
+  });
+
+  it("suffix is all hex characters", () => {
+    const token = createApikeyToken();
+    const hex = token.slice(3);
+    assert.ok(/^[0-9a-f]{32}$/.test(hex), `not all hex: ${hex}`);
+  });
+
+  it("produces different tokens on each call", () => {
+    const tokens = new Set(Array.from({ length: 10 }, createApikeyToken));
+    assert.equal(tokens.size, 10, "all tokens should be unique");
+  });
+});
+
+describe("isSessionToken", () => {
+  it("returns true for as_ prefixed strings", () => {
+    assert.equal(isSessionToken("as_" + "a".repeat(32)), true);
+  });
+
+  it("returns false for at_ prefixed strings", () => {
+    assert.equal(isSessionToken("at_abc"), false);
+  });
+
+  it("returns false for empty string", () => {
+    assert.equal(isSessionToken(""), false);
+  });
+
+  it("returns false for plain strings", () => {
+    assert.equal(isSessionToken("hello"), false);
+  });
+});
+
+describe("isApikeyToken", () => {
+  it("returns true for at_ prefixed strings", () => {
+    assert.equal(isApikeyToken("at_" + "b".repeat(32)), true);
+  });
+
+  it("returns false for as_ prefixed strings", () => {
+    assert.equal(isApikeyToken("as_abc"), false);
+  });
+
+  it("returns false for empty string", () => {
+    assert.equal(isApikeyToken(""), false);
+  });
+});

test/tools/validators.test.ts

@@ -0,0 +1,181 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  createuser,
+  updateuser,
+  clientuser,
+  loginuser,
+  createabode,
+  updateabode,
+  createresident,
+  createapikey,
+} from "../../src/schema/validators.js";
+
+describe("createuser validator", () => {
+  it("accepts a valid CreateUser object", () => {
+    const result = createuser({
+      email: "user@example.com",
+      name: "Alice",
+      password: "#unset",
+      flags: {},
+    });
+    assert.equal(result, true);
+  });
+
+  it("rejects missing name", () => {
+    const result = createuser({
+      email: "user@example.com",
+      password: "#unset",
+      flags: {},
+    });
+    assert.equal(result, false);
+    assert.ok(createuser.errors && createuser.errors.length > 0);
+  });
+
+  it("rejects missing email", () => {
+    const result = createuser({
+      name: "Alice",
+      password: "#unset",
+      flags: {},
+    });
+    assert.equal(result, false);
+  });
+
+  it("rejects missing password", () => {
+    const result = createuser({
+      email: "user@example.com",
+      name: "Alice",
+      flags: {},
+    });
+    assert.equal(result, false);
+  });
+});
+
+describe("updateuser validator", () => {
+  it("accepts update with just uid", () => {
+    const result = updateuser({ uid: "11111111-1111-1111-1111-111111111111" });
+    assert.equal(result, true);
+  });
+
+  it("accepts update with uid and name", () => {
+    const result = updateuser({
+      uid: "11111111-1111-1111-1111-111111111111",
+      name: "New Name",
+    });
+    assert.equal(result, true);
+  });
+
+  it("rejects missing uid", () => {
+    const result = updateuser({ name: "Alice" });
+    assert.equal(result, false);
+  });
+});
+
+describe("clientuser validator", () => {
+  it("accepts a valid ClientUser (no password)", () => {
+    const result = clientuser({
+      uid: "11111111-1111-1111-1111-111111111111",
+      email: "user@example.com",
+      name: "Alice",
+      flags: {},
+      created_at: "2024-01-01T00:00:00Z",
+      updated_at: "2024-01-01T00:00:00Z",
+    });
+    assert.equal(result, true);
+  });
+
+  it("rejects object with password field", () => {
+    const result = clientuser({
+      uid: "11111111-1111-1111-1111-111111111111",
+      email: "user@example.com",
+      name: "Alice",
+      password: "#unset",
+      flags: {},
+      created_at: "2024-01-01T00:00:00Z",
+      updated_at: "2024-01-01T00:00:00Z",
+    });
+    assert.equal(result, false);
+  });
+});
+
+describe("loginuser validator", () => {
+  it("accepts valid LoginUser", () => {
+    const result = loginuser({ email: "user@example.com", password: "secret" });
+    assert.equal(result, true);
+  });
+
+  it("rejects missing password", () => {
+    const result = loginuser({ email: "user@example.com" });
+    assert.equal(result, false);
+  });
+
+  it("rejects missing email", () => {
+    const result = loginuser({ password: "secret" });
+    assert.equal(result, false);
+  });
+});
+
+describe("createabode validator", () => {
+  it("accepts valid CreateAbode", () => {
+    const result = createabode({ name: "My Abode" });
+    assert.equal(result, true);
+  });
+
+  it("rejects missing name", () => {
+    const result = createabode({});
+    assert.equal(result, false);
+  });
+});
+
+describe("updateabode validator", () => {
+  it("accepts update with just aid", () => {
+    const result = updateabode({ aid: "22222222-2222-2222-2222-222222222222" });
+    assert.equal(result, true);
+  });
+
+  it("accepts update with aid and name", () => {
+    const result = updateabode({
+      aid: "22222222-2222-2222-2222-222222222222",
+      name: "New Name",
+    });
+    assert.equal(result, true);
+  });
+});
+
+describe("createresident validator", () => {
+  it("accepts valid CreateResident", () => {
+    const result = createresident({
+      uid: "11111111-1111-1111-1111-111111111111",
+      aid: "22222222-2222-2222-2222-222222222222",
+      flags: {},
+    });
+    assert.equal(result, true);
+  });
+
+  it("rejects missing uid", () => {
+    const result = createresident({
+      aid: "22222222-2222-2222-2222-222222222222",
+      flags: {},
+    });
+    assert.equal(result, false);
+  });
+});
+
+describe("createapikey validator", () => {
+  it("accepts valid CreateApikey", () => {
+    const result = createapikey({
+      uid: "11111111-1111-1111-1111-111111111111",
+      name: "My Key",
+      permissions: {},
+    });
+    assert.equal(result, true);
+  });
+
+  it("rejects missing name", () => {
+    const result = createapikey({
+      uid: "11111111-1111-1111-1111-111111111111",
+      permissions: {},
+    });
+    assert.equal(result, false);
+  });
+});

tsconfig.test.json

@@ -0,0 +1,7 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "rootDir": "."
+    },
+    "include": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
+}