@opengeni/db 0.2.0

package/src/migrate.ts

@@ -0,0 +1,95 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import postgres from "postgres";
+
+const DEFAULT_DATABASE_URL = "postgres://opengeni:opengeni@127.0.0.1:5432/opengeni";
+
+/** A bare Postgres identifier (schema/role name) safe to interpolate into DDL. */
+function assertIdentifier(name: string, value: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`${name} is not a valid Postgres identifier: ${value}`);
+  }
+  return value;
+}
+
+/**
+ * Apply the OpenGeni SQL migration chain.
+ *
+ * STANDALONE (default, unchanged): `migrate()` / `migrate(databaseUrl)` runs the
+ * whole chain with NO search_path manipulation, so every unqualified
+ * table/index/policy lands in the server default schema (`public`). This is the
+ * byte-for-byte historical behavior — the migration test suite calls
+ * `migrate(DB_URL)` and is unaffected.
+ *
+ * EMBEDDED (Step I, §7.8 runtime/SDK half): pass a `schema` (or set
+ * `OPENGENI_DB_SCHEMA`). The migrate session then `CREATE SCHEMA IF NOT EXISTS`
+ * for both `<schema>` and `opengeni_private`, and sets
+ * `search_path = "<schema>", "opengeni_private", "public"`, so EVERY unqualified
+ * DDL statement lands in the dedicated schema with NO per-statement SQL rewrite
+ * (the SPIKE-1 F1 result). Two things make this work and stay idempotent:
+ *   1. The policy-existence guards in the migration SQL use `current_schema()`
+ *      (not a hardcoded `'public'`) — so a re-run finds the policy it already
+ *      created in `<schema>` and DROP/CREATEs idempotently instead of failing
+ *      with "policy already exists". (This guard substitution is the migrate-
+ *      time enabler for the runtime search_path approach; without it the SDK
+ *      entry point silently fails on re-run — the Fork-6 hazard.)
+ *   2. `public` stays LAST on the path so `gen_random_uuid()` (pgcrypto) and the
+ *      `vector` type — both installed into `public` by 0000 — still resolve. The
+ *      `opengeni_private.*` helpers are always called with an absolute prefix.
+ *
+ * `OPENGENI_DB_SCHEMA` defaults UNSET → `public` → standalone, so the default
+ * binding never regresses.
+ */
+export async function migrate(
+  databaseUrl = process.env.OPENGENI_MIGRATIONS_DATABASE_URL ?? process.env.OPENGENI_DATABASE_URL ?? DEFAULT_DATABASE_URL,
+  schema: string | undefined = process.env.OPENGENI_DB_SCHEMA?.trim() || undefined,
+): Promise<void> {
+  const migrationsDir = join(dirname(fileURLToPath(import.meta.url)), "../drizzle");
+  const files = (await readdir(migrationsDir)).filter((file) => file.endsWith(".sql")).sort();
+  const sql = postgres(databaseUrl, { max: 1 });
+  try {
+    // Serialize concurrent migrate() runs; the session-level lock is released
+    // when the connection closes.
+    await sql`SELECT pg_advisory_lock(727458)`;
+    if (schema) {
+      assertIdentifier("OPENGENI_DB_SCHEMA", schema);
+      await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS "${schema}"`);
+      // opengeni_private is also created by 0001 with an absolute prefix, but the
+      // session search_path must already resolve it for the policy predicates
+      // and the SECURITY DEFINER functions that inherit the caller's path.
+      await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS "opengeni_private"`);
+      await sql.unsafe(`SET search_path = "${schema}", "opengeni_private", "public"`);
+    }
+    await sql.unsafe(`CREATE TABLE IF NOT EXISTS "schema_migrations" ("name" text PRIMARY KEY, "applied_at" timestamptz NOT NULL DEFAULT now())`);
+    const appliedRows = await sql`SELECT "name" FROM "schema_migrations"`;
+    const applied = new Set(appliedRows.map((row) => row.name as string));
+    for (const file of files) {
+      if (applied.has(file)) {
+        continue;
+      }
+      const sqlText = await readFile(join(migrationsDir, file), "utf8");
+      await sql.unsafe(sqlText);
+      await sql`INSERT INTO "schema_migrations" ("name") VALUES (${file}) ON CONFLICT DO NOTHING`;
+    }
+  } finally {
+    await sql.end();
+  }
+}
+
+/**
+ * SDK entry point (Step I): run the migration chain over a host-supplied admin
+ * connection string against an explicit target schema. This is the embedded
+ * topology's named entry — a host calls `runMigrations(adminConnection,
+ * targetSchema)` from its own provisioning code instead of relying on env vars.
+ * `targetSchema` undefined → `public` → standalone behavior. Thin wrapper over
+ * `migrate` so there is one migration engine.
+ */
+export async function runMigrations(adminConnection: string, targetSchema?: string): Promise<void> {
+  await migrate(adminConnection, targetSchema);
+}
+
+if (import.meta.main) {
+  await migrate();
+  console.log("Applied Drizzle SQL migrations.");
+}

