@indigoai-us/hq-cli 5.60.0 → 5.62.0

package/src/lib/db/remote-sql.test.ts

@@ -0,0 +1,32 @@
+/**
+ * Remote SQL helper tests (US-010).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { runRemoteSql } from "./remote-sql.js";
+
+describe("runRemoteSql", () => {
+  it("returns rows without connection string in output", async () => {
+    const result = await runRemoteSql({
+      company: "indigo",
+      sql: "SELECT 1 AS n",
+      getConnectionConfig: async () => ({ host: "mock", mock: true }),
+      execute: async () => [{ n: 1 }],
+    });
+    expect(result.rows).toEqual([{ n: 1 }]);
+    expect(JSON.stringify(result)).not.toMatch(/postgres:\/\//i);
+  });
+
+  it("clear error when no remote binding", async () => {
+    await expect(
+      runRemoteSql({
+        company: "indigo",
+        sql: "SELECT 1",
+        getConnectionConfig: async () => {
+          throw new Error("no remote binding");
+        },
+      }),
+    ).rejects.toThrow(/provision/i);
+  });
+});

package/src/lib/db/remote-sql.ts

@@ -0,0 +1,62 @@
+/**
+ * Remote SQL via secrets-exec style injection (US-010).
+ *
+ * Connection string never appears in argv, logs, or stdout.
+ * Local remains default when --remote is absent (handled by command layer).
+ */
+
+export interface RemoteSqlOptions {
+  company: string;
+  sql: string;
+  /** Injected secret material — never log. */
+  getConnectionConfig: () => Promise<Record<string, unknown>>;
+  /** Execute against remote; tests inject mock. */
+  execute?: (
+    config: Record<string, unknown>,
+    sql: string,
+  ) => Promise<Record<string, unknown>[]>;
+}
+
+export interface RemoteSqlResult {
+  rows: Record<string, unknown>[];
+}
+
+function assertNoLeak(label: string, value: unknown): void {
+  const s = typeof value === "string" ? value : JSON.stringify(value);
+  if (/postgres:\/\//i.test(s) || /postgresql:\/\//i.test(s)) {
+    throw new Error(`${label}: connection string leak blocked`);
+  }
+}
+
+/**
+ * Run SQL on remote tier using vault-bound credentials.
+ */
+export async function runRemoteSql(
+  opts: RemoteSqlOptions,
+): Promise<RemoteSqlResult> {
+  if (!opts.sql?.trim()) {
+    throw new Error("SQL statement is required");
+  }
+
+  let config: Record<string, unknown>;
+  try {
+    config = await opts.getConnectionConfig();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : "no remote binding";
+    throw new Error(
+      `remote SQL unavailable: ${msg}. Run \`hq db provision --company ${opts.company}\` first.`,
+    );
+  }
+
+  assertNoLeak("connection config", config);
+
+  if (!opts.execute) {
+    throw new Error(
+      "remote SQL executor not configured in this build (adapter pending live DSQL wire-up)",
+    );
+  }
+
+  const rows = await opts.execute(config, opts.sql);
+  assertNoLeak("remote sql rows", rows);
+  return { rows };
+}

