feat(meta): add META_TRIM_META size limit for meta payload (Fixes #132)

Add configurable `meta_trim_meta` option (default 128KB, 0 = no limit) to
CoreOptions that validates decoded `meta` payload size in `gen_meta_code_v0`.
Raises ValueError for oversized payloads instead of truncating, since meta
contains structured data that cannot be meaningfully truncated. Added to
conformance-critical options set.

Author: titusz

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [1.3.0] - Unreleased
 
+- Added `meta_trim_meta` option to limit decoded `meta` payload size in `gen_meta_code_v0` (Fixes #132)
 - Added conformance test vectors for JCS number canonicalization in Meta-Code (Fixes #131)
 - Migrated from Poetry to uv for dependency management and build tooling
 - Migrated pyproject.toml from Poetry format to PEP 621 with setuptools backend

iscc_core/code_meta.py

@@ -64,18 +64,26 @@ def gen_meta_code_v0(name, description=None, meta=None, bits=ic.core_opts.meta_b
             # Data-URL expected
             durl = meta
             payload = DataURL.from_url(durl).data
-            meta_code_digest = soft_hash_meta_v0(name, payload)
-            metahash = ic.multi_hash_blake3(payload)
-            metadata_value = durl
         elif isinstance(meta, dict):
             payload = jcs.canonicalize(meta)
-            meta_code_digest = soft_hash_meta_v0(name, payload)
-            metahash = ic.multi_hash_blake3(payload)
+        else:
+            raise TypeError(f"metadata must be Data-URL string or dict not {type(meta)}")
+
+        limit = ic.core_opts.meta_trim_meta
+        if limit and len(payload) > limit:
+            raise ValueError(
+                f"meta payload size ({len(payload)} bytes) exceeds META_TRIM_META ({limit} bytes)"
+            )
+
+        meta_code_digest = soft_hash_meta_v0(name, payload)
+        metahash = ic.multi_hash_blake3(payload)
+
+        if isinstance(meta, str):
+            metadata_value = durl
+        else:
             media_type = "application/ld+json" if "@context" in meta else "application/json"
             durl_obj = DataURL.from_byte_data(media_type, data=payload)
             metadata_value = durl_obj.url
-        else:
-            raise TypeError(f"metadata must be Data-URL string or dict not {type(meta)}")
     else:
         payload = " ".join((name, description)).strip().encode("utf-8")
         meta_code_digest = soft_hash_meta_v0(name, description)

iscc_core/options.py

@@ -34,6 +34,10 @@ class Config:
     meta_trim_description: int = Field(
         4096, description="Trim `description` to this number of bytes"
     )
+    meta_trim_meta: int = Field(
+        128_000,
+        description="Maximum decoded payload size in bytes for the meta element. 0 = no limit.",
+    )
     meta_ngram_size_text: int = Field(
         3, description="Sliding window width (characters) for metadata"
     )
@@ -366,6 +370,7 @@ class Config:
 conformanc_critical = {
     "meta_trim_name",
     "meta_trim_description",
+    "meta_trim_meta",
     "meta_ngram_size_text",
     "meta_ngram_size_bytes",
     "text_ngram_size",

tests/test_code_meta.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+import base64
 import pytest
 import iscc_core as ic
 
@@ -179,3 +180,41 @@ def test_remove_newlines():
     txt = "   Hello\nWorld!  - How Are you   "
     exp = "Hello World! - How Are you"
     assert ic.text_remove_newlines(txt) == exp
+
+
+def test_meta_trim_meta_at_limit(monkeypatch):
+    """Payload exactly at limit should succeed."""
+    monkeypatch.setattr(ic.core_opts, "meta_trim_meta", 100)
+    payload = b"x" * 100
+    encoded = base64.b64encode(payload).decode("ascii")
+    durl = f"data:application/octet-stream;base64,{encoded}"
+    result = ic.gen_meta_code_v0("Test", meta=durl)
+    assert "iscc" in result
+
+
+def test_meta_trim_meta_over_limit(monkeypatch):
+    """Payload exceeding limit should raise ValueError."""
+    monkeypatch.setattr(ic.core_opts, "meta_trim_meta", 100)
+    payload = b"x" * 101
+    encoded = base64.b64encode(payload).decode("ascii")
+    durl = f"data:application/octet-stream;base64,{encoded}"
+    with pytest.raises(ValueError, match="META_TRIM_META"):
+        ic.gen_meta_code_v0("Test", meta=durl)
+
+
+def test_meta_trim_meta_disabled(monkeypatch):
+    """Limit of 0 disables the check."""
+    monkeypatch.setattr(ic.core_opts, "meta_trim_meta", 0)
+    payload = b"x" * 200_000
+    encoded = base64.b64encode(payload).decode("ascii")
+    durl = f"data:application/octet-stream;base64,{encoded}"
+    result = ic.gen_meta_code_v0("Test", meta=durl)
+    assert "iscc" in result
+
+
+def test_meta_trim_meta_dict_over_limit(monkeypatch):
+    """Dict meta exceeding limit after JCS canonicalization should raise ValueError."""
+    monkeypatch.setattr(ic.core_opts, "meta_trim_meta", 50)
+    big_dict = {"key": "v" * 100}
+    with pytest.raises(ValueError, match="META_TRIM_META"):
+        ic.gen_meta_code_v0("Test", meta=big_dict)