openclaw-db9-audit 0.1.0

package/src/types.ts

@@ -0,0 +1,215 @@
+export type Db9AuditRedactConfig = {
+  enabled: boolean;
+  maxFieldBytes: number;
+};
+
+export type Db9AuditPluginConfig = {
+  enabled: boolean;
+  apiBase: string;
+  databaseName: string;
+  databaseRegion?: string | undefined;
+  schema: string;
+  logRoot: string;
+  batchSize: number;
+  flushIntervalMs: number;
+  backfillOnStart: boolean;
+  redact: Db9AuditRedactConfig;
+};
+
+export type Db9AuditCustomerState = {
+  id: string;
+  token: string;
+  tokenExpiresAt?: string | undefined;
+  isAnonymous: boolean;
+  anonymousId?: string | undefined;
+  anonymousSecret?: string | undefined;
+};
+
+export type Db9AuditDatabaseState = {
+  id: string;
+  name: string;
+  state: string;
+  adminUser: string;
+  adminPassword: string;
+  connectionString: string;
+  host: string;
+  port: number;
+  database: string;
+  region?: string | undefined;
+};
+
+export type Db9AuditFsState = {
+  wsUrl: string;
+  username: string;
+  password: string;
+};
+
+export type Db9AuditPluginState = {
+  schema: string;
+  logRoot: string;
+  initializedAt: string;
+  lastBootstrapAt: string;
+};
+
+export type Db9AuditState = {
+  version: 1;
+  apiBase: string;
+  customer: Db9AuditCustomerState;
+  database: Db9AuditDatabaseState;
+  fs: Db9AuditFsState;
+  plugin: Db9AuditPluginState;
+};
+
+export type Db9AnonymousRegisterResponse = {
+  token: string;
+  expires_at: string;
+  is_anonymous: boolean;
+  anonymous_id: string;
+  anonymous_secret: string;
+};
+
+export type Db9AnonymousRefreshResponse = {
+  token: string;
+  expires_at: string;
+};
+
+export type Db9CustomerResponse = {
+  id: string;
+  email: string;
+  created_at: string;
+  status: string;
+};
+
+export type Db9DatabaseResponse = {
+  id: string;
+  name: string;
+  state: string;
+  region?: string;
+  admin_user?: string;
+  admin_password?: string;
+  connection_string?: string;
+  created_at: string;
+};
+
+export type Db9DatabaseStatusResponse = Db9DatabaseResponse & {
+  endpoints?: Array<{
+    host: string;
+    port: number;
+    type?: string;
+    priority?: number;
+    description?: string;
+    enabled?: boolean;
+  }>;
+};
+
+export type Db9DatabaseCredentialsResponse = {
+  admin_user: string;
+  admin_password: string;
+  connection_string: string;
+};
+
+export type ParsedConnectionString = {
+  raw: string;
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  database: string;
+};
+
+export type TranscriptSessionHeader = {
+  type: "session";
+  version?: string | number;
+  id?: string;
+  timestamp?: string;
+  cwd?: string;
+};
+
+export type SessionLookupResult = {
+  agentId: string;
+  sessionId?: string;
+  sessionKey?: string;
+  sessionStorePath?: string;
+};
+
+export type SessionStoreEntry = {
+  sessionId?: string;
+  sessionFile?: string;
+  updatedAt?: number;
+};
+
+export type TranscriptMessageRecord = {
+  sessionKey: string;
+  agentId: string;
+  sessionFile: string;
+  lineNo: number;
+  runId?: string;
+  role?: string;
+  source: string;
+  toolName?: string;
+  toolCallId?: string;
+  contentText?: string;
+  contentJson?: unknown;
+  rawJson: Record<string, unknown>;
+  createdAt?: string;
+};
+
+export type TranscriptSyncSessionMeta = {
+  sessionKey: string;
+  agentId: string;
+  sessionId?: string;
+};
+
+export type TranscriptFileOffset = {
+  sessionFile: string;
+  agentId?: string | undefined;
+  sessionKey?: string | undefined;
+  lastOffset: number;
+  lastLineNo: number;
+};
+
+export type TranscriptSyncBatch = {
+  sessionFile: string;
+  sessionMeta: TranscriptSyncSessionMeta;
+  messages: TranscriptMessageRecord[];
+  lastOffset: number;
+  lastLineNo: number;
+  resetExistingFile: boolean;
+  sessionHeader?: TranscriptSessionHeader | undefined;
+  sessionMetaJson?: Record<string, unknown> | undefined;
+};
+
+export type TranscriptSyncResult = {
+  insertedMessages: number;
+  lastOffset: number;
+  lastLineNo: number;
+};
+
+export type AuditRunRecord = {
+  runId: string;
+  sessionKey?: string | undefined;
+  agentId?: string | undefined;
+  startedAt?: string | undefined;
+  endedAt?: string | undefined;
+  success?: boolean | undefined;
+  durationMs?: number | undefined;
+  error?: string | undefined;
+  trigger?: string | undefined;
+  messageProvider?: string | undefined;
+  stats: Record<string, unknown>;
+};
+
+export type Db9AuditDiagnosticEvent = {
+  stream?: string | undefined;
+  sessionKey?: string | undefined;
+  agentId?: string | undefined;
+  runId?: string | undefined;
+  data: Record<string, unknown>;
+};
+
+export type Db9AuditStatusReport = {
+  statePath: string;
+  hasState: boolean;
+  stateSummary?: Record<string, unknown> | undefined;
+  checks: Record<string, { ok: boolean; detail?: string | undefined }>;
+};

