@jskit-ai/auth-provider-local-db-core 0.1.1

package/package.descriptor.mjs

@@ -0,0 +1,109 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/auth-provider-local-db-core",
+  version: "0.1.1",
+  kind: "runtime",
+  description: "Database-backed local auth storage backend for JSKIT local auth.",
+  dependsOn: [
+    "@jskit-ai/auth-provider-local-core",
+    "@jskit-ai/database-runtime"
+  ],
+  capabilities: {
+    provides: [
+      "auth.local.backend.db"
+    ],
+    requires: [
+      "runtime.database"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/providers/AuthLocalDbBackendServiceProvider.js",
+          export: "AuthLocalDbBackendServiceProvider"
+        }
+      ]
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    jskit: {
+      tableOwnership: {
+        tables: [
+          {
+            tableName: "auth_local_users",
+            provenance: "auth-provider-local-db-core",
+            ownerKind: "package"
+          },
+          {
+            tableName: "auth_local_sessions",
+            provenance: "auth-provider-local-db-core",
+            ownerKind: "package"
+          },
+          {
+            tableName: "auth_local_recovery",
+            provenance: "auth-provider-local-db-core",
+            ownerKind: "package"
+          }
+        ]
+      }
+    },
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/providers/AuthLocalDbBackendServiceProvider",
+          summary: "Exports the service provider that registers auth.local.backend for AUTH_LOCAL_BACKEND=db."
+        },
+        {
+          subpath: "./server/lib/index",
+          summary: "Exports the DB local auth backend factory."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "auth.local.backend"
+        ],
+        client: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/auth-provider-local-core": "0.1.9",
+        "@jskit-ai/database-runtime": "0.1.109",
+        "@jskit-ai/kernel": "0.1.110"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [
+      {
+        op: "install-migration",
+        from: "templates/migrations/auth_local_db_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install DB-backed local auth credential, session, and recovery tables.",
+        category: "auth-local-db",
+        id: "auth-local-db-initial-schema"
+      }
+    ],
+    text: [
+      {
+        file: ".env",
+        op: "upsert-env",
+        key: "AUTH_LOCAL_BACKEND",
+        value: "db",
+        reason: "Use the database-backed local auth backend.",
+        category: "runtime-config",
+        id: "auth-local-backend-db"
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@jskit-ai/auth-provider-local-db-core",
+  "version": "0.1.1",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./server/providers/AuthLocalDbBackendServiceProvider": "./src/server/providers/AuthLocalDbBackendServiceProvider.js",
+    "./server/lib/index": "./src/server/lib/index.js"
+  },
+  "dependencies": {
+    "@jskit-ai/auth-provider-local-core": "0.1.9",
+    "@jskit-ai/database-runtime": "0.1.109",
+    "@jskit-ai/kernel": "0.1.110"
+  }
+}

package/src/server/lib/dbBackend.js

