@byline/db-mysql 4.8.0

package/dist/modules/admin/admin-users-repository.js

@@ -0,0 +1,303 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { ERR_ADMIN_USER_VERSION_CONFLICT, } from '@byline/admin/admin-users';
+import { and, asc, desc, eq, inArray, like, or, sql } from 'drizzle-orm';
+import { v7 as uuidv7 } from 'uuid';
+import { adminUsers } from '../../database/schema/auth.js';
+import { affectedRowCount } from '../storage/storage-utils.js';
+/**
+ * MySQL implementation of `AdminUsersRepository`. Ported from
+ * `packages/db-postgres/src/modules/admin/admin-users-repository.ts`.
+ *
+ * The DB column for the password hash is `password`; the public interface
+ * exposes it as `password_hash`. The mapping happens entirely inside this
+ * factory — callers speak the interface shape and never see the column
+ * name.
+ *
+ * Password hashing is *not* done here — the interface takes a pre-hashed
+ * PHC string. Callers (seed, admin-user commands) hash first via
+ * `hashPassword` from `@byline/admin/auth`.
+ *
+ * Divergences from the pg source (found live, not assumed):
+ *   - `ilike` → `like`. `byline_admin_users` (like every table in this
+ *     schema) uses the database's default `utf8mb4_0900_ai_ci` collation,
+ *     which is itself accent- *and* case-insensitive — confirmed against
+ *     the live container with a throwaway table (`'Alice@Example.com'`
+ *     matched `LIKE '%alice%'`). So a plain `like()` already reproduces
+ *     `ilike()`'s behaviour; MySQL has no `ILIKE` keyword to reach for.
+ *   - `count(*)::int` → `CAST(COUNT(*) AS SIGNED)`, with a `Number()`
+ *     normalisation at the result edge — mirrors the identical conversion
+ *     in `storage-queries.ts` (mysql2 can return `BIGINT` aggregates as
+ *     strings).
+ *   - `.returning()` (4 sites: `create`, `update`, `setPasswordHash`,
+ *     `delete`) → MySQL has no `RETURNING`. `create`'s id is app-generated
+ *     UUIDv7 and every other column is either caller-supplied or a literal
+ *     default, so the row is constructed in JS directly — the `created_at`/
+ *     `updated_at` pair is captured once as `now` and used for *both* the
+ *     `INSERT` values and the returned row, so there is no drift between
+ *     what is persisted and what is returned (the failure mode the Task 9
+ *     deferred-minor note warns about: two independent `new Date()` calls
+ *     that can disagree). `update` and `setPasswordHash` re-`SELECT` the
+ *     row after a successful guarded `UPDATE`, both statements sharing one
+ *     `db.transaction()`, rather than merging the patch onto a pre-read
+ *     snapshot — an earlier version of this file did the latter and was
+ *     correct on accept/reject (the vid-guarded `UPDATE`'s affected-row
+ *     count is still the sole accept/reject authority, exactly as pg's
+ *     guarded `UPDATE … RETURNING` is) but not on return-value freshness:
+ *     `recordLoginSuccess`/`recordLoginFailure` mutate `last_login`/
+ *     `last_login_ip`/`failed_login_attempts` *without* bumping `vid` (by
+ *     design, matching pg), so either racing against the pre-read left the
+ *     returned object reporting stale values for those columns.
+ *
+ *     A second version of this fix re-`SELECT`ed but as two separate
+ *     statements outside a transaction — better, but still left a window: a
+ *     `recordLoginSuccess`/`recordLoginFailure` committing *between* the
+ *     guarded `UPDATE` and the re-`SELECT` would leak into the returned
+ *     object. The transaction closes that too, and the mechanism is not a
+ *     REPEATABLE-READ-snapshot argument (a snapshot would just as easily
+ *     read the *pre*-mutation state) — it's that the guarded `UPDATE`
+ *     acquires an exclusive lock on this row that InnoDB holds until the
+ *     transaction commits, so `recordLoginSuccess`/`recordLoginFailure`
+ *     issued against the same row block until after the re-`SELECT` has run
+ *     and the transaction has committed. That is what makes "the re-`SELECT`
+ *     closes the freshness gap entirely" actually true, rather than true
+ *     modulo the specific window between the two statements. `delete` needs
+ *     no read at all — it returns `void`, so the affected-row count is the
+ *     entire contract.
+ */
+const PUBLIC_COLUMNS = {
+    id: adminUsers.id,
+    vid: adminUsers.vid,
+    given_name: adminUsers.given_name,
+    family_name: adminUsers.family_name,
+    username: adminUsers.username,
+    email: adminUsers.email,
+    remember_me: adminUsers.remember_me,
+    last_login: adminUsers.last_login,
+    last_login_ip: adminUsers.last_login_ip,
+    failed_login_attempts: adminUsers.failed_login_attempts,
+    is_super_admin: adminUsers.is_super_admin,
+    is_enabled: adminUsers.is_enabled,
+    is_email_verified: adminUsers.is_email_verified,
+    preferred_locale: adminUsers.preferred_locale,
+    created_at: adminUsers.created_at,
+    updated_at: adminUsers.updated_at,
+};
+const ORDER_COLUMN = {
+    given_name: adminUsers.given_name,
+    family_name: adminUsers.family_name,
+    email: adminUsers.email,
+    username: adminUsers.username,
+    created_at: adminUsers.created_at,
+    updated_at: adminUsers.updated_at,
+};
+export function createAdminUsersRepository(db) {
+    return {
+        async create(input) {
+            const id = uuidv7();
+            const now = new Date();
+            const row = {
+                id,
+                vid: 1,
+                given_name: input.given_name ?? null,
+                family_name: input.family_name ?? null,
+                username: input.username ?? null,
+                email: input.email.toLowerCase(),
+                remember_me: false,
+                last_login: null,
+                last_login_ip: null,
+                failed_login_attempts: 0,
+                is_super_admin: input.is_super_admin ?? false,
+                is_enabled: input.is_enabled ?? false,
+                is_email_verified: input.is_email_verified ?? false,
+                preferred_locale: input.preferred_locale ?? null,
+                created_at: now,
+                updated_at: now,
+            };
+            await db.insert(adminUsers).values({
+                id: row.id,
+                email: row.email,
+                password: input.password_hash,
+                given_name: row.given_name,
+                family_name: row.family_name,
+                username: row.username,
+                is_super_admin: row.is_super_admin,
+                is_enabled: row.is_enabled,
+                is_email_verified: row.is_email_verified,
+                preferred_locale: row.preferred_locale,
+                created_at: now,
+                updated_at: now,
+            });
+            return row;
+        },
+        async getById(id) {
+            const [row] = await db.select(PUBLIC_COLUMNS).from(adminUsers).where(eq(adminUsers.id, id));
+            return row ?? null;
+        },
+        async getByIds(ids) {
+            if (ids.length === 0)
+                return [];
+            return db.select(PUBLIC_COLUMNS).from(adminUsers).where(inArray(adminUsers.id, ids));
+        },
+        async getByEmail(email) {
+            const [row] = await db
+                .select(PUBLIC_COLUMNS)
+                .from(adminUsers)
+                .where(eq(adminUsers.email, email.toLowerCase()));
+            return row ?? null;
+        },
+        async getByUsername(username) {
+            const [row] = await db
+                .select(PUBLIC_COLUMNS)
+                .from(adminUsers)
+                .where(eq(adminUsers.username, username));
+            return row ?? null;
+        },
+        async getByEmailForSignIn(email) {
+            const [row] = await db
+                .select({ ...PUBLIC_COLUMNS, password_hash: adminUsers.password })
+                .from(adminUsers)
+                .where(eq(adminUsers.email, email.toLowerCase()));
+            return row ?? null;
+        },
+        async getByIdForSignIn(id) {
+            const [row] = await db
+                .select({ ...PUBLIC_COLUMNS, password_hash: adminUsers.password })
+                .from(adminUsers)
+                .where(eq(adminUsers.id, id));
+            return row ?? null;
+        },
+        async list(options) {
+            const needle = options.query?.trim();
+            const filter = needle && needle.length > 0
+                ? or(like(adminUsers.email, `%${needle}%`), like(adminUsers.given_name, `%${needle}%`), like(adminUsers.family_name, `%${needle}%`), like(adminUsers.username, `%${needle}%`))
+                : undefined;
+            const sortCol = ORDER_COLUMN[options.order];
+            const orderExpr = options.desc ? desc(sortCol) : asc(sortCol);
+            const offset = Math.max(0, (options.page - 1) * options.pageSize);
+            const query = db.select(PUBLIC_COLUMNS).from(adminUsers);
+            const filtered = filter ? query.where(filter) : query;
+            return filtered.orderBy(orderExpr).limit(options.pageSize).offset(offset);
+        },
+        async count(options) {
+            const needle = options?.query?.trim();
+            const filter = needle && needle.length > 0
+                ? or(like(adminUsers.email, `%${needle}%`), like(adminUsers.given_name, `%${needle}%`), like(adminUsers.family_name, `%${needle}%`), like(adminUsers.username, `%${needle}%`))
+                : undefined;
+            const base = db.select({ value: sql `CAST(COUNT(*) AS SIGNED)` }).from(adminUsers);
+            const [row] = await (filter ? base.where(filter) : base);
+            return Number(row?.value ?? 0);
+        },
+        async update(id, expectedVid, patch) {
+            const now = new Date();
+            const updateSet = {
+                updated_at: now,
+                vid: sql `${adminUsers.vid} + 1`,
+            };
+            if (patch.given_name !== undefined)
+                updateSet.given_name = patch.given_name;
+            if (patch.family_name !== undefined)
+                updateSet.family_name = patch.family_name;
+            if (patch.username !== undefined)
+                updateSet.username = patch.username;
+            if (patch.email !== undefined)
+                updateSet.email = patch.email.toLowerCase();
+            if (patch.is_super_admin !== undefined)
+                updateSet.is_super_admin = patch.is_super_admin;
+            if (patch.is_enabled !== undefined)
+                updateSet.is_enabled = patch.is_enabled;
+            if (patch.is_email_verified !== undefined)
+                updateSet.is_email_verified = patch.is_email_verified;
+            if (patch.remember_me !== undefined)
+                updateSet.remember_me = patch.remember_me;
+            if (patch.preferred_locale !== undefined)
+                updateSet.preferred_locale = patch.preferred_locale;
+            // Guarded `UPDATE` + re-`SELECT` share one transaction — see this
+            // file's docblock for why the transaction boundary (not just the
+            // re-`SELECT`) is what actually closes the freshness gap.
+            return db.transaction(async (tx) => {
+                const result = await tx
+                    .update(adminUsers)
+                    .set(updateSet)
+                    .where(and(eq(adminUsers.id, id), eq(adminUsers.vid, expectedVid)));
+                if (affectedRowCount(result) === 0)
+                    throw ERR_ADMIN_USER_VERSION_CONFLICT();
+                const [fresh] = await tx
+                    .select(PUBLIC_COLUMNS)
+                    .from(adminUsers)
+                    .where(eq(adminUsers.id, id));
+                if (!fresh)
+                    throw ERR_ADMIN_USER_VERSION_CONFLICT();
+                return fresh;
+            });
+        },
+        async setPasswordHash(id, expectedVid, passwordHash) {
+            const now = new Date();
+            // Guarded `UPDATE` + re-`SELECT` share one transaction — see `update()`
+            // above and this file's docblock.
+            return db.transaction(async (tx) => {
+                const result = await tx
+                    .update(adminUsers)
+                    .set({
+                    password: passwordHash,
+                    updated_at: now,
+                    vid: sql `${adminUsers.vid} + 1`,
+                })
+                    .where(and(eq(adminUsers.id, id), eq(adminUsers.vid, expectedVid)));
+                if (affectedRowCount(result) === 0)
+                    throw ERR_ADMIN_USER_VERSION_CONFLICT();
+                const [fresh] = await tx
+                    .select(PUBLIC_COLUMNS)
+                    .from(adminUsers)
+                    .where(eq(adminUsers.id, id));
+                if (!fresh)
+                    throw ERR_ADMIN_USER_VERSION_CONFLICT();
+                return fresh;
+            });
+        },
+        async setEnabled(id, enabled) {
+            await db
+                .update(adminUsers)
+                .set({ is_enabled: enabled, updated_at: new Date(), vid: sql `${adminUsers.vid} + 1` })
+                .where(eq(adminUsers.id, id));
+        },
+        async setPreferredLocale(id, locale) {
+            await db
+                .update(adminUsers)
+                .set({ preferred_locale: locale, updated_at: new Date(), vid: sql `${adminUsers.vid} + 1` })
+                .where(eq(adminUsers.id, id));
+        },
+        async recordLoginSuccess(id, ip) {
+            await db
+                .update(adminUsers)
+                .set({
+                last_login: new Date(),
+                last_login_ip: ip,
+                failed_login_attempts: 0,
+                updated_at: new Date(),
+            })
+                .where(eq(adminUsers.id, id));
+        },
+        async recordLoginFailure(id) {
+            await db
+                .update(adminUsers)
+                .set({
+                failed_login_attempts: sql `${adminUsers.failed_login_attempts} + 1`,
+                updated_at: new Date(),
+            })
+                .where(eq(adminUsers.id, id));
+        },
+        async delete(id, expectedVid) {
+            const result = await db
+                .delete(adminUsers)
+                .where(and(eq(adminUsers.id, id), eq(adminUsers.vid, expectedVid)));
+            if (affectedRowCount(result) === 0)
+                throw ERR_ADMIN_USER_VERSION_CONFLICT();
+        },
+    };
+}

