ghost-layer 0.1.0__py3-none-any.whl

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/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/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=(",", ":")))

ghost/proxy.py

@@ -0,0 +1,109 @@
+"""Agent-side intercept for GHOST.
+
+`possess()` returns a callable proxy that wraps an HTTP transport. Every mutating
+call the agent makes is mapped to a ghost.act() residue entry before the real
+call is dispatched, and the ephemeral session token is injected while any caller
+credentials are stripped. This module has no hard dependency on `requests`; the
+transport is injected, which keeps it unit-testable and SDK-agnostic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from . import session as _session
+from .store import ResidueStore
+
+MUTATING_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+
+class GhostProxy:
+    """Intercepts HTTP calls, records signed residue, then dispatches.
+
+    transport: a callable (method, url, **kwargs) -> response-like object with
+    at least a `.status_code` attribute and optional `.json()` method. Inject a
+    real adapter (requests/httpx) in production; inject a fake in tests.
+    """
+
+    def __init__(
+        self,
+        store: ResidueStore,
+        session_id: str,
+        transport: Callable[..., Any],
+        token: str,
+        enforce_scope: bool = True,
+    ) -> None:
+        self.store = store
+        self.session_id = session_id
+        self.transport = transport
+        self.token = token
+        self.enforce_scope = enforce_scope
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        tool: str,
+        action: str,
+        params: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        method = method.upper()
+        headers = dict(headers or {})
+
+        # Strip any caller-supplied auth; inject the ephemeral ghost token.
+        for h in list(headers):
+            if h.lower() in {"authorization", "x-api-key", "api-key"}:
+                headers.pop(h)
+        headers["X-Ghost-Token"] = self.token
+        headers["X-Ghost-Session"] = self.session_id
+
+        # Reads are dispatched without a residue entry unless mutating.
+        if method not in MUTATING_METHODS:
+            return self.transport(method, url, headers=headers, **kwargs)
+
+        # Record intent BEFORE dispatch so a crash still leaves a trace.
+        record = _session.act(
+            self.store,
+            self.session_id,
+            tool=tool,
+            action=action,
+            params=params or {"url": url, "method": method},
+            response=None,
+            http_status=0,
+            enforce_scope=self.enforce_scope,
+        )
+
+        resp = self.transport(method, url, headers=headers, **kwargs)
+        status = getattr(resp, "status_code", 0)
+
+        # Post-dispatch we record the response as a follow-on signed entry.
+        body: Optional[dict[str, Any]] = None
+        json_fn = getattr(resp, "json", None)
+        if callable(json_fn):
+            try:
+                body = json_fn()
+            except Exception:
+                body = None
+        _session.act(
+            self.store,
+            self.session_id,
+            tool=tool,
+            action=f"{action}:response",
+            params={"action_id": record["action_id"]},
+            response=body if isinstance(body, dict) else {"status": status},
+            http_status=status,
+            enforce_scope=False,  # response logging is never scope-blocked
+        )
+        return resp
+
+
+def possess(
+    store: ResidueStore,
+    session_id: str,
+    transport: Callable[..., Any],
+    token: str,
+    enforce_scope: bool = True,
+) -> GhostProxy:
+    return GhostProxy(store, session_id, transport, token, enforce_scope)

ghost/session.py

@@ -0,0 +1,307 @@
+"""Session lifecycle for GHOST.
+
+Pure logic layer (no CLI, no I/O formatting) so it is unit-testable. Ephemeral
+private keys live on disk under GHOST_HOME/sessions/<id>/ for the lifetime of
+the session and are shredded at evaporate.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+import shutil
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from . import crypto
+from .store import GHOST_HOME, ResidueStore
+
+SESSIONS_DIR = GHOST_HOME / "sessions"
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def _parse_iso(text: str) -> datetime:
+    return datetime.strptime(text, "%Y-%m-%dT%H:%M:%S.%fZ").replace(tzinfo=timezone.utc)
+
+
+def _session_dir(session_id: str) -> Path:
+    return SESSIONS_DIR / session_id
+
+
+def _fingerprint(public_raw: bytes) -> str:
+    return crypto.sha256_hex(crypto.b64(public_raw))[:16]
+
+
+class SessionError(Exception):
+    pass
+
+
+class ExpiredSessionError(SessionError):
+    pass
+
+
+class ScopeError(SessionError):
+    pass
+
+
+def spawn(
+    store: ResidueStore,
+    intent: str,
+    ttl: int = 300,
+    scopes: Optional[list[str]] = None,
+) -> dict[str, Any]:
+    """Create an ephemeral session and persist a session record."""
+    scopes = scopes or []
+    session_id = "gh_" + secrets.token_hex(16)
+
+    private_seed, public_raw = crypto.generate_keypair()
+    sdir = _session_dir(session_id)
+    sdir.mkdir(parents=True, exist_ok=True)
+    key_path = sdir / "ed25519_seed"
+    # 0600 so other users on the box cannot read the ephemeral key
+    fd = os.open(key_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "wb") as fh:
+        fh.write(private_seed)
+
+    spawned = _now()
+    expires = spawned + timedelta(seconds=ttl)
+    public_b64 = crypto.b64(public_raw)
+
+    store.insert_session(
+        {
+            "session_id": session_id,
+            "intent": intent,
+            "scopes": ",".join(scopes),
+            "public_key": public_b64,
+            "spawned_at": _iso(spawned),
+            "ttl_seconds": ttl,
+            "expires_at": _iso(expires),
+        }
+    )
+    store.log_credential(session_id, _fingerprint(public_raw), "spawn", _iso(spawned))
+
+    return {
+        "session_id": session_id,
+        "intent": intent,
+        "scopes": scopes,
+        "public_key": public_b64,
+        "spawned_at": _iso(spawned),
+        "expires_at": _iso(expires),
+        "ttl_seconds": ttl,
+    }
+
+
+def _load_seed(session_id: str) -> bytes:
+    key_path = _session_dir(session_id) / "ed25519_seed"
+    if not key_path.exists():
+        raise SessionError(f"ephemeral key for {session_id} not found (already evaporated?)")
+    return key_path.read_bytes()
+
+
+def act(
+    store: ResidueStore,
+    session_id: str,
+    tool: str,
+    action: str,
+    params: Optional[dict[str, Any]] = None,
+    response: Optional[dict[str, Any]] = None,
+    http_status: int = 200,
+    enforce_scope: bool = True,
+) -> dict[str, Any]:
+    """Record a scoped, signed action against a live session."""
+    row = store.get_session(session_id)
+    if row is None:
+        raise SessionError(f"session {session_id} not found")
+    if row["evaporated_at"]:
+        raise ExpiredSessionError(f"session {session_id} already evaporated")
+    if _now() > _parse_iso(row["expires_at"]):
+        raise ExpiredSessionError(f"session {session_id} TTL expired at {row['expires_at']}")
+
+    scopes = [s for s in (row["scopes"] or "").split(",") if s]
+    if enforce_scope and scopes and tool not in scopes:
+        raise ScopeError(f"tool '{tool}' not in session scopes {scopes}")
+
+    params = params or {}
+    seed = _load_seed(session_id)
+    seq = store.next_seq(session_id)
+    action_id = "act_" + secrets.token_hex(8)
+    ts = _iso(_now())
+
+    params_hash = crypto.canonical_hash(params)
+    response_hash = crypto.canonical_hash(response) if response is not None else None
+
+    # The signed payload binds order, identity, tool, action, and data hashes.
+    payload = {
+        "session_id": session_id,
+        "seq": seq,
+        "action_id": action_id,
+        "tool": tool,
+        "action": action,
+        "params_hash": params_hash,
+        "response_hash": response_hash,
+        "http_status": http_status,
+        "timestamp": ts,
+    }
+    signature = crypto.sign(seed, crypto.canonical_hash(payload).encode())
+
+    store.insert_action(
+        {
+            "action_id": action_id,
+            "session_id": session_id,
+            "seq": seq,
+            "tool": tool,
+            "action": action,
+            "params_hash": params_hash,
+            "response_hash": response_hash,
+            "http_status": http_status,
+            "decision": "executed",
+            "timestamp": ts,
+            "signature": signature,
+        }
+    )
+
+    return {
+        "action_id": action_id,
+        "session_id": session_id,
+        "seq": seq,
+        "tool": tool,
+        "action": action,
+        "params_hash": params_hash,
+        "response_hash": response_hash,
+        "http_status": http_status,
+        "timestamp": ts,
+        "signature": signature,
+    }
+
+
+def evaporate(store: ResidueStore, session_id: str) -> dict[str, Any]:
+    """Destroy the ephemeral key, sign the action chain, finalize the record."""
+    row = store.get_session(session_id)
+    if row is None:
+        raise SessionError(f"session {session_id} not found")
+    if row["evaporated_at"]:
+        raise SessionError(f"session {session_id} already evaporated")
+
+    seed = _load_seed(session_id)
+    actions = store.actions_for(session_id)
+    chain = [
+        {
+            "seq": a["seq"],
+            "action_id": a["action_id"],
+            "signature": a["signature"],
+        }
+        for a in actions
+    ]
+    root_signature = crypto.sign(
+        seed, crypto.canonical_hash({"session_id": session_id, "chain": chain}).encode()
+    )
+
+    evaporated = _now()
+    spawned = _parse_iso(row["spawned_at"])
+    lived = (evaporated - spawned).total_seconds()
+
+    store.finalize_session(session_id, _iso(evaporated), lived, root_signature)
+    store.log_credential(
+        session_id,
+        _fingerprint(crypto.unb64(row["public_key"])),
+        "evaporate",
+        _iso(evaporated),
+    )
+
+    # Shred the key material and remove the session directory.
+    sdir = _session_dir(session_id)
+    key_path = sdir / "ed25519_seed"
+    if key_path.exists():
+        with open(key_path, "wb") as fh:
+            fh.write(secrets.token_bytes(len(seed)))
+            fh.flush()
+            os.fsync(fh.fileno())
+    if sdir.exists():
+        shutil.rmtree(sdir)
+
+    return {
+        "session_id": session_id,
+        "intent": row["intent"],
+        "status": "evaporated",
+        "lived_for_seconds": round(lived, 3),
+        "actions_executed": len(actions),
+        "root_signature": root_signature,
+        "evaporated_at": _iso(evaporated),
+    }
+
+
+def replay(store: ResidueStore, session_id: str) -> dict[str, Any]:
+    """Return the full session record plus verification result."""
+    row = store.get_session(session_id)
+    if row is None:
+        raise SessionError(f"session {session_id} not found")
+
+    public_raw = crypto.unb64(row["public_key"])
+    actions = store.actions_for(session_id)
+
+    verified_actions = []
+    all_ok = True
+    for a in actions:
+        payload = {
+            "session_id": session_id,
+            "seq": a["seq"],
+            "action_id": a["action_id"],
+            "tool": a["tool"],
+            "action": a["action"],
+            "params_hash": a["params_hash"],
+            "response_hash": a["response_hash"],
+            "http_status": a["http_status"],
+            "timestamp": a["timestamp"],
+        }
+        ok = crypto.verify(public_raw, crypto.canonical_hash(payload).encode(), a["signature"])
+        all_ok = all_ok and ok
+        verified_actions.append(
+            {
+                "seq": a["seq"],
+                "action_id": a["action_id"],
+                "tool": a["tool"],
+                "action": a["action"],
+                "params_hash": a["params_hash"],
+                "response_hash": a["response_hash"],
+                "http_status": a["http_status"],
+                "timestamp": a["timestamp"],
+                "signature": a["signature"],
+                "verified": ok,
+            }
+        )
+
+    root_ok = None
+    if row["root_signature"]:
+        chain = [
+            {"seq": a["seq"], "action_id": a["action_id"], "signature": a["signature"]}
+            for a in actions
+        ]
+        root_ok = crypto.verify(
+            public_raw,
+            crypto.canonical_hash({"session_id": session_id, "chain": chain}).encode(),
+            row["root_signature"],
+        )
+        all_ok = all_ok and root_ok
+
+    return {
+        "session_id": session_id,
+        "intent": row["intent"],
+        "scopes": [s for s in (row["scopes"] or "").split(",") if s],
+        "spawned_at": row["spawned_at"],
+        "expires_at": row["expires_at"],
+        "evaporated_at": row["evaporated_at"],
+        "lived_for_seconds": row["lived_seconds"],
+        "public_key": row["public_key"],
+        "actions": verified_actions,
+        "root_signature": row["root_signature"],
+        "root_verified": root_ok,
+        "verified": all_ok,
+    }

