transwarpconduit 0.1.0__tar.gz

transwarpconduit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 transwarpconduit.com
+
+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.

transwarpconduit-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: transwarpconduit
+Version: 0.1.0
+Summary: Addressed, end-to-end encrypted messaging between agents. Four outcomes, no silence.
+Author-email: transwarp <hello@transwarpconduit.com>
+License-Expression: MIT
+Project-URL: Homepage, https://transwarpconduit.com
+Keywords: agents,messaging,mcp,end-to-end-encryption,ed25519
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=3.4.0
+Requires-Dist: websocket-client>=1.6
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == "mcp"
+Dynamic: license-file
+
+# transwarpconduit
+
+Addressed, end-to-end encrypted messaging between agents — and the people who
+run them. **Four outcomes, no silence.**
+
+```bash
+pip install transwarpconduit
+```
+
+> The import name is `transwarpconduit`, not `transwarp`. `transwarp` on PyPI
+> is an unrelated web framework last released in 2015; installing it will not
+> get you this.
+
+## What it is
+
+A message sent through transwarp resolves to an **address**:
+
+```
+twp://<tenant>/<space>/<local>        twp://acme/platform/alice
+```
+
+Every send ends in exactly one of four outcomes, and you are always told which:
+
+| outcome | meaning |
+|---|---|
+| `consumed` | someone read it |
+| `queued` | nobody is bound yet; it is held until its TTL |
+| `undeliverable` | the TTL expired, or the binding went stale. You are told. |
+| `refused` | it was rejected, and the reason is given |
+
+There is no fifth outcome and there is no silence. A refusal is an answer — an
+undelivered message and a message nobody sent look identical from the sender's
+side, and "nobody messaged me today" reads as a quiet day.
+
+## Sending and reading
+
+```bash
+twp --keyfile alice.key --nexus wss://nexus.transwarpconduit.com \
+    send --to twp://acme/platform/bob "first message"
+
+twp --keyfile bob.key --nexus wss://nexus.transwarpconduit.com inbox
+```
+
+Bodies are sealed to the recipient (X25519 + ChaCha20-Poly1305) and every
+envelope is signed (Ed25519). **The nexus cannot read your messages.** Neither
+can the web console — it has no body-viewing surface at all.
+
+Without a keyfile the client refuses to send rather than quietly sending in the
+clear; `--allow-cleartext` exists so that choosing it is a choice.
+
+## Provisioning an address
+
+Enrolment is signed by the **tenant key**, so it runs wherever that key is —
+not where the agent runs. An agent cannot vouch for itself; that is what makes
+enrolment checkable rather than trust-on-first-use.
+
+```bash
+twp-provision --tenant-key ./acme.root.key \
+  --addr twp://acme/platform/alice --out alice.key \
+  --nexus https://nexus.transwarpconduit.com
+```
+
+Pipe the key from a secret store (`--tenant-key -`) so it never lands on a
+disk. A file mode of 0600 separates a key from other Unix users and from
+nothing else — wherever several processes run as the same uid, read it as
+tidiness rather than as protection.
+
+## MCP server
+
+Injects arriving messages into a running agent session.
+
+```bash
+pip install "transwarpconduit[mcp]"
+TRANSWARP_ADDR=twp://acme/platform/alice python3 -m transwarpconduit.mcp_server
+```
+
+**Messages are untrusted input.** This service delivers text written by one
+party into another party's model context; the injector marks it as data rather
+than as instructions, and you should treat it that way too.
+
+## Requirements
+
+Python 3.9+. `cryptography` and `websocket-client` are required rather than
+optional, deliberately: a missing crypto dependency would surface as messages
+going out in the clear rather than as an error at install time.
+
+## Links
+
+- <https://transwarpconduit.com>

transwarpconduit-0.1.0/README.md

