Pixseal 0.2.1.post2__cp313-cp313-win_amd64.whl

Pixseal/__init__.py

@@ -0,0 +1,26 @@
+from .simpleImage import ImageInput, SimpleImage
+from .imageSigner import (
+    BinaryProvider,
+    addHiddenBit,
+    signImage,
+)
+from .imageValidator import (
+    binaryToString,
+    buildValidationReport,
+    deduplicate,
+    readHiddenBit,
+    validateImage,
+)
+
+__all__ = [
+    "SimpleImage",
+    "ImageInput",
+    "BinaryProvider",
+    "addHiddenBit",
+    "signImage",
+    "binaryToString",
+    "buildValidationReport",
+    "deduplicate",
+    "readHiddenBit",
+    "validateImage",
+]

Pixseal/imageSigner.py

@@ -0,0 +1,191 @@
+import base64
+from pathlib import Path
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+
+try:
+    from line_profiler import profile  # type: ignore
+except ImportError:  # pragma: no cover
+    def profile(func):
+        return func
+
+from .simpleImage import ImageInput, SimpleImage
+
+
+class BinaryProvider:
+
+    # Constructor
+    def __init__(
+        self,
+        hiddenString,
+        startString="START-VALIDATION\n",
+        endString="\nEND-VALIDATION",
+    ):
+        self.hiddenBits = self._stringToBits(hiddenString)
+        self.startBits = self._stringToBits(startString)
+        self.endBits = self._stringToBits(endString)
+
+    # Convert string to contiguous binary digits
+    def _stringToBits(self, string):
+        bits = []
+        for char in string:
+            binary = format(ord(char), "08b")
+            bits.extend(int(bit) for bit in binary)
+        return bits
+
+    def _expandPayload(self, count: int):
+        if count <= 0:
+            return []
+        payloadLen = len(self.hiddenBits)
+        if payloadLen == 0:
+            raise ValueError("Hidden payload is empty")
+        repeats, remainder = divmod(count, payloadLen)
+        return (self.hiddenBits * repeats) + self.hiddenBits[:remainder]
+
+    def buildBitArray(self, pixelCount: int):
+        startLen = len(self.startBits)
+        endLen = len(self.endBits)
+        if pixelCount < startLen + endLen:
+            raise ValueError("Image is too small to fit start/end sentinels")
+
+        bits = [0] * pixelCount
+
+        # 1. Place START-VALIDATION bits first
+        bits[:startLen] = self.startBits
+
+        # 2. Fill the remaining slots by repeating the payload bits
+        payloadSlots = pixelCount - startLen
+        payloadBits = self._expandPayload(payloadSlots)
+        bits[startLen:] = payloadBits[:payloadSlots]
+
+        # 3. Overwrite the tail with END-VALIDATION bits
+        tailStart = pixelCount - endLen
+        bits[tailStart:] = self.endBits
+
+        return bits
+
+
+@profile
+def addHiddenBit(imageInput: ImageInput, hiddenBinary: BinaryProvider):
+    img = SimpleImage.open(imageInput)
+    width, height = img.size
+    pixels = img._pixels  # direct buffer access for performance
+    total = width * height
+    payloadBits = hiddenBinary.buildBitArray(total)
+
+    # Iterate over every pixel and inject one bit
+    for idx in range(total):
+        base = idx * 3
+        # Read the pixel
+        r = pixels[base]
+        g = pixels[base + 1]
+        b = pixels[base + 2]
+
+        # Calculate the distance from 127
+        diffR = r - 127
+        if diffR < 0:
+            diffR = -diffR
+        diffG = g - 127
+        if diffG < 0:
+            diffG = -diffG
+        diffB = b - 127
+        if diffB < 0:
+            diffB = -diffB
+
+        # Pick the component farthest from 127
+        maxDiff = diffR
+        if diffG > maxDiff:
+            maxDiff = diffG
+        if diffB > maxDiff:
+            maxDiff = diffB
+
+        # Actual value of that channel
+        if maxDiff == diffR:
+            targetColorValue = r
+        elif maxDiff == diffG:
+            targetColorValue = g
+        else:
+            targetColorValue = b
+
+        # Channels >=127 are decremented, <127 incremented
+        addDirection = 1 if targetColorValue < 127 else -1
+
+        # Pull next bit from provider
+        bit = payloadBits[idx]
+
+        # Force the selected channel parity to match the bit
+        if maxDiff == diffR:
+            if r % 2 != bit:
+                r += addDirection
+        if maxDiff == diffG:
+            if g % 2 != bit:
+                g += addDirection
+        if maxDiff == diffB:
+            if b % 2 != bit:
+                b += addDirection
+
+        # Write the updated pixel
+        pixels[base] = r
+        pixels[base + 1] = g
+        pixels[base + 2] = b
+
+    # Return the modified image
+    return img
+
+
+def stringCryptor(plaintext: str, public_key) -> str:
+
+    ciphertext = public_key.encrypt(
+        plaintext.encode("utf-8"),
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA256()),
+            algorithm=hashes.SHA256(),
+            label=None,
+        ),
+    )
+
+    return base64.b64encode(ciphertext).decode("ascii")
+
+
+# main
+# Image input (path or bytes) + payload string => returns image with embedded payload
+def signImage(imageInput: ImageInput, hiddenString, publicKeyPath=None):
+    """
+    Embed a payload into an image using the parity-based steganography scheme.
+
+    Args:
+        imageInput: File path, bytes, or file-like object accepted by SimpleImage.
+        hiddenString: Text payload that should be written into the image.
+        publicKeyPath: Optional path to a PEM-encoded RSA public key used to
+            encrypt the payload and sentinel markers before embedding.
+
+    Returns:
+        SimpleImage instance whose pixels include the signed payload.
+
+    Raises:
+        FileNotFoundError: If a public key path is provided but the file is missing.
+        ValueError: If the file is not a valid PEM public key.
+    """
+
+    if publicKeyPath:  # When encryption key is supplied
+        key_path = Path(publicKeyPath)
+        if not key_path.is_file():
+            raise FileNotFoundError(f"Public key file not found: {publicKeyPath}")
+
+        pem_data = key_path.read_bytes()
+        if b"BEGIN PUBLIC KEY" not in pem_data:
+            raise ValueError("Provided file does not contain a valid public key")
+
+        public_key = serialization.load_pem_public_key(pem_data)
+
+        hiddenBinary = BinaryProvider(
+            hiddenString=stringCryptor(hiddenString, public_key) + "\n",
+            startString=stringCryptor("START-VALIDATION", public_key) + "\n",
+            endString="\n" + stringCryptor("END-VALIDATION", public_key),
+        )
+
+    else:  # Plain-text payload
+        hiddenBinary = BinaryProvider(hiddenString + "\n")
+
+    signedImage = addHiddenBit(imageInput, hiddenBinary)
+    return signedImage

