ajar-connector 0.5.3__tar.gz

ajar_connector-0.5.3/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: ajar-connector
+Version: 0.5.3
+Summary: Python SDK for building byte-compatible connectors to the Ajar integration plane.
+Author: Ajar connectors contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/promaka/ajar-connectors
+Project-URL: Documentation, https://github.com/promaka/ajar-connectors/blob/main/docs/embedding-python.md
+Project-URL: Wire contract, https://github.com/promaka/ajar-connectors/blob/main/docs/wire-contract-v1.md
+Project-URL: Source, https://github.com/promaka/ajar-connectors
+Project-URL: Changelog, https://github.com/promaka/ajar-connectors/blob/main/CHANGELOG.md
+Keywords: ajar,connector,defence,interoperability,protobuf,ed25519
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: protobuf<8,>=7.35
+Requires-Dist: cryptography>=42
+Provides-Extra: examples
+Requires-Dist: nats-py>=2.6; extra == "examples"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# ajar-connector (Python)
+
+The Python SDK for building byte-compatible connectors to Ajar. Types are
+generated from the same vendored `event.proto` as the Rust/Go/C++ SDKs, so this
+SDK reproduces the **same** golden vectors.
+
+## Try the template in 10 seconds
+
+```bash
+cd python
+pip install -e .                     # or: pip install protobuf cryptography
+echo '{"lat":26.4,"lon":50.9,"alt_m":11000,"quality":0.9}' \
+  | PYTHONPATH=. python examples/connector_template.py --dry-run
+# -> 019e... -> ajar.ingest.demo-connector (196 sealed bytes)  [dry-run]
+```
+
+You just built and signed a canonical Ajar event. To make it yours, edit the one
+function marked `EDIT` in [examples/connector_template.py](examples/connector_template.py).
+
+## Use it in code
+
+```python
+from ajar_connector import EventBuilder, canonical_bytes, seal, SigningKey
+
+event = (
+    EventBuilder("acme-radar-1", "mim:aircraft")
+    .new_id().now()
+    .location(26.4, 50.9, 11000.0)
+    .confidence(0.94)
+    .build()
+)
+sealed = seal(canonical_bytes(event), SigningKey.from_seed(my_seed))  # 64-byte sig ++ canonical
+```
+
+## Run the checks
+
+```bash
+cd python
+python -m pytest                                   # unit tests
+PYTHONPATH=. python conformance/golden_vectors.py   # the byte-compat gate
+```
+
+## Streaming example
+
+```bash
+pip install -e ".[examples]"                        # adds nats-py
+PYTHONPATH=. python examples/synthetic_radar.py      # publish to a local Core
+PYTHONPATH=. python examples/synthetic_radar.py --dry-run --ticks 3   # no infra
+```
+
+See the full [onboarding guide](../ONBOARDING.md) for data flow, deployment
+topology, key generation, and troubleshooting.
+
+> The conformance gate and `--dry-run` need only `protobuf` + `cryptography`.
+> `nats-py` is an `examples` extra, kept out of the SDK's core dependencies.

ajar_connector-0.5.3/README.md

