@agent-native/core 0.71.0 → 0.72.0

package/dist/audit/cleanup-job.js

@@ -0,0 +1,93 @@
+/**
+ * Audit-log retention job.
+ *
+ * Periodically purges `agent_audit_log` rows older than the configured horizon
+ * so the log doesn't grow unbounded. Retention is configurable via
+ * `AGENT_NATIVE_AUDIT_RETENTION_DAYS` (default: 365 days — audit trails are kept
+ * far longer than sampled traces). Setting it to `0` disables the purge (keep
+ * forever). Mirrors observability/cleanup-job.ts.
+ *
+ * Runs once on startup after a short delay, then on a 24-hour interval. Timers
+ * are unref'd so they never keep the process alive on their own.
+ */
+import { deleteOldAuditEvents } from "./store.js";
+const DEFAULT_RETENTION_DAYS = 365;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const STARTUP_DELAY_MS = 5 * 60 * 1000;
+let _cleanupTimer = null;
+let _intervalTimer = null;
+function resolveRetentionDays() {
+    const raw = process.env.AGENT_NATIVE_AUDIT_RETENTION_DAYS;
+    if (raw === undefined || raw === null || raw === "") {
+        return DEFAULT_RETENTION_DAYS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_RETENTION_DAYS;
+    return parsed;
+}
+/**
+ * Run the audit cleanup once. Returns the deleted row count, or null when
+ * retention is disabled (`AGENT_NATIVE_AUDIT_RETENTION_DAYS=0`).
+ */
+export async function runAuditCleanupOnce() {
+    const days = resolveRetentionDays();
+    if (days === 0)
+        return null;
+    const cutoff = Date.now() - days * ONE_DAY_MS;
+    return deleteOldAuditEvents(cutoff);
+}
+/**
+ * Start the recurring audit-cleanup job. Idempotent — calling more than once is
+ * a no-op while a previous schedule is active. Returns a stop function.
+ */
+export function startAuditCleanupJob() {
+    if (_cleanupTimer || _intervalTimer)
+        return stopAuditCleanupJob;
+    const days = resolveRetentionDays();
+    if (days === 0) {
+        if (process.env.DEBUG)
+            // eslint-disable-next-line no-console
+            console.log("[audit] Audit cleanup disabled (AGENT_NATIVE_AUDIT_RETENTION_DAYS=0)");
+        return () => { };
+    }
+    const tick = () => {
+        runAuditCleanupOnce()
+            .then((deleted) => {
+            if (deleted == null)
+                return;
+            if (process.env.DEBUG) {
+                // eslint-disable-next-line no-console
+                console.log(`[audit] Audit cleanup purged ${deleted} rows (retention=${days}d)`);
+            }
+        })
+            .catch((err) => {
+            // eslint-disable-next-line no-console
+            console.error("[audit] Audit cleanup failed:", err?.message ?? err);
+        });
+    };
+    _cleanupTimer = setTimeout(() => {
+        _cleanupTimer = null;
+        tick();
+        _intervalTimer = setInterval(tick, ONE_DAY_MS);
+        if (typeof _intervalTimer.unref === "function")
+            _intervalTimer.unref();
+    }, STARTUP_DELAY_MS);
+    if (typeof _cleanupTimer.unref === "function")
+        _cleanupTimer.unref();
+    if (process.env.DEBUG)
+        // eslint-disable-next-line no-console
+        console.log(`[audit] Audit cleanup scheduled (retention=${days}d, daily)`);
+    return stopAuditCleanupJob;
+}
+export function stopAuditCleanupJob() {
+    if (_cleanupTimer) {
+        clearTimeout(_cleanupTimer);
+        _cleanupTimer = null;
+    }
+    if (_intervalTimer) {
+        clearInterval(_intervalTimer);
+        _intervalTimer = null;
+    }
+}
+//# sourceMappingURL=cleanup-job.js.map

package/dist/audit/cleanup-job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-job.js","sourceRoot":"","sources":["../../src/audit/cleanup-job.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Audit-log retention job.\n *\n * Periodically purges `agent_audit_log` rows older than the configured horizon\n * so the log doesn't grow unbounded. Retention is configurable via\n * `AGENT_NATIVE_AUDIT_RETENTION_DAYS` (default: 365 days — audit trails are kept\n * far longer than sampled traces). Setting it to `0` disables the purge (keep\n * forever). Mirrors observability/cleanup-job.ts.\n *\n * Runs once on startup after a short delay, then on a 24-hour interval. Timers\n * are unref'd so they never keep the process alive on their own.\n */\nimport { deleteOldAuditEvents } from \"./store.js\";\n\nconst DEFAULT_RETENTION_DAYS = 365;\nconst ONE_DAY_MS = 24 * 60 * 60 * 1000;\nconst STARTUP_DELAY_MS = 5 * 60 * 1000;\n\nlet _cleanupTimer: NodeJS.Timeout | null = null;\nlet _intervalTimer: NodeJS.Timeout | null = null;\n\nfunction resolveRetentionDays(): number {\n  const raw = process.env.AGENT_NATIVE_AUDIT_RETENTION_DAYS;\n  if (raw === undefined || raw === null || raw === \"\") {\n    return DEFAULT_RETENTION_DAYS;\n  }\n  const parsed = Number.parseInt(raw, 10);\n  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_RETENTION_DAYS;\n  return parsed;\n}\n\n/**\n * Run the audit cleanup once. Returns the deleted row count, or null when\n * retention is disabled (`AGENT_NATIVE_AUDIT_RETENTION_DAYS=0`).\n */\nexport async function runAuditCleanupOnce(): Promise<number | null> {\n  const days = resolveRetentionDays();\n  if (days === 0) return null;\n  const cutoff = Date.now() - days * ONE_DAY_MS;\n  return deleteOldAuditEvents(cutoff);\n}\n\n/**\n * Start the recurring audit-cleanup job. Idempotent — calling more than once is\n * a no-op while a previous schedule is active. Returns a stop function.\n */\nexport function startAuditCleanupJob(): () => void {\n  if (_cleanupTimer || _intervalTimer) return stopAuditCleanupJob;\n  const days = resolveRetentionDays();\n  if (days === 0) {\n    if (process.env.DEBUG)\n      // eslint-disable-next-line no-console\n      console.log(\n        \"[audit] Audit cleanup disabled (AGENT_NATIVE_AUDIT_RETENTION_DAYS=0)\",\n      );\n    return () => {};\n  }\n\n  const tick = () => {\n    runAuditCleanupOnce()\n      .then((deleted) => {\n        if (deleted == null) return;\n        if (process.env.DEBUG) {\n          // eslint-disable-next-line no-console\n          console.log(\n            `[audit] Audit cleanup purged ${deleted} rows (retention=${days}d)`,\n          );\n        }\n      })\n      .catch((err) => {\n        // eslint-disable-next-line no-console\n        console.error(\"[audit] Audit cleanup failed:\", err?.message ?? err);\n      });\n  };\n\n  _cleanupTimer = setTimeout(() => {\n    _cleanupTimer = null;\n    tick();\n    _intervalTimer = setInterval(tick, ONE_DAY_MS);\n    if (typeof _intervalTimer.unref === \"function\") _intervalTimer.unref();\n  }, STARTUP_DELAY_MS);\n  if (typeof _cleanupTimer.unref === \"function\") _cleanupTimer.unref();\n\n  if (process.env.DEBUG)\n    // eslint-disable-next-line no-console\n    console.log(`[audit] Audit cleanup scheduled (retention=${days}d, daily)`);\n\n  return stopAuditCleanupJob;\n}\n\nexport function stopAuditCleanupJob(): void {\n  if (_cleanupTimer) {\n    clearTimeout(_cleanupTimer);\n    _cleanupTimer = null;\n  }\n  if (_intervalTimer) {\n    clearInterval(_intervalTimer);\n    _intervalTimer = null;\n  }\n}\n"]}

