@mastra/factory 0.0.0 → 0.1.0-alpha.3

package/dist/state-signing.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared OAuth/install `state` signing for web integrations.
+ *
+ * Both the GitHub and Linear OAuth flows round-trip a signed `state` value
+ * through the third party to bind the callback to the `(orgId, userId)` tenant
+ * that initiated it (CSRF protection + tenant routing). The signer is a system
+ * facility: `MastraFactory` creates ONE signer at boot and hands it to every
+ * registered integration through `IntegrationContext` (see
+ * `./factory-integration.ts`), so all integrations sign and verify with the
+ * same secret.
+ *
+ * Secret resolution happens in the factory, not here: explicit
+ * `config.stateSecret` → the GitHub integration's webhook secret → a
+ * per-process random secret. A random secret is NOT stable across replicas —
+ * a `state` signed by one replica cannot be verified by another — which is
+ * what the `stable` flag reports. The factory fails loud at boot when a
+ * registered integration requires a stable signer but only a random one is
+ * available.
+ *
+ * The wire format (base64url JSON payload + `.` + HMAC-SHA256 base64url
+ * signature) is unchanged from the previous `github/config.ts` implementation
+ * so in-flight OAuth states survive a deploy.
+ */
+/** Verified `(orgId, userId)` tenant carried by a signed `state`. */
+export interface StateTenant {
+    orgId: string;
+    userId: string;
+}
+/** Signs and verifies OAuth `state` values bound to a `(orgId, userId)` tenant. */
+export interface StateSigner {
+    /** Build a signed `state` bound to the tenant. */
+    sign(orgId: string, userId: string): string;
+    /** Verify a signed `state`; returns the bound tenant, or `null` if invalid. */
+    verify(state: string | undefined): StateTenant | null;
+    /**
+     * True when the signer was built from an explicit deployment-stable secret.
+     * False means a per-process random secret: fine for single-process/local
+     * dev, broken for multi-replica deploys (see module docs).
+     */
+    readonly stable: boolean;
+}
+/**
+ * Create a state signer. With a `secret`, the signer is deployment-stable
+ * (`stable: true`); without one it falls back to a per-process random secret
+ * (`stable: false`).
+ */
+export declare function createStateSigner(secret?: string): StateSigner;
+//# sourceMappingURL=state-signing.d.ts.map

package/dist/state-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-signing.d.ts","sourceRoot":"","sources":["../src/state-signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5C,+EAA+E;IAC/E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAAC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAYD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAwC9D"}

package/dist/state-signing.js

