image-shield

This npm package provides functionality for image fragmentation and restoration.

Architecture

Note

Work in progress

This project is a monorepo that contains the following packages:

• @image-shield/core: Environment-independent core functionality (types, algorithms, crypto interfaces)
• @image-shield/node: Node.js implementation
• @image-shield/browser: Browser implementation (coming soon)
• @image-shield/cli: CLI implementation

Features

This package provides two main modes for image fragmentation:

🔀 Shuffle Only Mode

• If secretKey is not set, only shuffling is performed.

Original Image → Load → Convert to RGBA → Shuffle → Fragmented PNG Output

🔐 Shuffle + Encrypt Mode (Deprecated)

• If secretKey is set, both shuffling and encryption are performed.

Original Image → Load → Convert to RGBA → Encrypt → Shuffle → Fragmented PNG Output

Installation

npm i image-shield

Usage

import ImageShield from "image-shield";

🔀 Shuffle Only Mode

If you do not set the secretKey, only shuffling will be applied to the images.

Encrypt

await ImageShield.encrypt({
  // config: { /** FragmentationConfig */ },
  imagePaths: [
    "./input_1.png",
    "./input_2.png",
    "./input_3.png",
  ],
  outputDir: "./output/fragmented",
  // secretKey: undefined
});

Output:

output
└── fragmented
    ├── img_1_fragmented.png
    ├── img_2_fragmented.png
    ├── img_3_fragmented.png
    └── manifest.json

input 1	input 2	input 3
500 x 500px (109KB)	400 x 600px (4KB)	600 x 400px (3KB)

output 1	output 2	output 3
494 x 494px (334KB)	494 x 494px (335KB)	494 x 494px (334KB)

Decrypt

await ImageShield.decrypt({
  manifestPath: "./output/fragmented/manifest.json",
  imagePaths: [
    "./output/fragmented/img_1_fragmented.png",
    "./output/fragmented/img_2_fragmented.png",
    "./output/fragmented/img_3_fragmented.png",
  ],
  outputDir: "./output/restored",
  // secretKey: undefined
});

Output:

output
└── restored
    ├── img_1.png
    ├── img_2.png
    └── img_3.png

input 1	input 2	input 3
494 x 494px (334KB)	494 x 494px (335KB)	494 x 494px (334KB)

output 1	output 2	output 3
500 x 500px (117KB)	400 x 600px (2KB)	600 x 400px (2KB)

---

🔐 Shuffle + Encrypt　Mode

If you set the secretKey, both shuffling and encryption will be applied to the images.

Encrypt

await ImageShield.encrypt({
  // config: { /** FragmentationConfig */ },
  imagePaths: [
    "./input_1.png",
    "./input_2.png",
    "./input_3.png",
  ],
  outputDir: "./output/fragmented",
  secretKey: "secret",
});

Output:

output
└── fragmented
    ├── img_1_fragmented.png
    ├── img_2_fragmented.png
    ├── img_3_fragmented.png
    └── manifest.json

input 1	input 2	input 3
500 x 500px (109KB)	400 x 600px (4KB)	600 x 400px (3KB)

output 1	output 2	output 3
494 x 494px (976KB)	494 x 494px (976KB)	494 x 494px (976KB)

Decrypt

await ImageShield.decrypt({
  manifestPath: "./output/fragmented/manifest.json",
  imagePaths: [
    "./output/fragmented/img_1_fragmented.png",
    "./output/fragmented/img_2_fragmented.png",
    "./output/fragmented/img_3_fragmented.png",
  ],
  outputDir: "./output/restored",
  secretKey: "secret",
});

Output:

output
└── restored
    ├── img_1.png
    ├── img_2.png
    └── img_3.png

input 1	input 2	input 3
494 x 494px (976KB)	494 x 494px (976KB)	494 x 494px (976KB)

output 1	output 2	output 3
500 x 500px (117KB)	400 x 600px (2KB)	600 x 400px (2KB)

Shuffle Overview

List by blockSize

input	blockSize: 1	blockSize: 2 (default)	blockSize: 3	blockSize: 4

blockSize: 8	blockSize: 16	blockSize: 32	blockSize: 50	blockSize: 128

Input multiple images

blockSize: 50

input 1	input 2	input 3

output 1	output 2	output 3

Manifest Structure

manifest.json:

{
  "id": "cd3c6a30-17ed-4893-85ea-8e644ab1a4a1",
  "version": "0.8.0",
  "timestamp": "2025-07-10T00:21:16.699Z",
  "config": {
    "blockSize": 2,
    "prefix": "img",
    "seed": 860865,
    "restoreFileName": false
  },
  "images": [
    {
      "w": 501,
      "h": 500,
      "c": 4,
      "x": 251,
      "y": 250
    },
    {
      "w": 490,
      "h": 490,
      "c": 4,
      "x": 245,
      "y": 245
    },
    {
      "w": 490,
      "h": 490,
      "c": 4,
      "x": 245,
      "y": 245
    }
  ],
  "algorithm": "aes-256-cbc",
  "secure": true
}

---

Note

• The manifest.json file contains the necessary information for restoration, but it does not include the secret key.
• Input images are converted to PNG format.

Clients

• Raycast Extension