lcg-png-confusion

基于 2×2 线性同余矩阵的 PNG 像素坐标置换（只打乱像素位置，RGBA 无损）。支持 Node.js（≥18） 与现代浏览器，入口根据环境选用 pngjs 或 Canvas / OffscreenCanvas。

提供两种用法：

| 方式 | API | 说明 | |------|-----|------| | 自动 | encryptImageAuto / decryptImageAuto | 不传矩阵；由解码后的 宽高 与包内 DERIVE_OPTIONS_VERSION 确定性推导参数（非密钥）。 | | 手动 | encryptImage / decryptImage + Options | 自行指定矩阵 a,b,c,d 与可选 rounds，解密须与加密完全一致。 |

安装

npm install lcg-png-confusion

构建后从入口导入（ESM）：

import {
  encryptImageAuto,
  decryptImageAuto,
  deriveOptionsFromDimensions,
  DERIVE_OPTIONS_VERSION,
  encryptPixelsAuto,
  decryptPixelsAuto,
  encryptImage,
  decryptImage,
  encryptPixels,
  decryptPixels,
  assertPngInput,
} from "lcg-png-confusion";

自动模式（仅 PNG 字节）

const pngBytes: Uint8Array = ...;

const scrambled = await encryptImageAuto(pngBytes);
const restored = await decryptImageAuto(scrambled);

• 参数由 SHA-256(width, height, DERIVE_OPTIONS_VERSION) 种子 + 有界搜索得到；任何人用相同版本、相同宽高可复现同一组 Options。
• 加密与解密时的解码宽高必须一致。平台若改分辨率或裁切，自动解密会对不上。
• 极小图（像素数 < 4）使用单位矩阵、rounds: 1。
• 调试：await deriveOptionsFromDimensions(width, height)（依赖 Web Crypto crypto.subtle）。

像素级（自动）

已有 ImageData 或原始 RGBA 时：

await encryptPixelsAuto(rgba, width, height);
await decryptPixelsAuto(rgba, width, height);

手动模式（显式矩阵）

const pngBytes: Uint8Array = ...;

const opts = { a: 1, b: 2, c: 3, d: 5, rounds: 1 }; // rounds 可省略，默认 1

const scrambled = await encryptImage(pngBytes, opts);
const restored = await decryptImage(scrambled, opts);

Options

| 字段 | 说明 | |------|------| | a, b, c, d | 整数矩阵 (\begin{pmatrix}a&b\c&d\end{pmatrix})；(x'=(ax+by)\bmod W)，(y'=(cx+dy)\bmod H) | | rounds | 可选，默认 1；多轮为同一映射重复应用 |

可逆条件

• 需 (\gcd(ad-bc, W)=1) 且 (\gcd(ad-bc, H)=1)。
• 正方形（(W=H)）时，上述 gcd 条件即保证为合法线性置换。
• 非正方形时 gcd 不足以排除碰撞；本库会再做 全网格置换检测，不通过则抛错。自动模式在搜索合法矩阵时也会满足同样约束。

像素级（手动）

encryptPixels(rgba, width, height, opts);
decryptPixels(rgba, width, height, opts);

其他导出说明

• 校验：assertPngInput(bytes) — 与入口相同 PNG 魔数检查。
• 矩阵/数学：assertPermutationMap、isPermutationMap、assertInvertibleModDims、determinant、gcd、modInverse、normalizeMod 等，便于自定义矩阵或测试。

限制与说明

• 仅 PNG；入口会校验签名。
• 手动/自动流程写回 PNG 时可能改变 压缩流（DEFLATE），但 解码后像素应与逻辑一致；比较文件字节不一定相同。
• 大图占用与像素数成比例的内存；浏览器可结合 Web Worker 自行拆分。
• 自动模式需要 Web Crypto（Node 18+ 全局 crypto.subtle 或浏览器 secure context）。

合规说明

使用本库时请遵守各平台规则与适用法律。像素重排仅为算法演示，不保证也不鼓励用于规避内容审核。

开发

npm install
npm run build
npm test

License

MIT