openclaw-db9-audit 0.1.0

package/src/cli.ts

@@ -0,0 +1,362 @@
+import type { OpenClawPluginApi, PluginLogger } from "openclaw/plugin-sdk/core";
+import { bootstrapFreshState, recoverDb9AuditState } from "./bootstrap.js";
+import { loadDb9AuditConfig } from "./config.js";
+import { Db9ControlPlaneClient, Db9ControlPlaneError } from "./control-plane.js";
+import { Db9FsClient } from "./fs-client.js";
+import { Db9AuditPostgres } from "./postgres.js";
+import { Db9AuditSessionLookup, discoverTranscriptFiles } from "./session-store.js";
+import { Db9AuditStateStore, summarizeDb9AuditState } from "./state-store.js";
+import { Db9AuditTranscriptSync } from "./transcript-sync.js";
+import type { Db9AuditPluginConfig, Db9AuditState, Db9AuditStatusReport } from "./types.js";
+import { extractErrorMessage, parseConnectionString } from "./utils.js";
+
+async function readState(params: {
+  stateStore: Db9AuditStateStore;
+}): Promise<Db9AuditState | null> {
+  return await params.stateStore.read();
+}
+
+async function readStateSafely(params: {
+  stateStore: Db9AuditStateStore;
+}): Promise<{ state: Db9AuditState | null; error?: string | undefined }> {
+  try {
+    return { state: await readState(params) };
+  } catch (error) {
+    return {
+      state: null,
+      error: extractErrorMessage(error) ?? String(error),
+    };
+  }
+}
+
+async function buildStatusReport(params: {
+  config: Db9AuditPluginConfig;
+  stateStore: Db9AuditStateStore;
+  logger: PluginLogger;
+}): Promise<Db9AuditStatusReport> {
+  const stateResult = await readStateSafely({ stateStore: params.stateStore });
+  const state = stateResult.state;
+  const report: Db9AuditStatusReport = {
+    statePath: params.stateStore.stateFilePath,
+    hasState: Boolean(state),
+    ...(state ? { stateSummary: summarizeDb9AuditState(state) } : {}),
+    checks: {},
+  };
+
+  if (!state) {
+    report.checks.state = { ok: false, detail: stateResult.error ?? "state file not found" };
+    return report;
+  }
+
+  report.checks.state = { ok: true };
+
+  const controlPlane = new Db9ControlPlaneClient(params.config.apiBase);
+  try {
+    await controlPlane.getMe(state.customer.token);
+    report.checks.controlPlane = { ok: true };
+  } catch (error) {
+    report.checks.controlPlane = {
+      ok: false,
+      detail: extractErrorMessage(error) ?? String(error),
+    };
+  }
+
+  let pg: Db9AuditPostgres | null = null;
+  try {
+    pg = new Db9AuditPostgres({
+      connectionString: state.database.connectionString,
+      schema: params.config.schema,
+      logger: params.logger,
+    });
+    await pg.ping();
+    report.checks.postgres = { ok: true };
+    report.checks.schema = { ok: await pg.hasSchemaVersion() };
+  } catch (error) {
+    report.checks.postgres = {
+      ok: false,
+      detail: extractErrorMessage(error) ?? String(error),
+    };
+    report.checks.schema = { ok: false, detail: "postgres unavailable" };
+  } finally {
+    await pg?.close().catch(() => undefined);
+  }
+
+  let fsClient: Db9FsClient | null = null;
+  try {
+    fsClient = new Db9FsClient({
+      wsUrl: state.fs.wsUrl,
+      username: state.fs.username,
+      password: state.fs.password,
+      logger: params.logger,
+    });
+    await fsClient.connect();
+    report.checks.fs = { ok: true };
+  } catch (error) {
+    report.checks.fs = {
+      ok: false,
+      detail: extractErrorMessage(error) ?? String(error),
+    };
+  } finally {
+    await fsClient?.close().catch(() => undefined);
+  }
+
+  return report;
+}
+
+async function runDoctor(params: {
+  config: Db9AuditPluginConfig;
+  stateStore: Db9AuditStateStore;
+  logger: PluginLogger;
+}): Promise<Record<string, unknown>> {
+  const stateResult = await readStateSafely({ stateStore: params.stateStore });
+  const state = stateResult.state;
+  const controlPlane = new Db9ControlPlaneClient(params.config.apiBase);
+  if (!state) {
+    return {
+      state: { ok: false, detail: stateResult.error ?? "state file not found" },
+    };
+  }
+
+  const report: Record<string, unknown> = {
+    state: { ok: true, path: params.stateStore.stateFilePath },
+    customer: {
+      id: state.customer.id,
+      anonymous: state.customer.isAnonymous,
+    },
+    database: {
+      id: state.database.id,
+      name: state.database.name,
+      host: state.database.host,
+    },
+  };
+
+  let refreshedState: Db9AuditState | null = null;
+  try {
+    await controlPlane.getMe(state.customer.token);
+    report.token = { ok: true };
+  } catch (error) {
+    report.token = {
+      ok: false,
+      detail: extractErrorMessage(error) ?? String(error),
+    };
+    if (error instanceof Db9ControlPlaneError && error.status === 401) {
+      try {
+        refreshedState = await recoverDb9AuditState({
+          client: controlPlane,
+          config: params.config,
+          state,
+          logger: params.logger,
+        });
+        report.recovery = { ok: true };
+      } catch (recoveryError) {
+        report.recovery = {
+          ok: false,
+          detail: extractErrorMessage(recoveryError) ?? String(recoveryError),
+        };
+      }
+    }
+  }
+
+  const effectiveState = refreshedState ?? state;
+  try {
+    const credentials = await controlPlane.getCredentials(effectiveState.customer.token, effectiveState.database.id);
+    try {
+      const parsed = parseConnectionString(credentials.connection_string);
+      report.credentials = {
+        ok: true,
+        host: parsed.host,
+        port: parsed.port,
+        database: parsed.database,
+        username: parsed.username,
+      };
+    } catch (parseError) {
+      report.credentials = {
+        ok: true,
+        detail: `failed to parse connection string: ${extractErrorMessage(parseError) ?? String(parseError)}`,
+      };
+    }
+  } catch (error) {
+    report.credentials = {
+      ok: false,
+      detail: extractErrorMessage(error) ?? String(error),
+    };
+  }
+
+  let pg: Db9AuditPostgres | null = null;
+  try {
+    pg = new Db9AuditPostgres({
+      connectionString: effectiveState.database.connectionString,
+      schema: params.config.schema,
+      logger: params.logger,
+    });
+    await pg.ping();
+    report.postgres = { ok: true };
+    report.schema = { ok: await pg.hasSchemaVersion() };
+  } catch (error) {
+    report.postgres = {
+      ok: false,
+      detail: extractErrorMessage(error) ?? String(error),
+    };
+    report.schema = { ok: false, detail: "postgres unavailable" };
+  } finally {
+    await pg?.close().catch(() => undefined);
+  }
+
+  let fsClient: Db9FsClient | null = null;
+  try {
+    fsClient = new Db9FsClient({
+      wsUrl: effectiveState.fs.wsUrl,
+      username: effectiveState.fs.username,
+      password: effectiveState.fs.password,
+      logger: params.logger,
+    });
+    await fsClient.connect();
+    report.fs = { ok: true };
+  } catch (error) {
+    report.fs = {
+      ok: false,
+      detail: extractErrorMessage(error) ?? String(error),
+    };
+  } finally {
+    await fsClient?.close().catch(() => undefined);
+  }
+
+  return report;
+}
+
+async function bootstrapState(params: {
+  config: Db9AuditPluginConfig;
+  stateStore: Db9AuditStateStore;
+  logger: PluginLogger;
+  force: boolean;
+}): Promise<Db9AuditState> {
+  const stateResult = await readStateSafely({ stateStore: params.stateStore });
+  if (stateResult.error && !params.force) {
+    throw new Error(
+      `Existing state is unreadable. Re-run with --force to rebuild it. (${stateResult.error})`,
+    );
+  }
+  const existing = stateResult.state;
+  if (existing && !params.force) {
+    return existing;
+  }
+  const controlPlane = new Db9ControlPlaneClient(params.config.apiBase);
+  const state = await bootstrapFreshState({
+    client: controlPlane,
+    config: params.config,
+    logger: params.logger,
+  });
+  await params.stateStore.write(state);
+  return state;
+}
+
+function printJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function registerDb9AuditCli(api: OpenClawPluginApi, config: Db9AuditPluginConfig): void {
+  api.registerCli(
+    ({ program, logger }) => {
+      const resolvedConfig = loadDb9AuditConfig(config);
+      const stateStore = new Db9AuditStateStore(api.runtime.state.resolveStateDir());
+      const root = program.command("db9-audit").description("DB9 audit plugin commands");
+
+      root.command("status").description("Show db9-audit status").action(async () => {
+        const report = await buildStatusReport({
+          config: resolvedConfig,
+          stateStore,
+          logger,
+        });
+        printJson(report);
+      });
+
+      root
+        .command("init")
+        .description("Bootstrap db9-audit state")
+        .option("--force", "overwrite existing state by creating a fresh DB9 bootstrap")
+        .action(async (options: { force?: boolean }) => {
+          const state = await bootstrapState({
+            config: resolvedConfig,
+            stateStore,
+            logger,
+            force: options.force === true,
+          });
+          printJson({
+            statePath: stateStore.stateFilePath,
+            summary: summarizeDb9AuditState(state),
+          });
+        });
+
+      root.command("doctor").description("Run db9-audit diagnostics").action(async () => {
+        const report = await runDoctor({
+          config: resolvedConfig,
+          stateStore,
+          logger,
+        });
+        printJson(report);
+      });
+
+      root
+        .command("backfill")
+        .description("Backfill local transcripts into DB9")
+        .option("--agent <id>", "limit to one agent id")
+        .option("--since <date>", "only include transcript files modified on/after this date")
+        .option("--reset-offsets", "clear stored offsets/messages for each session file before syncing")
+        .action(async (options: { agent?: string; since?: string; resetOffsets?: boolean }) => {
+          const state = await bootstrapState({
+            config: resolvedConfig,
+            stateStore,
+            logger,
+            force: false,
+          });
+
+          const pg = new Db9AuditPostgres({
+            connectionString: state.database.connectionString,
+            schema: resolvedConfig.schema,
+            logger,
+          });
+
+          try {
+            await pg.ensureSchema();
+
+            const sessionLookup = new Db9AuditSessionLookup();
+            const transcriptSync = new Db9AuditTranscriptSync({
+              sessionLookup,
+              redactConfig: resolvedConfig.redact,
+              batchSize: resolvedConfig.batchSize,
+              logger,
+              getStore: async () => ({
+                getOffset: (sessionFile) => pg.getOffset(sessionFile),
+                syncTranscriptBatch: (batch) => pg.syncTranscriptBatch(batch),
+              }),
+            });
+
+            const since = options.since ? new Date(options.since) : undefined;
+            const files = await discoverTranscriptFiles({
+              stateDir: api.runtime.state.resolveStateDir(),
+              ...(options.agent ? { agentId: options.agent } : {}),
+              ...(since && !Number.isNaN(since.valueOf()) ? { since } : {}),
+            });
+
+            let syncedFiles = 0;
+            let insertedMessages = 0;
+            for (const filePath of files) {
+              const result = await transcriptSync.syncSessionFile(filePath, {
+                resetOffsets: options.resetOffsets === true,
+              });
+              syncedFiles += 1;
+              insertedMessages += result.insertedMessages;
+            }
+
+            printJson({
+              syncedFiles,
+              insertedMessages,
+            });
+          } finally {
+            await pg.close().catch(() => undefined);
+          }
+        });
+    },
+    { commands: ["db9-audit"] },
+  );
+}

