@fluxpointstudios/orynq-sdk-flight-recorder 0.1.0

package/src/crypto/encryption.ts

@@ -0,0 +1,210 @@
+/**
+ * Encryption utilities for flight recorder chunks.
+ * Uses Web Crypto API for AES-256-GCM encryption.
+ */
+
+import { webcrypto } from "node:crypto";
+
+const crypto = webcrypto as unknown as Crypto;
+
+export interface EncryptedData {
+  ciphertext: Uint8Array;
+  nonce: Uint8Array;
+  tag: Uint8Array; // For AES-GCM, tag is appended to ciphertext
+}
+
+export interface EncryptionKey {
+  keyId: string;
+  key: CryptoKey;
+  algorithm: "aes-256-gcm" | "chacha20-poly1305";
+  createdAt: string;
+}
+
+/**
+ * Generate a new AES-256-GCM encryption key.
+ */
+export async function generateKey(algorithm: "aes-256-gcm" | "chacha20-poly1305" = "aes-256-gcm"): Promise<EncryptionKey> {
+  if (algorithm === "chacha20-poly1305") {
+    // ChaCha20-Poly1305 not directly supported in Web Crypto
+    // Fall back to AES-GCM for now, can add libsodium later
+    console.warn("ChaCha20-Poly1305 not supported, using AES-256-GCM");
+    algorithm = "aes-256-gcm";
+  }
+
+  const key = await crypto.subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    true, // extractable for export/wrapping
+    ["encrypt", "decrypt"]
+  );
+
+  const keyId = generateKeyId();
+
+  return {
+    keyId,
+    key,
+    algorithm,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Generate a random key ID.
+ */
+function generateKeyId(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Generate a random nonce/IV for AES-GCM (12 bytes recommended).
+ */
+export function generateNonce(): Uint8Array {
+  const nonce = new Uint8Array(12);
+  crypto.getRandomValues(nonce);
+  return nonce;
+}
+
+/**
+ * Encrypt data using AES-256-GCM.
+ */
+export async function encrypt(
+  data: Uint8Array,
+  key: EncryptionKey,
+  additionalData?: Uint8Array
+): Promise<EncryptedData> {
+  const nonce = generateNonce();
+
+  const params: AesGcmParams = {
+    name: "AES-GCM",
+    iv: nonce as unknown as ArrayBuffer,
+    tagLength: 128, // 16 bytes
+  };
+  if (additionalData) {
+    params.additionalData = additionalData as unknown as ArrayBuffer;
+  }
+
+  const ciphertextWithTag = await crypto.subtle.encrypt(
+    params,
+    key.key,
+    data as unknown as ArrayBuffer
+  );
+
+  const ciphertextWithTagArray = new Uint8Array(ciphertextWithTag);
+
+  // AES-GCM appends the tag to the ciphertext
+  // Split them for clarity in our data structure
+  const tagStart = ciphertextWithTagArray.length - 16;
+  const ciphertext = ciphertextWithTagArray.slice(0, tagStart);
+  const tag = ciphertextWithTagArray.slice(tagStart);
+
+  return {
+    ciphertext,
+    nonce,
+    tag,
+  };
+}
+
+/**
+ * Decrypt data using AES-256-GCM.
+ */
+export async function decrypt(
+  encrypted: EncryptedData,
+  key: EncryptionKey,
+  additionalData?: Uint8Array
+): Promise<Uint8Array> {
+  // Reconstruct ciphertext with tag appended
+  const ciphertextWithTag = new Uint8Array(encrypted.ciphertext.length + encrypted.tag.length);
+  ciphertextWithTag.set(encrypted.ciphertext, 0);
+  ciphertextWithTag.set(encrypted.tag, encrypted.ciphertext.length);
+
+  const decryptParams: AesGcmParams = {
+    name: "AES-GCM",
+    iv: encrypted.nonce as unknown as ArrayBuffer,
+    tagLength: 128,
+  };
+  if (additionalData) {
+    decryptParams.additionalData = additionalData as unknown as ArrayBuffer;
+  }
+
+  const plaintext = await crypto.subtle.decrypt(
+    decryptParams,
+    key.key,
+    ciphertextWithTag as unknown as ArrayBuffer
+  );
+
+  return new Uint8Array(plaintext);
+}
+
+/**
+ * Export key as raw bytes (for sealing/wrapping).
+ */
+export async function exportKey(key: EncryptionKey): Promise<Uint8Array> {
+  const rawKey = await crypto.subtle.exportKey("raw", key.key);
+  return new Uint8Array(rawKey);
+}
+
+/**
+ * Import key from raw bytes.
+ */
+export async function importKey(
+  rawKey: Uint8Array,
+  keyId: string,
+  algorithm: "aes-256-gcm" | "chacha20-poly1305" = "aes-256-gcm"
+): Promise<EncryptionKey> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    rawKey as unknown as ArrayBuffer,
+    { name: "AES-GCM", length: 256 },
+    true,
+    ["encrypt", "decrypt"]
+  );
+
+  return {
+    keyId,
+    key,
+    algorithm,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Derive a key from a master key using HKDF-SHA256.
+ */
+export async function deriveKey(
+  masterKey: Uint8Array,
+  info: string,
+  salt?: Uint8Array
+): Promise<EncryptionKey> {
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    masterKey as unknown as ArrayBuffer,
+    "HKDF",
+    false,
+    ["deriveKey"]
+  );
+
+  const saltBuffer = salt ?? new Uint8Array(32);
+  const infoBuffer = new TextEncoder().encode(info);
+  const derivedKey = await crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: saltBuffer as unknown as ArrayBuffer,
+      info: infoBuffer as unknown as ArrayBuffer,
+    },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    true,
+    ["encrypt", "decrypt"]
+  );
+
+  return {
+    keyId: generateKeyId(),
+    key: derivedKey,
+    algorithm: "aes-256-gcm",
+    createdAt: new Date().toISOString(),
+  };
+}

