c2pa-python 0.35.0__tar.gz → 0.35.1__tar.gz

{c2pa_python-0.35.0/src/c2pa_python.egg-info → c2pa_python-0.35.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: c2pa-python
-Version: 0.35.0
+Version: 0.35.1
 Summary: Python bindings for the C2PA Content Authenticity Initiative (CAI) library
 Author-email: Gavin Peacock <gvnpeacock@adobe.com>, Tania Mathern <mathern@adobe.com>
-Maintainer-email: Gavin Peacock <gpeacock@adobe.com>
+Maintainer-email: Gavin Peacock <gpeacock@adobe.com>, Tania Mathern <mathern@adobe.com>
 License: MIT OR Apache-2.0
 Project-URL: homepage, https://contentauthenticity.org
 Project-URL: repository, https://github.com/contentauth/c2pa-python

{c2pa_python-0.35.0 → c2pa_python-0.35.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "c2pa-python"
-version = "0.35.0"
+version = "0.35.1"
 requires-python = ">=3.10"
 description = "Python bindings for the C2PA Content Authenticity Initiative (CAI) library"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -17,7 +17,8 @@ classifiers = [
     "Operating System :: Microsoft :: Windows"
 ]
 maintainers = [
-  {name = "Gavin Peacock", email = "gpeacock@adobe.com"}
+  {name = "Gavin Peacock", email = "gpeacock@adobe.com"},
+  {name = "Tania Mathern", email = "mathern@adobe.com"}
 ]
 urls = {homepage = "https://contentauthenticity.org", repository = "https://github.com/contentauth/c2pa-python"}
 dependencies = [

{c2pa_python-0.35.0 → c2pa_python-0.35.1}/src/c2pa/c2pa.py

@@ -18,6 +18,7 @@ import logging
 import sys
 import os
 import warnings
+import weakref
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Optional, Union, Callable, Any, overload
@@ -65,6 +66,8 @@ _REQUIRED_FUNCTIONS = [
     'c2pa_builder_add_ingredient_from_stream',
     'c2pa_builder_add_action',
     'c2pa_builder_to_archive',
+    'c2pa_builder_write_ingredient_archive',
+    'c2pa_builder_add_ingredient_from_archive',
     'c2pa_builder_sign',
     'c2pa_builder_sign_context',
     'c2pa_builder_from_context',
@@ -623,6 +626,15 @@ _setup_function(_lib.c2pa_builder_add_action,
 _setup_function(_lib.c2pa_builder_to_archive,
                 [ctypes.POINTER(C2paBuilder), ctypes.POINTER(C2paStream)],
                 ctypes.c_int)
+_setup_function(_lib.c2pa_builder_write_ingredient_archive,
+                [ctypes.POINTER(C2paBuilder),
+                 ctypes.c_char_p,
+                 ctypes.POINTER(C2paStream)],
+                ctypes.c_int)
+_setup_function(_lib.c2pa_builder_add_ingredient_from_archive,
+                [ctypes.POINTER(C2paBuilder),
+                 ctypes.POINTER(C2paStream)],
+                ctypes.c_int)
 _setup_function(_lib.c2pa_builder_sign,
                 [ctypes.POINTER(C2paBuilder),
                  ctypes.c_char_p,
@@ -1614,6 +1626,10 @@ class Stream:
 
         self._file_like_stream = file_like_stream
 
+        # Weakref breaks avoids references cycles:
+        # Stream -> ctypes_cb -> closure -> Stream.
+        _weak_self = weakref.ref(self)
+
         def read_callback(ctx, data, length):
             """Callback function for reading data from the Python stream.
 
@@ -1632,13 +1648,16 @@ class Stream:
             Returns:
                 Number of bytes read, or -1 on error
             """
-            if not self._initialized or self._closed:
+            s = _weak_self()
+            if s is None:
+                return -1
+            if not s._initialized or s._closed:
                 return -1
             try:
                 if not data or length <= 0:
                     return -1
 
-                stream = self._file_like_stream
+                stream = s._file_like_stream
                 readinto = getattr(stream, "readinto", None)
                 if readinto is not None:
                     # Most streams have readinto
@@ -1689,8 +1708,11 @@ class Stream:
             Returns:
                 New position in the stream, or -1 on error
             """
-            file_stream = self._file_like_stream
-            if not self._initialized or self._closed:
+            s = _weak_self()
+            if s is None:
+                return -1
+            file_stream = s._file_like_stream
+            if not s._initialized or s._closed:
                 return -1
             try:
                 # Fall back to tell() only for stream objects that do not
@@ -1718,13 +1740,16 @@ class Stream:
             Returns:
                 Number of bytes written, or -1 on error
             """
-            if not self._initialized or self._closed:
+            s = _weak_self()
+            if s is None:
+                return -1
+            if not s._initialized or s._closed:
                 return -1
             try:
                 if not data or length <= 0:
                     return -1
 
-                self._file_like_stream.write(ctypes.string_at(data, length))
+                s._file_like_stream.write(ctypes.string_at(data, length))
                 return length
             except Exception:
                 return -1
@@ -1743,10 +1768,13 @@ class Stream:
             Returns:
                 0 on success, -1 on error
             """
-            if not self._initialized or self._closed:
+            s = _weak_self()
+            if s is None:
+                return -1
+            if not s._initialized or s._closed:
                 return -1
             try:
-                self._file_like_stream.flush()
+                s._file_like_stream.flush()
                 return 0
             except Exception:
                 return -1
@@ -2898,6 +2926,7 @@ class Builder(ManagedResource):
         'url_error': "Error setting remote URL: {}",
         'resource_error': "Error adding resource: {}",
         'ingredient_error': "Error adding ingredient: {}",
+        'archive_read_error': "Error loading ingredient from archive: {}",
         'action_error': "Error adding action: {}",
         'archive_error': "Error writing archive: {}",
         'sign_error': "Error during signing: {}",
@@ -3287,6 +3316,55 @@ class Builder(ManagedResource):
                 Builder._ERROR_MESSAGES["archive_error"].format("Unknown error"),
                 check=lambda r: r != 0)
 
+    def write_ingredient_archive(self, ingredient_id: str, stream: Any) -> None:
+        """Write a single-ingredient archive for the named ingredient.
+        The archive is in C2PA format.
+
+        Args:
+            ingredient_id: Identifier of the ingredient within this builder;
+                matched against the ingredient's label or instance_id
+            stream: Writable, seekable stream to receive the archive
+
+        Raises:
+            C2paError: If there was an error writing the archive
+        """
+        self._ensure_valid_state()
+
+        ingredient_id_str = _to_utf8_bytes(ingredient_id, "ingredient_id")
+
+        with Stream(stream) as stream_obj:
+            result = _lib.c2pa_builder_write_ingredient_archive(
+                self._handle, ingredient_id_str, stream_obj._stream)
+
+            _check_ffi_operation_result(result,
+                Builder._ERROR_MESSAGES["archive_error"].format(
+                    "Unknown error"
+                ),
+                check=lambda r: r != 0)
+
+    def add_ingredient_from_archive(self, stream: Any) -> None:
+        """Add an ingredient from a per-ingredient archive stream.
+        The archive must be in C2PA format, as written by
+        write_ingredient_archive.
+
+        Args:
+            stream: Readable, seekable stream containing the ingredient archive
+
+        Raises:
+            C2paError: If there was an error reading the archive
+        """
+        self._ensure_valid_state()
+
+        with Stream(stream) as stream_obj:
+            result = _lib.c2pa_builder_add_ingredient_from_archive(
+                self._handle, stream_obj._stream)
+
+            _check_ffi_operation_result(result,
+                Builder._ERROR_MESSAGES["archive_read_error"].format(
+                    "Unknown error"
+                ),
+                check=lambda r: r != 0)
+
     def with_archive(self, stream: Any) -> 'Builder':
         """Load an archive into this Builder instance, replacing its
         manifest definition. The archive carries only the

{c2pa_python-0.35.0 → c2pa_python-0.35.1/src/c2pa_python.egg-info}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: c2pa-python
-Version: 0.35.0
+Version: 0.35.1
 Summary: Python bindings for the C2PA Content Authenticity Initiative (CAI) library
 Author-email: Gavin Peacock <gvnpeacock@adobe.com>, Tania Mathern <mathern@adobe.com>
-Maintainer-email: Gavin Peacock <gpeacock@adobe.com>
+Maintainer-email: Gavin Peacock <gpeacock@adobe.com>, Tania Mathern <mathern@adobe.com>
 License: MIT OR Apache-2.0
 Project-URL: homepage, https://contentauthenticity.org
 Project-URL: repository, https://github.com/contentauth/c2pa-python

{c2pa_python-0.35.0 → c2pa_python-0.35.1}/tests/test_unit_tests.py

@@ -23,7 +23,6 @@ from cryptography.hazmat.backends import default_backend
 import tempfile
 import shutil
 import ctypes
-import toml
 import threading
 
 # Suppress deprecation warnings
@@ -1945,6 +1944,500 @@ class TestBuilderWithSigner(unittest.TestCase):
         self.assertIsNotNone(result.get('validation_state'))
         self.assertEqual(result.get('validation_state'), "Trusted")
 
+    def test_write_ingredient_archive_produces_readable_archive(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "0.1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "componentOf",
+            "instance_id": "ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("ingredient-A", archive)
+        builder.close()
+        self.assertGreater(len(archive.getvalue()), 0)
+        archive.close()
+
+    def test_add_ingredient_from_archive_roundtrip(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "0.1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "componentOf",
+            "instance_id": "catalog:ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("catalog:ingredient-A", archive)
+        builder.close()
+
+        archive.seek(0)
+        builder2 = Builder.from_json(manifest)
+        builder2.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            builder2.sign(self.signer, "image/jpeg", f, output)
+        builder2.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_preserves_instance_id(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "0.1.0"}],
+            "assertions": [],
+        }
+        archive_builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "parentOf",
+            "instance_id": "my-ingredient",
+        }
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive("my-ingredient", archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("photo.jpg", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_preserves_instance_id_component_of(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        archive_builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "componentOf",
+            "instance_id": "my-ingredient",
+        }
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive("my-ingredient", archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("photo.jpg", json_data)
+        self.assertIn("componentOf", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_preserves_instance_id_input_to(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        archive_builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "inputTo",
+            "instance_id": "my-ingredient",
+        }
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive("my-ingredient", archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("photo.jpg", json_data)
+        self.assertIn("inputTo", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_roundtrip_parent_of(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "parentOf",
+            "instance_id": "catalog:ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("catalog:ingredient-A", archive)
+        builder.close()
+
+        archive.seek(0)
+        builder2 = Builder.from_json(manifest)
+        builder2.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            builder2.sign(self.signer, "image/jpeg", f, output)
+        builder2.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        self.assertIn("parentOf", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_roundtrip_input_to(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "inputTo",
+            "instance_id": "catalog:ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("catalog:ingredient-A", archive)
+        builder.close()
+
+        archive.seek(0)
+        builder2 = Builder.from_json(manifest)
+        builder2.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            builder2.sign(self.signer, "image/jpeg", f, output)
+        builder2.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        self.assertIn("inputTo", json_data)
+        output.close()
+
+    def test_ingredient_from_archive_linked_to_opened_action(self):
+        ingredient_id = "xmp:iid:archive-parent-001"
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions.v2",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.opened",
+                                "parameters": {"ingredientIds": [ingredient_id]},
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+        archive_builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(
+                {"title": "photo.jpg", "relationship": "parentOf", "instance_id": ingredient_id},
+                "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive(ingredient_id, archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("c2pa.opened", json_data)
+        self.assertIn(ingredient_id, json_data)
+        output.close()
+
+    def test_ingredient_from_archive_linked_to_placed_action(self):
+        ingredient_id = "xmp:iid:archive-component-001"
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions.v2",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.placed",
+                                "parameters": {"ingredientIds": [ingredient_id]},
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+        archive_builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(
+                {"title": "photo.jpg", "relationship": "componentOf", "instance_id": ingredient_id},
+                "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive(ingredient_id, archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("c2pa.placed", json_data)
+        self.assertIn(ingredient_id, json_data)
+        output.close()
+
+    def test_ingredient_from_archive_linked_to_edited_action(self):
+        ingredient_id = "xmp:iid:archive-input-001"
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions.v2",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.edited",
+                                "parameters": {"ingredientIds": [ingredient_id]},
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+        archive_builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(
+                {"title": "photo.jpg", "relationship": "inputTo", "instance_id": ingredient_id},
+                "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive(ingredient_id, archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("c2pa.edited", json_data)
+        self.assertIn(ingredient_id, json_data)
+        output.close()
+
+    def test_add_two_ingredient_archives_to_one_builder(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        archives = []
+        for title, instance_id in [("A.jpg", "ingredient-A"), ("B.jpg", "ingredient-B")]:
+            archive_builder = Builder.from_json(manifest)
+            ingredient_json = {
+                "title": title,
+                "relationship": "componentOf",
+                "instance_id": instance_id,
+            }
+            with open(self.testPath, "rb") as f:
+                archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+            archive = io.BytesIO()
+            archive_builder.write_ingredient_archive(instance_id, archive)
+            archive_builder.close()
+            archive.seek(0)
+            archives.append(archive)
+
+        signing_builder = Builder.from_json(manifest)
+        for archive in archives:
+            signing_builder.add_ingredient_from_archive(archive)
+            archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        self.assertIn("B.jpg", json_data)
+        output.close()
+
+    def test_write_ingredient_archive_only_contains_requested_ingredient(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        archive_builder = Builder.from_json(manifest)
+        for title, instance_id in [("A.jpg", "ingredient-A"), ("B.jpg", "ingredient-B")]:
+            ingredient_json = {
+                "title": title,
+                "relationship": "componentOf",
+                "instance_id": instance_id,
+            }
+            with open(self.testPath, "rb") as f:
+                archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive("ingredient-A", archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        self.assertNotIn("B.jpg", json_data)
+        output.close()
+
+    def test_write_ingredient_archive_matches_label_or_instance_id(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "componentOf",
+            "label": "my-label",
+            "instance_id": "my-instance-id",
+        }
+        builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+
+        by_label = io.BytesIO()
+        builder.write_ingredient_archive("my-label", by_label)
+        self.assertGreater(len(by_label.getvalue()), 0)
+        by_label.close()
+
+        by_instance_id = io.BytesIO()
+        builder.write_ingredient_archive("my-instance-id", by_instance_id)
+        self.assertGreater(len(by_instance_id.getvalue()), 0)
+        by_instance_id.close()
+
+        builder.close()
+
+    def test_write_ingredient_archive_unknown_id_raises(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "componentOf",
+            "instance_id": "ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        with self.assertRaises(Error):
+            builder.write_ingredient_archive("nonexistent-id", io.BytesIO())
+        builder.close()
+
+    def test_add_ingredient_from_archive_invalid_data_raises(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        with self.assertRaises(Error):
+            builder.add_ingredient_from_archive(io.BytesIO(b"not a c2pa archive"))
+        with self.assertRaises(Error):
+            builder.add_ingredient_from_archive(io.BytesIO())
+        builder.close()
+
+    def test_ingredient_archive_methods_raise_on_closed_builder(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        builder.close()
+        with self.assertRaises(Error):
+            builder.write_ingredient_archive("ingredient-A", io.BytesIO())
+        with self.assertRaises(Error):
+            builder.add_ingredient_from_archive(io.BytesIO())
+
     def test_remote_sign(self):
         with open(self.testPath, "rb") as file:
             builder = Builder(self.manifestDefinition)
@@ -6255,5 +6748,68 @@ class TestContextIntegration(TestContextAPIs):
         context.close()
 
 
+class TestStreamReferences(unittest.TestCase):
+
+    def test_stream_collected_after_del(self):
+        """Stream must be collected by reference counting."""
+        import gc
+        import weakref
+        gc.collect()
+        garbage_before = len(gc.garbage)
+
+        buf = io.BytesIO(b"hello world")
+        s = Stream(buf)
+        ref = weakref.ref(s)
+        del s
+
+        # Trigger gc, we want to verify it's collected
+        # collected now (1 gc call) means no gc cycle breaker needed
+        # aka ref cycle did not happen.
+        gc.collect()
+
+        self.assertIsNone(ref(), "Stream not collected")
+        self.assertEqual(len(gc.garbage), garbage_before,
+                         "Stream added objects to gc.garbage")
+
+    def test_stream_not_added_to_gc_garbage_list(self):
+        """Creating and dropping many Streams must not grow gc.garbage."""
+        import gc
+        gc.collect()
+        gc.garbage.clear()
+
+        for _ in range(20):
+            s = Stream(io.BytesIO(b"data"))
+            del s
+
+        gc.collect()
+        self.assertEqual(len(gc.garbage), 0,
+                         f"gc.garbage unexpectedly non-empty: {gc.garbage}")
+
+    def test_callbacks_return_minus_one_after_stream_collected(self):
+        """Callbacks must return -1 gracefully when the Stream has been GC'd."""
+        import gc
+        import weakref
+
+        buf = io.BytesIO(b"test")
+        s = Stream(buf)
+
+        read_cb = s._read_cb
+        seek_cb = s._seek_cb
+        write_cb = s._write_cb
+        flush_cb = s._flush_cb
+        ref = weakref.ref(s)
+        del s
+        gc.collect()
+
+        # Stream should be gone.
+        self.assertIsNone(ref(), "Stream not collected before callback test")
+
+        # All callbacks must return -1 without crashing.
+        self.assertEqual(read_cb(None, None, 0), -1)
+        self.assertEqual(seek_cb(None, 0, 0), -1)
+        self.assertEqual(write_cb(None, None, 0), -1)
+        self.assertEqual(flush_cb(None), -1)
+
+
 if __name__ == '__main__':
     unittest.main(warnings='ignore')