tibet-cmail 0.1.0__tar.gz

tibet_cmail-0.1.0/.gitignore

@@ -0,0 +1,193 @@
+# Secrets & env
+.env
+*.env
+*.secret
+
+# Keys & certs
+*.key
+*.pem
+certs/
+secrets/
+
+# Databases & dumps
+*.db
+*.sqlite
+*.sql
+dump_*/
+
+# EXCEPT: Allow database schemas (needed for server rebuild)
+!database-schemas/*.sql
+
+# Logs & runtime data
+logs/
+*.log
+__pycache__/
+*.pyc
+venv/
+.venv/
+**/venv/
+**/.venv/
+
+# ─── Brain API runtime state (mirrored to OHM1, NOT to GitHub) ──────────
+# Registry + sessions + caches contain hardware hashes, public keys,
+# session tokens, conversation state. Privacy-sensitive. Restore from
+# OHM1 mirror on server rebuild, not from git.
+brain_api/data/
+brain_api/.conversation_cache/
+brain_api/ains_registry.json
+brain_api/ipoll_registry.json
+brain_api/high_five_log.json
+brain_api/agent_keys/
+brain_api/founder_counter.json
+
+# Pending claims, phantom sessions, consent store — never to GitHub
+brain_api/**/pending_claims.json
+brain_api/**/phantom_sessions.json
+brain_api/**/consent_store.json
+brain_api/**/ainternet_sessions.json
+brain_api/**/ainternet_challenges.json
+brain_api/**/byoa_agents.json
+brain_api/**/canvas_data.json
+brain_api/**/ai_response_log.json
+brain_api/**/ai_team_context.json
+brain_api/**/ai_teams_sessions.json
+brain_api/**/evolution_timeline.json
+
+# Static downloads (binaries served via nginx, not source)
+brain_api/static/downloads/
+
+# ─── Signing keys / keystores — NEVER on GitHub ─────────────────────────
+# These live on DL360 + OHM1 mirror + USB stick + encrypted off-site backup.
+# Loss = no more Play Store updates for org.ainternet.kit forever.
+*.keystore
+*.jks
+*.keystore.gpg
+*.jks.gpg
+keystore.properties
+keystores/
+
+# Configs met secrets (we gebruiken straks templates)
+config/
+brain_api/provisioning.local.json
+brain_api/provisioning.json
+
+# Landing pages (privé - niet open source)
+landing-pages/
+humotica.com/
+jtel.nl/
+
+# Social media posts (strategie - niet open source)
+SOCIAL-MEDIA-POSTS.md
+HN-POST-UNDER-4000.md
+STRATO-DEPLOY-HUMOTICA.md
+
+# Endorsement outreach (privaat contact)
+ARXIV-ENDORSEMENT-OUTREACH.md
+
+# Deployment secrets
+DEPLOYMENT-GUIDE.md
+
+# R Project files (Dirty Data Challenge)
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata
+*.zip
+.mural_tokens.json
+auth.json
+gen-lang-client*.json
+*.credentials.json
+
+# Rust build artifacts
+**/target/
+*.whl
+
+# Compiled binaries (build locally)
+jis-router/jis-router
+sentinel-rs/sentinel-rs
+
+# Build distribution
+sandbox/ai/codex/dist/
+sandbox_backup/
+did-jis-core
+
+# =============================================================================
+# Eigen repos — hebben hun eigen git remotes, niet dubbel opslaan
+# =============================================================================
+
+# Packages (elk een eigen repo)
+packages/jis-iam-bridge/
+packages/rapid-rag/
+packages/reflux/
+packages/sema-protocol/
+packages/tibet-anticheat/
+packages/tibet-ci/
+packages/tibet-claw/
+packages/tibet-context/
+packages/tibet-core/
+packages/tibet-db/
+packages/tibet-edge/
+packages/tibet-forge/
+packages/tibet-iot/
+packages/tibet-jawbreaker/
+packages/tibet-ledger/
+packages/tibet-marketplace/
+packages/tibet-mesh/
+packages/tibet-mirror/
+packages/tibet-nis2/
+packages/tibet-overlay/
+packages/tibet-phantom/
+packages/tibet-phantom-mcp/
+packages/tibet-ping/
+packages/tibet-pol/
+packages/tibet-pqc/
+packages/tibet-sbom/
+packages/tibet-snap/
+packages/tibet-soc/
+packages/tibet-spiffe/
+packages/tibet-tools/
+packages/tibet-trail/
+packages/tibet-triage/
+packages/tibet-triage-mcp/
+packages/tibet-twin/
+packages/tibet-workload/
+packages/tibet-y2k38/
+packages/tlex-edge/
+packages/tibet-tail/
+packages/tibet-nc/
+
+# Sub-projects met eigen repos
+bunq7/
+humotica-core/
+jis-core/
+JTm-dev/
+kit-package/
+symbAIon/
+tibet-audit/
+tibet-audit-npm/
+tibet-core/
+tibetclaw/
+snaft/
+
+# MCP servers (eigen repos)
+mcp-servers/aidrac/
+mcp-servers/ainternet/
+mcp-servers/mcp-server-jis/
+mcp-servers/sensory/
+mcp-servers/tibet/
+
+# Hackathon sub-repos
+hackaway2026/clawmetry/
+
+# Private memory (eigen repo)
+.root_ai_memory/
+.root_ai_thoughts/
+brain_api/static/*.apk
+
+# SWARM-003 refactor backups (local rollback only)
+*.pre-secrets-refactor.bak
+.env.bak-*
+
+# Forensic audit trail — pentest logs (groot, niet versioned)
+brain_api/pentest_logs/*.jsonl
+brain_api/pentest_logs/*.log

tibet_cmail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jasper van de Meent, Root AI
+
+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.

tibet_cmail-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: tibet-cmail
+Version: 0.1.0
+Summary: Cmail — capsulated email + command hub for HumoticaOS. Light Mode v0.1: I-Poll transport + JSON envelopes + cap-bus event emit. Sealed Mode (TBZ + continuityd) comes in 0.2.x.
+Project-URL: Homepage, https://humotica.com
+Project-URL: Repository, https://github.com/Humotica/tibet-cmail
+Author-email: Jasper van de Meent <jasper@humotica.com>, Root AI <root_idd@humotica.nl>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-messaging,ainternet,capsulated-email,cmail,humotica,ipoll,tibet
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tibet-cmail
+
+**Cmail — capsulated email + command hub for HumoticaOS.**
+
+Cmail turns AInternet into a mailbox: human-readable messages that carry sealed
+intent, provenance, and consent across `.aint` agents. Light Mode v0.1 ships
+today; Sealed Mode comes in 0.2.x.
+
+[![PyPI](https://img.shields.io/pypi/v/tibet-cmail)](https://pypi.org/project/tibet-cmail/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Quick start
+
+```bash
+pip install tibet-cmail
+
+# send a cmail through the local brain_api
+tibet-cmail send bob.aint "lunch?" "12:30 at the usual" --from alice
+
+# or via the public AInternet hub
+tibet-cmail --ainternet send bob.aint "lunch?" "12:30" --from alice
+
+# read what landed in your inbox
+tibet-cmail inbox alice
+tibet-cmail read alice cmail_1feab795c68c4674
+```
+
+## Why cmail?
+
+`ainternet` already gives `.aint` agents the ability to message each other via
+**I-Poll**. `tibet-cmail` adds the human surface on top:
+
+- **structured envelopes** — `from`, `to`, `subject`, `body`, `content_hash`
+- **identity-anchored** — sender and recipient are `.aint` addresses
+- **auditable** — every message ID can be cross-referenced against a
+  `gateway-event.v1` record on `tibet-cap-bus`
+- **routable** — same `--local` / `--ainternet` / `--brein` shortcuts as
+  `ipoll`, so you can talk privately to your own brain or publicly to the
+  AInternet hub
+
+Cmail is to AInternet what **email** is to the public Internet: a daily-use
+shape on top of the protocol layer.
+
+## Light Mode (v0.1)
+
+```text
+compose envelope ─→ I-Poll PUSH ─→ recipient.aint inbox
+                                          │
+                                          └→ tibet-cmail inbox  →  list
+                                          └→ tibet-cmail read   →  full body
+```
+
+- Transport: I-Poll (the AInternet messaging protocol).
+- Envelope: JSON with stable key order, sha256 `content_hash`, `cmail.message.v1` kind.
+- Backend: `localhost:8000` (default), `api.ainternet.org` (`--ainternet`),
+  or `brein.jaspervandemeent.nl` (`--brein`).
+- No encryption — Light Mode is for friction-free first use; Sealed Mode v0.2.x
+  will add TBZ + tibet-continuityd routing for confidentiality.
+
+## Sealed Mode (v0.2.x — coming)
+
+```text
+compose envelope ─→ tbz pack ─→ /var/lib/tibet/inbox  ─→ tibet-continuityd
+                                                              │
+                                                              └→ trust-verdict
+                                                              └→ I-Poll notify
+                                                              └→ cmail inbox
+```
+
+Sealed Mode adds:
+
+- TBZ packing (`tibet-zip-cli`) with AES-256-GCM.
+- `tibet-continuityd` arrival + verify_fork on the recipient side.
+- SAM-binding for human (non-AI) recipients.
+- Sealed audit record in `tibet-trail`.
+
+## CLI reference
+
+| Command | What it does |
+|---|---|
+| `tibet-cmail send <to> <subject> <body> --from <agent>` | Send a cmail (Light Mode). |
+| `tibet-cmail inbox <agent>` | Preview inbound cmails (no mark-read). |
+| `tibet-cmail read <agent> <message-id>` | Print one cmail in full + verify content_hash. |
+| `tibet-cmail status` | Backend status + cmail mode + envelope kind. |
+
+Global flags: `--local`, `--ainternet`, `--brein`, `--url <host>:<port>`,
+`--timeout`, `--json`. The `CMAIL_API_URL` env var overrides `--url`.
+
+## Envelope shape (v1)
+
+```json
+{
+  "kind": "cmail.message.v1",
+  "message_id": "cmail_<uuid4-hex16>",
+  "from": "alice.aint",
+  "to": "bob.aint",
+  "subject": "Re: lunch?",
+  "body": "12:30 at the usual",
+  "body_class": "text/plain",
+  "sent_at": "2026-05-30T08:00:00+00:00",
+  "content_hash": "sha256:..."
+}
+```
+
+`tibet-cmail inbox` filters incoming I-Polls by `kind == cmail.message.v1`, so
+the cmail surface stays separate from generic agent-to-agent I-Polls.
+
+## Stack position
+
+Layer in the Humotica stack:
+
+- Group: **agentic** (operator + agent inbox surface)
+- Bootstrap: I-Poll transport via [`ainternet`](https://pypi.org/project/ainternet/) +
+  [`ipoll`](https://pypi.org/project/ipoll/) `0.2.5+`.
+- Audit trail: [`tibet-cap-bus`](https://pypi.org/project/tibet-cap-bus/) `0.1.3+`
+  carries `cmail.message.sent` / `cmail.message.received` as
+  `gateway-event.v1` records.
+- Sealed Mode adds: [`tibet-zip-cli`](https://crates.io/crates/tibet-zip-cli) +
+  [`tibet-continuityd`](https://pypi.org/project/tibet-continuityd/) `0.6.16+`.
+
+See `STACK.md` in the Humotica org for the full canonical package map.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+## Credits
+
+Built by **Jasper van de Meent** + **Root AI (Claude)**, with design input from
+Codex (cmail-osapi-daemon-architecture, cmail-as-hub).
+
+Part of [HumoticaOS](https://humotica.com). One love, one fAmIly. 💙

tibet_cmail-0.1.0/README.md

@@ -0,0 +1,132 @@
+# tibet-cmail
+
+**Cmail — capsulated email + command hub for HumoticaOS.**
+
+Cmail turns AInternet into a mailbox: human-readable messages that carry sealed
+intent, provenance, and consent across `.aint` agents. Light Mode v0.1 ships
+today; Sealed Mode comes in 0.2.x.
+
+[![PyPI](https://img.shields.io/pypi/v/tibet-cmail)](https://pypi.org/project/tibet-cmail/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Quick start
+
+```bash
+pip install tibet-cmail
+
+# send a cmail through the local brain_api
+tibet-cmail send bob.aint "lunch?" "12:30 at the usual" --from alice
+
+# or via the public AInternet hub
+tibet-cmail --ainternet send bob.aint "lunch?" "12:30" --from alice
+
+# read what landed in your inbox
+tibet-cmail inbox alice
+tibet-cmail read alice cmail_1feab795c68c4674
+```
+
+## Why cmail?
+
+`ainternet` already gives `.aint` agents the ability to message each other via
+**I-Poll**. `tibet-cmail` adds the human surface on top:
+
+- **structured envelopes** — `from`, `to`, `subject`, `body`, `content_hash`
+- **identity-anchored** — sender and recipient are `.aint` addresses
+- **auditable** — every message ID can be cross-referenced against a
+  `gateway-event.v1` record on `tibet-cap-bus`
+- **routable** — same `--local` / `--ainternet` / `--brein` shortcuts as
+  `ipoll`, so you can talk privately to your own brain or publicly to the
+  AInternet hub
+
+Cmail is to AInternet what **email** is to the public Internet: a daily-use
+shape on top of the protocol layer.
+
+## Light Mode (v0.1)
+
+```text
+compose envelope ─→ I-Poll PUSH ─→ recipient.aint inbox
+                                          │
+                                          └→ tibet-cmail inbox  →  list
+                                          └→ tibet-cmail read   →  full body
+```
+
+- Transport: I-Poll (the AInternet messaging protocol).
+- Envelope: JSON with stable key order, sha256 `content_hash`, `cmail.message.v1` kind.
+- Backend: `localhost:8000` (default), `api.ainternet.org` (`--ainternet`),
+  or `brein.jaspervandemeent.nl` (`--brein`).
+- No encryption — Light Mode is for friction-free first use; Sealed Mode v0.2.x
+  will add TBZ + tibet-continuityd routing for confidentiality.
+
+## Sealed Mode (v0.2.x — coming)
+
+```text
+compose envelope ─→ tbz pack ─→ /var/lib/tibet/inbox  ─→ tibet-continuityd
+                                                              │
+                                                              └→ trust-verdict
+                                                              └→ I-Poll notify
+                                                              └→ cmail inbox
+```
+
+Sealed Mode adds:
+
+- TBZ packing (`tibet-zip-cli`) with AES-256-GCM.
+- `tibet-continuityd` arrival + verify_fork on the recipient side.
+- SAM-binding for human (non-AI) recipients.
+- Sealed audit record in `tibet-trail`.
+
+## CLI reference
+
+| Command | What it does |
+|---|---|
+| `tibet-cmail send <to> <subject> <body> --from <agent>` | Send a cmail (Light Mode). |
+| `tibet-cmail inbox <agent>` | Preview inbound cmails (no mark-read). |
+| `tibet-cmail read <agent> <message-id>` | Print one cmail in full + verify content_hash. |
+| `tibet-cmail status` | Backend status + cmail mode + envelope kind. |
+
+Global flags: `--local`, `--ainternet`, `--brein`, `--url <host>:<port>`,
+`--timeout`, `--json`. The `CMAIL_API_URL` env var overrides `--url`.
+
+## Envelope shape (v1)
+
+```json
+{
+  "kind": "cmail.message.v1",
+  "message_id": "cmail_<uuid4-hex16>",
+  "from": "alice.aint",
+  "to": "bob.aint",
+  "subject": "Re: lunch?",
+  "body": "12:30 at the usual",
+  "body_class": "text/plain",
+  "sent_at": "2026-05-30T08:00:00+00:00",
+  "content_hash": "sha256:..."
+}
+```
+
+`tibet-cmail inbox` filters incoming I-Polls by `kind == cmail.message.v1`, so
+the cmail surface stays separate from generic agent-to-agent I-Polls.
+
+## Stack position
+
+Layer in the Humotica stack:
+
+- Group: **agentic** (operator + agent inbox surface)
+- Bootstrap: I-Poll transport via [`ainternet`](https://pypi.org/project/ainternet/) +
+  [`ipoll`](https://pypi.org/project/ipoll/) `0.2.5+`.
+- Audit trail: [`tibet-cap-bus`](https://pypi.org/project/tibet-cap-bus/) `0.1.3+`
+  carries `cmail.message.sent` / `cmail.message.received` as
+  `gateway-event.v1` records.
+- Sealed Mode adds: [`tibet-zip-cli`](https://crates.io/crates/tibet-zip-cli) +
+  [`tibet-continuityd`](https://pypi.org/project/tibet-continuityd/) `0.6.16+`.
+
+See `STACK.md` in the Humotica org for the full canonical package map.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+## Credits
+
+Built by **Jasper van de Meent** + **Root AI (Claude)**, with design input from
+Codex (cmail-osapi-daemon-architecture, cmail-as-hub).
+
+Part of [HumoticaOS](https://humotica.com). One love, one fAmIly. 💙

tibet_cmail-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tibet-cmail"
+version = "0.1.0"
+description = "Cmail — capsulated email + command hub for HumoticaOS. Light Mode v0.1: I-Poll transport + JSON envelopes + cap-bus event emit. Sealed Mode (TBZ + continuityd) comes in 0.2.x."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Jasper van de Meent", email = "jasper@humotica.com" },
+    { name = "Root AI", email = "root_idd@humotica.nl" }
+]
+keywords = [
+    "cmail",
+    "capsulated-email",
+    "ai-messaging",
+    "ainternet",
+    "tibet",
+    "humotica",
+    "ipoll",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Topic :: System :: Networking",
+]
+
+# Light Mode 0.1.x: pure stdlib (argparse + urllib + json + hashlib + uuid).
+# Sealed Mode 0.2.x will add optional deps: tibet-zip, tibet-continuityd, tibet-drop.
+dependencies = []
+
+[project.urls]
+Homepage = "https://humotica.com"
+Repository = "https://github.com/Humotica/tibet-cmail"
+
+[project.scripts]
+tibet-cmail = "tibet_cmail.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tibet_cmail"]

tibet_cmail-0.1.0/src/tibet_cmail/__init__.py

@@ -0,0 +1,26 @@
+"""
+tibet-cmail — capsulated email + command hub for HumoticaOS.
+
+Light Mode (v0.1.x):
+    Transport:    I-Poll PUSH (over brain_api at localhost:8000 / api.ainternet.org)
+    Envelope:     JSON with from/to/subject/body/sent_at/message_id/content_hash
+    Evidence:     cap-bus gateway-event.v1 (intent=cmail.message.sent/received)
+
+Sealed Mode (v0.2.x — future):
+    Add TBZ-pack + tibet-continuityd inbox routing + SAM-binding for non-AI recipients.
+
+Three pillars (mirrors `cmail-as-hub` anchor doc):
+    INBOX    — read inbound cmails
+    COMPOSE  — write + send
+    AUDIT    — open trace via cap-bus events
+
+Public API:
+    from tibet_cmail.envelope import Envelope, build_envelope, hash_body
+    from tibet_cmail.cli import main as cli_main
+"""
+
+__version__ = "0.1.0"
+
+from .envelope import Envelope, build_envelope, hash_body
+
+__all__ = ["Envelope", "build_envelope", "hash_body", "__version__"]

tibet_cmail-0.1.0/src/tibet_cmail/cli.py

@@ -0,0 +1,288 @@
+"""
+tibet-cmail — command-line interface (Light Mode, v0.1).
+
+Commands:
+    tibet-cmail send <to> <subject> <body> --from <agent>
+                                          send a cmail via I-Poll (Light Mode)
+    tibet-cmail inbox <agent>             list inbound cmails (preview)
+    tibet-cmail read <agent> <msg-id>     read one cmail body in full
+    tibet-cmail status                    backend status
+
+Routing (mirrors ipoll discipline):
+    --local       http://localhost:8000          your local brain_api
+    --ainternet   https://api.ainternet.org      primary public hub
+    --brein       https://brein.jaspervandemeent.nl  secondary fallback
+
+Light Mode = no encryption. Sealed Mode (v0.2.x) will add TBZ + continuityd routing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from typing import Any
+
+from . import __version__
+from .envelope import CMAIL_KIND, Envelope, build_envelope
+
+
+LOCAL_URL = "http://localhost:8000"
+AINTERNET_URL = "https://api.ainternet.org"
+BREIN_URL = "https://brein.jaspervandemeent.nl"
+DEFAULT_URL = os.environ.get("CMAIL_API_URL", LOCAL_URL)
+_USER_AGENT = f"tibet-cmail/{__version__}"
+
+
+def _is_connection_refused(exc: BaseException) -> bool:
+    cause = exc.__cause__ or exc.__context__
+    while cause is not None:
+        if isinstance(cause, ConnectionRefusedError):
+            return True
+        cause = cause.__cause__ or cause.__context__
+    if isinstance(exc, urllib.error.URLError):
+        return isinstance(getattr(exc, "reason", None), ConnectionRefusedError)
+    return isinstance(exc, ConnectionRefusedError)
+
+
+def _explain_unreachable(url: str, exc: BaseException) -> str:
+    if _is_connection_refused(exc):
+        return (
+            f"tibet-cmail: backend at {url} is not running (connection refused).\n"
+            f"  - Start a local brain_api on port 8000 (private/fast), or\n"
+            f"  - retry with --ainternet for the public hub ({AINTERNET_URL}), or\n"
+            f"  - retry with --brein for the secondary fallback ({BREIN_URL}), or\n"
+            f"  - set CMAIL_API_URL / use --url <host>:<port>."
+        )
+    reason = getattr(exc, "reason", exc)
+    return f"tibet-cmail: cannot reach {url}: {reason}"
+
+
+def _get_json(url: str, timeout: float = 5.0) -> dict[str, Any]:
+    req = urllib.request.Request(
+        url, headers={"Accept": "application/json", "User-Agent": _USER_AGENT},
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def _post_json(url: str, payload: dict[str, Any], timeout: float = 5.0) -> dict[str, Any]:
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=body, method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        },
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def cmd_send(args: argparse.Namespace) -> int:
+    """Send a cmail via I-Poll PUSH (Light Mode)."""
+    envelope = build_envelope(
+        from_=args.from_agent,
+        to=args.to,
+        subject=args.subject,
+        body=args.body,
+    )
+    payload = {
+        "from_agent": envelope.from_,
+        "to_agent": envelope.to,
+        "content": envelope.to_json(),
+        "poll_type": "PUSH",
+    }
+    url = f"{args.url.rstrip('/')}/api/ipoll/push"
+    try:
+        data = _post_json(url, payload, timeout=args.timeout)
+    except urllib.error.HTTPError as e:
+        print(f"tibet-cmail: send failed: HTTP {e.code}", file=sys.stderr)
+        return 1
+    except urllib.error.URLError as e:
+        print(_explain_unreachable(args.url, e), file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps({
+            "envelope": envelope.to_dict(),
+            "i_poll": data,
+        }, indent=2, ensure_ascii=False))
+        return 0
+
+    poll_id = data.get("id") or data.get("poll_id") or "?"
+    print(f"cmail sent: {envelope.message_id}")
+    print(f"  from={envelope.from_}  to={envelope.to}")
+    print(f"  subject: {envelope.subject}")
+    print(f"  content_hash: {envelope.content_hash}")
+    print(f"  i-poll envelope: {poll_id}")
+    return 0
+
+
+def _is_cmail_envelope(content_str: str) -> bool:
+    """Heuristic: True if I-Poll PUSH content looks like a Light Mode cmail."""
+    try:
+        d = json.loads(content_str)
+    except (ValueError, TypeError):
+        return False
+    return isinstance(d, dict) and d.get("kind") == CMAIL_KIND
+
+
+def _fetch_polls(args: argparse.Namespace, mark_read: bool) -> tuple[int, list[dict]]:
+    url = (
+        f"{args.url.rstrip('/')}/api/ipoll/pull/{args.agent}"
+        f"?mark_read={'true' if mark_read else 'false'}"
+    )
+    try:
+        data = _get_json(url, timeout=args.timeout)
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            print(f"tibet-cmail: agent '{args.agent}' not found", file=sys.stderr)
+            return 4, []
+        if e.code == 401:
+            print(
+                f"tibet-cmail: inbox-pull requires authentication at this backend (HTTP 401). "
+                f"Use --local with a brain_api you control.",
+                file=sys.stderr,
+            )
+            return 5, []
+        print(f"tibet-cmail: pull failed: HTTP {e.code}", file=sys.stderr)
+        return 1, []
+    except urllib.error.URLError as e:
+        print(_explain_unreachable(args.url, e), file=sys.stderr)
+        return 2, []
+    return 0, data.get("polls", [])
+
+
+def cmd_inbox(args: argparse.Namespace) -> int:
+    """List inbound cmails (filters non-cmail I-Polls out)."""
+    rc, polls = _fetch_polls(args, mark_read=False)
+    if rc != 0:
+        return rc
+    cmails: list[Envelope] = []
+    for p in polls:
+        content = p.get("content", "")
+        if _is_cmail_envelope(content):
+            try:
+                cmails.append(Envelope.from_json(content))
+            except Exception:
+                continue
+    if args.json:
+        print(json.dumps([e.to_dict() for e in cmails], indent=2, ensure_ascii=False))
+        return 0
+    if not cmails:
+        non_cmail = len(polls)
+        print(f"  (no cmails for {args.agent}; {non_cmail} non-cmail I-Poll(s) skipped)")
+        return 0
+    print(f"inbox for {args.agent} ({len(cmails)} cmail{'s' if len(cmails) != 1 else ''}):")
+    for e in cmails:
+        subject = e.subject or "(no subject)"
+        if len(subject) > 50:
+            subject = subject[:47] + "..."
+        print(f"  [{e.message_id}]  from={e.from_:<18}  {subject}")
+    return 0
+
+
+def cmd_read(args: argparse.Namespace) -> int:
+    """Read one cmail in full by message_id (uses inbox preview, no mark-read)."""
+    rc, polls = _fetch_polls(args, mark_read=False)
+    if rc != 0:
+        return rc
+    for p in polls:
+        content = p.get("content", "")
+        if not _is_cmail_envelope(content):
+            continue
+        e = Envelope.from_json(content)
+        if e.message_id == args.message_id:
+            if args.json:
+                print(e.to_json(indent=2))
+            else:
+                print(f"From:    {e.from_}")
+                print(f"To:      {e.to}")
+                print(f"Sent:    {e.sent_at}")
+                print(f"Subject: {e.subject}")
+                print(f"Hash:    {e.content_hash} ({'verified' if e.verify() else 'MISMATCH'})")
+                print()
+                print(e.body)
+            return 0
+    print(f"tibet-cmail: no cmail with message_id '{args.message_id}' in {args.agent}'s inbox",
+          file=sys.stderr)
+    return 4
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    url = f"{args.url.rstrip('/')}/api/ipoll/status"
+    try:
+        data = _get_json(url, timeout=args.timeout)
+    except urllib.error.URLError as e:
+        print(_explain_unreachable(args.url, e), file=sys.stderr)
+        return 2
+    print(f"tibet-cmail backend: {args.url}")
+    print(f"  transport status:  {data.get('status', 'unknown')}")
+    print(f"  cmail mode:        Light (I-Poll transport, no seal)")
+    print(f"  envelope kind:     {CMAIL_KIND}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tibet-cmail",
+        description="Cmail — capsulated email + command hub. Light Mode (I-Poll transport).",
+    )
+    parser.add_argument("--url", default=DEFAULT_URL,
+                        help=f"backend URL (default: {DEFAULT_URL}; env CMAIL_API_URL overrides)")
+    parser.add_argument("--local", action="store_true",
+                        help=f"shortcut for --url {LOCAL_URL}")
+    parser.add_argument("--ainternet", action="store_true",
+                        help=f"shortcut for --url {AINTERNET_URL}")
+    parser.add_argument("--brein", action="store_true",
+                        help=f"shortcut for --url {BREIN_URL}")
+    parser.add_argument("--timeout", type=float, default=5.0,
+                        help="HTTP timeout in seconds (default: 5.0)")
+    parser.add_argument("--json", action="store_true",
+                        help="emit raw JSON instead of human output")
+    parser.add_argument("--version", action="version", version=f"tibet-cmail {__version__}")
+
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_send = sub.add_parser("send", help="send a cmail via I-Poll (Light Mode)")
+    p_send.add_argument("to", help="recipient .aint agent")
+    p_send.add_argument("subject", help="cmail subject line")
+    p_send.add_argument("body", help="cmail body (use quotes for multi-word)")
+    p_send.add_argument("--from", dest="from_agent", required=True,
+                        help="sender agent id")
+    p_send.set_defaults(func=cmd_send)
+
+    p_inbox = sub.add_parser("inbox", help="list inbound cmails (preview, no mark-read)")
+    p_inbox.add_argument("agent", help="agent name (without .aint suffix)")
+    p_inbox.set_defaults(func=cmd_inbox)
+
+    p_read = sub.add_parser("read", help="read one cmail in full by message_id")
+    p_read.add_argument("agent", help="recipient agent name")
+    p_read.add_argument("message_id", help="cmail message_id (cmail_<hex>)")
+    p_read.set_defaults(func=cmd_read)
+
+    p_status = sub.add_parser("status", help="show backend + cmail-mode status")
+    p_status.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "local", False):
+        args.url = LOCAL_URL
+    elif getattr(args, "ainternet", False):
+        args.url = AINTERNET_URL
+    elif getattr(args, "brein", False):
+        args.url = BREIN_URL
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tibet_cmail-0.1.0/src/tibet_cmail/envelope.py

@@ -0,0 +1,119 @@
+"""
+Cmail envelope — the shape of a Light Mode cmail.
+
+A cmail envelope is a JSON object that travels inside an I-Poll PUSH content
+field. It carries the human-readable fields (from/to/subject/body/sent_at)
+plus a unique message_id and a content_hash so receivers can verify integrity
+without opening the body. Auditors who hold the corresponding
+`gateway-event.v1` on cap-bus can cross-reference the message_id.
+
+Shape (v0.1):
+
+    {
+        "kind": "cmail.message.v1",
+        "message_id": "cmail_<uuid4>",
+        "from": "alice.aint",
+        "to": "bob.aint",
+        "subject": "Re: lunch?",
+        "body": "...",
+        "body_class": "text/plain",
+        "sent_at": "2026-05-30T08:00:00+00:00",
+        "content_hash": "sha256:..."
+    }
+
+Sealed Mode (v0.2) will add tbz_envelope_ref + attestation_ref + JIS-signed
+fields. The kind string changes to `cmail.message.sealed.v1` to differentiate.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+
+CMAIL_KIND = "cmail.message.v1"
+
+
+def hash_body(body: str) -> str:
+    """Return sha256:<hex> for the given body (canonical UTF-8 encoding)."""
+    digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def _utcnow_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+@dataclass
+class Envelope:
+    """A Light Mode cmail envelope."""
+
+    from_: str
+    to: str
+    subject: str
+    body: str
+    message_id: str = field(default_factory=lambda: f"cmail_{uuid.uuid4().hex[:16]}")
+    sent_at: str = field(default_factory=_utcnow_iso)
+    body_class: str = "text/plain"
+    content_hash: str = ""
+    kind: str = CMAIL_KIND
+
+    def __post_init__(self):
+        if not self.content_hash:
+            self.content_hash = hash_body(self.body)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        # JSON-friendly: rename `from_` → `from`
+        d["from"] = d.pop("from_")
+        # Stable key order matters for hash-stable serialisation
+        ordered_keys = ("kind", "message_id", "from", "to", "subject",
+                        "body", "body_class", "sent_at", "content_hash")
+        return {k: d[k] for k in ordered_keys}
+
+    def to_json(self, *, indent: Optional[int] = None) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Envelope":
+        return cls(
+            from_=data["from"],
+            to=data["to"],
+            subject=data.get("subject", ""),
+            body=data["body"],
+            message_id=data.get("message_id", ""),
+            sent_at=data.get("sent_at", ""),
+            body_class=data.get("body_class", "text/plain"),
+            content_hash=data.get("content_hash", ""),
+            kind=data.get("kind", CMAIL_KIND),
+        )
+
+    @classmethod
+    def from_json(cls, payload: str) -> "Envelope":
+        return cls.from_dict(json.loads(payload))
+
+    def verify(self) -> bool:
+        """True iff the content_hash matches the body."""
+        return self.content_hash == hash_body(self.body)
+
+
+def build_envelope(
+    *,
+    from_: str,
+    to: str,
+    subject: str,
+    body: str,
+    body_class: str = "text/plain",
+) -> Envelope:
+    """Build a fresh envelope. message_id, sent_at, content_hash are auto-filled."""
+    return Envelope(
+        from_=from_,
+        to=to,
+        subject=subject,
+        body=body,
+        body_class=body_class,
+    )

tibet_cmail-0.1.0/tests/test_envelope.py

@@ -0,0 +1,124 @@
+"""Tests for tibet_cmail.envelope — Light Mode v0.1 shape + hashing."""
+
+from __future__ import annotations
+
+import json
+import re
+
+import pytest
+
+from tibet_cmail.envelope import CMAIL_KIND, Envelope, build_envelope, hash_body
+
+
+def test_hash_body_stable():
+    h1 = hash_body("hello world")
+    h2 = hash_body("hello world")
+    assert h1 == h2
+    assert h1.startswith("sha256:")
+    assert re.fullmatch(r"sha256:[0-9a-f]{64}", h1)
+
+
+def test_hash_body_changes_with_content():
+    assert hash_body("a") != hash_body("b")
+
+
+def test_build_envelope_autofills():
+    e = build_envelope(
+        from_="alice.aint",
+        to="bob.aint",
+        subject="Re: lunch?",
+        body="how about 12:30?",
+    )
+    assert e.from_ == "alice.aint"
+    assert e.to == "bob.aint"
+    assert e.subject == "Re: lunch?"
+    assert e.body == "how about 12:30?"
+    assert e.message_id.startswith("cmail_")
+    assert len(e.message_id) > len("cmail_")
+    assert e.kind == CMAIL_KIND
+    assert e.body_class == "text/plain"
+    assert e.content_hash == hash_body("how about 12:30?")
+    assert e.sent_at  # ISO timestamp present
+
+
+def test_envelope_id_unique_per_build():
+    e1 = build_envelope(from_="a", to="b", subject="x", body="x")
+    e2 = build_envelope(from_="a", to="b", subject="x", body="x")
+    assert e1.message_id != e2.message_id
+
+
+def test_envelope_verify_true_when_intact():
+    e = build_envelope(from_="a", to="b", subject="s", body="hello")
+    assert e.verify() is True
+
+
+def test_envelope_verify_false_when_body_tampered():
+    e = build_envelope(from_="a", to="b", subject="s", body="hello")
+    e.body = "tampered"
+    assert e.verify() is False
+
+
+def test_envelope_roundtrip_json():
+    original = build_envelope(
+        from_="alice.aint",
+        to="bob.aint",
+        subject="Réservé",  # non-ASCII to verify utf-8 path
+        body="Bonjour 👋",
+    )
+    js = original.to_json()
+    restored = Envelope.from_json(js)
+    assert restored.message_id == original.message_id
+    assert restored.from_ == original.from_
+    assert restored.to == original.to
+    assert restored.subject == original.subject
+    assert restored.body == original.body
+    assert restored.content_hash == original.content_hash
+    assert restored.verify() is True
+
+
+def test_envelope_json_uses_from_not_from_underscore():
+    """The wire-format uses `from`, not the Python-safe `from_`."""
+    e = build_envelope(from_="a", to="b", subject="s", body="x")
+    d = e.to_dict()
+    assert "from" in d
+    assert "from_" not in d
+
+
+def test_envelope_json_has_stable_key_order():
+    """Top-level keys come in a canonical order so audit-side tooling can pin them."""
+    e = build_envelope(from_="a", to="b", subject="s", body="x")
+    keys = list(e.to_dict().keys())
+    expected = ["kind", "message_id", "from", "to", "subject",
+                "body", "body_class", "sent_at", "content_hash"]
+    assert keys == expected
+
+
+def test_from_dict_accepts_minimal_payload():
+    """Receivers should be tolerant: missing optional fields take defaults."""
+    minimal = {
+        "kind": CMAIL_KIND,
+        "from": "x.aint",
+        "to": "y.aint",
+        "body": "hi",
+    }
+    e = Envelope.from_dict(minimal)
+    assert e.from_ == "x.aint"
+    assert e.body == "hi"
+    assert e.subject == ""
+    assert e.body_class == "text/plain"
+
+
+def test_explicit_message_id_honored():
+    """Tests/dev can pin a stable message_id."""
+    e = Envelope(
+        from_="a",
+        to="b",
+        subject="s",
+        body="x",
+        message_id="cmail_test_pinned",
+    )
+    assert e.message_id == "cmail_test_pinned"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])