index.d.ts

/**
 * @module
 * Content Addressable Store — Managed blob storage in Git.
 */

import Manifest from "./src/domain/value-objects/Manifest.js";
import type { EncryptionMeta, ManifestData, CompressionMeta, KdfParams, SubManifestRef, RecipientEntry, EncryptionScheme } from "./src/domain/value-objects/Manifest.js";
import Chunk from "./src/domain/value-objects/Chunk.js";
import CasService from "./src/domain/services/CasService.js";
import type {
  CryptoPort,
  CodecPort,
  GitPersistencePort,
  ObservabilityPort,
  CasServiceOptions,
  DeriveKeyOptions,
  DeriveKeyResult,
  StoreEncryptionOptions,
  VerifyIntegrityOptions,
} from "./src/domain/services/CasService.js";

export { CasService, Manifest, Chunk };
/** Type alias mapping the runtime `CompressionPort` export to its base class declaration. */
export type CompressionPort = CompressionPortBase;

export type { EncryptionMeta, ManifestData, CompressionMeta, KdfParams, SubManifestRef, RecipientEntry, EncryptionScheme, CryptoPort, CodecPort, GitPersistencePort, ObservabilityPort, CasServiceOptions, DeriveKeyOptions, DeriveKeyResult, StoreEncryptionOptions, VerifyIntegrityOptions };

/** Abstract port for compression and decompression of buffers and streams. */
export declare class CompressionPortBase {
  compressBuffer(buffer: Buffer): Promise<Buffer>;
  decompressBuffer(buffer: Buffer): Promise<Buffer>;
  compressStream(source: AsyncIterable<Buffer>): AsyncIterable<Buffer>;
  decompressStream(source: AsyncIterable<Buffer>): AsyncIterable<Buffer>;
}

/** Node.js compression adapter using node:zlib (gzip/gunzip). */
export declare class NodeCompressionAdapter extends CompressionPortBase {}

/** Abstract port for splitting a byte stream into chunks. */
export declare class ChunkingPort {
  get strategy(): string;
  get params(): Record<string, unknown>;
  chunk(source: AsyncIterable<Buffer>): AsyncIterable<Buffer>;
}

/** Fixed-size chunking adapter. */
export declare class FixedChunker extends ChunkingPort {
  constructor(options?: { chunkSize?: number });
  get strategy(): "fixed";
  get params(): { chunkSize: number };
}

/** Content-defined chunking adapter using buzhash rolling hash. */
export declare class CdcChunker extends ChunkingPort {
  constructor(options?: {
    minChunkSize?: number;
    maxChunkSize?: number;
    targetChunkSize?: number;
    normalized?: boolean;
  });
  get strategy(): "cdc";
  get params(): { target: number; min: number; max: number; normalized: boolean };
}

/** Abstract port for cryptographic operations. */
export declare class CryptoPortBase {
  sha256(buf: Buffer): Promise<string>;
  randomBytes(n: number): Buffer;
  encryptBuffer(
    buffer: Buffer,
    key: Buffer,
    aad?: Buffer | Uint8Array,
  ): { buf: Buffer; meta: EncryptionMeta } | Promise<{ buf: Buffer; meta: EncryptionMeta }>;
  decryptBuffer(buffer: Buffer, key: Buffer, meta: EncryptionMeta, aad?: Buffer | Uint8Array): Buffer | Promise<Buffer>;
  createEncryptionStream(key: Buffer, aad?: Buffer | Uint8Array): {
    encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>;
    finalize: () => EncryptionMeta;
  };
  createDecryptionStream(key: Buffer, meta: EncryptionMeta, aad?: Buffer | Uint8Array): {
    decrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>;
  };
  hmacSha256(key: Buffer | Uint8Array, data: Buffer | Uint8Array | string): Buffer;
  encryptBufferWithNonce(
    buffer: Buffer | Uint8Array,
    key: Buffer | Uint8Array,
    nonce: Buffer | Uint8Array,
  ): { buf: Buffer; tag: Buffer } | Promise<{ buf: Buffer; tag: Buffer }>;
  decryptBufferWithNonceTag(
    buffer: Buffer | Uint8Array,
    key: Buffer | Uint8Array,
    nonce: Buffer | Uint8Array,
    tag: Buffer | Uint8Array,
  ): Buffer | Promise<Buffer>;
  deriveKey(options: DeriveKeyOptions): Promise<DeriveKeyResult>;
}