package/dist/audit/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure (no-DB) audit configuration helpers.
+ *
+ * Kept free of any database / store import so `action.ts` can statically
+ * import them without pulling the DB client into every bundle that touches an
+ * action. The DB-touching recorder lives in `record.ts`, which `action.ts`
+ * loads lazily via dynamic import on first audited call.
+ */
+import type { ActionAuditConfig, AuditActorKind, AuditStatus } from "./types.js";
+/** Normalize a raw `audit` option into a config object (or undefined). */
+export declare function normalizeAuditConfig(raw: unknown): ActionAuditConfig | undefined;
+/**
+ * Whether to attach the audit wrapper to an action at definition time. Decided
+ * from the action's resolved `readOnly` flag plus its config — the action's
+ * *name* isn't known here (it's the registry key), so name-based skipping
+ * happens later in `shouldRecordAudit`.
+ */
+export declare function resolveAuditAttach(config: ActionAuditConfig | undefined, readOnly: boolean | undefined): boolean;
+/**
+ * Final, name-aware decision made at record time. Explicit `enabled: true`
+ * overrides the high-frequency denylist; otherwise denylisted names are
+ * dropped.
+ */
+export declare function shouldRecordAudit(config: ActionAuditConfig | undefined, actionName: string): boolean;
+/** Derive the actor kind from the invocation surface + resolved identity. */
+export declare function deriveActorKind(caller: string | undefined, actorEmail: string | undefined | null): AuditActorKind;
+/** Whether the whole subsystem is disabled via env. */
+export declare function isAuditDisabled(): boolean;
+export type { AuditStatus };
+//# sourceMappingURL=config.d.ts.map

package/dist/audit/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/audit/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAwBpB,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,GACX,iBAAiB,GAAG,SAAS,CAG/B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAC5B,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,UAAU,EAAE,MAAM,GACjB,OAAO,CAKT;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GACpC,cAAc,CAGhB;AAED,uDAAuD;AACvD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,YAAY,EAAE,WAAW,EAAE,CAAC"}

package/dist/audit/config.js