package/src/utils.ts

@@ -0,0 +1,277 @@
+import os from "node:os";
+import path from "node:path";
+import type { ParsedConnectionString } from "./types.js";
+
+const DEFAULT_DB9_API_BASE = "https://db9.ai/api";
+const DEFAULT_DB9_FS_PORT = 5480;
+const DEFAULT_DB9_PG_PORT = 5433;
+const DEFAULT_AGENT_ID = "main";
+
+export function defaultDb9ApiBase(): string {
+  return DEFAULT_DB9_API_BASE;
+}
+
+export function defaultDb9FsPort(): number {
+  return DEFAULT_DB9_FS_PORT;
+}
+
+export function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function maskSecret(value: string | undefined, opts?: { keepStart?: number }): string {
+  if (!value) {
+    return "";
+  }
+  const keepStart = Math.max(0, opts?.keepStart ?? 6);
+  if (value.length <= keepStart) {
+    return "*".repeat(value.length);
+  }
+  return `${value.slice(0, keepStart)}***`;
+}
+
+export function truncateUtf8Bytes(input: string, maxBytes: number): string {
+  const limit = Math.max(1, maxBytes);
+  if (Buffer.byteLength(input, "utf8") <= limit) {
+    return input;
+  }
+  let output = "";
+  for (const char of input) {
+    const candidate = output + char;
+    if (Buffer.byteLength(candidate, "utf8") > limit) {
+      break;
+    }
+    output = candidate;
+  }
+  return `${output}...<truncated>`;
+}
+
+export function sanitizeDatabaseName(raw: string): string {
+  const normalized = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+/g, "")
+    .replace(/-+$/g, "")
+    .replace(/-{2,}/g, "-");
+  const safe = normalized || "unknown-host";
+  return safe.slice(0, 48);
+}
+
+export function resolveDefaultDatabaseName(hostname: string = os.hostname()): string {
+  return `openclaw-audit-${sanitizeDatabaseName(hostname)}`;
+}
+
+export function normalizeApiBase(value: string | undefined): string {
+  const trimmed = value?.trim();
+  return (trimmed && trimmed.replace(/\/+$/g, "")) || defaultDb9ApiBase();
+}
+
+export function normalizeLogRoot(value: string | undefined): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return "/logs";
+  }
+  const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return prefixed.replace(/\/+$/g, "") || "/logs";
+}
+
+export function normalizeSchemaName(value: string | undefined): string {
+  const trimmed = value?.trim().toLowerCase();
+  const normalized = trimmed?.replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+  return normalized || "openclaw_audit";
+}
+
+export function parseConnectionString(connectionString: string): ParsedConnectionString {
+  let url: URL;
+  try {
+    url = new URL(connectionString);
+  } catch (error) {
+    throw new Error(`Invalid connection string: ${formatError(error)}`);
+  }
+  if (url.protocol !== "postgresql:" && url.protocol !== "postgres:") {
+    throw new Error(`Unsupported connection string protocol: ${url.protocol}`);
+  }
+  const username = decodeURIComponent(url.username);
+  const password = decodeURIComponent(url.password);
+  if (!username) {
+    throw new Error("Connection string is missing username");
+  }
+  if (!password) {
+    throw new Error("Connection string is missing password");
+  }
+  const host = url.hostname;
+  if (!host) {
+    throw new Error("Connection string is missing host");
+  }
+  return {
+    raw: connectionString,
+    host,
+    port: url.port ? Number.parseInt(url.port, 10) : DEFAULT_DB9_PG_PORT,
+    username,
+    password,
+    database: url.pathname.replace(/^\/+/, "") || "postgres",
+  };
+}
+
+export function resolveFsWsUrl(host: string, port: number = defaultDb9FsPort()): string {
+  return `wss://${host}:${port}`;
+}
+
+export function joinPosixPath(...parts: string[]): string {
+  const joined = path.posix.join(...parts.map((part) => part.trim()).filter(Boolean));
+  return joined.startsWith("/") ? joined : `/${joined}`;
+}
+
+export function dirnamePosix(filePath: string): string {
+  const normalized = filePath.trim() || "/";
+  return path.posix.dirname(normalized);
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+export function toIsoString(timestamp: number = Date.now()): string {
+  return new Date(timestamp).toISOString();
+}
+
+export function parseInteger(value: unknown, fallback: number, min: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(min, Math.floor(value));
+}
+
+export function parseOptionalString(value: unknown): string | undefined {
+  return isNonEmptyString(value) ? value.trim() : undefined;
+}
+
+export function normalizeSessionPath(pathValue: string): string {
+  return path.resolve(pathValue.trim());
+}
+
+export function safeJsonParse(value: string): unknown {
+  return JSON.parse(value) as unknown;
+}
+
+export function safeStringifyJson(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+export function resolveAgentIdFromSessionKey(sessionKey: string | undefined | null): string {
+  const raw = (sessionKey ?? "").trim();
+  if (!raw) {
+    return DEFAULT_AGENT_ID;
+  }
+  const lower = raw.toLowerCase();
+  if (!lower.startsWith("agent:")) {
+    return DEFAULT_AGENT_ID;
+  }
+  const parts = raw.split(":");
+  return sanitizeAgentId(parts[1]);
+}
+
+export function sanitizeAgentId(value: string | undefined | null): string {
+  const trimmed = (value ?? "").trim().toLowerCase();
+  if (!trimmed) {
+    return DEFAULT_AGENT_ID;
+  }
+  const sanitized = trimmed
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+/g, "")
+    .replace(/-+$/g, "");
+  return sanitized || DEFAULT_AGENT_ID;
+}
+
+export function resolveAgentIdFromSessionPath(sessionFile: string): string | undefined {
+  const normalized = path.resolve(sessionFile);
+  const parts = normalized.split(path.sep).filter(Boolean);
+  const sessionsIndex = parts.lastIndexOf("sessions");
+  if (sessionsIndex < 2 || parts[sessionsIndex - 2] !== "agents") {
+    return undefined;
+  }
+  const candidate = parts[sessionsIndex - 1];
+  return candidate ? sanitizeAgentId(candidate) : undefined;
+}
+
+export function resolveSessionIdFromSessionPath(sessionFile: string): string | undefined {
+  const base = path.basename(sessionFile.trim());
+  if (!base) {
+    return undefined;
+  }
+  return base.endsWith(".jsonl") ? base.slice(0, -".jsonl".length) : base;
+}
+
+export function toDatePartition(timestampMs: number): string {
+  return new Date(timestampMs).toISOString().slice(0, 10);
+}
+
+export function coerceIsoTimestamp(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.valueOf()) ? undefined : parsed.toISOString();
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  return undefined;
+}
+
+export function extractErrorMessage(value: unknown): string | undefined {
+  if (value instanceof Error) {
+    return value.message;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed || undefined;
+  }
+  if (isRecord(value)) {
+    const message = parseOptionalString(value.message);
+    if (message) {
+      return message;
+    }
+    const nested = value.error;
+    if (typeof nested === "string") {
+      return parseOptionalString(nested);
+    }
+    if (isRecord(nested)) {
+      return parseOptionalString(nested.message) ?? parseOptionalString(nested.code);
+    }
+  }
+  return undefined;
+}
+
+export function coerceInteger(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Math.trunc(value);
+  }
+  return undefined;
+}
+
+export function asArray<T>(value: T | T[] | undefined): T[] {
+  if (value === undefined) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}