@decohere/data-typeorm 0.0.1-dev.126 → 0.0.1-dev.5

package/package.json

@@ -1,25 +1,9 @@
 {
   "name": "@decohere/data-typeorm",
-  "version": "0.0.1-dev.126",
-  "description": "TypeORM and Postgres adapter for @decohere/data: DataSource, migrations and least-privilege roles",
-  "keywords": [
-    "typescript",
-    "typeorm",
-    "postgres",
-    "data-access",
-    "decohere"
-  ],
-  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/data/data-typeorm#readme",
-  "bugs": {
-    "url": "https://github.com/typesmiths/decohere/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/typesmiths/decohere.git",
-    "directory": "projects/data/data-typeorm"
-  },
+  "version": "0.0.1-dev.5",
+  "description": "",
   "license": "ISC",
-  "author": "Typesmiths",
+  "author": "",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -33,11 +17,11 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/core": "0.0.1-dev.126",
-    "@decohere/crucible": "0.0.1-dev.126",
-    "@decohere/data": "0.0.1-dev.126",
-    "@decohere/http": "0.0.1-dev.126",
-    "@decohere/scribe": "0.0.1-dev.126",
+    "@decohere/data": "0.0.1-dev.5",
+    "@decohere/http": "0.0.1-dev.5",
+    "@decohere/di": "0.0.1-dev.5",
+    "@decohere/core": "0.0.1-dev.5",
+    "@decohere/scribe": "0.0.1-dev.5",
     "pg": "^8.16.3",
     "pino-pretty": "^13.1.3",
     "typeorm": "^0.3.31"

package/src/bootstrap-policy.ts

@@ -0,0 +1,84 @@
+import { type ConnectionInfo, DataConfigurationError } from "@decohere/data";
+
+/** True when NODE_ENV says development. Only then may a data source declare `auth: trust`. */
+export function isDevelopmentEnv(nodeEnv: string | undefined = process.env.NODE_ENV): boolean {
+	const env = nodeEnv?.toLowerCase() ?? "";
+	return env === "development" || env === "dev";
+}
+
+function isTrusted(info: ConnectionInfo): boolean {
+	return info.auth === "trust";
+}
+
+function has(value: string | undefined): boolean {
+	return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Check how a data source signs in, in every environment. A server that needs no password is
+ * declared with `auth: trust`, never inferred from a missing password: a password left out by
+ * mistake would otherwise look like a trusted server and fail later, less clearly.
+ */
+export function assertDataSourceAuth(
+	info: ConnectionInfo,
+	nodeEnv: string | undefined = process.env.NODE_ENV,
+): void {
+	const auth = info.auth ?? "password";
+	if (auth !== "password" && auth !== "trust") {
+		throw new DataConfigurationError(
+			`Data source "${info.name}": auth must be "password" or "trust" (got ${JSON.stringify(auth)})`,
+		);
+	}
+	if (auth === "trust") {
+		if (!isDevelopmentEnv(nodeEnv)) {
+			throw new DataConfigurationError(
+				`Data source "${info.name}" sets auth: trust, which is allowed only in development (NODE_ENV is ${JSON.stringify(nodeEnv ?? "")}). A server that trusts every connection belongs on a developer's machine.`,
+			);
+		}
+		return;
+	}
+	if (!has(info.password)) {
+		throw new DataConfigurationError(
+			`Data source "${info.name}" has no password. Set password, or auth: trust for a local server that trusts every connection.`,
+		);
+	}
+}
+
+/**
+ * Decide whether to bootstrap a data source (create its database, roles and schema).
+ *
+ * - `bootstrap: false` → never
+ * - `bootstrap: true` → yes (requires adminUser, and adminPassword unless `auth: trust`)
+ * - omitted → only in development, when those admin credentials are present
+ */
+export function shouldBootstrapDatabase(
+	info: ConnectionInfo,
+	nodeEnv: string | undefined = process.env.NODE_ENV,
+): boolean {
+	if (info.bootstrap === false) {
+		return false;
+	}
+
+	const hasAdmin = has(info.adminUser) && (isTrusted(info) || has(info.adminPassword));
+
+	if (info.bootstrap === true) {
+		if (!hasAdmin) {
+			throw new DataConfigurationError(
+				`Data source "${info.name}": bootstrap requires adminUser and adminPassword (adminPassword may be left out only with auth: trust)`,
+			);
+		}
+		return true;
+	}
+
+	return isDevelopmentEnv(nodeEnv) && hasAdmin;
+}
+
+/** A data source that will be bootstrapped must have every password the bootstrap needs. */
+export function assertBootstrapCredentials(info: ConnectionInfo): void {
+	if (isTrusted(info)) return;
+	if (has(info.migrateUsername) && !has(info.migratePassword)) {
+		throw new DataConfigurationError(
+			`Data source "${info.name}" has migrateUsername but no migratePassword. Set migratePassword, or auth: trust for a local server that trusts every connection.`,
+		);
+	}
+}

package/src/bootstrap.ts

@@ -0,0 +1,76 @@
+import { type ConnectionInfo, DataConfigurationError } from "@decohere/data";
+import {
+	assertBootstrapCredentials,
+	assertDataSourceAuth,
+	shouldBootstrapDatabase,
+} from "./bootstrap-policy.js";
+import { PostgresServerManager } from "./server-manager.js";
+
+export type BootstrapDataSourcesOptions = {
+	/** Shown as `application_name` on the bootstrap connections. */
+	applicationName: string;
+	/** Defaults to `process.env.NODE_ENV`. Decides whether `auth: trust` is allowed. */
+	nodeEnv?: string;
+};
+
+/** What every data source on one server and database must agree on. */
+const SHARED_FIELDS = ["auth", "adminUser", "migrateUsername"] as const;
+
+/**
+ * Check every data source's auth, then create the databases, roles and schemas of those that
+ * bootstrap. Data sources on the same server and database are bootstrapped once, one after the
+ * other: in parallel they would race to create the same database and roles. Running it again
+ * changes nothing.
+ *
+ * For runners and scripts that open their own `DataSource`; `withTypeOrm` calls it for you.
+ */
+export async function bootstrapDataSources(
+	dataSources: readonly ConnectionInfo[],
+	options: BootstrapDataSourcesOptions,
+): Promise<void> {
+	const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV;
+	for (const info of dataSources) assertDataSourceAuth(info, nodeEnv);
+
+	const toBootstrap = dataSources.filter((info) => shouldBootstrapDatabase(info, nodeEnv));
+	for (const info of toBootstrap) assertBootstrapCredentials(info);
+
+	for (const group of byServerAndDatabase(toBootstrap)) {
+		const [first] = group;
+		await using server = new PostgresServerManager(options.applicationName, first);
+		await server.connect();
+		await server.initializeDatabase(first.database);
+		for (const info of group) {
+			await server.provisionRoles({
+				database: info.database,
+				appUsername: info.username,
+				appPassword: info.password,
+				migrateUsername: info.migrateUsername,
+				migratePassword: info.migratePassword,
+				allowAppDdl: info.synchronize === true,
+				schema: info.schema,
+			});
+		}
+	}
+}
+
+function byServerAndDatabase(dataSources: readonly ConnectionInfo[]): ConnectionInfo[][] {
+	const groups = new Map<string, ConnectionInfo[]>();
+	for (const info of dataSources) {
+		const key = `${info.host}:${info.port}/${info.database}`;
+		const group = groups.get(key);
+		if (group == null) {
+			groups.set(key, [info]);
+			continue;
+		}
+		const [first] = group;
+		for (const field of SHARED_FIELDS) {
+			if (info[field] !== first[field]) {
+				throw new DataConfigurationError(
+					`Data sources "${first.name}" and "${info.name}" share database ${key} but set different ${field} (${JSON.stringify(first[field])} and ${JSON.stringify(info[field])})`,
+				);
+			}
+		}
+		group.push(info);
+	}
+	return [...groups.values()];
+}

package/src/data-source.factory.ts

@@ -0,0 +1,51 @@
+import type { ConnectionInfo } from "@decohere/data";
+import type { Constructable } from "@decohere/core/reflection";
+import { DataSource, type Logger } from "typeorm";
+import { ProviderMap } from "./dialect-map.js";
+
+export type ConnectionOptions = ConnectionInfo & {
+	entities: Constructable[];
+	applicationName?: string;
+};
+
+/** Fields used only for bootstrap / privilege provisioning — not TypeORM connection options. */
+function omitProvisionFields(options: ConnectionOptions) {
+	const {
+		adminUser: _adminUser,
+		adminPassword: _adminPassword,
+		migrateUsername: _migrateUsername,
+		migratePassword: _migratePassword,
+		bootstrap: _bootstrap,
+		auth: _auth,
+		seed: _seed,
+		dialect: _dialect,
+		name: _name,
+		...rest
+	} = options;
+	return rest;
+}
+
+/**
+ * A DataSource the container can close: TypeORM's has `destroy()` but no `Symbol.asyncDispose`,
+ * so disposing the app's container used to leave its connections open (#541).
+ */
+export class ManagedDataSource extends DataSource {
+	public async [Symbol.asyncDispose]() {
+		if (this.isInitialized) await this.destroy();
+	}
+}
+
+export class DataSourceFactory {
+	public static create(options: ConnectionOptions, logger: Logger): DataSource {
+		const { applicationName } = options;
+		const { provider } = options;
+		const type = ProviderMap[provider];
+
+		return new ManagedDataSource({
+			type,
+			logger,
+			applicationName,
+			...omitProvisionFields(options),
+		});
+	}
+}

package/src/database-options.ts

@@ -0,0 +1,10 @@
+import type { Constructable } from "@decohere/core/reflection";
+import type { DataSource } from "typeorm";
+
+export type ModuleConfig = {
+	/** The unique identifier for the data source. Required when multiple data sources are configured. */
+	name?: string | symbol;
+	repositories?: Constructable[];
+	entities: Constructable[];
+	seed?: (dataSource: DataSource) => Promise<void>;
+};

package/src/dialect-map.ts

@@ -0,0 +1,12 @@
+import type { Dialect, Provider } from "@decohere/data";
+import type { DatabaseType } from "typeorm";
+
+export const ProviderMap = {
+	postgres: "postgres",
+	mssql: "mssql",
+} satisfies Record<Provider, DatabaseType>;
+
+export const DialectMap = {
+	postgresql: "postgres",
+	tsql: "mssql",
+} satisfies Record<Dialect, DatabaseType>;

package/{es6/src/inject-data-source.js → src/inject-data-source.ts}

@@ -1,20 +1,26 @@
 import { DEFAULT_DATA_SOURCE } from "@decohere/data";
-import { inject } from "@decohere/crucible/decorators";
-/** Default TypeORM DataSource when `withTypeOrm` is used without `name`. */ export const TypeOrmDataSourceToken = Symbol("TypeOrmDataSource");
+import { inject } from "@decohere/di/decorators";
+
+/** Default TypeORM DataSource when `withTypeOrm` is used without `name`. */
+export const TypeOrmDataSourceToken = Symbol("TypeOrmDataSource");
+
 /**
  * Container key for a TypeORM DataSource. Distinct from the unit-of-work key
  * (datasource name / {@link DEFAULT_DATA_SOURCE}) so request-scoped UoW and
  * process-lifetime DataSource can coexist.
- */ export function typeOrmDataSourceToken(name) {
-    if (name == null || name === DEFAULT_DATA_SOURCE) {
-        return TypeOrmDataSourceToken;
-    }
-    return Symbol.for(`decohere:typeorm:datasource:${String(name)}`);
+ */
+export function typeOrmDataSourceToken(name?: string | symbol): symbol {
+	if (name == null || name === DEFAULT_DATA_SOURCE) {
+		return TypeOrmDataSourceToken;
+	}
+	return Symbol.for(`decohere:typeorm:datasource:${String(name)}`);
 }
+
 /**
  * Inject the TypeORM DataSource for process-lifetime (singleton) work.
  * Pass the same `name` as `withTypeOrm({ name })`. Request-scoped persistence
  * should keep using `injectUnitOfWork`.
- */ export function injectDataSource(name) {
-    return inject(typeOrmDataSourceToken(name));
+ */
+export function injectDataSource(name?: string | symbol) {
+	return inject(typeOrmDataSourceToken(name));
 }

package/src/scripts/user.ts

@@ -0,0 +1,234 @@
+/** Postgres identifier: letters, digits, underscore; must start with letter or underscore. */
+const SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function assertSafeSqlIdent(value: string, label: string): string {
+	if (typeof value !== "string" || value.length === 0 || !SAFE_IDENT.test(value)) {
+		throw new Error(
+			`Invalid ${label}: must match ${SAFE_IDENT} (got ${JSON.stringify(value)})`,
+		);
+	}
+	return value;
+}
+
+/** Double-quote a validated identifier for use in DDL. */
+export function quoteIdent(value: string, label = "identifier"): string {
+	const safe = assertSafeSqlIdent(value, label);
+	return `"${safe.replaceAll('"', '""')}"`;
+}
+
+/**
+ * Single-quote a string literal for DDL that cannot take bind parameters
+ * (e.g. CREATE USER … PASSWORD — Postgres rejects PASSWORD $1).
+ */
+export function quoteLiteral(value: string): string {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+
+export type SqlQuery = { text: string; values: unknown[] };
+
+/** Existence check — username bound as $1 (never concatenated). */
+export function roleExistsQuery(username: string): SqlQuery {
+	assertSafeSqlIdent(username, "username");
+	return {
+		text: `SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = $1`,
+		values: [username],
+	};
+}
+
+/**
+ * CREATE USER with password as an escaped SQL literal.
+ * Username is validated + quoted as an identifier (cannot be parameterized in DDL).
+ * Password cannot use bind params in CREATE USER … PASSWORD (Postgres syntax error).
+ *
+ * `password` omitted (undefined) creates a role with no password, for a local dev server that
+ * trusts every connection. An empty string is still an error: that is a typo, not a choice.
+ * Callers decide when no password is allowed (see PostgresServerManager).
+ */
+export function createUserQuery(username: string, password?: string): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const attributes = "NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE";
+	if (password === undefined) {
+		return { text: `CREATE USER ${userIdent} WITH LOGIN ${attributes}`, values: [] };
+	}
+	if (typeof password !== "string" || password.length === 0) {
+		throw new Error("Invalid password: must be a non-empty string");
+	}
+	const passwordLiteral = quoteLiteral(password);
+	return {
+		text: `CREATE USER ${userIdent} WITH LOGIN PASSWORD ${passwordLiteral} ${attributes}`,
+		values: [],
+	};
+}
+
+/** CONNECT only — production runtime app role. */
+export function grantConnectQuery(username: string, database: string): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const dbIdent = quoteIdent(database, "database");
+	return {
+		text: `GRANT CONNECT ON DATABASE ${dbIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+export function grantSchemaUsageQuery(username: string, schema = "public"): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return {
+		text: `GRANT USAGE ON SCHEMA ${schemaIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+/** Needed for TypeORM synchronize (dev only). */
+export function grantSchemaCreateQuery(username: string, schema = "public"): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return {
+		text: `GRANT CREATE ON SCHEMA ${schemaIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+/** The schema, owned by `owner`. Unchanged when it already exists. */
+export function createSchemaQuery(schema: string, owner: string): SqlQuery {
+	const schemaIdent = quoteIdent(schema, "schema");
+	const ownerIdent = quoteIdent(owner, "owner");
+	return {
+		text: `CREATE SCHEMA IF NOT EXISTS ${schemaIdent} AUTHORIZATION ${ownerIdent}`,
+		values: [],
+	};
+}
+
+/**
+ * Whether a role already holds a privilege. Postgres checks that the grantor may grant even when
+ * the grant would change nothing, so bootstrap asks first and grants only what is missing.
+ */
+export function hasDatabasePrivilegeQuery(
+	username: string,
+	database: string,
+	privilege: string,
+): SqlQuery {
+	assertSafeSqlIdent(username, "username");
+	assertSafeSqlIdent(database, "database");
+	return {
+		text: `SELECT has_database_privilege($1, $2, $3) AS granted`,
+		values: [username, database, privilege],
+	};
+}
+
+export function hasSchemaPrivilegeQuery(
+	username: string,
+	schema: string,
+	privilege: string,
+): SqlQuery {
+	assertSafeSqlIdent(username, "username");
+	assertSafeSqlIdent(schema, "schema");
+	return {
+		text: `SELECT has_schema_privilege($1, $2, $3) AS granted`,
+		values: [username, schema, privilege],
+	};
+}
+
+/** Whether `member` already has the privileges of `role` (inherited, or as a superuser). */
+export function hasRolePrivilegesQuery(member: string, role: string): SqlQuery {
+	assertSafeSqlIdent(member, "member");
+	assertSafeSqlIdent(role, "role");
+	return {
+		text: `SELECT pg_has_role($1, $2, 'USAGE') AS granted`,
+		values: [member, role],
+	};
+}
+
+export function databaseOwnerQuery(database: string): SqlQuery {
+	assertSafeSqlIdent(database, "database");
+	return {
+		text: `SELECT pg_get_userbyid(datdba) AS owner FROM pg_catalog.pg_database WHERE datname = $1`,
+		values: [database],
+	};
+}
+
+export function grantSchemaPrivilegesQuery(username: string, schema = "public"): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return {
+		text: `GRANT ALL ON SCHEMA ${schemaIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+export function alterDatabaseOwnerQuery(database: string, username: string): SqlQuery {
+	const dbIdent = quoteIdent(database, "database");
+	const userIdent = quoteIdent(username, "username");
+	return {
+		text: `ALTER DATABASE ${dbIdent} OWNER TO ${userIdent}`,
+		values: [],
+	};
+}
+
+/**
+ * Postgres requires the session user to be a member of the target role to
+ * `ALTER DATABASE … OWNER TO` / `ALTER DEFAULT PRIVILEGES FOR ROLE`.
+ */
+export function grantRoleMembershipQuery(member: string, role: string): SqlQuery {
+	const memberIdent = quoteIdent(member, "member");
+	const roleIdent = quoteIdent(role, "role");
+	return {
+		text: `GRANT ${roleIdent} TO ${memberIdent}`,
+		values: [],
+	};
+}
+
+export function revokeRoleMembershipQuery(member: string, role: string): SqlQuery {
+	const memberIdent = quoteIdent(member, "member");
+	const roleIdent = quoteIdent(role, "role");
+	return {
+		text: `REVOKE ${roleIdent} FROM ${memberIdent}`,
+		values: [],
+	};
+}
+
+/**
+ * Future tables/sequences created by the migration role are usable by the app role (DML only).
+ */
+export function defaultPrivilegesForAppQueries(
+	migrateUsername: string,
+	appUsername: string,
+	schema = "public",
+): SqlQuery[] {
+	const migrateIdent = quoteIdent(migrateUsername, "migrateUsername");
+	const appIdent = quoteIdent(appUsername, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return [
+		{
+			text: `ALTER DEFAULT PRIVILEGES FOR ROLE ${migrateIdent} IN SCHEMA ${schemaIdent} GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${appIdent}`,
+			values: [],
+		},
+		{
+			text: `ALTER DEFAULT PRIVILEGES FOR ROLE ${migrateIdent} IN SCHEMA ${schemaIdent} GRANT USAGE, SELECT ON SEQUENCES TO ${appIdent}`,
+			values: [],
+		},
+	];
+}
+
+/**
+ * @deprecated Prefer discrete query helpers + PostgresServerManager.provisionRoles.
+ * Kept for call-site / pen-test migration: emits create + CONNECT + USAGE (not ALL PRIVILEGES).
+ */
+const createOwnerUser = (username: string, password: string, database: string): SqlQuery => {
+	quoteIdent(username, "username");
+	quoteIdent(database, "database");
+	if (typeof password !== "string" || password.length === 0) {
+		throw new Error("Invalid password: must be a non-empty string");
+	}
+	const create = createUserQuery(username, password);
+	const connect = grantConnectQuery(username, database);
+	const usage = grantSchemaUsageQuery(username);
+	return {
+		text: [create.text, connect.text, usage.text].join(";\n"),
+		values: [],
+	};
+};
+
+const userExists = (username: string): SqlQuery => roleExistsQuery(username);
+
+export const userScripts = { createOwnerUser, userExists };