Pixseal/imageValidator.py

@@ -0,0 +1,206 @@
+import base64
+from cryptography.hazmat.primitives import serialization, hashes
+from cryptography.hazmat.primitives.asymmetric import padding
+
+try:
+    from line_profiler import profile  # type: ignore
+except ImportError:  # pragma: no cover
+    def profile(func):
+        return func
+
+from .simpleImage import ImageInput, SimpleImage
+
+
+def binaryToString(binaryCode):
+    string = []
+    for i in range(0, len(binaryCode), 8):
+        byte = binaryCode[i : i + 8]
+        decimal = int(byte, 2)
+        character = chr(decimal)
+        string.append(character)
+    return "".join(string)
+
+
+@profile
+def readHiddenBit(imageInput: ImageInput):
+    img = SimpleImage.open(imageInput)
+    width, height = img.size
+    pixels = img._pixels  # direct buffer access for performance
+    total = width * height
+    bits = []
+    append_bit = bits.append
+
+    for idx in range(total):
+        base = idx * 3
+        r = pixels[base]
+        g = pixels[base + 1]
+        b = pixels[base + 2]
+
+        diffR = r - 127
+        if diffR < 0:
+            diffR = -diffR
+        diffG = g - 127
+        if diffG < 0:
+            diffG = -diffG
+        diffB = b - 127
+        if diffB < 0:
+            diffB = -diffB
+
+        maxDiff = diffR
+        if diffG > maxDiff:
+            maxDiff = diffG
+        if diffB > maxDiff:
+            maxDiff = diffB
+
+        append_bit("1" if maxDiff % 2 == 0 else "0")
+
+    return "".join(bits)
+
+
+def deduplicate(arr):
+    deduplicated = []
+    freq = {}
+    most_common = None
+    most_count = 0
+
+    for i, value in enumerate(arr):
+        freq[value] = freq.get(value, 0) + 1
+        if freq[value] > most_count:
+            most_count = freq[value]
+            most_common = value
+
+        if i == 0 or value != arr[i - 1]:
+            deduplicated.append(value)
+
+    return deduplicated, most_common
+
+
+def tailCheck(arr: list[str]):
+    if len(arr) != 4:
+        return None  # Not required
+
+    full_cipher = arr[1]  # complete ciphertext
+    truncated_cipher = arr[2]  # incomplete ciphertext
+
+    return full_cipher.startswith(truncated_cipher)
+
+
+def buildValidationReport(decrypted, tailCheck: bool, skipPlain: bool = False):
+    # Length after deduplication/decryption
+    arrayLength = len(decrypted)
+
+    # 1. Check that the deduplicated sequence length is valid
+    lengthCheck = arrayLength in (3, 4)
+
+    # 2. Validate start/end markers
+    startCheck = decrypted[0] == "START-VALIDATION" if decrypted else False
+    endCheck = decrypted[-1] == "END-VALIDATION" if decrypted else False
+
+    # 4. Determine whether payload was successfully decrypted
+    decryptedPayload = decrypted[1] if len(decrypted) > 1 else ""
+    isDecrypted = bool(decryptedPayload) and not decryptedPayload.endswith("==")
+
+    checkList = [lengthCheck, startCheck, endCheck, isDecrypted]
+    # 5. Parse tailCheck result
+    if tailCheck is None:
+        tailCheckResult = "Not Required"
+    else:
+        tailCheckResult = tailCheck
+        checkList.append(tailCheckResult)
+
+    # Overall verdict requires every check to pass
+    verdict = all(checkList)
+
+    result = {
+        "arrayLength": arrayLength,
+        "lengthCheck": lengthCheck,
+        "startCheck": startCheck,
+        "endCheck": endCheck,
+        "isDecrypted": isDecrypted,
+        "tailCheckResult": tailCheckResult,
+        "verdict": verdict,
+    }
+
+    if skipPlain:
+        result["decryptSkipMessage"] = (
+            "Skip decrypt: payload was plain or corrupted text despite decrypt request."
+        )
+
+    return result
+
+
+def decrypt_array(deduplicated, privKeyPath):
+    # Load PEM private key
+    with open(privKeyPath, "rb") as key_file:
+        private_key = serialization.load_pem_private_key(
+            key_file.read(),
+            password=None,
+        )
+
+    decrypted = []
+    skippedPlainCount = 0
+    decryptError = False
+    for item in deduplicated:
+        if item.endswith("=="):
+            try:
+                cipher_bytes = base64.b64decode(item)
+                plain_bytes = private_key.decrypt(
+                    cipher_bytes,
+                    padding.OAEP(
+                        mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                        algorithm=hashes.SHA256(),
+                        label=None,
+                    ),
+                )
+                decrypted.append(plain_bytes.decode("utf-8"))
+            except Exception as exc:
+                print(exc)
+                decryptError = True
+                decrypted.append(item)
+        else:
+            skippedPlainCount += 1
+            decrypted.append(item)
+
+    expectedPlainCount = 0
+    if len(deduplicated) == 4:
+        expectedPlainCount = 1
+
+    skippedPlain = decryptError or skippedPlainCount != expectedPlainCount
+
+    return decrypted, skippedPlain
+
+
+# main
+def validateImage(imageInput: ImageInput, privKeyPath=None):
+    """
+    Extract the embedded payload from an image and optionally decrypt it.
+
+    Args:
+        imageInput: File path, bytes, or file-like object accepted by SimpleImage.
+        privKeyPath: Optional path to a PEM-encoded RSA private key used to
+            decrypt the extracted ciphertext.
+
+    Returns:
+        Dict with the most common extracted string, decrypted sequence, and
+        a validation report describing the sentinel checks and verdict.
+    """
+    resultBinary = readHiddenBit(imageInput)
+    resultString = binaryToString(resultBinary)
+    splited = resultString.split("\n")
+    deduplicated, most_common = deduplicate(splited)
+
+    if privKeyPath:
+        decrypted, skippedPlain = decrypt_array(deduplicated, privKeyPath)
+    else:
+        decrypted = deduplicated
+        skippedPlain = False
+
+    report = buildValidationReport(
+        decrypted=decrypted, tailCheck=tailCheck(deduplicated), skipPlain=skippedPlain
+    )
+
+    return {
+        "extractedString": decrypt_array({most_common}, privKeyPath)[0][0],
+        "decrypted": decrypted,
+        "validationReport": report,
+    }

