otdf-python 0.11.0__tar.gz → 0.12.0__tar.gz

{otdf_python-0.11.0 → otdf_python-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: otdf-python
-Version: 0.11.0
+Version: 0.12.0
 Summary: Unofficial OpenTDF SDK for Python
 Project-URL: Homepage, https://github.com/b-long/opentdf-python-sdk
 Project-URL: Repository, https://github.com/b-long/opentdf-python-sdk
@@ -25,9 +25,9 @@ Requires-Dist: connect-python>=0.9.0
 Requires-Dist: cryptography>=50.0.0
 Requires-Dist: grpcio-status>=1.74.0
 Requires-Dist: grpcio>=1.74.0
-Requires-Dist: httpx2>=2.3.0
+Requires-Dist: httpx2>=2.12.0
 Requires-Dist: protobuf>=6.31.1
-Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: pyjwt>=2.15.0
 Requires-Dist: typing-extensions>=4.14.1
 Description-Content-Type: text/markdown
 
@@ -130,6 +130,12 @@ with open("decrypted.txt", "wb") as f:
 
 ```
 
+## TDF container format
+
+TDF archives are written with the spec-mandated `manifest.json` zip entry (per opentdf/spec) instead of the legacy `0.manifest.json`. Readers accept both names, so archives written by older versions of this SDK remain readable forever. The payload zip entry is resolved from `manifest.payload.url` rather than assumed. `schemaVersion` is unchanged (still `4.3.0`); `tdf_spec_version` is now read at either its legacy or spec-conformant placement, but never written.
+
+**Interoperability note:** archives written by this version cannot currently be opened by released `otdfctl`, or by the upstream `opentdf/platform` Go, Java, or JS SDKs, until they add a `manifest.json` read fallback (an upstream reader-fallback PR is planned). If you interoperate with those tools today, hold off upgrading until that fallback ships.
+
 ## Project Structure
 
 ```

{otdf_python-0.11.0 → otdf_python-0.12.0}/README.md

@@ -97,6 +97,12 @@ with open("decrypted.txt", "wb") as f:
 
 ```
 
+## TDF container format
+
+TDF archives are written with the spec-mandated `manifest.json` zip entry (per opentdf/spec) instead of the legacy `0.manifest.json`. Readers accept both names, so archives written by older versions of this SDK remain readable forever. The payload zip entry is resolved from `manifest.payload.url` rather than assumed. `schemaVersion` is unchanged (still `4.3.0`); `tdf_spec_version` is now read at either its legacy or spec-conformant placement, but never written.
+
+**Interoperability note:** archives written by this version cannot currently be opened by released `otdfctl`, or by the upstream `opentdf/platform` Go, Java, or JS SDKs, until they add a `manifest.json` read fallback (an upstream reader-fallback PR is planned). If you interoperate with those tools today, hold off upgrading until that fallback ships.
+
 ## Project Structure
 
 ```

{otdf_python-0.11.0 → otdf_python-0.12.0}/hatch_build.py

@@ -8,7 +8,7 @@ from hatchling.builders.hooks.plugin.interface import BuildHookInterface
 class CustomBuildHook(BuildHookInterface):
     """Dynamically resolves proto sources for wheel builds from source tree or sdist."""
 
-    def initialize(self, version, build_data):
+    def initialize(self, _version, build_data):
         """Set force_include for otdf_python_proto based on build context."""
         if self.target_name != "wheel":
             return

{otdf_python-0.11.0 → otdf_python-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "otdf-python"
-version = "0.11.0"
+version = "0.12.0"
 description = "Unofficial OpenTDF SDK for Python"
 readme = "README.md"
 authors = [
@@ -27,9 +27,9 @@ classifiers = [
 dependencies = [
     "cryptography>=50.0.0",
     "connect-python>=0.9.0",
-    "httpx2>=2.3.0",
+    "httpx2>=2.12.0",
     "protobuf>=6.31.1",
-    "pyjwt>=2.10.1",
+    "pyjwt>=2.15.0",
     "typing-extensions>=4.14.1",
     # Legacy gRPC support (may be removed in future versions)
     "grpcio>=1.74.0",

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/aesgcm.py

@@ -44,7 +44,9 @@ class AesGcm:
     def encrypt_with_iv(
         self,
         iv: bytes,
-        auth_tag_len: int,
+        # Kept for signature parity with the Java SDK; the cryptography lib
+        # derives the tag length itself.
+        auth_tag_len: int,  # noqa: ARG002
         plaintext: bytes,
         offset: int = 0,
         length: int | None = None,
@@ -58,6 +60,11 @@ class AesGcm:
         return self.aesgcm.decrypt(encrypted.iv, encrypted.ciphertext, None)
 
     def decrypt_with_iv(
-        self, iv: bytes, auth_tag_len: int, cipher_data: bytes
+        self,
+        iv: bytes,
+        # Kept for signature parity with the Java SDK; the cryptography lib
+        # derives the tag length itself.
+        auth_tag_len: int,  # noqa: ARG002
+        cipher_data: bytes,
     ) -> bytes:
         return self.aesgcm.decrypt(iv, cipher_data, None)

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/cli.py

@@ -205,12 +205,15 @@ def build_sdk(args) -> SDK:
 
 # Features the Python SDK currently exercises honestly in community xtest Stage-1.
 # Keep conservative: only advertise what encrypt/decrypt paths actually honor.
+# "spec-container": writes manifest.json at the zip root and resolves the
+# payload entry from manifest.payload.url (opentdf/spec container rules).
 _SUPPORTED_FEATURES: frozenset[str] = frozenset(
     {
         "autoconfigure",
         "connectrpc",
         "hexless",
         "kasallowlist",
+        "spec-container",
     }
 )
 
@@ -238,6 +241,7 @@ _KNOWN_FEATURES: frozenset[str] = frozenset(
         "mechanism-mlkem",
         "ns_grants",
         "obligations",
+        "spec-container",
     }
 )
 
@@ -286,7 +290,7 @@ def create_tdf_config(sdk: SDK, args) -> TDFConfig:
     return config
 
 
-def create_nano_tdf_config(sdk: SDK, args) -> NanoTDFConfig:
+def create_nano_tdf_config(_sdk: SDK, args) -> NanoTDFConfig:
     """Create NanoTDF configuration from CLI arguments."""
     attributes = (
         parse_attributes(args.attributes)

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/collection_store.py

@@ -29,7 +29,7 @@ class NoOpCollectionStore(CollectionStore):
     def store(self, header, key: CollectionKey):
         """Discard key operation (no-op)."""
 
-    def get_key(self, header) -> CollectionKey:
+    def get_key(self, _header) -> CollectionKey:
         return self.NO_PRIVATE_KEY
 
 

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/kas_client.py

@@ -553,7 +553,7 @@ class KASClient:
             return RSA_KEY_TYPE
         return session_key_type
 
-    def _prepare_ec_keypair(self, session_key_type):
+    def _prepare_ec_keypair(self, _session_key_type):
         """Prepare EC key pair for unwrapping.
 
         Args:

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/manifest.py

@@ -86,6 +86,8 @@ class ManifestPayload:
     protocol: str
     mimeType: str
     isEncrypted: bool
+    # Read-only: some spec revisions place the version here. Never written.
+    tdf_spec_version: str | None = None
 
 
 @dataclass
@@ -116,6 +118,18 @@ class Manifest:
     encryptionInformation: ManifestEncryptionInformation | None = None
     payload: ManifestPayload | None = None
     assertions: list[ManifestAssertion] = field(default_factory=list)
+    # Read-only: spec prose places tdf_spec_version at the top level. Never written.
+    tdf_spec_version: str | None = None
+
+    def spec_version(self) -> str | None:
+        """Resolve the spec version: schemaVersion, then tdf_spec_version, then payload.tdf_spec_version."""
+        if self.schemaVersion:
+            return self.schemaVersion
+        if self.tdf_spec_version:
+            return self.tdf_spec_version
+        if self.payload and self.payload.tdf_spec_version:
+            return self.payload.tdf_spec_version
+        return None
 
     def _remove_none_values_and_empty_lists(self, obj):
         """Recursively remove None values and empty lists from dictionaries and lists."""
@@ -147,7 +161,9 @@ class Manifest:
             manifest_dict["encryptionInformation"] = asdict(self.encryptionInformation)
 
         if self.payload is not None:
-            manifest_dict["payload"] = asdict(self.payload)
+            payload_dict = asdict(self.payload)
+            payload_dict.pop("tdf_spec_version", None)
+            manifest_dict["payload"] = payload_dict
 
         if self.schemaVersion is not None:
             manifest_dict["schemaVersion"] = self.schemaVersion
@@ -229,6 +245,7 @@ class Manifest:
 
         return Manifest(
             schemaVersion=d.get("schemaVersion", d.get("tdf_version")),
+            tdf_spec_version=d.get("tdf_spec_version"),
             encryptionInformation=_enc_info(
                 d.get("encryptionInformation", d.get("encryption_information"))
             )

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/nanotdf.py

@@ -468,7 +468,7 @@ class NanoTDF:
         return len(header_bytes) + 3 + payload_length
 
     def _kas_unwrap(
-        self, nano_tdf_data: bytes, header_len: int, wrapped_key: bytes
+        self, nano_tdf_data: bytes, header_len: int, _wrapped_key: bytes
     ) -> bytes | None:
         try:
             # For NanoTDF, send the entire header to KAS
@@ -622,7 +622,7 @@ class NanoTDF:
         # Try KAS unwrap first if services available
         if self.services:
             try:
-                key = self._kas_unwrap(nano_tdf_data, header_len, wrapped_key=b"")
+                key = self._kas_unwrap(nano_tdf_data, header_len, b"")
                 if key:
                     logging.info(
                         "Successfully unwrapped NanoTDF key via KAS (ECDH mode)"

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/policy_binding_serializer.py

@@ -25,7 +25,7 @@ class PolicyBindingSerializer:
 
     @staticmethod
     def deserialize(
-        json_data: Any, typeofT: type | None = None, context: Any = None
+        json_data: Any, _typeof_t: type | None = None, _context: Any = None
     ) -> Any:
         if isinstance(json_data, dict):
             return PolicyBinding(**json_data)
@@ -35,7 +35,7 @@ class PolicyBindingSerializer:
 
     @staticmethod
     def serialize(
-        src: Any, typeofSrc: type | None = None, context: Any = None
+        src: Any, _typeof_src: type | None = None, _context: Any = None
     ) -> dict | str:
         if isinstance(src, PolicyBinding):
             return vars(src)

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/policy_info.py

@@ -43,7 +43,7 @@ class PolicyInfo:
         return offset - start
 
     @staticmethod
-    def from_bytes_with_size(buffer: bytes, ecc_mode):
+    def from_bytes_with_size(buffer: bytes, _ecc_mode):
         # Parse policy_type (1 byte), body_len (2 bytes), body
         # Note: binding is NOT part of PolicyInfo - it's read separately in Header
         offset = 0

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/sdk.py

@@ -97,9 +97,9 @@ class KAS(AbstractContextManager):
 
     def unwrap_nanotdf(
         self,
-        curve: Any,
-        header: str,
-        kas_url: str,
+        curve: Any,  # noqa: ARG002
+        header: str,  # noqa: ARG002
+        kas_url: str,  # noqa: ARG002
         wrapped_key: bytes | None = None,
         kas_private_key: str | None = None,
         mock: bool = False,
@@ -368,13 +368,22 @@ class SDK(AbstractContextManager):
         import zipfile
         from io import BytesIO
 
+        from otdf_python.tdf_reader import (
+            payload_url_from_manifest_json,
+            resolve_manifest_name,
+            resolve_payload_name,
+        )
+
         try:
             file_like = BytesIO(data) if isinstance(data, bytes | bytearray) else data
             with zipfile.ZipFile(file_like) as zf:
-                names = set(zf.namelist())
-                return {"0.manifest.json", "0.payload"}.issubset(names) and len(
-                    names
-                ) == 2
+                names = zf.namelist()
+                manifest_name = resolve_manifest_name(names)
+                url = payload_url_from_manifest_json(
+                    zf.read(manifest_name).decode("utf-8")
+                )
+                resolve_payload_name(url, names)
+                return True
         except Exception:
             return False
 

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/sdk_builder.py

@@ -275,7 +275,9 @@ class SDKBuilder:
         config_doc = response.json()
         # Newer platform versions return the fields directly at the top
         # level instead of nested under a "configuration" key.
-        configuration = config_doc.get("configuration") or config_doc
+        configuration = config_doc.get("configuration")
+        if configuration is None:
+            configuration = config_doc
 
         # Try to get token endpoint from IDP configuration
         idp_config = configuration.get("idp", {})

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/tdf.py

@@ -28,6 +28,7 @@ from otdf_python.manifest import (
     ManifestSegment,
 )
 from otdf_python.policy_stub import NULL_POLICY_UUID
+from otdf_python.tdf_reader import resolve_manifest_name, resolve_payload_name
 from otdf_python.tdf_writer import TDFWriter
 
 
@@ -399,7 +400,7 @@ class TDF:
         )
         payload_info = ManifestPayload(
             type="reference",  # Changed from "file" to "reference" to match Java SDK
-            url="0.payload",
+            url=TDFWriter.TDF_PAYLOAD_FILE_NAME,
             protocol="zip",
             mimeType=config.mime_type,  # Use MIME type from config
             isEncrypted=True,  # Changed from is_encrypted to isEncrypted
@@ -433,7 +434,8 @@ class TDF:
         tdf_bytes_io = io.BytesIO(tdf_data) if isinstance(tdf_data, bytes) else tdf_data
 
         with zipfile.ZipFile(tdf_bytes_io, "r") as z:
-            manifest_json = z.read("0.manifest.json").decode()
+            names = z.namelist()
+            manifest_json = z.read(resolve_manifest_name(names)).decode()
             manifest = Manifest.from_json(manifest_json)
 
             if not manifest.encryptionInformation:
@@ -464,7 +466,8 @@ class TDF:
             segments = (
                 manifest.encryptionInformation.integrityInformation.segments
             )  # Changed field name
-            encrypted_payload = z.read("0.payload")
+            payload_url = manifest.payload.url if manifest.payload else None
+            encrypted_payload = z.read(resolve_payload_name(payload_url, names))
             payload = self._decrypt_segments(aesgcm, segments, encrypted_payload)
             return TDFReader(payload=payload, manifest=manifest)
 
@@ -487,7 +490,8 @@ class TDF:
         from .asym_crypto import AsymDecryption
 
         with zipfile.ZipFile(io.BytesIO(tdf_bytes), "r") as z:
-            manifest_json = z.read("0.manifest.json").decode()
+            names = z.namelist()
+            manifest_json = z.read(resolve_manifest_name(names)).decode()
             manifest = Manifest.from_json(manifest_json)
 
             if not manifest.encryptionInformation:
@@ -510,7 +514,8 @@ class TDF:
             segments = (
                 manifest.encryptionInformation.integrityInformation.segments
             )  # Changed field names
-            encrypted_payload = z.read("0.payload")
+            payload_url = manifest.payload.url if manifest.payload else None
+            encrypted_payload = z.read(resolve_payload_name(payload_url, names))
             offset = 0
             for seg in segments:
                 enc_len = seg.encryptedSegmentSize  # Changed field name

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/tdf_reader.py

@@ -1,15 +1,71 @@
 """TDFReader is responsible for reading and processing Trusted Data Format (TDF) files."""
 
+import json
+from collections.abc import Iterable
+
 from .manifest import Manifest
 from .policy_object import PolicyObject
 from .sdk_exceptions import SDKException
 from .zip_reader import ZipReader
 
-# Constants from TDFWriter
-TDF_MANIFEST_FILE_NAME = "0.manifest.json"
+# Spec (opentdf/spec schema/OpenTDF/README.md): the manifest entry MUST be
+# `manifest.json` at the archive root. `0.manifest.json` is what every SDK
+# wrote before this change and is accepted forever on read.
+TDF_MANIFEST_FILE_NAME = "manifest.json"
+LEGACY_TDF_MANIFEST_FILE_NAME = "0.manifest.json"
+# Payload entry name. Written by TDFWriter and into manifest.payload.url.
+# On read this is only a fallback for manifests with an empty payload.url.
 TDF_PAYLOAD_FILE_NAME = "0.payload"
 
 
+def resolve_manifest_name(names: Iterable[str]) -> str:
+    """Return the zip entry holding the manifest, spec name first."""
+    name_set = set(names)
+    for candidate in (TDF_MANIFEST_FILE_NAME, LEGACY_TDF_MANIFEST_FILE_NAME):
+        if candidate in name_set:
+            return candidate
+    raise ValueError("tdf doesn't contain a manifest")
+
+
+def _is_safe_entry_name(name: str) -> bool:
+    if not name or name.startswith("/") or "\\" in name:
+        return False
+    return ".." not in name.split("/")
+
+
+def resolve_payload_name(payload_url: str | None, names: Iterable[str]) -> str:
+    """Return the zip entry holding the payload.
+
+    Uses manifest.payload.url when present; falls back to `0.payload` only
+    when the url is empty or missing.
+    """
+    name_set = set(names)
+    if payload_url:
+        if not _is_safe_entry_name(payload_url):
+            raise ValueError(f"unsafe payload url in manifest: {payload_url!r}")
+        if payload_url in name_set:
+            return payload_url
+        raise ValueError(f"tdf doesn't contain payload entry {payload_url!r}")
+    if TDF_PAYLOAD_FILE_NAME in name_set:
+        return TDF_PAYLOAD_FILE_NAME
+    raise ValueError("tdf doesn't contain a payload")
+
+
+def payload_url_from_manifest_json(manifest_text: str) -> str | None:
+    """Extract payload.url without requiring a fully valid manifest."""
+    try:
+        data = json.loads(manifest_text)
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    payload = data.get("payload")
+    if not isinstance(payload, dict):
+        return None
+    url = payload.get("url")
+    return url if isinstance(url, str) else None
+
+
 class TDFReader:
     """TDFReader is responsible for reading and processing Trusted Data Format (TDF) files.
 
@@ -31,15 +87,16 @@ class TDFReader:
         try:
             self._zip_reader = ZipReader(tdf)
             namelist = self._zip_reader.namelist()
-
-            if TDF_MANIFEST_FILE_NAME not in namelist:
-                raise ValueError("tdf doesn't contain a manifest")
-            if TDF_PAYLOAD_FILE_NAME not in namelist:
-                raise ValueError("tdf doesn't contain a payload")
-
-            # Store the names for later use
-            self._manifest_name = TDF_MANIFEST_FILE_NAME
-            self._payload_name = TDF_PAYLOAD_FILE_NAME
+            self._manifest_name = resolve_manifest_name(namelist)
+            manifest_text = self._zip_reader.read(self._manifest_name).decode("utf-8")
+            payload_url = payload_url_from_manifest_json(manifest_text)
+            self._payload_name = resolve_payload_name(payload_url, namelist)
+        except UnicodeDecodeError as e:
+            # UnicodeDecodeError is a ValueError subclass, but it means the
+            # manifest entry is corrupt, not that the tdf is missing an
+            # entry (the resolvers' own ValueErrors). Wrap it like any
+            # other unexpected failure instead of letting it pass through.
+            raise SDKException("Error initializing TDFReader") from e
         except Exception as e:
             if isinstance(e, ValueError):
                 raise

{otdf_python-0.11.0 → otdf_python-0.12.0}/src/otdf_python/tdf_writer.py

@@ -8,8 +8,10 @@ from otdf_python.zip_writer import ZipWriter
 class TDFWriter:
     """TDF file writer for creating encrypted TDF packages."""
 
+    # Spec: manifest entry MUST be `manifest.json` at the archive root.
+    TDF_MANIFEST_FILE_NAME = "manifest.json"
+    # Payload entry name; TDF.create_tdf writes this same value into manifest.payload.url.
     TDF_PAYLOAD_FILE_NAME = "0.payload"
-    TDF_MANIFEST_FILE_NAME = "0.manifest.json"
 
     def __init__(self, out_stream: io.BytesIO | None = None):
         """Initialize TDF writer."""