package/dist/modules/admin/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * `@byline/db-mysql/admin` — MySQL implementations of the admin repository
+ * contracts declared in `@byline/admin`.
+ *
+ * Most callers want `createAdminStore(db)` — it bundles all five
+ * repositories into the `AdminStore` shape that `@byline/admin` consumers
+ * (the built-in `JwtSessionProvider`, `seedSuperAdmin`, admin-user and
+ * admin-role commands) expect. Individual factories remain exported for
+ * unusual cases (custom wiring, partial testing).
+ *
+ * No session-provider code lives here — `JwtSessionProvider` lives in
+ * `@byline/admin/auth`. This package only supplies the adapter-shaped
+ * pieces it implements. Mirrors `packages/db-postgres/src/modules/admin/index.ts`.
+ */
+export { createAdminPermissionsRepository } from './admin-permissions-repository.js';
+export { createAdminPreferencesRepository } from './admin-preferences-repository.js';
+export { createAdminRolesRepository } from './admin-roles-repository.js';
+export { createAdminStore } from './admin-store.js';
+export { createAdminUsersRepository } from './admin-users-repository.js';
+export { createRefreshTokensRepository } from './refresh-tokens-repository.js';

package/dist/modules/admin/index.js

@@ -0,0 +1,27 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * `@byline/db-mysql/admin` — MySQL implementations of the admin repository
+ * contracts declared in `@byline/admin`.
+ *
+ * Most callers want `createAdminStore(db)` — it bundles all five
+ * repositories into the `AdminStore` shape that `@byline/admin` consumers
+ * (the built-in `JwtSessionProvider`, `seedSuperAdmin`, admin-user and
+ * admin-role commands) expect. Individual factories remain exported for
+ * unusual cases (custom wiring, partial testing).
+ *
+ * No session-provider code lives here — `JwtSessionProvider` lives in
+ * `@byline/admin/auth`. This package only supplies the adapter-shaped
+ * pieces it implements. Mirrors `packages/db-postgres/src/modules/admin/index.ts`.
+ */
+export { createAdminPermissionsRepository } from './admin-permissions-repository.js';
+export { createAdminPreferencesRepository } from './admin-preferences-repository.js';
+export { createAdminRolesRepository } from './admin-roles-repository.js';
+export { createAdminStore } from './admin-store.js';
+export { createAdminUsersRepository } from './admin-users-repository.js';
+export { createRefreshTokensRepository } from './refresh-tokens-repository.js';