package/src/config.ts

@@ -0,0 +1,53 @@
+import { resolveDefaultDatabaseName, normalizeApiBase, normalizeLogRoot, normalizeSchemaName, parseInteger, parseOptionalString } from "./utils.js";
+import type { Db9AuditPluginConfig } from "./types.js";
+
+export const db9AuditConfigSchema = {
+  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 },
+      },
+    },
+  },
+} as const;
+
+export function loadDb9AuditConfig(input: unknown): Db9AuditPluginConfig {
+  const raw = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
+  const redact = typeof raw.redact === "object" && raw.redact !== null
+    ? (raw.redact as Record<string, unknown>)
+    : {};
+
+  const databaseName = parseOptionalString(raw.databaseName) ?? resolveDefaultDatabaseName();
+
+  return {
+    enabled: raw.enabled !== false,
+    apiBase: normalizeApiBase(parseOptionalString(raw.apiBase)),
+    databaseName,
+    ...(parseOptionalString(raw.databaseRegion)
+      ? { databaseRegion: parseOptionalString(raw.databaseRegion) }
+      : {}),
+    schema: normalizeSchemaName(parseOptionalString(raw.schema)),
+    logRoot: normalizeLogRoot(parseOptionalString(raw.logRoot)),
+    batchSize: parseInteger(raw.batchSize, 100, 1),
+    flushIntervalMs: parseInteger(raw.flushIntervalMs, 1_000, 100),
+    backfillOnStart: raw.backfillOnStart !== false,
+    redact: {
+      enabled: redact.enabled !== false,
+      maxFieldBytes: parseInteger(redact.maxFieldBytes, 65_536, 1_024),
+    },
+  };
+}