@@ -0,0 +1,89 @@
+# transwarpconduit
+
+Addressed, end-to-end encrypted messaging between agents — and the people who
+run them. **Four outcomes, no silence.**
+
+```bash
+pip install transwarpconduit
+```
+
+> The import name is `transwarpconduit`, not `transwarp`. `transwarp` on PyPI
+> is an unrelated web framework last released in 2015; installing it will not
+> get you this.
+
+## What it is
+
+A message sent through transwarp resolves to an **address**:
+
+```
+twp://<tenant>/<space>/<local>        twp://acme/platform/alice
+```
+
+Every send ends in exactly one of four outcomes, and you are always told which:
+
+| outcome | meaning |
+|---|---|
+| `consumed` | someone read it |
+| `queued` | nobody is bound yet; it is held until its TTL |
+| `undeliverable` | the TTL expired, or the binding went stale. You are told. |
+| `refused` | it was rejected, and the reason is given |
+
+There is no fifth outcome and there is no silence. A refusal is an answer — an
+undelivered message and a message nobody sent look identical from the sender's
+side, and "nobody messaged me today" reads as a quiet day.
+
+## Sending and reading
+
+```bash
+twp --keyfile alice.key --nexus wss://nexus.transwarpconduit.com \
+    send --to twp://acme/platform/bob "first message"
+
+twp --keyfile bob.key --nexus wss://nexus.transwarpconduit.com inbox
+```
+
+Bodies are sealed to the recipient (X25519 + ChaCha20-Poly1305) and every
+envelope is signed (Ed25519). **The nexus cannot read your messages.** Neither
+can the web console — it has no body-viewing surface at all.
+
+Without a keyfile the client refuses to send rather than quietly sending in the
+clear; `--allow-cleartext` exists so that choosing it is a choice.
+
+## Provisioning an address
+
+Enrolment is signed by the **tenant key**, so it runs wherever that key is —
+not where the agent runs. An agent cannot vouch for itself; that is what makes
+enrolment checkable rather than trust-on-first-use.
+
+```bash
+twp-provision --tenant-key ./acme.root.key \
+  --addr twp://acme/platform/alice --out alice.key \
+  --nexus https://nexus.transwarpconduit.com
+```
+
+Pipe the key from a secret store (`--tenant-key -`) so it never lands on a
+disk. A file mode of 0600 separates a key from other Unix users and from
+nothing else — wherever several processes run as the same uid, read it as
+tidiness rather than as protection.
+
+## MCP server
+
+Injects arriving messages into a running agent session.
+
+```bash
+pip install "transwarpconduit[mcp]"
+TRANSWARP_ADDR=twp://acme/platform/alice python3 -m transwarpconduit.mcp_server
+```
+
+**Messages are untrusted input.** This service delivers text written by one
+party into another party's model context; the injector marks it as data rather
+than as instructions, and you should treat it that way too.
+
+## Requirements
+
+Python 3.9+. `cryptography` and `websocket-client` are required rather than
+optional, deliberately: a missing crypto dependency would surface as messages
+going out in the clear rather than as an error at install time.
+
+## Links
+
+- <https://transwarpconduit.com>

transwarpconduit-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "transwarpconduit"
+version = "0.1.0"
+description = "Addressed, end-to-end encrypted messaging between agents. Four outcomes, no silence."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+# THE LICENCE FILE IS INSIDE python/, NOT AT THE REPO ROOT, so it actually
+# ships. A LICENSE outside the packaging directory produces metadata that
+# claims a licence over an artefact carrying no licence text -- a real package
+# on PyPI is in exactly that state today. tools/check_package.py REQUIRES
+# LICENSE in both artefacts, so an artefact without the text now fails:
+# absence is invisible to a check that only lists what is permitted.
+license-files = ["LICENSE"]
+# NO `License :: OSI Approved :: MIT License` CLASSIFIER. PEP 639 superseded
+# them and current setuptools REFUSES THE BUILD if both are present, which is
+# the good kind of refusal -- two places to state a licence is two places for
+# them to disagree. The SPDX expression above is the single statement.
+authors = [{ name = "transwarp", email = "hello@transwarpconduit.com" }]
+keywords = ["agents", "messaging", "mcp", "end-to-end-encryption", "ed25519"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications",
+  "Topic :: Security :: Cryptography",
+]
+
+# BOTH ARE REQUIRED, NOT EXTRAS, AND THAT IS THE SECURITY POSTURE.
+#
+# The core is stdlib-only and every third-party import in the tree is lazy, so
+# the package imports fine without either of these. That is exactly the danger:
+# a missing dependency would surface as messages going out IN THE CLEAR rather
+# than as an ImportError at install time. "Sending unencrypted has to be chosen,
+# not defaulted into by omitting an argument" is the rule the CLI already
+# enforces with --allow-cleartext; making cryptography optional would let a
+# packaging decision quietly override it.
+dependencies = [
+  "cryptography>=3.4.0",   # Ed25519 signing, X25519 + ChaCha20-Poly1305 sealing
+  "websocket-client>=1.6", # the client transport. Sync, no event loop.
+]
+
+[project.optional-dependencies]
+# The MCP server, for injecting messages into a running agent session.
+mcp = ["mcp>=1.2.0"]
+
+[project.scripts]
+twp = "transwarpconduit.cli:main"
+twp-provision = "transwarpconduit.provision:main"
+
+[project.urls]
+Homepage = "https://transwarpconduit.com"
+# No Repository or Bug Tracker URL, and their absence is deliberate rather than
+# forgotten: the source lives on a private forge a customer cannot reach, and a
+# link that 404s is worse than no link. Add both the moment there is a public
+# mirror -- a package with no source link is harder to trust, and rightly.
+
+# AN ALLOW-LIST, NOT AN EXCLUDE LIST. `find` with an explicit `include` ships
+# what is named and nothing else. A default-exclude list fails OPEN, silently,
+# once, and permanently: PyPI never accepts a re-upload of a version, and a
+# yanked file is still downloadable. The repo root -- CLAUDE.md, tools/, tests/,
+# evidence/ -- is physically outside this directory as the first line of that
+# defence, and this is the second.
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["transwarpconduit*"]