package/dist/modules/admin/refresh-tokens-repository.d.ts

@@ -0,0 +1,34 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { RefreshTokensRepository } from '@byline/admin/auth';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+/**
+ * MySQL implementation of `RefreshTokensRepository`, backing the built-in
+ * `JwtSessionProvider`. Ported from
+ * `packages/db-postgres/src/modules/admin/refresh-tokens-repository.ts`.
+ *
+ * `issue()`'s `.returning()` has no MySQL equivalent. Every field
+ * `RefreshTokenRow` exposes is either caller-supplied (`id`, `admin_user_id`,
+ * `token_hash`, `expires_at`, `user_agent`, `ip`) or a fresh row's literal
+ * default (`revoked_at`/`rotated_to_id`/`last_used_at` all `null`) — except
+ * `issued_at`, which the schema defaults to `CURRENT_TIMESTAMP(6)`. Rather
+ * than let the insert rely on that default and approximate the returned
+ * value with a second, independent `new Date()` call (the drift the Task 9
+ * deferred-minor note flags), `issued_at` — and the underlying table's
+ * `created_at`/`updated_at`, which `RefreshTokenRow` doesn't expose but
+ * which exist on the row — are set explicitly from one `now` captured
+ * before the insert and reused for the returned row, so there is no gap
+ * between what is persisted and what is returned. No re-`SELECT` needed.
+ *
+ * `revokeAllForUser` and `purgeExpired` only ever consumed
+ * `.returning({ id })` for its `.length` (the affected-row count); MySQL's
+ * driver result surfaces that directly via `affectedRows` — no row
+ * reconstruction needed at all.
+ */
+export declare function createRefreshTokensRepository(db: MySql2Database<typeof schema>): RefreshTokensRepository;

