dahvault 🔒

dahvault is a universal, platform-agnostic, multi-tenant file management and cryptographic synchronization engine. It handles data-at-rest protection, data-in-transit streaming, and offline-first data synchronization across Web Browsers (Online-Only) and Electron Desktop Applications (Local-First).

It utilizes TypeScript Generics to decouple cryptographic file operations from specific application schemas. It allows developers to register any custom Content model and extended Metadata dictionary seamlessly.

Architecture Blueprint

Every file generated or decrypted by this engine conforms to a unified VaultDocument envelope wrapper:

export interface VaultDocument<C, M> {
    id: string;               // Unique document identifier (UUIDv4)
    orgId?: string;           // Multi-tenant organization routing target
    productKey?: string;      // Software license validation parameter
    metadata: BaseFileMetadata & M; // System tracking headers + your extended metadata
    content: C;               // Your custom functional layout parameters
}

📂 Core Module Layout

• Vault: Core cryptographic engine. Handles 256-bit AES-GCM encryption, decryption, human-readable file size calculation, and locks payloads with a tamper-proof 32-byte HMAC-SHA256 signature seal.
• S3SyncService: Cloud networking adapter. Communicates directly with your AWS API Gateway/Lambda-lith route maps to handle presigned uploads, direct S3 binary streaming, deletion, and cloud-side file renames.
• VaultFileManager: Core state operations manager. Handles template creation, local/remote reads, and file-state subscriptions.
• VaultFileManagerFeatures: Extends the file manager to provide file renaming, deletion, and automated MD5/eTag folder synchronization loops.

🛠️ Quick Start Guide

1. Installation & Linking

In a local development environment, link the module inside the dahvault root workspace folder:

npm install
npm run build
npm link

Then, navigate to your target web frontend or Electron application project and bind it:

npm link @your-org/dahvault

2. Define Your Application Schemas

Define the typescript interfaces mapping your custom file characteristics:

// Define what data goes inside the file
interface WorkspaceContent {
    projectName: string;
    nodesCount: number;
}

// Define any extra tracking flags needed
interface WorkspaceMetaExtensions {
    isCloudStorage: boolean;
    confidentialityLevel: "low" | "high";
}

3. Initialize the Manager (The Injected Adapter Pattern)

Instantiate your components. To keep the engine decoupled from platform-specific bugs, you pass an environment adapter.

On the web, leave the adapter block blank (Online-Only mode). In Electron, map your custom V2 IPC Channel Bridge Invoke loops onto the adapter fields:

import { S3SyncService, VaultFileManager } from "@your-org/dahvault";

// Set up the cloud syncing utility service
const syncService = new S3SyncService("https://your-api-gateway.com", "tenant_company_abc");

// Connect Electron-native file operations safely via your preload bridge
const electronStorageAdapter = {
    readFile: async (filePath) => {
        const arrayBuffer = await window.electronSecureAPI.invokeV2('read-local-disk-bytes', { filePath });
        return new Blob([arrayBuffer]);
    },
    writeFile: async (filePath, fileBlob) => {
        const dataBuffer = await fileBlob.arrayBuffer();
        await window.electronSecureAPI.invokeV2('write-local-disk-bytes', { filePath, binaryData: dataBuffer });
    },
    readLocalDirectoryMetadata: async (directoryPath) => {
        return await window.electronSecureAPI.invokeV2('scan-local-directory-metadata', { directoryPath });
    },
    deleteFile: async (filePath) => {
        await window.electronSecureAPI.invokeV2('delete-local-file', { filePath });
    }
};

// Instantiate the fully typed manager
const manager = new VaultFileManager<WorkspaceContent, WorkspaceMetaExtensions>(
    syncService,
    "tenant_aes_cryptographic_secret_passphrase",
    async () => await firebaseUserInstance.getIdToken(true), // Generic token provider
    { localDirectoryPath: "C:/MyFiles", s3FolderPrefix: "files/workspaces" },
    { projectName: "New Project", nodesCount: 0 }, // Base Content Defaults
    { isCloudStorage: false, confidentialityLevel: "low" }, // Base Meta Defaults
    electronStorageAdapter // Pass adapter (omit on web for online-only mode)
);

💻 Developer Workflows & Fluent APIs

Creating and Fluent Updating

Modify your document states safely using clean, chainable methods without writing raw try/catch blocks or tracking properties inside your React forms:

// Create
const fileInstance = await manager.createVaultFile("invoice.stc", "Alex", "invoice.stc");

// Fluent Update Chain (Isolates properties to prevent naming collisions)
const { content, metadata } = fileInstance.update("JaneManager");
content({ nodesCount: 45 });
metadata({ confidentialityLevel: "high" });

// Save changes down to disk and cloud automatically
await manager.saveVaultFile(fileInstance, "C:/MyFiles/invoice.stc");

Dual-Mode Data Security

Production Mode (Default)

By default, compiling files via toFile() or toBuffer() automatically generates a signed, encrypted binary package layout: [32-Byte HMAC Signature] [12-Byte IV Vector] [Ciphertext Block].

Development Mode (Unsecure Bypassing)

To inspect plain text properties or troubleshoot data-flow anomalies during development coding phases, toggle encryption off explicitly:

// Output a raw, human-readable plain JSON text asset file for debugging
const devFilePayload = await fileInstance.toFile({ secure: false });

// Reading files (Smart Auto-Detection)
// The loading layer detects the raw JSON '{' token header flag and automatically 
// parses the document without throwing signature verification errors.
await fileInstance.decryptFromBlob(devFilePayload);

Advanced File Adjustments & Sync

Manage advanced tasks cleanly through the sub-namespaced .features engine layer:

// Renames files locally on disk and coordinates a Copy + Delete on S3
await manager.features.rename("invoice.stc", "archived_invoice.stc", "local");

// Erases files completely from both local disk and remote cloud space buckets
await manager.features.delete("archived_invoice.stc", "local");

// Automated Reconciliation loop (Compares local file MD5s vs S3 eTags)
// Safely downloads missing cloud files or uploads updates made offline
await manager.features.syncLocalStorageWithCloud();

🧪 Testing Suite

Automated validation schemas are written using Vitest. To execute your cryptographic integrity verifications, tamper-detection guards, and adapter mapping unit tests, execute:

npm run test