@@ -0,0 +1,284 @@
+import { isDuplicateEntryError } from "@jskit-ai/database-runtime/shared/duplicateEntry";
+
+const TABLES = Object.freeze({
+  users: "auth_local_users",
+  sessions: "auth_local_sessions",
+  recovery: "auth_local_recovery"
+});
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function toDate(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError("Invalid local auth DB timestamp.");
+  }
+  return date;
+}
+
+function requiredDateTime(value, fallback = nowIso()) {
+  return toDate(value || fallback);
+}
+
+function optionalDateTime(value) {
+  return value ? toDate(value) : null;
+}
+
+function readDateTime(value, fallback = "") {
+  if (!value) {
+    return fallback;
+  }
+  return toDate(value).toISOString();
+}
+
+function readPassword(row) {
+  return {
+    algorithm: String(row.password_algorithm || ""),
+    version: String(row.password_version || ""),
+    salt: String(row.password_salt || ""),
+    hash: String(row.password_hash || "")
+  };
+}
+
+function writePassword(password = {}) {
+  return {
+    password_algorithm: String(password.algorithm || ""),
+    password_version: String(password.version || ""),
+    password_salt: String(password.salt || ""),
+    password_hash: String(password.hash || "")
+  };
+}
+
+function mapUser(row) {
+  if (!row) {
+    return null;
+  }
+  return {
+    id: String(row.id || ""),
+    email: String(row.email || ""),
+    displayName: String(row.display_name || ""),
+    password: readPassword(row),
+    createdAt: readDateTime(row.created_at),
+    updatedAt: readDateTime(row.updated_at),
+    disabled: row.disabled === true || row.disabled === 1 || row.disabled === "1"
+  };
+}
+
+function mapSession(row) {
+  if (!row) {
+    return null;
+  }
+  return {
+    id: String(row.id || ""),
+    userId: String(row.user_id || ""),
+    tokenHash: String(row.token_hash || ""),
+    purpose: String(row.purpose || "normal"),
+    createdAt: readDateTime(row.created_at),
+    expiresAt: readDateTime(row.expires_at),
+    revokedAt: readDateTime(row.revoked_at)
+  };
+}
+
+function mapRecovery(row) {
+  if (!row) {
+    return null;
+  }
+  return {
+    id: String(row.id || ""),
+    userId: String(row.user_id || ""),
+    tokenHash: String(row.token_hash || ""),
+    createdAt: readDateTime(row.created_at),
+    expiresAt: readDateTime(row.expires_at),
+    usedAt: readDateTime(row.used_at)
+  };
+}
+
+function userInsert(input = {}) {
+  const createdAt = requiredDateTime(input.createdAt);
+  return {
+    id: String(input.id || ""),
+    email: String(input.email || ""),
+    display_name: String(input.displayName || ""),
+    ...writePassword(input.password),
+    disabled: input.disabled === true,
+    created_at: createdAt,
+    updated_at: requiredDateTime(input.updatedAt, createdAt)
+  };
+}
+
+function sessionInsert(input = {}) {
+  const createdAt = requiredDateTime(input.createdAt);
+  return {
+    id: String(input.id || ""),
+    user_id: String(input.userId || ""),
+    token_hash: String(input.tokenHash || ""),
+    purpose: String(input.purpose || "normal"),
+    expires_at: requiredDateTime(input.expiresAt),
+    revoked_at: optionalDateTime(input.revokedAt),
+    created_at: createdAt,
+    updated_at: requiredDateTime(input.updatedAt, createdAt)
+  };
+}
+
+function recoveryInsert(input = {}) {
+  const createdAt = requiredDateTime(input.createdAt);
+  return {
+    id: String(input.id || ""),
+    user_id: String(input.userId || ""),
+    token_hash: String(input.tokenHash || ""),
+    expires_at: requiredDateTime(input.expiresAt),
+    used_at: optionalDateTime(input.usedAt),
+    created_at: createdAt,
+    updated_at: requiredDateTime(input.updatedAt, createdAt)
+  };
+}
+
+function assertBackendDependencies({ knex, transactionManager } = {}) {
+  if (typeof knex !== "function") {
+    throw new Error("createLocalDbBackend requires jskit.database.knex.");
+  }
+  if (!transactionManager || typeof transactionManager.inTransaction !== "function") {
+    throw new Error("createLocalDbBackend requires jskit.database.transactionManager.");
+  }
+}
+
+function createLocalDbBackend({ knex, transactionManager } = {}) {
+  assertBackendDependencies({ knex, transactionManager });
+
+  function table(client, tableName) {
+    return client(tableName);
+  }
+
+  function createTx(client) {
+    return Object.freeze({
+      users: Object.freeze({
+        async create(input) {
+          const row = userInsert(input);
+          try {
+            await table(client, TABLES.users).insert(row);
+          } catch (error) {
+            if (isDuplicateEntryError(error, { client: knex })) {
+              throw new Error("Local auth user already exists.");
+            }
+            throw error;
+          }
+          return mapUser(row);
+        },
+        async findById(userId) {
+          return mapUser(await table(client, TABLES.users).where({ id: String(userId || "") }).first());
+        },
+        async findByEmail(email) {
+          return mapUser(await table(client, TABLES.users).where({ email: String(email || "") }).first());
+        },
+        async updatePassword(userId, passwordRecord) {
+          const updatedAt = requiredDateTime();
+          await table(client, TABLES.users)
+            .where({ id: String(userId || "") })
+            .update({
+              ...writePassword(passwordRecord),
+              updated_at: updatedAt
+            });
+          return mapUser(await table(client, TABLES.users).where({ id: String(userId || "") }).first());
+        },
+        async updateProfile(userId, updates = {}) {
+          const patch = {
+            updated_at: requiredDateTime()
+          };
+          if (typeof updates.displayName === "string") {
+            patch.display_name = updates.displayName;
+          }
+          await table(client, TABLES.users).where({ id: String(userId || "") }).update(patch);
+          return mapUser(await table(client, TABLES.users).where({ id: String(userId || "") }).first());
+        }
+      }),
+      sessions: Object.freeze({
+        async create(input) {
+          const row = sessionInsert(input);
+          await table(client, TABLES.sessions).insert(row);
+          return mapSession(row);
+        },
+        async findById(sessionId) {
+          return mapSession(await table(client, TABLES.sessions).where({ id: String(sessionId || "") }).first());
+        },
+        async findByTokenHash(tokenHash) {
+          return mapSession(await table(client, TABLES.sessions).where({ token_hash: String(tokenHash || "") }).first());
+        },
+        async revoke(sessionId) {
+          const existing = await table(client, TABLES.sessions).where({ id: String(sessionId || "") }).first();
+          if (!existing || existing.revoked_at) {
+            return mapSession(existing);
+          }
+          const updatedAt = requiredDateTime();
+          await table(client, TABLES.sessions)
+            .where({ id: String(sessionId || "") })
+            .update({
+              revoked_at: updatedAt,
+              updated_at: updatedAt
+            });
+          return mapSession(await table(client, TABLES.sessions).where({ id: String(sessionId || "") }).first());
+        },
+        async revokeForUser(userId, options = {}) {
+          const query = table(client, TABLES.sessions)
+            .where({ user_id: String(userId || "") })
+            .whereNull("revoked_at");
+          const exceptSessionId = String(options.exceptSessionId || "");
+          if (exceptSessionId) {
+            query.whereNot("id", exceptSessionId);
+          }
+          const updatedAt = requiredDateTime();
+          const count = await query.update({
+            revoked_at: updatedAt,
+            updated_at: updatedAt
+          });
+          return Number(count || 0);
+        }
+      }),
+      recovery: Object.freeze({
+        async create(input) {
+          const row = recoveryInsert(input);
+          await table(client, TABLES.recovery).insert(row);
+          return mapRecovery(row);
+        },
+        async findByTokenHash(tokenHash) {
+          return mapRecovery(await table(client, TABLES.recovery).where({ token_hash: String(tokenHash || "") }).first());
+        },
+        async consume(tokenId) {
+          const existing = await table(client, TABLES.recovery).where({ id: String(tokenId || "") }).first();
+          if (!existing || existing.used_at) {
+            return mapRecovery(existing);
+          }
+          const updatedAt = requiredDateTime();
+          await table(client, TABLES.recovery)
+            .where({ id: String(tokenId || "") })
+            .update({
+              used_at: updatedAt,
+              updated_at: updatedAt
+            });
+          return mapRecovery(await table(client, TABLES.recovery).where({ id: String(tokenId || "") }).first());
+        },
+        async consumeForUser(userId) {
+          const updatedAt = requiredDateTime();
+          const count = await table(client, TABLES.recovery)
+            .where({ user_id: String(userId || "") })
+            .whereNull("used_at")
+            .update({
+              used_at: updatedAt,
+              updated_at: updatedAt
+            });
+          return Number(count || 0);
+        }
+      })
+    });
+  }
+
+  return Object.freeze({
+    tables: TABLES,
+    async withTransaction(callback) {
+      return transactionManager.inTransaction(async (trx) => callback(createTx(trx)));
+    }
+  });
+}
+
+export { TABLES as LOCAL_AUTH_DB_TABLES, createLocalDbBackend };