package/dist/modules/admin/refresh-tokens-repository.js

@@ -0,0 +1,160 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { and, eq, isNull, lt } from 'drizzle-orm';
+import { adminRefreshTokens } from '../../database/schema/auth.js';
+import { affectedRowCount } from '../storage/storage-utils.js';
+/**
+ * MySQL implementation of `RefreshTokensRepository`, backing the built-in
+ * `JwtSessionProvider`. Ported from
+ * `packages/db-postgres/src/modules/admin/refresh-tokens-repository.ts`.
+ *
+ * `issue()`'s `.returning()` has no MySQL equivalent. Every field
+ * `RefreshTokenRow` exposes is either caller-supplied (`id`, `admin_user_id`,
+ * `token_hash`, `expires_at`, `user_agent`, `ip`) or a fresh row's literal
+ * default (`revoked_at`/`rotated_to_id`/`last_used_at` all `null`) — except
+ * `issued_at`, which the schema defaults to `CURRENT_TIMESTAMP(6)`. Rather
+ * than let the insert rely on that default and approximate the returned
+ * value with a second, independent `new Date()` call (the drift the Task 9
+ * deferred-minor note flags), `issued_at` — and the underlying table's
+ * `created_at`/`updated_at`, which `RefreshTokenRow` doesn't expose but
+ * which exist on the row — are set explicitly from one `now` captured
+ * before the insert and reused for the returned row, so there is no gap
+ * between what is persisted and what is returned. No re-`SELECT` needed.
+ *
+ * `revokeAllForUser` and `purgeExpired` only ever consumed
+ * `.returning({ id })` for its `.length` (the affected-row count); MySQL's
+ * driver result surfaces that directly via `affectedRows` — no row
+ * reconstruction needed at all.
+ */
+export function createRefreshTokensRepository(db) {
+    return {
+        async issue(input) {
+            const now = new Date();
+            const row = {
+                id: input.id,
+                admin_user_id: input.admin_user_id,
+                token_hash: input.token_hash,
+                issued_at: now,
+                expires_at: input.expires_at,
+                revoked_at: null,
+                rotated_to_id: null,
+                last_used_at: null,
+                user_agent: input.user_agent ?? null,
+                ip: input.ip ?? null,
+            };
+            await db.insert(adminRefreshTokens).values({
+                id: row.id,
+                admin_user_id: row.admin_user_id,
+                token_hash: row.token_hash,
+                issued_at: now,
+                expires_at: row.expires_at,
+                user_agent: row.user_agent,
+                ip: row.ip,
+                created_at: now,
+                updated_at: now,
+            });
+            return row;
+        },
+        async findByHash(tokenHash) {
+            const [row] = await db
+                .select()
+                .from(adminRefreshTokens)
+                .where(eq(adminRefreshTokens.token_hash, tokenHash));
+            return row ?? null;
+        },
+        async findById(id) {
+            const [row] = await db.select().from(adminRefreshTokens).where(eq(adminRefreshTokens.id, id));
+            return row ?? null;
+        },
+        async touch(id, at = new Date()) {
+            await db
+                .update(adminRefreshTokens)
+                .set({ last_used_at: at, updated_at: new Date() })
+                .where(eq(adminRefreshTokens.id, id));
+        },
+        async markRotated(oldId, newId, at = new Date()) {
+            await db
+                .update(adminRefreshTokens)
+                .set({ revoked_at: at, rotated_to_id: newId, updated_at: new Date() })
+                .where(eq(adminRefreshTokens.id, oldId));
+        },
+        async revoke(id, at = new Date()) {
+            await db
+                .update(adminRefreshTokens)
+                .set({ revoked_at: at, updated_at: new Date() })
+                .where(and(eq(adminRefreshTokens.id, id), isNull(adminRefreshTokens.revoked_at)));
+        },
+        async revokeChain(startId, at = new Date()) {
+            let cursor = startId;
+            let touched = 0;
+            // Bounded walk — chains in practice are short; 1000 is a safety ceiling.
+            for (let step = 0; cursor != null && step < 1000; step++) {
+                const [row] = await db
+                    .select({
+                    id: adminRefreshTokens.id,
+                    rotated_to_id: adminRefreshTokens.rotated_to_id,
+                    revoked_at: adminRefreshTokens.revoked_at,
+                })
+                    .from(adminRefreshTokens)
+                    .where(eq(adminRefreshTokens.id, cursor));
+                if (!row)
+                    break;
+                if (row.revoked_at == null) {
+                    await db
+                        .update(adminRefreshTokens)
+                        .set({ revoked_at: at, updated_at: new Date() })
+                        .where(eq(adminRefreshTokens.id, row.id));
+                    touched++;
+                }
+                cursor = row.rotated_to_id;
+            }
+            return touched;
+        },
+        async revokeAllForUser(adminUserId, at = new Date()) {
+            const result = await db
+                .update(adminRefreshTokens)
+                .set({ revoked_at: at, updated_at: new Date() })
+                .where(and(eq(adminRefreshTokens.admin_user_id, adminUserId), isNull(adminRefreshTokens.revoked_at)));
+            return affectedRowCount(result);
+        },
+        async purgeExpired(now = new Date()) {
+            const result = await db
+                .delete(adminRefreshTokens)
+                .where(lt(adminRefreshTokens.expires_at, now));
+            return affectedRowCount(result);
+        },
+        async listActiveForUser(adminUserId) {
+            return db
+                .select()
+                .from(adminRefreshTokens)
+                .where(and(eq(adminRefreshTokens.admin_user_id, adminUserId), isNull(adminRefreshTokens.revoked_at)));
+        },
+        async listAllForUser(adminUserId) {
+            return db
+                .select()
+                .from(adminRefreshTokens)
+                .where(eq(adminRefreshTokens.admin_user_id, adminUserId))
+                .orderBy(adminRefreshTokens.issued_at);
+        },
+        async listRotationChain(startId) {
+            const chain = [];
+            let cursor = startId;
+            for (let step = 0; cursor != null && step < 1000; step++) {
+                const [row] = await db
+                    .select()
+                    .from(adminRefreshTokens)
+                    .where(eq(adminRefreshTokens.id, cursor));
+                if (!row)
+                    break;
+                chain.push(row);
+                cursor = row.rotated_to_id;
+            }
+            return chain;
+        },
+    };
+}

