feat: add HOL audit trail hcs-2 + hcs-1

Signed-off-by: Piotr Kierzniewski <piotr.kierzniewski@blockydevs.com>

Author: kierzniak

typescript/src/shared/audit/audit-entry.ts

@@ -0,0 +1,53 @@
+import z from 'zod';
+
+import { HOL_AUDIT_ENTRY_TYPE, HOL_AUDIT_ENTRY_VERSION, HOL_AUDIT_ENTRY_SOURCE } from './constants';
+
+export type AuditEntry = {
+  type: typeof HOL_AUDIT_ENTRY_TYPE;
+  version: typeof HOL_AUDIT_ENTRY_VERSION;
+  source: string;
+  timestamp: string;
+  tool: string;
+  params: Record<string, any>;
+  result: {
+    raw: Record<string, any>;
+    message: string | null;
+  };
+};
+
+export type BuildAuditEntryParams = {
+  tool: string;
+  params?: Record<string, any>;
+  result?: {
+    raw?: Record<string, any>;
+    message?: string | null;
+  };
+};
+
+export const auditEntrySchema = z.object({
+  type: z.literal(HOL_AUDIT_ENTRY_TYPE),
+  version: z.literal(HOL_AUDIT_ENTRY_VERSION),
+  source: z.string().describe('Identifier of the system that produced this entry.'),
+  timestamp: z.string().describe('ISO 8601 timestamp of when the tool was executed.'),
+  tool: z.string().describe('Name of the tool that was executed.'),
+  params: z.record(z.any()).describe('Normalised parameters passed to the tool.'),
+  result: z.object({
+    raw: z.record(z.any()).describe('Raw result returned by the tool.'),
+    message: z.string().nullable().describe('Human-readable result message.'),
+  }),
+});
+
+export function buildAuditEntry(params: BuildAuditEntryParams): AuditEntry {
+  return {
+    type: HOL_AUDIT_ENTRY_TYPE,
+    version: HOL_AUDIT_ENTRY_VERSION,
+    source: HOL_AUDIT_ENTRY_SOURCE,
+    timestamp: new Date().toISOString(),
+    tool: params.tool,
+    params: params.params ?? {},
+    result: {
+      raw: params.result?.raw ?? {},
+      message: params.result?.message ?? null,
+    },
+  };
+}

typescript/src/shared/audit/audit-session.ts

@@ -0,0 +1,45 @@
+import type { AuditEntry } from './audit-entry';
+import type { AuditWriter } from './writers/types';
+import { isSessionAware } from './writers/types';
+
+export class AuditSession {
+  private sessionId: string | null;
+  private writer: AuditWriter;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(writer: AuditWriter, sessionId?: string) {
+    this.writer = writer;
+    this.sessionId = sessionId ?? null;
+
+    if (this.sessionId && isSessionAware(writer)) {
+      writer.setSessionId(this.sessionId);
+    }
+  }
+
+  getSessionId(): string | null {
+    return this.sessionId;
+  }
+
+  async writeEntry(entry: AuditEntry): Promise<void> {
+    await this.ensureInitialized();
+    await this.writer.write(entry);
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.sessionId) return;
+
+    if (!this.initPromise) {
+      this.initPromise = this.initialize();
+    }
+
+    await this.initPromise;
+  }
+
+  private async initialize(): Promise<void> {
+    this.sessionId = await this.writer.initialize();
+
+    if (isSessionAware(this.writer)) {
+      this.writer.setSessionId(this.sessionId);
+    }
+  }
+}

typescript/src/shared/audit/constants.ts

@@ -0,0 +1,3 @@
+export const HOL_AUDIT_ENTRY_VERSION = '1.0' as const;
+export const HOL_AUDIT_ENTRY_SOURCE = 'hedera-agent-kit-js' as const;
+export const HOL_AUDIT_ENTRY_TYPE = 'hedera-agent-kit:audit-entry' as const;

typescript/src/shared/audit/index.ts

@@ -0,0 +1,5 @@
+export * from './constants';
+export * from './audit-entry';
+export * from './audit-session';
+export * from './writers/types';
+export * from './writers/hol-audit-writer';

typescript/src/shared/audit/writers/hol-audit-writer.ts

