@nifrajs/cli 3.5.0 → 4.0.0

package/src/contracts.ts

@@ -6,6 +6,8 @@ import {
   snapshotProjectEvidence,
 } from "@nifrajs/core/evidence"
 import type { ReflectedRoute } from "@nifrajs/core/reflection"
+import { BACKEND_APP_FILE } from "./app-files.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 
 export interface ContractDigest {
   readonly request: string
@@ -26,18 +28,58 @@ function recordOf(value: unknown): Record<string, unknown> | undefined {
     : undefined
 }
 
-function canonical(value: unknown, key?: string): unknown {
-  if (["description", "title", "default", "example", "examples"].includes(key ?? ""))
-    return undefined
+/** Annotation keywords: editing one is not a contract change. */
+const ANNOTATIONS: ReadonlySet<string> = new Set([
+  "description",
+  "title",
+  "default",
+  "example",
+  "examples",
+])
+/** Keywords whose value maps user-chosen names to schemas, so a key there is a name, never a keyword. */
+const NAME_MAPS: ReadonlySet<string> = new Set([
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "dependentRequired",
+  "dependencies",
+])
+/** Keywords whose value is instance data, compared whole. */
+const DATA: ReadonlySet<string> = new Set(["const", "enum"])
+
+function sortedRecord(
+  record: Record<string, unknown>,
+  entry: (name: string, item: unknown) => unknown,
+): Record<string, unknown> {
+  const entries: Array<[string, unknown]> = []
+  for (const name of Object.keys(record).sort()) {
+    const item = entry(name, record[name])
+    if (item !== undefined) entries.push([name, item])
+  }
+  // `fromEntries` defines each key, where an assignment would run the `__proto__` setter instead.
+  return Object.fromEntries(entries)
+}
+
+function canonicalData(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((item) => canonicalData(item))
+  const record = recordOf(value)
+  return record === undefined ? value : sortedRecord(record, (_name, item) => canonicalData(item))
+}
+
+function canonical(value: unknown): unknown {
   if (Array.isArray(value)) return value.map((item) => canonical(item))
   const record = recordOf(value)
   if (record === undefined) return value
-  const out: Record<string, unknown> = {}
-  for (const name of Object.keys(record).sort()) {
-    const item = canonical(record[name], name)
-    if (item !== undefined) out[name] = item
-  }
-  return out
+  return sortedRecord(record, (name, item) => {
+    if (ANNOTATIONS.has(name)) return undefined
+    if (DATA.has(name)) return canonicalData(item)
+    const names = NAME_MAPS.has(name) ? recordOf(item) : undefined
+    return names === undefined
+      ? canonical(item)
+      : sortedRecord(names, (_key, schema) => canonical(schema))
+  })
 }
 
 async function sha256(value: string): Promise<string> {
@@ -104,13 +146,13 @@ export async function buildContractsLock(
   )
   return {
     version: 1,
-    routes: Object.fromEntries(Object.entries(routes).sort(([a], [b]) => a.localeCompare(b))),
+    routes: Object.fromEntries(Object.entries(routes).sort(([a], [b]) => codeUnitOrder(a, b))),
   }
 }
 
 async function loadBackend(cwd: string): Promise<unknown> {
-  const backendPath = resolve(cwd, "backend.ts")
-  if (!existsSync(backendPath)) throw new Error(`[nifra] no backend.ts in ${cwd}`)
+  const backendPath = resolve(cwd, BACKEND_APP_FILE)
+  if (!existsSync(backendPath)) throw new Error(`[nifra] no ${BACKEND_APP_FILE} in ${cwd}`)
   const loadedValue: unknown = await import(backendPath)
   const loaded = recordOf(loadedValue)
   if (loaded?.backend === undefined)

package/src/db-audit.ts

@@ -0,0 +1,128 @@
+/**
+ * `.nifra/db-audit.jsonl`: one line per `nifra db` call - what ran, never what came back. Each entry
+ * carries the SQL (secrets redacted), its fingerprint, the row count, the duration and the refusal
+ * code. The file is owner-only, never followed through a symlink, and rotates at 1 MB to
+ * `db-audit.1.jsonl`, so it stays bounded.
+ */
+
+import { createHash } from "node:crypto"
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeSync,
+} from "node:fs"
+import { resolve } from "node:path"
+import type { DbRefusalCode } from "@nifrajs/mcp-db/engine"
+
+export const DB_AUDIT_FILE = ".nifra/db-audit.jsonl"
+export const DB_AUDIT_ROTATED_FILE = ".nifra/db-audit.1.jsonl"
+export const DB_AUDIT_MAX_BYTES = 1024 * 1024
+
+/** One audited call. */
+export interface DbAuditEntry {
+  readonly at: string
+  readonly tool: "schema" | "query" | "explain" | "role"
+  readonly engine?: "sqlite" | "postgres" | undefined
+  /** The statement, secrets redacted. */
+  readonly sql?: string | undefined
+  /** Stable across literal values and whitespace, so repeated shapes group together. */
+  readonly fingerprint?: string | undefined
+  readonly table?: string | undefined
+  readonly ok: boolean
+  readonly code?: DbRefusalCode | undefined
+  readonly rowCount?: number | undefined
+  readonly durationMs: number
+}
+
+/** A statement's shape: literals become `?`, whitespace collapses, case folds; hashed. */
+export function sqlFingerprint(sql: string): string {
+  const shape = sql
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/'(?:[^']|'')*'/g, "?")
+    .replace(/\b\d+(?:\.\d+)?\b/g, "?")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase()
+  return createHash("sha256").update(shape).digest("hex").slice(0, 16)
+}
+
+/** True when `path` exists and is a symlink: the audit never writes through one. */
+function isSymlink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Append one entry. Returns false (and writes nothing) when `.nifra` or the log is a symlink or the
+ * write fails - an audit problem never fails the call it records.
+ */
+export function appendDbAudit(root: string, entry: DbAuditEntry): boolean {
+  const dir = resolve(root, ".nifra")
+  const file = resolve(root, DB_AUDIT_FILE)
+  try {
+    if (isSymlink(dir)) return false
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    if (isSymlink(file)) return false
+    const line = `${JSON.stringify(entry)}\n`
+    if (existsSync(file) && lstatSync(file).size + Buffer.byteLength(line) > DB_AUDIT_MAX_BYTES) {
+      const rotated = resolve(root, DB_AUDIT_ROTATED_FILE)
+      if (isSymlink(rotated)) return false
+      renameSync(file, rotated)
+    }
+    const fd = openSync(
+      file,
+      constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW,
+      0o600,
+    )
+    try {
+      writeSync(fd, line)
+    } finally {
+      closeSync(fd)
+    }
+    chmodSync(file, 0o600)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** True for a line `appendDbAudit` wrote (its required fields, at least). */
+export const isDbAuditEntry = (value: unknown): value is DbAuditEntry =>
+  typeof value === "object" &&
+  value !== null &&
+  "at" in value &&
+  typeof value.at === "string" &&
+  "tool" in value &&
+  typeof value.tool === "string" &&
+  "ok" in value &&
+  typeof value.ok === "boolean"
+
+/** The newest `limit` entries, oldest first, across the current and the rotated file. */
+export function readDbAudit(root: string, limit: number): DbAuditEntry[] {
+  const entries: DbAuditEntry[] = []
+  for (const name of [DB_AUDIT_ROTATED_FILE, DB_AUDIT_FILE]) {
+    const path = resolve(root, name)
+    if (!existsSync(path) || isSymlink(path)) continue
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+      if (line.trim() === "") continue
+      try {
+        const parsed: unknown = JSON.parse(line)
+        if (isDbAuditEntry(parsed)) entries.push(parsed)
+      } catch {
+        // A torn last line from a killed writer is skipped, not fatal.
+      }
+    }
+  }
+  return entries.slice(-limit)
+}

package/src/db-child.ts

@@ -0,0 +1,285 @@
+/**
+ * The `nifra db` subprocess. The parent (`db-tool.ts`) spawns a fresh one per call: it applies the
+ * project's `.env` files, imports `nifra.config.ts`, reports the declared deadline, opens the database,
+ * runs one operation, prints the answer and exits. The parent kills it at the deadline, so the deadline
+ * bounds the work and not only the response.
+ *
+ * Protocol: one JSON request on stdin; answers on stdout as lines prefixed with the request's token,
+ * so anything the config prints cannot be read as an answer.
+ */
+
+import {
+  type DbPlan,
+  type DbRedaction,
+  type DbRefusal,
+  type DbRows,
+  type DbSchemaReport,
+  dbRefusal,
+  explainSqlite,
+  isDbRefusal,
+  openReadOnlySqlite,
+  querySqlite,
+  readSqliteSchema,
+  resolveSqliteFile,
+} from "@nifrajs/mcp-db/engine"
+import {
+  connectPostgres,
+  explainPostgres,
+  type PostgresRoleSql,
+  parsePostgresUrl,
+  postgresRoleSql,
+  queryPostgres,
+  readPostgresSchema,
+} from "@nifrajs/mcp-db/postgres"
+import { createDevFeed } from "@nifrajs/web/dev-feed"
+import { isSensitiveFieldName } from "@nifrajs/web/zones"
+import { type DevDatabase, loadDevDatabase } from "./db-config.ts"
+import { CHILD_INPUT_MAX_BYTES, readBoundedStream } from "./mcp-io.ts"
+
+/** The one operation a subprocess runs. */
+export interface DbChildRequest {
+  readonly op: "schema" | "query" | "explain" | "role"
+  readonly sql?: string | undefined
+  readonly table?: string | undefined
+  readonly analyze?: boolean | undefined
+}
+
+/** What an operation produced, before the parent adds timing and the untrusted-data note. */
+export type DbChildAnswer =
+  | {
+      readonly ok: true
+      readonly engine: DevDatabase["kind"]
+      readonly database: string
+      readonly durationMs: number
+      readonly schema?: DbSchemaReport
+      readonly rows?: DbRows
+      readonly plan?: DbPlan
+      readonly role?: Omit<PostgresRoleSql, "serverVersionNum"> | { readonly statements: [] }
+    }
+  | {
+      readonly ok: false
+      readonly engine?: DevDatabase["kind"] | undefined
+      readonly database?: string | undefined
+      readonly durationMs: number
+      readonly refusal: DbRefusal
+    }
+
+/** The lines a subprocess writes, after its token. */
+export type DbChildMessage =
+  | { readonly type: "ready"; readonly timeoutMs: number }
+  | { readonly type: "answer"; readonly answer: DbChildAnswer }
+
+const lower = (name: string): string => name.toLowerCase()
+
+/**
+ * The masked columns a query may not read (the credential-name classifier, plus `redactColumns`,
+ * minus `revealColumns`) and the dev feed's text redactor for every string value.
+ */
+export function dbRedaction(
+  root: string,
+  db: DevDatabase,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): DbRedaction {
+  const redact = new Set(db.redactColumns.map(lower))
+  const reveal = new Set(db.revealColumns.map(lower))
+  const feed = createDevFeed({ root, persist: false, env })
+  return {
+    column: (name) =>
+      !reveal.has(lower(name)) && (isSensitiveFieldName(name) || redact.has(lower(name))),
+    text: (value) => feed.redact(value),
+  }
+}
+
+const QUERY_OFF = (): DbRefusal =>
+  dbRefusal("NIFRA_DB_QUERY_OFF", "devDatabase.query is false: only the schema tool is on")
+
+async function runSqlite(
+  root: string,
+  request: DbChildRequest,
+  db: Extract<DevDatabase, { kind: "sqlite" }>,
+  redaction: DbRedaction,
+): Promise<Omit<Extract<DbChildAnswer, { ok: true }>, "durationMs"> | DbRefusal> {
+  if (request.op === "role") {
+    return { ok: true, engine: "sqlite", database: db.file, role: { statements: [] } }
+  }
+  if (request.op !== "schema" && !db.query) return QUERY_OFF()
+  const file = resolveSqliteFile(root, db.file, db.allowFiles)
+  if (isDbRefusal(file)) return file
+  let handle: Awaited<ReturnType<typeof openReadOnlySqlite>>
+  try {
+    handle = await openReadOnlySqlite(file)
+  } catch (error) {
+    return dbRefusal("NIFRA_DB_DRIVER", `could not open ${db.file}: ${String(error)}`)
+  }
+  try {
+    const base = { ok: true as const, engine: "sqlite" as const, database: db.file }
+    if (request.op === "schema") {
+      const schema = readSqliteSchema(handle, {
+        exclude: db.exclude,
+        redaction,
+        table: request.table,
+      })
+      return isDbRefusal(schema) ? schema : { ...base, schema }
+    }
+    if (request.op === "explain") {
+      const plan = explainSqlite(handle, request.sql ?? "", db)
+      return isDbRefusal(plan) ? plan : { ...base, plan }
+    }
+    const rows = querySqlite(handle, request.sql ?? "", { ...db, redaction })
+    return isDbRefusal(rows) ? rows : { ...base, rows }
+  } finally {
+    handle.close()
+  }
+}
+
+async function runPostgres(
+  request: DbChildRequest,
+  db: Extract<DevDatabase, { kind: "postgres" }>,
+  redaction: DbRedaction,
+): Promise<Omit<Extract<DbChildAnswer, { ok: true }>, "durationMs"> | DbRefusal> {
+  if ((request.op === "query" || request.op === "explain") && !db.query) return QUERY_OFF()
+  const target = parsePostgresUrl(db.url)
+  if (isDbRefusal(target)) return target
+  const database = `${target.host ?? target.socket}:${target.port}/${target.database}`
+  const client = connectPostgres(target, db)
+  if (isDbRefusal(client)) return client
+  const base = { ok: true as const, engine: "postgres" as const, database }
+  try {
+    if (request.op === "schema") {
+      const schema = await readPostgresSchema(client, {
+        ...db,
+        redaction,
+        table: request.table,
+      })
+      return isDbRefusal(schema) ? schema : { ...base, schema }
+    }
+    if (request.op === "role") {
+      const role = await postgresRoleSql(client, db)
+      if (isDbRefusal(role)) return role
+      return {
+        ...base,
+        role: { role: role.role, database: role.database, statements: role.statements },
+      }
+    }
+    if (request.op === "explain") {
+      const plan = await explainPostgres(client, request.sql ?? "", {
+        ...db,
+        redaction,
+        analyze: request.analyze === true,
+      })
+      return isDbRefusal(plan) ? plan : { ...base, plan }
+    }
+    const rows = await queryPostgres(client, request.sql ?? "", { ...db, redaction })
+    return isDbRefusal(rows) ? rows : { ...base, rows }
+  } finally {
+    await client.close({ timeout: 0 }).catch(() => {})
+  }
+}
+
+/** Run one operation against a loaded declaration. Every refusal message is redacted too. */
+export async function runDbOperation(
+  root: string,
+  request: DbChildRequest,
+  db: DevDatabase,
+): Promise<DbChildAnswer> {
+  const started = performance.now()
+  const redaction = dbRedaction(root, db)
+  let outcome: Omit<Extract<DbChildAnswer, { ok: true }>, "durationMs"> | DbRefusal
+  try {
+    outcome =
+      db.kind === "sqlite"
+        ? await runSqlite(root, request, db, redaction)
+        : await runPostgres(request, db, redaction)
+  } catch (error) {
+    outcome = dbRefusal("NIFRA_DB_DRIVER", error instanceof Error ? error.message : String(error))
+  }
+  const durationMs = Math.round(performance.now() - started)
+  if (!isDbRefusal(outcome)) return { ...outcome, durationMs }
+  return {
+    ok: false,
+    engine: db.kind,
+    durationMs,
+    refusal: { ...outcome, message: redaction.text?.(outcome.message) ?? outcome.message },
+  }
+}
+
+const OPS = ["schema", "query", "explain", "role"] as const
+
+/** Validate the parent's request (it crosses a process boundary). */
+export function parseDbChildRequest(
+  text: string,
+): (DbChildRequest & { readonly token: string }) | undefined {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  if (typeof value !== "object" || value === null) return undefined
+  const field = (key: string): unknown => Reflect.get(value, key)
+  const token = field("token")
+  const op = OPS.find((name) => name === field("op"))
+  const sql = field("sql")
+  const table = field("table")
+  const analyze = field("analyze")
+  if (typeof token !== "string" || !/^[0-9a-f-]{16,64}$/.test(token)) return undefined
+  if (op === undefined) return undefined
+  if (sql !== undefined && typeof sql !== "string") return undefined
+  if (table !== undefined && typeof table !== "string") return undefined
+  if (analyze !== undefined && typeof analyze !== "boolean") return undefined
+  return { token, op, sql, table, analyze }
+}
+
+/**
+ * Serve one request: read it from `input`, load the declaration, report the deadline, run the
+ * operation and write the answer through `write`, each line prefixed with the request's token.
+ * Returns false (writing nothing) for a malformed request.
+ */
+export async function serveDbChild(
+  root: string,
+  input: ReadableStream<Uint8Array>,
+  write: (line: string) => Promise<void>,
+): Promise<boolean> {
+  const text = await readBoundedStream(input, CHILD_INPUT_MAX_BYTES)
+  const request = text.truncated ? undefined : parseDbChildRequest(text.text)
+  if (request === undefined) return false
+  const send = (message: DbChildMessage): Promise<void> =>
+    write(`${request.token} ${JSON.stringify(message)}\n`)
+  const started = performance.now()
+  let answer: DbChildAnswer
+  try {
+    const db = await loadDevDatabase(root)
+    if (isDbRefusal(db)) {
+      answer = { ok: false, durationMs: Math.round(performance.now() - started), refusal: db }
+    } else {
+      await send({ type: "ready", timeoutMs: db.timeoutMs })
+      answer = await runDbOperation(root, request, db)
+    }
+  } catch (error) {
+    answer = {
+      ok: false,
+      durationMs: Math.round(performance.now() - started),
+      refusal: dbRefusal("NIFRA_DB_DRIVER", error instanceof Error ? error.message : String(error)),
+    }
+  }
+  await send({ type: "answer", answer })
+  return true
+}
+
+if (import.meta.main) {
+  // Bound before the config loads, so nothing it patches can reach the protocol channel.
+  const stdout = process.stdout.write.bind(process.stdout)
+  const toStderr = (...args: unknown[]): void => {
+    process.stderr.write(`${args.map((arg) => String(arg)).join(" ")}\n`)
+  }
+  console.log = toStderr
+  console.info = toStderr
+  console.debug = toStderr
+  const served = await serveDbChild(
+    process.argv[2] ?? process.cwd(),
+    Bun.stdin.stream(),
+    (line) => new Promise((done) => stdout(line, () => done())),
+  )
+  if (!served) process.stderr.write("nifra db: invalid request\n")
+  process.exit(served ? 0 : 2)
+}