@gsengai/core 0.1.0

package/dist/gsengai-audit.js

@@ -0,0 +1,629 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync } from "fs";
+import { parseArgs } from "util";
+
+// src/store.ts
+import { randomUUID } from "crypto";
+import { once } from "events";
+import { createWriteStream, writeFileSync } from "fs";
+import Database from "better-sqlite3";
+
+// src/hash.ts
+import { createHash } from "crypto";
+var HASH_VERSION = 1;
+function sha256Hex(data) {
+  const hash = createHash("sha256");
+  if (typeof data === "string") {
+    hash.update(data, "utf8");
+  } else {
+    hash.update(data);
+  }
+  return hash.digest("hex");
+}
+function normalizeText(raw) {
+  return raw.normalize("NFC").toLowerCase().replace(/\s+/gu, " ").trim();
+}
+function hashText(raw) {
+  return {
+    outputHash: sha256Hex(raw),
+    outputHashNormalized: sha256Hex(normalizeText(raw)),
+    hashVersion: HASH_VERSION
+  };
+}
+
+// src/canonical-json.ts
+function canonicalJson(value) {
+  const out = JSON.stringify(value, (_key, val) => {
+    if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+      const record = val;
+      const sorted = {};
+      for (const key of Object.keys(record).sort()) {
+        sorted[key] = record[key];
+      }
+      return sorted;
+    }
+    return val;
+  });
+  if (out === void 0) {
+    throw new TypeError("canonicalJson: value does not serialize to JSON");
+  }
+  return out;
+}
+
+// src/errors.ts
+var NotImplementedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotImplementedError";
+  }
+};
+
+// src/export.ts
+var CSV_COLUMNS = [
+  "id",
+  "ts",
+  "modality",
+  "model",
+  "system_id",
+  "prompt_hash",
+  "output_hash",
+  "output_hash_normalized",
+  "hash_version",
+  "marking_methods",
+  "manifest_ref",
+  "disclosure_context",
+  "prev_hash",
+  "record_hash"
+];
+function csvField(value) {
+  if (value === null) {
+    return "";
+  }
+  const s = String(value);
+  return /[",\r\n]/.test(s) ? `"${s.replaceAll('"', '""')}"` : s;
+}
+function recordToCsvRow(record) {
+  return CSV_COLUMNS.map(
+    (column) => csvField(
+      column === "marking_methods" ? JSON.stringify(record.marking_methods) : record[column]
+    )
+  ).join(",");
+}
+var PRD_S9_LIMITS = `> **What this does NOT do**
+>
+> - It does not make you compliant. It supports compliance with EU AI Act Article 50 and California SB 942; compliance depends on your system, your deployment context, and your processes.
+> - It does not embed imperceptible watermarks (MVP). It implements the signed-metadata and logging/fingerprinting layers of a multi-layer marking strategy.
+> - It cannot prevent downstream metadata stripping \u2014 manifests can be removed by re-encoding, screenshots, or platform uploads. That is exactly why the logging layer exists.
+> - It does not detect third-party AI content.
+> - It is not legal advice. Consult qualified counsel about your obligations.`;
+function cell(value) {
+  if (value === null || value === "") {
+    return "";
+  }
+  return value.replaceAll("|", "\\|").replaceAll(/\r?\n/gu, " ");
+}
+function code(value) {
+  return value === null || value === "" ? "" : `\`${cell(value)}\``;
+}
+function describeFilter(filter) {
+  const parts = [];
+  if (filter?.systemId !== void 0) {
+    parts.push(`system_id = \`${cell(filter.systemId)}\``);
+  }
+  if (filter?.modality !== void 0) {
+    parts.push(`modality = \`${filter.modality}\``);
+  }
+  if (filter?.since !== void 0) {
+    parts.push(`ts \u2265 \`${filter.since}\``);
+  }
+  if (filter?.until !== void 0) {
+    parts.push(`ts \u2264 \`${filter.until}\``);
+  }
+  return parts.length === 0 ? "none (full store)" : parts.join(" \xB7 ");
+}
+function breakdown(records, label) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const key = label(record);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const rows = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  return rows.map(([key, n]) => `| ${cell(key)} | ${n} |`).join("\n");
+}
+function integritySection(integrity) {
+  if (integrity.ok) {
+    return `**Chain verified** \u2014 ${integrity.checked} record(s) checked; the tamper-evident hash chain is intact.`;
+  }
+  return `**\u26A0 BROKEN at seq ${integrity.brokenAtSeq}** \u2014 tamper-evident hash-chain verification FAILED at record seq ${integrity.brokenAtSeq} (${integrity.checked} record(s) checked up to and including the break). Records at and after this point cannot be trusted as appended; investigate the store before relying on this log.`;
+}
+function renderAuditReport(ctx) {
+  const { records, integrity } = ctx;
+  const firstTs = records[0]?.ts ?? null;
+  const lastTs = records.at(-1)?.ts ?? null;
+  const recordRows = records.length === 0 ? "_No records match the filter._" : [
+    "| id | ts | modality | model | system_id | output_hash | output_hash_normalized | marking_methods | manifest_ref | disclosure_context |",
+    "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+    ...records.map(
+      (r) => `| ${code(r.id)} | ${r.ts} | ${r.modality} | ${cell(r.model)} | ${cell(r.system_id)} | ${code(r.output_hash)} | ${code(r.output_hash_normalized)} | ${cell(r.marking_methods.join(" + "))} | ${code(r.manifest_ref)} | ${cell(r.disclosure_context)} |`
+    )
+  ].join("\n");
+  const summaryBreakdowns = records.length === 0 ? "" : `
+### By modality
+
+| Modality | Records |
+| --- | --- |
+${breakdown(records, (r) => r.modality)}
+
+### By model
+
+| Model | Records |
+| --- | --- |
+${breakdown(records, (r) => r.model)}
+
+### By system_id
+
+| system_id | Records |
+| --- | --- |
+${breakdown(records, (r) => r.system_id)}
+
+### By marking methods
+
+| Marking methods | Records |
+| --- | --- |
+${breakdown(records, (r) => r.marking_methods.join(" + "))}
+`;
+  return `# Evidence audit report (gsengai)
+
+- Generated: ${ctx.generatedAt} (UTC)
+- Store: \`${cell(ctx.storePath)}\`
+- Filter: ${describeFilter(ctx.filter)}
+- Record schema: v1 (PRD \xA74) \u2014 hashes and metadata only; raw content is never stored or exported
+
+## Integrity
+
+${integritySection(integrity)}
+
+Chain verification always covers the entire store, regardless of the export filter above.
+
+## Summary
+
+- Records (after filter): ${records.length}
+- First record: ${firstTs ?? "\u2014"}
+- Last record: ${lastTs ?? "\u2014"}
+${summaryBreakdowns}
+## Records
+
+${recordRows}
+
+## What this evidence is \u2014 and is not
+
+This report is a machine-generated record of the outputs an AI system generated, marked,
+and disclosed, as captured in an append-only, hash-chained evidence store. It contains
+cryptographic hashes and metadata only \u2014 raw prompts and outputs are never stored and
+never exported. It supports compliance with EU AI Act Article 50 and California SB 942;
+it is not, by itself, a determination of compliance.
+
+${PRD_S9_LIMITS}
+`;
+}
+
+// src/store.ts
+var MODALITIES = /* @__PURE__ */ new Set(["text", "image", "audio", "video"]);
+var SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS evidence (
+  seq INTEGER PRIMARY KEY,
+  id TEXT NOT NULL UNIQUE,
+  ts TEXT NOT NULL,
+  modality TEXT NOT NULL CHECK (modality IN ('text','image','audio','video')),
+  model TEXT NOT NULL,
+  system_id TEXT NOT NULL,
+  prompt_hash TEXT,
+  output_hash TEXT NOT NULL,
+  output_hash_normalized TEXT,
+  hash_version INTEGER NOT NULL,
+  marking_methods TEXT NOT NULL,
+  manifest_ref TEXT,
+  disclosure_context TEXT,
+  prev_hash TEXT,
+  record_hash TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_evidence_output_hash
+  ON evidence (output_hash);
+CREATE INDEX IF NOT EXISTS idx_evidence_output_hash_normalized
+  ON evidence (output_hash_normalized);
+CREATE TRIGGER IF NOT EXISTS evidence_append_only_update
+BEFORE UPDATE ON evidence
+BEGIN
+  SELECT RAISE(ABORT, 'gsengai evidence store is append-only: UPDATE is not permitted');
+END;
+CREATE TRIGGER IF NOT EXISTS evidence_append_only_delete
+BEFORE DELETE ON evidence
+BEGIN
+  SELECT RAISE(ABORT, 'gsengai evidence store is append-only: DELETE is not permitted');
+END;
+`;
+function rowToRecord(row) {
+  return {
+    id: row.id,
+    ts: row.ts,
+    modality: row.modality,
+    model: row.model,
+    system_id: row.system_id,
+    prompt_hash: row.prompt_hash,
+    output_hash: row.output_hash,
+    output_hash_normalized: row.output_hash_normalized,
+    hash_version: row.hash_version,
+    marking_methods: JSON.parse(row.marking_methods),
+    manifest_ref: row.manifest_ref,
+    disclosure_context: row.disclosure_context,
+    prev_hash: row.prev_hash,
+    record_hash: row.record_hash
+  };
+}
+function computeRecordHash(body) {
+  return sha256Hex(canonicalJson(body));
+}
+function requireNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`gsengai: ${name} must be a non-empty string`);
+  }
+  return value;
+}
+function resolveOutputHashes(input) {
+  const provided = [input.outputText, input.outputBytes, input.outputHashes].filter(
+    (v) => v !== void 0
+  );
+  if (provided.length !== 1) {
+    throw new TypeError("gsengai: provide exactly one of outputText, outputBytes, or outputHashes");
+  }
+  if (input.outputText !== void 0) {
+    const hashes = hashText(input.outputText);
+    return {
+      output_hash: hashes.outputHash,
+      output_hash_normalized: hashes.outputHashNormalized,
+      hash_version: hashes.hashVersion
+    };
+  }
+  if (input.outputBytes !== void 0) {
+    return {
+      output_hash: sha256Hex(input.outputBytes),
+      output_hash_normalized: null,
+      hash_version: HASH_VERSION
+    };
+  }
+  const given = input.outputHashes;
+  return {
+    output_hash: requireNonEmptyString(given.outputHash, "outputHashes.outputHash"),
+    output_hash_normalized: given.outputHashNormalized ?? null,
+    hash_version: given.hashVersion ?? HASH_VERSION
+  };
+}
+function normalizeInstant(value, name) {
+  const ms = Date.parse(requireNonEmptyString(value, name));
+  if (Number.isNaN(ms)) {
+    throw new TypeError(`gsengai: ${name} must be a Date.parse-able timestamp`);
+  }
+  return new Date(ms).toISOString();
+}
+function buildFilter(filter) {
+  if (filter === void 0) {
+    return { where: "", params: {}, normalized: void 0 };
+  }
+  const conditions = [];
+  const params = {};
+  const normalized = {};
+  if (filter.systemId !== void 0) {
+    normalized.systemId = requireNonEmptyString(filter.systemId, "filter.systemId");
+    conditions.push("system_id = @systemId");
+    params.systemId = normalized.systemId;
+  }
+  if (filter.modality !== void 0) {
+    if (!MODALITIES.has(filter.modality)) {
+      throw new TypeError(
+        "gsengai: filter.modality must be one of 'text' | 'image' | 'audio' | 'video'"
+      );
+    }
+    normalized.modality = filter.modality;
+    conditions.push("modality = @modality");
+    params.modality = normalized.modality;
+  }
+  if (filter.since !== void 0) {
+    normalized.since = normalizeInstant(filter.since, "filter.since");
+    conditions.push("ts >= @since");
+    params.since = normalized.since;
+  }
+  if (filter.until !== void 0) {
+    normalized.until = normalizeInstant(filter.until, "filter.until");
+    conditions.push("ts <= @until");
+    params.until = normalized.until;
+  }
+  if (conditions.length === 0) {
+    return { where: "", params: {}, normalized: void 0 };
+  }
+  return { where: ` WHERE ${conditions.join(" AND ")}`, params, normalized };
+}
+function createEvidenceStore(options) {
+  if (options.storeRawContent) {
+    throw new NotImplementedError(
+      "gsengai: storeRawContent is not implemented in the MVP. Only hashes and metadata persist (PRD C4); encrypted raw-content capture is planned post-MVP."
+    );
+  }
+  const storePath = requireNonEmptyString(options.path, "path");
+  const db = new Database(storePath);
+  db.pragma("journal_mode = WAL");
+  db.exec(SCHEMA_SQL);
+  const insertStmt = db.prepare(`
+    INSERT INTO evidence (
+      id, ts, modality, model, system_id, prompt_hash, output_hash,
+      output_hash_normalized, hash_version, marking_methods, manifest_ref,
+      disclosure_context, prev_hash, record_hash
+    ) VALUES (
+      @id, @ts, @modality, @model, @system_id, @prompt_hash, @output_hash,
+      @output_hash_normalized, @hash_version, @marking_methods, @manifest_ref,
+      @disclosure_context, @prev_hash, @record_hash
+    )
+  `);
+  const lastHashStmt = db.prepare("SELECT record_hash FROM evidence ORDER BY seq DESC LIMIT 1");
+  const allStmt = db.prepare("SELECT * FROM evidence ORDER BY seq");
+  const byOutputHashStmt = db.prepare("SELECT * FROM evidence WHERE output_hash = ? ORDER BY seq");
+  const byTextStmt = db.prepare(
+    "SELECT * FROM evidence WHERE output_hash = @raw OR output_hash_normalized = @normalized ORDER BY seq"
+  );
+  const countStmt = db.prepare("SELECT COUNT(*) AS n FROM evidence");
+  function filteredRows(filter) {
+    const { where, params, normalized } = buildFilter(filter);
+    const stmt = db.prepare(`SELECT * FROM evidence${where} ORDER BY seq`);
+    return { rows: stmt.iterate(params), normalized };
+  }
+  function verifyChainImpl() {
+    let checked = 0;
+    let prevHash = null;
+    for (const row of allStmt.iterate()) {
+      checked += 1;
+      const { record_hash, ...body } = rowToRecord(row);
+      if (body.prev_hash !== prevHash || computeRecordHash(body) !== record_hash) {
+        return { ok: false, checked, brokenAtSeq: row.seq };
+      }
+      prevHash = record_hash;
+    }
+    return { ok: true, checked };
+  }
+  const runAppend = db.transaction(
+    (body) => {
+      const last = lastHashStmt.get();
+      const chained = {
+        ...body,
+        prev_hash: last ? last.record_hash : null
+      };
+      const record = { ...chained, record_hash: computeRecordHash(chained) };
+      insertStmt.run({ ...record, marking_methods: JSON.stringify(record.marking_methods) });
+      return record;
+    }
+  );
+  return {
+    append(input) {
+      const modality = input.modality;
+      if (typeof modality !== "string" || !MODALITIES.has(modality)) {
+        throw new TypeError(
+          "gsengai: modality must be one of 'text' | 'image' | 'audio' | 'video'"
+        );
+      }
+      const body = {
+        id: randomUUID(),
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        modality,
+        model: requireNonEmptyString(input.model, "model"),
+        system_id: requireNonEmptyString(input.systemId, "systemId"),
+        prompt_hash: input.promptHash ?? null,
+        ...resolveOutputHashes(input),
+        marking_methods: input.markingMethods ?? ["logging"],
+        manifest_ref: input.manifestRef ?? null,
+        disclosure_context: input.disclosureContext ?? null
+      };
+      return runAppend.immediate(body);
+    },
+    findByOutputHash(hash) {
+      const rows = byOutputHashStmt.all(hash);
+      return rows.map(rowToRecord);
+    },
+    findByText(text) {
+      const hashes = hashText(text);
+      const rows = byTextStmt.all({
+        raw: hashes.outputHash,
+        normalized: hashes.outputHashNormalized
+      });
+      return rows.map(rowToRecord);
+    },
+    async exportJsonl(path) {
+      const out = createWriteStream(path, { encoding: "utf8" });
+      let records = 0;
+      try {
+        for (const row of allStmt.iterate()) {
+          const line = `${canonicalJson(rowToRecord(row))}
+`;
+          if (!out.write(line)) {
+            await once(out, "drain");
+          }
+          records += 1;
+        }
+      } finally {
+        out.end();
+      }
+      await once(out, "close");
+      return { records, path };
+    },
+    async exportCsv(path, filter) {
+      const { rows } = filteredRows(filter);
+      const out = createWriteStream(path, { encoding: "utf8" });
+      let records = 0;
+      try {
+        if (!out.write(`${CSV_COLUMNS.join(",")}
+`)) {
+          await once(out, "drain");
+        }
+        for (const row of rows) {
+          const line = `${recordToCsvRow(rowToRecord(row))}
+`;
+          if (!out.write(line)) {
+            await once(out, "drain");
+          }
+          records += 1;
+        }
+      } finally {
+        out.end();
+      }
+      await once(out, "close");
+      return { records, path };
+    },
+    buildAuditReport(opts = {}) {
+      const { rows, normalized } = filteredRows(opts.filter);
+      const records = [...rows].map(rowToRecord);
+      const integrity = verifyChainImpl();
+      const markdown = renderAuditReport({
+        records,
+        integrity,
+        storePath,
+        filter: normalized,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (opts.path !== void 0) {
+        writeFileSync(opts.path, markdown, "utf8");
+      }
+      return { markdown, records: records.length, integrity, path: opts.path ?? null };
+    },
+    verifyChain: verifyChainImpl,
+    count() {
+      const row = countStmt.get();
+      return row.n;
+    },
+    close() {
+      db.close();
+    }
+  };
+}
+
+// src/cli.ts
+var USAGE = `gsengai-audit \u2014 export audit artifacts from an gsengai evidence store.
+Supports compliance with EU AI Act Article 50 and California SB 942. Exports
+contain hashes and metadata only; raw content is never stored or exported.
+Not legal advice.
+
+Usage:
+  gsengai-audit export --store <evidence.db> --format csv|report --out <path>
+                    [--system-id <id>] [--modality text|image|audio|video]
+                    [--since <ISO timestamp>] [--until <ISO timestamp>]
+
+Formats:
+  csv     streaming CSV of evidence records (fixed schema-v1 column order)
+  report  human-readable Markdown audit report (integrity, summary, records)
+
+Tip: render the report Markdown to PDF/HTML yourself before handing it to
+counsel (e.g. pandoc report.md -o report.pdf).`;
+var MODALITIES2 = /* @__PURE__ */ new Set(["text", "image", "audio", "video"]);
+function parseCliArgs(argv) {
+  return parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      store: { type: "string" },
+      format: { type: "string" },
+      out: { type: "string" },
+      "system-id": { type: "string" },
+      modality: { type: "string" },
+      since: { type: "string" },
+      until: { type: "string" },
+      help: { type: "boolean" }
+    }
+  });
+}
+async function runAuditCli(argv, io = console) {
+  let parsed;
+  try {
+    parsed = parseCliArgs(argv);
+  } catch (err) {
+    io.error(err instanceof Error ? err.message : String(err));
+    io.error(USAGE);
+    return 1;
+  }
+  const { values, positionals } = parsed;
+  if (values.help === true) {
+    io.log(USAGE);
+    return 0;
+  }
+  if (positionals[0] !== "export" || positionals.length !== 1) {
+    io.error("gsengai-audit: the only supported command is 'export'");
+    io.error(USAGE);
+    return 1;
+  }
+  const storePath = values.store;
+  const format = values.format;
+  const outPath = values.out;
+  if (storePath === void 0 || format === void 0 || outPath === void 0) {
+    io.error("gsengai-audit: --store, --format, and --out are required");
+    io.error(USAGE);
+    return 1;
+  }
+  if (format !== "csv" && format !== "report") {
+    io.error(`gsengai-audit: unknown --format '${format}' (expected csv or report)`);
+    return 1;
+  }
+  if (!existsSync(storePath)) {
+    io.error(`gsengai-audit: no evidence store found at '${storePath}'`);
+    return 1;
+  }
+  const modality = values.modality;
+  if (modality !== void 0 && !MODALITIES2.has(modality)) {
+    io.error(`gsengai-audit: unknown --modality '${modality}' (expected text|image|audio|video)`);
+    return 1;
+  }
+  const filter = {};
+  if (values["system-id"] !== void 0) {
+    filter.systemId = values["system-id"];
+  }
+  if (modality !== void 0) {
+    filter.modality = modality;
+  }
+  if (values.since !== void 0) {
+    filter.since = values.since;
+  }
+  if (values.until !== void 0) {
+    filter.until = values.until;
+  }
+  const store = createEvidenceStore({ path: storePath });
+  try {
+    if (format === "csv") {
+      const result = await store.exportCsv(outPath, filter);
+      io.log(`CSV export: ${result.records} record(s) -> ${result.path}`);
+    } else {
+      const report = store.buildAuditReport({ path: outPath, filter });
+      io.log(`Audit report: ${report.records} record(s) -> ${outPath}`);
+      if (report.integrity.ok) {
+        io.log(`Integrity: chain verified (${report.integrity.checked} record(s) checked)`);
+      } else {
+        io.error(
+          `WARNING: evidence hash chain BROKEN at seq ${report.integrity.brokenAtSeq} \u2014 the Integrity section of the report records the break.`
+        );
+      }
+    }
+  } catch (err) {
+    io.error(`gsengai-audit: export failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  } finally {
+    store.close();
+  }
+  return 0;
+}
+
+// src/gsengai-audit.ts
+runAuditCli(process.argv.slice(2)).then(
+  (code2) => {
+    process.exitCode = code2;
+  },
+  (err) => {
+    console.error(err);
+    process.exitCode = 1;
+  }
+);
+//# sourceMappingURL=gsengai-audit.js.map