/** Abstract port for persisting data to Git's object database. */
export declare class GitPersistencePortBase {
  writeBlob(content: Buffer | string): Promise<string>;
  writeTree(entries: string[]): Promise<string>;
  readBlob(oid: string): Promise<Buffer>;
  readBlobStream(oid: string): Promise<AsyncIterable<Buffer>>;
  readTree(
    treeOid: string,
  ): Promise<Array<{ mode: string; type: string; oid: string; name: string }>>;
}

/** Abstract port for Git ref and commit operations. */
export declare class GitRefPortBase {
  resolveRef(ref: string): Promise<string>;
  resolveTree(commitOid: string): Promise<string>;
  createCommit(options: {
    treeOid: string;
    parentOid?: string | null;
    message: string;
  }): Promise<string>;
  updateRef(options: {
    ref: string;
    newOid: string;
    expectedOldOid?: string | null;
  }): Promise<void>;
}

/** Git-backed implementation of the persistence port. */
export declare class GitPersistenceAdapter extends GitPersistencePortBase {
  constructor(options: { plumbing: unknown; policy?: unknown });
}

/** Git-backed implementation of the ref port. */
export declare class GitRefAdapter extends GitRefPortBase {
  constructor(options: { plumbing: unknown; policy?: unknown });
}

/** Node.js crypto implementation of CryptoPort. */
export declare class NodeCryptoAdapter extends CryptoPortBase {
  constructor();
}

/** Abstract codec interface for manifest serialization. */
export declare class CodecPortBase {
  encode(data: object): Buffer | string;
  decode(buffer: Buffer | string): object;
  get extension(): string;
}

/** JSON codec for manifest serialization. */
export declare class JsonCodec extends CodecPortBase {
  constructor();
}

/** CBOR codec for manifest serialization. */
export declare class CborCodec extends CodecPortBase {
  constructor();
}

/** No-op observability adapter. */
export declare class SilentObserver {
  metric(channel: string, data: Record<string, unknown>): void;
  log(level: string, msg: string, meta?: Record<string, unknown>): void;
  span(name: string): { end(meta?: Record<string, unknown>): void };
}

/** EventEmitter-based observability adapter for backward compatibility. */
export declare class EventEmitterObserver {
  metric(channel: string, data: Record<string, unknown>): void;
  log(level: string, msg: string, meta?: Record<string, unknown>): void;
  span(name: string): { end(meta?: Record<string, unknown>): void };
  on(event: string, listener: (...args: unknown[]) => void): this;
  removeListener(event: string, listener: (...args: unknown[]) => void): this;
  listenerCount(event: string): number;
}

/** Stats-collecting observability adapter. */
export declare class StatsCollector {
  metric(channel: string, data: Record<string, unknown>): void;
  log(level: string, msg: string, meta?: Record<string, unknown>): void;
  span(name: string): { end(meta?: Record<string, unknown>): void };
  summary(): {
    chunksProcessed: number;
    bytesTotal: number;
    elapsed: number;
    throughput: number;
    errors: number;
  };
}

/** Declarative chunking strategy configuration. */
export interface ChunkingConfig {
  strategy: "fixed" | "cdc";
  chunkSize?: number;
  targetChunkSize?: number;
  minChunkSize?: number;
  maxChunkSize?: number;
}

/** Constructor options for {@link ContentAddressableStore}. */
export interface ContentAddressableStoreOptions {
  plumbing: unknown;
  chunkSize?: number;
  codec?: CodecPort;
  crypto?: CryptoPort;
  observability?: ObservabilityPort;
  policy?: unknown;
  merkleThreshold?: number;
  concurrency?: number;
  chunking?: ChunkingConfig;
  chunker?: ChunkingPort;
  /** Compression adapter (default NodeCompressionAdapter). */
  compressionAdapter?: CompressionPortBase;
  /** Maximum bytes to buffer during encrypted/compressed restore. @default 536870912 (512 MiB) */
  maxRestoreBufferSize?: number;
}

