@plitzi/sdk-server 0.33.2 → 0.34.0

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

@@ -0,0 +1,35 @@
+import { Tables } from './config';
+import { Queryable } from './query';
+/** The same person at somebody else's identity provider. */
+export interface LinkedIdentity {
+    id: number;
+    provider: string;
+    subject: string;
+    email?: string;
+    createdAt: number;
+}
+/**
+ * External identities, as rows.
+ *
+ * Deliberately NOT part of the auth adapters: whether a Google account with a matching email is the same person is
+ * a judgement only a deployment can make, and it lives in `exchangeCredential` / the social `linkAccount` hook.
+ * What is mechanical is the storage, and a self-hoster should not have to design the table for it.
+ *
+ * The unique key is `(provider, subject)`, never the email. A provider that does not verify addresses lets anybody
+ * claim any account by signing up with one — which is the single most common way social linking is got wrong.
+ */
+export declare const createIdentityStore: (db: Queryable, t: Tables) => {
+    find: (provider: string, subject: string) => Promise<{
+        accountId: number;
+    } | undefined>;
+    /** Idempotent: signing in again with the same provider identity must not be an error. */
+    link: (accountId: number, identity: {
+        provider: string;
+        subject: string;
+        email?: string;
+    }) => Promise<void>;
+    list: (accountId: number) => Promise<LinkedIdentity[]>;
+    /** Scoped by account, or one person could unlink another's provider by guessing a number. */
+    unlink: (accountId: number, provider: string) => Promise<boolean>;
+};
+export type IdentityStore = ReturnType<typeof createIdentityStore>;

package/dist/modules/mysql/identities.js

@@ -0,0 +1,43 @@
+import { execute, selectOne, selectRows } from "./query.js";
+//#region src/modules/mysql/identities.ts
+/**
+* External identities, as rows.
+*
+* Deliberately NOT part of the auth adapters: whether a Google account with a matching email is the same person is
+* a judgement only a deployment can make, and it lives in `exchangeCredential` / the social `linkAccount` hook.
+* What is mechanical is the storage, and a self-hoster should not have to design the table for it.
+*
+* The unique key is `(provider, subject)`, never the email. A provider that does not verify addresses lets anybody
+* claim any account by signing up with one — which is the single most common way social linking is got wrong.
+*/
+var createIdentityStore = (db, t) => ({
+	find: async (provider, subject) => {
+		const row = await selectOne(db, `SELECT account_id FROM ${t.identity} WHERE provider = ? AND subject = ? LIMIT 1`, [provider, subject]);
+		return row ? { accountId: row.account_id } : void 0;
+	},
+	/** Idempotent: signing in again with the same provider identity must not be an error. */
+	link: async (accountId, identity) => {
+		await execute(db, `INSERT INTO ${t.identity} (account_id, provider, subject, email) VALUES (?, ?, ?, ?)
+       ON DUPLICATE KEY UPDATE account_id = VALUES(account_id), email = VALUES(email)`, [
+			accountId,
+			identity.provider,
+			identity.subject,
+			identity.email ?? null
+		]);
+	},
+	list: async (accountId) => {
+		return (await selectRows(db, `SELECT id, provider, subject, email, created_at FROM ${t.identity} WHERE account_id = ? ORDER BY id ASC`, [accountId])).map((row) => ({
+			id: row.id,
+			provider: row.provider,
+			subject: row.subject,
+			...row.email ? { email: row.email } : {},
+			createdAt: Math.floor(row.created_at.getTime() / 1e3)
+		}));
+	},
+	/** Scoped by account, or one person could unlink another's provider by guessing a number. */
+	unlink: async (accountId, provider) => {
+		return (await execute(db, `DELETE FROM ${t.identity} WHERE account_id = ? AND provider = ?`, [accountId, provider])).affectedRows > 0;
+	}
+});
+//#endregion
+export { createIdentityStore };

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