@@ -0,0 +1,56 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# ajar-connector (Python)
+
+The Python SDK for building byte-compatible connectors to Ajar. Types are
+generated from the same vendored `event.proto` as the Rust/Go/C++ SDKs, so this
+SDK reproduces the **same** golden vectors.
+
+## Try the template in 10 seconds
+
+```bash
+cd python
+pip install -e .                     # or: pip install protobuf cryptography
+echo '{"lat":26.4,"lon":50.9,"alt_m":11000,"quality":0.9}' \
+  | PYTHONPATH=. python examples/connector_template.py --dry-run
+# -> 019e... -> ajar.ingest.demo-connector (196 sealed bytes)  [dry-run]
+```
+
+You just built and signed a canonical Ajar event. To make it yours, edit the one
+function marked `EDIT` in [examples/connector_template.py](examples/connector_template.py).
+
+## Use it in code
+
+```python
+from ajar_connector import EventBuilder, canonical_bytes, seal, SigningKey
+
+event = (
+    EventBuilder("acme-radar-1", "mim:aircraft")
+    .new_id().now()
+    .location(26.4, 50.9, 11000.0)
+    .confidence(0.94)
+    .build()
+)
+sealed = seal(canonical_bytes(event), SigningKey.from_seed(my_seed))  # 64-byte sig ++ canonical
+```
+
+## Run the checks
+
+```bash
+cd python
+python -m pytest                                   # unit tests
+PYTHONPATH=. python conformance/golden_vectors.py   # the byte-compat gate
+```
+
+## Streaming example
+
+```bash
+pip install -e ".[examples]"                        # adds nats-py
+PYTHONPATH=. python examples/synthetic_radar.py      # publish to a local Core
+PYTHONPATH=. python examples/synthetic_radar.py --dry-run --ticks 3   # no infra
+```
+
+See the full [onboarding guide](../ONBOARDING.md) for data flow, deployment
+topology, key generation, and troubleshooting.
+
+> The conformance gate and `--dry-run` need only `protobuf` + `cryptography`.
+> `nats-py` is an `examples` extra, kept out of the SDK's core dependencies.

ajar_connector-0.5.3/ajar_connector/__init__.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+"""ajar-connector: the Python SDK for building byte-compatible connectors to the
+Ajar integration plane.
+
+Types are generated from the same vendored ``event.proto`` as the Rust, Go, and
+C++ SDKs; canonical bytes are the deterministic protobuf encoding that gets
+hashed and signed. The shared ``vendor/contract/vectors.json`` proves this
+SDK's output is byte-identical to the others.
+"""
+
+from .builder import MAX_ATTRIBUTES, MAX_METADATA, MAX_POLICY_TAGS, BuildError, EventBuilder
+from .canonical import canonical_bytes
+from .connector import Connector, OutboundProfile
+from .event_pb2 import Attribute, Event, GeoPoint
+from .profile import ConnectorProfile
+from .seal import SEAL_SIGNATURE_LEN, SealVerificationError, SigningKey, seal, verify
+
+__all__ = [
+    "Attribute",
+    "BuildError",
+    "Connector",
+    "ConnectorProfile",
+    "Event",
+    "EventBuilder",
+    "GeoPoint",
+    "MAX_ATTRIBUTES",
+    "MAX_METADATA",
+    "MAX_POLICY_TAGS",
+    "OutboundProfile",
+    "SEAL_SIGNATURE_LEN",
+    "SealVerificationError",
+    "SigningKey",
+    "canonical_bytes",
+    "seal",
+    "verify",
+]

