Protect your files against future quantum computer attacks. Built on NIST-standardized cryptography (FIPS 203/204) with an auditable, open-source design and verifiable builds.

Installation

npm install @zkim-platform/file-format

Requirements

• Node.js 18+ (for Node.js environments)
• Modern browser with TypedArray and ES2020+ support (for browser environments)
  • Browser builds rely on WebAssembly-backed libsodium (via libsodium-wrappers-sumo)
• TypeScript 5.0+ (recommended for type safety)

Quick Start

import { ZKIMFileService, InMemoryStorage } from "@zkim-platform/file-format";
import sodium from "libsodium-wrappers-sumo";

async function main() {
  await sodium.ready;

  // ⚠️ NOTE: This example uses random keys for simplicity.
  // In production, derive keys from actual user authentication.
  // See Authentication Integration guide for proper key derivation.
  
  // Platform key (store securely, same for all users)
  const platformKey = sodium.randombytes_buf(32);
  
  // User key (in production, derive from user authentication)
  // Example: const userKey = await deriveKeyFromWallet(walletAddress, signature);
  const userKey = sodium.randombytes_buf(32);
  const userId = "example-user";

  // Create storage backend
  const storage = new InMemoryStorage();

  // Initialize the file service
  const fileService = new ZKIMFileService(
    {
      enableCompression: true,
      enableSearchableEncryption: false,
      enableIntegrityValidation: true,
    },
    undefined,
    storage
  );

  await fileService.initialize();

  try {
    // Create encrypted ZKIM file
    const testData = new TextEncoder().encode("Hello, ZKIM File Format!");
    const result = await fileService.createZkimFile(
      testData,
      userId,
      platformKey,
      userKey,
      {
        fileName: "example.txt",
        mimeType: "text/plain",
      }
    );

    if (result.success && result.file) {
      console.log("File created:", result.file.header.fileId);
    }
  } catch (error) {
    console.error("Failed to create file:", error);
  }

  await fileService.cleanup();
}

main().catch(console.error);

Who is this for?

• Developers building secure file storage or sharing systems
• Applications requiring long-term confidentiality (store-now-decrypt-later resistance)
• Projects that need post-quantum signatures and crypto agility
• Teams concerned about supply-chain security and provenance

Documentation

📖 Full Documentation → Wiki

• Getting Started
• Authentication Integration ⭐ CRITICAL
• Storage Integration ⭐ CRITICAL
• API Reference
• Examples
• Security & Post-Quantum
• Architecture
• Troubleshooting

Features

• 🔐 Three-Layer Encryption: XChaCha20-Poly1305 with platform, user, and content layers
• 🔍 Privacy-Preserving Search: OPRF-based trapdoors with rotation
• ✅ Post-Quantum Signatures: ML-DSA-65 (FIPS 204) for long-term authenticity
• 📦 Compression: Optional GZIP/Brotli compression
• 🛡️ Integrity Validation: BLAKE3-based content hashing and integrity verification
• 🌐 Cross-Platform: Works in browser and Node.js environments

⚠️ FIPS Validation Disclaimer: This package uses NIST-standardized algorithms (FIPS 203/204) but is NOT FIPS 140-3 validated by an accredited laboratory. The implementation follows NIST specifications but is not certified for government use requiring FIPS validation. See Security Documentation for details.

Key Technologies

• Encryption: XChaCha20-Poly1305 (AEAD) via libsodium
• Hashing: BLAKE3 (256-bit output) via @noble/hashes
• Signatures: ML-DSA-65 (FIPS 204, post-quantum) via @noble/post-quantum
• Key Exchange: ML-KEM-768 (FIPS 203, post-quantum) via @noble/post-quantum
• Searchable Encryption: OPRF (Oblivious Pseudorandom Function) via @noble/curves

Design Philosophy

• Post-quantum by default - Future-proof cryptography from day one
• Crypto agility - Algorithm choices are explicit and configurable
• Explicit threat models - Security assumptions are documented
• Auditability over obscurity - Open design and verifiable builds

License

MIT License - see LICENSE for details.

Provenance

This package is published with npm Provenance (build attestation) to ensure authenticity and integrity.

What is Provenance? Provenance provides verifiable information about how and where this package was built:

• ✅ Built and signed on: GitHub Actions
• ✅ Source Commit: Links to exact GitHub commit
• ✅ Build File: Links to GitHub Actions workflow
• ✅ Public Ledger: Transparency log entry (immutable record)

Why it matters:

• Verifies package authenticity
• Shows exact source code used
• Provides build environment details
• Creates immutable audit trail
• Enhances supply chain security

View Provenance: Visit the package page on npm and scroll to the "Provenance" section at the bottom to see:

• Build environment details
• Source commit link
• Build workflow file
• Public ledger entry

Verify locally:

npm audit signatures

For more information, see npm Provenance Documentation.

Made with ❤️ by the ZKIM Team