@@ -0,0 +1,67 @@
+import { dropSchema } from './schema';
+import { MysqlAdmin } from './admin';
+import { MysqlConfig } from './config';
+import { IdentityStore } from './identities';
+import { SessionStore } from './sessions';
+import { AccountAdapters } from '../../core/auth/api';
+import { IdentityAdapters } from '../../core/auth/identity';
+import { SpaceTokenAdapters } from '../../core/auth/spaceTokens';
+import { Pool } from 'mysql2/promise';
+export interface MysqlStore {
+    /** The pool, for a deployment with queries of its own. Ended by `close()` unless it was handed in. */
+    pool: Pool;
+    /** The resolved, unprefixed-plus-prefix table names, so a migration tool or an error can name one. */
+    tables: Record<string, string>;
+    schemaVersion: number;
+    /**
+     * Both halves of what `createAuth` asks for, implemented. Spread your own on top to add what only you can answer
+     * — `sendMail` for the reset and validation flows, `exchangeCredential` for an external identity provider.
+     */
+    authAdapters: IdentityAdapters & AccountAdapters;
+    /** For `createSpaceTokenApi`. Present whether or not this deployment issues space credentials. */
+    spaceTokenAdapters: SpaceTokenAdapters;
+    /** The account's signed-in devices: list them, end one, end the others. */
+    sessions: SessionStore;
+    /** Accounts at other identity providers. Storage only — whether two are the same person is your judgement. */
+    identities: IdentityStore;
+    /** Seeding and administration — roles, permissions, memberships, a space's first credential. */
+    admin: MysqlAdmin;
+    /**
+     * Removes this schema and nothing else — for a deployment that shared a database with other things and has
+     * stopped using it. Returns the tables it dropped. Refuses a database it was never migrated into.
+     */
+    uninstall: (options?: {
+        force?: boolean;
+    }) => Promise<string[]>;
+    close: () => Promise<void>;
+}
+/**
+ * An account store on MySQL, with the tables it needs.
+ *
+ * This is the batteries-included half of `createAuth`. A deployment that already has users implements the adapters
+ * against its own tables and never comes here; a deployment standing one up gets the schema, the queries and the
+ * traps already handled:
+ *
+ * ```ts
+ * const store = await createMysqlStore({ url: process.env.DATABASE_URL });
+ *
+ * const auth = createAuth({
+ *   tokens: { secret, issuer },
+ *   adapters: store.authAdapters,
+ * });
+ * ```
+ *
+ * It connects to a MySQL server; it does not start one. Where the database lives is a deployment decision and one
+ * this cannot make well — a container in development, a managed instance in production, and neither of them
+ * something a library should be launching behind your back.
+ */
+export declare const createMysqlStore: (config: MysqlConfig) => Promise<MysqlStore>;
+export { dropSchema };
+/** The DDL, for a deployment whose database user may not run it — see `MysqlConfig.autoMigrate`. */
+export declare const mysqlSchemaStatements: (tablePrefix: string, fromVersion?: number) => string[];
+export { TABLE_NAMES, tableNames } from './config';
+export { SCHEMA_VERSION } from './schema';
+export type { MysqlConfig, TableKey, Tables } from './config';
+export type { AccountSeed, MysqlAdmin, SpaceTokenSeed } from './admin';
+export type { SessionStore, SessionSummary } from './sessions';
+export type { IdentityStore, LinkedIdentity } from './identities';

package/dist/modules/mysql/index.js

@@ -0,0 +1,62 @@
+import { createSessionStore } from "./sessions.js";
+import { createAccountStore } from "./accounts.js";
+import { createAdmin } from "./admin.js";
+import { TABLE_NAMES, resolveTables, tableNames } from "./config.js";
+import { createIdentityStore } from "./identities.js";
+import { createPool } from "./pool.js";
+import { SCHEMA_VERSION, dropSchema, migrate, schemaStatements } from "./schema.js";
+import { createSpaceTokenStore } from "./spaceTokens.js";
+//#region src/modules/mysql/index.ts
+/**
+* An account store on MySQL, with the tables it needs.
+*
+* This is the batteries-included half of `createAuth`. A deployment that already has users implements the adapters
+* against its own tables and never comes here; a deployment standing one up gets the schema, the queries and the
+* traps already handled:
+*
+* ```ts
+* const store = await createMysqlStore({ url: process.env.DATABASE_URL });
+*
+* const auth = createAuth({
+*   tokens: { secret, issuer },
+*   adapters: store.authAdapters,
+* });
+* ```
+*
+* It connects to a MySQL server; it does not start one. Where the database lives is a deployment decision and one
+* this cannot make well — a container in development, a managed instance in production, and neither of them
+* something a library should be launching behind your back.
+*/
+var createMysqlStore = async (config) => {
+	const { tablePrefix, autoMigrate = true, log } = config;
+	const tables = resolveTables(tablePrefix);
+	const pool = await createPool(config);
+	const owned = !config.pool;
+	if (autoMigrate) await migrate(pool, tables, {
+		prefix: tablePrefix,
+		adoptExisting: config.adoptExisting,
+		log
+	});
+	return {
+		pool,
+		tables: tableNames(tablePrefix),
+		schemaVersion: SCHEMA_VERSION,
+		authAdapters: createAccountStore(pool, tables),
+		spaceTokenAdapters: createSpaceTokenStore(pool, tables),
+		sessions: createSessionStore(pool, tables),
+		identities: createIdentityStore(pool, tables),
+		admin: createAdmin(pool, tables),
+		uninstall: (options = {}) => dropSchema(pool, tables, {
+			prefix: tablePrefix,
+			force: options.force,
+			log
+		}),
+		close: async () => {
+			if (owned) await pool.end();
+		}
+	};
+};
+/** The DDL, for a deployment whose database user may not run it — see `MysqlConfig.autoMigrate`. */
+var mysqlSchemaStatements = (tablePrefix, fromVersion = 0) => schemaStatements(resolveTables(tablePrefix), fromVersion);
+//#endregion
+export { SCHEMA_VERSION, TABLE_NAMES, createMysqlStore, dropSchema, mysqlSchemaStatements, tableNames };

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

