postgresai 0.15.0-dev.1 → 0.15.0-dev.11

package/lib/init.ts

@@ -87,7 +87,7 @@ export type AdminConnection = {
 /**
  * Check if an error indicates SSL negotiation failed and fallback to non-SSL should be attempted.
  * This mimics libpq's sslmode=prefer behavior.
- * 
+ *
  * IMPORTANT: This should NOT match certificate errors (expired, invalid, self-signed)
  * as those are real errors the user needs to fix, not negotiation failures.
  */
@@ -127,8 +127,10 @@ export async function connectWithSslFallback(
   verbose?: boolean
 ): Promise<{ client: PgClient; usedSsl: boolean }> {
   const tryConnect = async (config: PgClientConfig): Promise<PgClient> => {
-    const client = new ClientClass(config);
+    const client = new ClientClass({ ...config, connectionTimeoutMillis: 10_000 } as any);
     await client.connect();
+    // Set a default statement timeout to prevent runaway queries
+    await client.query("SET statement_timeout = '30s'");
     return client;
   };
 
@@ -149,7 +151,7 @@ export async function connectWithSslFallback(
     }
 
     if (verbose) {
-      console.log("SSL connection failed, retrying without SSL...");
+      console.error("SSL connection failed, retrying without SSL...");
     }
 
     // Retry without SSL
@@ -454,8 +456,18 @@ export function resolveAdminConnection(opts: {
   return { clientConfig: cfg, display: describePgConfig(cfg), sslFallbackEnabled: true };
 }
 
+/**
+ * Generate a cryptographically secure random password for the monitoring role.
+ *
+ * Encoding note — bytes vs output length:
+ *   - hex:      N bytes → 2N characters  (24 bytes → 48 hex chars)
+ *   - base64:   N bytes → ⌈4N/3⌉ chars   (24 bytes → 32 base64url chars, no padding)
+ *
+ * We use base64url (RFC 4648 §5) because it is shorter than hex and safe in URLs,
+ * connection strings, and shell variables without quoting.
+ */
 function generateMonitoringPassword(): string {
-  // URL-safe and easy to copy/paste; 24 bytes => 32 base64url chars (no padding).
+  // 24 random bytes → 32 base64url characters (no padding).
   // Note: randomBytes() throws on failure; we add a tiny sanity check for unexpected output.
   const password = randomBytes(24).toString("base64url");
   if (password.length < 30) {
@@ -659,6 +671,36 @@ export type VerifyInitResult = {
   missingOptional: string[];
 };
 
+/** A single permission check result from the preflight query. */
+export type PermissionCheckRow = {
+  permission_name: string;
+  status: "required" | "optional";
+  /**
+   * Whether the permission is granted.
+   * - `true`  — permission is granted
+   * - `false` — permission is explicitly denied
+   * - `null`  — check was skipped (e.g., object does not exist, so the privilege
+   *             check is inapplicable — such as SELECT on a view that hasn't been created)
+   */
+  granted: boolean | null;
+  fix_command: string | null;
+};
+
+/**
+ * Result of the preflight permission check for the current DB user.
+ *
+ * - `ok` is `true` when `missingRequired` is empty.
+ * - `rows` contains every check (for inspection / logging).
+ * - `missingRequired` / `missingOptional` are filtered subsets of `rows`
+ *   where the permission is not granted (`granted !== true`).
+ */
+export type PreflightPermissionResult = {
+  ok: boolean;
+  rows: PermissionCheckRow[];
+  missingRequired: PermissionCheckRow[];
+  missingOptional: PermissionCheckRow[];
+};
+
 export type UninitPlan = {
   monitoringUser: string;
   database: string;
@@ -813,7 +855,12 @@ export async function verifyInitSetup(params: {
       missingRequired.push("USAGE on schema postgres_ai");
     }
 
-    const viewExistsRes = await params.client.query("select to_regclass('postgres_ai.pg_statistic') is not null as ok");
+    const viewExistsRes = await params.client.query(`
+      select case
+        when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+        else to_regclass('postgres_ai.pg_statistic') is not null
+      end as ok
+    `);
     if (!viewExistsRes.rows?.[0]?.ok) {
       missingRequired.push("view postgres_ai.pg_statistic exists");
     } else {
@@ -936,4 +983,149 @@ export async function verifyInitSetup(params: {
   }
 }
 
+/**
+ * Check that the currently connected DB user has sufficient permissions for
+ * monitoring operations. Returns structured results with fix commands.
+ *
+ * Required permissions cause startup to fail; optional ones produce warnings.
+ *
+ * @param client  An already-connected PostgreSQL client.
+ * @returns       A {@link PreflightPermissionResult} with per-check rows and
+ *                filtered `missingRequired` / `missingOptional` arrays.
+ * @throws        Propagates database errors (network, permission denied on catalog
+ *                tables, timeout) to the caller.
+ */
+export async function checkCurrentUserPermissions(
+  client: PgClient
+): Promise<PreflightPermissionResult> {
+  const sql = `
+    with permission_checks as (
+      select
+        format('connect on database %I', current_database()) as permission_name,
+        'required' as status,
+        has_database_privilege(current_user, current_database(), 'connect') as granted
+
+      union all
+
+      select
+        'pg_monitor role membership' as permission_name,
+        'required' as status,
+        -- CASE guarantees evaluation order: pg_has_role() is only called if the
+        -- pg_monitor role exists, avoiding ERROR on PostgreSQL < 10 or when dropped.
+        case
+          when not exists (select from pg_roles where rolname = 'pg_monitor')
+          then false
+          else pg_has_role(current_user, 'pg_monitor', 'member')
+        end as granted
+
+      union all
+
+      select
+        'select on pg_catalog.pg_index' as permission_name,
+        'required' as status,
+        has_table_privilege(current_user, 'pg_catalog.pg_index', 'select') as granted
+
+      union all
+
+      select
+        'postgres_ai.pg_statistic view exists' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as granted
+
+      union all
+
+      select
+        'select on postgres_ai.pg_statistic' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          when to_regclass('postgres_ai.pg_statistic') is null then null
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
+        end as granted
+    )
+    select
+      permission_name,
+      status,
+      granted,
+      case
+        when status = 'required' and not coalesce(granted, false) then
+          case
+            when permission_name like 'connect%' then
+              format('grant connect on database %I to %I;', current_database(), current_user)
+            when permission_name = 'pg_monitor role membership' then
+              format('grant pg_monitor to %I;', current_user)
+            when permission_name like 'select on pg_catalog.pg_index' then
+              format('grant select on pg_catalog.pg_index to %I;', current_user)
+          end
+        when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
+          '-- create postgres_ai.pg_statistic view (see setup script)'
+        when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
+          format('grant select on postgres_ai.pg_statistic to %I;', current_user)
+        else null
+      end as fix_command
+    from permission_checks
+    order by
+      case status when 'required' then 1 else 2 end,
+      permission_name;
+  `;
+
+  const res = await client.query(sql);
+  const rows: PermissionCheckRow[] = res.rows;
+
+  // Required: treat null (skipped) as not-granted — fail safe.
+  // Optional: only explicit false counts as missing; null means the check was
+  //           skipped (e.g., view doesn't exist) and is not actionable.
+  const missingRequired = rows.filter((r) => r.status === "required" && r.granted !== true);
+  const missingOptional = rows.filter((r) => r.status === "optional" && r.granted === false);
+
+  return {
+    ok: missingRequired.length === 0,
+    rows,
+    missingRequired,
+    missingOptional,
+  };
+}
+
+/**
+ * Format permission check results into user-facing error/warning lines.
+ *
+ * @returns An object with `warnings` (for optional misses), `errors` (for
+ *          required misses including fix SQL), and `failed` (whether required
+ *          permissions are missing).
+ */
+export function formatPermissionCheckMessages(result: PreflightPermissionResult): {
+  failed: boolean;
+  warnings: string[];
+  errors: string[];
+} {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  for (const row of result.missingOptional) {
+    const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
+    warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
+  }
 
+  if (!result.ok) {
+    errors.push("Error: the database user is missing required permissions.\n");
+    errors.push("Missing permissions:");
+    for (const row of result.missingRequired) {
+      errors.push(`  - ${row.permission_name}`);
+    }
+    const fixes = result.missingRequired
+      .map((r) => r.fix_command)
+      .filter(Boolean);
+    if (fixes.length > 0) {
+      errors.push("\nTo fix, run the following as a superuser:\n");
+      for (const fix of fixes) {
+        errors.push(`  ${fix}`);
+      }
+    }
+    errors.push("\nAlternatively, run 'postgresai prepare-db' to set up permissions automatically.");
+  }
+
+  return { failed: !result.ok, warnings, errors };
+}

package/lib/instances.ts

@@ -0,0 +1,245 @@
+/**
+ * Helpers for managing instances.yml (the pgwatch monitoring target list)
+ * and for opening pg connections that honor libpq sslmode semantics.
+ *
+ * These helpers exist as a single source of truth so that `mon targets
+ * add/remove/test` and `mon local-install` (which has its own inline copies
+ * of the same logic) stay consistent — and so unit tests exercise the same
+ * code path the CLI actually runs.
+ */
+
+import * as fs from "fs";
+import * as yaml from "js-yaml";
+import { parse as parseConnString } from "pg-connection-string";
+import type { ClientConfig } from "pg";
+
+export interface Instance {
+  name: string;
+  conn_str?: string;
+  preset_metrics?: string;
+  custom_metrics?: any;
+  is_enabled?: boolean;
+  group?: string;
+  custom_tags?: Record<string, any>;
+}
+
+export class InstancesParseError extends Error {
+  constructor(file: string, cause: unknown) {
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
+    super(`Failed to parse ${file}: ${causeMsg}`);
+    this.name = "InstancesParseError";
+  }
+}
+
+/**
+ * Read instances.yml as an array of Instance.
+ *
+ * Returns `[]` for a missing/empty file (this is normal — fresh installs and
+ * just-after-`remove` states). Throws InstancesParseError on a corrupted file
+ * so callers can surface the corruption to the user instead of silently
+ * overwriting it (the previous append-text behavior could erase several
+ * targets — including their conn_strs with credentials — if the file had a
+ * partial write or hand-edit problem).
+ */
+export function loadInstances(file: string): Instance[] {
+  if (!fs.existsSync(file)) return [];
+  if (fs.lstatSync(file).isDirectory()) return [];
+  const text = fs.readFileSync(file, "utf8");
+  if (text.trim() === "") return [];
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(text);
+  } catch (err) {
+    throw new InstancesParseError(file, err);
+  }
+  if (parsed === null || parsed === undefined) return [];
+  if (!Array.isArray(parsed)) {
+    throw new InstancesParseError(file, "expected a YAML list at the document root");
+  }
+  return parsed as Instance[];
+}
+
+export function buildInstance(name: string, connStr: string): Instance {
+  return {
+    name,
+    conn_str: connStr,
+    preset_metrics: "full",
+    custom_metrics: null,
+    is_enabled: true,
+    group: "default",
+    custom_tags: {
+      env: "production",
+      cluster: "default",
+      node_name: name,
+      // Sed-substituted placeholder by config/scripts/generate-pgwatch-sources.sh.
+      // js-yaml emits this unquoted on dump (~ is only special at the start of a
+      // scalar in the right context); sed s/~sink_type~/.../g still hits it as
+      // raw text regardless.
+      sink_type: "~sink_type~",
+    },
+  };
+}
+
+/**
+ * Parse → mutate → serialize: load existing list, append, dump back.
+ *
+ * Replaces the previous text-append code path which corrupted instances.yml
+ * after `remove` had left the empty marker `[]` in the file (the append
+ * produced two YAML documents in one file → parse error on every subsequent
+ * read).
+ *
+ * Replaces files where the previous code path treated the directory created
+ * by Docker's bind-mount-into-missing-path as a target.
+ */
+export function addInstanceToFile(file: string, instance: Instance): void {
+  if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+    fs.rmSync(file, { recursive: true, force: true });
+  }
+  const existing = loadInstances(file);
+  if (existing.some((i) => i.name === instance.name)) {
+    throw new Error(`Monitoring target '${instance.name}' already exists`);
+  }
+  existing.push(instance);
+  fs.writeFileSync(file, yaml.dump(existing), "utf8");
+}
+
+/**
+ * Remove a named instance from the file. Returns true if removed.
+ */
+export function removeInstanceFromFile(file: string, name: string): boolean {
+  const instances = loadInstances(file);
+  const filtered = instances.filter((i) => i.name !== name);
+  if (filtered.length === instances.length) return false;
+  fs.writeFileSync(file, yaml.dump(filtered), "utf8");
+  return true;
+}
+
+/**
+ * Extract `sslmode` (lowercased) from a postgresql:// URL. Returns `""` for
+ * unset or unparseable.
+ */
+export function extractSslmode(connStr: string): string {
+  try {
+    return (new URL(connStr).searchParams.get("sslmode") || "").toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Map libpq sslmode values to node-postgres' `ssl` option.
+ *
+ * libpq:                     node-postgres ssl:
+ *   disable                    false
+ *   allow / prefer / require   { rejectUnauthorized: false }   (encrypt, no chain check)
+ *   verify-ca                  { rejectUnauthorized: true, checkServerIdentity: () => undefined }
+ *   verify-full                { rejectUnauthorized: true }
+ *   no-verify (pg extension)   { rejectUnauthorized: false }
+ *
+ * Default for unset: prefer-like → no chain verification, matches what
+ * pgwatch (Go pgx) does and what users pass to psql every day.
+ */
+export type SslOption = false | { rejectUnauthorized: boolean; checkServerIdentity?: () => undefined };
+
+export function sslOptionFromConnString(connStr: string): SslOption {
+  return sslOptionFromSslmode(extractSslmode(connStr));
+}
+
+function sslOptionFromSslmode(sslmode: string): SslOption {
+  switch (sslmode) {
+    case "disable":
+      return false;
+    case "verify-ca":
+      return { rejectUnauthorized: true, checkServerIdentity: () => undefined };
+    case "verify-full":
+      return { rejectUnauthorized: true };
+    case "allow":
+    case "prefer":
+    case "require":
+    case "no-verify":
+    case "":
+    default:
+      return { rejectUnauthorized: false };
+  }
+}
+
+/**
+ * The set of sslmode values for which we DO NOT verify the certificate chain.
+ * Exposed so callers can warn users about the lax security posture.
+ */
+export const LAX_SSLMODES = new Set(["", "allow", "prefer", "require"]);
+
+export function isLaxSslmode(sslmode: string): boolean {
+  return LAX_SSLMODES.has(sslmode);
+}
+
+/**
+ * Print a stderr warning when the connection string uses an sslmode that
+ * skips certificate-chain verification. Centralises the message so the
+ * three Client-construction sites stay consistent.
+ */
+export function warnIfLaxSslmode(connStr: string): void {
+  const sslmode = extractSslmode(connStr);
+  if (!isLaxSslmode(sslmode)) return;
+  const shown = sslmode || "(unset)";
+  console.error(
+    `⚠ sslmode=${shown}: TLS chain is NOT verified (matches libpq/psql semantics). ` +
+      `Use sslmode=verify-full for full chain+hostname verification.`,
+  );
+}
+
+/**
+ * Build a `pg.Client` config from a connection string that ACTUALLY honors
+ * libpq sslmode semantics.
+ *
+ * This is non-trivial because node-postgres' `Client` constructor, given a
+ * `connectionString`, runs `Object.assign({}, config, parse(connectionString))`
+ * — meaning the parsed sslmode-derived `ssl` value REPLACES any explicit
+ * `ssl` you passed alongside `connectionString`. So setting
+ * `{ connectionString, ssl: { rejectUnauthorized: false } }` does not work
+ * when the URL contains `sslmode=require` (the parsed value `{}` wins, and
+ * `{}` defaults to chain verification → "self-signed certificate in
+ * certificate chain" against managed Postgres).
+ *
+ * The fix: parse the URL ourselves, pass discrete host/port/user/etc., and
+ * include our explicit `ssl` — never pass `connectionString` so nothing
+ * overrides us.
+ *
+ * We strip `sslmode` from the URL before handing it to `pg-connection-string`'s
+ * `parse()` so that:
+ *   1. its `process.emitWarning("SECURITY WARNING: SSL modes 'prefer'/'require'/
+ *      'verify-ca' are treated as aliases for 'verify-full'…")` doesn't fire
+ *      on every CLI invocation against a Supabase-shaped URL, and
+ *   2. its `verify-ca` compatibility branch doesn't *throw* on us (requires
+ *      sslrootcert which we don't have).
+ *
+ * We don't use the parser's `ssl` output anyway — we compute our own from
+ * `sslOptionFromSslmode(extractSslmode(originalConnStr))` — so removing the
+ * sslmode parameter before parsing is a no-op for the fields we actually use.
+ */
+export function buildClientConfig(
+  connStr: string,
+  extra: { connectionTimeoutMillis?: number } = {},
+): ClientConfig {
+  const sslmode = extractSslmode(connStr);
+  const parsed = parseConnString(withoutSslmode(connStr));
+  return {
+    host: parsed.host || undefined,
+    port: parsed.port ? Number(parsed.port) : undefined,
+    user: parsed.user,
+    password: parsed.password,
+    database: parsed.database || undefined,
+    ssl: sslOptionFromSslmode(sslmode),
+    ...extra,
+  };
+}
+
+function withoutSslmode(connStr: string): string {
+  try {
+    const u = new URL(connStr);
+    u.searchParams.delete("sslmode");
+    return u.toString();
+  } catch {
+    return connStr;
+  }
+}