mememage 0.1.0__py3-none-any.whl

mememage/__init__.py

@@ -0,0 +1,37 @@
+"""Mememage — a bar in an image's pixels points to a JSON record.
+
+Stamp a 2-pixel bar into an image; the bar carries an **identifier** (a key to a
+JSON record stored separately) and a **content hash** (a SHA-256 over the record).
+The core API is three functions, all pure image operations:
+
+- ``encode(image, fields)`` — write the bar, build the record from your fields.
+- ``decode(image)``         — read the bar back: identifier + content hash.
+- ``verify(image, record)`` — does a record match the image, by hash?
+
+Resolving the record (a dict, a file, a DB, a URL) is the caller's — core does not
+fetch. Optional field encryption: ``encode(password=…, private=[…])``
+(AES-256-GCM), revealed with ``unlock``.
+
+``pip install mememage`` (Pillow included); add ``[encrypt]`` for field encryption.
+"""
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("mememage")
+except Exception:  # running from a source tree that isn't installed
+    __version__ = "0.1.0"
+
+from mememage.api import (
+    Bar, Record, Verification, decode, encode, is_encrypted, unlock, verify,
+)
+
+__all__ = [
+    "encode",
+    "decode",
+    "verify",
+    "unlock",
+    "is_encrypted",
+    "Record",
+    "Bar",
+    "Verification",
+]

mememage/__main__.py