transwarpconduit-0.1.0/setup.cfg

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

transwarpconduit-0.1.0/transwarpconduit/addressing.py

@@ -0,0 +1,80 @@
+"""Address parsing and validation.
+
+Implements WARP / Spec: address grammar and resolution. The rule that shapes
+this module: normalisation is a REFUSAL, not a fixup. Two spellings of one
+address that compare unequal is an authorisation bug, so we never lowercase or
+repair -- we reject and let the caller see the error.
+"""
+
+import re
+
+SEGMENT = r"[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?"
+LOCAL = r"(?:#|role:)?[a-z0-9](?:[a-z0-9_.-]{0,62}[a-z0-9])?|\*"
+
+_ADDR_RE = re.compile(rf"^twp://({SEGMENT})/({SEGMENT})/({LOCAL})$")
+
+RESERVED_LOCALS = frozenset({"_nexus", "_system", "_admin"})
+
+
+class AddressError(ValueError):
+    """An address was refused. Carries why, because 'invalid address' sends the
+    caller looking in the wrong place."""
+
+
+class Address:
+    """A parsed, validated address. Immutable and hashable so it can be a dict
+    key and a set member without anyone having to remember to normalise first."""
+
+    __slots__ = ("tenant", "space", "local", "_s")
+
+    def __init__(self, tenant: str, space: str, local: str):
+        self.tenant = tenant
+        self.space = space
+        self.local = local
+        self._s = f"twp://{tenant}/{space}/{local}"
+
+    @classmethod
+    def parse(cls, s: str) -> "Address":
+        if not isinstance(s, str):
+            raise AddressError(f"address must be a string, got {type(s).__name__}")
+        if s != s.lower():
+            # Deliberately not s.lower(). See module docstring.
+            raise AddressError(
+                f"address contains uppercase and is refused rather than folded: {s!r}"
+            )
+        if not s.isascii():
+            raise AddressError(
+                f"address contains non-ASCII; confusable characters in a routing "
+                f"identity are a homograph attack with delivery attached: {s!r}"
+            )
+        m = _ADDR_RE.match(s)
+        if not m:
+            raise AddressError(f"address does not match twp://<tenant>/<space>/<local>: {s!r}")
+        tenant, space, local = m.group(1), m.group(2), m.group(3)
+        if local in RESERVED_LOCALS:
+            raise AddressError(f"local part {local!r} is reserved for the service itself")
+        return cls(tenant, space, local)
+
+    @property
+    def is_group(self) -> bool:
+        """True for a group address: an explicit topic, a role, or the wildcard.
+        A group resolves to a SET OF ADDRESSES, which then each resolve to
+        bindings. It is the same lookup with one more hop, not a second
+        mechanism."""
+        return self.local.startswith("#") or self.local.startswith("role:") or self.local == "*"
+
+    @property
+    def space_key(self) -> tuple:
+        return (self.tenant, self.space)
+
+    def __str__(self) -> str:
+        return self._s
+
+    def __repr__(self) -> str:
+        return f"Address({self._s!r})"
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, Address) and self._s == other._s
+
+    def __hash__(self) -> int:
+        return hash(self._s)

transwarpconduit-0.1.0/transwarpconduit/auth.py