/** A single vault entry. */
export interface VaultEntry {
  slug: string;
  treeOid: string;
}

/** Vault metadata stored in .vault.json. */
export interface VaultMetadata {
  version: number;
  /** Number of encrypted store operations performed with this vault key. */
  encryptionCount?: number;
  encryption?: {
    cipher: string;
    kdf: {
      algorithm: string;
      salt: string;
      iterations?: number;
      cost?: number;
      blockSize?: number;
      parallelization?: number;
      keyLength: number;
    };
  };
  /** Privacy mode configuration. When enabled, vault slugs are HMAC-masked in the Git tree. */
  privacy?: {
    enabled: boolean;
    /** Encryption metadata for the privacy index blob. */
    indexMeta?: { nonce: string; tag: string };
  };
}

/** Internal vault state returned by VaultService.readState(). */
export interface VaultState {
  entries: Map<string, string>;
  parentCommitOid: string | null;
  metadata: VaultMetadata | null;
}

/**
 * Domain service for vault (GC-safe ref-based asset index) operations.
 */
export declare class VaultService {
  static VAULT_REF: string;

  constructor(options: {
    persistence: GitPersistencePortBase;
    ref: GitRefPortBase;
    crypto: CryptoPortBase;
    observability?: ObservabilityPort;
  });

  /** Validates a vault slug. Throws CasError with code INVALID_SLUG on failure. */
  validateSlug(slug: string): void;