package/src/provision-roles.ts

@@ -0,0 +1,198 @@
+import postgres from "postgres";
+import type { RlsStrategy } from "./index";
+
+export type ProvisionResult = {
+  appRole: string | null;
+  temporalRole: string | null;
+  temporalDatabases: string[];
+  schema: string;
+  rlsStrategy: RlsStrategy;
+};
+
+export type ProvisionRolesOptions = {
+  /**
+   * The schema OpenGeni's tables live in. The app-role GRANTs target this
+   * schema + `opengeni_private`. Defaults to `public` (standalone).
+   */
+  targetSchema?: string;
+  /**
+   * RLS posture (Step I). `"force"` (default) provisions the non-owner
+   * `opengeni_app` login role and GRANTs it table DML in the target schema —
+   * the role OpenGeni connects as under FORCE-RLS. `"scoped"` SKIPS the app-role
+   * provisioning entirely: the embedded host runs OpenGeni's queries over a role
+   * IT owns/manages (typically the schema owner), so OpenGeni neither creates
+   * nor grants the `opengeni_app` role. Temporal-role provisioning is unaffected
+   * by strategy.
+   */
+  rlsStrategy?: RlsStrategy;
+  appRole?: string;
+  appPassword?: string;
+  temporalRole?: string;
+  temporalPassword?: string;
+  temporalDatabases?: string[];
+};
+
+/**
+ * SDK entry point (Step I): provision the OpenGeni database roles + grants over
+ * a host-supplied admin connection. This is the named, parameterized form of the
+ * historical env-driven `provision-roles` script (which still works as a CLI via
+ * the `import.meta.main` block at the bottom — it just reads env into these
+ * options).
+ *
+ * STANDALONE (default): `provisionRoles(adminConnection)` with no options →
+ * `targetSchema: "public"`, `rlsStrategy: "force"`, reads `opengeni_app` creds
+ * from env. Byte-for-byte the historical script behavior.
+ *
+ * EMBEDDED: `provisionRoles(adminConnection, { targetSchema, rlsStrategy })` lets
+ * a host provision the app role over a dedicated schema (force) OR skip the
+ * app role entirely and own the connection role itself (scoped).
+ */
+export async function provisionRoles(
+  adminConnection: string,
+  options: ProvisionRolesOptions = {},
+): Promise<ProvisionResult> {
+  const schema = validateIdentifier("targetSchema", options.targetSchema ?? "public");
+  const rlsStrategy: RlsStrategy = options.rlsStrategy ?? "force";
+
+  const appRole = validateIdentifier("appRole", options.appRole ?? (process.env.OPENGENI_APP_DATABASE_USER?.trim() || "opengeni_app"));
+  const appPassword = options.appPassword ?? process.env.OPENGENI_APP_DATABASE_PASSWORD;
+  const temporalRole = validateIdentifier("temporalRole", options.temporalRole ?? (process.env.OPENGENI_TEMPORAL_DATABASE_USER?.trim() || "opengeni_temporal"));
+  const temporalPassword = options.temporalPassword ?? process.env.OPENGENI_TEMPORAL_DATABASE_PASSWORD;
+  const temporalDatabases = (options.temporalDatabases
+    ?? commaSeparated(process.env.OPENGENI_TEMPORAL_DATABASES ?? "temporal,temporal_visibility"))
+    .map((name) => validateIdentifier("temporalDatabases", name));
+
+  const sql = postgres(adminConnection, { max: 1 });
+  try {
+    // FORCE strategy provisions the non-owner app role OpenGeni connects as.
+    // SCOPED strategy: the host owns the connection role; OpenGeni provisions no
+    // app role (skipped here), only the optional Temporal role.
+    let provisionedAppRole: string | null = null;
+    if (rlsStrategy === "force") {
+      if (!appPassword) {
+        throw new Error("OPENGENI_APP_DATABASE_PASSWORD (or appPassword) is required for rlsStrategy 'force'");
+      }
+      await ensureLoginRole(sql, appRole, appPassword);
+      provisionedAppRole = appRole;
+    }
+
+    if (temporalPassword) {
+      await ensureLoginRole(sql, temporalRole, temporalPassword);
+      for (const database of temporalDatabases) {
+        await ensureDatabase(sql, database, temporalRole);
+        await grantTemporalRoleInDatabase(adminConnection, database, temporalRole);
+      }
+    }
+
+    if (rlsStrategy === "force") {
+      await grantAppRoleIfSchemaExists(sql, appRole, schema);
+    }
+
+    return {
+      appRole: provisionedAppRole,
+      temporalRole: temporalPassword ? temporalRole : null,
+      temporalDatabases: temporalPassword ? temporalDatabases : [],
+      schema,
+      rlsStrategy,
+    };
+  } finally {
+    await sql.end();
+  }
+}
+
+async function ensureLoginRole(sql: postgres.Sql, role: string, password: string): Promise<void> {
+  await sql.unsafe(`
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = ${literal(role)}) THEN
+    EXECUTE format('CREATE ROLE %I LOGIN PASSWORD %L', ${literal(role)}, ${literal(password)});
+  ELSE
+    EXECUTE format('ALTER ROLE %I LOGIN PASSWORD %L', ${literal(role)}, ${literal(password)});
+  END IF;
+END $$;
+`);
+}
+
+async function ensureDatabase(sql: postgres.Sql, database: string, owner: string): Promise<void> {
+  const existing = await sql<{ exists: boolean }[]>`
+    select exists(select 1 from pg_database where datname = ${database}) as exists
+  `;
+  if (!existing[0]?.exists) {
+    await sql.unsafe(`CREATE DATABASE ${identifier(database)} OWNER ${identifier(owner)}`);
+  }
+  await sql.unsafe(`GRANT ALL PRIVILEGES ON DATABASE ${identifier(database)} TO ${identifier(owner)}`);
+}
+
+async function grantTemporalRoleInDatabase(adminConnection: string, database: string, role: string): Promise<void> {
+  const databaseUrl = databaseUrlFor(adminConnection, database);
+  const databaseSql = postgres(databaseUrl, { max: 1 });
+  try {
+    await databaseSql.unsafe(`GRANT USAGE, CREATE ON SCHEMA public TO ${identifier(role)}`);
+  } finally {
+    await databaseSql.end();
+  }
+}
+
+/**
+ * Grant the app role table DML in the OpenGeni data schema + EXECUTE on the
+ * `opengeni_private` helper functions. Schema-parameterized (Step I): standalone
+ * passes `public`; embedded passes the dedicated schema. The grants are guarded
+ * on schema existence so provisioning before migrate is a safe no-op.
+ */
+async function grantAppRoleIfSchemaExists(sql: postgres.Sql, role: string, schema: string): Promise<void> {
+  await sql.unsafe(`
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = ${literal(schema)}) THEN
+    EXECUTE format('GRANT USAGE ON SCHEMA %I TO %I', ${literal(schema)}, ${literal(role)});
+    EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA %I TO %I', ${literal(schema)}, ${literal(role)});
+  END IF;
+  IF EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = 'opengeni_private') THEN
+    EXECUTE format('GRANT USAGE ON SCHEMA opengeni_private TO %I', ${literal(role)});
+    EXECUTE format('GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA opengeni_private TO %I', ${literal(role)});
+  END IF;
+END $$;
+`);
+}
+
+function commaSeparated(value: string): string[] {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+function validateIdentifier(name: string, value: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`${name} contains an invalid Postgres identifier: ${value}`);
+  }
+  return value;
+}
+
+function identifier(value: string): string {
+  return `"${value.replace(/"/g, "\"\"")}"`;
+}
+
+function literal(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function databaseUrlFor(value: string, database: string): string {
+  const url = new URL(value);
+  url.pathname = `/${database}`;
+  return url.toString();
+}
+
+// CLI form (unchanged behavior): read env into the SDK options and run. This is
+// what `bun src/provision-roles.ts` / the `provision-roles` package script
+// invokes — standalone byte-for-byte the historical script (public schema,
+// force strategy, env-driven creds).
+if (import.meta.main) {
+  const adminUrl = process.env.OPENGENI_MIGRATIONS_DATABASE_URL
+    ?? process.env.OPENGENI_DATABASE_ADMIN_URL
+    ?? process.env.OPENGENI_DATABASE_URL;
+  if (!adminUrl) {
+    throw new Error("OPENGENI_MIGRATIONS_DATABASE_URL, OPENGENI_DATABASE_ADMIN_URL, or OPENGENI_DATABASE_URL is required");
+  }
+  const result = await provisionRoles(adminUrl, {
+    ...(process.env.OPENGENI_DB_SCHEMA?.trim() ? { targetSchema: process.env.OPENGENI_DB_SCHEMA.trim() } : {}),
+  });
+  console.log(JSON.stringify(result, null, 2));
+}