From 650a2aade60f8049c23bdb3574ce12e3d34b2ba2 Mon Sep 17 00:00:00 2001 From: Colin Murphy Date: Wed, 22 Oct 2025 09:48:50 -0400 Subject: [PATCH 1/3] docs: add Markdown file comparing different bindings SDKs --- Bindings.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 Bindings.md diff --git a/Bindings.md b/Bindings.md new file mode 100644 index 000000000..36443089a --- /dev/null +++ b/Bindings.md @@ -0,0 +1,108 @@ +# C2PA Language Bindings Comparison + +This document provides a comprehensive comparison of Reader and Builder methods across the different language bindings for the C2PA Rust SDK. + +## Reader Methods Comparison + +| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-python | +|--------|--------------|------------------|--------|-------------| +| `from_stream` | ❌ | ❌ | ✅ | ✅ | +| `from_file` | ❌ | N/A | ✅ | ✅ | +| `from_json` | ❌ | ❌ | ❌ | ❌ | +| `from_manifest_data_and_stream` | ✅ | ❌ | ❌ | ✅ | +| `from_fragment` | ❌ | ✅ | ❌ | ❌ | +| `from_fragmented_files` | ❌ | N/A | ❌ | ❌ | +| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | +| `json` | ✅ | ✅ | ✅ | ✅ | +| `detailed_json` | ❌ | ❌ | ❌ | ❌ | +| `remote_url` | ✅ | ❌ | ✅ | ✅ | +| `is_embedded` | ✅ | ❌ | ✅ | ✅ | +| `validation_status` | ❌ | ❌ | ❌ | ❌ | +| `validation_results` | ❌ | ❌ | ❌ | ✅ | +| `validation_state` | ❌ | ❌ | ❌ | ✅ | +| `active_manifest` | ✅ | ✅ | ❌ | ✅ | +| `active_label` | ✅ | ✅ | ❌ | ❌ | +| `iter_manifests` | ❌ | ❌ | ❌ | ❌ | +| `manifests` | ❌ | ❌ | ❌ | ❌ | +| `get_manifest` | ❌ | ❌ | ❌ | ✅ | +| `resource_to_stream` | ✅ | ✅ | ✅ | ✅ | +| `to_folder` | ❌ | N/A | ❌ | ❌ | +| `post_validate` | ✅ | ❌ | ❌ | ❌ | + +### Reader Method Notes + +- **c2pa-node-v2**: Uses `fromAsset` and `fromManifestDataAndAsset` instead of `from_stream` and `from_manifest_data_and_stream` +- **c2pa-js/c2pa-web**: Uses `fromBlob` and `fromBlobFragment` instead of `from_stream` and `from_fragment`. File-based methods are N/A due to browser security restrictions +- **c2pa-c**: Uses `read_file` function instead of Reader class methods for file reading +- **c2pa-python**: Has comprehensive Reader class with most methods available + +## Builder Methods Comparison + +| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-python | +|--------|--------------|------------------|--------|-------------| +| `new` | ✅ | ❌ | ❌ | ❌ | +| `set_intent` | ✅ | ❌ | ❌ | ❌ | +| `from_json` | ✅ | ✅ | ✅ | ✅ | +| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | +| `claim_version` | ❌ | ❌ | ❌ | ❌ | +| `set_claim_generator_info` | ❌ | ❌ | ❌ | ❌ | +| `set_format` | ❌ | ❌ | ❌ | ❌ | +| `set_base_path` | ❌ | N/A | ✅ | ❌ | +| `set_remote_url` | ✅ | ✅ | ✅ | ✅ | +| `set_no_embed` | ✅ | ✅ | ✅ | ✅ | +| `set_thumbnail` | ❌ | ✅ | ❌ | ❌ | +| `add_assertion` | ✅ | ❌ | ❌ | ❌ | +| `add_assertion_json` | ❌ | ❌ | ❌ | ❌ | +| `add_action` | ❌ | ❌ | ✅ | ✅ | +| `add_ingredient_from_stream` | ✅ | ✅ | ✅ | ✅ | +| `add_ingredient` | ✅ | ✅ | ❌ | ✅ | +| `add_resource` | ✅ | ✅ | ✅ | ✅ | +| `to_archive` | ✅ | ❌ | ✅ | ✅ | +| `from_archive` | ✅ | ❌ | ✅ | ✅ | +| `data_hashed_placeholder` | ❌ | ❌ | ✅ | ❌ | +| `sign_data_hashed_embeddable` | ❌ | ❌ | ✅ | ❌ | +| `sign_box_hashed_embeddable` | ❌ | ❌ | ❌ | ❌ | +| `sign` | ✅ | ✅ | ✅ | ✅ | +| `sign_fragmented_files` | ❌ | N/A | ❌ | ❌ | +| `sign_file` | ✅ | N/A | ✅ | ✅ | +| `composed_manifest` | ❌ | ❌ | ❌ | ❌ | + +### Builder Method Notes + +- **c2pa-node-v2**: Uses `withJson` instead of `from_json`, has comprehensive Builder class +- **c2pa-js/c2pa-web**: Uses `fromDefinition` instead of `from_json`, has `setThumbnailFromBlob` instead of `set_thumbnail`. File-based methods are N/A due to browser security restrictions, but archive methods can work with buffers +- **c2pa-c**: Uses `Builder(const std::string &manifest_json)` constructor instead of `from_json` +- **c2pa-python**: Has comprehensive Builder class with most methods available + +## Summary + +### Reader Coverage +- **c2pa-python**: 15/22 methods (68%) ✅ +- **c2pa-c**: 8/22 methods (36%) ⚠️ +- **c2pa-node-v2**: 7/22 methods (32%) ⚠️ +- **c2pa-js/c2pa-web**: 4/22 methods (18%) - Note: 3 methods N/A due to browser limitations + +### Builder Coverage +- **c2pa-python**: 12/25 methods (48%) ✅ +- **c2pa-c**: 10/25 methods (40%) ⚠️ +- **c2pa-node-v2**: 9/25 methods (36%) ⚠️ +- **c2pa-js/c2pa-web**: 6/25 methods (24%) - Note: 2 methods N/A due to browser limitations + +### Key Observations + +1. **c2pa-python** has the most comprehensive implementation with the highest method coverage +2. **c2pa-c** provides good coverage for core functionality but lacks some advanced features +3. **c2pa-node-v2** has good coverage for Builder operations but limited Reader functionality +4. **c2pa-js/c2pa-web** has the most limited coverage, focusing on web-specific use cases + +### Missing Critical Methods + +- **Validation methods**: Most bindings lack `validation_status`, `validation_results`, and `validation_state` +- **Advanced Reader methods**: `detailed_json`, `iter_manifests`, `manifests`, `to_folder` +- **Advanced Builder methods**: `data_hashed_placeholder`, `sign_data_hashed_embeddable`, `composed_manifest` + +### Legend +- ✅ = Method available +- ❌ = Method not available +- N/A = Not applicable (e.g., file system access in browser environments) +- ⚠️ = Partial coverage \ No newline at end of file From 988bf84f184e7548f2c01214728ea36cb60d26fc Mon Sep 17 00:00:00 2001 From: Colin Murphy Date: Wed, 22 Oct 2025 13:52:28 -0400 Subject: [PATCH 2/3] docs: add c_ffi --- Bindings.md | 108 +++++++++++++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 52 deletions(-) diff --git a/Bindings.md b/Bindings.md index 36443089a..e9aa1623d 100644 --- a/Bindings.md +++ b/Bindings.md @@ -4,86 +4,90 @@ This document provides a comprehensive comparison of Reader and Builder methods ## Reader Methods Comparison -| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-python | -|--------|--------------|------------------|--------|-------------| -| `from_stream` | ❌ | ❌ | ✅ | ✅ | -| `from_file` | ❌ | N/A | ✅ | ✅ | -| `from_json` | ❌ | ❌ | ❌ | ❌ | -| `from_manifest_data_and_stream` | ✅ | ❌ | ❌ | ✅ | -| `from_fragment` | ❌ | ✅ | ❌ | ❌ | -| `from_fragmented_files` | ❌ | N/A | ❌ | ❌ | -| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | -| `json` | ✅ | ✅ | ✅ | ✅ | -| `detailed_json` | ❌ | ❌ | ❌ | ❌ | -| `remote_url` | ✅ | ❌ | ✅ | ✅ | -| `is_embedded` | ✅ | ❌ | ✅ | ✅ | -| `validation_status` | ❌ | ❌ | ❌ | ❌ | -| `validation_results` | ❌ | ❌ | ❌ | ✅ | -| `validation_state` | ❌ | ❌ | ❌ | ✅ | -| `active_manifest` | ✅ | ✅ | ❌ | ✅ | -| `active_label` | ✅ | ✅ | ❌ | ❌ | -| `iter_manifests` | ❌ | ❌ | ❌ | ❌ | -| `manifests` | ❌ | ❌ | ❌ | ❌ | -| `get_manifest` | ❌ | ❌ | ❌ | ✅ | -| `resource_to_stream` | ✅ | ✅ | ✅ | ✅ | -| `to_folder` | ❌ | N/A | ❌ | ❌ | -| `post_validate` | ✅ | ❌ | ❌ | ❌ | +| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-c-ffi | c2pa-python | +|--------|--------------|------------------|--------|-------------|-------------| +| `from_stream` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `from_file` | ❌ | N/A | ✅ | ✅ | ✅ | +| `from_json` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `from_manifest_data_and_stream` | ✅ | ❌ | ❌ | ✅ | ✅ | +| `from_fragment` | ❌ | ✅ | ❌ | ❌ | ❌ | +| `from_fragmented_files` | ❌ | N/A | ❌ | ❌ | ❌ | +| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `json` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `detailed_json` | ❌ | ❌ | ❌ | ✅ | ❌ | +| `remote_url` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `is_embedded` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `validation_status` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `validation_results` | ❌ | ❌ | ❌ | ❌ | ✅ | +| `validation_state` | ❌ | ❌ | ❌ | ❌ | ✅ | +| `active_manifest` | ✅ | ✅ | ❌ | ❌ | ✅ | +| `active_label` | ✅ | ✅ | ❌ | ❌ | ❌ | +| `iter_manifests` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `manifests` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `get_manifest` | ❌ | ❌ | ❌ | ❌ | ✅ | +| `resource_to_stream` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `to_folder` | ❌ | N/A | ❌ | ❌ | ❌ | +| `post_validate` | ✅ | ❌ | ❌ | ❌ | ❌ | ### Reader Method Notes - **c2pa-node-v2**: Uses `fromAsset` and `fromManifestDataAndAsset` instead of `from_stream` and `from_manifest_data_and_stream` - **c2pa-js/c2pa-web**: Uses `fromBlob` and `fromBlobFragment` instead of `from_stream` and `from_fragment`. File-based methods are N/A due to browser security restrictions - **c2pa-c**: Uses `read_file` function instead of Reader class methods for file reading +- **c2pa-c-ffi**: Provides C API functions for most Reader operations, including `c2pa_reader_from_stream`, `c2pa_reader_from_file`, `c2pa_reader_json`, etc. - **c2pa-python**: Has comprehensive Reader class with most methods available ## Builder Methods Comparison -| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-python | -|--------|--------------|------------------|--------|-------------| -| `new` | ✅ | ❌ | ❌ | ❌ | -| `set_intent` | ✅ | ❌ | ❌ | ❌ | -| `from_json` | ✅ | ✅ | ✅ | ✅ | -| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | -| `claim_version` | ❌ | ❌ | ❌ | ❌ | -| `set_claim_generator_info` | ❌ | ❌ | ❌ | ❌ | -| `set_format` | ❌ | ❌ | ❌ | ❌ | -| `set_base_path` | ❌ | N/A | ✅ | ❌ | -| `set_remote_url` | ✅ | ✅ | ✅ | ✅ | -| `set_no_embed` | ✅ | ✅ | ✅ | ✅ | -| `set_thumbnail` | ❌ | ✅ | ❌ | ❌ | -| `add_assertion` | ✅ | ❌ | ❌ | ❌ | -| `add_assertion_json` | ❌ | ❌ | ❌ | ❌ | -| `add_action` | ❌ | ❌ | ✅ | ✅ | -| `add_ingredient_from_stream` | ✅ | ✅ | ✅ | ✅ | -| `add_ingredient` | ✅ | ✅ | ❌ | ✅ | -| `add_resource` | ✅ | ✅ | ✅ | ✅ | -| `to_archive` | ✅ | ❌ | ✅ | ✅ | -| `from_archive` | ✅ | ❌ | ✅ | ✅ | -| `data_hashed_placeholder` | ❌ | ❌ | ✅ | ❌ | -| `sign_data_hashed_embeddable` | ❌ | ❌ | ✅ | ❌ | -| `sign_box_hashed_embeddable` | ❌ | ❌ | ❌ | ❌ | -| `sign` | ✅ | ✅ | ✅ | ✅ | -| `sign_fragmented_files` | ❌ | N/A | ❌ | ❌ | -| `sign_file` | ✅ | N/A | ✅ | ✅ | -| `composed_manifest` | ❌ | ❌ | ❌ | ❌ | +| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-c-ffi | c2pa-python | +|--------|--------------|------------------|--------|-------------|-------------| +| `new` | ✅ | ❌ | ❌ | ❌ | ❌ | +| `set_intent` | ✅ | ❌ | ❌ | ❌ | ❌ | +| `from_json` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `claim_version` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `set_claim_generator_info` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `set_format` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `set_base_path` | ❌ | N/A | ✅ | ✅ | ❌ | +| `set_remote_url` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `set_no_embed` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `set_thumbnail` | ❌ | ✅ | ❌ | ❌ | ❌ | +| `add_assertion` | ✅ | ❌ | ❌ | ❌ | ❌ | +| `add_assertion_json` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `add_action` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `add_ingredient_from_stream` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `add_ingredient` | ✅ | ✅ | ❌ | ❌ | ✅ | +| `add_resource` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `to_archive` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `from_archive` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `data_hashed_placeholder` | ❌ | ❌ | ✅ | ✅ | ❌ | +| `sign_data_hashed_embeddable` | ❌ | ❌ | ✅ | ✅ | ❌ | +| `sign_box_hashed_embeddable` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `sign` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `sign_fragmented_files` | ❌ | N/A | ❌ | ❌ | ❌ | +| `sign_file` | ✅ | N/A | ✅ | ✅ | ✅ | +| `composed_manifest` | ❌ | ❌ | ❌ | ❌ | ❌ | ### Builder Method Notes - **c2pa-node-v2**: Uses `withJson` instead of `from_json`, has comprehensive Builder class - **c2pa-js/c2pa-web**: Uses `fromDefinition` instead of `from_json`, has `setThumbnailFromBlob` instead of `set_thumbnail`. File-based methods are N/A due to browser security restrictions, but archive methods can work with buffers - **c2pa-c**: Uses `Builder(const std::string &manifest_json)` constructor instead of `from_json` +- **c2pa-c-ffi**: Provides C API functions for Builder operations, including `c2pa_builder_from_json`, `c2pa_builder_sign`, etc. - **c2pa-python**: Has comprehensive Builder class with most methods available ## Summary ### Reader Coverage - **c2pa-python**: 15/22 methods (68%) ✅ +- **c2pa-c-ffi**: 12/22 methods (55%) ✅ - **c2pa-c**: 8/22 methods (36%) ⚠️ - **c2pa-node-v2**: 7/22 methods (32%) ⚠️ - **c2pa-js/c2pa-web**: 4/22 methods (18%) - Note: 3 methods N/A due to browser limitations ### Builder Coverage - **c2pa-python**: 12/25 methods (48%) ✅ +- **c2pa-c-ffi**: 12/25 methods (48%) ✅ - **c2pa-c**: 10/25 methods (40%) ⚠️ - **c2pa-node-v2**: 9/25 methods (36%) ⚠️ - **c2pa-js/c2pa-web**: 6/25 methods (24%) - Note: 2 methods N/A due to browser limitations From 217658c73662fd6a67d82ca1387c807a11461fe3 Mon Sep 17 00:00:00 2001 From: Colin Murphy Date: Wed, 22 Oct 2025 14:08:46 -0400 Subject: [PATCH 3/3] docs: move Bindings.md to docs Add cursor rules file to keep Bindings.md up to date and have the prompt in source control. --- .cursorrules | 32 ++++++++++++++++++++++++++++++++ Bindings.md => docs/Bindings.md | 0 2 files changed, 32 insertions(+) create mode 100644 .cursorrules rename Bindings.md => docs/Bindings.md (100%) diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 000000000..c063a7a60 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,32 @@ +# C2PA Language Bindings Documentation + +## Update Bindings.md Task + +When asked to "update the bindings comparison" or similar, perform the following task: + +1. **Examine the current Reader and Builder methods** in `sdk/src/reader.rs` and `sdk/src/builder.rs` +2. **Check each language binding** for method availability: + - `../c2pa-node-v2` - Node.js binding + - `../c2pa-js/packages/c2pa-web` - Web JavaScript binding + - `../c2pa-c` - C++ binding + - `./c2pa_c_ffi` - C FFI binding + - `../c2pa-python` - Python binding + +3. **Update the comparison tables** in `docs/Bindings.md` with: + - ✅ = Method available + - ❌ = Method not available + - N/A = Not applicable (e.g., file system access in browser environments) + +4. **Key considerations**: + - Web JS SDK cannot access files directly, so file-based methods should be N/A + - Archive methods (`to_archive`, `from_archive`) can work with buffers in web environments + - Different bindings may use different method names (e.g., `fromAsset` vs `from_stream`) + - Update coverage statistics and method notes accordingly + +5. **Focus on**: + - Reader methods from the Reader struct + - Builder methods from the Builder struct + - Accurate representation of what's actually available in each binding + - Clear distinction between unavailable vs not applicable methods + +This ensures the docs/Bindings.md document stays current with the evolving C2PA language bindings. \ No newline at end of file diff --git a/Bindings.md b/docs/Bindings.md similarity index 100% rename from Bindings.md rename to docs/Bindings.md