package/src/crypto/hashing.ts

@@ -0,0 +1,225 @@
+/**
+ * Hashing utilities for flight recorder.
+ * Provides consistent SHA-256 hashing with domain separation.
+ */
+
+import { webcrypto } from "node:crypto";
+
+const crypto = webcrypto as unknown as Crypto;
+
+/**
+ * Hash domain prefixes for different data types.
+ */
+export const HASH_DOMAINS = {
+  event: "poi-flight:event:v2|",
+  chunk: "poi-flight:chunk:v2|",
+  manifest: "poi-flight:manifest:v2|",
+  roll: "poi-flight:roll:v2|",
+  merkleLeaf: "poi-flight:leaf:v2|",
+  merkleNode: "poi-flight:node:v2|",
+  encryptedChunk: "poi-flight:encrypted:v2|",
+} as const;
+
+export type HashDomain = keyof typeof HASH_DOMAINS;
+
+/**
+ * Compute SHA-256 hash of data with domain separation.
+ */
+export async function sha256(data: Uint8Array, domain?: HashDomain): Promise<string> {
+  let input = data;
+
+  if (domain) {
+    const prefix = new TextEncoder().encode(HASH_DOMAINS[domain]);
+    const combined = new Uint8Array(prefix.length + data.length);
+    combined.set(prefix, 0);
+    combined.set(data, prefix.length);
+    input = combined;
+  }
+
+  const hashBuffer = await crypto.subtle.digest("SHA-256", input as unknown as ArrayBuffer);
+  return bufferToHex(new Uint8Array(hashBuffer));
+}
+
+/**
+ * Compute SHA-256 hash of a string.
+ */
+export async function sha256String(str: string, domain?: HashDomain): Promise<string> {
+  const data = new TextEncoder().encode(str);
+  return sha256(data, domain);
+}
+
+/**
+ * Compute SHA-256 hash of JSON-serializable data.
+ */
+export async function sha256Json(obj: unknown, domain?: HashDomain): Promise<string> {
+  const json = JSON.stringify(obj, null, 0);
+  return sha256String(json, domain);
+}
+
+/**
+ * Compute rolling hash by combining previous hash with new data.
+ */
+export async function rollingHash(prevHash: string, newData: Uint8Array): Promise<string> {
+  const prevBytes = hexToBuffer(prevHash);
+  const combined = new Uint8Array(prevBytes.length + newData.length);
+  combined.set(prevBytes, 0);
+  combined.set(newData, prevBytes.length);
+  return sha256(combined, "roll");
+}
+
+/**
+ * Compute Merkle tree leaf hash.
+ */
+export async function merkleLeaf(data: Uint8Array): Promise<string> {
+  return sha256(data, "merkleLeaf");
+}
+
+/**
+ * Compute Merkle tree internal node hash.
+ */
+export async function merkleNode(left: string, right: string): Promise<string> {
+  const leftBytes = hexToBuffer(left);
+  const rightBytes = hexToBuffer(right);
+  const combined = new Uint8Array(leftBytes.length + rightBytes.length);
+  combined.set(leftBytes, 0);
+  combined.set(rightBytes, leftBytes.length);
+  return sha256(combined, "merkleNode");
+}
+
+/**
+ * Build a Merkle tree from leaf hashes and return the root.
+ */
+export async function buildMerkleRoot(leafHashes: string[]): Promise<string> {
+  if (leafHashes.length === 0) {
+    // Empty tree - hash of empty string
+    return sha256(new Uint8Array(0), "merkleNode");
+  }
+
+  if (leafHashes.length === 1) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return leafHashes[0]!;
+  }
+
+  // Build tree level by level
+  let currentLevel = leafHashes;
+
+  while (currentLevel.length > 1) {
+    const nextLevel: string[] = [];
+
+    for (let i = 0; i < currentLevel.length; i += 2) {
+      const left = currentLevel[i];
+      const right = currentLevel[i + 1];
+      if (left !== undefined && right !== undefined) {
+        // Pair exists
+        const nodeHash = await merkleNode(left, right);
+        nextLevel.push(nodeHash);
+      } else if (left !== undefined) {
+        // Odd element - promote to next level
+        nextLevel.push(left);
+      }
+    }
+
+    currentLevel = nextLevel;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return currentLevel[0]!;
+}
+
+/**
+ * Generate a Merkle proof for a leaf at the given index.
+ */
+export interface MerkleProof {
+  leafIndex: number;
+  leafHash: string;
+  siblings: Array<{ hash: string; position: "left" | "right" }>;
+  root: string;
+}
+
+export async function generateMerkleProof(
+  leafHashes: string[],
+  leafIndex: number
+): Promise<MerkleProof> {
+  if (leafIndex < 0 || leafIndex >= leafHashes.length) {
+    throw new Error(`Invalid leaf index: ${leafIndex}`);
+  }
+
+  const siblings: Array<{ hash: string; position: "left" | "right" }> = [];
+  let currentLevel = leafHashes;
+  let currentIndex = leafIndex;
+
+  while (currentLevel.length > 1) {
+    const isLeft = currentIndex % 2 === 0;
+    const siblingIndex = isLeft ? currentIndex + 1 : currentIndex - 1;
+
+    const siblingHash = currentLevel[siblingIndex];
+    if (siblingIndex < currentLevel.length && siblingHash !== undefined) {
+      siblings.push({
+        hash: siblingHash,
+        position: isLeft ? "right" : "left",
+      });
+    }
+
+    // Build next level
+    const nextLevel: string[] = [];
+    for (let i = 0; i < currentLevel.length; i += 2) {
+      const left = currentLevel[i];
+      const right = currentLevel[i + 1];
+      if (left !== undefined && right !== undefined) {
+        const nodeHash = await merkleNode(left, right);
+        nextLevel.push(nodeHash);
+      } else if (left !== undefined) {
+        nextLevel.push(left);
+      }
+    }
+
+    currentLevel = nextLevel;
+    currentIndex = Math.floor(currentIndex / 2);
+  }
+
+  const leafHash = leafHashes[leafIndex];
+  const root = currentLevel[0];
+  if (leafHash === undefined || root === undefined) {
+    throw new Error("Invalid merkle tree state");
+  }
+
+  return {
+    leafIndex,
+    leafHash,
+    siblings,
+    root,
+  };
+}
+
+/**
+ * Verify a Merkle proof.
+ */
+export async function verifyMerkleProof(proof: MerkleProof): Promise<boolean> {
+  let currentHash = proof.leafHash;
+
+  for (const sibling of proof.siblings) {
+    if (sibling.position === "left") {
+      currentHash = await merkleNode(sibling.hash, currentHash);
+    } else {
+      currentHash = await merkleNode(currentHash, sibling.hash);
+    }
+  }
+
+  return currentHash === proof.root;
+}
+
+// === Utility functions ===
+
+function bufferToHex(buffer: Uint8Array): string {
+  return Array.from(buffer)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function hexToBuffer(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}

package/src/crypto/index.ts

@@ -0,0 +1,3 @@
+export * from "./encryption.js";
+export * from "./compression.js";
+export * from "./hashing.js";

package/src/index.ts

@@ -0,0 +1,96 @@
+/**
+ * @fluxpointstudios/orynq-sdk-flight-recorder
+ *
+ * Streaming flight recorder for Proof of Inference (PoI).
+ * Captures inference events with chunking, compression, and encryption.
+ *
+ * @example
+ * ```typescript
+ * import { FlightRecorder, LocalStorageAdapter } from '@fluxpointstudios/orynq-sdk-flight-recorder';
+ *
+ * const storage = new LocalStorageAdapter({ baseDir: './traces' });
+ *
+ * const recorder = new FlightRecorder({
+ *   agentId: 'my-agent',
+ *   chunkSizeBytes: 4 * 1024 * 1024, // 4MB chunks
+ *   encryption: {
+ *     algorithm: 'aes-256-gcm',
+ *     keyDerivation: 'hkdf-sha256',
+ *     keyMode: { type: 'ephemeral' },
+ *   },
+ *   storage,
+ * });
+ *
+ * await recorder.start();
+ *
+ * await recorder.record({
+ *   kind: 'inference:start',
+ *   requestId: 'req-123',
+ *   model: 'claude-3-opus',
+ *   promptHash: '...',
+ *   params: { temperature: 0.7 },
+ * });
+ *
+ * const result = await recorder.finalize();
+ * console.log('Manifest:', result.manifest);
+ * ```
+ */
+
+// Types
+export * from "./types.js";
+
+// Core recorder
+export { FlightRecorder } from "./recorder/stream-recorder.js";
+export { EventBuffer } from "./recorder/event-buffer.js";
+export { ChunkManager } from "./recorder/chunk-manager.js";
+
+// Crypto utilities
+export {
+  generateKey,
+  encrypt,
+  decrypt,
+  exportKey,
+  importKey,
+  deriveKey,
+  type EncryptionKey,
+  type EncryptedData,
+} from "./crypto/encryption.js";
+
+export {
+  compress,
+  decompress,
+  compressString,
+  decompressString,
+  isCompressible,
+  type CompressionType,
+  type CompressionResult,
+} from "./crypto/compression.js";
+
+export {
+  sha256,
+  sha256String,
+  sha256Json,
+  rollingHash,
+  merkleLeaf,
+  merkleNode,
+  buildMerkleRoot,
+  generateMerkleProof,
+  verifyMerkleProof,
+  HASH_DOMAINS,
+  type HashDomain,
+  type MerkleProof,
+} from "./crypto/hashing.js";
+
+// Manifest
+export { ManifestBuilder, type ManifestInput } from "./manifest/manifest-builder.js";
+
+// Storage
+export { LocalStorageAdapter, type LocalStorageConfig } from "./storage/local-adapter.js";
+
+// Integration
+export {
+  OpenClawAdapter,
+  type LegacyTraceEvent,
+  type LegacyTraceBundle,
+  type LegacyManifest,
+} from "./integration/openclaw-adapter.js";

package/src/integration/index.ts

@@ -0,0 +1 @@
+export { OpenClawAdapter } from "./openclaw-adapter.js";