package/dist/modules/audit/audit-commands.d.ts

@@ -0,0 +1,29 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Append-only audit-log writes (docs/06-auth-and-security/02-auditability.md — Workstream 2). A deliberately
+ * dumb command: it inserts one row and knows nothing about *which* changes
+ * warrant an audit entry — that policy lives in the lifecycle services, which
+ * wrap the mutation + this append in `withTransaction` so they commit
+ * atomically. Runs on the `DBManager` executor, so an `append` issued inside a
+ * `withTransaction` boundary joins the ambient transaction. Mirrors
+ * `packages/db-postgres/src/modules/audit/audit-commands.ts` exactly — the
+ * transaction-join split is the load-bearing property, not the dialect.
+ */
+import type { AuditLogAppendInput, IAuditCommands } from '@byline/core';
+import type { DBManager } from '../../lib/db-manager.js';
+export declare class AuditCommands implements IAuditCommands {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    /** Ambient transaction when a `withTransaction` boundary is open, else the pool. */
+    private get db();
+    append(input: AuditLogAppendInput): Promise<{
+        id: string;
+    }>;
+}
+export declare function createAuditCommands(dbManager: DBManager): AuditCommands;

package/dist/modules/audit/audit-commands.js

@@ -0,0 +1,40 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { v7 as uuidv7 } from 'uuid';
+import { auditLog } from '../../database/schema/index.js';
+export class AuditCommands {
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    /** Ambient transaction when a `withTransaction` boundary is open, else the pool. */
+    get db() {
+        return this.dbManager.get();
+    }
+    async append(input) {
+        const id = uuidv7(); // time-ordered, so id ordering ≈ occurred_at ordering
+        await this.db.insert(auditLog).values({
+            id,
+            document_id: input.documentId ?? null,
+            collection_id: input.collectionId ?? null,
+            actor_id: input.actorId ?? null,
+            actor_realm: input.actorRealm,
+            action: input.action,
+            field: input.field ?? null,
+            // `?? null` only coerces undefined → SQL NULL; a real `false`/`0`/`''`
+            // before/after value is preserved.
+            before: input.before ?? null,
+            after: input.after ?? null,
+            // occurred_at defaults to CURRENT_TIMESTAMP(6) at the DB.
+        });
+        return { id };
+    }
+}
+export function createAuditCommands(dbManager) {
+    return new AuditCommands(dbManager);
+}

