# yeeztech/meta-encryptor architecture

> Architecture diagram of the GitHub repository yeeztech/meta-encryptor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yeeztech/meta-encryptor
- Repository: https://github.com/yeeztech/meta-encryptor

## Overview

##### Project type and purpose
- This is an open-source JavaScript/TypeScript library for local client-side (Node/browser) stream encryption and decryption, with support for resumable (breakpoint-resume) file transfers.
- It exposes:
- A `crypto` API (key generation, pub/priv operations, file metadata generators)
- A streaming API (Sealer, Unsealer, SealedFileStream)
- A resumable-transfer API (RecoverableReadStream, RecoverableWriteStream, PipelineContext).

##### File structure
Top-level:
- src/ → implementation modules
– DataProvider.js, utils.js, header_util.js, limits.js, blockfile.js, ypccrypto.js, ypcntobject.js
– Streaming transforms: Sealer.js, Unsealer.js, SealedFileStream.js, SealedFileUtil.js
– Recoverable streams: Recoverable.js, PipelineContext.js
– submodule: node-aes-cmac/… (AES-CMAC implementation)
- test/ → unit tests for each module, plus a small HTTP file-fetcher/server for stream tests
- config files: rollup.config.js, babel.config.cjs, webpack.config.js, jest.config.cjs, tsconfig.json

##### README for insights
- Describes use cases: encrypt local data before upload, decrypt after download, generate/forward keys, support large-file resume encryption & decryption.
- Lists public APIs and usage patterns, showing data flows through Node.js streams with `pipe()`.

##### Main components and their relationships
A. Crypto Subsystem
- Key generator & public/private operations
- File metadata: file-name & JSON content creation
- Hashing & signing functions (dataHashOfSealedFile, signedDataHash, forwardSkey)
B. Streaming Subsystem
- Sealer (Transform): consumes Buffer or string → adds header, encrypts payload → outputs sealed file stream
- Unsealer (Transform): consumes sealed stream → decrypts → strips header → emits original data
- SealedFileStream (Readable): reads sealed files, exposes header + encrypted blocks
- SealedFileUtil: header parsing, version checks, hash extraction
C. Recoverable Transfer Subsystem
- PipelineContext (abstract): interface for saving/loading transfer state
- PipelineContextInFile: file-backed implementation
- RecoverableReadStream / RecoverableWriteStream (Readable/Writable): track bytes, on restart resume at last-saved offset
- Integration: RecoverableReadStream → Unsealer → RecoverableWriteStream for resume-able decryption
D. Utility Modules & Sub-Algorithms
- node-aes-cmac: pure-JS AES-CMAC implementation used by both crypto and streaming subsystems
- DataProvider: likely key-pair or external data feeder for streaming
- limits.js: defines block sizes, version constants

- Data flow through streams: file source → [RecoverableReadStream] → [Sealer] → write to disk
- Recovery: context load/save ↔ PipelineContextInFile
- Decryption flow: sealed file → [SealedFileStream] → [RecoverableReadStream] → [Unsealer] → [RecoverableWriteStream] → output

##### Architectural patterns & design principles
- Modular subsystem separation: crypto primitives vs. streaming transforms vs. resumption logic
- Node.js “pipeable” Transform streams pattern
- Single-Responsibility: each class handles one aspect (header parsing, context persistence, AES-CMAC, encryption)
- Dependency Injection: Sealer/Unsealer accept keyPair + optional context + progress handler

