@plitzi/sdk-server 0.33.2 → 0.34.0

package/dist/modules/mysql/accounts.js

@@ -0,0 +1,365 @@
+import { execute, selectOne, selectRows } from "./query.js";
+import { createSessionStore } from "./sessions.js";
+//#region src/modules/mysql/accounts.ts
+var ACCOUNT_COLUMNS = "a.id, a.username, a.email, a.password_hash, a.status, a.verified";
+var toRecord = (row) => ({
+	id: row.id,
+	username: row.username,
+	email: row.email,
+	active: row.status === "active",
+	verified: row.verified === 1,
+	...row.password_hash ? { passwordHash: row.password_hash } : {},
+	...row.refresh_expires_at !== null && row.refresh_expires_at !== void 0 ? { refreshExpiresAt: row.refresh_expires_at } : {},
+	...row.session_started_at !== null && row.session_started_at !== void 0 ? { sessionStartedAt: row.session_started_at } : {}
+});
+/**
+* An opaque single-use token, as a lookup key. Empty is not one.
+*
+* Clearing a reset token is written as `setResetToken(userId, '')` — the flows say so — and an empty string stored
+* as an empty string is a value that MATCHES: one lookup would then return whichever account was cleared first, and
+* a password-reset link with no token in it would work. Stored as NULL, and never looked up when blank.
+*/
+var asLookup = (token) => token.trim() === "" ? void 0 : token;
+var accessRows = (rows) => {
+	const roles = /* @__PURE__ */ new Set();
+	const permissions = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		roles.add(row.role);
+		if (row.permission) permissions.add(row.permission);
+	}
+	return {
+		roles: [...roles],
+		permissions: [...permissions]
+	};
+};
+var createAccountStore = (db, t) => {
+	const sessions = createSessionStore(db, t);
+	const findBy = (column, value) => selectOne(db, `SELECT ${ACCOUNT_COLUMNS} FROM ${t.account} a WHERE a.${column} = ? LIMIT 1`, [value]);
+	const loadAccess = async (userId) => accessRows(await selectRows(db, `SELECT r.name AS role, p.name AS permission
+           FROM ${t.accountRole} ar
+           JOIN ${t.role} r ON r.id = ar.role_id
+           LEFT JOIN ${t.rolePermission} rp ON rp.role_id = r.id
+           LEFT JOIN ${t.permission} p ON p.id = rp.permission_id
+          WHERE ar.account_id = ?`, [userId]));
+	return {
+		/**
+		* Looked up BY THE TOKEN, which is what makes a session revocable: writing a new pair over the row retires the
+		* previous one, so a credential that no longer matches is dead however valid its signature still is.
+		*
+		* A suspended account resolves to nothing at all rather than to an actor the caller then has to remember to
+		* check — deactivating somebody has to end the session they are already holding, not just the next login.
+		*/
+		findAccountByToken: async (token) => {
+			const row = await selectOne(db, `SELECT ${ACCOUNT_COLUMNS}, s.expires_at AS session_expires_at
+           FROM ${t.session} s
+           JOIN ${t.account} a ON a.id = s.account_id
+          WHERE s.token = ? AND a.status = 'active'
+          LIMIT 1`, [token]);
+			if (!row) return;
+			const { roles, permissions } = await loadAccess(row.id);
+			return {
+				id: row.id,
+				username: row.username,
+				email: row.email,
+				verified: row.verified === 1,
+				roles,
+				permissions,
+				token,
+				expiresAt: row.session_expires_at ?? 0
+			};
+		},
+		findSpaceToken: async (token) => {
+			const row = await selectOne(db, `SELECT space_id, scope, account_id FROM ${t.spaceToken} WHERE token = ? LIMIT 1`, [token]);
+			if (!row) return;
+			return {
+				spaceId: row.space_id,
+				scope: row.scope,
+				...row.account_id !== null ? { userId: row.account_id } : {}
+			};
+		},
+		findMembership: async (userId, spaceId) => {
+			const rows = await selectRows(db, `SELECT sm.is_owner, r.name AS role, p.name AS permission
+           FROM ${t.spaceMember} sm
+           JOIN ${t.role} r ON r.id = sm.role_id
+           LEFT JOIN ${t.rolePermission} rp ON rp.role_id = r.id
+           LEFT JOIN ${t.permission} p ON p.id = rp.permission_id
+          WHERE sm.account_id = ? AND sm.space_id = ?`, [userId, spaceId]);
+			if (rows.length === 0) return;
+			const { roles, permissions } = accessRows(rows);
+			return {
+				spaceId,
+				isOwner: rows[0].is_owner === 1,
+				role: roles[0],
+				permissions
+			};
+		},
+		loadAccess,
+		/**
+		* A sign-in adds a session; a renewal replaces the one it names.
+		*
+		* The replace is an UPDATE on purpose, not a delete-then-insert: it keeps the row's identity, so the device
+		* somebody sees in their session list is still the same device after it renews, and a session revoked in the
+		* instant between the two cannot come back. When the update matches nothing — the session was revoked while
+		* this renewal was in flight — **no row is written**. The caller walks away with a credential that is not
+		* stored, which is a signed-out user rather than a revoked session resurrected.
+		*/
+		saveSession: async (userId, session, context) => {
+			const replaces = context?.replaces;
+			if (replaces?.refreshToken !== void 0 || replaces?.accessToken !== void 0) {
+				const column = replaces.refreshToken !== void 0 ? "refresh_token" : "token";
+				const value = replaces.refreshToken ?? replaces.accessToken;
+				await execute(db, `UPDATE ${t.session}
+              SET token = ?, expires_at = ?, refresh_token = ?, refresh_expires_at = ?
+            WHERE ${column} = ? AND account_id = ?`, [
+					session.token,
+					session.expiresAt,
+					session.refreshToken ?? null,
+					session.refreshExpiresAt ?? null,
+					value,
+					userId
+				]);
+				return;
+			}
+			await execute(db, `INSERT INTO ${t.session} (account_id, token, expires_at, refresh_token, refresh_expires_at, user_agent, ip)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+				userId,
+				session.token,
+				session.expiresAt,
+				session.refreshToken ?? null,
+				session.refreshExpiresAt ?? null,
+				context?.client?.userAgent?.slice(0, 255) ?? null,
+				context?.client?.ip ?? null
+			]);
+		},
+		/**
+		* By whichever half the caller is holding, or every session of an account.
+		*
+		* An empty target clears NOTHING — a `WHERE` assembled from no conditions is a `WHERE` that matches every row,
+		* and the statement that would sign out an entire deployment must not be reachable by leaving an argument off.
+		*/
+		clearSession: async (target) => {
+			const conditions = [];
+			const params = [];
+			if (target.userId !== void 0) {
+				conditions.push("account_id = ?");
+				params.push(target.userId);
+			}
+			if (target.accessToken !== void 0) {
+				conditions.push("token = ?");
+				params.push(target.accessToken);
+			}
+			if (target.refreshToken !== void 0) {
+				conditions.push("refresh_token = ?");
+				params.push(target.refreshToken);
+			}
+			if (conditions.length === 0) return;
+			await execute(db, `DELETE FROM ${t.session} WHERE ${conditions.join(" OR ")}`, params);
+		},
+		findByUsername: async (username) => {
+			const row = await findBy("username", username);
+			return row ? toRecord(row) : void 0;
+		},
+		findByEmail: async (email) => {
+			const row = await findBy("email", email);
+			return row ? toRecord(row) : void 0;
+		},
+		/**
+		* `refreshExpiresAt` comes off the ROW. A store that keeps it inside a session object and forgets to lift it out
+		* has every renewal refused as expired — which does not fail at login, it fails a day later, silently, when the
+		* access token ages out and the session that looked fine simply ends.
+		*/
+		findByRefreshToken: async (token) => {
+			const row = await selectOne(db, `SELECT ${ACCOUNT_COLUMNS}, s.refresh_expires_at, UNIX_TIMESTAMP(s.created_at) AS session_started_at
+           FROM ${t.session} s
+           JOIN ${t.account} a ON a.id = s.account_id
+          WHERE s.refresh_token = ?
+          LIMIT 1`, [token]);
+			return row ? toRecord(row) : void 0;
+		},
+		createAccount: async (account) => {
+			return {
+				id: (await execute(db, `INSERT INTO ${t.account} (username, email, password_hash) VALUES (?, ?, ?)`, [
+					account.username,
+					account.email,
+					account.passwordHash
+				])).insertId,
+				username: account.username,
+				email: account.email,
+				active: true,
+				verified: false,
+				passwordHash: account.passwordHash
+			};
+		},
+		setPassword: async (userId, passwordHash) => {
+			await execute(db, `UPDATE ${t.account} SET password_hash = ? WHERE id = ?`, [passwordHash, userId]);
+		},
+		setResetToken: async (userId, token) => {
+			await execute(db, `UPDATE ${t.account} SET reset_token = ? WHERE id = ?`, [asLookup(token) ?? null, userId]);
+		},
+		findByResetToken: async (token) => {
+			const lookup = asLookup(token);
+			if (!lookup) return;
+			const row = await findBy("reset_token", lookup);
+			return row ? toRecord(row) : void 0;
+		},
+		setValidationToken: async (userId, token) => {
+			await execute(db, `UPDATE ${t.account} SET validation_token = ? WHERE id = ?`, [asLookup(token) ?? null, userId]);
+		},
+		findByValidationToken: async (token) => {
+			const lookup = asLookup(token);
+			if (!lookup) return;
+			const row = await findBy("validation_token", lookup);
+			return row ? toRecord(row) : void 0;
+		},
+		/**
+		* The address is parked in its own column, so nothing that resolves an account by email can find it: it is not
+		* this account's address until it is confirmed, and a lookup that matched it would let an unconfirmed change
+		* take over a sign-in identifier.
+		*/
+		setPendingEmail: async (userId, email, token) => {
+			await execute(db, `UPDATE ${t.account} SET pending_email = ?, pending_email_token = ? WHERE id = ?`, [
+				email,
+				asLookup(token) ?? null,
+				userId
+			]);
+		},
+		findByPendingEmail: async (token) => {
+			const lookup = asLookup(token);
+			if (!lookup) return;
+			const row = await selectOne(db, `SELECT ${ACCOUNT_COLUMNS}, a.pending_email FROM ${t.account} a WHERE a.pending_email_token = ? LIMIT 1`, [lookup]);
+			return row?.pending_email ? {
+				account: toRecord(row),
+				email: row.pending_email
+			} : void 0;
+		},
+		clearPendingEmail: async (userId) => {
+			await execute(db, `UPDATE ${t.account} SET pending_email = NULL, pending_email_token = NULL WHERE id = ?`, [userId]);
+		},
+		setVerified: async (userId, verified) => {
+			await execute(db, `UPDATE ${t.account} SET verified = ?, validation_token = NULL WHERE id = ?`, [verified ? 1 : 0, userId]);
+		},
+		findById: async (userId) => {
+			const row = await findBy("id", userId);
+			return row ? toRecord(row) : void 0;
+		},
+		/**
+		* Only the columns the caller named. A blanket UPDATE cannot tell "leave the email alone" from "clear it", and
+		* a profile form that posts one field would wipe the other.
+		*/
+		updateAccount: async (userId, changes) => {
+			const columns = [];
+			const params = [];
+			if (changes.username !== void 0) {
+				columns.push("username = ?");
+				params.push(changes.username);
+			}
+			if (changes.email !== void 0) {
+				columns.push("email = ?");
+				params.push(changes.email);
+			}
+			if (columns.length > 0) await execute(db, `UPDATE ${t.account} SET ${columns.join(", ")} WHERE id = ?`, [...params, userId]);
+			const row = await findBy("id", userId);
+			if (!row) throw new Error(`@plitzi/sdk-server/mysql: account ${userId} disappeared while being updated.`);
+			return toRecord(row);
+		},
+		setStatus: async (userId, status) => {
+			await execute(db, `UPDATE ${t.account} SET status = ? WHERE id = ?`, [status, userId]);
+		},
+		/**
+		* The row goes, and its sessions with it — the foreign key cascades, so there is no window in which a deleted
+		* account still has a working credential. A deployment that has to keep the row for its content or its invoices
+		* replaces this adapter with one that anonymises instead; the sessions still have to go.
+		*/
+		deleteAccount: async (userId) => {
+			await execute(db, `DELETE FROM ${t.account} WHERE id = ?`, [userId]);
+		},
+		listAccounts: async (query) => {
+			const conditions = [];
+			const params = [];
+			if (query.search) {
+				conditions.push("(a.username LIKE ? OR a.email LIKE ?)");
+				const like = `%${query.search.replace(/[%_\\]/g, (character) => `\\${character}`)}%`;
+				params.push(like, like);
+			}
+			if (query.status) {
+				conditions.push("a.status = ?");
+				params.push(query.status);
+			}
+			const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+			const limit = Math.min(Math.max(query.limit ?? 50, 1), 200);
+			const offset = Math.max(query.offset ?? 0, 0);
+			const counted = await selectOne(db, `SELECT COUNT(*) AS total FROM ${t.account} a ${where}`, params);
+			return {
+				accounts: (await selectRows(db, `SELECT ${ACCOUNT_COLUMNS} FROM ${t.account} a ${where} ORDER BY a.id ASC LIMIT ? OFFSET ?`, [
+					...params,
+					limit,
+					offset
+				])).map(toRecord),
+				total: counted?.total ?? 0
+			};
+		},
+		/** Exactly these roles, which means the ones not named are taken away. Unknown names are ignored, not created. */
+		setRoles: async (userId, roles) => {
+			await execute(db, `DELETE FROM ${t.accountRole} WHERE account_id = ?`, [userId]);
+			if (roles.length === 0) return;
+			const placeholders = roles.map(() => "?").join(", ");
+			await execute(db, `INSERT INTO ${t.accountRole} (account_id, role_id)
+         SELECT ?, id FROM ${t.role} WHERE name IN (${placeholders})`, [userId, ...roles]);
+		},
+		saveOtp: async (code) => {
+			await execute(db, `DELETE FROM ${t.otp} WHERE purpose = ? AND identifier = ?`, [code.purpose, code.identifier]);
+			await execute(db, `INSERT INTO ${t.otp} (account_id, purpose, identifier, code_hash, expires_at) VALUES (?, ?, ?, ?, ?)`, [
+				code.userId ?? null,
+				code.purpose,
+				code.identifier,
+				code.codeHash,
+				code.expiresAt
+			]);
+		},
+		findOtp: async (purpose, identifier) => {
+			const row = await selectOne(db, `SELECT id, code_hash, expires_at, account_id FROM ${t.otp}
+          WHERE purpose = ? AND identifier = ? ORDER BY id DESC LIMIT 1`, [purpose, identifier]);
+			if (!row) return;
+			return {
+				id: row.id,
+				codeHash: row.code_hash,
+				expiresAt: row.expires_at,
+				...row.account_id !== null ? { userId: row.account_id } : {}
+			};
+		},
+		consumeOtp: async (id) => {
+			await execute(db, `DELETE FROM ${t.otp} WHERE id = ?`, [id]);
+		},
+		/**
+		* The second factor. `recovery_codes` is a newline-separated list of digests, not a JSON blob: it is only ever
+		* read whole and written whole, and a text column that a human can read in a crisis beats one they cannot.
+		*/
+		loadMfa: async (userId) => {
+			const row = await selectOne(db, `SELECT secret, confirmed_at, recovery_codes FROM ${t.mfa} WHERE account_id = ? LIMIT 1`, [userId]);
+			if (!row) return;
+			return {
+				secret: row.secret,
+				...row.confirmed_at !== null ? { confirmedAt: row.confirmed_at } : {},
+				recoveryCodes: (row.recovery_codes ?? "").split("\n").filter(Boolean)
+			};
+		},
+		saveMfa: async (userId, mfaRecord) => {
+			await execute(db, `INSERT INTO ${t.mfa} (account_id, secret, confirmed_at, recovery_codes) VALUES (?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE
+           secret = VALUES(secret), confirmed_at = VALUES(confirmed_at), recovery_codes = VALUES(recovery_codes)`, [
+				userId,
+				mfaRecord.secret,
+				mfaRecord.confirmedAt ?? null,
+				(mfaRecord.recoveryCodes ?? []).join("\n")
+			]);
+		},
+		deleteMfa: async (userId) => {
+			await execute(db, `DELETE FROM ${t.mfa} WHERE account_id = ?`, [userId]);
+		},
+		listSessions: (userId, currentToken) => sessions.list(userId, currentToken),
+		revokeSession: (userId, sessionId) => sessions.revoke(userId, sessionId),
+		revokeOtherSessions: (userId, currentToken) => sessions.revokeOthers(userId, currentToken)
+	};
+};
+//#endregion
+export { createAccountStore };

package/dist/modules/mysql/accounts.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,58 @@
+import { Tables } from './config';
+import { SpaceScope } from '../../core/auth/tokens';
+import { Pool } from 'mysql2/promise';
+export interface AccountSeed {
+    username: string;
+    email: string;
+    /** Plain text, hashed here. Omit for an account that signs in through an identity provider and has no password. */
+    password?: string;
+    verified?: boolean;
+    /** Global roles. They must exist — `ensureRole` first, or an unknown name is a mistake worth failing on. */
+    roles?: string[];
+}
+export interface SpaceTokenSeed {
+    token: string;
+    scope?: SpaceScope;
+    isDefault?: boolean;
+    origins?: string[];
+    expiresAt?: number | null;
+    accountId?: number;
+}
+/**
+ * Everything that puts rows in these tables that no request ever will.
+ *
+ * The auth flows read accounts, roles and memberships; almost none of them create one. Signing up creates an
+ * account and that is the whole of it — a role, a permission, a space membership and a space's first credential all
+ * come from somewhere else: a seed script, an admin screen, the moment a space is created. That somewhere else
+ * needs statements, and a deployment writing them by hand against a schema it did not design is a deployment about
+ * to get a join wrong.
+ *
+ * Every operation is idempotent, because the place they are called from is usually a startup path that runs again.
+ */
+export declare const createAdmin: (pool: Pool, t: Tables) => {
+    ensurePermissions: (names: string[]) => Promise<void>;
+    ensureRole: (name: string, options?: {
+        permissions?: string[];
+        description?: string;
+    }) => Promise<number>;
+    grantRole: (accountId: number, role: string) => Promise<void>;
+    revokeRole: (accountId: number, role: string) => Promise<void>;
+    ensureAccount: (seed: AccountSeed) => Promise<number>;
+    /** Membership of one space, with the role that decides what they may do inside it. */
+    addMember: (spaceId: number, accountId: number, role: string, options?: {
+        owner?: boolean;
+    }) => Promise<void>;
+    removeMember: (spaceId: number, accountId: number) => Promise<void>;
+    listMembers: (spaceId: number) => Promise<{
+        accountId: number;
+        username: string;
+        role: string;
+        owner: boolean;
+    }[]>;
+    /**
+     * A space's credential row. Replaces the default one rather than adding a second: exactly one row per space
+     * carries `is_default`, and two of them make `loadDefault` answer whichever the database happened to return.
+     */
+    createSpaceToken: (spaceId: number, seed: SpaceTokenSeed) => Promise<number>;
+};
+export type MysqlAdmin = ReturnType<typeof createAdmin>;

package/dist/modules/mysql/admin.js

@@ -0,0 +1,133 @@
+import { hashPassword } from "../../core/auth/passwords.js";
+import { execute, selectOne, selectRows } from "./query.js";
+//#region src/modules/mysql/admin.ts
+/**
+* Everything that puts rows in these tables that no request ever will.
+*
+* The auth flows read accounts, roles and memberships; almost none of them create one. Signing up creates an
+* account and that is the whole of it — a role, a permission, a space membership and a space's first credential all
+* come from somewhere else: a seed script, an admin screen, the moment a space is created. That somewhere else
+* needs statements, and a deployment writing them by hand against a schema it did not design is a deployment about
+* to get a join wrong.
+*
+* Every operation is idempotent, because the place they are called from is usually a startup path that runs again.
+*/
+var createAdmin = (pool, t) => {
+	const idOf = async (table, name) => {
+		return (await selectOne(pool, `SELECT id FROM ${table} WHERE name = ? LIMIT 1`, [name]))?.id;
+	};
+	const ensurePermissions = async (names) => {
+		if (names.length === 0) return;
+		const values = names.map(() => "(?)").join(", ");
+		await execute(pool, `INSERT IGNORE INTO ${t.permission} (name) VALUES ${values}`, names);
+	};
+	/**
+	* Declarative: the permission list given is the permission list the role ends up with. A role that only ever
+	* gained permissions could never lose one, and the first thing anybody does with a role is take something away.
+	*/
+	const ensureRole = async (name, options = {}) => {
+		const { permissions = [], description } = options;
+		await execute(pool, `INSERT INTO ${t.role} (name, description) VALUES (?, ?)
+       ON DUPLICATE KEY UPDATE description = COALESCE(VALUES(description), description)`, [name, description ?? null]);
+		const roleId = await idOf(t.role, name);
+		if (roleId === void 0) throw new Error(`@plitzi/sdk-server/mysql: role "${name}" could not be read back after being written.`);
+		await ensurePermissions(permissions);
+		const connection = await pool.getConnection();
+		try {
+			await connection.beginTransaction();
+			await execute(connection, `DELETE FROM ${t.rolePermission} WHERE role_id = ?`, [roleId]);
+			if (permissions.length > 0) {
+				const placeholders = permissions.map(() => "?").join(", ");
+				await execute(connection, `INSERT INTO ${t.rolePermission} (role_id, permission_id)
+           SELECT ?, id FROM ${t.permission} WHERE name IN (${placeholders})`, [roleId, ...permissions]);
+			}
+			await connection.commit();
+		} catch (error) {
+			await connection.rollback();
+			throw error;
+		} finally {
+			connection.release();
+		}
+		return roleId;
+	};
+	const requireRole = async (name) => {
+		const roleId = await idOf(t.role, name);
+		if (roleId === void 0) throw new Error(`@plitzi/sdk-server/mysql: no role named "${name}". Create it with ensureRole() first.`);
+		return roleId;
+	};
+	const grantRole = async (accountId, role) => {
+		const roleId = await requireRole(role);
+		await execute(pool, `INSERT IGNORE INTO ${t.accountRole} (account_id, role_id) VALUES (?, ?)`, [accountId, roleId]);
+	};
+	const revokeRole = async (accountId, role) => {
+		const roleId = await requireRole(role);
+		await execute(pool, `DELETE FROM ${t.accountRole} WHERE account_id = ? AND role_id = ?`, [accountId, roleId]);
+	};
+	/**
+	* Keyed by username. The password is re-hashed on every call so a seed stays the source of truth for it — which
+	* is what a seed is for, and the reason this must never be pointed at a database where people change their own.
+	*/
+	const ensureAccount = async (seed) => {
+		const passwordHash = seed.password === void 0 ? null : await hashPassword(seed.password);
+		await execute(pool, `INSERT INTO ${t.account} (username, email, password_hash, verified) VALUES (?, ?, ?, ?)
+       ON DUPLICATE KEY UPDATE
+         email = VALUES(email),
+         password_hash = COALESCE(VALUES(password_hash), password_hash),
+         verified = VALUES(verified)`, [
+			seed.username,
+			seed.email,
+			passwordHash,
+			seed.verified ? 1 : 0
+		]);
+		const row = await selectOne(pool, `SELECT id FROM ${t.account} WHERE username = ? LIMIT 1`, [seed.username]);
+		if (!row) throw new Error(`@plitzi/sdk-server/mysql: account "${seed.username}" could not be read back after writing.`);
+		for (const role of seed.roles ?? []) await grantRole(row.id, role);
+		return row.id;
+	};
+	return {
+		ensurePermissions,
+		ensureRole,
+		grantRole,
+		revokeRole,
+		ensureAccount,
+		/** Membership of one space, with the role that decides what they may do inside it. */
+		addMember: async (spaceId, accountId, role, options = {}) => {
+			const roleId = await requireRole(role);
+			await execute(pool, `INSERT INTO ${t.spaceMember} (space_id, account_id, role_id, is_owner) VALUES (?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE role_id = VALUES(role_id), is_owner = VALUES(is_owner)`, [
+				spaceId,
+				accountId,
+				roleId,
+				options.owner ? 1 : 0
+			]);
+		},
+		removeMember: async (spaceId, accountId) => {
+			await execute(pool, `DELETE FROM ${t.spaceMember} WHERE space_id = ? AND account_id = ?`, [spaceId, accountId]);
+		},
+		listMembers: (spaceId) => selectRows(pool, `SELECT sm.account_id AS accountId, a.username, r.name AS role, sm.is_owner AS owner
+           FROM ${t.spaceMember} sm
+           JOIN ${t.account} a ON a.id = sm.account_id
+           JOIN ${t.role} r ON r.id = sm.role_id
+          WHERE sm.space_id = ?`, [spaceId]),
+		/**
+		* A space's credential row. Replaces the default one rather than adding a second: exactly one row per space
+		* carries `is_default`, and two of them make `loadDefault` answer whichever the database happened to return.
+		*/
+		createSpaceToken: async (spaceId, seed) => {
+			const isDefault = seed.isDefault ?? true;
+			if (isDefault) await execute(pool, `DELETE FROM ${t.spaceToken} WHERE space_id = ? AND is_default = 1`, [spaceId]);
+			return (await execute(pool, `INSERT INTO ${t.spaceToken} (space_id, token, scope, is_default, origins, expires_at, account_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+				spaceId,
+				seed.token,
+				seed.scope ?? "render",
+				isDefault ? 1 : 0,
+				(seed.origins ?? []).join(","),
+				seed.expiresAt ?? null,
+				seed.accountId ?? null
+			])).insertId;
+		}
+	};
+};
+//#endregion
+export { createAdmin };

package/dist/modules/mysql/config.d.ts

@@ -0,0 +1,82 @@
+import { Pool, PoolOptions } from 'mysql2/promise';
+/**
+ * Where the database is, and what this deployment calls the tables in it.
+ *
+ * `url` and the discrete fields are two ways of saying the same thing — a hosted database hands you one string, a
+ * docker-compose hands you five values — and the discrete fields win where both are given, so a single override
+ * does not mean re-assembling the URL.
+ */
+export interface MysqlConfig {
+    /** `mysql://user:password@host:port/database`. Whatever a managed database hands you, unedited. */
+    url?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    /** Passed to the driver as given. `true` turns TLS on with the system CA set. */
+    ssl?: PoolOptions['ssl'];
+    connectionLimit?: number;
+    /**
+     * Prefix for every table below. **Required**, and deliberately so.
+     *
+     * `account`, `role`, `permission` and `session` are among the most ordinary table names there are, and this
+     * module exists to be pointed at a database that has other things in it. Optional, the default was the empty
+     * string — the one value guaranteed to collide — so the guard that refuses to adopt somebody else's tables fired
+     * on the common case rather than the dangerous one. A prefix you chose makes a collision mean what it says.
+     *
+     * `'plitzi_'` is a fine answer. So is your product's name. Say it once: nothing outside this module ever writes
+     * a table name.
+     */
+    tablePrefix: string;
+    /**
+     * Create and update the tables at startup. On by default, which is what makes a fresh database work with no step
+     * before it. A deployment whose database user cannot run DDL — the usual arrangement in production — turns it off
+     * and applies the statements from `schemaStatements()` through whatever it migrates with.
+     */
+    autoMigrate?: boolean;
+    /**
+     * Create the database itself if the server has not got it, before connecting to it. Off by default and meant for
+     * development, where "point it at a MySQL and go" is the whole appeal and the alternative is one `CREATE DATABASE`
+     * that nobody remembers until the first run fails. In production the database exists before the application does,
+     * made by somebody holding rights the application should not have.
+     */
+    ensureDatabase?: boolean;
+    /**
+     * Use tables with these names that already exist and were not created here.
+     *
+     * Off by default, and the default is the safe one: this module is meant to be pointed at a database that has
+     * unrelated tables in it, and `role`, `permission` and `session` are among the most ordinary names there are.
+     * `CREATE TABLE IF NOT EXISTS` would silently adopt somebody else's, and the failure would surface much later as
+     * a query against columns that are not there. Turn it on only when re-attaching to tables that really are this
+     * schema's — a restored backup whose `schema_version` row was lost, say.
+     */
+    adoptExisting?: boolean;
+    /** An existing pool, for a deployment that already has one. Given, nothing here creates or ends a connection. */
+    pool?: Pool;
+    log?: (message: string) => void;
+}
+/**
+ * The tables the auth kernel needs. Named after the kernel's own vocabulary — an `AccountRecord` is stored in
+ * `account` — rather than after any one deployment's user table, which is a thing it maps ONTO these.
+ */
+export declare const TABLE_NAMES: {
+    readonly schemaVersion: "schema_version";
+    readonly account: "account";
+    readonly session: "session";
+    readonly identity: "account_identity";
+    readonly mfa: "account_mfa";
+    readonly otp: "account_otp";
+    readonly role: "role";
+    readonly permission: "permission";
+    readonly rolePermission: "role_permission";
+    readonly accountRole: "account_role";
+    readonly spaceMember: "space_member";
+    readonly spaceToken: "space_token";
+};
+export type TableKey = keyof typeof TABLE_NAMES;
+/** Table names, already prefixed and already backticked — the only form the rest of the module ever sees. */
+export type Tables = Record<TableKey, string>;
+export declare const resolveTables: (prefix: string) => Tables;
+/** The bare, unquoted names — for a migration tool, or an error that has to say which table it meant. */
+export declare const tableNames: (prefix: string) => Record<TableKey, string>;

package/dist/modules/mysql/config.js

@@ -0,0 +1,30 @@
+//#region src/modules/mysql/config.ts
+/**
+* The tables the auth kernel needs. Named after the kernel's own vocabulary — an `AccountRecord` is stored in
+* `account` — rather than after any one deployment's user table, which is a thing it maps ONTO these.
+*/
+var TABLE_NAMES = {
+	schemaVersion: "schema_version",
+	account: "account",
+	session: "session",
+	identity: "account_identity",
+	mfa: "account_mfa",
+	otp: "account_otp",
+	role: "role",
+	permission: "permission",
+	rolePermission: "role_permission",
+	accountRole: "account_role",
+	spaceMember: "space_member",
+	spaceToken: "space_token"
+};
+var resolveTables = (prefix) => {
+	const entries = Object.entries(TABLE_NAMES).map(([key, name]) => [key, `\`${prefix}${name}\``]);
+	return Object.fromEntries(entries);
+};
+/** The bare, unquoted names — for a migration tool, or an error that has to say which table it meant. */
+var tableNames = (prefix) => {
+	const entries = Object.entries(TABLE_NAMES).map(([key, name]) => [key, `${prefix}${name}`]);
+	return Object.fromEntries(entries);
+};
+//#endregion
+export { TABLE_NAMES, resolveTables, tableNames };