A steganography library supporting image and text steganography with LSB embedding, JPEG DCT coefficients, and zero-width character encoding.
npm install @pinta365/steganographyA steganography library supporting image and text steganography.
- Image Steganography
- LSB (Least Significant Bit) embedding for lossless formats
- JPEG DCT coefficient-domain embedding
- File embedding with metadata support
- Text Steganography
- Zero-Width Character (ZWC) encoding
- Optional AES-256-CTR encryption
- Compression support
``bashDeno
deno add jsr:@pinta365/steganography
Or import directly:
typescript
import { decodeText, encodeText } from "jsr:@pinta365/steganography@0.2.0";
`$3
bash
npm install @pinta365/steganography
`Or with other package managers:
bash
yarn
yarn add @pinta365/steganographypnpm
pnpm add @pinta365/steganographybun
bun add @pinta365/steganography
`Note: This library is runtime-agnostic and works on Deno, Node.js (18+), Bun, and browsers.
Usage
$3
typescript
import { decodeText, encodeText } from "@pinta365/steganography";// Hide text in text
const coverText = "# Project README\n\nInstallation guide...";
const secret = "API key: sk_live_1234567890";
const stegaText = await encodeText(coverText, secret, "password", true);
const { visibleText, secretMessage } = await decodeText(stegaText, "password");
`$3
typescript
import { createImage, decodeImage, embedTextInImage, encodeImage, extractTextFromImage } from "@pinta365/steganography";// Load image
const imageData = await Deno.readFile("image.png");
const image = await decodeImage(imageData);
// Embed message
const message = "Hidden secret message";
const modifiedData = embedTextInImage(image.data, message);
// Save image with hidden data
const stegaImage = createImage(image.width, image.height, modifiedData);
const output = await encodeImage(stegaImage, "png");
await Deno.writeFile("stega.png", output);
// Extract message
const loadedImage = await decodeImage(await Deno.readFile("stega.png"));
const extractedMessage = extractTextFromImage(loadedImage.data);
console.log(extractedMessage); // "Hidden secret message"
`$3
typescript
import { decodeImageFrames, embedTextInImageFrames, encodeImageFrames, extractTextFromImageFrames } from "@pinta365/steganography";// Load animated GIF
const gifData = await Deno.readFile("animated.gif");
const multiFrame = await decodeImageFrames(gifData, "gif");
// Embed message in first frame
const message = "Hidden message";
const stegaMultiFrame = embedTextInImageFrames(multiFrame, message, 1, "first");
// Save as GIF
const stegaGifData = await encodeImageFrames("gif", stegaMultiFrame);
await Deno.writeFile("stega.gif", stegaGifData);
// Extract message
const decoded = await decodeImageFrames(stegaGifData, "gif");
const extracted = extractTextFromImageFrames(decoded);
console.log(extracted); // "Hidden message"
`Embedding modes:
-
- Embed only in the first frame (recommended for most cases)
- "all" - Embed the same message in all frames
- "split" - Distribute message across frames (useful for large messages)``
Capacity and Configuration
$3
The library automatically calculates capacity based on your cover media:
- Text Steganography: Capacity depends on cover text length. Each byte requires ~4 zero-width characters. Use
to check capacity.
- Image Steganography: Capacity depends on image dimensions and bit depth. Use to check capacity.$3
All encoding functions support optional configuration via options:
Text Functions (
encodeText, encodeBinary):`typescript
interface EncodeOptions {
maxPayloadBytes?: number; // Override calculated capacity
maxSecretLength?: number; // Max secret size (default: 50KB)
maxCoverLength?: number; // Max cover text size (default: 100KB)
strictCapacity?: boolean; // Throw error vs warn (default: true)
}
``Image Functions (
, embedDataInImage):`typescript
interface ImageEncodeOptions {
maxPayloadBytes?: number; // Override calculated capacity
maxMessageLength?: number; // Max message size (default: 10MB)
strictCapacity?: boolean; // Throw error vs warn (default: true)
}
`$3
By default, the library will throw errors if payload exceeds capacity. Set
to get warnings instead:`typescript
// Warns but continues encoding
const stegaText = await encodeText(cover, secret, undefined, false, {
strictCapacity: false,
});
`$3
typescript
// Check capacity before encoding
const capacity = calculateTextCapacity(coverText);
console.log(Can hide up to ${capacity} bytes);// Override capacity limit
const stegaText = await encodeText(coverText, secret, undefined, false, {
maxPayloadBytes: 10000, // Allow up to 10KB
maxSecretLength: 20000, // Allow up to 20KB secret
});
// Use calculated capacity with warnings
const stegaImage = embedTextInImage(image.data, message, 1, {
strictCapacity: false, // Warn instead of error
});
`API Reference
$3
####
Branded type for steganographic text containing hidden ZWC data. Returned by encoding functions and accepted by decoding functions for type safety.
typescript
type StegaText = string & { readonly __brand: "StegaText" };
`####
Image type from @cross/image, re-exported for convenience. Use for type annotations when working with image helper functions.
typescript
import { decodeImage, Image } from "@pinta365/steganography";const image: Image = await decodeImage(imageData);
`$3
####
Encodes a secret text message into cover text using zero-width characters.
- coverText (
): Visible text that will contain the hidden message
- secretMessage (string): Secret text to hide
- password (string?): Optional password for AES-256-CTR encryption
- distribute (boolean?): If true, distributes ZWC characters throughout text (default: false)
- Returns: Promise - Cover text with invisible ZWC payload embedded####
decodeText(stegaText, password?)Decodes a hidden text message from text with hidden data.
- stegaText (
): Text containing hidden ZWC data
- password (string?): Password if the message was encrypted
- Returns: Promise<{ visibleText: string; secretMessage: string | null }>####
Encodes binary data (images, files) into cover text using zero-width characters.
- coverText (
): Visible text that will contain the hidden data
- binaryData (Uint8Array): Binary data to hide
- password (string?): Optional password for AES-256-CTR encryption
- distribute (boolean?): If true, distributes ZWC characters throughout text (default: false)
- Returns: Promise - Cover text with invisible ZWC payload embedded####
decodeBinary(stegaText, password?)Decodes binary data from text with hidden data.
- stegaText (
): Text containing hidden ZWC data
- password (string?): Password if the data was encrypted
- Returns: Promise<{ visibleText: string; binaryData: Uint8Array | null }>####
Unified decode function that auto-detects payload type (text or binary).
- stegaText (
): Text containing hidden ZWC data
- password (string?): Password if the data was encrypted
- Returns: Promise<{ visibleText: string; payloadType: "text" | "binary" | null; textData: string | null; binaryData: Uint8Array | null }>####
Checks if text contains hidden ZWC steganography data.
- text (
): Text to check
- Returns: boolean####
Returns statistics about hidden data in text.
- text (
): Text to analyze
- Returns: ZWCStats - Object with hasHiddenData, visibleLength, zwcCount, estimatedPayloadBytes, breakdown####
Removes all ZWC characters from text (removes any hidden data).
- text (
): Text to clean
- Returns: string$3
####
Decodes image file data into an Image object.
- imageData (
): Image file data (PNG, JPEG, WebP, etc.)
- Returns: Promise - Image object with width, height, and RGBA data####
encodeImage(image, format, options?)Encodes an Image object to file data.
- image (
): Image object
- format (string): Output format (png, jpeg, webp, etc.)
- options (ImageFormatEncodeOptions?): Optional encoding options (format-specific). See
@cross/image documentation for format-specific option types:
- PNG/APNG: PNGEncoderOptions (compressionLevel: 0-9, default: 6)
- WebP: WebPEncoderOptions (quality: 1-100, lossless: boolean, default: quality: 90)
- TIFF: TIFFEncoderOptions (compression: "none" | "lzw" | "packbits" | "deflate", default: "lzw")
- Other formats: See @cross/image types
- Returns: Promise - Encoded image file data####
createImage(width, height, data)Creates a new Image object.
- width (
): Image width in pixels
- height (number): Image height in pixels
- data (Uint8Array): RGBA image data
- Returns: Image - Image object$3
LSB (Least Significant Bit) steganography embeds data in the least significant bits of image pixels. Works with lossless formats (PNG, WebP lossless,
BMP, etc.). Lossy formats (JPEG) will destroy hidden data on re-encoding.
####
embedTextInImage(imageData, message, bitDepth?, options?)Embeds a text message into image data using LSB (Least Significant Bit).
- imageData (
): RGBA image data
- message (string): Text message to embed
- bitDepth (number?): Bits per pixel (1-4, default: 1)
- options (ImageEncodeOptions?): Optional encoding options (capacity limits, strict mode)
- Returns: Uint8Array - Modified image data####
extractTextFromImage(imageData, bitDepth?)Extracts a text message from image data using LSB. The message length is automatically read from the embedded header.
- imageData (
): RGBA image data
- bitDepth (number?): Bits per pixel (1-4, default: 1)
- Returns: string - Extracted text message####
embedDataInImage(imageData, data, bitDepth?, options?)Embeds binary data into image data using LSB.
- imageData (
): RGBA image data
- data (Uint8Array): Binary data to embed
- bitDepth (number?): Bits per pixel (1-4, default: 1)
- options (ImageEncodeOptions?): Optional encoding options (capacity limits, strict mode)
- Returns: Uint8Array - Modified image data####
extractDataFromImage(imageData, dataLength, bitDepth?)Extracts binary data from image data using LSB.
- imageData (
): RGBA image data
- dataLength (number): Length of the data in bytes
- bitDepth (number?): Bits per pixel (1-4, default: 1)
- Returns: Uint8Array - Extracted binary data####
embedLSB(imageData, messageBits, bitDepth?)Low-level function to embed bits into image pixels.
- imageData (
): RGBA image data
- messageBits (Uint8Array): Bits to embed
- bitDepth (number?): Bits per pixel (1-4, default: 1)
- Returns: Uint8Array - Modified image data####
extractLSB(imageData, bitCount, bitDepth?)Low-level function to extract bits from image pixels.
- imageData (
): RGBA image data
- bitCount (number): Number of bits to extract
- bitDepth (number?): Bits per pixel (1-4, default: 1)
- Returns: Uint8Array - Extracted bits####
calculateBitCapacity(width, height, bitDepth?)Calculates the bit capacity of an image.
- width (
): Image width in pixels
- height (number): Image height in pixels
- bitDepth (number?): Bits per pixel (1-4, default: 1)
- Returns: number - Number of bytes that can be hidden####
generateLSBStats(imageData, originalData?)Generates LSB statistics for display.
- imageData (
): RGBA image data
- originalData (Uint8Array?): Original image data for comparison
- Returns: Object with LSB statistics per channel (red, green, blue, total)$3
####
embedDataInJpegCoefficients(coefficients, data, useChroma?)Embeds binary data into JPEG coefficients using DCT coefficient-domain embedding.
- coefficients (
): JPEG quantized coefficients (will be modified)
- data (Uint8Array): Binary data to embed
- useChroma (boolean?): Use chroma components (default: true)
- Returns: JPEGQuantizedCoefficients - Modified coefficients####
extractDataFromJpegCoefficients(coefficients, maxBytes, useChroma?)Extracts binary data from JPEG coefficients.
- coefficients (
): JPEG quantized coefficients
- maxBytes (number): Maximum number of bytes to extract
- useChroma (boolean?): Extract from chroma components (default: true)
- Returns: Uint8Array - Extracted binary data####
embedInCoefficients(coefficients, messageBits, useChroma?)Low-level function to embed bits into JPEG coefficients.
- coefficients (
): JPEG quantized coefficients (will be modified)
- messageBits (Uint8Array): Bits to embed
- useChroma (boolean?): Use chroma components (default: true)
- Returns: JPEGQuantizedCoefficients - Modified coefficients####
extractFromCoefficients(coefficients, bitCount, useChroma?)Low-level function to extract bits from JPEG coefficients.
- coefficients (
): JPEG quantized coefficients
- bitCount (number): Number of bits to extract
- useChroma (boolean?): Extract from chroma components (default: true)
- Returns: Uint8Array - Extracted bits####
calculateJpegCoefficientCapacity(coefficients, useChroma?)Calculates the embedding capacity of JPEG coefficients.
- coefficients (
): JPEG quantized coefficients
- useChroma (boolean?): Include chroma components (default: true)
- Returns: number - Number of bytes that can be hidden####
extractJpegCoefficients(jpegData)Extracts JPEG quantized coefficients from JPEG data.
- jpegData (
): JPEG file data
- Returns: Promise####
Encodes JPEG from quantized coefficients.
- coefficients (
): JPEG quantized coefficients
- Returns: Promise - JPEG file data####
cloneJpegCoefficients(coefficients)Deep clones JPEG coefficients to avoid modifying the original.
- coefficients (
): JPEG quantized coefficients
- Returns: JPEGQuantizedCoefficients - Cloned coefficients$3
####
bytesToBits(bytes)Converts a byte array to a bit array (LSB first).
- bytes (
): Bytes to convert
- Returns: Uint8Array - Bit array####
bitsToBytes(bits)Converts a bit array back to bytes (LSB first).
- bits (
): Bits to convert
- Returns: Uint8Array - Byte array####
xorEncrypt(data, password)XOR encrypts data using a cyclic password key.
- data (
): Data to encrypt
- password (string): Password key
- Returns: Uint8Array - Encrypted data####
xorDecrypt(data, password)XOR decrypts data (XOR is its own inverse).
- data (
): Data to decrypt
- password (string): Password key
- Returns: Uint8Array - Decrypted data####
detectImageFormat(data)Detects image format from file data.
- data (
): Image file data
- Returns: string | null - Format name or null if unknown####
isLossyFormat(format)Checks if a format is lossy (will destroy pixel-domain embedding data on re-encoding).
- format (
): Format name
- Returns: boolean####
Gets a recommended output format based on input format.
- inputFormat (
): Input format name
- Returns: Object with format, reason, and optional useWebP`MIT