mememage 0.1.0__tar.gz

mememage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Catmemes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mememage-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: mememage
+Version: 0.1.0
+Summary: Encode an identifier into an image's pixels; verify a JSON record against any copy
+Author: Catmemes
+License: MIT
+Project-URL: Homepage, https://github.com/sememtac/mememage
+Keywords: steganography,image,watermark,content-hash,tamper-evident
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10.0
+Provides-Extra: encrypt
+Requires-Dist: cryptography>=41.0; extra == "encrypt"
+Provides-Extra: heic
+Requires-Dist: pillow-heif>=0.16; extra == "heic"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: Pillow>=10.0; extra == "dev"
+Requires-Dist: cryptography>=41.0; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
+Dynamic: license-file
+
+# Mememage
+
+Encode an identifier into an image's pixels; verify a JSON record against any copy.
+
+Mememage writes a 2-pixel-tall bar into the bottom rows of an image. The bar holds two values:
+
+- **identifier** — a short string that points to a JSON record, stored separately (a server, a CDN, IPFS, a file).
+- **content hash** — a SHA-256 over the record. `verify` recomputes it and compares against the bar.
+
+The bar survives JPEG, resaves, screenshots, and re-uploads, so the identifier reads back from any copy. `encode` reads any image Pillow can open and writes a lossless PNG; `decode` and `verify` work on any format the bar survives. Record fields are arbitrary — captions, credits, generation parameters, links.
+
+```bash
+pip install mememage                 # encode / decode / verify — Pillow included
+# pip install "mememage[encrypt]"    # adds AES-256 field encryption
+```
+
+## Quickstart
+
+Three functions, all pure image operations:
+
+```python
+import mememage
+
+# encode — write the bar into the image, build the record from your fields
+result = mememage.encode("photo.png", {"title": "Morning fog", "by": "catmemes"})
+result.identifier            # 'mememage-3dc5f03a747bb38e' (derived from the fields)
+result.save("photo.json")    # the record — store or serve it separately
+
+# decode — read the bar back out of the pixels (the inverse of encode)
+bar = mememage.decode("photo.jpg")      # any format the bar survived: PNG, JPEG, a screenshot
+bar.identifier, bar.content_hash
+
+# verify — does a record match an image? (recomputed hash == the bar's)
+mememage.verify("photo.jpg", result.record)        # True if the record is intact
+```
+
+You resolve the record from its identifier — look it up wherever you keep it, then verify:
+
+```python
+bar    = mememage.decode("photo.jpg")    # identifier + content hash from the pixels
+record = my_store[bar.identifier]        # your storage: a dict, a file, a DB, a URL
+mememage.verify("photo.jpg", record)     # True if the record matches the image
+```
+
+- **`encode` accepts any image** — a path, `bytes`, a PIL `Image`, or a numpy array (HEIC needs the `[heic]` extra) — and returns the barred image as `Record.image`. Given a destination — a path (in place, or a `.png` sibling for non-PNG), `out=<path.png>`, or `out=<stream>` (e.g. `BytesIO`) — it writes the file. Output is always PNG: the bar is lossless, and a lossy re-encode would corrupt it. An in-memory input with no destination never touches disk.
+- **`decode` / `verify` accept the same in-memory forms** — a path, `bytes`, a file-like, a PIL `Image`, or a numpy array. No disk round-trip.
+- **No network I/O** — `decode` returns the identifier; you resolve the record. Core is pure pixel + hash operations.
+
+## Encrypt private fields
+
+- Mark fields `private` to encrypt them (AES-256-GCM via PBKDF2) under a password.
+- The record still **verifies without the password** — the hash covers the ciphertext.
+- `unlock` returns the decrypted fields. The password is not stored; only the ciphertext is kept in the record.
+
+```python
+result = mememage.encode("photo.png", {"title": "Public", "gps": "45.5,-122.6"},
+                         password="hunter2", private=["gps"])
+mememage.verify("photo.png", result.record)              # matches — no password
+mememage.unlock(result, "hunter2")["gps"]                # '45.5,-122.6'
+```
+
+## Command line
+
+```bash
+mememage encode photo.png --field title="Morning fog" -o photo.json   # write the record
+mememage decode photo.jpg --record photo.json                         # VERIFIED (exit 0) / ALTERED (exit 1)
+mememage decode photo.jpg                                             # read the identifier only (no record)
+```
+
+Without `-o`, the record is written next to the image as `<identifier>.json`.
+`decode` exits 0 on a match.
+
+## License
+
+MIT.