package/src/control-plane.ts

@@ -0,0 +1,170 @@
+import type {
+  Db9AnonymousRefreshResponse,
+  Db9AnonymousRegisterResponse,
+  Db9CustomerResponse,
+  Db9DatabaseCredentialsResponse,
+  Db9DatabaseResponse,
+  Db9DatabaseStatusResponse,
+} from "./types.js";
+import { extractErrorMessage, formatError, isRecord, parseOptionalString } from "./utils.js";
+
+export class Db9ControlPlaneError extends Error {
+  readonly status: number;
+  readonly code?: string | undefined;
+  readonly body?: unknown;
+
+  constructor(params: {
+    message: string;
+    status: number;
+    code?: string | undefined;
+    body?: unknown;
+    cause?: unknown;
+  }) {
+    super(params.message, params.cause !== undefined ? { cause: params.cause } : undefined);
+    this.name = "Db9ControlPlaneError";
+    this.status = params.status;
+    this.code = params.code;
+    this.body = params.body;
+  }
+}
+
+function parseErrorCode(payload: unknown): string | undefined {
+  if (!isRecord(payload)) {
+    return undefined;
+  }
+  const error = payload.error;
+  if (typeof error === "string") {
+    return parseOptionalString(error);
+  }
+  if (!isRecord(error)) {
+    return undefined;
+  }
+  return parseOptionalString(error.code);
+}
+
+function parseJsonObject(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error("DB9 API returned a non-object JSON payload");
+  }
+  return value;
+}
+
+export class Db9ControlPlaneClient {
+  readonly apiBase: string;
+
+  constructor(apiBase: string) {
+    this.apiBase = apiBase;
+  }
+
+  async anonymousRegister(): Promise<Db9AnonymousRegisterResponse> {
+    return await this.requestJson<Db9AnonymousRegisterResponse>("POST", "/customer/anonymous-register", {
+      body: {},
+    });
+  }
+
+  async anonymousRefresh(params: {
+    anonymousId: string;
+    anonymousSecret: string;
+  }): Promise<Db9AnonymousRefreshResponse> {
+    return await this.requestJson<Db9AnonymousRefreshResponse>("POST", "/customer/anonymous-refresh", {
+      body: {
+        anonymous_id: params.anonymousId,
+        anonymous_secret: params.anonymousSecret,
+      },
+    });
+  }
+
+  async getMe(token: string): Promise<Db9CustomerResponse> {
+    return await this.requestJson<Db9CustomerResponse>("GET", "/customer/me", { token });
+  }
+
+  async createDatabase(
+    token: string,
+    params: { name: string; region?: string | undefined },
+  ): Promise<Db9DatabaseResponse> {
+    return await this.requestJson<Db9DatabaseResponse>("POST", "/customer/databases", {
+      token,
+      body: {
+        name: params.name,
+        ...(params.region ? { region: params.region } : {}),
+      },
+    });
+  }
+
+  async getDatabase(token: string, databaseId: string): Promise<Db9DatabaseStatusResponse> {
+    return await this.requestJson<Db9DatabaseStatusResponse>(
+      "GET",
+      `/customer/databases/${encodeURIComponent(databaseId)}`,
+      { token },
+    );
+  }
+
+  async getCredentials(token: string, databaseId: string): Promise<Db9DatabaseCredentialsResponse> {
+    return await this.requestJson<Db9DatabaseCredentialsResponse>(
+      "GET",
+      `/customer/databases/${encodeURIComponent(databaseId)}/credentials`,
+      { token },
+    );
+  }
+
+  private async requestJson<T>(
+    method: string,
+    pathname: string,
+    options: {
+      token?: string | undefined;
+      body?: Record<string, unknown> | null | undefined;
+    } = {},
+  ): Promise<T> {
+    const url = `${this.apiBase}${pathname}`;
+    let response: Response;
+    try {
+      const init: RequestInit = {
+        method,
+        headers: {
+          accept: "application/json",
+          ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+          ...(options.body !== undefined ? { "content-type": "application/json" } : {}),
+        },
+        ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+      };
+      response = await fetch(url, init);
+    } catch (error) {
+      throw new Db9ControlPlaneError({
+        status: 0,
+        message: `DB9 API request failed: ${formatError(error)}`,
+        cause: error,
+      });
+    }
+
+    const payload = await this.readJsonResponse(response);
+    if (!response.ok) {
+      const message =
+        extractErrorMessage(payload) ??
+        `DB9 API request failed with status ${response.status} ${response.statusText}`;
+      throw new Db9ControlPlaneError({
+        status: response.status,
+        code: parseErrorCode(payload),
+        body: payload,
+        message,
+      });
+    }
+
+    return payload as T;
+  }
+
+  private async readJsonResponse(response: Response): Promise<unknown> {
+    const raw = await response.text();
+    if (!raw.trim()) {
+      return {};
+    }
+    try {
+      return parseJsonObject(JSON.parse(raw));
+    } catch (error) {
+      throw new Db9ControlPlaneError({
+        status: response.status,
+        message: `DB9 API returned invalid JSON: ${formatError(error)}`,
+        cause: error,
+      });
+    }
+  }
+}