ecosemantic-relay 0.1.14__tar.gz

ecosemantic_relay-0.1.14/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+.cache/
+build/
+node_modules/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.json
+htmlcov/
+
+.env
+.env.*
+!.env.example
+
+.DS_Store
+graphify-out
+knowledge/
+.okf-cache.json
+**/ecosemantic/view/static/
+
+installer/windows/defines.iss
+
+/payload/

ecosemantic_relay-0.1.14/LICENSE

@@ -0,0 +1,73 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

ecosemantic_relay-0.1.14/NOTICE

@@ -0,0 +1,13 @@
+EcoSemantic
+Required Notice: Copyright 2026 Carlos Gaete-Morales (https://github.com/cdgaete/ecosemantic)
+
+EcoSemantic is licensed under the PolyForm Noncommercial License 1.0.0, in LICENSE
+and at https://polyformproject.org/licenses/noncommercial/1.0.0. Any noncommercial
+purpose is permitted. Commercial use needs a separate licence from Carlos
+Gaete-Morales: cdgaete@gmail.com.
+
+The page that ecosemantic-view carries bundles third-party software under its
+own licences; their notices are in ecosemantic/view/static/THIRD_PARTY_NOTICES.txt
+inside that distribution. Components of the page adapt shadcn/ui, Copyright (c)
+2023 shadcn, under the MIT licence, as page/PROVENANCE.md in the source
+repository records.

ecosemantic_relay-0.1.14/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.5
+Name: ecosemantic-relay
+Version: 0.1.14
+Summary: The EcoSemantic bridge tunnel: its messages, its frames, the bridge's discovery document and the Ed25519 proof a bridged request carries.
+Project-URL: Homepage, https://github.com/cdgaete/ecosemantic
+Project-URL: Repository, https://github.com/cdgaete/ecosemantic
+Project-URL: Issues, https://github.com/cdgaete/ecosemantic/issues
+Project-URL: Changelog, https://github.com/cdgaete/ecosemantic/blob/main/CHANGELOG.md
+Author-email: Carlos Gaete-Morales <cdgaete@gmail.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: Ed25519,LCA,bridge,life cycle assessment,tunnel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cryptography<51,>=44
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyjwt[crypto]<3,>=2.10
+Description-Content-Type: text/markdown
+
+`ecosemantic-relay` holds the tunnel between a hosted bridge and an engine: the messages its text frames carry — the engine's hello, the bridge's welcome, a request's and a response's start, and a stream's reset — the binary frames that carry a stream's body in chunks of at most 64 KiB, the document the bridge publishes at its well-known address with what an engine registers and is registered as, and the Ed25519 proof a bridged request carries with the JWKs the bridge publishes to check it. The bridge service imports it for both sides of the tunnel, and `ecosemantic` depends on it for `ecosemantic serve --bridge`.

ecosemantic_relay-0.1.14/README.md

@@ -0,0 +1 @@
+`ecosemantic-relay` holds the tunnel between a hosted bridge and an engine: the messages its text frames carry — the engine's hello, the bridge's welcome, a request's and a response's start, and a stream's reset — the binary frames that carry a stream's body in chunks of at most 64 KiB, the document the bridge publishes at its well-known address with what an engine registers and is registered as, and the Ed25519 proof a bridged request carries with the JWKs the bridge publishes to check it. The bridge service imports it for both sides of the tunnel, and `ecosemantic` depends on it for `ecosemantic serve --bridge`.

ecosemantic_relay-0.1.14/ecosemantic/relay/__init__.py

@@ -0,0 +1,3 @@
+"""The tunnel's messages, frames, discovery document and proof."""
+
+from __future__ import annotations

ecosemantic_relay-0.1.14/ecosemantic/relay/discovery.py

@@ -0,0 +1,50 @@
+"""What the bridge publishes at its well-known address, and what an engine registers as and is
+registered with."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+WELL_KNOWN = "/.well-known/ecosemantic-bridge"
+
+
+class _Document(BaseModel):
+    """One document of the bridge's discovery, frozen: what the bridge answers and what an engine
+    sends it."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class BridgeConfiguration(_Document):
+    """The bridge's discovery document: the issuer, the browser's and the device's client ids, the
+    tunnel's resource, scope and address, and the connector's and the registration's addresses."""
+
+    issuer: str
+    browser_client_id: str
+    device_client_id: str
+    tunnel_resource: str
+    tunnel_scope: str
+    tunnel_url: str
+    connector_url: str
+    registration_url: str
+
+
+class Registration(_Document):
+    """What an engine registers: itself when it has an id, the name it answers to and its
+    version."""
+
+    engine: UUID | None
+    name: str
+    version: str
+
+
+class Registered(_Document):
+    """What the bridge answers a registration with: the engine, its account, its handle and the
+    page's address."""
+
+    engine: UUID
+    account: str
+    handle: str
+    page_url: str

ecosemantic_relay-0.1.14/ecosemantic/relay/errors.py

@@ -0,0 +1,11 @@
+"""The relay's typed errors: text, a frame or a proof it cannot accept."""
+
+from __future__ import annotations
+
+
+class RelayError(ValueError):
+    """The tunnel carries something the protocol does not define, or not the thing it defines."""
+
+
+class ProofRefused(RelayError):
+    """A bridged request's proof does not admit the request; the message names the fault."""

ecosemantic_relay-0.1.14/ecosemantic/relay/frames.py

@@ -0,0 +1,45 @@
+"""The tunnel's binary frames: a stream's body in chunks of at most 64 KiB, each frame carrying its
+stream and whether it ends it."""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from ecosemantic.relay.errors import RelayError
+
+CHUNK_BYTES = 65536
+_HEADER = struct.Struct(">IB")
+
+
+@dataclass(frozen=True)
+class Chunk:
+    """One frame of a stream's body: its stream, its bytes, and whether it is the last."""
+
+    stream: int
+    data: bytes
+    end: bool
+
+
+def pack(chunk: Chunk) -> bytes:
+    """The binary frame that carries the chunk: its stream, the bit that ends it, then its body."""
+    return _HEADER.pack(chunk.stream, 1 if chunk.end else 0) + chunk.data
+
+
+def unpack(frame: bytes) -> Chunk:
+    """The chunk a binary frame carries, refused when the frame is shorter than its header."""
+    if len(frame) < _HEADER.size:
+        raise RelayError(
+            f"a frame of {len(frame)} bytes is shorter than its {_HEADER.size}-byte header"
+        )
+    stream, flags = _HEADER.unpack_from(frame)
+    return Chunk(stream=stream, data=frame[_HEADER.size :], end=bool(flags & 1))
+
+
+def chunks(stream: int, data: bytes, end: bool) -> list[Chunk]:
+    """A stream's body split at 64 KiB, the last chunk alone carrying whether it ends the stream."""
+    pieces = [data[at : at + CHUNK_BYTES] for at in range(0, len(data), CHUNK_BYTES)] or [b""]
+    last = len(pieces) - 1
+    return [
+        Chunk(stream=stream, data=piece, end=end and at == last) for at, piece in enumerate(pieces)
+    ]

ecosemantic_relay-0.1.14/ecosemantic/relay/messages.py

@@ -0,0 +1,102 @@
+"""The tunnel's text messages: the opening exchange, a request's and a response's start, and a
+stream's reset, each carried as one JSON document."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+
+from ecosemantic.relay.errors import RelayError
+
+PROTOCOL = 1
+Door = Literal["mcp", "page"]
+ResetReason = Literal["cancelled", "failed"]
+Header = tuple[str, str]
+
+
+class _Message(BaseModel):
+    """One message of the tunnel, frozen: what a text frame carries."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class Hello(_Message):
+    """The engine opens the tunnel: the protocol it speaks, itself and the version it runs."""
+
+    type: Literal["hello"] = "hello"
+    protocol: int
+    engine: UUID
+    version: str
+
+
+class Welcome(_Message):
+    """The bridge answers: the protocol, the engine and its account, the handle it answers to, the
+    moment of the exchange and the keys a bridged request's proof is checked against."""
+
+    type: Literal["welcome"] = "welcome"
+    protocol: int
+    engine: UUID
+    account: str
+    handle: str
+    now: datetime
+    keys: list[dict[str, str]]
+
+
+class RequestStart(_Message):
+    """A request opens a stream: its door, its method, path and query, its headers and the proof
+    that admits it."""
+
+    type: Literal["request"] = "request"
+    stream: int = Field(ge=1)
+    door: Door
+    method: str
+    path: str
+    query: str
+    headers: list[Header]
+    proof: str
+
+
+class ResponseStart(_Message):
+    """The engine answers a stream: the status and headers of the response its body follows."""
+
+    type: Literal["response"] = "response"
+    stream: int
+    status: int
+    headers: list[Header]
+
+
+class Reset(_Message):
+    """A stream ends without its answer: the reason it was cancelled or failed."""
+
+    type: Literal["reset"] = "reset"
+    stream: int
+    reason: ResetReason
+
+
+Message = Annotated[
+    Hello | Welcome | RequestStart | ResponseStart | Reset, Field(discriminator="type")
+]
+
+_ADAPTER: TypeAdapter[Message] = TypeAdapter(Message)
+
+
+def encode(message: Message) -> str:
+    """The text frame that carries the message."""
+    return _ADAPTER.dump_json(message).decode("utf-8")
+
+
+def decode(text: str) -> Message:
+    """The message a text frame carries, refused when the text is no message of this protocol."""
+    try:
+        return _ADAPTER.validate_json(text)
+    except ValidationError as error:
+        raise RelayError(f"no message of protocol {PROTOCOL} in {text!r}: {error}") from error
+
+
+def door_of(path: str) -> Door:
+    """The door a request's path belongs to: the chats' for `/mcp` and its subpaths, the page's for
+    every other path."""
+    return "mcp" if path == "/mcp" or path.startswith("/mcp/") else "page"

ecosemantic_relay-0.1.14/ecosemantic/relay/proof.py

@@ -0,0 +1,154 @@
+"""The Ed25519 proof a bridged request carries, and the JWKs the bridge's welcome publishes to check
+it."""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+from jwt.types import Options
+
+from ecosemantic.relay.errors import ProofRefused
+from ecosemantic.relay.messages import Door
+
+PROOF_SECONDS = 60
+_ALGORITHM = "EdDSA"
+_CLAIMS: Options = {
+    "verify_exp": False,
+    "verify_aud": False,
+    "verify_iss": False,
+    "verify_jti": False,
+}
+
+
+@dataclass(frozen=True)
+class Proof:
+    """What a verified proof admits: the account, the engine, the door and its expiry."""
+
+    account: str
+    engine: UUID
+    door: Door
+    expires: datetime
+
+
+def public_jwk(key: Ed25519PublicKey, kid: str) -> dict[str, str]:
+    """The JWK a welcome carries for this key: its raw public bytes under the key's id."""
+    raw = key.public_bytes(encoding=Encoding.Raw, format=PublicFormat.Raw)
+    return {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii"),
+        "kid": kid,
+        "alg": _ALGORITHM,
+        "use": "sig",
+    }
+
+
+def mint_proof(
+    key: Ed25519PrivateKey,
+    kid: str,
+    issuer: str,
+    account: str,
+    engine: UUID,
+    door: Door,
+    now: datetime,
+) -> str:
+    """The token that admits one bridged request: the account, the engine and the door it names,
+    its own id, expiring 60 seconds after `now`."""
+    issued = int(now.timestamp())
+    return jwt.encode(
+        {
+            "iss": issuer,
+            "sub": account,
+            "aud": str(engine),
+            "door": door,
+            "iat": issued,
+            "exp": issued + PROOF_SECONDS,
+            "jti": uuid4().hex,
+        },
+        key,
+        algorithm=_ALGORITHM,
+        headers={"kid": kid},
+    )
+
+
+def verify_proof(
+    token: str,
+    keys: Sequence[Mapping[str, str]],
+    issuer: str,
+    account: str,
+    engine: UUID,
+    door: Door,
+    now: datetime,
+) -> Proof:
+    """What the proof admits. Refused when no key of the welcome carries the id it names, when its
+    signature is not that key's, when it names another issuer, account, engine or door, when it
+    carries no id of its own, or once `now` reaches its expiry."""
+    kid = _header(token).get("kid")
+    key = next((candidate for candidate in keys if candidate.get("kid") == kid), None)
+    if key is None:
+        raise ProofRefused(f"no key of the welcome carries the id {kid!r}")
+    claims = _claims(token, _public(key))
+    if claims.get("iss") != issuer:
+        raise ProofRefused(f"the proof is issued by {claims.get('iss')!r}, not {issuer!r}")
+    if claims.get("sub") != account:
+        raise ProofRefused(f"the proof names the account {claims.get('sub')!r}, not {account!r}")
+    if claims.get("aud") != str(engine):
+        raise ProofRefused(f"the proof names the engine {claims.get('aud')!r}, not {engine}")
+    if claims.get("door") != door:
+        raise ProofRefused(f"the proof names the door {claims.get('door')!r}, not {door!r}")
+    jti = claims.get("jti")
+    if not isinstance(jti, str) or not jti:
+        raise ProofRefused(f"the proof carries no jti, only {jti!r}")
+    expires = _moment(claims, "exp")
+    if expires <= now:
+        raise ProofRefused(
+            f"the proof expires at {expires.isoformat()}, not after {now.isoformat()}"
+        )
+    return Proof(account=account, engine=engine, door=door, expires=expires)
+
+
+def _header(token: str) -> Mapping[str, object]:
+    """The unverified header of a token, refused when the text is no token."""
+    try:
+        return jwt.get_unverified_header(token)
+    except jwt.InvalidTokenError as error:
+        raise ProofRefused(f"the proof is no token: {error}") from error
+
+
+def _public(key: Mapping[str, str]) -> Ed25519PublicKey:
+    """The Ed25519 key a JWK of the welcome carries, refused when it carries none."""
+    try:
+        return Ed25519PublicKey.from_public_bytes(_raw(key["x"]))
+    except (KeyError, ValueError) as error:
+        raise ProofRefused(f"the key {key.get('kid')!r} is no Ed25519 public key") from error
+
+
+def _raw(encoded: str) -> bytes:
+    """The bytes a base64url value of a JWK stands for."""
+    return base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4))
+
+
+def _claims(token: str, key: Ed25519PublicKey) -> Mapping[str, object]:
+    """What a token claims once its signature is the key's; the clock and the claims it names are
+    checked by the caller."""
+    try:
+        return jwt.decode(token, key, algorithms=[_ALGORITHM], options=_CLAIMS)
+    except jwt.InvalidSignatureError as error:
+        raise ProofRefused("the signature is not the key's") from error
+    except jwt.InvalidTokenError as error:
+        raise ProofRefused(f"the proof cannot be read: {error}") from error
+
+
+def _moment(claims: Mapping[str, object], name: str) -> datetime:
+    """The moment a claim carries, in seconds, refused when the claim carries none."""
+    value = claims.get(name)
+    if not isinstance(value, int | float) or isinstance(value, bool):
+        raise ProofRefused(f"the proof carries no numeric {name}")
+    return datetime.fromtimestamp(value, UTC)

ecosemantic_relay-0.1.14/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "ecosemantic-relay"
+version = "0.1.14"
+description = "The EcoSemantic bridge tunnel: its messages, its frames, the bridge's discovery document and the Ed25519 proof a bridged request carries."
+requires-python = ">=3.12"
+license = "PolyForm-Noncommercial-1.0.0"
+license-files = ["LICENSE", "NOTICE"]
+readme = "README.md"
+authors = [{ name = "Carlos Gaete-Morales", email = "cdgaete@gmail.com" }]
+keywords = ["life cycle assessment", "LCA", "bridge", "tunnel", "Ed25519"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7,<3",
+    "pyjwt[crypto]>=2.10,<3",
+    "cryptography>=44,<51",
+]
+
+[project.urls]
+Homepage = "https://github.com/cdgaete/ecosemantic"
+Repository = "https://github.com/cdgaete/ecosemantic"
+Issues = "https://github.com/cdgaete/ecosemantic/issues"
+Changelog = "https://github.com/cdgaete/ecosemantic/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ecosemantic"]