pamoja-session 0.1.18__tar.gz

pamoja_session-0.1.18/.gitignore

@@ -0,0 +1,13 @@
+# Native extensions are built per platform, not committed.
+*.so
+*.pyd
+*.dylib
+
+# Build and packaging output.
+dist/
+wheels/
+target/
+
+# Local virtual environments.
+.venv/
+venv/

pamoja_session-0.1.18/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pamoja_session-0.1.18/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: pamoja-session
+Version: 0.1.18
+Summary: X25519 key agreement, HKDF, and ChaCha20-Poly1305 with an anti-replay window, with no TLS stack.
+Project-URL: Repository, https://github.com/molexxxx/pamoja
+Project-URL: Documentation, https://pamoja.molex.cloud/docs/guides/session.html
+Author: molexxxx
+License: MIT
+License-File: LICENSE-MIT
+Keywords: iot,pamoja,robotics,session
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pamoja-native==0.1.18
+Description-Content-Type: text/markdown
+
+# pamoja-session
+
+X25519 key agreement, HKDF, and ChaCha20-Poly1305 with an anti-replay window, with no TLS stack. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/session.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/session.html)
+
+## Install
+
+```sh
+pip install pamoja-session
+```
+
+```python
+from pamoja import session
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/session.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/session.py):
+
+```python
+import os
+
+from pamoja.core import PamojaError
+from pamoja.session import AgreementKey, Role, Session
+
+# Each device is provisioned with a 32-byte seed and publishes the key it derives. A real
+# seed comes from the factory or a secure element; any 32 bytes stand in here.
+node = AgreementKey(bytes([7]) * 32)
+gateway = AgreementKey(bytes([9]) * 32)
+
+# Neither side sends the session key. Both derive it from the shared secret, a salt that
+# travels in the clear, and both public keys, with opposite roles.
+#
+# The salt must be fresh for every session: reusing one derives the same key from the same
+# pair of devices twice. The initiator draws it and sends it in the clear, so the responder
+# uses the salt it received rather than one of its own.
+salt = os.urandom(16)
+uplink = Session(node, gateway.public_key, salt, Role.INITIATOR)
+downlink = Session(gateway, node.public_key, salt, Role.RESPONDER)
+print("both sides derived a key without sending one")
+
+# The pump id is authenticated but not encrypted, so a router still reads it while any
+# change to it fails the tag.
+sealed = uplink.seal(b"flow=41.2", b"pump-3")
+print(f"sealed    the reading is no longer readable: {sealed.ciphertext != b'flow=41.2'}")
+print(f"opened    {downlink.open(sealed, b'pump-3').decode()}")
+
+# The anti-replay window refuses a counter it has already accepted, so a frame captured
+# off the air and sent again is not delivered a second time.
+try:
+    downlink.open(sealed, b"pump-3")
+    print("a replayed frame was accepted, which should never happen")
+except PamojaError as error:
+    print(f"replay    refused: {error}")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-session`](https://crates.io/crates/pamoja-session) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_session/index.html), [docs.rs](https://docs.rs/pamoja-session), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-session) |
+| TypeScript | [`@pamoja/session`](https://www.npmjs.com/package/@pamoja/session) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_session.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-session) |
+| Python | [`pamoja-session`](https://pypi.org/project/pamoja-session/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/session.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-session) |
+| C# | [`Pamoja.Session`](https://www.nuget.org/packages/Pamoja.Session) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Session.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-session) |
+
+## Documentation
+
+- [`pamoja.session` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/session.html), every class and function in this module.
+- [The Secured session guide](https://pamoja.molex.cloud/docs/guides/session.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_session-0.1.18/README.md

@@ -0,0 +1,81 @@
+# pamoja-session
+
+X25519 key agreement, HKDF, and ChaCha20-Poly1305 with an anti-replay window, with no TLS stack. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/session.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/session.html)
+
+## Install
+
+```sh
+pip install pamoja-session
+```
+
+```python
+from pamoja import session
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/session.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/session.py):
+
+```python
+import os
+
+from pamoja.core import PamojaError
+from pamoja.session import AgreementKey, Role, Session
+
+# Each device is provisioned with a 32-byte seed and publishes the key it derives. A real
+# seed comes from the factory or a secure element; any 32 bytes stand in here.
+node = AgreementKey(bytes([7]) * 32)
+gateway = AgreementKey(bytes([9]) * 32)
+
+# Neither side sends the session key. Both derive it from the shared secret, a salt that
+# travels in the clear, and both public keys, with opposite roles.
+#
+# The salt must be fresh for every session: reusing one derives the same key from the same
+# pair of devices twice. The initiator draws it and sends it in the clear, so the responder
+# uses the salt it received rather than one of its own.
+salt = os.urandom(16)
+uplink = Session(node, gateway.public_key, salt, Role.INITIATOR)
+downlink = Session(gateway, node.public_key, salt, Role.RESPONDER)
+print("both sides derived a key without sending one")
+
+# The pump id is authenticated but not encrypted, so a router still reads it while any
+# change to it fails the tag.
+sealed = uplink.seal(b"flow=41.2", b"pump-3")
+print(f"sealed    the reading is no longer readable: {sealed.ciphertext != b'flow=41.2'}")
+print(f"opened    {downlink.open(sealed, b'pump-3').decode()}")
+
+# The anti-replay window refuses a counter it has already accepted, so a frame captured
+# off the air and sent again is not delivered a second time.
+try:
+    downlink.open(sealed, b"pump-3")
+    print("a replayed frame was accepted, which should never happen")
+except PamojaError as error:
+    print(f"replay    refused: {error}")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-session`](https://crates.io/crates/pamoja-session) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_session/index.html), [docs.rs](https://docs.rs/pamoja-session), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-session) |
+| TypeScript | [`@pamoja/session`](https://www.npmjs.com/package/@pamoja/session) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_session.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-session) |
+| Python | [`pamoja-session`](https://pypi.org/project/pamoja-session/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/session.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-session) |
+| C# | [`Pamoja.Session`](https://www.nuget.org/packages/Pamoja.Session) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Session.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-session) |
+
+## Documentation
+
+- [`pamoja.session` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/session.html), every class and function in this module.
+- [The Secured session guide](https://pamoja.molex.cloud/docs/guides/session.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_session-0.1.18/pamoja/session/__init__.py

@@ -0,0 +1,112 @@
+"""Idiomatic secured-session facade.
+
+Two devices that already know each other's public keys can agree on a session key
+without ever sending it, and then exchange messages that are confidential, cannot
+be altered undetected, and cannot be replayed. That is the whole of what a small
+device usually needs from transport security, at a fraction of what a TLS stack
+costs it.
+"""
+
+from __future__ import annotations
+
+import enum
+
+from pamoja._native import AgreementKey, SealedMessage
+from pamoja._native import Session as _Session
+from pamoja._native import hkdf_sha256_expand as _hkdf_sha256
+from pamoja._native import hmac_sha256_digest as _hmac_sha256
+
+__all__ = [
+    "AgreementKey",
+    "Role",
+    "SealedMessage",
+    "Session",
+    "hkdf_sha256",
+    "hmac_sha256",
+]
+
+
+class Role(str, enum.Enum):
+    """Which side of a session a device is on.
+
+    The two devices must choose opposite roles: the role decides the order the
+    public keys are mixed in and which direction each side tags its messages
+    with, so a session where both sides claim the same role opens nothing.
+    """
+
+    #: The device that opens the session.
+    INITIATOR = "Initiator"
+    #: The device that answers.
+    RESPONDER = "Responder"
+
+
+class Session:
+    """A confidential, tamper-evident, replay-protected channel with one peer."""
+
+    def __init__(
+        self,
+        local: AgreementKey,
+        peer_public_key: bytes,
+        salt: bytes,
+        role: Role,
+    ) -> None:
+        """Establish a session with a peer.
+
+        :param local: This device's key-agreement secret.
+        :param peer_public_key: The peer's 32-byte public key, already
+            authenticated by pinning or by a signature.
+        :param salt: A fresh per-session salt both sides share, exchanged in the
+            clear. Reusing one with the same pair of keys reuses the session key,
+            so it must change each session.
+        :param role: Whether this device opens the session or answers.
+        """
+        self._inner = _Session(local, peer_public_key, salt, role.value)
+
+    def seal(self, plaintext: bytes, aad: bytes = b"") -> SealedMessage:
+        """Seal a message for the peer.
+
+        :param plaintext: The message to protect.
+        :param aad: Data authenticated but not encrypted, so it stays readable on
+            the wire yet cannot be altered: a device identifier or a routing
+            header belongs here.
+        :returns: The ciphertext, with the counter and tag to send beside it.
+        """
+        return self._inner.seal(plaintext, aad)
+
+    def open(self, sealed: SealedMessage, aad: bytes = b"") -> bytes:
+        """Open a message from the peer.
+
+        :param sealed: The ciphertext with the counter and tag that arrived with
+            it.
+        :param aad: The same associated data the sender authenticated.
+        :returns: The plaintext.
+        :raises PamojaError: When the counter repeats or is older than the replay
+            window still tracks, and when the tag does not authenticate. Nothing
+            readable is ever returned from a message that failed either check.
+        """
+        return self._inner.open(sealed, aad)
+
+
+def hmac_sha256(key: bytes, message: bytes) -> bytes:
+    """Compute a keyed hash over a message.
+
+    This is the primitive a host uses to authenticate a pairing exchange or a
+    single command, where a whole session would be more than the job needs.
+
+    :param key: The secret key.
+    :param message: The message to authenticate.
+    :returns: The 32-byte digest.
+    """
+    return _hmac_sha256(key, message)
+
+
+def hkdf_sha256(salt: bytes, ikm: bytes, info: bytes, length: int) -> bytes:
+    """Expand input keying material into ``length`` bytes bound to ``info``.
+
+    :param salt: The salt, which may be empty.
+    :param ikm: The input keying material.
+    :param info: Context binding the output to its purpose.
+    :param length: How many bytes to derive.
+    :returns: The derived bytes.
+    """
+    return _hkdf_sha256(salt, ikm, info, length)

pamoja_session-0.1.18/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pamoja-session"
+version = "0.1.18"
+description = "X25519 key agreement, HKDF, and ChaCha20-Poly1305 with an anti-replay window, with no TLS stack."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE-MIT"]
+requires-python = ">=3.10"
+authors = [{ name = "molexxxx" }]
+keywords = ["pamoja", "iot", "robotics", "session"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pamoja-native==0.1.18",
+]
+
+[project.urls]
+Repository = "https://github.com/molexxxx/pamoja"
+Documentation = "https://pamoja.molex.cloud/docs/guides/session.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pamoja"]