@@ -0,0 +1,64 @@
+import { Client } from '@hashgraph/sdk';
+
+import { Hcs1FileBuilder } from '@/shared/hol/hcs1-file-builder';
+import { Hcs2RegistryBuilder } from '@/shared/hol/hcs2-registry-builder';
+import { HCS2_REGISTRY_TYPE } from '@/shared/hol/constants';
+import type { AuditEntry } from '../audit-entry';
+import type { SessionAwareWriter } from './types';
+
+export class HolAuditWriter implements SessionAwareWriter {
+  private client: Client;
+  private sessionId!: string;
+
+  constructor(client: Client) {
+    this.client = client;
+  }
+
+  setSessionId(sessionId: string): void {
+    this.sessionId = sessionId;
+  }
+
+  async initialize(): Promise<string> {
+    const tx = Hcs2RegistryBuilder.createRegistry({
+      autoRenewAccountId: this.client.operatorAccountId!.toString(),
+      submitKey: this.client.operatorPublicKey!,
+      registryType: HCS2_REGISTRY_TYPE.INDEXED,
+      ttl: 0,
+    });
+
+    const response = await tx.execute(this.client);
+    const receipt = await response.getReceipt(this.client);
+    if (!receipt.topicId) {
+      throw new Error('Failed to create session topic');
+    }
+
+    return receipt.topicId.toString();
+  }
+
+  async write(entry: AuditEntry): Promise<void> {
+    const { topicTransaction, buildMessageTransactions } = Hcs1FileBuilder.createFile({
+      autoRenewAccountId: this.client.operatorAccountId!.toString(),
+      submitKey: this.client.operatorPublicKey!,
+      content: JSON.stringify(entry),
+    });
+
+    const topicResponse = await topicTransaction.execute(this.client);
+    const topicReceipt = await topicResponse.getReceipt(this.client);
+    if (!topicReceipt.topicId) {
+      throw new Error('Failed to create HCS-1 topic for audit entry');
+    }
+    const entryTopicId = topicReceipt.topicId.toString();
+
+    const messageTxs = buildMessageTransactions(entryTopicId);
+    for (const messageTx of messageTxs) {
+      await messageTx.execute(this.client);
+    }
+
+    const registerTx = Hcs2RegistryBuilder.registerEntry({
+      registryTopicId: this.sessionId,
+      targetTopicId: entryTopicId,
+    });
+
+    await registerTx.execute(this.client);
+  }
+}

typescript/src/shared/audit/writers/types.ts

@@ -0,0 +1,16 @@
+import type { AuditEntry } from '../audit-entry';
+
+export type AuditWriter = {
+  /** One-time setup: create resources (e.g. registry topic). Returns session identifier. */
+  initialize(): Promise<string>;
+  /** Write a single audit entry. */
+  write(entry: AuditEntry): Promise<void>;
+};
+
+export type SessionAwareWriter = AuditWriter & {
+  setSessionId(sessionId: string): void;
+};
+
+export function isSessionAware(writer: AuditWriter): writer is SessionAwareWriter {
+  return 'setSessionId' in writer;
+}

typescript/src/shared/hol/constants.ts

@@ -0,0 +1,17 @@
+export const HCS1_CHUNK_THRESHOLD = 1024;
+export const HCS1_CHUNK_ENVELOPE_SIZE = 16; // JSON envelope overhead: {"o":NNN,"c":"..."} ≈ 16 bytes
+export const HCS1_CHUNK_SIZE = HCS1_CHUNK_THRESHOLD - HCS1_CHUNK_ENVELOPE_SIZE;
+
+export const HCS2_PROTOCOL = 'hcs-2' as const;
+
+export const HCS2_OPERATION = {
+  REGISTER: 'register',
+  UPDATE: 'update',
+  DELETE: 'delete',
+  MIGRATE: 'migrate',
+} as const;
+
+export const HCS2_REGISTRY_TYPE = {
+  INDEXED: 0,
+  NON_INDEXED: 1,
+} as const;

typescript/src/shared/hol/hcs1-file-builder.ts

