lsb-tool 2.0.0__py3-none-any.whl

lsb_tool-2.0.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: lsb-tool
+Version: 2.0.0
+Summary: Embed and extract files hidden inside PNG images using N-bit LSB steganography.
+License-Expression: MIT
+Keywords: steganography,lsb,png,embed,security
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=8.0
+Requires-Dist: numpy>=1.20
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# LSB Tool
+
+Embed files inside a PNG image or extract previously hidden files using
+**N-bit LSB steganography** secured by a password.
+
+Files are scattered across pixels in a password-derived pseudo-random order so
+the hidden data is not readable by standard steganalysis tools that scan
+sequential pixel runs.
+
+---
+
+## Features
+
+| | |
+|-|-|
+| **All image modes** | 1-bit, 8-bit grayscale/palette, 16-bit grayscale, RGB, RGBA |
+| **N-bit embedding** | Store 1–N bits per channel (N limited by channel bit-depth) |
+| **Multiple files** | Embed any number of files in a single carrier image |
+| **Filename storage** | Optionally preserve original filenames on extraction |
+| **Error codes** | Every failure exits with a distinct code — see [ERRORS.md](ERRORS.md) |
+
+---
+
+## Requirements
+
+- Python 3.8+
+- Pillow ≥ 8.0
+- NumPy ≥ 1.20
+
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## Usage
+
+### Embed
+
+```bash
+python main.py -E -i carrier.png -p password -f file1.txt file2.bin
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `-i` | Carrier image (any PIL-supported format; output is always PNG) |
+| `-p` | Password used to derive the pixel-shuffle seed and verification hash |
+| `-f` | One or more files to embed |
+| `-l` | Bits per channel to use — **embedding depth** (default `1`, max depends on image type) |
+| `-n` | Filename field length in bytes 0–255 (default `0` = filenames not stored) |
+| `-v` | Print capacity and hash diagnostics after the operation |
+
+Output: `<original_name>_embedded.png` in the current directory.
+
+### Extract
+
+```bash
+python main.py -e -i carrier_embedded.png -p password
+```
+
+Extracted files are written to the current directory.  If `-n` was used during
+embedding, the original filenames are restored; otherwise files are named
+`extracted_file_0`, `extracted_file_1`, …
+
+---
+
+## Embedding depth (`-l`)
+
+Higher depth stores more bits per channel, multiplying capacity roughly
+proportionally, but making changes more visible to the human eye.
+
+| Image type | Max depth | Capacity formula (bytes) |
+|------------|-----------|--------------------------|
+| 1-bit (`1`) | 1 | `(pixels − 5) × 1 / 8` |
+| 8-bit (`L`, `LA`, `RGB`, `RGBA`, `P`) | 8 | `(pixels − preamble) × channels × depth / 8` |
+| 16-bit grayscale (`I;16`) | 16 | same formula |
+
+If you request a depth greater than the image supports, the tool warns and
+clamps to the maximum automatically.
+
+---
+
+## Examples
+
+```bash
+# Embed two files at depth 1 (default)
+python main.py -E -i photo.png -p hunter2 -f report.pdf archive.zip
+
+# Extract (restores original files)
+python main.py -e -i photo_embedded.png -p hunter2
+
+# Embed with filename storage and depth 4
+python main.py -E -i photo.png -p hunter2 -f secret.txt -l 4 -n 32
+
+# Extract — file is written as "secret.txt" instead of "extracted_file_0"
+python main.py -e -i photo_embedded.png -p hunter2
+
+# Check capacity (verbose)
+python main.py -E -i photo.png -p hunter2 -f data.bin -v
+```
+
+---
+
+## Image format note
+
+Always use PNG for the carrier image.  Lossy formats (JPEG, WebP) alter pixel
+values after saving and will destroy the hidden data.  The tool always saves
+output as PNG regardless of the input format.
+
+---
+
+## Running tests
+
+```bash
+pip install pytest
+pytest tests/ -v
+```
+
+---
+
+## Error codes
+
+All errors exit with a specific code and print `[Exx] …` to stderr.
+See [ERRORS.md](ERRORS.md) for the full reference.
+
+| Code | Meaning |
+|------|---------|
+| E02 | No mode selected (`-E` or `-e` required) |
+| E03 | Carrier image not found |
+| E04 | A file to embed was not found |
+| E05 | Files too large for this image at the chosen depth |
+| E06 | Wrong password or no embedded data |
+| E07 | Image file is corrupt or unsupported |
+| E08 | Cannot write an output file |
+| E10 | Internal error (bug) |
+
+---
+
+## How it works
+
+1. **Key derivation** — The password and image dimensions are hashed (SHA-256,
+   iterated `width × height` times) to produce a 64-character hex digest.
+2. **Pixel shuffle** — A NumPy PCG64 RNG seeded from the digest shuffles all
+   pixel coordinates into a pseudo-random order.
+3. **Preamble** — The first `⌈13/channels⌉` shuffled pixels store a 13-bit
+   header at LSB-only depth: 5 bits for the embedding depth, 8 bits for the
+   filename-field length.
+4. **Main data** — Remaining shuffled pixels carry the payload at the chosen
+   depth using the formula `bit k → pixel = k ÷ (channels × depth)`,
+   `channel = (k ÷ depth) mod channels`, `bit_pos = k mod depth`.
+5. **Verification** — The first 512 bits of the main region store the
+   password-derived SHA-256 hash as ASCII.  Extraction fails with E06 if it
+   does not match.

lsb_tool-2.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+main.py,sha256=yKZTyyUsuWmn9OklwSqJf3P2TnaiYUlGiCWTYnD_2-4,3578
+util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+util/container.py,sha256=2qB1GkbmkJIA_Wtt8hFHmdiPhDVru5j3RPIeRR30rn4,7626
+util/errors.py,sha256=8hqXVmJHmGeRqEBndb-bN5doP6fxXjkqafcgoO3offE,1430
+util/security.py,sha256=Yuo7U4393_hVEZy_Gl3wr2N7y9PmhQNGiy461xCqNT4,2140
+util/utils.py,sha256=_Ja2uSxu5F3nqU5k8Zo28vWe2sj3gNcEOLID4HdGGXc,12665
+lsb_tool-2.0.0.dist-info/METADATA,sha256=QlrgBmAeO7i5d6V8HTJ8At1kBC0SJPK4Hr0-uZbzeI8,5511
+lsb_tool-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+lsb_tool-2.0.0.dist-info/entry_points.txt,sha256=hCr-1TrTMg-pknLfhqjzhF4D31O4gpW8xuHam3GaoIQ,39
+lsb_tool-2.0.0.dist-info/top_level.txt,sha256=bCJ8VhbgyTOrXkuBR6DxWcF940BOuPvpaBhclPUU-5g,10
+lsb_tool-2.0.0.dist-info/RECORD,,

lsb_tool-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lsb_tool-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lsb-tool = main:main

lsb_tool-2.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+main
+util

main.py

@@ -0,0 +1,105 @@
+#! /usr/bin/env python3
+"""LSB Steganography Tool – CLI entry point.
+
+Embeds files inside a PNG image or extracts previously embedded files from one,
+using Least Significant Bit (LSB) steganography secured by a password.
+
+Usage:
+  Embed:   main.py -E -i <image> -p <password> -f <file1> [file2 ...] [-l <level>] [-n <len>] [-v]
+  Extract: main.py -e -i <image> -p <password> [-v]
+
+Arguments:
+  -i   Source image (any PIL-supported format; output is always PNG).
+  -p   Password used to derive the shuffle seed and header hash.
+  -f   One or more files to embed (embed mode only).
+  -l   LSB depth level 1–N (default 1; N depends on image type — see ERRORS.md).
+  -n   Filename field length in bytes 0–255 (default 0; 0 = no filenames stored).
+  -e   Extract mode: read and save files hidden in the image.
+  -E   Embed mode: hide files inside the image.
+  -v   Verbose: print capacity and hash diagnostics after the operation.
+
+Output:
+  Embed:   <original_name>_embedded.png written to the current directory.
+  Extract: Files written to the current directory, named by stored filename or
+           extracted_file_0, extracted_file_1, … if no filename was stored.
+
+Error codes are documented in ERRORS.md.
+"""
+
+import sys
+from argparse import ArgumentParser
+from pathlib import Path
+
+from util.container import Container
+from util.errors import die, E
+from util.utils import status
+
+
+def _build_parser():
+	parser = ArgumentParser(
+		description="Embed or extract files hidden inside a PNG image using LSB steganography."
+	)
+	parser.add_argument("-i", type=Path, help="Image to embed files in / extract from",
+	                    required=True)
+	parser.add_argument("-p", type=str, help="Embedding password", required=True)
+	parser.add_argument("-f", type=Path, help="File(s) to embed (embed mode only)", nargs="+")
+	parser.add_argument("-l", type=int,
+	                    help="Embedding depth in bits per channel (default 1)", default=1)
+	parser.add_argument("-n", "--max-name-len", type=int,
+	                    help="Filename field length in bytes 0–255 (default 0 = no names)",
+	                    default=0)
+	parser.add_argument("-e", help="Extract files hidden in the image", action="store_true")
+	parser.add_argument("-E", help="Embed files into the image", action="store_true")
+	parser.add_argument("-v", help="Print capacity and hash diagnostics", action="store_true")
+	return parser
+
+
+def main():
+	parser = _build_parser()
+	args = parser.parse_args()
+
+	if not args.i.exists():
+		die(E.IMAGE_NOT_FOUND, f"Image file '{args.i}' not found.")
+
+	if args.E:  # Embedding
+		missing = [f for f in args.f if not f.exists()]
+		if missing:
+			for f in missing:
+				print(f"[E{E.EMBED_FILE_NOT_FOUND:02d}] File to embed not found: '{f}'",
+				      file=sys.stderr)
+			sys.exit(E.EMBED_FILE_NOT_FOUND)
+
+		image = Container(args.i, args.p)
+		image.set_level(args.l)
+		image.set_max_name_len(args.max_name_len)
+
+		for f in args.f:
+			image.add_file(f)
+
+		print(f"Embedding {len(args.f)} file(s) into '{args.i}' at depth {image.depth}...",
+		      flush=True)
+		image.embed()
+
+		out_name = "".join(str(args.i).split('/')[-1].split('.')[:-1]) + "_embedded.png"
+		print(f"Saving '{out_name}'...", flush=True)
+		image.save()
+		print("Done.")
+
+		if args.v:
+			status(image)
+
+	elif args.e:  # Extraction
+		image = Container(args.i, args.p)
+
+		print(f"Extracting from '{args.i}'...", flush=True)
+		image.extract()
+
+		if args.v:
+			status(image)
+
+	else:
+		die(E.INVALID_ARGS, "No mode selected. Use -E to embed files or -e to extract.")
+
+
+if __name__ == "__main__":
+	main()

util/container.py

@@ -0,0 +1,197 @@
+from util.security import get_hash, get_generator, verify_hash
+from util.utils import embed_files, test_fit, extract_hash, extract_files, read_preamble
+from util.errors import die, E
+from PIL import Image, UnidentifiedImageError
+from math import prod, ceil
+from pathlib import Path
+
+class Container:
+	"""Wraps a PIL image and provides LSB steganography embed/extract operations.
+
+	On construction the image is opened, its pixels are loaded into a mutable
+	pixel-access object, and a password-derived shuffle of all pixel coordinates
+	is computed. Every subsequent read or write uses that shuffled order so that
+	data is scattered pseudo-randomly across the image rather than written
+	sequentially from the top-left corner.
+
+	Layout (in the shuffled pixel stream):
+
+	  Preamble (first ceil(13/channels) pixels, always LSB/depth=1):
+	    bits 0-4  : depth (5-bit uint, 1–32; max valid value depends on image mode)
+	    bits 5-12 : max_name_len (8-bit uint)
+
+	  Main data (remaining pixels, depth=N bits per channel):
+	    [0   – 511]           : SHA-256 hash of the password (64 ASCII chars × 8 bits)
+	    [512 – 543]           : number of embedded files (32-bit uint)
+	    per file:
+	      32 bits             : file size in bytes
+	      max_name_len*8 bits : filename, UTF-8, zero-padded (omitted if max_name_len=0)
+	    [remainder]           : raw file bytes, concatenated
+	"""
+
+	supported_modes = ['1', 'I', 'I;16', 'L', 'LA', 'P', 'RGB', 'RGBA']
+
+	# Number of channels per pixel (= max LSBs at depth=1).
+	bits = {	'1':1, 'I':1, 'I;16':1, 'L':1, 'P':1, #grayscale images
+				'LA':2, #grayscale with alpha channel
+				'RGB':3, #true color
+				'RGBA':4 #true color with alpha channel
+			}
+
+	# Bit-depth of each channel value (stored here for reference / future use).
+	depths = {	'1':1, #1-bit pixel values
+				'L':8, 'P':8, 'LA':8, 'RGB':8, 'RGBA':8, #8-bit pixel values
+				'I;16':16, #16-bit pixel values
+				'I':32 #32-bit pixel values
+			}
+
+	def __init__(self, filename, password):
+		"""Open an image file and prepare it for steganographic operations.
+
+		If the image mode is not in supported_modes it is converted to RGBA,
+		which is the most capable supported mode (4 bits/pixel).
+
+		The pixel coordinate list is shuffled using an RNG seeded from the
+		password hash so that the storage positions are unpredictable without
+		the password.
+
+		Args:
+			filename (str | Path): Path to the source image file.
+			password (str): Password used to derive the hash and shuffle seed.
+		"""
+		#Image elements
+		self.filename = str(filename)
+		try:
+			self.img = Image.open(filename)
+		except (UnidentifiedImageError, OSError) as exc:
+			die(E.IMAGE_LOAD_ERROR,
+			    f"Could not open '{filename}' as an image. "
+			    f"The file may be corrupt, truncated, or in an unsupported format.")
+
+		#Checking if the image is supported as it is, converting otherwise
+		if self.img.mode not in self.supported_modes:
+			self.img = self.img.convert("RGBA") #Best type for embedding
+
+		self.size = self.img.size          # (width, height) tuple
+		self.pixels = self.img.load()      # Mutable PixelAccess object
+
+		#Security elements
+		self.hash = get_hash(password, self)
+		self.rng = get_generator(self.hash)
+		# Build a flat list of (x, y) coordinates for every pixel, then shuffle
+		# it so data is written in a password-dependent pseudo-random order.
+		self.pixel_values = [(i//self.size[1], i%self.size[1]) for i in range(prod(self.size))]
+		self.rng.shuffle(self.pixel_values)
+
+		#Key elements
+		self.files = []      # List of bytes objects, one per file to embed/extract
+		self.filenames = []  # Original filenames, one per file
+		self.depth = 1       # LSB embedding depth (1–8)
+		self.max_name_len = 0  # Filename field length in bytes (0 = no filename stored)
+
+	def add_file(self, filename):
+		"""Read a file from disk and queue it for embedding.
+
+		Args:
+			filename (str | Path): Path to the file to embed.
+		"""
+		with open(filename, "rb") as f:
+			self.files.append(f.read())
+		self.filenames.append(Path(filename).name)
+
+	def set_level(self, level):
+		"""Set the LSB embedding depth level.
+
+		The maximum allowed depth is the bit-depth of the image's channel type:
+		  1-bit ('1'):               depth capped at 1
+		  8-bit ('L','P','LA',etc.): depth capped at 8
+		  16-bit ('I;16'):           depth capped at 16
+		  32-bit ('I'):              depth capped at 32
+
+		Deeper levels store more bits per channel, increasing capacity at the
+		cost of more visible image degradation.
+
+		Args:
+			level (int): Desired bit depth (clamped to 1 – channel bit-depth).
+		"""
+		max_depth = self.depths.get(self.img.mode, 8)
+		clamped = max(1, min(max_depth, level))
+		if clamped != level:
+			print(f"Warning: depth {level} is not supported by this image type "
+			      f"(max {max_depth} for '{self.img.mode}' mode). Using depth={clamped}.")
+		self.depth = clamped
+
+	def set_max_name_len(self, n):
+		"""Set the per-file filename field length in bytes (0–255).
+
+		Set to 0 (the default) to omit filenames entirely; extracted files
+		will be named extracted_file_0, extracted_file_1, etc.
+
+		Args:
+			n (int): Filename field size in bytes (clamped to 0–255).
+		"""
+		self.max_name_len = max(0, min(255, n))
+
+	def embed(self):
+		"""Write all queued files into the image using LSB steganography.
+
+		Verifies the payload fits before writing; exits with E05 if not.
+		"""
+		channels = self.bits[self.img.mode]
+		test_fit(self, channels, self.depth)   # exits via die() if too large
+		embed_files(self, channels, self.depth)
+
+	def extract(self):
+		"""Extract previously embedded files from the image and write them to disk.
+
+		Reads the preamble to determine the embedding depth and filename field
+		length, then verifies the header hash. If the hash matches, reads all
+		embedded files and writes them to the current directory using either the
+		stored filename (if max_name_len > 0) or extracted_file_<index>.
+		"""
+		channels = self.bits[self.img.mode]
+		preamble_pixels = ceil(13 / channels)
+
+		depth, max_name_len = read_preamble(self)
+		self.depth = depth
+		self.max_name_len = max_name_len
+
+		hash_string = extract_hash(self, channels, depth, preamble_pixels)
+
+		if verify_hash(self, hash_string):
+			extract_files(self, channels, depth, preamble_pixels, max_name_len)
+			written = []
+			for i, (file_data, filename) in enumerate(zip(self.files, self.filenames)):
+				out_name = filename if filename else f"extracted_file_{i}"
+				try:
+					with open(out_name, "wb") as f:
+						f.write(file_data)
+				except OSError:
+					die(E.WRITE_ERROR,
+					    f"Could not write '{out_name}'. "
+					    f"Check that you have write permission in the current directory.")
+				written.append(out_name)
+			print(f"Extracted {len(written)} file(s): {written}")
+		else:
+			die(E.WRONG_PASSWORD,
+			    "Could not verify the embedded data. "
+			    "The password may be incorrect, or this image contains no hidden files.")
+
+	def save(self):
+		"""Save the modified image as a PNG file in the current directory.
+
+		The output filename is derived from the original filename by stripping
+		the extension and appending ``_embedded.png``.
+		PNG is used to guarantee lossless storage of the modified pixel values;
+		a lossy format (e.g. JPEG) would destroy the hidden data.
+		"""
+		new_file = "".join(self.filename.split('/')[-1].split('.')[:-1])
+		self.img.save(new_file+"_embedded.png", format="png")
+
+	def reset_rng(self):
+		"""Re-seed the RNG to its initial state using the stored hash.
+
+		Useful if you need to replay the pixel shuffle from the beginning
+		(e.g. for a second pass over the image).
+		"""
+		self.rng = get_generator(self.hash)

util/errors.py

@@ -0,0 +1,35 @@
+"""Exit codes and error-reporting for the LSB steganography tool.
+
+All user-visible errors are routed through ``die()``, which prints a
+human-readable message prefixed with the error code and exits with that
+code as the process exit status.  Codes are documented in full in
+ERRORS.md at the project root.
+"""
+
+import sys
+
+
+class E:
+    """Exit-code constants.  See ERRORS.md for the authoritative reference."""
+    INVALID_ARGS         = 2   # Bad or missing CLI arguments (shared with argparse)
+    IMAGE_NOT_FOUND      = 3   # Source image file does not exist on disk
+    EMBED_FILE_NOT_FOUND = 4   # A file queued for embedding does not exist
+    IMAGE_TOO_SMALL      = 5   # Payload does not fit at the chosen depth
+    WRONG_PASSWORD       = 6   # Hash mismatch during extraction
+    IMAGE_LOAD_ERROR     = 7   # PIL cannot open / decode the image
+    WRITE_ERROR          = 8   # Cannot write an output file
+    INTERNAL_ERROR       = 10  # Should never be reached; indicates a bug
+
+
+def die(code, message):
+    """Print a user-friendly error and exit with ``code``.
+
+    Output is written to stderr so it does not pollute piped stdout.
+    The ``[Exx]`` prefix lets users cross-reference ERRORS.md quickly.
+
+    Args:
+        code (int):    One of the ``E.*`` constants.
+        message (str): Plain-language description of what went wrong.
+    """
+    print(f"[E{code:02d}] {message}", file=sys.stderr)
+    sys.exit(code)

util/security.py

@@ -0,0 +1,61 @@
+import hmac
+from hashlib import sha256
+from numpy.random import default_rng
+from math import prod
+
+def get_hash(password, img):
+	"""Derive a deterministic SHA-256 hash from a password and image dimensions.
+
+	The password is salted with the image size string, then hashed repeatedly
+	prod(width * height) times to make brute-force attacks expensive. A final
+	SHA-256 pass produces the output hex digest.
+
+	Args:
+		password (str): The user-supplied embedding/extraction password.
+		img: A Container instance (must have a .size attribute of (width, height)).
+
+	Returns:
+		str: A 64-character lowercase hex SHA-256 digest used as both the
+		     header verification token and the RNG seed.
+	"""
+	password = password+str(img.size)
+	rounds = prod(img.size)
+	for i in range(rounds):
+		password = sha256(password.encode()).hexdigest()
+	return sha256(password.encode()).hexdigest()
+
+def get_generator(seed):
+	"""Create a NumPy random Generator seeded from a hex hash string.
+
+	The hex digest is converted to an integer so it can serve as a numeric seed
+	for numpy's default_rng (PCG64). The same seed always produces the same
+	pixel shuffle order, which is required for both embedding and extraction.
+
+	Args:
+		seed (str): A hex string (e.g. the output of get_hash).
+
+	Returns:
+		numpy.random.Generator: A seeded RNG used to shuffle pixel coordinates.
+	"""
+	return default_rng(seed=int(seed, 16))
+
+def verify_hash(container, hsh):
+	"""Check whether an extracted header hash matches the container's expected hash.
+
+	Called during extraction to confirm that the correct password was supplied
+	and that the image actually contains embedded data.
+
+	Args:
+		container: A Container instance with a .hash attribute.
+		hsh (str): The hash string read back from the image header.
+
+	Returns:
+		bool: True if the hashes match (correct password / data present).
+	"""
+	try:
+		return hmac.compare_digest(container.hash, hsh)
+	except TypeError:
+		# hsh may contain non-ASCII characters when the password is wrong and
+		# the extracted bit-stream decodes to arbitrary Unicode code points.
+		# Any such mismatch is definitively a failed verification.
+		return False

util/utils.py

@@ -0,0 +1,370 @@
+from math import prod, ceil
+from pathlib import Path
+from util.errors import die, E
+
+# Header size lookup table (kept for future reference / validation use).
+# Each entry is [hash_bits, file_count_bits, ???, total_bits] for a given mode.
+# Not actively used in the current implementation; computed values in
+# embed_files / test_fit are the authoritative source.
+header_size = {
+	**dict.fromkeys(['1', 'I', 'I;16', 'L', 'P'], [504, 32, 32, 568]), #For grayscale and black/white images (1 channel)
+	**dict.fromkeys(['LA'], [504, 32, 33, 569]), #For grayscale with alpha channel (2 channels)
+	**dict.fromkeys(['RGB', 'RGBA'], [504, 32, 34, 570]) #For true color (3 and 4 channels)
+}
+
+
+
+def inject_pixel(orig, adder, bit_pos=0):
+	"""Write one message bit into each channel of a single pixel at the given bit position.
+
+	For each channel: if the message bit is 1, bit ``bit_pos`` is set; if 0 it is
+	cleared. ``bit_pos=0`` (the default) modifies the LSB, reproducing the
+	original behaviour.
+
+	When ``adder`` has fewer elements than ``orig`` (e.g. embedding 3-bit data
+	into an RGBA pixel), the missing channels are copied from the original so
+	those channels are left untouched.
+
+	Args:
+		orig (tuple | int): The original pixel value. A tuple for multi-channel
+		                    modes (RGB, RGBA, LA), or a plain int for grayscale.
+		adder (list[int]):  Message bits to write, one per channel (0 or 1).
+		bit_pos (int):      Which bit of each channel to modify (0 = LSB).
+
+	Returns:
+		tuple: The modified pixel value with the target bit updated.
+	"""
+	adder = list(adder)  # prevent in-place mutation of caller's list
+	mask = 1 << bit_pos
+	inject = lambda x: (x[0] | mask) if x[1] else (x[0] & ~mask)
+
+	try:
+		final = list(orig)
+	except:
+		final = [orig]
+
+	if len(final) == len(adder):
+		final = list(map(inject, [(final[i], adder[i]) for i in range(len(adder))]))
+		return tuple(final)
+	elif len(adder) < len(orig):
+		# Fewer message bits than channels: leave the extra channels unchanged
+		for i in range(len(adder), len(orig)):
+			adder.append(orig[i])
+		final = list(map(inject, [(final[i], adder[i]) for i in range(len(adder))]))
+		return tuple(final)
+	else:
+		# Should never happen: more message bits than pixel channels
+		die(E.INTERNAL_ERROR,
+		    "inject_pixel received more bits than the pixel has channels. "
+		    "Please report this as a bug.")
+
+
+
+def extract_pixel(orig, channel, bit_pos=0):
+	"""Read one bit from a specific channel of a pixel.
+
+	Args:
+		orig (tuple | int): Pixel value (tuple for multi-channel, int for grayscale).
+		channel (int):      Zero-based channel index to read from.
+		bit_pos (int):      Which bit to read (0 = LSB).
+
+	Returns:
+		int: The requested bit (0 or 1).
+	"""
+	try:
+		orig = list(orig)
+	except:
+		orig = [orig]
+
+	return (orig[channel] >> bit_pos) & 1
+
+
+
+# Split a flat list/string into 8-element chunks (used to reassemble bytes from bits).
+splitup = lambda arr: [arr[i:i+8] for i in range(0, len(arr), 8)]
+
+
+
+def _bits_to_str(bits):
+	return "".join([str(b) for b in bits])
+
+
+def _write_preamble_bit(container, k, bit, channels):
+	"""Write a single bit to position k in the preamble region (always LSB, depth=1)."""
+	pixel_idx = k // channels
+	ch = k % channels
+	x, y = container.pixel_values[pixel_idx]
+	try:
+		p = list(container.pixels[x, y])
+	except:
+		p = [container.pixels[x, y]]
+	if bit:
+		p[ch] |= 1
+	else:
+		p[ch] &= ~1
+	# Mode "1": PIL normalises any non-zero value to 255 on storage.
+	# 255 & ~1 = 254 (non-zero) would be stored as 255, flipping a 0-bit back to 1.
+	# Explicitly write 0 or 255 so the LSB reads back correctly.
+	if container.img.mode == '1':
+		p[ch] = 255 if (p[ch] & 1) else 0
+	container.pixels[x, y] = tuple(p)
+
+
+def _read_preamble_bit(container, k, channels):
+	"""Read a single bit from position k in the preamble region (always LSB, depth=1)."""
+	pixel_idx = k // channels
+	ch = k % channels
+	x, y = container.pixel_values[pixel_idx]
+	return extract_pixel(container.pixels[x, y], ch, 0)
+
+
+def _write_main_bit(container, k, bit, channels, depth, preamble_pixels):
+	"""Write a single bit to position k in the main data region."""
+	pixel_idx = k // (channels * depth)
+	ch = (k // depth) % channels
+	bp = k % depth
+	x, y = container.pixel_values[preamble_pixels + pixel_idx]
+	mask = 1 << bp
+	try:
+		p = list(container.pixels[x, y])
+	except:
+		p = [container.pixels[x, y]]
+	if bit:
+		p[ch] |= mask
+	else:
+		p[ch] &= ~mask
+	# Mode "1": same normalisation as _write_preamble_bit — avoid 254→255 rounding.
+	if container.img.mode == '1':
+		p[ch] = 255 if (p[ch] & mask) else 0
+	container.pixels[x, y] = tuple(p)
+
+
+def _read_main_bit(container, k, channels, depth, preamble_pixels):
+	"""Read a single bit from position k in the main data region."""
+	pixel_idx = k // (channels * depth)
+	ch = (k // depth) % channels
+	bp = k % depth
+	x, y = container.pixel_values[preamble_pixels + pixel_idx]
+	return extract_pixel(container.pixels[x, y], ch, bp)
+
+
+def read_preamble(container):
+	"""Read the 12-bit preamble and return (depth, max_name_len).
+
+	The preamble is always stored at LSB (bit_pos=0), using the first
+	ceil(13 / channels) pixels in the shuffled order.
+
+	  bits 0-4  : depth        (5-bit uint, values 1-32)
+	  bits 5-12 : max_name_len (8-bit uint, values 0-255)
+
+	Args:
+		container: A Container instance.
+
+	Returns:
+		tuple[int, int]: (depth, max_name_len)
+	"""
+	channels = container.bits[container.img.mode]
+	bits = [_read_preamble_bit(container, k, channels) for k in range(13)]
+	depth = int(_bits_to_str(bits[0:5]), 2)
+	max_name_len = int(_bits_to_str(bits[5:13]), 2)
+	# Clamp depth to a valid range so a bad password doesn't cause division by zero
+	depth = max(1, min(32, depth))
+	return depth, max_name_len
+
+
+
+def embed_files(container, channels, depth):
+	"""Encode the preamble, header, filenames, and file data into the container's pixels.
+
+	Layout:
+	  Preamble (first ceil(13/channels) pixels, depth=1):
+	    5 bits: depth
+	    8 bits: max_name_len
+
+	  Main data region (remaining pixels, depth=N):
+	    512 bits : hash (64 ASCII chars)
+	     32 bits : num_files
+	    per file:
+	      32 bits              : file size in bytes
+	      max_name_len*8 bits  : filename bytes, UTF-8, zero-padded (omitted if max_name_len=0)
+	    file data (concatenated)
+
+	Args:
+		container: A Container instance with .hash, .files, .filenames,
+		           .max_name_len, and .pixel_values attributes.
+		channels (int): Number of channels in the image (bits per pixel at depth=1).
+		depth (int):    Number of LSBs per channel to use (1–8).
+	"""
+	preamble_pixels = ceil(13 / channels)
+
+	# Write 13-bit preamble (always depth=1, bit_pos=0)
+	preamble_bits = f"{depth:05b}{container.max_name_len:08b}"
+	for k in range(13):
+		_write_preamble_bit(container, k, int(preamble_bits[k]), channels)
+
+	# Build main message: hash + num_files + per-file (size [+ name]) + file data
+	header = "".join([f"{ord(c):08b}" for c in container.hash])  # 512 bits
+	header += f"{len(container.files):032b}"
+
+	for i, file_data in enumerate(container.files):
+		header += f"{len(file_data):032b}"
+		if container.max_name_len > 0:
+			name = container.filenames[i] if i < len(container.filenames) else ""
+			name_bytes = name.encode('utf-8')[:container.max_name_len]
+			name_bytes = name_bytes + b'\x00' * (container.max_name_len - len(name_bytes))
+			header += "".join([f"{b:08b}" for b in name_bytes])
+
+	files_bits = "".join(
+		["".join([f"{b:08b}" for b in file_data]) for file_data in container.files]
+	)
+	message = header + files_bits
+
+	for k in range(len(message)):
+		_write_main_bit(container, k, int(message[k]), channels, depth, preamble_pixels)
+
+
+
+def test_fit(container, channels, depth):
+	"""Check whether the queued files will fit inside the image.
+
+	Args:
+		container: A Container instance.
+		channels (int): Number of channels in the image.
+		depth (int):    Number of LSBs per channel to use.
+
+	Returns:
+		bool: True if the message fits, False otherwise.
+	"""
+	preamble_pixels = ceil(13 / channels)
+	total_pixels = prod(container.size)
+	main_pixels = total_pixels - preamble_pixels
+	main_capacity = main_pixels * channels * depth
+
+	name_bits_per_file = container.max_name_len * 8
+	files_data_bits = sum([len(f) for f in container.files]) * 8
+	message_size = 512 + 32 + (32 + name_bits_per_file) * len(container.files) + files_data_bits
+
+	if message_size > main_capacity:
+		needed_bytes   = (message_size + 7) // 8
+		available_bytes = main_capacity // 8
+		die(E.IMAGE_TOO_SMALL,
+		    f"The files are too large to embed in this image at depth {depth}.\n"
+		    f"  Required : {needed_bytes:,} bytes\n"
+		    f"  Available: {available_bytes:,} bytes\n"
+		    f"  Try a larger image, increase the depth with -l, or embed fewer files.")
+	return True
+
+
+
+def status(container):
+	"""Print a diagnostic summary of the container's capacity and contents.
+
+	Args:
+		container: A Container instance (used after embed or extract).
+	"""
+	channels = container.bits[container.img.mode]
+	depth = container.depth
+	preamble_pixels = ceil(13 / channels)
+	total_pixels = prod(container.size)
+	main_pixels = total_pixels - preamble_pixels
+	capacity = main_pixels * channels * depth
+
+	name_bits_per_file = container.max_name_len * 8
+	files_data_bits = sum([len(f) * 8 for f in container.files])
+	message_size = 512 + 32 + (32 + name_bits_per_file) * len(container.files) + files_data_bits
+
+	print(f"""
+{container.filename}
+
+Embedded files sizes: {[len(i) for i in container.files]}
+
+->{container.hash}
+->{container.rng}
+->{container.img.mode} mode
+->{container.size} pixels
+->{channels * depth} estimated bits/pixel (depth={depth})
+->{capacity} estimated bits to fit
+->{message_size} estimated message size
+""")
+
+
+
+def extract_hash(container, channels, depth, preamble_pixels):
+	"""Read the 512-bit hash from the beginning of the embedded main data region.
+
+	Args:
+		container: A Container instance whose pixel_values have been shuffled.
+		channels (int): Number of channels in the image.
+		depth (int):    Embedding depth read from the preamble.
+		preamble_pixels (int): Number of pixels reserved for the preamble.
+
+	Returns:
+		str: The 64-character hex hash string extracted from the image header.
+	"""
+	raw_bits = [_read_main_bit(container, k, channels, depth, preamble_pixels)
+	            for k in range(512)]
+	raw_str = _bits_to_str(raw_bits)
+	return "".join([chr(int(raw_str[j:j+8], 2)) for j in range(0, len(raw_str), 8)])
+
+
+
+def extract_files(container, channels, depth, preamble_pixels, max_name_len):
+	"""Read the file count, sizes, filenames, and raw file data from the embedded header.
+
+	Populates container.files and container.filenames.
+
+	Args:
+		container: A Container instance after a successful extract_hash call.
+		channels (int): Number of channels in the image.
+		depth (int):    Embedding depth read from the preamble.
+		preamble_pixels (int): Number of pixels reserved for the preamble.
+		max_name_len (int): Filename field length in bytes (0 = no filename stored).
+	"""
+	container.files = []
+	container.filenames = []
+
+	# Read num_files (bits 512-543)
+	bits = [_read_main_bit(container, k, channels, depth, preamble_pixels)
+	        for k in range(512, 544)]
+	no_files = int(_bits_to_str(bits), 2)
+
+	offset = 544
+	file_sizes = []
+	file_names = []
+
+	for i in range(no_files):
+		# Read file size (32 bits)
+		size_bits = [_read_main_bit(container, k, channels, depth, preamble_pixels)
+		             for k in range(offset, offset + 32)]
+		file_size = int(_bits_to_str(size_bits), 2)
+		file_sizes.append(file_size)
+		offset += 32
+
+		# Read filename field if present
+		if max_name_len > 0:
+			name_bits = [_read_main_bit(container, k, channels, depth, preamble_pixels)
+			             for k in range(offset, offset + max_name_len * 8)]
+			name_bytes = bytes([int(_bits_to_str(name_bits[j:j+8]), 2)
+			                    for j in range(0, len(name_bits), 8)])
+			null = name_bytes.find(b'\x00')
+			name_bytes = name_bytes[:null] if null != -1 else name_bytes
+			try:
+				filename = Path(name_bytes.decode('utf-8')).name
+				if not filename:
+					filename = f"extracted_file_{i}"
+			except (UnicodeDecodeError, ValueError):
+				filename = f"extracted_file_{i}"
+			file_names.append(filename)
+			offset += max_name_len * 8
+		else:
+			file_names.append(f"extracted_file_{i}")
+
+	# Read file data
+	for i in range(no_files):
+		file_bits = [_read_main_bit(container, k, channels, depth, preamble_pixels)
+		             for k in range(offset, offset + file_sizes[i] * 8)]
+		file_bytes = bytes([int(_bits_to_str(file_bits[j:j+8]), 2)
+		                    for j in range(0, len(file_bits), 8)])
+		container.files.append(bytearray(file_bytes))
+		container.filenames.append(file_names[i])
+		offset += file_sizes[i] * 8