@@ -0,0 +1,3 @@
+import { MysqlConfig } from './config';
+import { Pool } from 'mysql2/promise';
+export declare const createPool: (config: MysqlConfig) => Promise<Pool>;

package/dist/modules/mysql/pool.js

@@ -0,0 +1,88 @@
+//#region src/modules/mysql/pool.ts
+var driver;
+/**
+* `mysql2` is an OPTIONAL peer dependency: this is the only module in the package that speaks to a database, and a
+* deployment bringing its own store should not download a driver to find that out. Loaded dynamically so its absence
+* is a sentence rather than a bare `ERR_MODULE_NOT_FOUND` from a file the reader has never heard of.
+*/
+var loadDriver = async () => {
+	if (driver) return driver;
+	try {
+		driver = await import("mysql2/promise");
+	} catch {
+		throw new Error("@plitzi/sdk-server/mysql needs the `mysql2` driver, which is not installed. Add it with `yarn add mysql2` (or `npm install mysql2`). It is an optional peer dependency so that a deployment bringing its own account store never downloads a database driver it does not use.");
+	}
+	return driver;
+};
+/**
+* The configured connection string, as the driver wants it.
+*
+* Parsed rather than handed to `createPool` as `uri`, and that is not a style choice: **that option is ignored** —
+* only `createPool(uriString)` reads a URL, and that form takes no options. Passing both silently drops the URL and
+* connects to the driver's own defaults, which on a machine that happens to run MySQL locally is a connection to
+* the wrong database rather than an error. Anything unparseable is refused here, where the message can say so.
+*/
+var fromUrl = (url) => {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error("@plitzi/sdk-server/mysql: `url` is not a valid database URL");
+	}
+	const database = parsed.pathname.replace(/^\//, "");
+	if (!parsed.hostname) throw new Error("@plitzi/sdk-server/mysql: `url` names no host");
+	return {
+		host: parsed.hostname,
+		port: parsed.port ? Number(parsed.port) : 3306,
+		user: decodeURIComponent(parsed.username),
+		password: decodeURIComponent(parsed.password),
+		database
+	};
+};
+var createPool = async (config) => {
+	if (config.pool) return config.pool;
+	const { url, host, port, user, password, database, ssl, connectionLimit = 10 } = config;
+	const options = {
+		...url ? fromUrl(url) : {},
+		...host !== void 0 ? { host } : {},
+		...port !== void 0 ? { port } : {},
+		...user !== void 0 ? { user } : {},
+		...password !== void 0 ? { password } : {},
+		...database !== void 0 ? { database } : {},
+		...ssl !== void 0 ? { ssl } : {},
+		connectionLimit,
+		supportBigNumbers: true,
+		bigNumberStrings: false,
+		waitForConnections: true,
+		queueLimit: 0
+	};
+	if (!options.database) throw new Error("@plitzi/sdk-server/mysql: no database was given. Pass `database`, or a `url` that ends in one — a connection with no database selected fails later, on the first query, as a much less obvious error.");
+	const mysql = await loadDriver();
+	if (config.ensureDatabase) await createDatabase(mysql, options);
+	return mysql.createPool(options);
+};
+/**
+* A database name cannot be a bound parameter — it is an identifier, not a value — so it is quoted by hand, and
+* anything that could end the quoting is refused rather than escaped. The set of legal MySQL database names is
+* small and this is all of it.
+*/
+var quoteDatabase = (name) => {
+	if (!/^[A-Za-z0-9_$]+$/.test(name)) throw new Error(`@plitzi/sdk-server/mysql: "${name}" is not a database name that can be created safely. Use letters, digits, underscores and dollar signs, or create the database yourself and leave \`ensureDatabase\` off.`);
+	return `\`${name}\``;
+};
+/** Connects to the SERVER rather than to the database, which is the only way to ask for one that is not there. */
+var createDatabase = async (mysql, options) => {
+	const { database, ...server } = options;
+	const name = quoteDatabase(database ?? "");
+	const connection = await mysql.createConnection(server);
+	try {
+		await connection.query(`CREATE DATABASE IF NOT EXISTS ${name} CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`);
+	} catch (error) {
+		if (error.code === "ER_DBACCESS_DENIED_ERROR") throw new Error(`@plitzi/sdk-server/mysql: the user "${String(options.user)}" may not create the database ${name}. Create it once as an administrator — CREATE DATABASE ${name} CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; — and grant that user rights on it, then turn \`ensureDatabase\` off. Creating databases is not a right an application should hold in the first place.`, { cause: error });
+		throw error;
+	} finally {
+		await connection.end();
+	}
+};
+//#endregion
+export { createPool };

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