package/dist/modules/audit/audit-queries.d.ts

@@ -0,0 +1,41 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Audit-log reads (docs/06-auth-and-security/02-auditability.md — Workstreams 3 & 4). Reads run on the pool
+ * directly — they never need to join an audit write's transaction — so this
+ * takes the raw `db` (drizzle over the pool) rather than the `DBManager`.
+ * Access scoping is the caller's responsibility (the document's own read
+ * gate); these queries do no scoping of their own. Mirrors
+ * `packages/db-postgres/src/modules/audit/audit-queries.ts` with the CAST /
+ * string-concat / result-shape adjustments the mysql2 driver requires — see
+ * inline comments at each divergence.
+ */
+import type { AuditLogPage, IAuditQueries } from '@byline/core';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+type DatabaseConnection = MySql2Database<typeof schema>;
+export declare class AuditQueries implements IAuditQueries {
+    private db;
+    constructor(db: DatabaseConnection);
+    getDocumentAuditLog(params: {
+        document_id: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<AuditLogPage>;
+    findAuditLog(params: {
+        actorId?: string;
+        collectionId?: string;
+        action?: string;
+        from?: Date;
+        to?: Date;
+        page?: number;
+        page_size?: number;
+    }): Promise<AuditLogPage>;
+}
+export declare function createAuditQueries(db: DatabaseConnection): AuditQueries;
+export {};