package/src/server/lib/index.js

@@ -0,0 +1 @@
+export { createLocalDbBackend, LOCAL_AUTH_DB_TABLES } from "./dbBackend.js";

package/src/server/providers/AuthLocalDbBackendServiceProvider.js

@@ -0,0 +1,30 @@
+import { resolveLocalBackendMode } from "@jskit-ai/auth-provider-local-core/server/providers/AuthLocalServiceProvider";
+import { createLocalDbBackend } from "../lib/dbBackend.js";
+
+class AuthLocalDbBackendServiceProvider {
+  static id = "auth.provider.local.db";
+
+  static dependsOn = ["runtime.database"];
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function" || typeof app.has !== "function") {
+      throw new Error("AuthLocalDbBackendServiceProvider requires application singleton()/has().");
+    }
+
+    const backendMode = resolveLocalBackendMode(app);
+    if (backendMode !== "db") {
+      return;
+    }
+
+    if (app.has("auth.local.backend")) {
+      throw new Error('AUTH_LOCAL_BACKEND="db" requires auth-provider-local-db-core to own auth.local.backend.');
+    }
+
+    app.singleton("auth.local.backend", (scope) => createLocalDbBackend({
+      knex: scope.make("jskit.database.knex"),
+      transactionManager: scope.make("jskit.database.transactionManager")
+    }));
+  }
+}
+
+export { AuthLocalDbBackendServiceProvider };