@@ -0,0 +1,113 @@
+"""Proving a bind. WARP-27.
+
+Before this, the nexus served whoever reached it: anyone could bind to any
+registered address and collect its mail. Enrollment (WARP-26) put signing keys
+on file, which is what makes a proof possible -- an assertion becomes a check.
+
+CHALLENGE-RESPONSE, and the shape of it matters:
+
+  - the NEXUS chooses the challenge. A challenge the binder picks is a
+    challenge the binder can pre-compute, which is the same defect as a frame
+    delimiter the sender chooses (WARP-19). Twice now, in unrelated places, the
+    party being checked must not choose the thing they are checked against.
+  - a challenge is single-use and expires. Replay is otherwise free forever.
+  - the address is bound INTO the signed bytes, so a valid response for one
+    address cannot be presented for another -- the same reason a message
+    signature covers the header and not only the payload.
+  - no secret crosses the wire in either direction.
+
+AND IT REFUSES RATHER THAN DEGRADING. An address with no enrolled key cannot
+bind at all. "No key on file" must never quietly mean "no check performed":
+that is how a security control becomes a no-op that still reports success, and
+this project has already shipped one of those.
+"""
+
+import json
+import os
+import time
+
+from .errors import Refusal
+from .addressing import Address
+from .crypto import CryptoError, canon_json
+from .enroll import EnrollmentError, _verify_raw
+
+CHALLENGE_TTL_S = 60.0
+
+
+class AuthError(Refusal):
+    """A bind was refused. Distinct from an enrollment failure and from a
+    transport failure: this one means the caller could not prove who it is."""
+
+
+def challenge_input(addr: str, nonce: str, purpose: str = "bind") -> bytes:
+    """What the binder signs. The address travels inside it, so a response
+    collected for one address cannot be replayed against another."""
+    return canon_json({"p": purpose, "addr": addr, "n": nonce})
+
+
+class Authenticator:
+    """Issues challenges and checks responses. Holds no secrets -- only public
+    keys from the directory and the nonces it has issued."""
+
+    def __init__(self, directory, clock=time.time, ttl_s=CHALLENGE_TTL_S):
+        self._dir = directory
+        self._clock = clock
+        self._ttl = ttl_s
+        self._open = {}          # nonce -> {"addr", "issued"}
+
+    def challenge(self, addr) -> dict:
+        a = Address.parse(str(addr))
+        try:
+            self._dir.keys_of(str(a))
+        except EnrollmentError as e:
+            # Refuse at the FIRST step rather than issuing a challenge nobody
+            # can answer. An unenrolled address getting a challenge and then
+            # failing looks like a wrong key; refusing here says what is
+            # actually true.
+            raise AuthError(f"{a} is not enrolled, so a bind cannot be proven: {e}") from e
+        nonce = os.urandom(16).hex()
+        self._open[nonce] = {"addr": str(a), "issued": self._clock()}
+        return {"nonce": nonce, "addr": str(a), "expires_in_s": self._ttl}
+
+    def verify(self, nonce: str, signature_b64: str) -> str:
+        """Consume a challenge. Returns the proven address, or raises.
+
+        Single-use by construction: the nonce is removed before the signature
+        is checked, so a failed attempt cannot be retried against the same
+        challenge and a successful one cannot be replayed.
+        """
+        entry = self._open.pop(nonce, None)
+        if entry is None:
+            raise AuthError("unknown or already-used challenge")
+        if self._clock() - entry["issued"] > self._ttl:
+            raise AuthError("challenge expired")
+
+        keys = self._dir.keys_of(entry["addr"])
+        try:
+            ok = _verify_raw(keys["signing_pub"],
+                             challenge_input(entry["addr"], nonce),
+                             signature_b64)
+        except CryptoError as e:
+            raise AuthError(f"enrolled signing key is unusable: {e}") from e
+        if not ok:
+            raise AuthError(f"signature does not match the key enrolled for {entry['addr']}")
+        return entry["addr"]
+
+    def open_count(self) -> int:
+        """Outstanding challenges. Exposed because an unbounded pile of them is
+        a memory leak an attacker can drive, and a number nobody can see is a
+        number nobody will notice growing."""
+        return len(self._open)
+
+    def expire(self) -> int:
+        now = self._clock()
+        dead = [n for n, e in self._open.items() if now - e["issued"] > self._ttl]
+        for n in dead:
+            del self._open[n]
+        return len(dead)
+
+
+def respond(addr: str, nonce: str, signing_key) -> str:
+    """The binder's half. Signs the challenge with the address's enrolled key."""
+    from .crypto import _b64
+    return _b64(signing_key._sk.sign(challenge_input(str(addr), nonce)))