@@ -0,0 +1,48 @@
+// src/state-signing.ts
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+var STATE_MAX_AGE_MS = 10 * 60 * 1e3;
+function createStateSigner(secret) {
+  const stable = typeof secret === "string" && secret.length > 0;
+  const key = stable ? secret : randomBytes(32).toString("hex");
+  return {
+    stable,
+    sign(orgId, userId) {
+      const payload = {
+        orgId,
+        userId,
+        nonce: randomBytes(8).toString("hex"),
+        issuedAt: Date.now()
+      };
+      const body = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+      const sig = createHmac("sha256", key).update(body).digest("base64url");
+      return `${body}.${sig}`;
+    },
+    verify(state) {
+      if (!state) return null;
+      const dot = state.lastIndexOf(".");
+      if (dot <= 0) return null;
+      const body = state.slice(0, dot);
+      const sig = state.slice(dot + 1);
+      const expected = createHmac("sha256", key).update(body).digest("base64url");
+      const sigBuf = Buffer.from(sig);
+      const expectedBuf = Buffer.from(expected);
+      if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
+        return null;
+      }
+      try {
+        const parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+        if (typeof parsed.orgId !== "string" || typeof parsed.userId !== "string") return null;
+        if (typeof parsed.issuedAt !== "number" || !Number.isFinite(parsed.issuedAt)) return null;
+        const age = Date.now() - parsed.issuedAt;
+        if (age < 0 || age > STATE_MAX_AGE_MS) return null;
+        return { orgId: parsed.orgId, userId: parsed.userId };
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+export {
+  createStateSigner
+};
+//# sourceMappingURL=state-signing.js.map

package/dist/state-signing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/state-signing.ts"],"sourcesContent":["/**\n * Shared OAuth/install `state` signing for web integrations.\n *\n * Both the GitHub and Linear OAuth flows round-trip a signed `state` value\n * through the third party to bind the callback to the `(orgId, userId)` tenant\n * that initiated it (CSRF protection + tenant routing). The signer is a system\n * facility: `MastraFactory` creates ONE signer at boot and hands it to every\n * registered integration through `IntegrationContext` (see\n * `./factory-integration.ts`), so all integrations sign and verify with the\n * same secret.\n *\n * Secret resolution happens in the factory, not here: explicit\n * `config.stateSecret` → the GitHub integration's webhook secret → a\n * per-process random secret. A random secret is NOT stable across replicas —\n * a `state` signed by one replica cannot be verified by another — which is\n * what the `stable` flag reports. The factory fails loud at boot when a\n * registered integration requires a stable signer but only a random one is\n * available.\n *\n * The wire format (base64url JSON payload + `.` + HMAC-SHA256 base64url\n * signature) is unchanged from the previous `github/config.ts` implementation\n * so in-flight OAuth states survive a deploy.\n */\n\nimport { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';\n\n/** Verified `(orgId, userId)` tenant carried by a signed `state`. */\nexport interface StateTenant {\n  orgId: string;\n  userId: string;\n}\n\n/** Signs and verifies OAuth `state` values bound to a `(orgId, userId)` tenant. */\nexport interface StateSigner {\n  /** Build a signed `state` bound to the tenant. */\n  sign(orgId: string, userId: string): string;\n  /** Verify a signed `state`; returns the bound tenant, or `null` if invalid. */\n  verify(state: string | undefined): StateTenant | null;\n  /**\n   * True when the signer was built from an explicit deployment-stable secret.\n   * False means a per-process random secret: fine for single-process/local\n   * dev, broken for multi-replica deploys (see module docs).\n   */\n  readonly stable: boolean;\n}\n\ninterface StatePayload {\n  orgId: string;\n  userId: string;\n  nonce: string;\n  issuedAt: number;\n}\n\n/** Signed `state` values expire after this window to bound the CSRF token. */\nconst STATE_MAX_AGE_MS = 10 * 60 * 1000;\n\n/**\n * Create a state signer. With a `secret`, the signer is deployment-stable\n * (`stable: true`); without one it falls back to a per-process random secret\n * (`stable: false`).\n */\nexport function createStateSigner(secret?: string): StateSigner {\n  const stable = typeof secret === 'string' && secret.length > 0;\n  const key = stable ? secret : randomBytes(32).toString('hex');\n  return {\n    stable,\n    sign(orgId: string, userId: string): string {\n      const payload: StatePayload = {\n        orgId,\n        userId,\n        nonce: randomBytes(8).toString('hex'),\n        issuedAt: Date.now(),\n      };\n      const body = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');\n      const sig = createHmac('sha256', key).update(body).digest('base64url');\n      return `${body}.${sig}`;\n    },\n    verify(state: string | undefined): StateTenant | null {\n      if (!state) return null;\n      const dot = state.lastIndexOf('.');\n      if (dot <= 0) return null;\n      const body = state.slice(0, dot);\n      const sig = state.slice(dot + 1);\n      const expected = createHmac('sha256', key).update(body).digest('base64url');\n      const sigBuf = Buffer.from(sig);\n      const expectedBuf = Buffer.from(expected);\n      if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {\n        return null;\n      }\n      try {\n        const parsed = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as StatePayload;\n        if (typeof parsed.orgId !== 'string' || typeof parsed.userId !== 'string') return null;\n        if (typeof parsed.issuedAt !== 'number' || !Number.isFinite(parsed.issuedAt)) return null;\n        const age = Date.now() - parsed.issuedAt;\n        if (age < 0 || age > STATE_MAX_AGE_MS) return null;\n        return { orgId: parsed.orgId, userId: parsed.userId };\n      } catch {\n        return null;\n      }\n    },\n  };\n}\n"],"mappings":";AAwBA,SAAS,YAAY,aAAa,uBAAuB;AA8BzD,IAAM,mBAAmB,KAAK,KAAK;AAO5B,SAAS,kBAAkB,QAA8B;AAC9D,QAAM,SAAS,OAAO,WAAW,YAAY,OAAO,SAAS;AAC7D,QAAM,MAAM,SAAS,SAAS,YAAY,EAAE,EAAE,SAAS,KAAK;AAC5D,SAAO;AAAA,IACL;AAAA,IACA,KAAK,OAAe,QAAwB;AAC1C,YAAM,UAAwB;AAAA,QAC5B;AAAA,QACA;AAAA,QACA,OAAO,YAAY,CAAC,EAAE,SAAS,KAAK;AAAA,QACpC,UAAU,KAAK,IAAI;AAAA,MACrB;AACA,YAAM,OAAO,OAAO,KAAK,KAAK,UAAU,OAAO,GAAG,MAAM,EAAE,SAAS,WAAW;AAC9E,YAAM,MAAM,WAAW,UAAU,GAAG,EAAE,OAAO,IAAI,EAAE,OAAO,WAAW;AACrE,aAAO,GAAG,IAAI,IAAI,GAAG;AAAA,IACvB;AAAA,IACA,OAAO,OAA+C;AACpD,UAAI,CAAC,MAAO,QAAO;AACnB,YAAM,MAAM,MAAM,YAAY,GAAG;AACjC,UAAI,OAAO,EAAG,QAAO;AACrB,YAAM,OAAO,MAAM,MAAM,GAAG,GAAG;AAC/B,YAAM,MAAM,MAAM,MAAM,MAAM,CAAC;AAC/B,YAAM,WAAW,WAAW,UAAU,GAAG,EAAE,OAAO,IAAI,EAAE,OAAO,WAAW;AAC1E,YAAM,SAAS,OAAO,KAAK,GAAG;AAC9B,YAAM,cAAc,OAAO,KAAK,QAAQ;AACxC,UAAI,OAAO,WAAW,YAAY,UAAU,CAAC,gBAAgB,QAAQ,WAAW,GAAG;AACjF,eAAO;AAAA,MACT;AACA,UAAI;AACF,cAAM,SAAS,KAAK,MAAM,OAAO,KAAK,MAAM,WAAW,EAAE,SAAS,MAAM,CAAC;AACzE,YAAI,OAAO,OAAO,UAAU,YAAY,OAAO,OAAO,WAAW,SAAU,QAAO;AAClF,YAAI,OAAO,OAAO,aAAa,YAAY,CAAC,OAAO,SAAS,OAAO,QAAQ,EAAG,QAAO;AACrF,cAAM,MAAM,KAAK,IAAI,IAAI,OAAO;AAChC,YAAI,MAAM,KAAK,MAAM,iBAAkB,QAAO;AAC9C,eAAO,EAAE,OAAO,OAAO,OAAO,QAAQ,OAAO,OAAO;AAAA,MACtD,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/storage/domains/audit/agent-audit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent-level audit event detection (Audit v1.1).
+ *
+ * Git actions performed by agents inside runs never touch web routes, so this
+ * observer detects externally-visible git side effects and delegates recording
+ * to the factory-owned audit domain.
+ */
+import type { RequestContext } from '@mastra/core/request-context';
+import type { AuditAgentEmitter } from './domain.js';
+interface ToolObserverContext {
+    toolName: string;
+    input: unknown;
+    output?: unknown;
+    error?: unknown;
+    context: RequestContext;
+}
+/**
+ * Detect externally-visible git side effects in a completed tool call and
+ * record `factory.agent.*` audit events for them. One command can emit
+ * multiple events (`git commit && git push` emits both). Never throws.
+ */
+export declare function observeAgentGitAction({ audit, toolContext, }: {
+    audit: AuditAgentEmitter;
+    toolContext: ToolObserverContext;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=agent-audit.d.ts.map

package/dist/storage/domains/audit/agent-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-audit.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/audit/agent-audit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,cAAc,CAAC;CACzB;AAgCD;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,KAAK,EACL,WAAW,GACZ,EAAE;IACD,KAAK,EAAE,iBAAiB,CAAC;IACzB,WAAW,EAAE,mBAAmB,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqChB"}

package/dist/storage/domains/audit/agent-audit.js

@@ -0,0 +1,65 @@
+// src/storage/domains/audit/agent-audit.ts
+var GIT_COMMIT_RE = /(?:^|\n|;|&&|\|\|)\s*git\s+commit(?:\s|$)/;
+var GIT_PUSH_RE = /(?:^|\n|;|&&|\|\|)\s*git\s+push(?:\s|$)/;
+function stripHeredocBodies(command) {
+  const lines = command.split("\n");
+  const executableLines = [];
+  let delimiter;
+  for (const line of lines) {
+    if (delimiter) {
+      if (line.trim() === delimiter) delimiter = void 0;
+      continue;
+    }
+    executableLines.push(line);
+    const heredoc = line.match(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/);
+    delimiter = heredoc?.[2];
+  }
+  return executableLines.join("\n");
+}
+function parsePushedBranch(command) {
+  const match = command.match(
+    /(?:^|\n|;|&&|\|\|)\s*git\s+push\s+(?:-[^\s]+\s+)*([^\s;&|-][^\s;&|]*)\s+([^\s;&|-][^\s;&|]*)/
+  );
+  return match?.[2];
+}
+async function observeAgentGitAction({
+  audit,
+  toolContext
+}) {
+  try {
+    if (toolContext.toolName !== "execute_command" || toolContext.error) return;
+    const rawCommand = toolContext.input?.command;
+    if (typeof rawCommand !== "string") return;
+    const command = stripHeredocBodies(rawCommand);
+    const controller = toolContext.context.get("controller");
+    const worktreePath = controller?.scope;
+    if (GIT_COMMIT_RE.test(command)) {
+      await audit.emitAgent({
+        requestContext: toolContext.context,
+        input: {
+          action: "factory.agent.commit",
+          targets: worktreePath ? [{ type: "worktree", id: worktreePath }] : []
+        }
+      });
+    }
+    if (GIT_PUSH_RE.test(command)) {
+      const branch = parsePushedBranch(command);
+      await audit.emitAgent({
+        requestContext: toolContext.context,
+        input: {
+          action: "factory.agent.push",
+          targets: worktreePath ? [{ type: "worktree", id: worktreePath }] : [],
+          ...branch ? { metadata: { branch } } : {}
+        }
+      });
+    }
+  } catch (err) {
+    console.warn("[Audit] Failed to observe agent git action", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+export {
+  observeAgentGitAction
+};
+//# sourceMappingURL=agent-audit.js.map

package/dist/storage/domains/audit/agent-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/storage/domains/audit/agent-audit.ts"],"sourcesContent":["/**\n * Agent-level audit event detection (Audit v1.1).\n *\n * Git actions performed by agents inside runs never touch web routes, so this\n * observer detects externally-visible git side effects and delegates recording\n * to the factory-owned audit domain.\n */\n\nimport type { AgentControllerRequestContext } from '@mastra/core/agent-controller';\nimport type { RequestContext } from '@mastra/core/request-context';\n\nimport type { AuditAgentEmitter } from './domain.js';\n\ntype FactorySessionState = { factoryProjectId?: string; projectRepositoryId?: string };\n\ninterface ToolObserverContext {\n  toolName: string;\n  input: unknown;\n  output?: unknown;\n  error?: unknown;\n  context: RequestContext;\n}\n\n/** Match command-start positions while ignoring command text embedded in heredoc bodies. */\nconst GIT_COMMIT_RE = /(?:^|\\n|;|&&|\\|\\|)\\s*git\\s+commit(?:\\s|$)/;\nconst GIT_PUSH_RE = /(?:^|\\n|;|&&|\\|\\|)\\s*git\\s+push(?:\\s|$)/;\n\nfunction stripHeredocBodies(command: string): string {\n  const lines = command.split('\\n');\n  const executableLines: string[] = [];\n  let delimiter: string | undefined;\n\n  for (const line of lines) {\n    if (delimiter) {\n      if (line.trim() === delimiter) delimiter = undefined;\n      continue;\n    }\n    executableLines.push(line);\n    const heredoc = line.match(/<<-?\\s*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\\1/);\n    delimiter = heredoc?.[2];\n  }\n\n  return executableLines.join('\\n');\n}\n\n/** Parse the branch from a plain `git push <remote> <branch>` invocation. */\nfunction parsePushedBranch(command: string): string | undefined {\n  const match = command.match(\n    /(?:^|\\n|;|&&|\\|\\|)\\s*git\\s+push\\s+(?:-[^\\s]+\\s+)*([^\\s;&|-][^\\s;&|]*)\\s+([^\\s;&|-][^\\s;&|]*)/,\n  );\n  return match?.[2];\n}\n\n/**\n * Detect externally-visible git side effects in a completed tool call and\n * record `factory.agent.*` audit events for them. One command can emit\n * multiple events (`git commit && git push` emits both). Never throws.\n */\nexport async function observeAgentGitAction({\n  audit,\n  toolContext,\n}: {\n  audit: AuditAgentEmitter;\n  toolContext: ToolObserverContext;\n}): Promise<void> {\n  try {\n    if (toolContext.toolName !== 'execute_command' || toolContext.error) return;\n    const rawCommand = (toolContext.input as { command?: unknown } | undefined)?.command;\n    if (typeof rawCommand !== 'string') return;\n    const command = stripHeredocBodies(rawCommand);\n\n    const controller = toolContext.context.get('controller') as\n      AgentControllerRequestContext<FactorySessionState> | undefined;\n    const worktreePath = controller?.scope;\n\n    if (GIT_COMMIT_RE.test(command)) {\n      await audit.emitAgent({\n        requestContext: toolContext.context,\n        input: {\n          action: 'factory.agent.commit',\n          targets: worktreePath ? [{ type: 'worktree', id: worktreePath }] : [],\n        },\n      });\n    }\n\n    if (GIT_PUSH_RE.test(command)) {\n      const branch = parsePushedBranch(command);\n      await audit.emitAgent({\n        requestContext: toolContext.context,\n        input: {\n          action: 'factory.agent.push',\n          targets: worktreePath ? [{ type: 'worktree', id: worktreePath }] : [],\n          ...(branch ? { metadata: { branch } } : {}),\n        },\n      });\n    }\n  } catch (err) {\n    console.warn('[Audit] Failed to observe agent git action', {\n      error: err instanceof Error ? err.message : String(err),\n    });\n  }\n}\n"],"mappings":";AAwBA,IAAM,gBAAgB;AACtB,IAAM,cAAc;AAEpB,SAAS,mBAAmB,SAAyB;AACnD,QAAM,QAAQ,QAAQ,MAAM,IAAI;AAChC,QAAM,kBAA4B,CAAC;AACnC,MAAI;AAEJ,aAAW,QAAQ,OAAO;AACxB,QAAI,WAAW;AACb,UAAI,KAAK,KAAK,MAAM,UAAW,aAAY;AAC3C;AAAA,IACF;AACA,oBAAgB,KAAK,IAAI;AACzB,UAAM,UAAU,KAAK,MAAM,0CAA0C;AACrE,gBAAY,UAAU,CAAC;AAAA,EACzB;AAEA,SAAO,gBAAgB,KAAK,IAAI;AAClC;AAGA,SAAS,kBAAkB,SAAqC;AAC9D,QAAM,QAAQ,QAAQ;AAAA,IACpB;AAAA,EACF;AACA,SAAO,QAAQ,CAAC;AAClB;AAOA,eAAsB,sBAAsB;AAAA,EAC1C;AAAA,EACA;AACF,GAGkB;AAChB,MAAI;AACF,QAAI,YAAY,aAAa,qBAAqB,YAAY,MAAO;AACrE,UAAM,aAAc,YAAY,OAA6C;AAC7E,QAAI,OAAO,eAAe,SAAU;AACpC,UAAM,UAAU,mBAAmB,UAAU;AAE7C,UAAM,aAAa,YAAY,QAAQ,IAAI,YAAY;AAEvD,UAAM,eAAe,YAAY;AAEjC,QAAI,cAAc,KAAK,OAAO,GAAG;AAC/B,YAAM,MAAM,UAAU;AAAA,QACpB,gBAAgB,YAAY;AAAA,QAC5B,OAAO;AAAA,UACL,QAAQ;AAAA,UACR,SAAS,eAAe,CAAC,EAAE,MAAM,YAAY,IAAI,aAAa,CAAC,IAAI,CAAC;AAAA,QACtE;AAAA,MACF,CAAC;AAAA,IACH;AAEA,QAAI,YAAY,KAAK,OAAO,GAAG;AAC7B,YAAM,SAAS,kBAAkB,OAAO;AACxC,YAAM,MAAM,UAAU;AAAA,QACpB,gBAAgB,YAAY;AAAA,QAC5B,OAAO;AAAA,UACL,QAAQ;AAAA,UACR,SAAS,eAAe,CAAC,EAAE,MAAM,YAAY,IAAI,aAAa,CAAC,IAAI,CAAC;AAAA,UACpE,GAAI,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,QAC3C;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF,SAAS,KAAK;AACZ,YAAQ,KAAK,8CAA8C;AAAA,MACzD,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IACxD,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/storage/domains/audit/base.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Factory audit events domain — the append-only "who did what, when" trail
+ * behind the software factory.
+ *
+ * One `audit_events` row records a single audited mutation (work-item change,
+ * stage move, run start, worktree create/delete, git action, intake config
+ * change). Rows are append-only: there is no update/delete API, and the table
+ * is the local source of truth even when the WorkOS Audit Logs mirror is
+ * unavailable.
+ *
+ * Tenancy is **org-first**, like `work_items`: events are scoped by `org_id`
+ * and (usually) `factory_project_id`; `actor_id` records who acted but never
+ * scopes reads.
+ *
+ * v1 action taxonomy (register these in the WorkOS dashboard under
+ * Audit Logs → Events for the export mirror to accept them):
+ *   - factory.work_item.created
+ *   - factory.work_item.updated
+ *   - factory.work_item.stage_moved
+ *   - factory.work_item.deleted
+ *   - factory.run.started
+ *   - factory.worktree.created
+ *   - factory.worktree.deleted
+ *   - factory.triage.started
+ *   - factory.git.commit
+ *   - factory.git.push
+ *   - factory.git.pr_opened
+ *   - factory.intake.config_updated
+ *
+ * v1.1 adds agent-level actions (also register these in WorkOS):
+ *   - factory.agent.commit
+ *   - factory.agent.push
+ *   - factory.agent.pr_opened
+ *
+ * Agent events carry `actor_type = 'agent'` with `actor_id = 'agent:<threadId>'`
+ * and `metadata.startedBy = <userId>` chaining accountability back to the human
+ * whose message drove the run.
+ */
+import { FactoryStorageDomain } from '@mastra/core/storage';
+import type { CollectionSchema } from '@mastra/core/storage';
+/** What an audit event acted on (WorkOS Audit Logs target shape). */
+export interface AuditTarget {
+    /** Target kind, e.g. 'work_item', 'worktree', 'issue', 'pull_request'. */
+    type: string;
+    /** Stable identifier of the target (row id, branch name, issue number...). */
+    id: string;
+    /** Human-readable label (work-item title, branch name...). */
+    name?: string;
+}
+/** Who performed the audited action. */
+export type AuditActorType = 'human' | 'agent';
+/** Request context captured alongside the event. */
+export interface AuditContext {
+    /** Client IP (first hop of `x-forwarded-for`) when available. */
+    location?: string;
+    /** Request `user-agent` header when available. */
+    userAgent?: string;
+}
+/** One persisted audit event. */
+export interface AuditEventRow {
+    id: string;
+    /** Owning WorkOS organization id — the trail is org-wide. */
+    orgId: string;
+    /** WorkOS user id of whoever performed the action, or `agent:<threadId>`. */
+    actorId: string;
+    /** Whether a human or an agent (inside a run) performed the action. */
+    actorType: AuditActorType;
+    /** Dot-namespaced action, e.g. 'factory.work_item.stage_moved'. */
+    action: string;
+    /** What was acted on. */
+    targets: AuditTarget[];
+    /** Bounded event summary — never full payloads, never secrets. */
+    metadata: Record<string, unknown>;
+    /** Factory project the event is scoped to; null for org-level events. */
+    factoryProjectId: string | null;
+    /** Project-repository link affected by a repository-specific action. */
+    projectRepositoryId: string | null;
+    /** Request context (`x-forwarded-for` / `user-agent`). */
+    context: AuditContext;
+    occurredAt: Date;
+}
+export interface RecordAuditEventInput {
+    orgId: string;
+    actorId: string;
+    /** Who performed the action; defaults to 'human'. */
+    actorType?: AuditActorType;
+    /** Dot-namespaced action, e.g. 'factory.work_item.stage_moved'. */
+    action: string;
+    targets: AuditTarget[];
+    metadata?: Record<string, unknown>;
+    factoryProjectId?: string;
+    projectRepositoryId?: string;
+    context?: AuditContext;
+    occurredAt?: Date;
+}
+/** A fully-normalized event ready to persist (id assigned on insert). */
+export type AuditEventInsert = Omit<AuditEventRow, 'id'>;
+export interface ListAuditEventsInput {
+    orgId: string;
+    factoryProjectId?: string;
+    /** Restrict to these actions (exact match). */
+    actions?: string[];
+    actorId?: string;
+    /** Opaque cursor from a previous page (`nextCursor`). */
+    before?: string;
+    limit?: number;
+}
+export interface AuditEventPage {
+    events: AuditEventRow[];
+    /** Pass back as `before` to fetch the next (older) page; absent at the end. */
+    nextCursor?: string;
+}
+/** Truncate oversized metadata rather than dropping the whole event. */
+export declare function boundAuditMetadata(metadata: Record<string, unknown> | undefined): Record<string, unknown>;
+/** Normalize a requested page size to a finite integer in `[1, MAX_PAGE_SIZE]`. */
+export declare function clampAuditLimit(limit: number | undefined): number;
+/** Encode the `(occurredAt, id)` keyset cursor of a row. */
+export declare function encodeAuditCursor(row: AuditEventRow): string;
+/** Decode a cursor back into its `(occurredAt, id)` parts, or `undefined`. */
+export declare function decodeAuditCursor(cursor: string): {
+    occurredAt: Date;
+    id: string;
+} | undefined;
+export declare const AUDIT_EVENTS_SCHEMA: CollectionSchema;
+/**
+ * Audit event storage, written once against the generic `FactoryStorageOps`
+ * surface. `record()` normalizes inputs (defaults, metadata bounding);
+ * `list()` is keyset-paginated on `(occurred_at, id)` newest-first.
+ */
+export declare class AuditStorage extends FactoryStorageDomain {
+    #private;
+    constructor();
+    init(): Promise<void>;
+    dangerouslyClearAll(): Promise<void>;
+    /** Append one audit event. Throws on failure — swallow-on-failure lives in the caller. */
+    record(input: RecordAuditEventInput): Promise<AuditEventRow>;
+    /** List an org's audit events newest-first with keyset pagination. */
+    list(input: ListAuditEventsInput): Promise<AuditEventPage>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/storage/domains/audit/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/audit/base.ts"],"names":[],"mappings":"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"}

package/dist/storage/domains/audit/base.js

@@ -0,0 +1,127 @@
+// src/storage/domains/audit/base.ts
+import { FactoryStorageDomain } from "@mastra/core/storage";
+var MAX_METADATA_JSON_LENGTH = 4096;
+var DEFAULT_PAGE_SIZE = 50;
+var MAX_PAGE_SIZE = 200;
+function boundAuditMetadata(metadata) {
+  if (!metadata) return {};
+  try {
+    if (JSON.stringify(metadata).length <= MAX_METADATA_JSON_LENGTH) return metadata;
+  } catch {
+    return { truncated: true };
+  }
+  return { truncated: true };
+}
+function clampAuditLimit(limit) {
+  const normalized = typeof limit === "number" && Number.isFinite(limit) ? Math.trunc(limit) : DEFAULT_PAGE_SIZE;
+  return Math.min(Math.max(normalized, 1), MAX_PAGE_SIZE);
+}
+function encodeAuditCursor(row) {
+  return `${row.occurredAt.toISOString()}_${row.id}`;
+}
+function decodeAuditCursor(cursor) {
+  const sep = cursor.lastIndexOf("_");
+  if (sep <= 0) return void 0;
+  const occurredAt = new Date(cursor.slice(0, sep));
+  const id = cursor.slice(sep + 1);
+  if (Number.isNaN(occurredAt.getTime()) || !id) return void 0;
+  return { occurredAt, id };
+}
+var AUDIT_EVENTS_SCHEMA = {
+  name: "audit_events",
+  columns: {
+    id: { type: "uuid-pk" },
+    org_id: { type: "text" },
+    actor_id: { type: "text" },
+    actor_type: { type: "text", default: "human" },
+    action: { type: "text" },
+    targets: { type: "json" },
+    metadata: { type: "json" },
+    factory_project_id: { type: "text", nullable: true },
+    project_repository_id: { type: "text", nullable: true },
+    context: { type: "json" },
+    occurred_at: { type: "timestamp" }
+  },
+  indexes: [
+    { name: "audit_events_org_occurred_idx", columns: ["org_id", "occurred_at"] },
+    { name: "audit_events_org_project_occurred_idx", columns: ["org_id", "factory_project_id", "occurred_at"] }
+  ]
+};
+function toRow(db) {
+  return {
+    id: db.id,
+    orgId: db.org_id,
+    actorId: db.actor_id,
+    actorType: db.actor_type,
+    action: db.action,
+    targets: db.targets,
+    metadata: db.metadata,
+    factoryProjectId: db.factory_project_id,
+    projectRepositoryId: db.project_repository_id,
+    context: db.context,
+    occurredAt: db.occurred_at
+  };
+}
+var AuditStorage = class extends FactoryStorageDomain {
+  constructor() {
+    super("audit");
+  }
+  async init() {
+    await this.ensureCollections([AUDIT_EVENTS_SCHEMA]);
+  }
+  async dangerouslyClearAll() {
+    await this.ops.deleteMany("audit_events", {});
+  }
+  get #db() {
+    return this.ops;
+  }
+  /** Append one audit event. Throws on failure — swallow-on-failure lives in the caller. */
+  async record(input) {
+    const inserted = await this.#db.insertOne("audit_events", {
+      org_id: input.orgId,
+      actor_id: input.actorId,
+      actor_type: input.actorType ?? "human",
+      action: input.action,
+      targets: input.targets,
+      metadata: boundAuditMetadata(input.metadata),
+      factory_project_id: input.factoryProjectId ?? null,
+      project_repository_id: input.projectRepositoryId ?? null,
+      context: input.context ?? {},
+      occurred_at: input.occurredAt ?? /* @__PURE__ */ new Date()
+    });
+    return toRow(inserted);
+  }
+  /** List an org's audit events newest-first with keyset pagination. */
+  async list(input) {
+    const limit = clampAuditLimit(input.limit);
+    const where = { org_id: input.orgId };
+    if (input.factoryProjectId) where.factory_project_id = input.factoryProjectId;
+    if (input.actions && input.actions.length > 0) where.action = { in: input.actions };
+    if (input.actorId) where.actor_id = input.actorId;
+    const cursor = input.before ? decodeAuditCursor(input.before) : void 0;
+    const rows = await this.#db.findMany("audit_events", where, {
+      orderBy: [
+        ["occurred_at", "desc"],
+        ["id", "desc"]
+      ],
+      limit: limit + 1,
+      ...cursor ? { cursor: { values: [cursor.occurredAt, cursor.id] } } : {}
+    });
+    const events = rows.slice(0, limit).map(toRow);
+    const hasMore = rows.length > limit;
+    const last = events[events.length - 1];
+    return {
+      events,
+      ...hasMore && last ? { nextCursor: encodeAuditCursor(last) } : {}
+    };
+  }
+};
+export {
+  AUDIT_EVENTS_SCHEMA,
+  AuditStorage,
+  boundAuditMetadata,
+  clampAuditLimit,
+  decodeAuditCursor,
+  encodeAuditCursor
+};
+//# sourceMappingURL=base.js.map

package/dist/storage/domains/audit/base.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/storage/domains/audit/base.ts"],"sourcesContent":["/**\n * Factory audit events domain — the append-only \"who did what, when\" trail\n * behind the software factory.\n *\n * One `audit_events` row records a single audited mutation (work-item change,\n * stage move, run start, worktree create/delete, git action, intake config\n * change). Rows are append-only: there is no update/delete API, and the table\n * is the local source of truth even when the WorkOS Audit Logs mirror is\n * unavailable.\n *\n * Tenancy is **org-first**, like `work_items`: events are scoped by `org_id`\n * and (usually) `factory_project_id`; `actor_id` records who acted but never\n * scopes reads.\n *\n * v1 action taxonomy (register these in the WorkOS dashboard under\n * Audit Logs → Events for the export mirror to accept them):\n *   - factory.work_item.created\n *   - factory.work_item.updated\n *   - factory.work_item.stage_moved\n *   - factory.work_item.deleted\n *   - factory.run.started\n *   - factory.worktree.created\n *   - factory.worktree.deleted\n *   - factory.triage.started\n *   - factory.git.commit\n *   - factory.git.push\n *   - factory.git.pr_opened\n *   - factory.intake.config_updated\n *\n * v1.1 adds agent-level actions (also register these in WorkOS):\n *   - factory.agent.commit\n *   - factory.agent.push\n *   - factory.agent.pr_opened\n *\n * Agent events carry `actor_type = 'agent'` with `actor_id = 'agent:<threadId>'`\n * and `metadata.startedBy = <userId>` chaining accountability back to the human\n * whose message drove the run.\n */\n\nimport { FactoryStorageDomain } from '@mastra/core/storage';\nimport type { CollectionSchema, CollectionWhere, FactoryStorageOps } from '@mastra/core/storage';\n\n/** What an audit event acted on (WorkOS Audit Logs target shape). */\nexport interface AuditTarget {\n  /** Target kind, e.g. 'work_item', 'worktree', 'issue', 'pull_request'. */\n  type: string;\n  /** Stable identifier of the target (row id, branch name, issue number...). */\n  id: string;\n  /** Human-readable label (work-item title, branch name...). */\n  name?: string;\n}\n\n/** Who performed the audited action. */\nexport type AuditActorType = 'human' | 'agent';\n\n/** Request context captured alongside the event. */\nexport interface AuditContext {\n  /** Client IP (first hop of `x-forwarded-for`) when available. */\n  location?: string;\n  /** Request `user-agent` header when available. */\n  userAgent?: string;\n}\n\n/** One persisted audit event. */\nexport interface AuditEventRow {\n  id: string;\n  /** Owning WorkOS organization id — the trail is org-wide. */\n  orgId: string;\n  /** WorkOS user id of whoever performed the action, or `agent:<threadId>`. */\n  actorId: string;\n  /** Whether a human or an agent (inside a run) performed the action. */\n  actorType: AuditActorType;\n  /** Dot-namespaced action, e.g. 'factory.work_item.stage_moved'. */\n  action: string;\n  /** What was acted on. */\n  targets: AuditTarget[];\n  /** Bounded event summary — never full payloads, never secrets. */\n  metadata: Record<string, unknown>;\n  /** Factory project the event is scoped to; null for org-level events. */\n  factoryProjectId: string | null;\n  /** Project-repository link affected by a repository-specific action. */\n  projectRepositoryId: string | null;\n  /** Request context (`x-forwarded-for` / `user-agent`). */\n  context: AuditContext;\n  occurredAt: Date;\n}\n\nexport interface RecordAuditEventInput {\n  orgId: string;\n  actorId: string;\n  /** Who performed the action; defaults to 'human'. */\n  actorType?: AuditActorType;\n  /** Dot-namespaced action, e.g. 'factory.work_item.stage_moved'. */\n  action: string;\n  targets: AuditTarget[];\n  metadata?: Record<string, unknown>;\n  factoryProjectId?: string;\n  projectRepositoryId?: string;\n  context?: AuditContext;\n  occurredAt?: Date;\n}\n\n/** A fully-normalized event ready to persist (id assigned on insert). */\nexport type AuditEventInsert = Omit<AuditEventRow, 'id'>;\n\nexport interface ListAuditEventsInput {\n  orgId: string;\n  factoryProjectId?: string;\n  /** Restrict to these actions (exact match). */\n  actions?: string[];\n  actorId?: string;\n  /** Opaque cursor from a previous page (`nextCursor`). */\n  before?: string;\n  limit?: number;\n}\n\nexport interface AuditEventPage {\n  events: AuditEventRow[];\n  /** Pass back as `before` to fetch the next (older) page; absent at the end. */\n  nextCursor?: string;\n}\n\n/** Metadata is a bounded summary — never full payloads, never secrets. */\nconst MAX_METADATA_JSON_LENGTH = 4096;\n\nconst DEFAULT_PAGE_SIZE = 50;\nconst MAX_PAGE_SIZE = 200;\n\n/** Truncate oversized metadata rather than dropping the whole event. */\nexport function boundAuditMetadata(metadata: Record<string, unknown> | undefined): Record<string, unknown> {\n  if (!metadata) return {};\n  try {\n    if (JSON.stringify(metadata).length <= MAX_METADATA_JSON_LENGTH) return metadata;\n  } catch {\n    return { truncated: true };\n  }\n  return { truncated: true };\n}\n\n/** Normalize a requested page size to a finite integer in `[1, MAX_PAGE_SIZE]`. */\nexport function clampAuditLimit(limit: number | undefined): number {\n  const normalized = typeof limit === 'number' && Number.isFinite(limit) ? Math.trunc(limit) : DEFAULT_PAGE_SIZE;\n  return Math.min(Math.max(normalized, 1), MAX_PAGE_SIZE);\n}\n\n/** Encode the `(occurredAt, id)` keyset cursor of a row. */\nexport function encodeAuditCursor(row: AuditEventRow): string {\n  return `${row.occurredAt.toISOString()}_${row.id}`;\n}\n\n/** Decode a cursor back into its `(occurredAt, id)` parts, or `undefined`. */\nexport function decodeAuditCursor(cursor: string): { occurredAt: Date; id: string } | undefined {\n  const sep = cursor.lastIndexOf('_');\n  if (sep <= 0) return undefined;\n  const occurredAt = new Date(cursor.slice(0, sep));\n  const id = cursor.slice(sep + 1);\n  if (Number.isNaN(occurredAt.getTime()) || !id) return undefined;\n  return { occurredAt, id };\n}\n\nexport const AUDIT_EVENTS_SCHEMA: CollectionSchema = {\n  name: 'audit_events',\n  columns: {\n    id: { type: 'uuid-pk' },\n    org_id: { type: 'text' },\n    actor_id: { type: 'text' },\n    actor_type: { type: 'text', default: 'human' },\n    action: { type: 'text' },\n    targets: { type: 'json' },\n    metadata: { type: 'json' },\n    factory_project_id: { type: 'text', nullable: true },\n    project_repository_id: { type: 'text', nullable: true },\n    context: { type: 'json' },\n    occurred_at: { type: 'timestamp' },\n  },\n  indexes: [\n    { name: 'audit_events_org_occurred_idx', columns: ['org_id', 'occurred_at'] },\n    { name: 'audit_events_org_project_occurred_idx', columns: ['org_id', 'factory_project_id', 'occurred_at'] },\n  ],\n};\n\n/** Column shape of one `audit_events` row as returned by ops. */\ninterface AuditEventDbRow extends Record<string, unknown> {\n  id: string;\n  org_id: string;\n  actor_id: string;\n  actor_type: AuditActorType;\n  action: string;\n  targets: AuditTarget[];\n  metadata: Record<string, unknown>;\n  factory_project_id: string | null;\n  project_repository_id: string | null;\n  context: AuditContext;\n  occurred_at: Date;\n}\n\nfunction toRow(db: AuditEventDbRow): AuditEventRow {\n  return {\n    id: db.id,\n    orgId: db.org_id,\n    actorId: db.actor_id,\n    actorType: db.actor_type,\n    action: db.action,\n    targets: db.targets,\n    metadata: db.metadata,\n    factoryProjectId: db.factory_project_id,\n    projectRepositoryId: db.project_repository_id,\n    context: db.context,\n    occurredAt: db.occurred_at,\n  };\n}\n\n/**\n * Audit event storage, written once against the generic `FactoryStorageOps`\n * surface. `record()` normalizes inputs (defaults, metadata bounding);\n * `list()` is keyset-paginated on `(occurred_at, id)` newest-first.\n */\nexport class AuditStorage extends FactoryStorageDomain {\n  constructor() {\n    super('audit');\n  }\n\n  async init(): Promise<void> {\n    await this.ensureCollections([AUDIT_EVENTS_SCHEMA]);\n  }\n\n  async dangerouslyClearAll(): Promise<void> {\n    await this.ops.deleteMany('audit_events', {});\n  }\n\n  get #db(): FactoryStorageOps {\n    return this.ops;\n  }\n\n  /** Append one audit event. Throws on failure — swallow-on-failure lives in the caller. */\n  async record(input: RecordAuditEventInput): Promise<AuditEventRow> {\n    const inserted = await this.#db.insertOne<AuditEventDbRow>('audit_events', {\n      org_id: input.orgId,\n      actor_id: input.actorId,\n      actor_type: input.actorType ?? 'human',\n      action: input.action,\n      targets: input.targets,\n      metadata: boundAuditMetadata(input.metadata),\n      factory_project_id: input.factoryProjectId ?? null,\n      project_repository_id: input.projectRepositoryId ?? null,\n      context: input.context ?? {},\n      occurred_at: input.occurredAt ?? new Date(),\n    });\n    return toRow(inserted);\n  }\n\n  /** List an org's audit events newest-first with keyset pagination. */\n  async list(input: ListAuditEventsInput): Promise<AuditEventPage> {\n    const limit = clampAuditLimit(input.limit);\n\n    const where: CollectionWhere = { org_id: input.orgId };\n    if (input.factoryProjectId) where.factory_project_id = input.factoryProjectId;\n    if (input.actions && input.actions.length > 0) where.action = { in: input.actions };\n    if (input.actorId) where.actor_id = input.actorId;\n\n    const cursor = input.before ? decodeAuditCursor(input.before) : undefined;\n\n    const rows = await this.#db.findMany<AuditEventDbRow>('audit_events', where, {\n      orderBy: [\n        ['occurred_at', 'desc'],\n        ['id', 'desc'],\n      ],\n      limit: limit + 1,\n      ...(cursor ? { cursor: { values: [cursor.occurredAt, cursor.id] } } : {}),\n    });\n\n    const events = rows.slice(0, limit).map(toRow);\n    const hasMore = rows.length > limit;\n    const last = events[events.length - 1];\n    return {\n      events,\n      ...(hasMore && last ? { nextCursor: encodeAuditCursor(last) } : {}),\n    };\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/storage/domains/audit/domain.d.ts

@@ -0,0 +1,69 @@
+import type { RequestContext } from '@mastra/core/request-context';
+import type { ApiRoute } from '@mastra/core/server';
+import type { Context } from 'hono';
+import type { RouteAuth } from '../../../routes/route.js';
+import type { FactoryProjectsStorage } from '../projects/base.js';
+import type { AuditContext, AuditEventPage, AuditEventRow, AuditStorage, AuditTarget, ListAuditEventsInput, RecordAuditEventInput } from './base.js';
+export interface EmitAuditInput {
+    action: string;
+    factoryProjectId?: string;
+    projectRepositoryId?: string;
+    targets: AuditTarget[];
+    metadata?: Record<string, unknown>;
+}
+export interface EmitAgentAuditInput {
+    action: string;
+    targets: AuditTarget[];
+    metadata?: Record<string, unknown>;
+}
+export interface AuditEmitter {
+    emit(args: {
+        context: Context;
+        input: EmitAuditInput;
+    }): Promise<void>;
+}
+export interface AuditAgentEmitter {
+    emitAgent(args: {
+        requestContext: RequestContext;
+        input: EmitAgentAuditInput;
+    }): Promise<void>;
+}
+/** Best-effort destination for locally persisted audit events (e.g. an integration's audit log). */
+export interface AuditSink {
+    id: string;
+    audit?(args: {
+        event: AuditEventRow;
+    }): Promise<void>;
+}
+export interface AuditDomainOptions {
+    auth: RouteAuth;
+    /** Audit storage domain handle. */
+    audit: AuditStorage;
+    /** Projects domain handle, used to scope the audit trail route. */
+    projects: FactoryProjectsStorage;
+    /** Best-effort fan-out destinations notified after each recorded event. */
+    sinks?: AuditSink[];
+    /** Resolve the acting tenant for agent-emitted events from the request context. */
+    agentTenant?: (requestContext: RequestContext) => {
+        orgId?: string;
+        userId?: string;
+    } | undefined;
+}
+export declare function auditRequestContext(c: Context): AuditContext;
+/** Factory-owned audit behavior backed by the audit storage domain. */
+export declare class AuditDomain implements AuditEmitter, AuditAgentEmitter {
+    #private;
+    constructor({ auth, audit, projects, sinks, agentTenant }: AuditDomainOptions);
+    record(input: RecordAuditEventInput): Promise<AuditEventRow | null>;
+    list(input: ListAuditEventsInput): Promise<AuditEventPage>;
+    emit({ context, input }: {
+        context: Context;
+        input: EmitAuditInput;
+    }): Promise<void>;
+    emitAgent({ requestContext, input, }: {
+        requestContext: RequestContext;
+        input: EmitAgentAuditInput;
+    }): Promise<void>;
+    routes(): ApiRoute[];
+}
+//# sourceMappingURL=domain.d.ts.map

package/dist/storage/domains/audit/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/audit/domain.ts"],"names":[],"mappings":"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"}