ghost/store.py

@@ -0,0 +1,148 @@
+"""SQLite residue store for GHOST.
+
+Append-only audit log of sessions and the actions executed within them. Each
+action carries a hash of its params/response and an Ed25519 signature. At
+evaporate time a root signature is computed over the ordered action chain,
+making any later tampering detectable.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+from typing import Any, Optional
+
+GHOST_HOME = Path(os.environ.get("GHOST_HOME", Path.home() / ".ghost"))
+DEFAULT_DB = GHOST_HOME / "residue.db"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id      TEXT PRIMARY KEY,
+    intent          TEXT NOT NULL,
+    scopes          TEXT NOT NULL DEFAULT '',
+    public_key      TEXT NOT NULL,
+    spawned_at      TEXT NOT NULL,
+    ttl_seconds     INTEGER NOT NULL,
+    expires_at      TEXT NOT NULL,
+    evaporated_at   TEXT,
+    lived_seconds   REAL,
+    root_signature  TEXT
+);
+
+CREATE TABLE IF NOT EXISTS actions (
+    action_id       TEXT PRIMARY KEY,
+    session_id      TEXT NOT NULL,
+    seq             INTEGER NOT NULL,
+    tool            TEXT NOT NULL,
+    action          TEXT NOT NULL,
+    params_hash     TEXT NOT NULL,
+    response_hash   TEXT,
+    http_status     INTEGER,
+    decision        TEXT NOT NULL DEFAULT 'executed',
+    timestamp       TEXT NOT NULL,
+    signature       TEXT NOT NULL,
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+CREATE TABLE IF NOT EXISTS credentials_log (
+    session_id      TEXT NOT NULL,
+    key_fingerprint TEXT NOT NULL,
+    event           TEXT NOT NULL,
+    timestamp       TEXT NOT NULL,
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_spawned ON sessions(spawned_at DESC);
+CREATE INDEX IF NOT EXISTS idx_actions_session ON actions(session_id, seq);
+"""
+
+
+class ResidueStore:
+    def __init__(self, db_path: Optional[Path] = None) -> None:
+        self.db_path = Path(db_path) if db_path else DEFAULT_DB
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(self.db_path)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+
+    # ---- sessions ---------------------------------------------------------
+    def insert_session(self, row: dict[str, Any]) -> None:
+        self._conn.execute(
+            """INSERT INTO sessions
+               (session_id, intent, scopes, public_key, spawned_at,
+                ttl_seconds, expires_at)
+               VALUES (:session_id, :intent, :scopes, :public_key, :spawned_at,
+                       :ttl_seconds, :expires_at)""",
+            row,
+        )
+        self._conn.commit()
+
+    def get_session(self, session_id: str) -> Optional[sqlite3.Row]:
+        cur = self._conn.execute(
+            "SELECT * FROM sessions WHERE session_id = ?", (session_id,)
+        )
+        return cur.fetchone()
+
+    def finalize_session(
+        self, session_id: str, evaporated_at: str, lived_seconds: float, root_signature: str
+    ) -> None:
+        self._conn.execute(
+            """UPDATE sessions
+               SET evaporated_at = ?, lived_seconds = ?, root_signature = ?
+               WHERE session_id = ?""",
+            (evaporated_at, lived_seconds, root_signature, session_id),
+        )
+        self._conn.commit()
+
+    def list_sessions(self, limit: int = 50) -> list[sqlite3.Row]:
+        cur = self._conn.execute(
+            "SELECT * FROM sessions ORDER BY spawned_at DESC LIMIT ?", (limit,)
+        )
+        return cur.fetchall()
+
+    # ---- actions ----------------------------------------------------------
+    def next_seq(self, session_id: str) -> int:
+        cur = self._conn.execute(
+            "SELECT COALESCE(MAX(seq), 0) + 1 AS n FROM actions WHERE session_id = ?",
+            (session_id,),
+        )
+        return int(cur.fetchone()["n"])
+
+    def insert_action(self, row: dict[str, Any]) -> None:
+        self._conn.execute(
+            """INSERT INTO actions
+               (action_id, session_id, seq, tool, action, params_hash,
+                response_hash, http_status, decision, timestamp, signature)
+               VALUES (:action_id, :session_id, :seq, :tool, :action, :params_hash,
+                       :response_hash, :http_status, :decision, :timestamp, :signature)""",
+            row,
+        )
+        self._conn.commit()
+
+    def actions_for(self, session_id: str) -> list[sqlite3.Row]:
+        cur = self._conn.execute(
+            "SELECT * FROM actions WHERE session_id = ? ORDER BY seq ASC",
+            (session_id,),
+        )
+        return cur.fetchall()
+
+    def count_actions(self, session_id: str) -> int:
+        cur = self._conn.execute(
+            "SELECT COUNT(*) AS c FROM actions WHERE session_id = ?", (session_id,)
+        )
+        return int(cur.fetchone()["c"])
+
+    # ---- credentials ------------------------------------------------------
+    def log_credential(self, session_id: str, fingerprint: str, event: str, ts: str) -> None:
+        self._conn.execute(
+            """INSERT INTO credentials_log (session_id, key_fingerprint, event, timestamp)
+               VALUES (?, ?, ?, ?)""",
+            (session_id, fingerprint, event, ts),
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()

ghost_layer-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+ghost/__init__.py,sha256=iNtWEHjRZi7XsQ8PBMUYLVFTVyRnDFVYWVvfdNb-BYc,731
+ghost/cli.py,sha256=Pxk4EisY1RHh8HH4HRoF3BGJZVasUA_VY8kdK1J0qzw,7111
+ghost/crypto.py,sha256=jjiHwZEsIPbVJibMzJtoRDL1bk2_lWQ1mYb8NmwSWag,1923
+ghost/proxy.py,sha256=AaTP3wj5NVkyjgtDI39b033otCPPHTsZriPyefRw4oE,3598
+ghost/session.py,sha256=g-CSSrqvF7UC9ClAahPFkwmwbXZ4TYkbhUrXSzTNkn4,9369
+ghost/store.py,sha256=IiyW9zAGpJam5-0DCJVbcpQaZGjDwGAasW_igXDFBhg,5396
+ghost_layer-0.1.0.dist-info/licenses/LICENSE,sha256=emBVfKHqKE_XRCXAgZUcCPHT0bZKXSDGLmSxxMU3100,1096
+ghost_layer-0.1.0.dist-info/METADATA,sha256=wNmMlxOaIqRnwJj7ukBIdoLYzratNJipKTGDnAMzl6Y,6997
+ghost_layer-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ghost_layer-0.1.0.dist-info/entry_points.txt,sha256=2wrE4K_rV0tiQ94jZ-g-ifQid6iFQzVeBUWKut2XKuw,41
+ghost_layer-0.1.0.dist-info/top_level.txt,sha256=frV3IWB1-bLZC7XzliilZbAe-3CweZiXnQ8dy57Xpf8,6
+ghost_layer-0.1.0.dist-info/RECORD,,

ghost_layer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ghost_layer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ghost = ghost.cli:main

ghost_layer-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+ghost