@@ -0,0 +1,12 @@
+import { Pool, PoolConnection, ResultSetHeader } from 'mysql2/promise';
+export type Queryable = Pool | PoolConnection;
+/**
+ * The driver boundary, in one place.
+ *
+ * A row arrives as `RowDataPacket` — an index signature over `unknown`, which is all the driver can honestly say
+ * about a result set it has not been told the shape of. Naming that shape is a cast whichever way it is written, so
+ * it is written once, here, rather than at each of the thirty call sites that would otherwise each carry one.
+ */
+export declare const selectRows: <T>(db: Queryable, sql: string, params?: unknown[]) => Promise<T[]>;
+export declare const selectOne: <T>(db: Queryable, sql: string, params?: unknown[]) => Promise<T | undefined>;
+export declare const execute: (db: Queryable, sql: string, params?: unknown[]) => Promise<ResultSetHeader>;

package/dist/modules/mysql/query.js

@@ -0,0 +1,21 @@
+//#region src/modules/mysql/query.ts
+/**
+* The driver boundary, in one place.
+*
+* A row arrives as `RowDataPacket` — an index signature over `unknown`, which is all the driver can honestly say
+* about a result set it has not been told the shape of. Naming that shape is a cast whichever way it is written, so
+* it is written once, here, rather than at each of the thirty call sites that would otherwise each carry one.
+*/
+var selectRows = async (db, sql, params = []) => {
+	const [rows] = await db.query(sql, params);
+	return rows;
+};
+var selectOne = async (db, sql, params = []) => {
+	return (await selectRows(db, sql, params))[0];
+};
+var execute = async (db, sql, params = []) => {
+	const [result] = await db.query(sql, params);
+	return result;
+};
+//#endregion
+export { execute, selectOne, selectRows };

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

@@ -0,0 +1,43 @@
+import { Tables } from './config';
+import { Pool } from 'mysql2/promise';
+/** Adds a column unless it is already there. `definition` is everything after the column name. */
+export declare const addColumn: (table: string, column: string, definition: string) => string[];
+/** Removes a column if it is there. Data goes with it — a step that does this is not reversible. */
+export declare const dropColumn: (table: string, column: string) => string[];
+/** Adds an index unless one of that name exists. `definition` is the parenthesised column list. */
+export declare const addIndex: (table: string, index: string, definition: string) => string[];
+export declare const SCHEMA_VERSION: number;
+/**
+ * Every statement this schema is made of, in order — for a deployment that runs `autoMigrate: false` and applies
+ * DDL through its own migration tool, which is the normal arrangement anywhere the application's database user is
+ * not allowed to alter tables.
+ */
+export declare const schemaStatements: (tables: Tables, fromVersion?: number) => string[];
+/**
+ * Brings the schema up to date, once.
+ *
+ * The advisory lock is not decoration: an all-in-one deployment starts several roles against one database at the
+ * same moment, and without it they race to create the same tables and to bump the same version row. `IF NOT EXISTS`
+ * makes the statements survive that; the version bump would not.
+ */
+export declare const migrate: (pool: Pool, tables: Tables, options: {
+    prefix: string;
+    adoptExisting?: boolean;
+    log?: (message: string) => void;
+}) => Promise<number>;
+/**
+ * Removes this schema and nothing else.
+ *
+ * For a deployment that pointed the store at a database it shares with other things and has now stopped using
+ * `@plitzi/sdk-server` — dropping the database would take the rest of their application with it, and working out
+ * which nine tables were ours is not something anybody should have to do by hand at that moment.
+ *
+ * It drops **only** the names this schema owns, children first so the foreign keys allow it, and it refuses to
+ * touch a database it was never migrated into: without that check, a typo in `tablePrefix` turns this into a tool
+ * that deletes somebody else's `role` table.
+ */
+export declare const dropSchema: (pool: Pool, tables: Tables, options: {
+    prefix: string;
+    force?: boolean;
+    log?: (message: string) => void;
+}) => Promise<string[]>;