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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: c2pa-python
-Version: 0.35.0
+Version: 0.35.2
 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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "c2pa-python"
-version = "0.35.0"
+version = "0.35.2"
 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.2}/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
@@ -2235,6 +2263,9 @@ class Reader(ManagedResource):
         if not context.is_valid:
             raise C2paError("Context is not valid")
 
+        if manifest_data is not None and not isinstance(manifest_data, bytes):
+            raise TypeError(Reader._ERROR_MESSAGES['manifest_error'])
+
         # Determine format and open stream
         supported = Reader.get_supported_mime_types()
 
@@ -2275,10 +2306,6 @@ class Reader(ManagedResource):
                 raise
 
             if manifest_data is not None:
-                if not isinstance(manifest_data, bytes):
-                    raise TypeError(
-                        Reader._ERROR_MESSAGES[
-                            'manifest_error'])
                 manifest_array = (
                     ctypes.c_ubyte *
                     len(manifest_data)).from_buffer_copy(manifest_data)
@@ -2294,14 +2321,15 @@ class Reader(ManagedResource):
                         len(manifest_data),
                     )
                 )
-                # reader_ptr has been invalidated(consumed)
             else:
                 # Consume reader with stream
                 new_ptr = _lib.c2pa_reader_with_stream(
                     reader_ptr, format_bytes,
                     self._own_stream._stream,
                 )
-                # reader_ptr has been invalidated(consumed)
+
+            # reader_ptr has been consumed by the FFI call.
+            reader_ptr = None
 
             self._handle = new_ptr
 
@@ -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.2/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.2
 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.2}/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)
@@ -5548,6 +6041,119 @@ class TestReaderWithContext(TestContextAPIs):
         context.close()
 
 
+class TestSidecarReader(TestContextAPIs):
+    """Reader over a detached (sidecar) manifest with a Context"""
+
+    def _make_detached_manifest(self):
+        """Sign DEFAULT_TEST_FILE with no-embed, return (asset_bytes,
+        manifest_bytes) where manifest_bytes is the "detached" sidecar
+        C2PA manifest."""
+
+        signer = self._ctx_make_signer()
+        with open(DEFAULT_TEST_FILE, "rb") as f:
+            asset_bytes = f.read()
+        builder = Builder(self.test_manifest)
+        builder.set_no_embed()
+        # Output is discarded: with no-embed the asset is unchanged and the
+        # manifest is returned by sign().
+        manifest_bytes = builder.sign(
+            signer, "image/jpeg", io.BytesIO(asset_bytes), io.BytesIO())
+        builder.close()
+        signer.close()
+        self.assertIsInstance(manifest_bytes, bytes)
+        self.assertGreater(len(manifest_bytes), 0)
+        return asset_bytes, manifest_bytes
+
+    def test_reader_with_manifest_data_and_context(self):
+        asset_bytes, manifest_bytes = self._make_detached_manifest()
+        context = Context()
+        reader = Reader(
+            "image/jpeg",
+            io.BytesIO(asset_bytes),
+            manifest_bytes,
+            context=context,
+        )
+        try:
+            data = reader.json()
+            self.assertTrue(data)
+            self.assertFalse(reader.is_embedded())
+            self.assertIn("manifests", json.loads(data))
+        finally:
+            reader.close()
+            context.close()
+
+    def test_reader_manifest_data_context_invalid_manifest_raises(self):
+        with open(DEFAULT_TEST_FILE, "rb") as f:
+            asset_bytes = f.read()
+        context = Context()
+        reader = None
+        try:
+            with self.assertRaises(Error):
+                reader = Reader(
+                    "image/jpeg",
+                    io.BytesIO(asset_bytes),
+                    b"not a real manifest",
+                    context=context,
+                )
+            # The consumed-pointer error branch must leave no usable handle.
+            if reader is not None:
+                self.assertEqual(
+                    reader._lifecycle_state, LifecycleState.CLOSED)
+                self.assertIsNone(reader._handle)
+        finally:
+            if reader is not None:
+                reader.close()
+            context.close()
+
+    def test_reader_manifest_data_context_wrong_type_raises(self):
+        with open(DEFAULT_TEST_FILE, "rb") as f:
+            asset_bytes = f.read()
+        context = Context()
+        try:
+            # Non-bytes manifest_data must raise TypeError before any native
+            # reader handle is allocated (no leak on this path).
+            with self.assertRaises(TypeError):
+                Reader(
+                    "image/jpeg",
+                    io.BytesIO(asset_bytes),
+                    "manifest as str, not bytes",
+                    context=context,
+                )
+        finally:
+            context.close()
+
+    def test_reader_manifest_data_context_use_after_close_raises(self):
+        asset_bytes, manifest_bytes = self._make_detached_manifest()
+        context = Context()
+        reader = Reader(
+            "image/jpeg",
+            io.BytesIO(asset_bytes),
+            manifest_bytes,
+            context=context,
+        )
+        reader.close()
+        self.assertEqual(reader._lifecycle_state, LifecycleState.CLOSED)
+        with self.assertRaises(Error):
+            reader.json()
+        # Idempotent close after use-after-close attempt.
+        reader.close()
+        context.close()
+
+    def test_reader_manifest_data_context_as_context_manager(self):
+        asset_bytes, manifest_bytes = self._make_detached_manifest()
+        context = Context()
+        with Reader(
+            "image/jpeg",
+            io.BytesIO(asset_bytes),
+            manifest_bytes,
+            context=context,
+        ) as reader:
+            self.assertEqual(reader._lifecycle_state, LifecycleState.ACTIVE)
+            self.assertTrue(reader.json())
+        self.assertEqual(reader._lifecycle_state, LifecycleState.CLOSED)
+        context.close()
+
+
 class TestBuilderWithContext(TestContextAPIs):
 
     def test_contextual_builder_with_default_context(self):
@@ -6255,5 +6861,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')