enigma-memory 0.1.18 → 0.1.22

package/packages/vault/index.d.ts

@@ -0,0 +1,449 @@
+/// <reference types="node" />
+
+export interface KdfSpec {
+  algorithm: 'pbkdf2' | 'scrypt';
+  iterations?: number;
+  hash?: string;
+  n?: number;
+  r?: number;
+  p?: number;
+  maxmem?: number;
+  salt?: string;
+}
+
+export declare const DEFAULT_KDF_SPEC: KdfSpec;
+export declare const PBKDF2_KDF_SPEC: KdfSpec;
+
+export interface DerivedKeys {
+  kek: Buffer;
+  vaultKey: Buffer;
+  addressKey: Buffer;
+  signingSeed: Buffer;
+}
+
+export declare function validateKdfSpec(kdfSpec?: KdfSpec): KdfSpec;
+export declare function deriveMasterKeyFromPassphrase(passphrase: string | Buffer, salt: string | Buffer, kdfSpec?: KdfSpec): Buffer;
+export declare function deriveKeysFromPassphrase(passphrase: string | Buffer, salt: string | Buffer, kdfSpec?: KdfSpec): DerivedKeys;
+
+export interface MemoryReceipt {
+  schema: string;
+  version: number;
+  receipt_id: string;
+  memory_id: string;
+  operation: 'append' | 'update' | 'revoke' | string;
+  commitment: string;
+  previous_root: string;
+  new_root: string;
+  leaf_index: number;
+  inclusion_proof?: unknown;
+  transition_proof?: {
+    type: string;
+    operation: string;
+    prior_size: number;
+    new_size: number;
+    prior_commitments: string[];
+    prior_commitment?: string;
+    prior_inclusion_proof?: unknown;
+    new_non_membership_proof?: unknown;
+  };
+  timestamp: string;
+  agent_pubkey: string;
+  signature: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CreateMemoryReceiptResult {
+  receipt: MemoryReceipt;
+  opening: {
+    blindingFactor: string;
+    contentHash: string;
+  };
+}
+
+export interface ReceiptVerificationResult {
+  ok: boolean;
+  verified: boolean;
+  receipt_id: string;
+  memory_id: string;
+  operation?: string;
+  commitment: string;
+  previous_root?: string;
+  new_root?: string;
+  signatureValid: boolean;
+  inclusionValid: boolean;
+  transitionValid: boolean;
+  openingValid?: boolean;
+  errors: string[];
+}
+
+export declare const MEMORY_RECEIPT_SCHEMA: string;
+
+export declare function computeHidingCommitment(
+  plaintext: string,
+  blindingFactor?: Buffer | string | null
+): { commitment: string; blindingFactor: string; contentHash: string };
+
+export declare function verifyCommitmentOpening(
+  plaintext: string,
+  blindingFactorHex: string,
+  expectedCommitmentHex: string
+): boolean;
+
+export declare function getReceiptSignablePayload(receipt: Partial<MemoryReceipt>): string;
+
+export declare function createMemoryReceipt(params: {
+  memoryId: string;
+  plaintext: string;
+  operation?: 'append' | 'update' | 'revoke' | string;
+  blindingFactor?: Buffer | string | null;
+  previousRoot?: string;
+  priorCommitments?: string[];
+  priorCommitment?: string;
+  signingSecretKey: Buffer | string;
+  signingPublicKey: Buffer | string;
+  metadata?: Record<string, unknown>;
+}): CreateMemoryReceiptResult;
+
+export declare function verifyMemoryReceipt(
+  receipt: MemoryReceipt,
+  options?: { expectedAgentPubkey?: string; plaintext?: string; blindingFactor?: string }
+): ReceiptVerificationResult;
+
+export interface ErasureReceipt {
+  schema: string;
+  version: number;
+  erasure_id: string;
+  agent_id: string;
+  scope: string;
+  erased_memory_count: number;
+  pre_erasure_root: string;
+  erasure_digest: string;
+  storage_wiped?: boolean;
+  timestamp: string;
+  agent_pubkey: string;
+  signature: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type ErasureAttestation = ErasureReceipt;
+
+export interface ErasureVerificationResult {
+  ok: boolean;
+  verified: boolean;
+  erasure_id: string;
+  agent_id: string;
+  signatureValid: boolean;
+  digestValid?: boolean;
+  errors: string[];
+}
+
+export declare const ERASURE_RECEIPT_SCHEMA: string;
+export declare const ERASURE_ATTESTATION_SCHEMA: string;
+
+export declare function secureZeroizeBuffer(buffer: Buffer): void;
+
+export declare function getErasureSignablePayload(receipt: Partial<ErasureReceipt>): string;
+
+export declare function createErasureReceipt(params: {
+  agentId: string;
+  scope: string;
+  erasedMemoryCount: number;
+  preErasureRoot: string;
+  activeCommitments?: string[];
+  storageWiped?: boolean;
+  signingSecretKey: Buffer | string;
+  signingPublicKey: Buffer | string;
+  metadata?: Record<string, unknown>;
+}): ErasureReceipt;
+
+export declare function createErasureAttestation(params: {
+  agentId: string;
+  scope: string;
+  erasedMemoryCount: number;
+  preErasureRoot: string;
+  activeCommitments?: string[];
+  storageWiped?: boolean;
+  signingSecretKey: Buffer | string;
+  signingPublicKey: Buffer | string;
+  metadata?: Record<string, unknown>;
+}): ErasureReceipt;
+
+export declare function verifyErasureReceipt(
+  receipt: ErasureReceipt,
+  options?: { expectedAgentPubkey?: string; expectedCommitments?: string[] }
+): ErasureVerificationResult;
+
+export declare function verifyErasureAttestation(
+  receipt: ErasureReceipt,
+  options?: { expectedAgentPubkey?: string; expectedCommitments?: string[] }
+): ErasureVerificationResult;
+export interface ContentKeyEpoch {
+  epoch: number;
+  key_id: string;
+  status: 'active' | 'retained' | 'sealed';
+  created_at: string;
+  sealed_at?: string;
+  key?: Buffer | string;
+  key_b64?: string;
+}
+
+export interface VaultOptions {
+  passphrase?: string;
+  vaultKey?: Buffer | string;
+  vault_key?: Buffer | string;
+  addressKey?: Buffer | string;
+  address_key?: Buffer | string;
+  keyId?: string;
+  key_id?: string;
+  keyEpochs?: ContentKeyEpoch[];
+  key_epochs?: ContentKeyEpoch[];
+  activeKeyEpoch?: number;
+  active_key_epoch?: number;
+  allowOldEpochReads?: boolean;
+  allow_old_epoch_reads?: boolean;
+  kdf?: KdfSpec;
+  now?: string | Date;
+  vault_id?: string;
+  tenant_id?: string;
+  subject_id?: string;
+  actor_id?: string;
+  policy_id?: string;
+  signingKeyPair?: unknown;
+  signer?: { key_id: string; alg: string };
+}
+
+export interface VaultRoots {
+  active_set_root: string;
+  quarantine_set_root: string;
+  tombstone_set_root: string;
+  receipt_log_root: string;
+  lifecycle_root: string;
+}
+
+export interface VaultInstance extends VaultRoots {
+  schema: string;
+  vault_id: string;
+  tenant_id: string;
+  subject_id: string;
+  actor_id: string;
+  policy_id: string;
+  key_id: string;
+  activeKeyEpoch: number;
+  keyEpochs: Map<number, ContentKeyEpoch & { key: Buffer }>;
+  allowOldEpochReads: boolean;
+  vaultKey: Buffer;
+  addressKey: Buffer;
+  signingKeyPair: unknown;
+  signer: { key_id: string; alg: string };
+  created_at: string;
+  updated_at: string;
+  sequence: number;
+  memories: Map<string, MemoryObject>;
+  events: unknown[];
+  receipts: unknown[];
+  activeAddresses: Set<string>;
+  tombstones: Map<string, unknown>;
+  __getRecord(memoryAddr: string): MemoryObject | undefined;
+  __getPlaintext(memoryAddr: string): string;
+  __computeRoots(): VaultRoots;
+}
+
+export interface MemoryObject {
+  schema: string;
+  memory_id: string;
+  memory_addr: string;
+  subject_id: string;
+  kind: string;
+  key_epoch: number;
+  key_id: string;
+  content_ciphertext: {
+    alg: 'AES-256-GCM';
+    iv: string;
+    aad: string;
+    ciphertext: string;
+    tag: string;
+  };
+  content_commitment: string;
+  state: 'active' | 'superseded' | 'tombstoned';
+  created_at: string;
+  updated_at: string;
+  [key: string]: unknown;
+}
+
+export interface VaultOperationResult {
+  memory?: MemoryObject;
+  memory_addr: string;
+  event: unknown;
+  receipt: unknown;
+}
+
+export interface VaultBundle {
+  schema: 'enigma.vault_bundle.v1';
+  exported_at: string;
+  vault: Record<string, unknown>;
+  keyring: Record<string, unknown>;
+  memory_objects: MemoryObject[];
+  active_memory_addresses: string[];
+  tombstones: unknown[];
+  events: unknown[];
+  receipts: unknown[];
+  export_receipt: unknown;
+}
+
+export declare const VAULT_SCHEMA: string;
+export declare const VAULT_BUNDLE_SCHEMA: string;
+export declare const MEMORY_OBJECT_SCHEMA: string;
+export declare const EVENT_SCHEMA: string;
+export declare const KEYRING_ENCRYPTED_TYPE: 'local_secret_encrypted';
+export declare const KEYRING_PLAINTEXT_TYPE: 'local_secret';
+
+export declare function createVault(args?: VaultOptions): VaultInstance;
+
+export declare function remember(args: {
+  vault: VaultInstance;
+  content?: string;
+  text?: string;
+  plaintext?: string;
+  memory_id?: string;
+  memoryId?: string;
+  key_epoch?: number;
+  keyEpoch?: number;
+  importance?: number;
+  kind?: string;
+  purpose_tags?: string[];
+  metadata?: Record<string, unknown>;
+  now?: string | Date;
+}): VaultOperationResult & { memory: MemoryObject };
+
+export declare function recall(args: {
+  vault: VaultInstance;
+  memory_addr?: string;
+  memoryAddr?: string;
+  purpose?: string;
+  operation?: string;
+  now?: string | Date;
+}): VaultOperationResult & { memory: MemoryObject & { content: string }; content: string };
+
+export declare function updateMemory(args: {
+  vault: VaultInstance;
+  memory_addr?: string;
+  memoryAddr?: string;
+  content?: string;
+  text?: string;
+  plaintext?: string;
+  key_epoch?: number;
+  keyEpoch?: number;
+  metadata?: Record<string, unknown>;
+  now?: string | Date;
+}): VaultOperationResult & { old_memory_addr: string; memory: MemoryObject; tombstone: unknown };
+
+export declare function deleteMemory(args: {
+  vault: VaultInstance;
+  memory_addr?: string;
+  memoryAddr?: string;
+  reason?: string;
+  now?: string | Date;
+}): VaultOperationResult & { tombstone: unknown };
+
+export declare function rotateContentKey(args: {
+  vault: VaultInstance;
+  key?: Buffer | string;
+  key_id?: string;
+  keyId?: string;
+  now?: string | Date;
+}): Record<string, unknown> & { epoch: number; key_id: string; receipt: unknown };
+
+export declare function sealContentKeyEpoch(args: {
+  vault: VaultInstance;
+  epoch?: number;
+  now?: string | Date;
+}): Record<string, unknown> & { epoch: number; key_id: string; receipt: unknown };
+
+export declare function resetVaultContentKeys(args: {
+  vault: VaultInstance;
+  key?: Buffer | string;
+  key_id?: string;
+  keyId?: string;
+  now?: string | Date;
+}): Record<string, unknown> & { epoch: number; key_id: string; receipt: unknown };
+
+export declare function exportBundle(args: {
+  vault: VaultInstance;
+  passphrase?: string;
+  kdf?: KdfSpec;
+  now?: string | Date;
+}): VaultBundle;
+
+export declare function importBundle(args: {
+  bundle: VaultBundle | string;
+  passphrase?: string;
+  strict?: boolean;
+  insecureDevMode?: boolean;
+  allowOldEpochReads?: boolean;
+  recordImport?: boolean;
+}): {
+  vault: VaultInstance;
+  active_memory_addresses: string[];
+  tombstones: unknown[];
+  warnings: string[];
+  verified: boolean;
+};
+
+export declare function canonicalKeyringAad(meta?: Record<string, unknown>): Buffer;
+export declare function decryptKeyring(keyring: Record<string, unknown>, passphrase: string): Record<string, unknown>;
+
+export interface VaultMonotonicHead {
+  schema: string;
+  vault_id: string;
+  sequence: number;
+  bundle_revision: string;
+  receipt_hash: string | null;
+  trust_domain: string;
+  updated_at: string;
+}
+
+export interface VaultCheckpointProvider {
+  load(input: { path: string; vault_id?: string }): Promise<VaultMonotonicHead | null> | VaultMonotonicHead | null;
+  advance(input: {
+    path: string;
+    previous: VaultMonotonicHead | null;
+    next: VaultMonotonicHead;
+  }): Promise<boolean | void> | boolean | void;
+}
+
+export interface VaultPersistenceOptions {
+  expectedRevision?: string | null;
+  minimumSequence?: number;
+  requireMonotonicHead?: boolean;
+  requireExternalCheckpoint?: boolean;
+  checkpointProvider?: VaultCheckpointProvider;
+  resetMonotonicHead?: boolean;
+  lockOptions?: { timeoutMs?: number; staleLockMs?: number };
+}
+
+export declare function monotonicHeadPath(path: string): string;
+
+export declare function withBundleFileLock<T>(
+  path: string,
+  operation: () => Promise<T> | T,
+  options?: { timeoutMs?: number; staleLockMs?: number }
+): Promise<T>;
+
+export declare function readJsonFileWithRevision(path: string, options?: VaultPersistenceOptions): Promise<{
+  value: unknown;
+  revision: string;
+  raw: string;
+  localHead: VaultMonotonicHead | null;
+  externalHead: VaultMonotonicHead | null;
+}>;
+
+export declare function readFileRevision(path: string): Promise<{
+  revision: string;
+  raw: Buffer;
+}>;
+
+export declare function writeJsonFileAtomic(
+  path: string,
+  value: unknown,
+  options?: VaultPersistenceOptions
+): Promise<{ revision: string; bytes: number; head: VaultMonotonicHead | null }>;

package/packages/vault/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@enigma/vault",
+  "version": "0.1.22",
+  "description": "Enigma Encrypted Vault: Fail-Closed Sovereign AI Memory Custody with AES-256-GCM and PBKDF2/scrypt",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "src/",
+    "index.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "@enigma/core": "workspace:*",
+    "@hpke/chacha20poly1305": "^1.8.0",
+    "@hpke/core": "^1.9.0",
+    "@noble/ciphers": "^2.3.0",
+    "@noble/curves": "^1.9.0",
+    "circomlibjs": "^0.1.7"
+  }
+}