brainy/src/storage/binaryDataCodec.ts

/**
 * @module storage/binaryDataCodec
 * @description Single source of truth for wrapping/unwrapping binary payloads
 * stored in JSON-based object storage. Binary bytes (compressed blobs, raw
 * buffers) are persisted as `{ _binary: true, data: "<base64>" }` so they can
 * travel through adapters whose object primitive is JSON. `unwrapBinaryData`
 * reverses that wrapping — and MUST be used everywhere bytes come back out,
 * because content hashes are computed over the original bytes, not the
 * wrapper.
 *
 * Used by `BaseStorage`'s blob-store bridge and by `BlobStorage`'s
 * defense-in-depth verification path.
 */

/**
 * @description Wrapped binary data format used when storing binary data in
 * JSON-based storage.
 */
export interface WrappedBinaryData {
  _binary: true
  data: string // base64-encoded
}

/**
 * @description Type guard for the wrapped binary format.
 * @param data - Candidate value.
 * @returns True when `data` is a `{ _binary: true, data: string }` wrapper.
 */
export function isWrappedBinary(data: any): data is WrappedBinaryData {
  return (
    typeof data === 'object' &&
    data !== null &&
    data._binary === true &&
    typeof data.data === 'string'
  )
}

/**
 * @description Unwrap binary data from its JSON wrapper.
 *
 * Handles:
 * - `Buffer` → `Buffer` (pass-through)
 * - `{ _binary: true, data: "<base64>" }` → `Buffer` (unwrap)
 * - Plain object → `Buffer` (JSON stringify — defensive)
 * - String → `Buffer`
 *
 * @param data - Data to unwrap (Buffer, wrapped object, plain object, or string).
 * @returns The unwrapped bytes.
 * @throws Error when the value cannot be interpreted as binary data.
 */
export function unwrapBinaryData(data: any): Buffer {
  // Case 1: Already a Buffer (no unwrapping needed)
  if (Buffer.isBuffer(data)) {
    return data
  }

  // Case 2: Wrapped binary data {_binary: true, data: "base64..."}
  if (isWrappedBinary(data)) {
    return Buffer.from(data.data, 'base64')
  }

  // Case 3: Plain object (shouldn't happen for binary blobs, but handle gracefully)
  if (typeof data === 'object' && data !== null) {
    return Buffer.from(JSON.stringify(data))
  }

  // Case 4: String (convert to Buffer)
  if (typeof data === 'string') {
    return Buffer.from(data)
  }

  // Case 5: Invalid type
  throw new Error(
    `Invalid data type for unwrap: ${typeof data}. ` +
      `Expected Buffer or {_binary: true, data: "base64..."}`
  )
}