ajar_connector-0.5.3/ajar_connector/builder.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Ergonomic, fail-closed construction of canonical Events."""
+
+import os
+import time
+from datetime import datetime, timezone
+
+from .event_pb2 import Event
+
+MAX_ATTRIBUTES = 128
+MAX_METADATA = 128
+MAX_POLICY_TAGS = 64
+_SCHEMA_VERSION = "v1"
+
+
+class BuildError(Exception):
+    """Raised when a canonical invariant or required field is violated."""
+
+
+def _uuid7() -> str:
+    """A UUIDv7 string (48-bit ms timestamp + random), dependency-free."""
+    b = bytearray(os.urandom(16))
+    ms = int(time.time() * 1000)
+    b[0] = (ms >> 40) & 0xFF
+    b[1] = (ms >> 32) & 0xFF
+    b[2] = (ms >> 24) & 0xFF
+    b[3] = (ms >> 16) & 0xFF
+    b[4] = (ms >> 8) & 0xFF
+    b[5] = ms & 0xFF
+    b[6] = (b[6] & 0x0F) | 0x70  # version 7
+    b[8] = (b[8] & 0x3F) | 0x80  # RFC 4122 variant
+    h = b.hex()
+    return f"{h[0:8]}-{h[8:12]}-{h[12:16]}-{h[16:20]}-{h[20:32]}"
+
+
+def _is_namespaced(entity_type: str) -> bool:
+    """True if entity_type is mim:<type> or x:<vendor>:<type>."""
+    if entity_type.startswith("mim:"):
+        rest = entity_type[4:]
+        return bool(rest) and ":" not in rest
+    if entity_type.startswith("x:"):
+        parts = entity_type[2:].split(":")
+        return len(parts) == 2 and all(parts)
+    return False
+
+
+class EventBuilder:
+    """Builds a canonical Event. Auto-sorts attributes, rejects duplicate keys,
+    enforces required fields and limits, offers UUIDv7 / RFC 3339 helpers.
+    ``received_at`` is intentionally not exposed — Ajar stamps its own clock.
+    """
+
+    def __init__(self, source_id: str, entity_type: str) -> None:
+        self._source_id = source_id
+        self._entity_type = entity_type
+        self._id: str | None = None
+        self._timestamp: str | None = None
+        self._location: tuple[float, float, float] | None = None
+        self._payload = b""
+        self._policy_tags: list[str] = []
+        self._confidence = 0.0
+        self._attributes: list[tuple[str, str]] = []
+        self._metadata: list[tuple[str, str]] = []
+        self._strict_entity_namespace = True
+
+    def id(self, value: str) -> "EventBuilder":
+        self._id = value
+        return self
+
+    def new_id(self) -> "EventBuilder":
+        self._id = _uuid7()
+        return self
+
+    def timestamp(self, ts: str) -> "EventBuilder":
+        self._timestamp = ts
+        return self
+
+    def now(self) -> "EventBuilder":
+        self._timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        return self
+
+    def location(self, latitude: float, longitude: float, altitude_m: float) -> "EventBuilder":
+        self._location = (latitude, longitude, altitude_m)
+        return self
+
+    def payload(self, data: bytes) -> "EventBuilder":
+        self._payload = data
+        return self
+
+    def policy_tag(self, tag: str) -> "EventBuilder":
+        self._policy_tags.append(tag)
+        return self
+
+    def confidence(self, confidence: float) -> "EventBuilder":
+        self._confidence = confidence
+        return self
+
+    def attribute(self, key: str, value: str) -> "EventBuilder":
+        self._attributes.append((key, value))
+        return self
+
+    def metadata(self, key: str, value: str) -> "EventBuilder":
+        """Add one ungoverned passthrough metadata entry (ADR-0030): a
+        vendor-specific field carried and audited opaquely, but not
+        type-validated or correlated (e.g. a source's native identifier).
+        Order does not matter — ``build`` sorts by key and rejects duplicates.
+        """
+        self._metadata.append((key, value))
+        return self
+
+    def allow_unnamespaced_entity_type(self) -> "EventBuilder":
+        self._strict_entity_namespace = False
+        return self
+
+    def build(self) -> Event:
+        """Validate invariants and produce the canonical Event."""
+        if not self._id:
+            raise BuildError("missing required field: id")
+        if not self._timestamp:
+            raise BuildError("missing required field: timestamp")
+        if not self._source_id:
+            raise BuildError("missing required field: source_id")
+        if not self._entity_type:
+            raise BuildError("missing required field: entity_type")
+        if self._strict_entity_namespace and not _is_namespaced(self._entity_type):
+            raise BuildError(
+                f"entity_type {self._entity_type!r} is not namespaced as "
+                "mim:<type> or x:<vendor>:<type>"
+            )
+        if not (0.0 <= self._confidence <= 1.0):
+            raise BuildError(f"confidence {self._confidence} is outside [0.0, 1.0]")
+        if len(self._policy_tags) > MAX_POLICY_TAGS:
+            raise BuildError(f"too many policy tags: {len(self._policy_tags)} (max {MAX_POLICY_TAGS})")
+        if len(self._attributes) > MAX_ATTRIBUTES:
+            raise BuildError(f"too many attributes: {len(self._attributes)} (max {MAX_ATTRIBUTES})")
+        if len(self._metadata) > MAX_METADATA:
+            raise BuildError(f"too many metadata entries: {len(self._metadata)} (max {MAX_METADATA})")
+
+        # Canonical rule: attributes sorted by key, unique.
+        attrs = sorted(self._attributes, key=lambda kv: kv[0])
+        for i in range(1, len(attrs)):
+            if attrs[i][0] == attrs[i - 1][0]:
+                raise BuildError(f"duplicate attribute key: {attrs[i][0]!r}")
+
+        # Metadata follows the identical canonical rule: sorted by key, unique.
+        meta = sorted(self._metadata, key=lambda kv: kv[0])
+        for i in range(1, len(meta)):
+            if meta[i][0] == meta[i - 1][0]:
+                raise BuildError(f"duplicate metadata key: {meta[i][0]!r}")
+
+        event = Event()
+        event.schema_version = _SCHEMA_VERSION
+        event.id = self._id
+        event.source_id = self._source_id
+        event.entity_type = self._entity_type
+        event.timestamp = self._timestamp
+        # received_at intentionally left empty — Ajar stamps its own clock.
+        if self._location is not None:
+            event.location.latitude = self._location[0]
+            event.location.longitude = self._location[1]
+            event.location.altitude_m = self._location[2]
+        event.payload = self._payload
+        event.policy_tags.extend(self._policy_tags)
+        event.confidence = self._confidence
+        for key, value in attrs:
+            event.attributes.add(key=key, value=value)
+        for key, value in meta:
+            event.metadata.add(key=key, value=value)
+        return event

ajar_connector-0.5.3/ajar_connector/canonical.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Canonical byte encoding of an Event."""
+
+from .event_pb2 import Event
+
+
+def canonical_bytes(event: Event) -> bytes:
+    """Return the canonical protobuf encoding of ``event``.
+
+    ``deterministic=True`` gives ascending tag order with proto3 defaults
+    omitted and map keys sorted (the contract has no maps) — the same wire
+    shape prost (Rust), Go, libprotobuf, and nanopb produce. The caller owns
+    the attribute invariant (sorted by key, unique); EventBuilder guarantees it.
+    """
+    return event.SerializeToString(deterministic=True)

ajar_connector-0.5.3/ajar_connector/connector.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Connector interfaces: inbound normalization and outbound rendering."""
+
+import abc
+
+from .event_pb2 import Event
+
+
+class Connector(abc.ABC):
+    """An inbound connector: native bytes -> canonical Event.
+
+    Implementations parse ``native`` (CoT XML, a CSV row, a vendor frame, ...)
+    and return a fully-populated event, ideally via EventBuilder.
+    """
+
+    @abc.abstractmethod
+    def normalize(self, native: bytes) -> Event:
+        ...
+
+
+class OutboundProfile(abc.ABC):
+    """An outbound profile: render a governed Event into a target format.
+
+    Its honesty is the modeled/lossy field declaration; round-trip conformance
+    (canonical -> target -> canonical) checks the claim.
+    """
+
+    @abc.abstractmethod
+    def target(self) -> str: ...
+
+    @abc.abstractmethod
+    def slug(self) -> str: ...
+
+    @abc.abstractmethod
+    def version(self) -> str: ...
+
+    @abc.abstractmethod
+    def modeled_fields(self) -> list[str]: ...
+
+    @abc.abstractmethod
+    def lossy_fields(self) -> list[str]: ...
+
+    @abc.abstractmethod
+    def render(self, event: Event) -> bytes: ...

ajar_connector-0.5.3/ajar_connector/event_pb2.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: event.proto
+# Protobuf Python Version: 7.35.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    7,
+    35,
+    0,
+    '',
+    'event.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0b\x65vent.proto\x12\rajar.event.v1\"\xba\x02\n\x05\x45vent\x12\x16\n\x0eschema_version\x18\x01 \x01(\t\x12\n\n\x02id\x18\x02 \x01(\t\x12\x11\n\tsource_id\x18\x03 \x01(\t\x12\x13\n\x0b\x65ntity_type\x18\x04 \x01(\t\x12\x11\n\ttimestamp\x18\x05 \x01(\t\x12\x13\n\x0breceived_at\x18\n \x01(\t\x12)\n\x08location\x18\x06 \x01(\x0b\x32\x17.ajar.event.v1.GeoPoint\x12\x0f\n\x07payload\x18\x07 \x01(\x0c\x12\x13\n\x0bpolicy_tags\x18\x08 \x03(\t\x12\x12\n\nconfidence\x18\t \x01(\x01\x12,\n\nattributes\x18\x0b \x03(\x0b\x32\x18.ajar.event.v1.Attribute\x12*\n\x08metadata\x18\x0c \x03(\x0b\x32\x18.ajar.event.v1.Attribute\"\'\n\tAttribute\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t\"C\n\x08GeoPoint\x12\x10\n\x08latitude\x18\x01 \x01(\x01\x12\x11\n\tlongitude\x18\x02 \x01(\x01\x12\x12\n\naltitude_m\x18\x03 \x01(\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'event_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_EVENT']._serialized_start=31
+  _globals['_EVENT']._serialized_end=345
+  _globals['_ATTRIBUTE']._serialized_start=347
+  _globals['_ATTRIBUTE']._serialized_end=386
+  _globals['_GEOPOINT']._serialized_start=388
+  _globals['_GEOPOINT']._serialized_end=455
+# @@protoc_insertion_point(module_scope)

ajar_connector-0.5.3/ajar_connector/profile.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Connector profile: the self-declaration a connector publishes."""
+
+import json
+
+
+class ConnectorProfile:
+    """A connector's published profile. Serializes deterministically (verifying
+    key as lowercase hex); byte-identical to the Rust/Go/C++ profile JSON.
+    """
+
+    def __init__(self, source_id: str, verifying_key: bytes) -> None:
+        self.source_id = source_id
+        self.allowed_entity_types: list[str] = []
+        self.max_payload_bytes = 64 * 1024
+        self.rate_capacity = 100
+        self.rate_refill_per_sec = 10.0
+        self.verifying_key = verifying_key
+
+    def allow_entity_type(self, entity_type: str) -> "ConnectorProfile":
+        self.allowed_entity_types.append(entity_type)
+        return self
+
+    def with_max_payload_bytes(self, max_bytes: int) -> "ConnectorProfile":
+        self.max_payload_bytes = max_bytes
+        return self
+
+    def rate_limit(self, capacity: int, refill_per_sec: float) -> "ConnectorProfile":
+        self.rate_capacity = capacity
+        self.rate_refill_per_sec = refill_per_sec
+        return self
+
+    def _wire(self) -> dict:
+        return {
+            "source_id": self.source_id,
+            "allowed_entity_types": self.allowed_entity_types,
+            "max_payload_bytes": self.max_payload_bytes,
+            "rate_capacity": self.rate_capacity,
+            "rate_refill_per_sec": self.rate_refill_per_sec,
+            "verifying_key_hex": self.verifying_key.hex(),
+        }
+
+    def to_json(self) -> str:
+        """Compact JSON."""
+        return json.dumps(self._wire(), separators=(",", ":"))
+
+    def to_json_pretty(self) -> str:
+        """Indented JSON."""
+        return json.dumps(self._wire(), indent=2)

ajar_connector-0.5.3/ajar_connector/seal.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The seal envelope: detached Ed25519 signature prefixed to canonical bytes."""
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+SEAL_SIGNATURE_LEN = 64
+"""Length in bytes of the Ed25519 signature prefix on a sealed envelope."""
+
+
+class SigningKey:
+    """An Ed25519 signing key.
+
+    Each production connector holds its own; Ajar registers the matching
+    verifying key in the connector's profile. The golden-vector seed (32 x
+    0x47) is a published TEST seed — never sign production events with it.
+    """
+
+    def __init__(self, key: Ed25519PrivateKey) -> None:
+        self._key = key
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> "SigningKey":
+        """Derive a key from a 32-byte seed."""
+        if len(seed) != 32:
+            raise ValueError(f"signing seed must be 32 bytes, got {len(seed)}")
+        return cls(Ed25519PrivateKey.from_private_bytes(seed))
+
+    @property
+    def verifying_key(self) -> bytes:
+        """The 32-byte Ed25519 public (verifying) key."""
+        return self._key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+
+    def sign(self, data: bytes) -> bytes:
+        """Return the 64-byte detached signature over ``data``."""
+        return self._key.sign(data)
+
+
+def seal(canonical: bytes, key: SigningKey) -> bytes:
+    """Seal canonical bytes: ``sign(key, canonical) ++ canonical``.
+
+    The verifier splits at :data:`SEAL_SIGNATURE_LEN`, checks the signature over
+    the remainder with the connector's registered verifying key, and recovers
+    the canonical event from the suffix.
+    """
+    return key.sign(canonical) + canonical
+
+
+class SealVerificationError(Exception):
+    """A sealed envelope was not accepted."""
+
+
+def verify(sealed: bytes, verifying_key: bytes) -> bytes:
+    """Verify a sealed envelope and return the canonical bytes it carries.
+
+    The inverse of :func:`seal`, and the whole trust model in one call: it
+    answers whether these exact bytes were sealed by the holder of
+    ``verifying_key`` and are unaltered since. A recipient holding a
+    connector's registered verifying key can establish provenance without the
+    connector, the broker or Ajar Core being present or trusted.
+
+    ``verifying_key`` is the 32-byte raw Ed25519 public key, as published in the
+    connector's profile.
+
+    Raises :class:`SealVerificationError` if the envelope is too short, the key
+    is not a valid Ed25519 public key, or the signature does not verify.
+    """
+    if len(verifying_key) != 32:
+        raise SealVerificationError(
+            f"verifying key must be 32 bytes, got {len(verifying_key)}"
+        )
+    if len(sealed) < SEAL_SIGNATURE_LEN:
+        raise SealVerificationError(
+            f"sealed envelope is {len(sealed)} bytes, shorter than the "
+            f"{SEAL_SIGNATURE_LEN}-byte signature"
+        )
+    signature, canonical = sealed[:SEAL_SIGNATURE_LEN], sealed[SEAL_SIGNATURE_LEN:]
+    try:
+        Ed25519PublicKey.from_public_bytes(verifying_key).verify(signature, canonical)
+    except InvalidSignature as exc:
+        raise SealVerificationError(
+            "signature did not verify under the given key"
+        ) from exc
+    except ValueError as exc:
+        raise SealVerificationError(f"invalid verifying key: {exc}") from exc
+    return canonical

ajar_connector-0.5.3/ajar_connector.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: ajar-connector
+Version: 0.5.3
+Summary: Python SDK for building byte-compatible connectors to the Ajar integration plane.
+Author: Ajar connectors contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/promaka/ajar-connectors
+Project-URL: Documentation, https://github.com/promaka/ajar-connectors/blob/main/docs/embedding-python.md
+Project-URL: Wire contract, https://github.com/promaka/ajar-connectors/blob/main/docs/wire-contract-v1.md
+Project-URL: Source, https://github.com/promaka/ajar-connectors
+Project-URL: Changelog, https://github.com/promaka/ajar-connectors/blob/main/CHANGELOG.md
+Keywords: ajar,connector,defence,interoperability,protobuf,ed25519
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: protobuf<8,>=7.35
+Requires-Dist: cryptography>=42
+Provides-Extra: examples
+Requires-Dist: nats-py>=2.6; extra == "examples"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# ajar-connector (Python)
+
+The Python SDK for building byte-compatible connectors to Ajar. Types are
+generated from the same vendored `event.proto` as the Rust/Go/C++ SDKs, so this
+SDK reproduces the **same** golden vectors.
+
+## Try the template in 10 seconds
+
+```bash
+cd python
+pip install -e .                     # or: pip install protobuf cryptography
+echo '{"lat":26.4,"lon":50.9,"alt_m":11000,"quality":0.9}' \
+  | PYTHONPATH=. python examples/connector_template.py --dry-run
+# -> 019e... -> ajar.ingest.demo-connector (196 sealed bytes)  [dry-run]
+```
+
+You just built and signed a canonical Ajar event. To make it yours, edit the one
+function marked `EDIT` in [examples/connector_template.py](examples/connector_template.py).
+
+## Use it in code
+
+```python
+from ajar_connector import EventBuilder, canonical_bytes, seal, SigningKey
+
+event = (
+    EventBuilder("acme-radar-1", "mim:aircraft")
+    .new_id().now()
+    .location(26.4, 50.9, 11000.0)
+    .confidence(0.94)
+    .build()
+)
+sealed = seal(canonical_bytes(event), SigningKey.from_seed(my_seed))  # 64-byte sig ++ canonical
+```
+
+## Run the checks
+
+```bash
+cd python
+python -m pytest                                   # unit tests
+PYTHONPATH=. python conformance/golden_vectors.py   # the byte-compat gate
+```
+
+## Streaming example
+
+```bash
+pip install -e ".[examples]"                        # adds nats-py
+PYTHONPATH=. python examples/synthetic_radar.py      # publish to a local Core
+PYTHONPATH=. python examples/synthetic_radar.py --dry-run --ticks 3   # no infra
+```
+
+See the full [onboarding guide](../ONBOARDING.md) for data flow, deployment
+topology, key generation, and troubleshooting.
+
+> The conformance gate and `--dry-run` need only `protobuf` + `cryptography`.
+> `nats-py` is an `examples` extra, kept out of the SDK's core dependencies.

ajar_connector-0.5.3/ajar_connector.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+ajar_connector/__init__.py
+ajar_connector/builder.py
+ajar_connector/canonical.py
+ajar_connector/connector.py
+ajar_connector/event_pb2.py
+ajar_connector/profile.py
+ajar_connector/seal.py
+ajar_connector.egg-info/PKG-INFO
+ajar_connector.egg-info/SOURCES.txt
+ajar_connector.egg-info/dependency_links.txt
+ajar_connector.egg-info/requires.txt
+ajar_connector.egg-info/top_level.txt
+tests/test_sdk.py

ajar_connector-0.5.3/ajar_connector.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ajar_connector-0.5.3/ajar_connector.egg-info/requires.txt

@@ -0,0 +1,8 @@
+protobuf<8,>=7.35
+cryptography>=42
+
+[dev]
+pytest>=8
+
+[examples]
+nats-py>=2.6

ajar_connector-0.5.3/ajar_connector.egg-info/top_level.txt

@@ -0,0 +1 @@
+ajar_connector

ajar_connector-0.5.3/pyproject.toml

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: Apache-2.0
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ajar-connector"
+version = "0.5.3"
+description = "Python SDK for building byte-compatible connectors to the Ajar integration plane."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Ajar connectors contributors" }]
+keywords = ["ajar", "connector", "defence", "interoperability", "protobuf", "ed25519"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Networking",
+]
+
+dependencies = [
+    "protobuf>=7.35,<8",
+    "cryptography>=42",
+]
+
+[project.urls]
+Homepage = "https://github.com/promaka/ajar-connectors"
+Documentation = "https://github.com/promaka/ajar-connectors/blob/main/docs/embedding-python.md"
+"Wire contract" = "https://github.com/promaka/ajar-connectors/blob/main/docs/wire-contract-v1.md"
+Source = "https://github.com/promaka/ajar-connectors"
+Changelog = "https://github.com/promaka/ajar-connectors/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+# Transport for the example connectors — kept OUT of the SDK's core deps.
+examples = ["nats-py>=2.6"]
+dev = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ajar_connector*"]
+
+[tool.pytest.ini_options]
+# Make ajar_connector importable from the repo without an install step.
+pythonpath = ["."]
+testpaths = ["tests"]

ajar_connector-0.5.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ajar_connector-0.5.3/tests/test_sdk.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the builder, seal, and profile (run with pytest)."""
+
+import pytest
+
+from ajar_connector import (
+    SEAL_SIGNATURE_LEN,
+    BuildError,
+    canonical_bytes,
+    ConnectorProfile,
+    EventBuilder,
+    SigningKey,
+    seal,
+    SealVerificationError,
+    verify,
+)
+
+
+def test_builder_sorts_attributes_and_sets_defaults():
+    e = (
+        EventBuilder("sensor-1", "mim:drone")
+        .new_id()
+        .now()
+        .attribute("speed", "110")
+        .attribute("heading", "225")
+        .build()
+    )
+    assert e.schema_version == "v1"
+    assert e.received_at == ""
+    assert [a.key for a in e.attributes] == ["heading", "speed"]
+
+
+def test_builder_rejects_duplicate_attribute_keys():
+    with pytest.raises(BuildError, match="duplicate attribute key"):
+        EventBuilder("sensor-1", "mim:drone").new_id().now().attribute(
+            "heading", "225"
+        ).attribute("heading", "226").build()
+
+
+def test_builder_requires_id_and_timestamp():
+    with pytest.raises(BuildError, match="missing required field: id"):
+        EventBuilder("sensor-1", "mim:drone").build()
+
+
+def test_builder_rejects_out_of_range_confidence():
+    with pytest.raises(BuildError, match="confidence"):
+        EventBuilder("sensor-1", "mim:drone").new_id().now().confidence(1.5).build()
+
+
+def test_builder_enforces_namespacing_with_opt_out():
+    with pytest.raises(BuildError, match="not namespaced"):
+        EventBuilder("sensor-1", "drone").new_id().now().build()
+    # opt-out builds fine
+    EventBuilder("sensor-1", "drone").new_id().now().allow_unnamespaced_entity_type().build()
+
+
+def test_seal_layout():
+    key = SigningKey.from_seed(bytes([0x47]) * 32)
+    canonical = b"hello ajar"
+    sealed = seal(canonical, key)
+    assert len(sealed) == SEAL_SIGNATURE_LEN + len(canonical)
+    assert sealed[SEAL_SIGNATURE_LEN:] == canonical
+
+
+def test_profile_json_serializes_verifying_key_as_hex():
+    vk = SigningKey.from_seed(bytes([0x47]) * 32).verifying_key
+    profile = (
+        ConnectorProfile("sensor-123", vk)
+        .allow_entity_type("mim:drone")
+        .rate_limit(50, 5.0)
+    )
+    js = profile.to_json()
+    assert '"source_id":"sensor-123"' in js
+    assert "mim:drone" in js
+    assert vk.hex() in js
+    assert '"rate_refill_per_sec":5.0' in js  # float keeps the .0, like the other SDKs
+
+
+def test_verify_round_trips_and_returns_canonical_bytes():
+    key = SigningKey.from_seed(bytes([0x47] * 32))
+    event = EventBuilder("acme-radar-1", "mim:aircraft").new_id().now().build()
+    canonical = canonical_bytes(event)
+    assert verify(seal(canonical, key), key.verifying_key) == canonical
+
+
+def test_verify_rejects_tampering_wrong_key_and_truncation():
+    key = SigningKey.from_seed(bytes([0x47] * 32))
+    other = SigningKey.from_seed(bytes([0x11] * 32))
+    sealed = seal(canonical_bytes(
+        EventBuilder("acme-radar-1", "mim:aircraft").new_id().now().build()
+    ), key)
+
+    tampered = bytearray(sealed)
+    tampered[-1] ^= 0x01
+    with pytest.raises(SealVerificationError):
+        verify(bytes(tampered), key.verifying_key)
+
+    with pytest.raises(SealVerificationError):
+        verify(sealed, other.verifying_key)
+
+    with pytest.raises(SealVerificationError):
+        verify(sealed[: SEAL_SIGNATURE_LEN - 1], key.verifying_key)
+
+    with pytest.raises(SealVerificationError):
+        verify(sealed, b"too-short-key")