@@ -0,0 +1,66 @@
+import { createHash } from 'crypto';
+import { brotliCompressSync, constants as zlibConstants } from 'zlib';
+
+import { PublicKey } from '@hashgraph/sdk';
+
+import HederaBuilder from '@/shared/hedera-utils/hedera-builder';
+import { HCS1_CHUNK_SIZE } from './constants';
+
+export type CreateHcs1FileParams = {
+  autoRenewAccountId: string;
+  submitKey: PublicKey;
+  content: string;
+  mimeType?: string;
+};
+
+export type Hcs1Message = {
+  o: number;
+  c: string;
+};
+
+export type Hcs1FileResult = {
+  topicTransaction: any;
+  buildMessageTransactions: (topicId: string) => any[];
+};
+
+export class Hcs1FileBuilder {
+  static createFile(params: CreateHcs1FileParams): Hcs1FileResult {
+    const mimeType = params.mimeType ?? 'application/json';
+    const contentBuffer = Buffer.from(params.content, 'utf-8');
+
+    const hash = createHash('sha256').update(contentBuffer).digest('hex');
+
+    const compressed = brotliCompressSync(contentBuffer, {
+      params: { [zlibConstants.BROTLI_PARAM_QUALITY]: zlibConstants.BROTLI_MAX_QUALITY },
+    });
+    const base64Data = compressed.toString('base64');
+
+    const dataUri = `data:${mimeType};base64,${base64Data}`;
+
+    const chunks: string[] = [];
+    for (let i = 0; i < dataUri.length; i += HCS1_CHUNK_SIZE) {
+      chunks.push(dataUri.slice(i, i + HCS1_CHUNK_SIZE));
+    }
+
+    const topicMemo = `${hash}:brotli:base64`;
+
+    const topicTransaction = HederaBuilder.createTopic({
+      topicMemo,
+      autoRenewAccountId: params.autoRenewAccountId,
+      isSubmitKey: false,
+      submitKey: params.submitKey,
+    });
+
+    return {
+      topicTransaction,
+      buildMessageTransactions: (topicId: string) =>
+        chunks.map((chunk, index) => {
+          const chunkMessage: Hcs1Message = { o: index, c: chunk };
+          return HederaBuilder.submitTopicMessage({
+            topicId,
+            message: JSON.stringify(chunkMessage),
+          });
+        }),
+    };
+  }
+}

typescript/src/shared/hol/hcs2-registry-builder.ts

@@ -0,0 +1,58 @@
+import { PublicKey } from '@hashgraph/sdk';
+
+import HederaBuilder from '@/shared/hedera-utils/hedera-builder';
+import { HCS2_PROTOCOL, HCS2_OPERATION, HCS2_REGISTRY_TYPE } from './constants';
+
+type Hcs2Operation = (typeof HCS2_OPERATION)[keyof typeof HCS2_OPERATION];
+
+export type CreateHcs2RegistryParams = {
+  autoRenewAccountId: string;
+  submitKey: PublicKey;
+  registryType?: 0 | 1;
+  ttl?: number;
+};
+
+export type RegisterHcs2EntryParams = {
+  registryTopicId: string;
+  targetTopicId: string;
+  metadata?: string;
+  memo?: string;
+};
+
+export type Hcs2Message = {
+  p: typeof HCS2_PROTOCOL;
+  op: Hcs2Operation;
+  t_id: string;
+  uid?: number;
+  metadata?: string;
+  m?: string;
+};
+
+export class Hcs2RegistryBuilder {
+  static createRegistry(params: CreateHcs2RegistryParams) {
+    const registryType = params.registryType ?? HCS2_REGISTRY_TYPE.INDEXED;
+    const ttl = params.ttl ?? 0;
+
+    return HederaBuilder.createTopic({
+      topicMemo: `${HCS2_PROTOCOL}:${registryType}:${ttl}`,
+      autoRenewAccountId: params.autoRenewAccountId,
+      isSubmitKey: false,
+      submitKey: params.submitKey,
+    });
+  }
+
+  static registerEntry(params: RegisterHcs2EntryParams) {
+    const message: Hcs2Message = {
+      p: HCS2_PROTOCOL,
+      op: HCS2_OPERATION.REGISTER,
+      t_id: params.targetTopicId,
+      metadata: params.metadata,
+      m: params.memo,
+    };
+
+    return HederaBuilder.submitTopicMessage({
+      topicId: params.registryTopicId,
+      message: JSON.stringify(message),
+    });
+  }
+}

typescript/src/shared/hol/index.ts

@@ -0,0 +1,3 @@
+export * from './constants';
+export * from './hcs1-file-builder';
+export * from './hcs2-registry-builder';