package/src/lib/db/sql.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Local SQL execution tests (vault-databases US-004).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { openLocalDb } from "./local.js";
+import { resolveLocalDbPath } from "./paths.js";
+import {
+  formatSqlResult,
+  resolveSqlDbPath,
+  runLocalSql,
+} from "./sql.js";
+
+const tempHomes: string[] = [];
+
+function makeTempHome(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-db-sql-"));
+  tempHomes.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempHomes.length > 0) {
+    const dir = tempHomes.pop();
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("runLocalSql", () => {
+  it("SELECT happy path returns rows as jsonl-friendly records", () => {
+    const home = makeTempHome();
+    const db = openLocalDb("alpha", { home });
+    db.exec("CREATE TABLE smoke (id INTEGER PRIMARY KEY, name TEXT)");
+    db.prepare("INSERT INTO smoke (name) VALUES (?)").run("hello");
+    db.close();
+
+    const result = runLocalSql({
+      company: "alpha",
+      home,
+      sql: "SELECT id, name FROM smoke ORDER BY id",
+    });
+
+    expect(result.rows).toEqual([{ id: 1, name: "hello" }]);
+    expect(formatSqlResult(result, "jsonl")).toContain('"name":"hello"');
+    expect(JSON.stringify(result)).not.toMatch(/postgres:\/\//i);
+  });
+
+  it("blocks write SQL without --write", () => {
+    const home = makeTempHome();
+    openLocalDb("alpha", { home }).close();
+
+    expect(() =>
+      runLocalSql({
+        company: "alpha",
+        home,
+        sql: "CREATE TABLE t (id INTEGER)",
+      }),
+    ).toThrow(/read-only/i);
+  });
+
+  it("denies cross-company path override by default", () => {
+    const home = makeTempHome();
+    openLocalDb("alpha", { home }).close();
+    openLocalDb("beta", { home }).close();
+
+    const betaPath = resolveLocalDbPath("beta", { home });
+
+    expect(() =>
+      resolveSqlDbPath({
+        company: "alpha",
+        home,
+        sql: "SELECT 1",
+        dbPathOverride: betaPath,
+      }),
+    ).toThrow(/denied/i);
+
+    expect(() =>
+      runLocalSql({
+        company: "alpha",
+        home,
+        sql: "SELECT 1",
+        dbPathOverride: betaPath,
+      }),
+    ).toThrow(/denied/i);
+  });
+
+  it("rejects ATTACH even with --write (tenant isolation)", () => {
+    const home = makeTempHome();
+    openLocalDb("alpha", { home }).close();
+    const betaPath = resolveLocalDbPath("beta", { home });
+
+    expect(() =>
+      runLocalSql({
+        company: "alpha",
+        home,
+        write: true,
+        sql: `ATTACH DATABASE '${betaPath}' AS other`,
+      }),
+    ).toThrow(/ATTACH|tenant isolation/i);
+  });
+});

package/src/lib/db/sql.ts

@@ -0,0 +1,192 @@
+/**
+ * Local SQL execution helpers (vault-databases US-004).
+ *
+ * Company scope is path-bound via resolveLocalDbPath — callers must pass the
+ * resolved company slug from HQ session/flags. Path overrides that open
+ * another company's DB are denied unless an explicit dangerous flag is set.
+ */
+
+import Database from "better-sqlite3";
+
+import type { LocalDb } from "./local.js";
+import { openLocalDb } from "./local.js";
+import {
+  normalizeCompanySlugForLocalDb,
+  resolveLocalDbDir,
+  resolveLocalDbPath,
+  type LocalDbPathEnv,
+} from "./paths.js";
+
+export interface SqlRunOptions extends LocalDbPathEnv {
+  company: string;
+  sql: string;
+  /** Allow INSERT/UPDATE/DELETE/DDL. Default false (read-only). */
+  write?: boolean;
+  /**
+   * Dangerous: open an absolute DB path instead of the company canonical path.
+   * Denied unless allowCrossCompanyPath is true.
+   */
+  dbPathOverride?: string;
+  /** Explicit dangerous flag to open a non-canonical local DB path. Default false. */
+  allowCrossCompanyPath?: boolean;
+  /** Output format */
+  format?: "jsonl" | "table";
+}
+
+export interface SqlRunResult {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  changes: number;
+  readonly: boolean;
+}
+
+const WRITE_PATTERN =
+  /^\s*(INSERT|UPDATE|DELETE|REPLACE|CREATE|DROP|ALTER|TRUNCATE|REINDEX|VACUUM|BEGIN|COMMIT|ROLLBACK)\b/i;
+
+/** Always forbidden — opens other files/DBs and breaks company path isolation. */
+const FORBIDDEN_SQL_PATTERN =
+  /\b(ATTACH|DETACH|LOAD_EXTENSION)\b/i;
+
+export function stripSqlNoise(sql: string): string {
+  return sql
+    .replace(/^\s*--[^\n]*\n/gm, "")
+    .replace(/^\s*\/\*[\s\S]*?\*\//gm, "")
+    .trim();
+}
+
+export function isWriteSql(sql: string): boolean {
+  return WRITE_PATTERN.test(stripSqlNoise(sql));
+}
+
+/**
+ * Statements that must never run via `hq db sql`, even with --write.
+ * ATTACH/DETACH would let a company-scoped session open another company's
+ * vault.db by absolute path (category-1 isolation).
+ */
+export function assertSqlAllowed(sql: string): void {
+  const stripped = stripSqlNoise(sql);
+  if (FORBIDDEN_SQL_PATTERN.test(stripped)) {
+    throw new Error(
+      "ATTACH/DETACH/LOAD_EXTENSION are not allowed via hq db sql (tenant isolation); use the company-canonical local path only",
+    );
+  }
+}
+
+/**
+ * Resolve which file path to open, enforcing company isolation by default.
+ */
+export function resolveSqlDbPath(opts: SqlRunOptions): string {
+  const company = normalizeCompanySlugForLocalDb(opts.company);
+  const canonical = resolveLocalDbPath(company, opts);
+
+  if (!opts.dbPathOverride) {
+    return canonical;
+  }
+
+  if (opts.dbPathOverride === canonical) {
+    return canonical;
+  }
+
+  if (!opts.allowCrossCompanyPath) {
+    throw new Error(
+      "cross-company or path override denied: refusing to open a non-canonical local DB path without --allow-cross-company-path (dangerous)",
+    );
+  }
+
+  return opts.dbPathOverride;
+}
+
+function openByPath(dbPath: string): LocalDb {
+  const db = new Database(dbPath);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  return db;
+}
+
+/**
+ * Execute SQL against the company local vault DB.
+ */
+export function runLocalSql(opts: SqlRunOptions): SqlRunResult {
+  const sql = opts.sql?.trim();
+  if (!sql) {
+    throw new Error("SQL statement is required");
+  }
+
+  assertSqlAllowed(sql);
+
+  const writeRequested = !!opts.write;
+  if (isWriteSql(sql) && !writeRequested) {
+    throw new Error(
+      "write/DDL statement blocked in read-only mode; pass --write to allow (prefer hq db migrate for schema changes)",
+    );
+  }
+
+  const dbPath = resolveSqlDbPath(opts);
+  const usingCanonical =
+    !opts.dbPathOverride || opts.dbPathOverride === resolveLocalDbPath(opts.company, opts);
+
+  const db: LocalDb = usingCanonical
+    ? openLocalDb(opts.company, opts)
+    : openByPath(dbPath);
+
+  try {
+    if (!writeRequested) {
+      db.pragma("query_only = ON");
+    }
+
+    const stmt = db.prepare(sql);
+    if (stmt.reader) {
+      const rows = stmt.all() as Record<string, unknown>[];
+      const columns =
+        rows.length > 0
+          ? Object.keys(rows[0] as object)
+          : stmt.columns().map((c) => c.name);
+      return {
+        columns,
+        rows,
+        changes: 0,
+        readonly: !writeRequested,
+      };
+    }
+
+    const info = stmt.run();
+    return {
+      columns: ["changes", "lastInsertRowid"],
+      rows: [
+        {
+          changes: info.changes,
+          lastInsertRowid: Number(info.lastInsertRowid),
+        },
+      ],
+      changes: info.changes,
+      readonly: !writeRequested,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export function formatSqlResult(
+  result: SqlRunResult,
+  format: "jsonl" | "table" = "jsonl",
+): string {
+  if (format === "jsonl") {
+    if (result.rows.length === 0) {
+      return JSON.stringify({ columns: result.columns, rows: 0 });
+    }
+    return result.rows.map((r) => JSON.stringify(r)).join("\n");
+  }
+
+  const cols = result.columns;
+  if (cols.length === 0) return "(no columns)";
+  const header = cols.join("\t");
+  const body = result.rows
+    .map((r) => cols.map((c) => String(r[c] ?? "")).join("\t"))
+    .join("\n");
+  return body ? `${header}\n${body}` : header;
+}
+
+/** Test helper: company dir for isolation assertions. */
+export function companyLocalDbDir(company: string, env?: LocalDbPathEnv): string {
+  return resolveLocalDbDir(company, env);
+}