package/templates/migrations/auth_local_db_initial.cjs

@@ -0,0 +1,60 @@
+const USERS_TABLE = "auth_local_users";
+const SESSIONS_TABLE = "auth_local_sessions";
+const RECOVERY_TABLE = "auth_local_recovery";
+
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable(USERS_TABLE))) {
+    await knex.schema.createTable(USERS_TABLE, (table) => {
+      table.string("id", 80).primary();
+      table.string("email", 320).notNullable();
+      table.string("display_name", 160).notNullable();
+      table.string("password_algorithm", 64).notNullable();
+      table.string("password_version", 32).notNullable();
+      table.string("password_salt", 256).notNullable();
+      table.string("password_hash", 512).notNullable();
+      table.boolean("disabled").notNullable().defaultTo(false);
+      table.timestamp("created_at").notNullable();
+      table.timestamp("updated_at").notNullable();
+      table.unique(["email"], "uq_auth_local_users_email");
+    });
+  }
+
+  if (!(await knex.schema.hasTable(SESSIONS_TABLE))) {
+    await knex.schema.createTable(SESSIONS_TABLE, (table) => {
+      table.string("id", 80).primary();
+      table.string("user_id", 80).notNullable();
+      table.string("token_hash", 128).notNullable();
+      table.string("purpose", 32).notNullable();
+      table.timestamp("expires_at").notNullable();
+      table.timestamp("revoked_at").nullable();
+      table.timestamp("created_at").notNullable();
+      table.timestamp("updated_at").notNullable();
+      table.unique(["token_hash"], "uq_auth_local_sessions_token_hash");
+      table.index(["user_id"], "idx_auth_local_sessions_user");
+      table.index(["expires_at"], "idx_auth_local_sessions_expires");
+      table.foreign(["user_id"], "fk_auth_local_sessions_user").references(["id"]).inTable(USERS_TABLE).onUpdate("RESTRICT").onDelete("CASCADE");
+    });
+  }
+
+  if (!(await knex.schema.hasTable(RECOVERY_TABLE))) {
+    await knex.schema.createTable(RECOVERY_TABLE, (table) => {
+      table.string("id", 80).primary();
+      table.string("user_id", 80).notNullable();
+      table.string("token_hash", 128).notNullable();
+      table.timestamp("expires_at").notNullable();
+      table.timestamp("used_at").nullable();
+      table.timestamp("created_at").notNullable();
+      table.timestamp("updated_at").notNullable();
+      table.unique(["token_hash"], "uq_auth_local_recovery_token_hash");
+      table.index(["user_id"], "idx_auth_local_recovery_user");
+      table.index(["expires_at"], "idx_auth_local_recovery_expires");
+      table.foreign(["user_id"], "fk_auth_local_recovery_user").references(["id"]).inTable(USERS_TABLE).onUpdate("RESTRICT").onDelete("CASCADE");
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(RECOVERY_TABLE);
+  await knex.schema.dropTableIfExists(SESSIONS_TABLE);
+  await knex.schema.dropTableIfExists(USERS_TABLE);
+};

package/test/providerRuntime.test.js

@@ -0,0 +1,505 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createApplication } from "@jskit-ai/kernel/_testable";
+import { DatabaseRuntimeServiceProvider } from "@jskit-ai/database-runtime/server/providers/DatabaseRuntimeServiceProvider";
+import { createLocalAuthService, hashPassword } from "@jskit-ai/auth-provider-local-core/server/lib/index";
+import { AuthLocalServiceProvider } from "@jskit-ai/auth-provider-local-core/server/providers/AuthLocalServiceProvider";
+import { createLocalDbBackend, LOCAL_AUTH_DB_TABLES } from "../src/server/lib/index.js";
+import { AuthLocalDbBackendServiceProvider } from "../src/server/providers/AuthLocalDbBackendServiceProvider.js";
+import descriptor from "../package.descriptor.mjs";
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function createDuplicateError() {
+  const error = new Error("duplicate key value violates unique constraint");
+  error.code = "23505";
+  return error;
+}
+
+function createMemoryKnex() {
+  const tables = new Map(Object.values(LOCAL_AUTH_DB_TABLES).map((tableName) => [tableName, []]));
+
+  function rowsFor(tableName) {
+    if (!tables.has(tableName)) {
+      tables.set(tableName, []);
+    }
+    return tables.get(tableName);
+  }
+
+  function assertUnique(tableName, row) {
+    const rows = rowsFor(tableName);
+    const duplicate = rows.some((existing) => {
+      if (existing.id === row.id) {
+        return true;
+      }
+      if (tableName === LOCAL_AUTH_DB_TABLES.users) {
+        return existing.email === row.email;
+      }
+      return existing.token_hash === row.token_hash;
+    });
+    if (duplicate) {
+      throw createDuplicateError();
+    }
+  }
+
+  class Query {
+    constructor(tableName) {
+      this.tableName = tableName;
+      this.filters = [];
+    }
+
+    where(criteria, value) {
+      if (criteria && typeof criteria === "object") {
+        for (const [key, expected] of Object.entries(criteria)) {
+          this.filters.push((row) => row[key] === expected);
+        }
+        return this;
+      }
+      const key = String(criteria || "");
+      this.filters.push((row) => row[key] === value);
+      return this;
+    }
+
+    whereNot(key, value) {
+      this.filters.push((row) => row[String(key || "")] !== value);
+      return this;
+    }
+
+    whereNull(key) {
+      this.filters.push((row) => row[String(key || "")] == null);
+      return this;
+    }
+
+    matches(row) {
+      return this.filters.every((filter) => filter(row));
+    }
+
+    async first() {
+      return clone(rowsFor(this.tableName).find((row) => this.matches(row)) || null);
+    }
+
+    async insert(row) {
+      assertUnique(this.tableName, row);
+      rowsFor(this.tableName).push(clone(row));
+      return [row.id];
+    }
+
+    async update(patch) {
+      let count = 0;
+      for (const row of rowsFor(this.tableName)) {
+        if (this.matches(row)) {
+          Object.assign(row, clone(patch));
+          count += 1;
+        }
+      }
+      return count;
+    }
+  }
+
+  function knex(tableName) {
+    return new Query(tableName);
+  }
+
+  knex.__tables = tables;
+  knex.transaction = async (callback) => callback(knex);
+
+  return knex;
+}
+
+function createReplyFixture() {
+  const cookies = {};
+  return {
+    cookies,
+    setCookie(name, value) {
+      cookies[name] = value;
+    },
+    clearCookie(name) {
+      delete cookies[name];
+    }
+  };
+}
+
+function createDbBackendFixture() {
+  const knex = createMemoryKnex();
+  const transactionManager = {
+    transactions: 0,
+    async inTransaction(work) {
+      this.transactions += 1;
+      return knex.transaction(work);
+    }
+  };
+  return {
+    knex,
+    transactionManager,
+    backend: createLocalDbBackend({
+      knex,
+      transactionManager
+    })
+  };
+}
+
+function createService(backend, options = {}) {
+  return createLocalAuthService({
+    backend,
+    config: {
+      nodeEnv: "test",
+      sessionSecret: "test-secret",
+      appPublicUrl: "http://localhost:5173",
+      smtpConfigured: false,
+      recoveryDevOutput: "response"
+    },
+    ...options
+  });
+}
+
+test("DB local auth backend implements the storage repository contract", async () => {
+  const { backend, transactionManager } = createDbBackendFixture();
+  const password = await hashPassword("stored password value");
+
+  await backend.withTransaction(async (tx) => {
+    const user = await tx.users.create({
+      id: "usr_db_contract",
+      email: "contract@example.com",
+      displayName: "Contract User",
+      password
+    });
+    assert.equal(user.email, "contract@example.com");
+    assert.deepEqual(user.password, password);
+
+    assert.equal((await tx.users.findByEmail("contract@example.com")).id, "usr_db_contract");
+    assert.equal((await tx.users.findById("usr_db_contract")).displayName, "Contract User");
+
+    const updated = await tx.users.updateProfile("usr_db_contract", {
+      displayName: "Renamed User"
+    });
+    assert.equal(updated.displayName, "Renamed User");
+
+    const nextPassword = await hashPassword("next password value");
+    assert.deepEqual((await tx.users.updatePassword("usr_db_contract", nextPassword)).password, nextPassword);
+
+    const session = await tx.sessions.create({
+      id: "ses_db_contract",
+      userId: "usr_db_contract",
+      tokenHash: "session-token-hash",
+      purpose: "normal",
+      expiresAt: new Date(Date.now() + 60_000).toISOString()
+    });
+    assert.equal(session.revokedAt, "");
+    assert.equal((await tx.sessions.findByTokenHash("session-token-hash")).id, "ses_db_contract");
+    assert.notEqual((await tx.sessions.revoke("ses_db_contract")).revokedAt, "");
+    assert.equal(await tx.sessions.revokeForUser("usr_db_contract"), 0);
+
+    const recovery = await tx.recovery.create({
+      id: "rec_db_contract",
+      userId: "usr_db_contract",
+      tokenHash: "recovery-token-hash",
+      expiresAt: new Date(Date.now() + 60_000).toISOString()
+    });
+    assert.equal(recovery.usedAt, "");
+    assert.equal((await tx.recovery.findByTokenHash("recovery-token-hash")).id, "rec_db_contract");
+    assert.notEqual((await tx.recovery.consume("rec_db_contract")).usedAt, "");
+    assert.equal(await tx.recovery.consumeForUser("usr_db_contract"), 0);
+  });
+
+  assert.equal(transactionManager.transactions, 1);
+});
+
+test("DB local auth backend rejects duplicate users by canonical email", async () => {
+  const { backend } = createDbBackendFixture();
+  const password = await hashPassword("stored password value");
+
+  await backend.withTransaction(async (tx) => {
+    await tx.users.create({
+      id: "usr_duplicate_1",
+      email: "duplicate@example.com",
+      displayName: "Duplicate One",
+      password
+    });
+    await assert.rejects(
+      () =>
+        tx.users.create({
+          id: "usr_duplicate_2",
+          email: "duplicate@example.com",
+          displayName: "Duplicate Two",
+          password
+        }),
+      /Local auth user already exists/
+    );
+  });
+});
+
+test("local auth service works end to end with DB backend", async () => {
+  const { backend } = createDbBackendFixture();
+  const authService = createService(backend);
+
+  const registered = await authService.register({
+    email: "DBUser@example.com",
+    password: "correct horse battery staple",
+    displayName: "DB User"
+  });
+  assert.equal(registered.actor.email, "dbuser@example.com");
+
+  const login = await authService.login({
+    email: "dbuser@example.com",
+    password: "correct horse battery staple"
+  });
+  const reply = createReplyFixture();
+  authService.writeSessionCookies(reply, login.session);
+  assert.equal((await authService.authenticateRequest({ cookies: reply.cookies })).authenticated, true);
+
+  const recoveryRequest = await authService.requestPasswordReset({
+    email: "dbuser@example.com"
+  });
+  const recoveryToken = new URL(recoveryRequest.recoveryUrl).searchParams.get("token");
+  const recovery = await authService.completePasswordRecovery({
+    code: recoveryToken,
+    type: "recovery"
+  });
+  const recoveryReply = createReplyFixture();
+  authService.writeSessionCookies(recoveryReply, recovery.session);
+  await authService.resetPassword(
+    {
+      cookies: recoveryReply.cookies
+    },
+    {
+      password: "updated password value"
+    }
+  );
+
+  await assert.rejects(
+    () =>
+      authService.login({
+        email: "dbuser@example.com",
+        password: "correct horse battery staple"
+      }),
+    /Invalid email or password/
+  );
+  assert.equal(
+    (await authService.login({
+      email: "dbuser@example.com",
+      password: "updated password value"
+    })).actor.email,
+    "dbuser@example.com"
+  );
+
+  const firstNormalLogin = await authService.login({
+    email: "dbuser@example.com",
+    password: "updated password value"
+  });
+  const firstReply = createReplyFixture();
+  authService.writeSessionCookies(firstReply, firstNormalLogin.session);
+  const secondNormalLogin = await authService.login({
+    email: "dbuser@example.com",
+    password: "updated password value"
+  });
+  const secondReply = createReplyFixture();
+  authService.writeSessionCookies(secondReply, secondNormalLogin.session);
+
+  const signOutResult = await authService.signOutOtherSessions({ cookies: secondReply.cookies });
+  assert.equal(signOutResult.revokedSessions >= 1, true);
+  assert.equal((await authService.authenticateRequest({ cookies: firstReply.cookies })).authenticated, false);
+
+  await authService.changePassword(
+    {
+      cookies: secondReply.cookies
+    },
+    {
+      currentPassword: "updated password value",
+      newPassword: "changed password value"
+    }
+  );
+  await assert.rejects(
+    () =>
+      authService.login({
+        email: "dbuser@example.com",
+        password: "updated password value"
+      }),
+    /Invalid email or password/
+  );
+  assert.equal(
+    (await authService.login({
+      email: "dbuser@example.com",
+      password: "changed password value"
+    })).actor.email,
+    "dbuser@example.com"
+  );
+});
+
+test("local auth DB backend works with custom password strategy", async () => {
+  const { backend } = createDbBackendFixture();
+  const authService = createService(backend, {
+    passwordStrategy: {
+      async hashPassword(password) {
+        return {
+          algorithm: "test-strategy",
+          version: "v1",
+          salt: "",
+          hash: `stored-${password}`
+        };
+      },
+      async verifyPassword(password, record) {
+        return record?.algorithm === "test-strategy" && record.hash === `stored-${password}`;
+      }
+    }
+  });
+
+  await authService.register({
+    email: "strategy-db@example.com",
+    password: "strategy password value",
+    displayName: "Strategy DB"
+  });
+  const login = await authService.login({
+    email: "strategy-db@example.com",
+    password: "strategy password value"
+  });
+  assert.equal(login.actor.email, "strategy-db@example.com");
+});
+
+test("local auth service rejects disabled DB-backed users", async () => {
+  const { backend } = createDbBackendFixture();
+  const password = await hashPassword("disabled password value");
+  await backend.withTransaction((tx) =>
+    tx.users.create({
+      id: "usr_disabled",
+      email: "disabled@example.com",
+      displayName: "Disabled",
+      password,
+      disabled: true
+    })
+  );
+  const authService = createService(backend);
+
+  await assert.rejects(
+    () =>
+      authService.login({
+        email: "disabled@example.com",
+        password: "disabled password value"
+      }),
+    /Invalid email or password/
+  );
+});
+
+test("local auth DB backend still supports lazy profile projection", async () => {
+  const { backend } = createDbBackendFixture();
+  let projectionCalls = 0;
+  const authService = createService(backend, {
+    profileProjector: {
+      async syncIdentityProfile(profile) {
+        projectionCalls += 1;
+        return {
+          ...profile,
+          id: "projected-db-user",
+          profileSource: "users"
+        };
+      }
+    }
+  });
+
+  const registered = await authService.register({
+    email: "projected-db@example.com",
+    password: "projected password value",
+    displayName: "Projected DB"
+  });
+
+  assert.equal(projectionCalls, 1);
+  assert.equal(registered.actor.appUserId, "projected-db-user");
+  assert.equal(registered.actor.profileSource, "users");
+});
+
+test("package descriptor installs portable local auth DB migrations", () => {
+  const files = descriptor.mutations.files.map((file) => file.from);
+  assert.deepEqual(files, ["templates/migrations/auth_local_db_initial.cjs"]);
+  assert.deepEqual(
+    descriptor.metadata.jskit.tableOwnership.tables.map((table) => table.tableName),
+    [
+      LOCAL_AUTH_DB_TABLES.users,
+      LOCAL_AUTH_DB_TABLES.sessions,
+      LOCAL_AUTH_DB_TABLES.recovery
+    ]
+  );
+});
+
+test("provider registration wires DB backend for AUTH_LOCAL_BACKEND=db", async () => {
+  const knex = createMemoryKnex();
+  const app = createApplication();
+  app.instance("jskit.env", {
+    AUTH_PROVIDER: "local",
+    AUTH_LOCAL_BACKEND: "db",
+    AUTH_LOCAL_SESSION_SECRET: "test-secret",
+    AUTH_LOCAL_RECOVERY_DEV_OUTPUT: "response",
+    APP_PUBLIC_URL: "http://localhost:5173",
+    NODE_ENV: "test"
+  });
+  app.instance("jskit.database.knex", knex);
+
+  await app.start({
+    providers: [
+      AuthLocalServiceProvider,
+      AuthLocalDbBackendServiceProvider,
+      DatabaseRuntimeServiceProvider
+    ]
+  });
+
+  assert.equal(app.has("auth.local.backend"), true);
+  const diagnostics = app.getDiagnostics();
+  assert.ok(diagnostics.registeredOrder.indexOf("auth.provider.local.db") > -1);
+
+  const authService = app.make("authService");
+  const registered = await authService.register({
+    email: "provider-db@example.com",
+    password: "provider password value",
+    displayName: "Provider DB"
+  });
+  assert.equal(registered.actor.email, "provider-db@example.com");
+});
+
+test("local auth DB mode fails clearly when no DB backend provider is installed", async () => {
+  const app = createApplication();
+  app.instance("jskit.env", {
+    AUTH_PROVIDER: "local",
+    AUTH_LOCAL_BACKEND: "db",
+    AUTH_LOCAL_SESSION_SECRET: "test-secret",
+    NODE_ENV: "test"
+  });
+
+  await assert.rejects(
+    () =>
+      app.start({
+        providers: [AuthLocalServiceProvider]
+      }),
+    (error) =>
+      /AUTH_LOCAL_BACKEND="db" requires a package or app provider that registers auth\.local\.backend/.test(
+        String(error.details?.cause?.message || error.message || "")
+      )
+  );
+});
+
+test("local auth DB provider rejects ambiguous backend ownership in DB mode", async () => {
+  const app = createApplication();
+  app.instance("jskit.env", {
+    AUTH_PROVIDER: "local",
+    AUTH_LOCAL_BACKEND: "db",
+    NODE_ENV: "test"
+  });
+  app.instance("auth.local.backend", {
+    async withTransaction() {}
+  });
+  app.instance("jskit.database.knex", createMemoryKnex());
+
+  await assert.rejects(
+    () =>
+      app.start({
+        providers: [
+          DatabaseRuntimeServiceProvider,
+          AuthLocalDbBackendServiceProvider
+        ]
+      }),
+    (error) =>
+      /auth-provider-local-db-core to own auth\.local\.backend/.test(
+        String(error.details?.cause?.message || error.message || "")
+      )
+  );
+});