mememage-0.1.0/README.md

@@ -0,0 +1,75 @@
+# Mememage
+
+Encode an identifier into an image's pixels; verify a JSON record against any copy.
+
+Mememage writes a 2-pixel-tall bar into the bottom rows of an image. The bar holds two values:
+
+- **identifier** — a short string that points to a JSON record, stored separately (a server, a CDN, IPFS, a file).
+- **content hash** — a SHA-256 over the record. `verify` recomputes it and compares against the bar.
+
+The bar survives JPEG, resaves, screenshots, and re-uploads, so the identifier reads back from any copy. `encode` reads any image Pillow can open and writes a lossless PNG; `decode` and `verify` work on any format the bar survives. Record fields are arbitrary — captions, credits, generation parameters, links.
+
+```bash
+pip install mememage                 # encode / decode / verify — Pillow included
+# pip install "mememage[encrypt]"    # adds AES-256 field encryption
+```
+
+## Quickstart
+
+Three functions, all pure image operations:
+
+```python
+import mememage
+
+# encode — write the bar into the image, build the record from your fields
+result = mememage.encode("photo.png", {"title": "Morning fog", "by": "catmemes"})
+result.identifier            # 'mememage-3dc5f03a747bb38e' (derived from the fields)
+result.save("photo.json")    # the record — store or serve it separately
+
+# decode — read the bar back out of the pixels (the inverse of encode)
+bar = mememage.decode("photo.jpg")      # any format the bar survived: PNG, JPEG, a screenshot
+bar.identifier, bar.content_hash
+
+# verify — does a record match an image? (recomputed hash == the bar's)
+mememage.verify("photo.jpg", result.record)        # True if the record is intact
+```
+
+You resolve the record from its identifier — look it up wherever you keep it, then verify:
+
+```python
+bar    = mememage.decode("photo.jpg")    # identifier + content hash from the pixels
+record = my_store[bar.identifier]        # your storage: a dict, a file, a DB, a URL
+mememage.verify("photo.jpg", record)     # True if the record matches the image
+```
+
+- **`encode` accepts any image** — a path, `bytes`, a PIL `Image`, or a numpy array (HEIC needs the `[heic]` extra) — and returns the barred image as `Record.image`. Given a destination — a path (in place, or a `.png` sibling for non-PNG), `out=<path.png>`, or `out=<stream>` (e.g. `BytesIO`) — it writes the file. Output is always PNG: the bar is lossless, and a lossy re-encode would corrupt it. An in-memory input with no destination never touches disk.
+- **`decode` / `verify` accept the same in-memory forms** — a path, `bytes`, a file-like, a PIL `Image`, or a numpy array. No disk round-trip.
+- **No network I/O** — `decode` returns the identifier; you resolve the record. Core is pure pixel + hash operations.
+
+## Encrypt private fields
+
+- Mark fields `private` to encrypt them (AES-256-GCM via PBKDF2) under a password.
+- The record still **verifies without the password** — the hash covers the ciphertext.
+- `unlock` returns the decrypted fields. The password is not stored; only the ciphertext is kept in the record.
+
+```python
+result = mememage.encode("photo.png", {"title": "Public", "gps": "45.5,-122.6"},
+                         password="hunter2", private=["gps"])
+mememage.verify("photo.png", result.record)              # matches — no password
+mememage.unlock(result, "hunter2")["gps"]                # '45.5,-122.6'
+```
+
+## Command line
+
+```bash
+mememage encode photo.png --field title="Morning fog" -o photo.json   # write the record
+mememage decode photo.jpg --record photo.json                         # VERIFIED (exit 0) / ALTERED (exit 1)
+mememage decode photo.jpg                                             # read the identifier only (no record)
+```
+
+Without `-o`, the record is written next to the image as `<identifier>.json`.
+`decode` exits 0 on a match.
+
+## License
+
+MIT.

mememage-0.1.0/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-0.1.0/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()