ghost-layer 0.1.0__tar.gz

ghost_layer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timothy Walton / Script Master Labs LLC
+
+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.

ghost_layer-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: ghost-layer
+Version: 0.1.0
+Summary: Ephemeral execution layer for autonomous AI agents — scoped credentials, cryptographic residue.
+Author-email: Timothy Walton <ScriptMasterLabs@gmail.com>
+License: MIT
+Project-URL: Homepage, https://scriptmasterlabs.com/stack/ghost
+Project-URL: Repository, https://github.com/timwal78/ghost-layer
+Project-URL: Documentation, https://github.com/timwal78/ghost-layer/blob/main/docs/ARCHITECTURE.md
+Project-URL: Issues, https://github.com/timwal78/ghost-layer/issues
+Keywords: ai-agents,autonomous,ephemeral,credentials,cryptography,audit,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# GHOST
+### The Spectral Execution Layer for Autonomous Agents
+
+> *"Most agents die in the light. Ours operate in the dark."*
+
+Give your AI agent a **body that vanishes**. GHOST is an ephemeral execution
+layer: an agent declares intent, spawns a short-lived signing key, executes
+**scoped** actions through an intercept that records **cryptographic residue**,
+then evaporates — leaving a tamper-evident audit trail and **zero standing
+credentials**.
+
+[![status](https://img.shields.io/badge/status-alpha-39FF14)](https://github.com/timwal78/ghost-layer)
+[![license](https://img.shields.io/badge/license-MIT-FFD700)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-FF1493)](pyproject.toml)
+
+---
+
+## The Problem
+
+You gave your agent AWS keys. Now you're watching CloudTrail at 3am.
+
+Agents are **ephemeral bursts of intent**. Humans are persistent. Yet today's
+agents execute with persistent, human-shaped credentials and unbounded scope.
+One leaked key compromises everything, and there's no signed proof of *why* the
+agent did what it did.
+
+## The Inversion
+
+| Human model | Agent model (GHOST) |
+|---|---|
+| log in → do stuff → log out | declare intent → **spawn** → execute → **evaporate** → leave **residue** |
+| session persists | session auto-expires (TTL) |
+| broad standing access | scoped to declared tools |
+| audit logs (unsigned) | Ed25519-signed, tamper-evident chain |
+
+---
+
+## The Ritual (Quickstart)
+
+```bash
+pip install ghost-layer
+
+ghost spawn --intent "deploy_staging" --ttl 300 --scope aws_ec2
+ghost act   --tool aws_ec2 --action RunInstances --session-id gh_9ddb...
+ghost evaporate --session-id gh_9ddb...
+ghost replay    --session-id gh_9ddb...
+```
+
+What just happened: your agent never held a standing credential. The session
+lived under a second. The residue is **Ed25519-signed** and immutable — replay
+it and verify exactly why that instance spawned.
+
+Out-of-scope calls are refused before they run:
+
+```bash
+ghost act --tool stripe --action CreateCharge --session-id gh_9ddb...
+# DENIED (scope): tool 'stripe' not in session scopes ['aws_ec2']   (exit 2)
+```
+
+---
+
+## Five Commands
+
+| Command | What it does |
+|---|---|
+| `ghost spawn` | Mint an ephemeral session + fresh Ed25519 keypair, TTL countdown begins |
+| `ghost possess` | Bind an agent to the session via the intercept proxy |
+| `ghost act` | Record a **scoped, signed** action (blocked if out-of-scope or expired) |
+| `ghost evaporate` | Shred the key, sign the whole action chain, finalize the residue |
+| `ghost replay` | Re-verify every signature + the root chain signature |
+
+---
+
+## Use It In Code (SDK-agnostic)
+
+The transport is injected, so GHOST wraps **any** HTTP client or agent
+framework — LangChain, the OpenAI SDK, raw `requests`/`httpx`:
+
+```python
+from ghost import spawn, possess, evaporate, replay
+from ghost.store import ResidueStore
+import requests
+
+store = ResidueStore()
+session = spawn(store, intent="enrich_lead", ttl=120, scopes=["httpbin"])
+
+def transport(method, url, headers=None, **kw):
+    return requests.request(method, url, headers=headers, **kw)
+
+proxy = possess(store, session["session_id"], transport, token="ghtok_demo")
+
+# Auth headers the agent sets are STRIPPED; the ghost token is injected.
+proxy.request("POST", "https://httpbin.org/post",
+              tool="httpbin", action="submit",
+              headers={"Authorization": "Bearer WILL_BE_STRIPPED"})
+
+evaporate(store, session["session_id"])
+print(replay(store, session["session_id"])["verified"])   # True
+```
+
+See [`examples/`](examples/) for a LangChain-style agent and an
+**x402 / XRPL payment agent** that settles a micropayment through a single
+60-second ghost body.
+
+---
+
+## Why It's Tamper-Evident
+
+Every action is signed over a canonical hash binding `session_id`, sequence,
+tool, action, and the hashes of params/response. At `evaporate`, a **root
+signature** covers the ordered chain. Change one byte of the residue and
+`ghost replay` reports `verified: false`. The private key is gone by then — it
+**cannot** be re-signed.
+
+```text
+spawn ─▶ keypair (priv on disk 0600, pub in residue)
+  │
+  ├─ act ─▶ sign(payload)  ─▶ residue row
+  ├─ act ─▶ sign(payload)  ─▶ residue row
+  │
+evaporate ─▶ sign(chain) = root_sig ─▶ shred priv key
+  │
+replay ─▶ verify(each) + verify(root)   ✓ tamper-evident
+```
+
+---
+
+## Where It Fits
+
+GHOST is the execution-safety layer beneath the **x402 agentic web**. It lets
+autonomous agents trigger payment rails ([NEXUS-402](https://nexus-402.com),
+402Proof, XAH Portal) and act on [SqueezeOS](https://scriptmasterlabs.com)
+signals **without ever holding a standing key** — every autonomous move leaves
+a signed receipt.
+
+Full catalog: **[scriptmasterlabs.com/stack](https://scriptmasterlabs.com/stack)**
+
+---
+
+## Status & Roadmap
+
+- [x] Python CLI — spawn / possess / act / evaporate / replay
+- [x] SQLite residue store, Ed25519 signing, scope + TTL enforcement
+- [x] Intercept proxy (SDK-agnostic), tamper-detection tests (17 passing)
+- [ ] Rust proxy core (performance)
+- [ ] Native LangChain / OpenAI tool wrappers
+- [ ] Pre/post validation hooks, webhook notifications
+- [ ] Optional cloud-hosted proxy
+
+---
+
+## Install from source
+
+```bash
+git clone https://github.com/timwal78/ghost-layer
+cd ghost-layer
+pip install -e ".[dev]"
+pytest -q          # 17 passed
+```
+
+---
+
+Built by **Script Master Labs LLC** · Disabled U.S. Army Veteran–Owned (SDVOSB) · Kinston, NC
+Docs: [ARCHITECTURE.md](docs/ARCHITECTURE.md) · [SECURITY.md](docs/SECURITY.md) · MIT License

ghost_layer-0.1.0/README.md

@@ -0,0 +1,164 @@
+# GHOST
+### The Spectral Execution Layer for Autonomous Agents
+
+> *"Most agents die in the light. Ours operate in the dark."*
+
+Give your AI agent a **body that vanishes**. GHOST is an ephemeral execution
+layer: an agent declares intent, spawns a short-lived signing key, executes
+**scoped** actions through an intercept that records **cryptographic residue**,
+then evaporates — leaving a tamper-evident audit trail and **zero standing
+credentials**.
+
+[![status](https://img.shields.io/badge/status-alpha-39FF14)](https://github.com/timwal78/ghost-layer)
+[![license](https://img.shields.io/badge/license-MIT-FFD700)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-FF1493)](pyproject.toml)
+
+---
+
+## The Problem
+
+You gave your agent AWS keys. Now you're watching CloudTrail at 3am.
+
+Agents are **ephemeral bursts of intent**. Humans are persistent. Yet today's
+agents execute with persistent, human-shaped credentials and unbounded scope.
+One leaked key compromises everything, and there's no signed proof of *why* the
+agent did what it did.
+
+## The Inversion
+
+| Human model | Agent model (GHOST) |
+|---|---|
+| log in → do stuff → log out | declare intent → **spawn** → execute → **evaporate** → leave **residue** |
+| session persists | session auto-expires (TTL) |
+| broad standing access | scoped to declared tools |
+| audit logs (unsigned) | Ed25519-signed, tamper-evident chain |
+
+---
+
+## The Ritual (Quickstart)
+
+```bash
+pip install ghost-layer
+
+ghost spawn --intent "deploy_staging" --ttl 300 --scope aws_ec2
+ghost act   --tool aws_ec2 --action RunInstances --session-id gh_9ddb...
+ghost evaporate --session-id gh_9ddb...
+ghost replay    --session-id gh_9ddb...
+```
+
+What just happened: your agent never held a standing credential. The session
+lived under a second. The residue is **Ed25519-signed** and immutable — replay
+it and verify exactly why that instance spawned.
+
+Out-of-scope calls are refused before they run:
+
+```bash
+ghost act --tool stripe --action CreateCharge --session-id gh_9ddb...
+# DENIED (scope): tool 'stripe' not in session scopes ['aws_ec2']   (exit 2)
+```
+
+---
+
+## Five Commands
+
+| Command | What it does |
+|---|---|
+| `ghost spawn` | Mint an ephemeral session + fresh Ed25519 keypair, TTL countdown begins |
+| `ghost possess` | Bind an agent to the session via the intercept proxy |
+| `ghost act` | Record a **scoped, signed** action (blocked if out-of-scope or expired) |
+| `ghost evaporate` | Shred the key, sign the whole action chain, finalize the residue |
+| `ghost replay` | Re-verify every signature + the root chain signature |
+
+---
+
+## Use It In Code (SDK-agnostic)
+
+The transport is injected, so GHOST wraps **any** HTTP client or agent
+framework — LangChain, the OpenAI SDK, raw `requests`/`httpx`:
+
+```python
+from ghost import spawn, possess, evaporate, replay
+from ghost.store import ResidueStore
+import requests
+
+store = ResidueStore()
+session = spawn(store, intent="enrich_lead", ttl=120, scopes=["httpbin"])
+
+def transport(method, url, headers=None, **kw):
+    return requests.request(method, url, headers=headers, **kw)
+
+proxy = possess(store, session["session_id"], transport, token="ghtok_demo")
+
+# Auth headers the agent sets are STRIPPED; the ghost token is injected.
+proxy.request("POST", "https://httpbin.org/post",
+              tool="httpbin", action="submit",
+              headers={"Authorization": "Bearer WILL_BE_STRIPPED"})
+
+evaporate(store, session["session_id"])
+print(replay(store, session["session_id"])["verified"])   # True
+```
+
+See [`examples/`](examples/) for a LangChain-style agent and an
+**x402 / XRPL payment agent** that settles a micropayment through a single
+60-second ghost body.
+
+---
+
+## Why It's Tamper-Evident
+
+Every action is signed over a canonical hash binding `session_id`, sequence,
+tool, action, and the hashes of params/response. At `evaporate`, a **root
+signature** covers the ordered chain. Change one byte of the residue and
+`ghost replay` reports `verified: false`. The private key is gone by then — it
+**cannot** be re-signed.
+
+```text
+spawn ─▶ keypair (priv on disk 0600, pub in residue)
+  │
+  ├─ act ─▶ sign(payload)  ─▶ residue row
+  ├─ act ─▶ sign(payload)  ─▶ residue row
+  │
+evaporate ─▶ sign(chain) = root_sig ─▶ shred priv key
+  │
+replay ─▶ verify(each) + verify(root)   ✓ tamper-evident
+```
+
+---
+
+## Where It Fits
+
+GHOST is the execution-safety layer beneath the **x402 agentic web**. It lets
+autonomous agents trigger payment rails ([NEXUS-402](https://nexus-402.com),
+402Proof, XAH Portal) and act on [SqueezeOS](https://scriptmasterlabs.com)
+signals **without ever holding a standing key** — every autonomous move leaves
+a signed receipt.
+
+Full catalog: **[scriptmasterlabs.com/stack](https://scriptmasterlabs.com/stack)**
+
+---
+
+## Status & Roadmap
+
+- [x] Python CLI — spawn / possess / act / evaporate / replay
+- [x] SQLite residue store, Ed25519 signing, scope + TTL enforcement
+- [x] Intercept proxy (SDK-agnostic), tamper-detection tests (17 passing)
+- [ ] Rust proxy core (performance)
+- [ ] Native LangChain / OpenAI tool wrappers
+- [ ] Pre/post validation hooks, webhook notifications
+- [ ] Optional cloud-hosted proxy
+
+---
+
+## Install from source
+
+```bash
+git clone https://github.com/timwal78/ghost-layer
+cd ghost-layer
+pip install -e ".[dev]"
+pytest -q          # 17 passed
+```
+
+---
+
+Built by **Script Master Labs LLC** · Disabled U.S. Army Veteran–Owned (SDVOSB) · Kinston, NC
+Docs: [ARCHITECTURE.md](docs/ARCHITECTURE.md) · [SECURITY.md](docs/SECURITY.md) · MIT License

ghost_layer-0.1.0/ghost/__init__.py

@@ -0,0 +1,27 @@
+"""GHOST — The Spectral Execution Layer for Autonomous Agents.
+
+Ephemeral, scoped, signed execution for AI agents. Spawn a short-lived session,
+route the agent's actions through an intercept that records cryptographic
+residue, then evaporate — leaving a tamper-evident audit trail.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "Timothy Walton (Script Master Labs LLC)"
+__license__ = "MIT"
+
+from .session import act, evaporate, replay, spawn  # noqa: E402
+from .store import ResidueStore  # noqa: E402
+from .proxy import GhostProxy, possess  # noqa: E402
+
+__all__ = [
+    "spawn",
+    "act",
+    "evaporate",
+    "replay",
+    "possess",
+    "GhostProxy",
+    "ResidueStore",
+    "__version__",
+]

ghost_layer-0.1.0/ghost/cli.py

@@ -0,0 +1,206 @@
+"""GHOST command-line interface.
+
+Give your AI agent a body that vanishes. Thin Click layer over ghost.session.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import click
+
+from . import __version__
+from . import session as _session
+from .session import (
+    ExpiredSessionError,
+    ScopeError,
+    SessionError,
+)
+from .store import ResidueStore
+
+GREEN = "green"
+GOLD = "yellow"
+PINK = "magenta"
+CYAN = "cyan"
+RED = "red"
+
+
+def _emit(obj: dict, color: str) -> None:
+    click.secho(json.dumps(obj, indent=2), fg=color)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="ghost")
+@click.option("--db", type=click.Path(), default=None, help="Override residue DB path.")
+@click.pass_context
+def cli(ctx: click.Context, db: Optional[str]) -> None:
+    """GHOST — Ephemeral Execution Layer for Autonomous Agents.
+
+    Declare intent -> spawn -> execute -> evaporate -> leave signed residue.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["store"] = ResidueStore(db)
+
+
+@cli.command()
+@click.option("--intent", required=True, help="Human-readable intent, e.g. 'deploy_staging'.")
+@click.option("--ttl", default=300, show_default=True, help="Session lifetime in seconds.")
+@click.option("--scope", multiple=True, help="Allowed tool scope (repeatable).")
+@click.pass_context
+def spawn(ctx: click.Context, intent: str, ttl: int, scope: tuple) -> None:
+    """Spawn an ephemeral session with a fresh signing key."""
+    store: ResidueStore = ctx.obj["store"]
+    result = _session.spawn(store, intent=intent, ttl=ttl, scopes=list(scope))
+    _emit(result, GREEN)
+    click.secho(
+        f"\nEphemeral session spawned: {result['session_id']}", fg=GREEN, bold=True
+    )
+    click.secho(
+        f"  TTL {ttl}s  |  scopes: {', '.join(scope) if scope else '(none)'}", fg=CYAN
+    )
+
+
+@cli.command()
+@click.option("--agent", required=True, help="Agent identifier, e.g. openai://gpt-4.")
+@click.option("--session-id", required=True, help="Session from 'ghost spawn'.")
+@click.option("--port", default=9999, show_default=True, help="Proxy listen port.")
+@click.pass_context
+def possess(ctx: click.Context, agent: str, session_id: str, port: int) -> None:
+    """Bind an agent to the session via the local intercept proxy."""
+    store: ResidueStore = ctx.obj["store"]
+    row = store.get_session(session_id)
+    if row is None:
+        click.secho(f"Error: session {session_id} not found", fg=RED)
+        sys.exit(1)
+    if row["evaporated_at"]:
+        click.secho(f"Error: session {session_id} already evaporated", fg=RED)
+        sys.exit(1)
+    click.secho(f"Proxy ready on localhost:{port}", fg=CYAN, bold=True)
+    click.secho(f"  agent   : {agent}", fg=CYAN)
+    click.secho(f"  session : {session_id}", fg=CYAN)
+    click.secho(f"  scopes  : {row['scopes'] or '(none)'}", fg=CYAN)
+    click.secho("\n  Route agent HTTP through GhostProxy (see examples/). ", fg=GOLD)
+
+
+@cli.command()
+@click.option("--tool", required=True, help="Tool name, e.g. aws_ec2.")
+@click.option("--action", required=True, help="Action name, e.g. RunInstances.")
+@click.option("--params", type=click.File("r"), default=None, help="JSON params file.")
+@click.option("--session-id", required=True, help="Target session.")
+@click.option("--no-scope", is_flag=True, help="Disable scope enforcement.")
+@click.pass_context
+def act(
+    ctx: click.Context,
+    tool: str,
+    action: str,
+    params: Optional[click.File],
+    session_id: str,
+    no_scope: bool,
+) -> None:
+    """Record a scoped, signed action against the session."""
+    store: ResidueStore = ctx.obj["store"]
+    payload = json.load(params) if params else {}
+    try:
+        result = _session.act(
+            store,
+            session_id,
+            tool=tool,
+            action=action,
+            params=payload,
+            enforce_scope=not no_scope,
+        )
+    except ScopeError as e:
+        click.secho(f"DENIED (scope): {e}", fg=RED)
+        sys.exit(2)
+    except ExpiredSessionError as e:
+        click.secho(f"DENIED (expired): {e}", fg=RED)
+        sys.exit(3)
+    except SessionError as e:
+        click.secho(f"Error: {e}", fg=RED)
+        sys.exit(1)
+    _emit(result, GREEN)
+    click.secho("\n  action signed + logged to residue", fg=GREEN)
+
+
+@cli.command()
+@click.option("--session-id", required=True, help="Session to evaporate.")
+@click.pass_context
+def evaporate(ctx: click.Context, session_id: str) -> None:
+    """Destroy the key, sign the chain, finalize the residue."""
+    store: ResidueStore = ctx.obj["store"]
+    try:
+        result = _session.evaporate(store, session_id)
+    except SessionError as e:
+        click.secho(f"Error: {e}", fg=RED)
+        sys.exit(1)
+    _emit(result, GOLD)
+    click.secho("\n  Session evaporated. Ephemeral key shredded.", fg=PINK, bold=True)
+
+
+@cli.command()
+@click.option("--session-id", default=None, help="Session to replay.")
+@click.option("--all", "all_", is_flag=True, help="List all sessions.")
+@click.option(
+    "--format", "fmt", type=click.Choice(["json", "csv"]), default="json", show_default=True
+)
+@click.pass_context
+def replay(ctx: click.Context, session_id: Optional[str], all_: bool, fmt: str) -> None:
+    """Retrieve and verify signed execution history."""
+    store: ResidueStore = ctx.obj["store"]
+    if all_:
+        rows = store.list_sessions()
+        if fmt == "csv":
+            click.echo("session_id,intent,spawned_at,evaporated_at,actions")
+            for r in rows:
+                n = store.count_actions(r["session_id"])
+                click.echo(
+                    f"{r['session_id']},{r['intent']},{r['spawned_at']},"
+                    f"{r['evaporated_at'] or ''},{n}"
+                )
+        else:
+            for r in rows:
+                _emit(
+                    {
+                        "session_id": r["session_id"],
+                        "intent": r["intent"],
+                        "spawned_at": r["spawned_at"],
+                        "evaporated_at": r["evaporated_at"],
+                        "actions": store.count_actions(r["session_id"]),
+                    },
+                    GREEN,
+                )
+        return
+
+    if not session_id:
+        click.secho("Error: provide --session-id or --all", fg=RED)
+        sys.exit(1)
+    try:
+        result = _session.replay(store, session_id)
+    except SessionError as e:
+        click.secho(f"Error: {e}", fg=RED)
+        sys.exit(1)
+
+    if fmt == "csv":
+        click.echo("seq,tool,action,timestamp,verified")
+        for a in result["actions"]:
+            click.echo(
+                f"{a['seq']},{a['tool']},{a['action']},{a['timestamp']},{a['verified']}"
+            )
+        click.echo(f"# root_verified={result['root_verified']} verified={result['verified']}")
+    else:
+        _emit(result, GREEN if result["verified"] else RED)
+    if result["verified"]:
+        click.secho("\n  residue verified", fg=GREEN, bold=True)
+    else:
+        click.secho("\n  RESIDUE VERIFICATION FAILED", fg=RED, bold=True)
+        sys.exit(4)
+
+
+def main() -> None:
+    cli(obj={})
+
+
+if __name__ == "__main__":
+    main()

ghost_layer-0.1.0/ghost/crypto.py

@@ -0,0 +1,62 @@
+"""Cryptographic primitives for GHOST.
+
+Ed25519 signing of residue entries plus SHA-256 hashing helpers. The signing
+key is generated per-session at spawn time and destroyed at evaporate time;
+only the public (verifying) key is persisted so the audit trail can be verified
+after the session is gone.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+
+def generate_keypair() -> tuple[bytes, bytes]:
+    """Return (private_seed_32b, public_raw_32b) for a fresh Ed25519 key."""
+    sk = Ed25519PrivateKey.generate()
+    private_seed = sk.private_bytes_raw()
+    public_raw = sk.public_key().public_bytes_raw()
+    return private_seed, public_raw
+
+
+def sign(private_seed: bytes, message: bytes) -> str:
+    """Sign message with the private seed; return base64 signature."""
+    sk = Ed25519PrivateKey.from_private_bytes(private_seed)
+    sig = sk.sign(message)
+    return base64.b64encode(sig).decode("ascii")
+
+
+def verify(public_raw: bytes, message: bytes, signature_b64: str) -> bool:
+    """Verify a base64 signature against message using the raw public key."""
+    try:
+        pk = Ed25519PublicKey.from_public_bytes(public_raw)
+        pk.verify(base64.b64decode(signature_b64), message)
+        return True
+    except (InvalidSignature, ValueError):
+        return False
+
+
+def b64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def unb64(text: str) -> bytes:
+    return base64.b64decode(text)
+
+
+def sha256_hex(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def canonical_hash(obj: Any) -> str:
+    """Deterministic SHA-256 over a JSON-serialisable object."""
+    return sha256_hex(json.dumps(obj, sort_keys=True, separators=(",", ":")))