  /** Reads the current vault state from refs/cas/vault. */
  readState(options?: {
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<VaultState>;

  /** Writes a new vault commit and updates the ref atomically. */
  writeCommit(options: {
    entries: Map<string, string>;
    metadata: VaultMetadata;
    parentCommitOid: string | null;
    message: string;
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<{ commitOid: string }>;

  /** Initializes the vault, optionally with encryption and privacy mode. */
  initVault(options?: {
    passphrase?: string;
    kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
    /** Enable privacy mode (requires passphrase/encryption). */
    privacy?: boolean;
  }): Promise<{ commitOid: string }>;

  /** Adds or updates an entry in the vault. */
  addToVault(options: {
    slug: string;
    treeOid: string;
    force?: boolean;
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<{ commitOid: string }>;

  /** Lists all vault entries sorted by slug. */
  listVault(options?: {
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<VaultEntry[]>;

  /** Removes an entry from the vault. */
  removeFromVault(options: {
    slug: string;
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<{ commitOid: string; removedTreeOid: string }>;

  /** Resolves a vault entry slug to its tree OID. */
  resolveVaultEntry(options: {
    slug: string;
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<string>;

  /** Returns the vault metadata, or null if no vault exists. */
  getVaultMetadata(): Promise<VaultMetadata | null>;
}

/** Result of comparing two manifests by chunk digest. */
export interface ManifestDiffResult {
  added: Chunk[];
  removed: Chunk[];
  unchanged: Chunk[];
  summary: {
    addedCount: number;
    removedCount: number;
    unchangedCount: number;
    addedBytes: number;
    removedBytes: number;
    unchangedBytes: number;
  };
}

/** Compares two manifests by chunk digest, returning added/removed/unchanged chunks. */
export function diffManifests(oldManifest: Manifest, newManifest: Manifest): ManifestDiffResult;

/**
 * High-level facade for the Content Addressable Store library.
 *
 * Wraps CasService and VaultService with lazy initialization, runtime-adaptive
 * crypto selection, and convenience helpers for file I/O.
 */
export default class ContentAddressableStore {
  constructor(options: ContentAddressableStoreOptions);

  get chunkSize(): number;

  getService(): Promise<CasService>;
  getVaultService(): Promise<VaultService>;

  static createJson(options: {
    plumbing: unknown;
    chunkSize?: number;
    policy?: unknown;
  }): ContentAddressableStore;

  static createCbor(options: {
    plumbing: unknown;
    chunkSize?: number;
    policy?: unknown;
  }): ContentAddressableStore;

  static diffManifests(oldManifest: Manifest, newManifest: Manifest): ManifestDiffResult;

  encrypt(options: {
    buffer: Buffer;
    key: Buffer;
  }): Promise<{ buf: Buffer; meta: EncryptionMeta }>;

  decrypt(options: {
    buffer: Buffer;
    key: Buffer;
    meta: EncryptionMeta;
  }): Promise<Buffer>;

  storeFile(options: {
    filePath: string;
    slug: string;
    filename?: string;
    encryptionKey?: Buffer;
    passphrase?: string;
    encryption?: StoreEncryptionOptions;
    kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
    compression?: { algorithm: "gzip" };
    recipients?: Array<{ label: string; key: Buffer }>;
  }): Promise<Manifest>;

  store(options: {
    source: AsyncIterable<Buffer>;
    slug: string;
    filename: string;
    encryptionKey?: Buffer;
    passphrase?: string;
    encryption?: StoreEncryptionOptions;
    kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
    compression?: { algorithm: "gzip" };
    recipients?: Array<{ label: string; key: Buffer }>;
  }): Promise<Manifest>;

  restoreFile(options: {
    manifest: Manifest;
    encryptionKey?: Buffer;
    passphrase?: string;
    outputPath: string;
  }): Promise<{ bytesWritten: number }>;

  restore(options: {
    manifest: Manifest;
    encryptionKey?: Buffer;
    passphrase?: string;
  }): Promise<{ buffer: Buffer; bytesWritten: number }>;

  restoreStream(options: {
    manifest: Manifest;
    encryptionKey?: Buffer;
    passphrase?: string;
  }): AsyncIterable<Buffer>;

  createTree(options: { manifest: Manifest }): Promise<string>;

  verifyIntegrity(manifest: Manifest, options?: VerifyIntegrityOptions): Promise<boolean>;

  readManifest(options: { treeOid: string }): Promise<Manifest>;

  inspectAsset(options: {
    treeOid: string;
  }): Promise<{ slug: string; chunksOrphaned: number }>;

  /** @deprecated Use {@link inspectAsset} instead. */
  deleteAsset(options: {
    treeOid: string;
  }): Promise<{ slug: string; chunksOrphaned: number }>;

  collectReferencedChunks(options: {
    treeOids: string[];
  }): Promise<{ referenced: Set<string>; total: number }>;

  /** @deprecated Use {@link collectReferencedChunks} instead. */
  findOrphanedChunks(options: {
    treeOids: string[];
  }): Promise<{ referenced: Set<string>; total: number }>;

  deriveKey(options: DeriveKeyOptions): Promise<DeriveKeyResult>;

  addRecipient(options: {
    manifest: Manifest;
    existingKey: Buffer;
    newRecipientKey: Buffer;
    label: string;
  }): Promise<Manifest>;

  removeRecipient(options: {
    manifest: Manifest;
    label: string;
  }): Promise<Manifest>;

  listRecipients(manifest: Manifest): Promise<string[]>;

  rotateKey(options: {
    manifest: Manifest;
    oldKey: Buffer;
    newKey: Buffer;
    label?: string;
  }): Promise<Manifest>;

  // Vault — delegates to VaultService

  static VAULT_REF: string;

  initVault(options?: {
    passphrase?: string;
    kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
    /** Enable privacy mode (requires passphrase/encryption). */
    privacy?: boolean;
  }): Promise<{ commitOid: string }>;

  addToVault(options: {
    slug: string;
    treeOid: string;
    force?: boolean;
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<{ commitOid: string }>;

  listVault(options?: {
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<VaultEntry[]>;

  removeFromVault(options: {
    slug: string;
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<{ commitOid: string; removedTreeOid: string }>;

  resolveVaultEntry(options: {
    slug: string;
    /** Vault encryption key (required when privacy mode is enabled). */
    encryptionKey?: Buffer;
  }): Promise<string>;

  getVaultMetadata(): Promise<VaultMetadata | null>;

  rotateVaultPassphrase(options: {
    oldPassphrase: string;
    newPassphrase: string;
    kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
    /** Maximum optimistic-concurrency retries on VAULT_CONFLICT. @default 3 */
    maxRetries?: number;
    /** Base delay in ms for exponential backoff between retries. @default 50 */
    retryBaseMs?: number;
  }): Promise<{
    commitOid: string;
    rotatedSlugs: string[];
    skippedSlugs: string[];
  }>;
}