@@ -0,0 +1,65 @@
+/**
+ * High-frequency / ephemeral framework actions that are not meaningful audit
+ * events. They mutate UI/agent-context state many times per session; auditing
+ * each one would flood the log without recording a real user-facing change.
+ *
+ * An action can still force itself on with `audit: { enabled: true }` —
+ * explicit config always wins over this denylist (see `shouldRecordAudit`).
+ */
+const DEFAULT_SKIP_ACTIONS = new Set([
+    "context-pin",
+    "context-evict",
+    "context-restore",
+    "context-report",
+    "context-manifest-get",
+    "change-appearance",
+    "toggle-demo-mode",
+]);
+/** Name patterns for high-frequency state-sync actions, skipped by default. */
+const DEFAULT_SKIP_PATTERN = /(application-state|app-state|set-state|view-screen|navigate|poll)/i;
+/** Normalize a raw `audit` option into a config object (or undefined). */
+export function normalizeAuditConfig(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    return raw;
+}
+/**
+ * Whether to attach the audit wrapper to an action at definition time. Decided
+ * from the action's resolved `readOnly` flag plus its config — the action's
+ * *name* isn't known here (it's the registry key), so name-based skipping
+ * happens later in `shouldRecordAudit`.
+ */
+export function resolveAuditAttach(config, readOnly) {
+    if (config && typeof config.enabled === "boolean")
+        return config.enabled;
+    // Read-only actions are not audited unless they opt in via `onRead`.
+    if (readOnly === true)
+        return config?.onRead === true;
+    // Everything else mutates — audit by default.
+    return true;
+}
+/**
+ * Final, name-aware decision made at record time. Explicit `enabled: true`
+ * overrides the high-frequency denylist; otherwise denylisted names are
+ * dropped.
+ */
+export function shouldRecordAudit(config, actionName) {
+    if (config && config.enabled === true)
+        return true;
+    if (DEFAULT_SKIP_ACTIONS.has(actionName))
+        return false;
+    if (DEFAULT_SKIP_PATTERN.test(actionName))
+        return false;
+    return true;
+}
+/** Derive the actor kind from the invocation surface + resolved identity. */
+export function deriveActorKind(caller, actorEmail) {
+    if (caller === "tool")
+        return "agent";
+    return actorEmail ? "human" : "system";
+}
+/** Whether the whole subsystem is disabled via env. */
+export function isAuditDisabled() {
+    return process.env.AGENT_NATIVE_AUDIT_ENABLED === "false";
+}
+//# sourceMappingURL=config.js.map

package/dist/audit/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/audit/config.ts"],"names":[],"mappings":"AAcA;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAS;IAC3C,aAAa;IACb,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,sBAAsB;IACtB,mBAAmB;IACnB,kBAAkB;CACnB,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,oBAAoB,GACxB,oEAAoE,CAAC;AAEvE,0EAA0E;AAC1E,MAAM,UAAU,oBAAoB,CAClC,GAAY;IAEZ,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5E,OAAO,GAAwB,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAqC,EACrC,QAA6B;IAE7B,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC;IACzE,qEAAqE;IACrE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,8CAA8C;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAqC,EACrC,UAAkB;IAElB,IAAI,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,oBAAoB,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IACvD,IAAI,oBAAoB,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAC7B,MAA0B,EAC1B,UAAqC;IAErC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC;IACtC,OAAO,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;AACzC,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,eAAe;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,0BAA0B,KAAK,OAAO,CAAC;AAC5D,CAAC","sourcesContent":["/**\n * Pure (no-DB) audit configuration helpers.\n *\n * Kept free of any database / store import so `action.ts` can statically\n * import them without pulling the DB client into every bundle that touches an\n * action. The DB-touching recorder lives in `record.ts`, which `action.ts`\n * loads lazily via dynamic import on first audited call.\n */\nimport type {\n  ActionAuditConfig,\n  AuditActorKind,\n  AuditStatus,\n} from \"./types.js\";\n\n/**\n * High-frequency / ephemeral framework actions that are not meaningful audit\n * events. They mutate UI/agent-context state many times per session; auditing\n * each one would flood the log without recording a real user-facing change.\n *\n * An action can still force itself on with `audit: { enabled: true }` —\n * explicit config always wins over this denylist (see `shouldRecordAudit`).\n */\nconst DEFAULT_SKIP_ACTIONS = new Set<string>([\n  \"context-pin\",\n  \"context-evict\",\n  \"context-restore\",\n  \"context-report\",\n  \"context-manifest-get\",\n  \"change-appearance\",\n  \"toggle-demo-mode\",\n]);\n\n/** Name patterns for high-frequency state-sync actions, skipped by default. */\nconst DEFAULT_SKIP_PATTERN =\n  /(application-state|app-state|set-state|view-screen|navigate|poll)/i;\n\n/** Normalize a raw `audit` option into a config object (or undefined). */\nexport function normalizeAuditConfig(\n  raw: unknown,\n): ActionAuditConfig | undefined {\n  if (!raw || typeof raw !== \"object\" || Array.isArray(raw)) return undefined;\n  return raw as ActionAuditConfig;\n}\n\n/**\n * Whether to attach the audit wrapper to an action at definition time. Decided\n * from the action's resolved `readOnly` flag plus its config — the action's\n * *name* isn't known here (it's the registry key), so name-based skipping\n * happens later in `shouldRecordAudit`.\n */\nexport function resolveAuditAttach(\n  config: ActionAuditConfig | undefined,\n  readOnly: boolean | undefined,\n): boolean {\n  if (config && typeof config.enabled === \"boolean\") return config.enabled;\n  // Read-only actions are not audited unless they opt in via `onRead`.\n  if (readOnly === true) return config?.onRead === true;\n  // Everything else mutates — audit by default.\n  return true;\n}\n\n/**\n * Final, name-aware decision made at record time. Explicit `enabled: true`\n * overrides the high-frequency denylist; otherwise denylisted names are\n * dropped.\n */\nexport function shouldRecordAudit(\n  config: ActionAuditConfig | undefined,\n  actionName: string,\n): boolean {\n  if (config && config.enabled === true) return true;\n  if (DEFAULT_SKIP_ACTIONS.has(actionName)) return false;\n  if (DEFAULT_SKIP_PATTERN.test(actionName)) return false;\n  return true;\n}\n\n/** Derive the actor kind from the invocation surface + resolved identity. */\nexport function deriveActorKind(\n  caller: string | undefined,\n  actorEmail: string | undefined | null,\n): AuditActorKind {\n  if (caller === \"tool\") return \"agent\";\n  return actorEmail ? \"human\" : \"system\";\n}\n\n/** Whether the whole subsystem is disabled via env. */\nexport function isAuditDisabled(): boolean {\n  return process.env.AGENT_NATIVE_AUDIT_ENABLED === \"false\";\n}\n\nexport type { AuditStatus };\n"]}