Pixseal/simpleImage.py

@@ -0,0 +1,35 @@
+"""
+Loader that prefers the Cython implementation and falls back to pure Python.
+Use environment variable PIXSEAL_SIMPLEIMAGE_BACKEND to force a backend:
+  - "cython": require compiled extension
+  - "python": force pure Python implementation
+"""
+
+from os import getenv
+
+_backend = getenv("PIXSEAL_SIMPLEIMAGE_BACKEND", "auto").lower()
+_loaded_module = "Pixseal.simpleImage_py"
+
+if _backend == "python":
+    from . import simpleImage_py as _impl  # type: ignore
+elif _backend == "cython":
+    try:
+        from . import simpleImage_ext as _impl  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "Cython backend requested but Pixseal.simpleImage_ext is not available. "
+            "Build the extension or choose the python backend."
+        ) from exc
+else:
+    try:  # pragma: no cover
+        from . import simpleImage_ext as _impl  # type: ignore
+    except ImportError:  # pragma: no cover
+        from . import simpleImage_py as _impl  # type: ignore
+
+SimpleImage = _impl.SimpleImage  # type: ignore
+ImageInput = _impl.ImageInput  # type: ignore
+_loaded_module = _impl.__name__
+
+print(f"[SimpleImage] Loaded from: {_loaded_module}")
+
+__all__ = ["SimpleImage", "ImageInput"]