##### Elements
- Crypto primitives (green)
- Stream transforms (blue)
- Context managers (yellow)
- I/O sources/sinks (grey)
- Annotations for key interactions, e.g., “header added/read here,” “state save/load”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Crypto Subsystem
    subgraph "Crypto Subsystem"
        CryptoAPI["Crypto API"]:::crypto
        CryptoMeta["Crypto Metadata Object"]:::crypto
        HeaderUtil["Header Utility"]:::crypto
        Limits["Limits & Constants"]:::crypto
        AESCMAC["AES-CMAC (index.js)"]:::util
        AESCMACAlgo["AES-CMAC (lib)"]:::util
    end

    %% Utilities
    subgraph "Utilities"
        DataProvider["Data Provider"]:::util
        Utils["Utility Functions"]:::util
        Blockfile["Blockfile Handler"]:::util
    end

    %% Streaming Subsystem
    subgraph "Streaming Subsystem"
        Sealer["Sealer"]:::transform
        Unsealer["Unsealer"]:::transform
        SealedStream["SealedFileStream"]:::io
        SealedUtil["SealedFileUtil"]:::transform
    end

    %% Recoverable Subsystem
    subgraph "Recoverable Subsystem"
        Pipeline["PipelineContext (abstract)"]:::context
        Recoverable["Recoverable Streams"]:::context
    end

    %% I/O Sources and Sinks
    FSIn["File Source"]:::io
    FSOut["File Sink"]:::io

    %% Data Flow: Encryption
    FSIn -->|"read()"| Recoverable
    Recoverable -->|"pipe()"| Sealer
    Sealer -->|"write()"| FSOut

    %% Data Flow: Decryption
    SealedStream -->|"read()"| Recoverable
    Recoverable -->|"pipe()"| Unsealer
    Unsealer -->|"write()"| FSOut

    %% Crypto Dependencies
    CryptoAPI -->|"key/status"| Sealer
    CryptoAPI -->|"key/status"| Unsealer
    CryptoMeta -->|"metadata"| Sealer
    HeaderUtil -->|"header ops"| Sealer
    HeaderUtil -->|"header ops"| Unsealer
    HeaderUtil -->|"header parse"| SealedUtil
    Limits -->|"constants"| Sealer
    AESCMAC -->|"mac ops"| CryptoAPI
    AESCMAC -->|"mac ops"| Sealer
    AESCMACAlgo -->|"crypto math"| AESCMAC

    %% PipelineContext Integration
    Pipeline -->|"load/save"| Recoverable

    %% Utility Links
    DataProvider -->|"feeds"| Sealer
    Utils -->|"helpers"| Recoverable
    Blockfile -->|"block mgmt"| Recoverable

    %% SealedFileUtil Usage
    SealedUtil -->|"parse header"| SealedStream

    %% Click Events
    click CryptoAPI "https://github.com/yeeztech/meta-encryptor/blob/main/src/ypccrypto.js"
    click CryptoMeta "https://github.com/yeeztech/meta-encryptor/blob/main/src/ypcntobject.js"
    click HeaderUtil "https://github.com/yeeztech/meta-encryptor/blob/main/src/header_util.js"
    click Limits "https://github.com/yeeztech/meta-encryptor/blob/main/src/limits.js"
    click AESCMAC "https://github.com/yeeztech/meta-encryptor/blob/main/src/node-aes-cmac/index.js"
    click AESCMACAlgo "https://github.com/yeeztech/meta-encryptor/blob/main/src/node-aes-cmac/lib/aes-cmac.js"
    click DataProvider "https://github.com/yeeztech/meta-encryptor/blob/main/src/DataProvider.js"
    click Utils "https://github.com/yeeztech/meta-encryptor/blob/main/src/utils.js"
    click Blockfile "https://github.com/yeeztech/meta-encryptor/blob/main/src/blockfile.js"
    click Sealer "https://github.com/yeeztech/meta-encryptor/blob/main/src/Sealer.js"
    click Unsealer "https://github.com/yeeztech/meta-encryptor/blob/main/src/Unsealer.js"
    click SealedStream "https://github.com/yeeztech/meta-encryptor/blob/main/src/SealedFileStream.js"
    click SealedUtil "https://github.com/yeeztech/meta-encryptor/blob/main/src/SealedFileUtil.js"
    click Pipeline "https://github.com/yeeztech/meta-encryptor/blob/main/src/PipelineConext.js"
    click Recoverable "https://github.com/yeeztech/meta-encryptor/blob/main/src/Recoverable.js"

    %% Styles
    classDef crypto fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef transform fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef context fill:#fff3b0,stroke:#333,stroke-width:1px
    classDef io fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef util fill:#f5d1e0,stroke:#333,stroke-width:1px
```