@@ -0,0 +1,192 @@
+"""Mememage core CLI — `encode` / `decode` from a shell.
+
+    mememage encode photo.png --field title="Morning fog" -o photo.json  # write the record
+    mememage decode photo.jpg --record photo.json                        # VERIFIED / ALTERED
+
+Without -o, the record is written next to the image as <identifier>.json.
+`decode` exits 0 only on a match, so it drops straight into a CI gate.
+"""
+import argparse
+import sys
+
+
+def _resolve_password(env_name, prompt):
+    """A password WITHOUT putting it in argv (visible in `ps` / shell history).
+    From ``--password-env VAR`` if given, else an interactive getpass prompt on a
+    TTY, else an error (non-interactive needs the env var)."""
+    import getpass
+    import os
+    if env_name:
+        val = os.environ.get(env_name)
+        if not val:
+            print(f"Error: env var {env_name} is unset/empty", file=sys.stderr)
+            sys.exit(1)
+        return val
+    if sys.stdin.isatty():
+        return getpass.getpass(prompt)
+    print("Error: no password — pass --password-env VAR (non-interactive)",
+          file=sys.stderr)
+    sys.exit(1)
+
+
+def cmd_encode(args):
+    """Write a bar + build an open-hash record from arbitrary fields."""
+    import json as _json
+    import os
+    import mememage
+
+    fields = {}
+    if args.fields:
+        try:
+            src = sys.stdin.read() if args.fields == "-" else \
+                open(args.fields, encoding="utf-8").read()
+            loaded = _json.loads(src)
+        except Exception as e:
+            print(f"Error reading --fields: {e}", file=sys.stderr)
+            sys.exit(1)
+        if not isinstance(loaded, dict):
+            print("Error: --fields must be a JSON object", file=sys.stderr)
+            sys.exit(1)
+        fields.update(loaded)
+    for kv in (args.field or []):
+        if "=" not in kv:
+            print(f"Error: --field expects KEY=VALUE, got {kv!r}", file=sys.stderr)
+            sys.exit(1)
+        k, v = kv.split("=", 1)
+        fields[k] = v
+
+    # Field visibility — encrypt private fields behind a password.
+    password = None
+    private = None
+    if args.encrypt or args.private:
+        password = _resolve_password(args.password_env, "Encrypt password: ")
+        if args.private:
+            private = [k.strip() for k in args.private.split(",") if k.strip()]
+
+    try:
+        result = mememage.encode(args.image, fields, prefix=args.prefix,
+                                 identifier=args.identifier,
+                                 password=password, private=private)
+    except (ValueError, RuntimeError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Name the record by its IDENTIFIER (not the image), so a record is found
+    # by the code the bar carries. Plain .json for the core; .soul is the
+    # provenance chain's. Matches the main CLI.
+    out = args.out or os.path.join(
+        os.path.dirname(args.image), result.identifier + ".json")
+    result.save(out)
+    print(f"Encoded {args.image}")
+    print(f"  image:        {result.image_path}")
+    print(f"  identifier:   {result.identifier}")
+    print(f"  content hash: {result.content_hash}")
+    if result.record.get("encrypted_fields"):
+        print(f"  encrypted:    {len(private) if private else 'all'} field(s)")
+    print(f"  record:       {out}")
+
+
+def cmd_decode(args):
+    """Read the bar (identifier + content hash). With --record, also verify it."""
+    import json as _json
+    import mememage
+
+    bar = mememage.decode(args.image)
+    if bar is None:
+        print("No Mememage bar in the image.", file=sys.stderr)
+        sys.exit(1)
+
+    # Pure read.
+    if not args.record:
+        if args.json:
+            print(_json.dumps({"identifier": bar.identifier,
+                               "content_hash": bar.content_hash}))
+        else:
+            print(f"Bar:  {bar.identifier}")
+            print(f"Hash: {bar.content_hash}")
+        return
+
+    # --record: verify against a LOCAL record file (no network — resolving is yours).
+    try:
+        with open(args.record, encoding="utf-8") as f:
+            record = _json.load(f)
+    except Exception as e:
+        print(f"Error reading --record: {e}", file=sys.stderr)
+        sys.exit(2)
+    v = mememage.verify(args.image, record)
+
+    if args.json:
+        print(_json.dumps({"identifier": bar.identifier, "content_hash": bar.content_hash,
+                           "match": bool(v), "reason": v.reason}))
+        sys.exit(0 if v else 1)
+
+    print(f"Bar:  {bar.identifier}")
+    print(f"Hash: {bar.content_hash}")
+    if v:
+        print("VERIFIED — record matches the image")
+        if record.get("encrypted_fields"):
+            if args.unlock or args.password_env:
+                password = _resolve_password(args.password_env, "Unlock password: ")
+                try:
+                    view = mememage.unlock(record, password)
+                    print("UNLOCKED — private fields decrypted:")
+                    _core = ("identifier", "content_hash", "hash_version",
+                             "signature", "encrypted_fields")
+                    for k, val in sorted(view.items()):
+                        if not (k.startswith("_") or k in _core):
+                            print(f"  {k}: {val}")
+                except Exception:
+                    print("(wrong password — could not decrypt)")
+            else:
+                print("ENCRYPTED — private fields (pass --unlock / --password-env to reveal)")
+    else:
+        print(f"ALTERED — {v.reason}")
+    sys.exit(0 if v else 1)
+
+
+def main():
+    p = argparse.ArgumentParser(prog="mememage",
+                                description="Encode an identifier into an image's pixels; "
+                                            "verify a JSON record against any copy.")
+    sub = p.add_subparsers(dest="command")
+
+    pe = sub.add_parser("encode", help="Encode a bar + build a record from your fields")
+    pe.add_argument("image", help="PNG image to encode (modified in place)")
+    pe.add_argument("--field", action="append", metavar="KEY=VALUE",
+                    help="A record field (repeatable). String values; use --fields for typed/nested.")
+    pe.add_argument("--fields", metavar="JSON_FILE",
+                    help="Read record fields from a JSON object file ('-' for stdin)")
+    pe.add_argument("--prefix", default="mememage",
+                    help="Identifier prefix (default: mememage)")
+    pe.add_argument("--identifier", help="Override the content-addressed identifier")
+    pe.add_argument("--encrypt", action="store_true",
+                    help="Encrypt ALL fields behind a password (private record)")
+    pe.add_argument("--private", metavar="F1,F2",
+                    help="Encrypt only these comma-separated fields (rest public)")
+    pe.add_argument("--password-env", metavar="VAR",
+                    help="Read the encrypt password from this env var (else prompt)")
+    pe.add_argument("-o", "--out",
+                    help="Record output path (default: <identifier>.json next to the image)")
+
+    pd = sub.add_parser("decode", help="Read the bar (identifier + content hash); with --record, verify")
+    pd.add_argument("image", help="Image to decode (PNG, JPEG, screenshot)")
+    pd.add_argument("--record", dest="record", metavar="FILE",
+                    help="A local record file (JSON) to verify the image against")
+    pd.add_argument("--unlock", action="store_true",
+                    help="With --record: decrypt the record's private fields (prompts for password)")
+    pd.add_argument("--password-env", metavar="VAR",
+                    help="Read the unlock password from this env var (else prompt)")
+    pd.add_argument("--json", action="store_true", help="Machine-readable JSON output")
+
+    args = p.parse_args()
+    if args.command == "encode":
+        cmd_encode(args)
+    elif args.command == "decode":
+        cmd_decode(args)
+    else:
+        p.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

mememage/api.py

@@ -0,0 +1,347 @@
+"""encode / decode / verify — the Mememage core API.
+
+The whole of Mememage core: write a bar into an image, get back a record whose
+fields you chose, and verify the data against the image by math alone. Just the
+bar, the record, and the hash — no networking, no record schema, no field
+semantics; anything more belongs to the application built on top. This is the
+small surface a tool can ``pip install`` and use::
+
+    import mememage
+    result = mememage.encode("shot.png", {"title": "a cat"})  # write the bar + record
+    result.save("shot.json")                  # store the record separately
+    ...
+    bar = mememage.decode("shot.jpg")         # read it back: identifier + content hash
+    if mememage.verify("shot.jpg", result.record):   # the record matches the image
+        ...
+
+The bar carries exactly two things: the IDENTIFIER (a key to a record stored
+separately — core does not fetch it) and the CONTENT HASH (a SHA-256 over the
+record). ``decode`` reads them back out; ``verify`` re-hashes a record and checks
+it against the hash in the pixels. The ``open`` hash makes every field of the
+record tamper-evident. Core stops at integrity (hash + optional field encryption);
+identity and authorship (signing) are out of scope.
+
+Pillow is required (the bar codec, shipped in the base install); ``cryptography``
+only if you encrypt fields.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections import namedtuple
+from dataclasses import dataclass
+
+from mememage import bar, hashing
+
+OPEN = hashing.OPEN_HASH_VERSION  # "open"
+
+# Keys encode computes / reserves — passing them in `fields` is a mistake, not a
+# silent override. `signature` is reserved (not just computed): the open hash
+# leaves it OUT (the structurally-circular slot), so a detached signature can be
+# attached later by an external tool without re-hashing — a user field
+# named `signature` would therefore go unprotected, so it's refused.
+_RESERVED = {"identifier", "content_hash", "hash_version", "signature",
+             "encrypted_fields"}
+
+# Identifier prefix rule: starts with a letter, ends alphanumeric, 3-10 chars,
+# URL/path-safe; capped at 10 so the bar still fits a 512px image.
+_PREFIX_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{1,8}[A-Za-z0-9]$")
+
+
+Bar = namedtuple("Bar", ["identifier", "content_hash"])
+
+
+@dataclass
+class Record:
+    """What :func:`encode` returns: the ``record`` (your fields + identifier +
+    content hash), the now-barred ``image`` (a PIL Image, always in memory), and
+    ``image_path`` (where it was written, or None for an in-memory-only encode).
+    Store the record wherever you like; a verifier finds it by identifier and
+    trusts it by hash."""
+    record: dict
+    image_path: "str | None" = None
+    image: "object | None" = None        # the barred PIL Image (in-memory output)
+
+    @property
+    def identifier(self) -> str:
+        return self.record["identifier"]
+
+    @property
+    def content_hash(self) -> str:
+        return self.record["content_hash"]
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.record, indent=indent, ensure_ascii=False)
+
+    def save(self, path: str) -> str:
+        """Write the record to ``path`` as JSON and return the path. Put it on
+        your own server, a CDN, IPFS, a file — the verifier is source-agnostic
+        and trusts it by hash alone."""
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(self.to_json())
+        return path
+
+
+@dataclass
+class Verification:
+    """What :func:`verify` returns. Truthy iff the record matches the image — the
+    re-hashed record equals the content hash baked in the pixels. ``reason``
+    explains a failure (empty on success). (Core verifies integrity only;
+    authorship/signatures are out of scope.) For the bar's identifier or hash,
+    call :func:`decode`."""
+    match: bool
+    reason: str = ""
+
+    def __bool__(self) -> bool:
+        return self.match
+
+
+def _validate_prefix(prefix: str) -> None:
+    if not isinstance(prefix, str) or not _PREFIX_RE.match(prefix):
+        raise ValueError(
+            f"invalid prefix {prefix!r}: 3-10 chars, [A-Za-z][A-Za-z0-9_-]*"
+            "[A-Za-z0-9] — URL/path/filename-safe (the bar must fit a 512px image)")
+
+
+def _canonical(obj) -> str:
+    """The canonical JSON the hash + identifier derive from — sorted keys,
+    normalized floats (1.0 → 1, matching JS), no whitespace."""
+    return json.dumps(hashing._normalize_for_hash(obj), sort_keys=True,
+                      separators=(",", ":"), ensure_ascii=True)
+
+
+def _swap_to_png(path: str) -> str:
+    """``/a/photo.jpg`` -> ``/a/photo.png`` — the lossless output for a non-PNG input."""
+    import os
+    return os.path.splitext(path)[0] + ".png"
+
+
+def _content_identifier(fields: dict, prefix: str) -> str:
+    """Content-address the record: ``<prefix>-<16 hex of canonical(fields)>``.
+    Same fields → same identifier (natural dedup); include a unique field
+    (timestamp, id) for a fresh one. The data determines its own name."""
+    digest = hashlib.sha256(_canonical(fields).encode("utf-8")).hexdigest()[:16]
+    return f"{prefix}-{digest}"
+
+
+def encode(image, fields=None, *, prefix="mememage", identifier=None,
+           password=None, private=None, out=None) -> Record:
+    """Write a Mememage bar into an image and return its :class:`Record`.
+
+    Adds ``identifier``, ``content_hash`` and ``hash_version="open"`` to your
+    fields, hashes everything (the ``open`` model — every field tamper-evident),
+    and embeds ``<identifier>\\0<content_hash>`` into the bottom two pixel rows.
+
+    Reads **any image** — a path, raw ``bytes``, a file-like object, a PIL Image,
+    or a numpy array (HEIC paths need the ``[heic]`` extra). The barred image is
+    always returned in memory as ``Record.image`` (a PIL Image). It is also
+    written to disk as a **lossless PNG** when there's a destination — the bar is
+    exact pixel data, so a lossy save would scramble it:
+
+    - a **path** input with no ``out`` → in place if PNG, else a ``.png`` sibling.
+    - ``out=<path.png>`` → written there. ``out=<file-like>`` (e.g. ``BytesIO``) →
+      written to the stream. ``out`` must be PNG.
+    - an **in-memory** input (PIL/bytes/ndarray) with no ``out`` → no disk; the
+      barred image is ``Record.image`` only.
+
+    Field visibility (``password``): your own encryption. With a password, the
+    private fields leave the cleartext record and become an ``encrypted_fields``
+    envelope (AES-256-GCM via PBKDF2). The content hash then covers the
+    CIPHERTEXT — so the record still verifies *without* the password (the proof
+    is over the encrypted shell), and tampering with the ciphertext breaks it.
+    Reveal the fields with :func:`unlock` (or in the browser decoder by typing the
+    password). The password is not stored; only the ciphertext is kept.
+
+    Args:
+        image: the source image — a path, bytes, a file-like, a PIL Image, or a
+            numpy array. Never mutated (encode works on a copy).
+        fields: your data as a JSON-serializable dict (None → identifier + hash
+            only). Reserved keys (identifier/content_hash/hash_version/
+            signature/encrypted_fields) can't be passed.
+        prefix: identifier namespace, 3-10 chars, IA-safe. Default ``mememage``.
+        identifier: override the auto content-addressed identifier with your own
+            ``<prefix>-...`` string.
+        password: encrypt private fields under this passphrase. Needs the
+            [encrypt] extra (cryptography). None → fully public record.
+        private: which field names to encrypt (list). With a password, ``None``
+            encrypts ALL your fields; a list encrypts just those, leaving the
+            rest public. Without a password it's an error.
+        out: a destination for the barred PNG — a ``.png`` path or a file-like
+            object. None → see the path/in-memory rules above.
+
+    Returns: :class:`Record` (``record`` + ``image`` (the barred PIL Image) +
+        ``image_path`` (the PNG written, or None)). On an encrypted record the
+        ``record`` holds the public fields + ``encrypted_fields``; the private
+        fields live only in the envelope.
+
+    Raises: ``ValueError`` if ``out`` isn't a ``.png``, on a reserved/`_`-prefixed
+        key, a bad prefix, ``private`` without ``password``, or an unknown
+        ``private`` name; ``RuntimeError`` if ``password`` is set but cryptography
+        is unavailable.
+    """
+    fields = dict(fields or {})
+    clash = _RESERVED & set(fields)
+    if clash:
+        raise ValueError(f"encode computes these — don't pass them: {sorted(clash)}")
+    underscored = sorted(k for k in fields if isinstance(k, str) and k.startswith("_"))
+    if underscored:
+        raise ValueError(
+            f"`_`-prefixed keys are reserved for decoder internals and are NOT "
+            f"hashed (they'd be unprotected): {underscored}")
+
+    record = dict(fields)
+    record["hash_version"] = OPEN
+
+    # Identity. Content-addressed from YOUR fields (stable whether or not you
+    # sign), unless you supplied one. The bar carries a CANONICAL
+    # ``<prefix>-<16 hex>`` identifier, so an override must take that shape.
+    ident = identifier
+    if ident is None:
+        _validate_prefix(prefix)
+        ident = _content_identifier(fields, prefix)
+    else:
+        pre, sep, idhex = ident.rpartition("-")
+        if not (sep and len(idhex) == 16
+                and all(c in "0123456789abcdef" for c in idhex)):
+            raise ValueError(
+                f"identifier must be canonical <prefix>-<16 lower-hex>, got {ident!r}")
+        _validate_prefix(pre)   # a supplied identifier's prefix obeys the same
+                                # contract as the prefix= auto-path — one rule.
+    record["identifier"] = ident
+
+    # Field visibility — encrypt the private fields behind a password BEFORE the
+    # hash, so the proof covers the ciphertext (tamper-evident shell; verifies
+    # without the password). The encrypted_fields envelope is AES-256-GCM and
+    # decryptable in any browser via SubtleCrypto.
+    if password is not None:
+        from mememage import crypto
+        if not crypto.is_encryption_available():
+            raise RuntimeError("field encryption needs the cryptography library "
+                               "(`pip install mememage[encrypt]`).")
+        if private is not None:
+            unknown = [k for k in private if k not in fields]
+            if unknown:
+                raise ValueError(f"private names fields you didn't pass: {sorted(unknown)}")
+        priv_keys = list(fields) if private is None else [k for k in private if k in fields]
+        priv = {}
+        for k in priv_keys:
+            priv[k] = record.pop(k)          # leaves the cleartext shell
+        if priv:
+            record["encrypted_fields"] = crypto.encrypt_field(
+                json.dumps(priv, sort_keys=True, separators=(",", ":")), password)
+    elif private:
+        raise ValueError("private=… needs a password=…")
+
+    # Proof. The content hash covers identity + the public shell + the ciphertext.
+    content_hash = hashing.compute_content_hash(record)
+    record["content_hash"] = content_hash
+
+    # Bar the pixels in memory (any input form -> a new barred RGB PIL Image).
+    barred = bar.embed_into(image, ident, content_hash)
+
+    # Write a lossless PNG, or keep it in memory. The bar is exact pixel data, so
+    # any written file must be PNG (a lossy save would scramble it).
+    import os
+    written = None
+    if out is not None:
+        if isinstance(out, (str, os.PathLike)):
+            if not str(out).lower().endswith(".png"):
+                raise ValueError("encode writes a lossless PNG (the bar can't survive "
+                                 f"lossy formats); out must end in .png, got {out}")
+            barred.save(out, "PNG")
+            written = str(out)
+        else:                                   # file-like (e.g. BytesIO)
+            barred.save(out, "PNG")
+    elif isinstance(image, (str, os.PathLike)):
+        # Path input, no out: write in place (PNG) or to a `.png` sibling.
+        src = str(image)
+        written = src if src.lower().endswith(".png") else _swap_to_png(src)
+        barred.save(written, "PNG")
+    # else: in-memory input, no out -> Record.image only (no disk).
+
+    return Record(record=record, image_path=written, image=barred)
+
+
+def decode(image, all_bars=False) -> "Bar | None | list[Bar]":
+    """Read the bar's payload out of an image. The inverse of :func:`encode`.
+
+    By default returns the FIRST (bottom-most) bar as ``Bar(identifier,
+    content_hash)``, or None — the common case: one image, one record.
+
+    With ``all_bars=True`` returns a LIST of *every* bar in the image (empty if
+    none) — for images stamped with more than one. Each bar is located wherever
+    it sits: the bottom (where :func:`encode` writes it), a different height,
+    horizontally offset, or pasted in from another image. CRC + Reed-Solomon
+    reject false matches, so bar-ish content never yields a spurious entry.
+
+    ``image`` is anything in memory or on disk — a path, raw ``bytes``, a
+    file-like object, a PIL ``Image``, or a numpy array. No network, no disk
+    round-trip: just the values stamped in the pixels.
+
+    The identifier points to a record you store separately; resolving it is yours
+    (a dict, a file, a DB, a URL — core doesn't fetch). The content hash lets
+    :func:`verify` confirm that record against the image."""
+    if all_bars:
+        return [Bar(identifier=i, content_hash=h) for (i, h) in bar.extract_bars(image)]
+    result = bar.extract_bar(image)
+    if not result:
+        return None
+    identifier, content_hash = result
+    return Bar(identifier=identifier, content_hash=content_hash)
+
+
+def is_encrypted(record) -> bool:
+    """True if the record carries an ``encrypted_fields`` envelope (private
+    fields behind a password)."""
+    rec = record.record if isinstance(record, Record) else (record or {})
+    return bool(rec.get("encrypted_fields"))
+
+
+def unlock(record, password) -> dict:
+    """Decrypt an encrypted record's private fields and return the full readable
+    view (public fields + the decrypted private fields; ``encrypted_fields``
+    dropped).
+
+    The ENCRYPTED record is what you :func:`verify` — its hash is over the
+    ciphertext. This is the *readable* view for display; don't re-hash it. A
+    record with no ``encrypted_fields`` is returned unchanged. Raises ``ValueError``
+    on the wrong password.
+    """
+    rec = record.record if isinstance(record, Record) else dict(record)
+    env = rec.get("encrypted_fields")
+    if not env:
+        return dict(rec)
+    from mememage import crypto
+    private = json.loads(crypto.decrypt_field(env, password))
+    view = {k: v for k, v in rec.items() if k != "encrypted_fields"}
+    view.update(private)
+    return view
+
+
+def verify(image, record) -> Verification:
+    """Verify a record against an image. Returns a :class:`Verification` (truthy iff
+    the data matches — the re-hashed record equals the content hash in the bar).
+
+    Reads the bar, recomputes the content hash over the record, and compares. A
+    match means the data is intact and belongs to this image. (Core verifies
+    integrity only; authorship/signatures are out of scope.)
+
+    Args:
+        image: the barred image — a path, bytes, a file-like, a PIL Image, or a
+            numpy array.
+        record: the record (a dict) or a :class:`Record`.
+    """
+    rec = record.record if isinstance(record, Record) else record
+
+    bar_data = decode(image)
+    if bar_data is None:
+        return Verification(False, "no Mememage bar in the image")
+
+    recomputed = hashing.compute_content_hash(rec)
+    if recomputed != bar_data.content_hash:
+        return Verification(False, f"hash mismatch: image bar says {bar_data.content_hash}, "
+                              f"data recomputes to {recomputed}")
+    return Verification(True)
+
+