Pixseal/simpleImage_py.py

@@ -0,0 +1,319 @@
+import struct
+import zlib
+from io import BytesIO
+from pathlib import Path
+from typing import List, Sequence, Tuple, Union
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def _paethPredictor(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa = abs(p - a)
+    pb = abs(p - b)
+    pc = abs(p - c)
+    if pa <= pb and pa <= pc:
+        return a
+    if pb <= pc:
+        return b
+    return c
+
+
+def _applyPngFilter(
+    filterType: int, rowData: bytearray, prevRow: Sequence[int], bytesPerPixel: int
+) -> bytearray:
+    recon = bytearray(len(rowData))
+    for i in range(len(rowData)):
+        left = recon[i - bytesPerPixel] if i >= bytesPerPixel else 0
+        up = prevRow[i] if prevRow else 0
+        upLeft = prevRow[i - bytesPerPixel] if (prevRow and i >= bytesPerPixel) else 0
+
+        if filterType == 0:
+            recon[i] = rowData[i]
+        elif filterType == 1:
+            recon[i] = (rowData[i] + left) & 0xFF
+        elif filterType == 2:
+            recon[i] = (rowData[i] + up) & 0xFF
+        elif filterType == 3:
+            recon[i] = (rowData[i] + ((left + up) >> 1)) & 0xFF
+        elif filterType == 4:
+            recon[i] = (rowData[i] + _paethPredictor(left, up, upLeft)) & 0xFF
+        else:
+            raise ValueError(f"Unsupported PNG filter: {filterType}")
+    return recon
+
+
+def _readChunk(stream) -> Tuple[bytes, bytes]:
+    lengthBytes = stream.read(4)
+    if len(lengthBytes) == 0:
+        return b"", b""
+    if len(lengthBytes) != 4:
+        raise ValueError("Unexpected EOF while reading chunk length")
+    length = struct.unpack(">I", lengthBytes)[0]
+    chunkType = stream.read(4)
+    if len(chunkType) != 4:
+        raise ValueError("Unexpected EOF while reading chunk type")
+    data = stream.read(length)
+    if len(data) != length:
+        raise ValueError("Unexpected EOF while reading chunk data")
+    crc = stream.read(4)
+    if len(crc) != 4:
+        raise ValueError("Unexpected EOF while reading chunk CRC")
+    expectedCrc = zlib.crc32(chunkType)
+    expectedCrc = zlib.crc32(data, expectedCrc) & 0xFFFFFFFF
+    actualCrc = struct.unpack(">I", crc)[0]
+    if actualCrc != expectedCrc:
+        raise ValueError("Corrupted PNG chunk detected")
+    return chunkType, data
+
+
+def _loadPng(stream) -> Tuple[int, int, bytearray]:
+    signature = stream.read(8)
+    if signature != PNG_SIGNATURE:
+        raise ValueError("Unsupported PNG signature")
+
+    width = height = None
+    bitDepth = colorType = None
+    compression = filterMethod = interlace = None
+    idatChunks: List[bytes] = []
+
+    while True:
+        chunkType, data = _readChunk(stream)
+        if chunkType == b"":
+            break
+        if chunkType == b"IHDR":
+            (
+                width,
+                height,
+                bitDepth,
+                colorType,
+                compression,
+                filterMethod,
+                interlace,
+            ) = struct.unpack(">IIBBBBB", data)
+        elif chunkType == b"IDAT":
+            idatChunks.append(data)
+        elif chunkType == b"IEND":
+            break
+
+    if None in (
+        width,
+        height,
+        bitDepth,
+        colorType,
+        compression,
+        filterMethod,
+        interlace,
+    ):
+        raise ValueError("Incomplete PNG header information")
+    if bitDepth != 8:
+        raise ValueError("Only 8-bit PNG images are supported")
+    if colorType not in (2, 6):
+        raise ValueError("Only RGB/RGBA PNG images are supported")
+    if compression != 0 or filterMethod != 0 or interlace != 0:
+        raise ValueError("Unsupported PNG configuration (compression/filter/interlace)")
+
+    rawImage = zlib.decompress(b"".join(idatChunks))
+    bytesPerPixel = 3 if colorType == 2 else 4
+    rowLength = width * bytesPerPixel
+    expected = height * (rowLength + 1)
+    if len(rawImage) != expected:
+        raise ValueError("Malformed PNG image data")
+
+    pixels = bytearray(width * height * 3)
+    prevRow = bytearray(rowLength)
+    offset = 0
+    for y in range(height):
+        filterType = rawImage[offset]
+        offset += 1
+        rowBytes = bytearray(rawImage[offset : offset + rowLength])
+        offset += rowLength
+        recon = _applyPngFilter(filterType, rowBytes, prevRow, bytesPerPixel)
+        for x in range(width):
+            srcIndex = x * bytesPerPixel
+            destIndex = (y * width + x) * 3
+            pixels[destIndex] = recon[srcIndex]
+            pixels[destIndex + 1] = recon[srcIndex + 1]
+            pixels[destIndex + 2] = recon[srcIndex + 2]
+        prevRow = recon
+    return width, height, pixels
+
+
+def _loadBmp(stream) -> Tuple[int, int, bytearray]:
+    header = stream.read(14)
+    if len(header) != 14 or header[:2] != b"BM":
+        raise ValueError("Unsupported BMP header")
+    fileSize, _, _, pixelOffset = struct.unpack("<IHHI", header[2:])
+    dibHeaderSizeBytes = stream.read(4)
+    if len(dibHeaderSizeBytes) != 4:
+        raise ValueError("Corrupted BMP DIB header")
+    dibHeaderSize = struct.unpack("<I", dibHeaderSizeBytes)[0]
+    if dibHeaderSize != 40:
+        raise ValueError("Only BITMAPINFOHEADER BMP files are supported")
+    dibData = stream.read(36)
+    (
+        width,
+        height,
+        planes,
+        bitCount,
+        compression,
+        imageSize,
+        xPpm,
+        yPpm,
+        clrUsed,
+        clrImportant,
+    ) = struct.unpack("<iiHHIIiiII", dibData)
+    if planes != 1 or bitCount != 24 or compression != 0:
+        raise ValueError("Only uncompressed 24-bit BMP files are supported")
+    absHeight = abs(height)
+    rowStride = ((width * 3 + 3) // 4) * 4
+    pixels = bytearray(width * absHeight * 3)
+    stream.seek(pixelOffset)
+    for row in range(absHeight):
+        rowData = stream.read(rowStride)
+        if len(rowData) != rowStride:
+            raise ValueError("Incomplete BMP pixel data")
+        targetRow = absHeight - 1 - row if height > 0 else row
+        baseIndex = targetRow * width * 3
+        for x in range(width):
+            pixelOffsetInRow = x * 3
+            b = rowData[pixelOffsetInRow]
+            g = rowData[pixelOffsetInRow + 1]
+            r = rowData[pixelOffsetInRow + 2]
+            dest = baseIndex + x * 3
+            pixels[dest] = r & 0xFF
+            pixels[dest + 1] = g & 0xFF
+            pixels[dest + 2] = b & 0xFF
+    return width, absHeight, pixels
+
+
+def _makeChunk(chunkType: bytes, data: bytes) -> bytes:
+    length = struct.pack(">I", len(data))
+    crcValue = zlib.crc32(chunkType)
+    crcValue = zlib.crc32(data, crcValue) & 0xFFFFFFFF
+    crc = struct.pack(">I", crcValue)
+    return length + chunkType + data + crc
+
+
+def _writePng(path: str, width: int, height: int, pixels: Sequence[int]) -> None:
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    rowStride = width * 3
+    raw = bytearray()
+    for y in range(height):
+        raw.append(0)
+        start = y * rowStride
+        raw.extend(pixels[start : start + rowStride])
+    compressed = zlib.compress(bytes(raw))
+    with open(path, "wb") as output:
+        output.write(PNG_SIGNATURE)
+        output.write(_makeChunk(b"IHDR", ihdr))
+        output.write(_makeChunk(b"IDAT", compressed))
+        output.write(_makeChunk(b"IEND", b""))
+
+
+def _writeBmp(path: str, width: int, height: int, pixels: Sequence[int]) -> None:
+    rowStride = ((width * 3 + 3) // 4) * 4
+    pixelArraySize = rowStride * height
+    fileSize = 14 + 40 + pixelArraySize
+    with open(path, "wb") as output:
+        output.write(b"BM")
+        output.write(struct.pack("<IHHI", fileSize, 0, 0, 54))
+        output.write(
+            struct.pack(
+                "<IIIHHIIIIII",
+                40,
+                width,
+                height,
+                1,
+                24,
+                0,
+                pixelArraySize,
+                2835,
+                2835,
+                0,
+                0,
+            )
+        )
+        rowPad = rowStride - width * 3
+        padBytes = b"\x00" * rowPad
+        for y in range(height - 1, -1, -1):
+            start = y * width * 3
+            for x in range(width):
+                idx = start + x * 3
+                r = pixels[idx]
+                g = pixels[idx + 1]
+                b = pixels[idx + 2]
+                output.write(bytes((b & 0xFF, g & 0xFF, r & 0xFF)))
+            if rowPad:
+                output.write(padBytes)
+
+
+ImageInput = Union[str, Path, bytes, bytearray]
+
+
+class SimpleImage:
+    __slots__ = ("width", "height", "_pixels")
+
+    def __init__(self, width: int, height: int, pixels: Sequence[int]):
+        self.width = width
+        self.height = height
+        expected = width * height * 3
+        if len(pixels) != expected:
+            raise ValueError("Pixel data length does not match image dimensions")
+        self._pixels = bytearray(pixels)
+
+    @property
+    def size(self) -> Tuple[int, int]:
+        return self.width, self.height
+
+    @staticmethod
+    def _streamToImage(stream) -> Tuple[int, int, bytearray]:
+        signature = stream.read(8)
+        stream.seek(0)
+        if signature.startswith(PNG_SIGNATURE):
+            return _loadPng(stream)
+        if signature[:2] == b"BM":
+            return _loadBmp(stream)
+        raise ValueError("Unsupported image format")
+
+    @classmethod
+    def open(cls, source: ImageInput) -> "SimpleImage":
+        if isinstance(source, (str, Path)):
+            with open(source, "rb") as stream:
+                width, height, pixels = cls._streamToImage(stream)
+        elif isinstance(source, (bytes, bytearray)):
+            stream = BytesIO(source)
+            width, height, pixels = cls._streamToImage(stream)
+        else:
+            raise TypeError("source must be a file path or raw bytes")
+        return cls(width, height, pixels)
+
+    def getPixel(self, coords: Tuple[int, int]) -> Tuple[int, int, int]:
+        x, y = coords
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            raise ValueError("Pixel coordinate out of bounds")
+        index = (y * self.width + x) * 3
+        return (
+            self._pixels[index],
+            self._pixels[index + 1],
+            self._pixels[index + 2],
+        )
+
+    def putPixel(self, coords: Tuple[int, int], value: Sequence[int]) -> None:
+        x, y = coords
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            raise ValueError("Pixel coordinate out of bounds")
+        index = (y * self.width + x) * 3
+        r, g, b = value
+        self._pixels[index] = int(r) & 0xFF
+        self._pixels[index + 1] = int(g) & 0xFF
+        self._pixels[index + 2] = int(b) & 0xFF
+
+    def copy(self) -> "SimpleImage":
+        return SimpleImage(self.width, self.height, self._pixels[:])
+
+    def save(self, path: str) -> None:
+        _writePng(path, self.width, self.height, self._pixels)
+
+    def saveBmp(self, path: str) -> None:
+        _writeBmp(path, self.width, self.height, self._pixels)

pixseal-0.2.1.post2.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: Pixseal
+Version: 0.2.1.post2
+Summary: Encrypted Image Watermark Injector / Validator
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0.0
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/Pixseal.png" width="200px"/>
+</p>
+
+# Pixseal
+### Prove what you published — and what you didn’t.
+Pixseal is a Python-based **image integrity and authenticity verification tool**
+designed to **detect whether an image has been modified since signing.**
+
+Pixseal embeds a **cryptographically verifiable integrity seal** into an image in an
+invisible manner. During verification, **any modification** — including editing,
+filtering, cropping, resizing, re-encoding — will cause
+verification to **immediately fail**.
+
+If **even a single pixel** is altered after signing, Pixseal will detect it.
+
+Pixseal is not a visual watermarking or branding tool.  
+The watermark exists solely as a **means to achieve strict, deterministic image
+tamper detection**.
+Pixseal prioritizes tamper sensitivity over robustness against intentional adversarial manipulation.
+
+- GitHub: https://github.com/kyj9447/Pixseal
+- Changelog: https://github.com/kyj9447/Pixseal/blob/main/CHANGELOG.md
+
+## Features
+- **Image Integrity Verification**
+  - Cryptographically proves that an image remains in its original, unmodified state
+  - Detects single-pixel changes with deterministic verification results
+
+- **Tamper Detection**
+  - Detects all forms of image modification, including:
+    - editing
+    - filters and color adjustments
+    - cropping and resizing
+    - re-encoding and recompression
+    - pixel-level changes
+
+- **Invisible Integrity Seal**
+  - Embeds verification data without any visible watermark
+  - Preserves the original visual appearance of the image
+
+- **RSA-Based Encryption (Optional)**
+  - Supports RSA public/private key encryption for embedded verification data
+  - Allows separation of signing and verification roles
+
+- **Verification & Extraction**
+  - Payloads may be partially or fully extractable even after modification
+  - Automatically fails verification when tampering is detected
+
+- **Fully Local & Offline**
+  - No external servers or network dependencies
+  - Pure Python implementation
+
+- **Lossless Format Support**
+  - Supports PNG and BMP (24-bit) images
+  - Lossy formats (e.g., JPEG, WebP) are intentionally excluded to preserve integrity guarantees
+
+## Installation
+
+```bash
+pip install Pixseal
+# or for local development
+pip install -e ./pip_package
+```
+
+Python 3.8+ is required. Wheels published to PyPI already include the compiled
+Cython extension, so `pip install Pixseal` automatically selects the right build
+for your operating system and CPU.
+
+### Building from a git clone
+
+If you cloned the repository (or downloaded the source), run the included build
+script to create a wheel/SDist tailored to your environment:
+
+```bash
+git clone https://github.com/kyj9447/Pixseal.git
+cd Pixseal
+python3 -m pip install -r requirements.txt
+./build.sh
+# Install the freshly built wheel (optional)
+python3 -m pip install pip_package/dist/Pixseal-*.whl
+```
+
+Even after running `python3 -m pip install -r requirements.txt` you still need a
+working C toolchain (`gcc`) and the Python development headers exposed via
+`python3-config`; these come from your OS packages, not pip.
+
+`build.sh` invokes Cython and `gcc` (via `python3-config`) before producing the
+wheel/sdist artifacts. Ensure `cython`, `build`, and a working C toolchain are
+installed. If you skip this step, Pixseal falls back to the pure Python
+implementation, which works but is significantly slower.
+
+## Usage
+
+### Sign an image
+
+```python
+from Pixseal import signImage
+
+result = signImage(
+    imageInput="assets/original.png",  # accepts a file path or raw PNG/BMP bytes
+    hiddenString="!Validation:kyj9447@mailmail.com",
+    publicKeyPath="assets/RSA/public_key.pem",  # omit for plain-text embedding
+)
+result.save("assets/signed_original.png")
+```
+
+- The payload is looped if it runs out before the image ends, so even small files carry the full sentinel/payload/end pattern.
+- When `publicKeyPath` is omitted, the payload remains plain text.
+
+### Validate and (optionally) decrypt
+
+```python
+from Pixseal import validateImage
+
+report = validateImage(
+    imageInput="assets/signed_original.png",  # accepts a file path or raw PNG/BMP bytes
+    privKeyPath="assets/RSA/private_key.pem",  # omit for plain-text payloads
+)
+
+print(report["extractedString1"])
+print(report["validationReport"])
+```
+
+`validateImage` returns:
+
+```python
+{
+    "extractedString1": "<payload or encrypted blob>",
+    "extractedString2": "<truncated payload or encrypted blob>",
+    "validationReport": {
+        "arrayLength": 4,
+        "lengthCheck": True,
+        "startCheck": True,
+        "endCheck": True,
+        "isDecrypted": True,
+        "tailCheckResult": True,
+        "verdict": True,
+        # decryptSkipMessage when a decrypt request was skipped
+    }
+}
+```
+
+### CLI demo script
+
+`python testRun.py` offers an interactive flow:
+
+1. Choose **1** to sign an image. It reads `assets/original.png`, asks for a payload (default `!Validation:kyj9447@mailmail.com`), optionally encrypts with `assets/RSA/public_key.pem`, and writes `assets/signed_<name>.png`.
+2. Choose **2** to validate. It reads `assets/signed_original.png`, optionally decrypts with `assets/RSA/private_key.pem`, and prints both the extracted string and verdict.
+3. Choose **3** to benchmark performance. It reads `assets/original.png`, encrypts it with `assets/RSA/public_key.pem`, and writes `assets/signed_original.png`, printing the elapsed signing time. Then it reads `assets/signed_original.png`, performs extraction/decryption/validation, and prints the elapsed validation time along with the total elapsed time.
+4. Choose **4** to test signing and validation with file-path input option.
+5. Choose **5** to test signing and validation with byte-stream input option.
+6. Choose **6** to run the optional line-profiler demo. It benchmarks `signImage` and `validateImage`, printing per-line timings when the script is executed through `kernprof`.
+
+Option **6** requires the optional dependency `line_profiler` and must be run via `kernprof -l testRun.py` so that `builtins.profile` is provided. Without `line_profiler` installed the script will continue to work, but the profiling option will display an informative message instead of running.
+### Key management
+
+Generate a test RSA pair (PKCS#8) with OpenSSL:
+
+```bash
+openssl genpkey -algorithm RSA -out assets/RSA/private_key.pem -pkeyopt rsa_keygen_bits:2048
+openssl rsa -pubout -in assets/RSA/private_key.pem -out assets/RSA/public_key.pem
+```
+
+Point `publicKeyPath` / `privKeyPath` to these files.
+
+## API reference
+
+| Function | Description |
+| --- | --- |
+| `signImage(imageInput, hiddenString, publicKeyPath=None)` | Loads a PNG/BMP from a filesystem path or raw bytes, injects `hiddenString` plus sentinels, encrypting each chunk when `publicKeyPath` is provided. Returns a `SimpleImage` that you can `save()` or `saveBmp()`. |
+| `validateImage(imageInput, privKeyPath=None)` | Reads the hidden bit stream from a path or raw bytes, splits by newlines, deduplicates, optionally decrypts each chunk (Base64 indicates ciphertext), and returns the payload plus a validation report. |
+
+
+## Examples
+
+| Original | Signed (`!Validation:kyj9447@mailmail.com`) |
+| --- | --- |
+| <img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/original.png" width="400px"/> | <img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/signed_original.png" width="400px"/> |
+
+Validation output excerpt:
+
+```
+[Validate] verdict: True
+[Validate] extracted string: !Validation:kyj9447@mailmail.com
+[Validate] decrypted with private key: RSA/private_key.pem
+
+Validation Report
+
+{'extractedString1': '!Validation:kyj9447@mailmail.com',
+ 'extractedString2': 'DMnWAzbd6NFycGAxcPkzzmGjL33WXovG...',
+ 'validationReport': {'arrayLength': 4,
+                      'endCheck': True,
+                      'isDecrypted': True,
+                      'lengthCheck': True,
+                      'startCheck': True,
+                      'tailCheckResult': True,
+                      'verdict': True}}
+```
+
+(When encrypted, each line appears as Base64 until decrypted with the RSA private key.)
+
+| Corrupted after signing |
+| --- |
+|<img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/currupted_signed_original.png" width="400px"/>
+
+Validation output excerpt:
+
+```
+...
+string argument should contain only ASCII characters
+string argument should contain only ASCII characters
+string argument should contain only ASCII characters
+[Validate] verdict: False
+[Validate] extracted string: !Validation:kyj9447@mailmail.com
+[Validate] decrypted with private key: RSA/private_key.pem
+
+Validation Report
+
+{'extractedString1': '!Validation:kyj9447@mailmail.com',
+ 'extractedString2': 'hh78IWEsRgfTWMw3Rg02hTnCdErjx0O4...',
+ 'validationReport': {'arrayLength': 400,
+                      'decryptSkipMessage': 'Skip decrypt: payload was plain '
+                                            'or corrupted text despite decrypt '
+                                            'request.',
+                      'endCheck': True,
+                      'isDecrypted': True,
+                      'lengthCheck': False,
+                      'startCheck': True,
+                      'tailCheckResult': 'Not Required',
+                      'verdict': False}}
+```
+## Related projects
+
+https://github.com/kyj9447/imageSignerCamera
+- Mobile camera that signs images on capture: 
+- Server-side validator that decrypts and verifies payloads.

pixseal-0.2.1.post2.dist-info/RECORD

@@ -0,0 +1,10 @@
+Pixseal/__init__.py,sha256=EaJiakSK0uB1edVY_RrgsjBiyjWj_i3Us2YHiu7Nfpk,514
+Pixseal/imageSigner.py,sha256=NKpjs5y2JMYvzc2enRkor7Ag8dwMsEectmx-cOwADyg,6170
+Pixseal/imageValidator.py,sha256=HaX8qKWSNYSnHbMfgElcdvGFQgaFQ0ffUbulEFh1HqQ,6155
+Pixseal/simpleImage.py,sha256=QhrbeIBCx2bs7Ehv1ss9fqX7JrjchjgCaGfljDGGQMg,1269
+Pixseal/simpleImage_ext.cp313-win_amd64.pyd,sha256=VC62UlslRtY8LGvxDCmWhCXcWdfE22vJj9v1WylS4WQ,207872
+Pixseal/simpleImage_py.py,sha256=egN7zQO5H7xTWmPSYi8JBiSJDz6SOvJE-RMcXSPH_jo,11168
+pixseal-0.2.1.post2.dist-info/METADATA,sha256=k0iELf5OW2e5EKAYgE61_nBKaJOCpL2XlCzDKQBStBk,9984
+pixseal-0.2.1.post2.dist-info/WHEEL,sha256=qV0EIPljj1XC_vuSatRWjn02nZIz3N1t8jsZz7HBr2U,101
+pixseal-0.2.1.post2.dist-info/top_level.txt,sha256=q35ICL7vJyo5hOpL4YbL5t_g4297gwUPIuLy82kgL3s,8
+pixseal-0.2.1.post2.dist-info/RECORD,,

pixseal-0.2.1.post2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64
+

pixseal-0.2.1.post2.dist-info/top_level.txt

@@ -0,0 +1 @@
+Pixseal