package/dist/audit/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Framework audit log — a durable, complete, access-scoped, append-only record
+ * of who mutated what app data, when, from where, and (for the agent) in which
+ * run. Distinct from observability (sampled telemetry) and tracking
+ * (fire-and-forget analytics). Capture is automatic at the `defineAction` seam.
+ */
+export type { ActionAuditConfig, AuditActorKind, AuditCallMeta, AuditEvent, AuditQueryFilters, AuditStatus, AuditTarget, AuditVisibility, } from "./types.js";
+export { deriveActorKind, isAuditDisabled, normalizeAuditConfig, resolveAuditAttach, shouldRecordAudit, } from "./config.js";
+export { redactArgsToJson } from "./redact.js";
+export { ensureAuditTables, insertAuditEvent, queryAuditEvents, getAuditEventById, deleteOldAuditEvents, type AuditReadScope, } from "./store.js";
+export { recordActionAudit } from "./record.js";
+export { runAuditCleanupOnce, startAuditCleanupJob, stopAuditCleanupJob, } from "./cleanup-job.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/dist/audit/index.js

@@ -0,0 +1,6 @@
+export { deriveActorKind, isAuditDisabled, normalizeAuditConfig, resolveAuditAttach, shouldRecordAudit, } from "./config.js";
+export { redactArgsToJson } from "./redact.js";
+export { ensureAuditTables, insertAuditEvent, queryAuditEvents, getAuditEventById, deleteOldAuditEvents, } from "./store.js";
+export { recordActionAudit } from "./record.js";
+export { runAuditCleanupOnce, startAuditCleanupJob, stopAuditCleanupJob, } from "./cleanup-job.js";
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,GAErB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC","sourcesContent":["/**\n * Framework audit log — a durable, complete, access-scoped, append-only record\n * of who mutated what app data, when, from where, and (for the agent) in which\n * run. Distinct from observability (sampled telemetry) and tracking\n * (fire-and-forget analytics). Capture is automatic at the `defineAction` seam.\n */\nexport type {\n  ActionAuditConfig,\n  AuditActorKind,\n  AuditCallMeta,\n  AuditEvent,\n  AuditQueryFilters,\n  AuditStatus,\n  AuditTarget,\n  AuditVisibility,\n} from \"./types.js\";\n\nexport {\n  deriveActorKind,\n  isAuditDisabled,\n  normalizeAuditConfig,\n  resolveAuditAttach,\n  shouldRecordAudit,\n} from \"./config.js\";\n\nexport { redactArgsToJson } from \"./redact.js\";\n\nexport {\n  ensureAuditTables,\n  insertAuditEvent,\n  queryAuditEvents,\n  getAuditEventById,\n  deleteOldAuditEvents,\n  type AuditReadScope,\n} from \"./store.js\";\n\nexport { recordActionAudit } from \"./record.js\";\n\nexport {\n  runAuditCleanupOnce,\n  startAuditCleanupJob,\n  stopAuditCleanupJob,\n} from \"./cleanup-job.js\";\n"]}

package/dist/audit/record.d.ts

@@ -0,0 +1,24 @@
+import type { ActionAuditConfig, AuditStatus } from "./types.js";
+/** Minimal view of the action run context the recorder needs. */
+export interface AuditRunContextLike {
+    actionName?: string;
+    caller?: string;
+    userEmail?: string;
+    orgId?: string | null;
+    threadId?: string;
+    turnId?: string;
+}
+export interface RecordActionAuditInput {
+    config: ActionAuditConfig | undefined;
+    args: unknown;
+    ctx: AuditRunContextLike | undefined;
+    status: AuditStatus;
+    result?: unknown;
+    error?: unknown;
+}
+/**
+ * Record one audit event. Resolves the actor, target, ownership (for scoped
+ * reads), and redacted inputs, then appends a row. Never throws.
+ */
+export declare function recordActionAudit(input: RecordActionAuditInput): Promise<void>;
+//# sourceMappingURL=record.d.ts.map

package/dist/audit/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/audit/record.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,iBAAiB,EAGjB,WAAW,EAEZ,MAAM,YAAY,CAAC;AAEpB,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA0CD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/audit/record.js

