openclaw-db9-audit 0.1.0

package/index.ts

@@ -0,0 +1,22 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { db9AuditConfigSchema, loadDb9AuditConfig } from "./src/config.js";
+import { registerDb9AuditCli } from "./src/cli.js";
+import { createDb9AuditService } from "./src/service.js";
+
+const plugin = {
+  id: "db9-audit",
+  name: "DB9 Audit",
+  description: "Mirror OpenClaw transcripts and agent events into DB9",
+  configSchema: db9AuditConfigSchema,
+  register(api: OpenClawPluginApi) {
+    const config = loadDb9AuditConfig(api.pluginConfig);
+    const service = createDb9AuditService({ api, config });
+    api.registerService(service);
+    registerDb9AuditCli(api, config);
+    api.on("agent_end", (event, ctx) => {
+      service.handleAgentEnd(event, ctx);
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "db9-audit",
+  "name": "DB9 Audit",
+  "description": "Mirror OpenClaw transcripts and agent events into DB9 for auditing",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "apiBase": { "type": "string", "minLength": 1 },
+      "databaseName": { "type": "string", "minLength": 1 },
+      "databaseRegion": { "type": "string", "minLength": 1 },
+      "schema": { "type": "string", "minLength": 1 },
+      "logRoot": { "type": "string", "minLength": 1 },
+      "batchSize": { "type": "integer", "minimum": 1 },
+      "flushIntervalMs": { "type": "integer", "minimum": 100 },
+      "backfillOnStart": { "type": "boolean" },
+      "redact": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "maxFieldBytes": { "type": "integer", "minimum": 1024 }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "openclaw-db9-audit",
+  "version": "0.1.0",
+  "description": "OpenClaw audit plugin backed by DB9 PostgreSQL and FS WebSocket storage",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "npm@11.6.2",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "src/"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run test"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.2"
+  },
+  "dependencies": {
+    "pg": "^8.13.3",
+    "ws": "^8.18.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "@types/pg": "^8.15.5",
+    "@types/ws": "^8.18.1",
+    "openclaw": "file:../openclaw",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,277 @@
+import type { PluginLogger } from "openclaw/plugin-sdk/core";
+import { Db9ControlPlaneClient, Db9ControlPlaneError } from "./control-plane.js";
+import type {
+  Db9AnonymousRefreshResponse,
+  Db9AuditPluginConfig,
+  Db9AuditState,
+  Db9CustomerResponse,
+  Db9DatabaseCredentialsResponse,
+  Db9DatabaseResponse,
+} from "./types.js";
+import { parseConnectionString, resolveFsWsUrl, toIsoString } from "./utils.js";
+
+export class Db9AuditDatabaseUnavailableError extends Error {
+  readonly databaseId: string;
+  readonly causeCode?: string | undefined;
+
+  constructor(params: { databaseId: string; message: string; causeCode?: string | undefined }) {
+    super(params.message);
+    this.name = "Db9AuditDatabaseUnavailableError";
+    this.databaseId = params.databaseId;
+    this.causeCode = params.causeCode;
+  }
+}
+
+function buildState(params: {
+  config: Db9AuditPluginConfig;
+  apiBase: string;
+  customer: {
+    id: string;
+    token: string;
+    tokenExpiresAt?: string | undefined;
+    anonymousId?: string | undefined;
+    anonymousSecret?: string | undefined;
+    isAnonymous: boolean;
+  };
+  database: {
+    id: string;
+    name: string;
+    state: string;
+    region?: string | undefined;
+    connectionString: string;
+    adminPassword: string;
+  };
+  previous?: Db9AuditState | undefined;
+}): Db9AuditState {
+  const parsed = parseConnectionString(params.database.connectionString);
+  const now = toIsoString();
+
+  return {
+    version: 1,
+    apiBase: params.apiBase,
+    customer: {
+      id: params.customer.id,
+      token: params.customer.token,
+      ...(params.customer.tokenExpiresAt ? { tokenExpiresAt: params.customer.tokenExpiresAt } : {}),
+      isAnonymous: params.customer.isAnonymous,
+      ...(params.customer.anonymousId ? { anonymousId: params.customer.anonymousId } : {}),
+      ...(params.customer.anonymousSecret ? { anonymousSecret: params.customer.anonymousSecret } : {}),
+    },
+    database: {
+      id: params.database.id,
+      name: params.database.name,
+      state: params.database.state,
+      adminUser: parsed.username,
+      adminPassword: params.database.adminPassword,
+      connectionString: params.database.connectionString,
+      host: parsed.host,
+      port: parsed.port,
+      database: parsed.database,
+      ...(params.database.region ? { region: params.database.region } : {}),
+    },
+    fs: {
+      wsUrl: resolveFsWsUrl(parsed.host),
+      username: parsed.username,
+      password: params.database.adminPassword,
+    },
+    plugin: {
+      schema: params.config.schema,
+      logRoot: params.config.logRoot,
+      initializedAt: params.previous?.plugin.initializedAt ?? now,
+      lastBootstrapAt: now,
+    },
+  };
+}
+
+function requireConnectionString(response: Db9DatabaseResponse | Db9DatabaseCredentialsResponse): string {
+  const connectionString = response.connection_string?.trim();
+  if (!connectionString) {
+    throw new Error("DB9 did not return a connection string");
+  }
+  return connectionString;
+}
+
+function requireAdminPassword(response: Db9DatabaseResponse | Db9DatabaseCredentialsResponse): string {
+  const password = response.admin_password?.trim();
+  if (!password) {
+    throw new Error("DB9 did not return an admin password");
+  }
+  return password;
+}
+
+function isTokenLikelyExpired(tokenExpiresAt: string | undefined): boolean {
+  if (!tokenExpiresAt) {
+    return false;
+  }
+  const expiresAt = Date.parse(tokenExpiresAt);
+  if (Number.isNaN(expiresAt)) {
+    return false;
+  }
+  return expiresAt - Date.now() < 60_000;
+}
+
+async function refreshAnonymousToken(params: {
+  client: Db9ControlPlaneClient;
+  state: Db9AuditState;
+  logger?: PluginLogger | undefined;
+}): Promise<Db9AnonymousRefreshResponse> {
+  const anonymousId = params.state.customer.anonymousId?.trim();
+  const anonymousSecret = params.state.customer.anonymousSecret?.trim();
+  if (!anonymousId || !anonymousSecret) {
+    throw new Error("Anonymous recovery credentials are not available");
+  }
+  params.logger?.info?.("db9-audit: refreshing anonymous DB9 token");
+  return await params.client.anonymousRefresh({
+    anonymousId,
+    anonymousSecret,
+  });
+}
+
+async function withRefreshedToken<T>(params: {
+  client: Db9ControlPlaneClient;
+  state: Db9AuditState;
+  logger?: PluginLogger | undefined;
+  action: (token: string) => Promise<T>;
+}): Promise<{
+  result: T;
+  token: string;
+  tokenExpiresAt?: string | undefined;
+}> {
+  let token = params.state.customer.token;
+  let tokenExpiresAt = params.state.customer.tokenExpiresAt;
+
+  const refresh = async () => {
+    const refreshed = await refreshAnonymousToken(params);
+    token = refreshed.token;
+    tokenExpiresAt = refreshed.expires_at;
+  };
+
+  if (isTokenLikelyExpired(tokenExpiresAt)) {
+    await refresh();
+  }
+
+  try {
+    const result = await params.action(token);
+    return { result, token, ...(tokenExpiresAt ? { tokenExpiresAt } : {}) };
+  } catch (error) {
+    if (!(error instanceof Db9ControlPlaneError) || error.status !== 401) {
+      throw error;
+    }
+    await refresh();
+    const result = await params.action(token);
+    return { result, token, ...(tokenExpiresAt ? { tokenExpiresAt } : {}) };
+  }
+}
+
+export async function bootstrapFreshState(params: {
+  client: Db9ControlPlaneClient;
+  config: Db9AuditPluginConfig;
+  logger?: PluginLogger | undefined;
+}): Promise<Db9AuditState> {
+  params.logger?.info?.("db9-audit: bootstrapping fresh DB9 state");
+  const anonymous = await params.client.anonymousRegister();
+  const me = await params.client.getMe(anonymous.token);
+  const database = await params.client.createDatabase(anonymous.token, {
+    name: params.config.databaseName,
+    ...(params.config.databaseRegion ? { region: params.config.databaseRegion } : {}),
+  });
+
+  return buildState({
+    config: params.config,
+    apiBase: params.client.apiBase,
+    customer: {
+      id: me.id,
+      token: anonymous.token,
+      tokenExpiresAt: anonymous.expires_at,
+      isAnonymous: anonymous.is_anonymous,
+      anonymousId: anonymous.anonymous_id,
+      anonymousSecret: anonymous.anonymous_secret,
+    },
+    database: {
+      id: database.id,
+      name: database.name,
+      state: database.state,
+      region: database.region,
+      connectionString: requireConnectionString(database),
+      adminPassword: requireAdminPassword(database),
+    },
+  });
+}
+
+async function ensureCustomerIdentity(params: {
+  client: Db9ControlPlaneClient;
+  token: string;
+  existingCustomerId: string;
+}): Promise<Db9CustomerResponse> {
+  if (params.existingCustomerId.trim()) {
+    return {
+      id: params.existingCustomerId,
+      email: "",
+      created_at: "",
+      status: "",
+    };
+  }
+  return await params.client.getMe(params.token);
+}
+
+export async function recoverDb9AuditState(params: {
+  client: Db9ControlPlaneClient;
+  config: Db9AuditPluginConfig;
+  state: Db9AuditState;
+  logger?: PluginLogger | undefined;
+}): Promise<Db9AuditState> {
+  if (!params.state.database.id.trim()) {
+    throw new Error("State is missing database id");
+  }
+
+  params.logger?.info?.(`db9-audit: recovering DB9 credentials for database ${params.state.database.id}`);
+  const recovered = await withRefreshedToken({
+    client: params.client,
+    state: params.state,
+    logger: params.logger,
+    action: async (token) => await params.client.getCredentials(token, params.state.database.id),
+  }).catch((error: unknown) => {
+    if (
+      error instanceof Db9ControlPlaneError &&
+      (error.status === 404 || error.status === 409)
+    ) {
+      throw new Db9AuditDatabaseUnavailableError({
+        databaseId: params.state.database.id,
+        causeCode: error.code,
+        message:
+          error.status === 404
+            ? `DB9 database ${params.state.database.id} no longer exists`
+            : `DB9 database ${params.state.database.id} is not available: ${error.message}`,
+      });
+    }
+    throw error;
+  });
+
+  const identity = await ensureCustomerIdentity({
+    client: params.client,
+    token: recovered.token,
+    existingCustomerId: params.state.customer.id,
+  });
+
+  return buildState({
+    config: params.config,
+    apiBase: params.client.apiBase,
+    previous: params.state,
+    customer: {
+      id: identity.id,
+      token: recovered.token,
+      tokenExpiresAt: recovered.tokenExpiresAt,
+      isAnonymous: params.state.customer.isAnonymous,
+      anonymousId: params.state.customer.anonymousId,
+      anonymousSecret: params.state.customer.anonymousSecret,
+    },
+    database: {
+      id: params.state.database.id,
+      name: params.state.database.name,
+      state: "ACTIVE",
+      region: params.state.database.region,
+      connectionString: requireConnectionString(recovered.result),
+      adminPassword: requireAdminPassword(recovered.result),
+    },
+  });
+}