@@ -0,0 +1,106 @@
+/**
+ * Audit capture entry point, called from the `defineAction` audit wrapper after
+ * an action runs (success or error). Best-effort: any failure here is swallowed
+ * so auditing never breaks the action it observes.
+ *
+ * This module touches the DB (`store.js`), so `action.ts` loads it lazily via
+ * dynamic import on the first audited call — keeping the DB client out of every
+ * bundle that merely defines actions.
+ */
+import { deriveActorKind, isAuditDisabled, shouldRecordAudit, } from "./config.js";
+import { redactArgsToJson } from "./redact.js";
+import { insertAuditEvent } from "./store.js";
+function errorCode(error) {
+    if (!error)
+        return null;
+    if (typeof error === "object") {
+        const e = error;
+        if (typeof e.errorCode === "string")
+            return e.errorCode;
+        if (typeof e.code === "string")
+            return e.code;
+        if (typeof e.name === "string")
+            return e.name;
+    }
+    return "error";
+}
+function safeTarget(config, args, result, meta) {
+    if (!config?.target)
+        return null;
+    try {
+        return config.target(args, result, meta) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function safeSummary(config, args, result, meta) {
+    if (!config?.summary)
+        return null;
+    try {
+        const s = config.summary(args, result, meta);
+        return typeof s === "string" ? s.slice(0, 500) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record one audit event. Resolves the actor, target, ownership (for scoped
+ * reads), and redacted inputs, then appends a row. Never throws.
+ */
+export async function recordActionAudit(input) {
+    try {
+        if (isAuditDisabled())
+            return;
+        const ctx = input.ctx;
+        const actionName = ctx?.actionName;
+        // No name → an internal/programmatic run() with no dispatch context. Skip
+        // rather than write a nameless row.
+        if (!actionName)
+            return;
+        if (!shouldRecordAudit(input.config, actionName))
+            return;
+        const caller = ctx?.caller ?? "http";
+        const actorEmail = ctx?.userEmail ?? null;
+        const meta = {
+            status: input.status,
+            caller,
+            userEmail: ctx?.userEmail,
+            orgId: ctx?.orgId ?? null,
+        };
+        const target = safeTarget(input.config, input.args, input.result, meta);
+        const summary = safeSummary(input.config, input.args, input.result, meta);
+        const recordInputs = input.config?.recordInputs !== false;
+        const inputJson = recordInputs ? redactArgsToJson(input.args) : null;
+        const event = {
+            id: crypto.randomUUID(),
+            createdAt: Date.now(),
+            action: actionName,
+            caller,
+            actorKind: deriveActorKind(caller, actorEmail),
+            actorEmail,
+            orgId: ctx?.orgId ?? null,
+            threadId: ctx?.threadId ?? null,
+            turnId: ctx?.turnId ?? null,
+            targetType: target?.type ?? null,
+            targetId: target?.id ?? null,
+            status: input.status,
+            summary,
+            input: inputJson,
+            errorCode: input.status === "error" ? errorCode(input.error) : null,
+            // Scope reads to the resource owner when the action declares one,
+            // otherwise to the actor (the common self-mutation case).
+            ownerEmail: target?.ownerEmail ?? actorEmail,
+            visibility: target?.visibility ?? "private",
+        };
+        // org_id used for scoping defaults to the target's, else the actor's org.
+        if (target?.orgId !== undefined)
+            event.orgId = target.orgId;
+        await insertAuditEvent(event);
+    }
+    catch {
+        // Best-effort — auditing must never break the audited action.
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/audit/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/audit/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA4B9C,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,KAAgE,CAAC;QAC3E,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,SAAS,CAAC;QACxD,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,IAAI,CAAC;QAC9C,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,UAAU,CACjB,MAAqC,EACrC,IAAa,EACb,MAAe,EACf,IAAmB;IAEnB,IAAI,CAAC,MAAM,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAClB,MAAqC,EACrC,IAAa,EACb,MAAe,EACf,IAAmB;IAEnB,IAAI,CAAC,MAAM,EAAE,OAAO;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7C,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAA6B;IAE7B,IAAI,CAAC;QACH,IAAI,eAAe,EAAE;YAAE,OAAO;QAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;QACtB,MAAM,UAAU,GAAG,GAAG,EAAE,UAAU,CAAC;QACnC,0EAA0E;QAC1E,oCAAoC;QACpC,IAAI,CAAC,UAAU;YAAE,OAAO;QACxB,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC;YAAE,OAAO;QAEzD,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,MAAM,CAAC;QACrC,MAAM,UAAU,GAAG,GAAG,EAAE,SAAS,IAAI,IAAI,CAAC;QAC1C,MAAM,IAAI,GAAkB;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM;YACN,SAAS,EAAE,GAAG,EAAE,SAAS;YACzB,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,IAAI;SAC1B,CAAC;QAEF,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACxE,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAE1E,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,EAAE,YAAY,KAAK,KAAK,CAAC;QAC1D,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAErE,MAAM,KAAK,GAAe;YACxB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,MAAM,EAAE,UAAU;YAClB,MAAM;YACN,SAAS,EAAE,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC;YAC9C,UAAU;YACV,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,IAAI;YACzB,QAAQ,EAAE,GAAG,EAAE,QAAQ,IAAI,IAAI;YAC/B,MAAM,EAAE,GAAG,EAAE,MAAM,IAAI,IAAI;YAC3B,UAAU,EAAE,MAAM,EAAE,IAAI,IAAI,IAAI;YAChC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,IAAI;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO;YACP,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;YACnE,kEAAkE;YAClE,0DAA0D;YAC1D,UAAU,EAAE,MAAM,EAAE,UAAU,IAAI,UAAU;YAC5C,UAAU,EAAE,MAAM,EAAE,UAAU,IAAI,SAAS;SAC5C,CAAC;QACF,0EAA0E;QAC1E,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;YAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAE5D,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;AACH,CAAC","sourcesContent":["/**\n * Audit capture entry point, called from the `defineAction` audit wrapper after\n * an action runs (success or error). Best-effort: any failure here is swallowed\n * so auditing never breaks the action it observes.\n *\n * This module touches the DB (`store.js`), so `action.ts` loads it lazily via\n * dynamic import on the first audited call — keeping the DB client out of every\n * bundle that merely defines actions.\n */\nimport {\n  deriveActorKind,\n  isAuditDisabled,\n  shouldRecordAudit,\n} from \"./config.js\";\nimport { redactArgsToJson } from \"./redact.js\";\nimport { insertAuditEvent } from \"./store.js\";\nimport type {\n  ActionAuditConfig,\n  AuditCallMeta,\n  AuditEvent,\n  AuditStatus,\n  AuditTarget,\n} from \"./types.js\";\n\n/** Minimal view of the action run context the recorder needs. */\nexport interface AuditRunContextLike {\n  actionName?: string;\n  caller?: string;\n  userEmail?: string;\n  orgId?: string | null;\n  threadId?: string;\n  turnId?: string;\n}\n\nexport interface RecordActionAuditInput {\n  config: ActionAuditConfig | undefined;\n  args: unknown;\n  ctx: AuditRunContextLike | undefined;\n  status: AuditStatus;\n  result?: unknown;\n  error?: unknown;\n}\n\nfunction errorCode(error: unknown): string | null {\n  if (!error) return null;\n  if (typeof error === \"object\") {\n    const e = error as { errorCode?: unknown; code?: unknown; name?: unknown };\n    if (typeof e.errorCode === \"string\") return e.errorCode;\n    if (typeof e.code === \"string\") return e.code;\n    if (typeof e.name === \"string\") return e.name;\n  }\n  return \"error\";\n}\n\nfunction safeTarget(\n  config: ActionAuditConfig | undefined,\n  args: unknown,\n  result: unknown,\n  meta: AuditCallMeta,\n): AuditTarget | null {\n  if (!config?.target) return null;\n  try {\n    return config.target(args, result, meta) ?? null;\n  } catch {\n    return null;\n  }\n}\n\nfunction safeSummary(\n  config: ActionAuditConfig | undefined,\n  args: unknown,\n  result: unknown,\n  meta: AuditCallMeta,\n): string | null {\n  if (!config?.summary) return null;\n  try {\n    const s = config.summary(args, result, meta);\n    return typeof s === \"string\" ? s.slice(0, 500) : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Record one audit event. Resolves the actor, target, ownership (for scoped\n * reads), and redacted inputs, then appends a row. Never throws.\n */\nexport async function recordActionAudit(\n  input: RecordActionAuditInput,\n): Promise<void> {\n  try {\n    if (isAuditDisabled()) return;\n    const ctx = input.ctx;\n    const actionName = ctx?.actionName;\n    // No name → an internal/programmatic run() with no dispatch context. Skip\n    // rather than write a nameless row.\n    if (!actionName) return;\n    if (!shouldRecordAudit(input.config, actionName)) return;\n\n    const caller = ctx?.caller ?? \"http\";\n    const actorEmail = ctx?.userEmail ?? null;\n    const meta: AuditCallMeta = {\n      status: input.status,\n      caller,\n      userEmail: ctx?.userEmail,\n      orgId: ctx?.orgId ?? null,\n    };\n\n    const target = safeTarget(input.config, input.args, input.result, meta);\n    const summary = safeSummary(input.config, input.args, input.result, meta);\n\n    const recordInputs = input.config?.recordInputs !== false;\n    const inputJson = recordInputs ? redactArgsToJson(input.args) : null;\n\n    const event: AuditEvent = {\n      id: crypto.randomUUID(),\n      createdAt: Date.now(),\n      action: actionName,\n      caller,\n      actorKind: deriveActorKind(caller, actorEmail),\n      actorEmail,\n      orgId: ctx?.orgId ?? null,\n      threadId: ctx?.threadId ?? null,\n      turnId: ctx?.turnId ?? null,\n      targetType: target?.type ?? null,\n      targetId: target?.id ?? null,\n      status: input.status,\n      summary,\n      input: inputJson,\n      errorCode: input.status === \"error\" ? errorCode(input.error) : null,\n      // Scope reads to the resource owner when the action declares one,\n      // otherwise to the actor (the common self-mutation case).\n      ownerEmail: target?.ownerEmail ?? actorEmail,\n      visibility: target?.visibility ?? \"private\",\n    };\n    // org_id used for scoping defaults to the target's, else the actor's org.\n    if (target?.orgId !== undefined) event.orgId = target.orgId;\n\n    await insertAuditEvent(event);\n  } catch {\n    // Best-effort — auditing must never break the audited action.\n  }\n}\n"]}

package/dist/audit/redact.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Redaction for audit-captured arguments.
+ *
+ * The audit log must never become a secondary store of secrets. Before any
+ * call arguments are persisted we:
+ *  - drop values under credential-looking keys (token, secret, password, …),
+ *  - redact string values that look like bearer tokens / long opaque keys,
+ *  - truncate oversized strings and cap the serialized payload size.
+ *
+ * This mirrors the framework's standing rule that credential-looking literals
+ * never land in source, logs, or fixtures.
+ */
+/** Heuristic: does a bare string value look like a secret? */
+declare function looksSecret(value: string): boolean;
+declare function redact(value: unknown, depth: number): unknown;
+/**
+ * Redact and serialize call arguments to a capped JSON string, or `null` when
+ * there is nothing to record. Never throws.
+ */
+export declare function redactArgsToJson(args: unknown): string | null;
+/** Exposed for tests. */
+export declare const __test: {
+    looksSecret: typeof looksSecret;
+    redact: typeof redact;
+    SENSITIVE_KEY: RegExp;
+};
+export {};
+//# sourceMappingURL=redact.d.ts.map

package/dist/audit/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/audit/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,8DAA8D;AAC9D,iBAAS,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAkB3C;AAUD,iBAAS,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA0BtD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAqB7D;AAED,yBAAyB;AACzB,eAAO,MAAM,MAAM;;;;CAAyC,CAAC"}

package/dist/audit/redact.js

@@ -0,0 +1,109 @@
+/**
+ * Redaction for audit-captured arguments.
+ *
+ * The audit log must never become a secondary store of secrets. Before any
+ * call arguments are persisted we:
+ *  - drop values under credential-looking keys (token, secret, password, …),
+ *  - redact string values that look like bearer tokens / long opaque keys,
+ *  - truncate oversized strings and cap the serialized payload size.
+ *
+ * This mirrors the framework's standing rule that credential-looking literals
+ * never land in source, logs, or fixtures.
+ */
+const SENSITIVE_KEY = /(pass(word|phrase)?|secret|token|api[_-]?key|apikey|authorization|bearer|credential|cookie|session[_-]?(id|token)|private[_-]?key|client[_-]?secret|signing[_-]?secret|access[_-]?key|refresh[_-]?token|webhook[_-]?(url|secret))/i;
+const REDACTED = "[redacted]";
+const MAX_STRING = 2000;
+const MAX_DEPTH = 6;
+const MAX_KEYS = 100;
+const MAX_ARRAY = 100;
+const MAX_JSON = 8000;
+/** Heuristic: does a bare string value look like a secret? */
+function looksSecret(value) {
+    if (/^bearer\s+\S/i.test(value))
+        return true;
+    // Long, unbroken, high-entropy-ish opaque token (hex/base64url, no spaces).
+    if (value.length >= 32 && /^[A-Za-z0-9_\-+/=.]+$/.test(value))
+        return true;
+    // Common secret prefixes (Stripe, GitHub, OpenAI, Slack, AWS, …).
+    if (/^(sk|pk|rk|ghp|gho|xox[baprs]|AKIA|AIza|ya29)[-_]/i.test(value)) {
+        return true;
+    }
+    // Webhook URLs carry their secret in the path — redact regardless of the key
+    // they arrive under (e.g. a generic `value` field holding a Slack webhook).
+    if (/^https?:\/\/(hooks\.slack\.com\/|[^/]*\.webhook\.office\.com\/|(canary\.|ptb\.)?discord(app)?\.com\/api\/webhooks\/|hooks\.zapier\.com\/|maker\.ifttt\.com\/|discord\.com\/api\/webhooks\/)/i.test(value)) {
+        return true;
+    }
+    return false;
+}
+function redactString(value) {
+    if (looksSecret(value))
+        return REDACTED;
+    if (value.length > MAX_STRING) {
+        return `${value.slice(0, MAX_STRING)}…(${value.length - MAX_STRING} more chars)`;
+    }
+    return value;
+}
+function redact(value, depth) {
+    if (value == null)
+        return value;
+    if (typeof value === "string")
+        return redactString(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (depth >= MAX_DEPTH)
+        return "[…]";
+    if (Array.isArray(value)) {
+        const out = value.slice(0, MAX_ARRAY).map((v) => redact(v, depth + 1));
+        if (value.length > MAX_ARRAY)
+            out.push(`…(${value.length - MAX_ARRAY} more)`);
+        return out;
+    }
+    if (typeof value === "object") {
+        const out = {};
+        let n = 0;
+        for (const [k, v] of Object.entries(value)) {
+            if (n >= MAX_KEYS) {
+                out["…"] = "(truncated)";
+                break;
+            }
+            n += 1;
+            out[k] = SENSITIVE_KEY.test(k) ? REDACTED : redact(v, depth + 1);
+        }
+        return out;
+    }
+    // Functions, symbols, bigint, etc. — not serializable / not interesting.
+    return undefined;
+}
+/**
+ * Redact and serialize call arguments to a capped JSON string, or `null` when
+ * there is nothing to record. Never throws.
+ */
+export function redactArgsToJson(args) {
+    try {
+        if (args == null)
+            return null;
+        const redacted = redact(args, 0);
+        if (redacted === undefined)
+            return null;
+        const json = JSON.stringify(redacted);
+        if (json == null)
+            return null;
+        if (json.length > MAX_JSON) {
+            // Slicing the serialized JSON would yield an unparseable string. Wrap a
+            // preview in a valid envelope so `get-audit-event` can always JSON.parse
+            // the stored `input`.
+            return JSON.stringify({
+                _auditTruncated: true,
+                originalBytes: json.length,
+                preview: json.slice(0, MAX_JSON),
+            });
+        }
+        return json;
+    }
+    catch {
+        return null;
+    }
+}
+/** Exposed for tests. */
+export const __test = { looksSecret, redact, SENSITIVE_KEY };
+//# sourceMappingURL=redact.js.map

package/dist/audit/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/audit/redact.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Redaction for audit-captured arguments.\n *\n * The audit log must never become a secondary store of secrets. Before any\n * call arguments are persisted we:\n *  - drop values under credential-looking keys (token, secret, password, …),\n *  - redact string values that look like bearer tokens / long opaque keys,\n *  - truncate oversized strings and cap the serialized payload size.\n *\n * This mirrors the framework's standing rule that credential-looking literals\n * never land in source, logs, or fixtures.\n */\n\nconst SENSITIVE_KEY =\n  /(pass(word|phrase)?|secret|token|api[_-]?key|apikey|authorization|bearer|credential|cookie|session[_-]?(id|token)|private[_-]?key|client[_-]?secret|signing[_-]?secret|access[_-]?key|refresh[_-]?token|webhook[_-]?(url|secret))/i;\n\nconst REDACTED = \"[redacted]\";\nconst MAX_STRING = 2000;\nconst MAX_DEPTH = 6;\nconst MAX_KEYS = 100;\nconst MAX_ARRAY = 100;\nconst MAX_JSON = 8000;\n\n/** Heuristic: does a bare string value look like a secret? */\nfunction looksSecret(value: string): boolean {\n  if (/^bearer\\s+\\S/i.test(value)) return true;\n  // Long, unbroken, high-entropy-ish opaque token (hex/base64url, no spaces).\n  if (value.length >= 32 && /^[A-Za-z0-9_\\-+/=.]+$/.test(value)) return true;\n  // Common secret prefixes (Stripe, GitHub, OpenAI, Slack, AWS, …).\n  if (/^(sk|pk|rk|ghp|gho|xox[baprs]|AKIA|AIza|ya29)[-_]/i.test(value)) {\n    return true;\n  }\n  // Webhook URLs carry their secret in the path — redact regardless of the key\n  // they arrive under (e.g. a generic `value` field holding a Slack webhook).\n  if (\n    /^https?:\\/\\/(hooks\\.slack\\.com\\/|[^/]*\\.webhook\\.office\\.com\\/|(canary\\.|ptb\\.)?discord(app)?\\.com\\/api\\/webhooks\\/|hooks\\.zapier\\.com\\/|maker\\.ifttt\\.com\\/|discord\\.com\\/api\\/webhooks\\/)/i.test(\n      value,\n    )\n  ) {\n    return true;\n  }\n  return false;\n}\n\nfunction redactString(value: string): string {\n  if (looksSecret(value)) return REDACTED;\n  if (value.length > MAX_STRING) {\n    return `${value.slice(0, MAX_STRING)}…(${value.length - MAX_STRING} more chars)`;\n  }\n  return value;\n}\n\nfunction redact(value: unknown, depth: number): unknown {\n  if (value == null) return value;\n  if (typeof value === \"string\") return redactString(value);\n  if (typeof value === \"number\" || typeof value === \"boolean\") return value;\n  if (depth >= MAX_DEPTH) return \"[…]\";\n  if (Array.isArray(value)) {\n    const out = value.slice(0, MAX_ARRAY).map((v) => redact(v, depth + 1));\n    if (value.length > MAX_ARRAY)\n      out.push(`…(${value.length - MAX_ARRAY} more)`);\n    return out;\n  }\n  if (typeof value === \"object\") {\n    const out: Record<string, unknown> = {};\n    let n = 0;\n    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n      if (n >= MAX_KEYS) {\n        out[\"…\"] = \"(truncated)\";\n        break;\n      }\n      n += 1;\n      out[k] = SENSITIVE_KEY.test(k) ? REDACTED : redact(v, depth + 1);\n    }\n    return out;\n  }\n  // Functions, symbols, bigint, etc. — not serializable / not interesting.\n  return undefined;\n}\n\n/**\n * Redact and serialize call arguments to a capped JSON string, or `null` when\n * there is nothing to record. Never throws.\n */\nexport function redactArgsToJson(args: unknown): string | null {\n  try {\n    if (args == null) return null;\n    const redacted = redact(args, 0);\n    if (redacted === undefined) return null;\n    const json = JSON.stringify(redacted);\n    if (json == null) return null;\n    if (json.length > MAX_JSON) {\n      // Slicing the serialized JSON would yield an unparseable string. Wrap a\n      // preview in a valid envelope so `get-audit-event` can always JSON.parse\n      // the stored `input`.\n      return JSON.stringify({\n        _auditTruncated: true,\n        originalBytes: json.length,\n        preview: json.slice(0, MAX_JSON),\n      });\n    }\n    return json;\n  } catch {\n    return null;\n  }\n}\n\n/** Exposed for tests. */\nexport const __test = { looksSecret, redact, SENSITIVE_KEY };\n"]}

package/dist/audit/store.d.ts

@@ -0,0 +1,14 @@
+import type { AuditEvent, AuditQueryFilters } from "./types.js";
+export declare function ensureAuditTables(): Promise<void>;
+export declare function insertAuditEvent(event: AuditEvent): Promise<void>;
+export interface AuditReadScope {
+    userEmail?: string;
+    orgId?: string | null;
+}
+export declare function queryAuditEvents(scope: AuditReadScope, filters?: AuditQueryFilters): Promise<AuditEvent[]>;
+export declare function getAuditEventById(id: string, scope: AuditReadScope): Promise<AuditEvent | null>;
+/** Purge audit rows older than `cutoffMs`. Returns the deleted row count. */
+export declare function deleteOldAuditEvents(cutoffMs: number): Promise<number>;
+/** Test-only: reset the cached init promise so a fresh DB re-creates tables. */
+export declare function __resetAuditInitForTests(): void;
+//# sourceMappingURL=store.d.ts.map

package/dist/audit/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/audit/store.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAIpB,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAmDvD;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BvE;AAwBD,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AA2CD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,UAAU,EAAE,CAAC,CAsCvB;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAW5B;AAED,6EAA6E;AAC7E,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}