elpis-cli 0.1.0__py3-none-any.whl

elpis_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Elpis Protocol CLI -- Agent Identity & Interaction."""
+
+__version__ = "0.1.0"

elpis_cli/cli.py

@@ -0,0 +1,358 @@
+"""Elpis CLI entry point."""
+
+import asyncio
+import json
+import sys
+
+import click
+
+from . import __version__
+from .config import (
+    ensure_dir,
+    identity_exists,
+    load_identity,
+    load_private_key,
+    save_identity,
+    save_private_key,
+)
+from .identity import build_identity, generate_keypair, load_keypair_from_file
+
+
+@click.group()
+@click.version_option(__version__)
+def cli():
+    """Elpis Protocol CLI -- Agent Identity & Interaction."""
+    pass
+
+
+@cli.command()
+@click.option("--name", prompt="Agent name", help="Display name for this identity.")
+@click.option("--provider", default="", help="Provider name (e.g. efiniti).")
+@click.option("--role", default="", help="Agent role description.")
+@click.option(
+    "--network",
+    default="testnet",
+    type=click.Choice(["testnet", "mainnet"]),
+    help="XRPL network for DID registration.",
+)
+@click.option(
+    "--key",
+    "key_path",
+    default=None,
+    type=click.Path(exists=True),
+    help="Path to existing Ed25519 private key file.",
+)
+@click.option("--force", is_flag=True, help="Overwrite existing identity.")
+@click.option(
+    "--register/--no-register",
+    default=True,
+    help="Register DID on XRPL (requires network access).",
+)
+@click.option("--wallet-address", default=None, help="XRPL wallet r-address (mainnet only).")
+@click.option("--wallet-secret", default=None, help="XRPL wallet secret (mainnet only).")
+def init(name, provider, role, network, key_path, force, register, wallet_address, wallet_secret):
+    """Initialize a new Elpis identity.
+
+    Generates an Ed25519 keypair, creates a DID, and optionally
+    registers it on the XRPL Testnet.
+    """
+    # Check existing identity
+    if identity_exists() and not force:
+        existing = load_identity()
+        if existing:
+            click.echo(f"Identity already exists: {existing.get('did', '?')}")
+            click.echo("Use --force to overwrite.")
+            sys.exit(1)
+
+    # Generate or load keypair
+    if key_path:
+        click.echo(f"Loading key from {key_path}...")
+        try:
+            private_seed, public_key = load_keypair_from_file(key_path)
+        except Exception as exc:
+            click.echo(f"Error loading key: {exc}", err=True)
+            sys.exit(1)
+        click.echo("Key loaded successfully.")
+    else:
+        click.echo("Generating Ed25519 keypair...")
+        private_seed, public_key = generate_keypair()
+        click.echo("Keypair generated.")
+
+    # Build identity
+    identity = build_identity(
+        name=name,
+        provider=provider,
+        role=role,
+        network=network,
+        private_seed=private_seed,
+        public_key=public_key,
+    )
+
+    # Save to ~/.elpis/
+    ensure_dir()
+    save_private_key(private_seed.hex())
+    save_identity(identity)
+    click.echo("Identity saved to ~/.elpis/")
+
+    # XRPL registration: full chain (DIDSet -> MPT -> Credential)
+    if register:
+        if network == "testnet":
+            click.echo("Registering on XRPL Testnet (Faucet -> DIDSet -> MPT -> Credential)...")
+            from .xrpl_client import register_did_testnet
+
+            result = asyncio.run(
+                register_did_testnet(
+                    did=identity["did"],
+                    public_key_hex=identity["public_key"],
+                    name=name,
+                )
+            )
+        elif network == "mainnet":
+            if not wallet_address or not wallet_secret:
+                wallet_address = wallet_address or click.prompt("XRPL wallet address (r...)")
+                wallet_secret = wallet_secret or click.prompt("XRPL wallet secret", hide_input=True)
+
+            click.echo("Registering on XRPL Mainnet (DIDSet -> MPT -> Credential)...")
+            click.echo("Each transaction requires your confirmation.")
+            from .xrpl_client import register_did_mainnet, TX_DESCRIPTIONS
+
+            def _confirm(step_name, tx_type, fee_xrp, reserve_xrp):
+                desc = TX_DESCRIPTIONS.get(tx_type, tx_type)
+                click.echo(f"\n  TX: {desc}")
+                click.echo(f"  Fee: {fee_xrp:.6f} XRP | Reserve: {reserve_xrp:.1f} XRP")
+                return click.confirm("  Submit?", default=True)
+
+            result = asyncio.run(
+                register_did_mainnet(
+                    did=identity["did"],
+                    public_key_hex=identity["public_key"],
+                    name=name,
+                    wallet_address=wallet_address,
+                    wallet_secret=wallet_secret,
+                    confirm_fn=_confirm,
+                )
+            )
+            if result and result.get("balance_xrp") is not None:
+                click.echo(f"  Balance:    {result['balance_xrp']:.2f} XRP")
+            if result and result.get("estimated_cost"):
+                cost = result["estimated_cost"]
+                click.echo(f"  Est. cost:  {cost['total_xrp']:.6f} XRP (fees + reserve)")
+        else:
+            result = None
+
+        if result:
+            if result.get("address"):
+                identity["xrpl_address"] = result["address"]
+                click.echo(f"  Wallet:     {result['address']}")
+
+            steps = result.get("steps", {})
+            for step_name, step_data in steps.items():
+                if step_data.get("skipped"):
+                    status = "SKIPPED"
+                elif step_data.get("success"):
+                    status = "OK"
+                else:
+                    status = "FAILED"
+                tx = step_data.get("tx_hash", "")[:12]
+                click.echo(f"  {step_name:12s} {status}" + (f"  tx={tx}..." if tx else ""))
+
+            if result.get("tx_hash"):
+                identity["xrpl_tx_hash"] = result["tx_hash"]
+            if result.get("mpt_tx_hash"):
+                identity["xrpl_mpt_hash"] = result["mpt_tx_hash"]
+            if result.get("credential_tx_hash"):
+                identity["xrpl_credential_hash"] = result["credential_tx_hash"]
+
+            save_identity(identity)
+
+            if not result.get("registered"):
+                click.echo(f"  Warning: {result.get('error', 'partial failure')}")
+        else:
+            click.echo("XRPL registration skipped (network unreachable).")
+
+    # Summary
+    click.echo("")
+    click.echo(f"  DID:        {identity['did']}")
+    click.echo(f"  Name:       {identity['name']}")
+    click.echo(f"  Network:    {identity['network']}")
+    click.echo(f"  Public Key: {identity['public_key'][:16]}...")
+    click.echo(f"  Cert Hash:  {identity['cert_hash']}")
+    if identity.get("xrpl_address"):
+        click.echo(f"  XRPL Addr:  {identity['xrpl_address']}")
+    if identity.get("xrpl_tx_hash"):
+        click.echo(f"  TX Hash:    {identity['xrpl_tx_hash'][:16]}...")
+    click.echo("")
+    click.echo("Ready. Run 'elpis whoami' to verify your identity.")
+
+
+@cli.command()
+@click.option(
+    "--resolver",
+    default="https://elpis.efiniti.ai/whoami",
+    help="Elpis resolver URL for identity verification.",
+)
+@click.option("--offline", is_flag=True, help="Show local identity without contacting resolver.")
+def whoami(resolver, offline):
+    """Verify identity via signed request to Elpis resolver.
+
+    Sends a signed GET request to the resolver and displays the
+    verified identity response. Use --offline to show local identity only.
+    """
+    identity = load_identity()
+    key_hex = load_private_key()
+    if not identity or not key_hex:
+        click.echo("No identity found. Run 'elpis init' first.")
+        sys.exit(1)
+
+    if offline:
+        click.echo(f"  DID:        {identity['did']}")
+        click.echo(f"  Name:       {identity['name']}")
+        click.echo(f"  Network:    {identity['network']}")
+        click.echo(f"  Public Key: {identity['public_key'][:16]}...")
+        click.echo(f"  Created:    {identity.get('created_at', '?')}")
+        return
+
+    # Sign and send whoami request
+    from .signer import sign_request
+    import httpx
+
+    private_seed = bytes.fromhex(key_hex)
+    sig_headers = sign_request(private_seed, "GET", resolver)
+    headers = {
+        **sig_headers,
+        "X-Elpis-DID": identity["did"],
+        "X-Elpis-Domain": identity.get("provider", ""),
+    }
+    if identity.get("xrpl_address"):
+        headers["X-Elpis-Account"] = identity["xrpl_address"]
+
+    click.echo(f"Verifying identity: {identity['did']}")
+    try:
+        resp = httpx.get(resolver, headers=headers, timeout=10.0)
+        if resp.status_code == 200:
+            data = resp.json()
+            click.echo(f"  Verified:   {data.get('verified', False)}")
+            click.echo(f"  DID:        {data.get('did', identity['did'])}")
+            click.echo(f"  Name:       {data.get('name', identity['name'])}")
+            if data.get("message"):
+                click.echo(f"  Message:    {data['message']}")
+        else:
+            click.echo(f"  Resolver returned {resp.status_code}")
+            click.echo(f"  Falling back to local identity:")
+            click.echo(f"  DID:        {identity['did']}")
+            click.echo(f"  Name:       {identity['name']}")
+            click.echo(f"  Signature:  valid (local)")
+    except httpx.ConnectError:
+        click.echo("  Resolver unreachable. Local identity:")
+        click.echo(f"  DID:        {identity['did']}")
+        click.echo(f"  Name:       {identity['name']}")
+        click.echo(f"  Signature:  valid (local, unverified)")
+    except Exception as exc:
+        click.echo(f"  Error: {exc}")
+        click.echo(f"  DID:        {identity['did']}")
+
+
+@cli.command("request")
+@click.argument("url")
+@click.option("-X", "--method", default="GET", help="HTTP method.")
+@click.option("-d", "--data", "body", default=None, help="Request body (string).")
+@click.option("-H", "--header", "extra_headers", multiple=True,
+              help="Extra header (key: value). Repeatable.")
+@click.option("-v", "--verbose", is_flag=True, help="Show request headers.")
+@click.option("-o", "--output", "output_file", default=None, type=click.Path(),
+              help="Write response body to file.")
+def request_cmd(url, method, body, extra_headers, verbose, output_file):
+    """Send a signed HTTP request (curl replacement).
+
+    Signs the request with your Elpis identity and injects X-Elpis-*
+    headers. The response is printed to stdout.
+
+    Examples:
+
+        elpis request https://efiniti.de/api/eacd/home
+
+        elpis request -X POST -d '{"key": "value"}' https://api.example.com/data
+    """
+    identity = load_identity()
+    key_hex = load_private_key()
+    if not identity or not key_hex:
+        click.echo("No identity found. Run 'elpis init' first.", err=True)
+        sys.exit(1)
+
+    from .signer import sign_request
+    import httpx
+
+    private_seed = bytes.fromhex(key_hex)
+    body_bytes = body.encode() if body else b""
+
+    # Sign the request
+    sig_headers = sign_request(private_seed, method.upper(), url, body_bytes)
+
+    # Build headers
+    headers = {
+        **sig_headers,
+        "X-Elpis-DID": identity["did"],
+        "X-Elpis-Domain": identity.get("provider", ""),
+    }
+    if identity.get("xrpl_address"):
+        headers["X-Elpis-Account"] = identity["xrpl_address"]
+    if identity.get("cert_hash"):
+        headers["X-Elpis-Cert-Hash"] = identity["cert_hash"]
+    if identity.get("name"):
+        headers["X-Elpis-Display-Name"] = identity["name"]
+
+    # Add extra headers
+    for h in extra_headers:
+        if ":" in h:
+            k, v = h.split(":", 1)
+            headers[k.strip()] = v.strip()
+
+    if verbose:
+        click.echo(f"> {method.upper()} {url}", err=True)
+        for k, v in headers.items():
+            click.echo(f"> {k}: {v}", err=True)
+        click.echo(">", err=True)
+
+    # Send request
+    try:
+        resp = httpx.request(
+            method=method.upper(),
+            url=url,
+            headers=headers,
+            content=body_bytes if body_bytes else None,
+            timeout=30.0,
+            follow_redirects=True,
+        )
+
+        if verbose:
+            click.echo(f"< HTTP {resp.status_code}", err=True)
+            for k, v in resp.headers.items():
+                click.echo(f"< {k}: {v}", err=True)
+            click.echo("<", err=True)
+
+        if output_file:
+            with open(output_file, "wb") as f:
+                f.write(resp.content)
+            click.echo(f"Response written to {output_file}", err=True)
+        else:
+            click.echo(resp.text)
+
+        sys.exit(0 if resp.status_code < 400 else 1)
+
+    except httpx.ConnectError as exc:
+        click.echo(f"Connection error: {exc}", err=True)
+        sys.exit(1)
+    except Exception as exc:
+        click.echo(f"Request failed: {exc}", err=True)
+        sys.exit(1)
+
+
+@cli.command()
+def status():
+    """Show current identity status."""
+    identity = load_identity()
+    if not identity:
+        click.echo("No identity found. Run 'elpis init' first.")
+        sys.exit(1)
+
+    click.echo(json.dumps(identity, indent=2))

elpis_cli/config.py

@@ -0,0 +1,67 @@
+"""Elpis CLI configuration and identity file management."""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+ELPIS_DIR = Path.home() / ".elpis"
+IDENTITY_FILE = ELPIS_DIR / "identity.json"
+KEY_FILE = ELPIS_DIR / "private.key"
+
+
+def ensure_dir() -> Path:
+    """Create ~/.elpis/ with restricted permissions if it doesn't exist."""
+    ELPIS_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+    return ELPIS_DIR
+
+
+def save_identity(identity: Dict[str, Any]) -> Path:
+    """Save identity to ~/.elpis/identity.json."""
+    ensure_dir()
+    IDENTITY_FILE.write_text(json.dumps(identity, indent=2))
+    IDENTITY_FILE.chmod(0o600)
+    return IDENTITY_FILE
+
+
+def load_identity() -> Optional[Dict[str, Any]]:
+    """Load identity from ~/.elpis/identity.json. Returns None if not found."""
+    if not IDENTITY_FILE.exists():
+        return None
+    try:
+        return json.loads(IDENTITY_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save_private_key(key_hex: str) -> Path:
+    """Save private key (hex-encoded) to ~/.elpis/private.key.
+
+    Uses os.open() with explicit permissions to avoid race condition
+    where the key file is briefly world-readable with default umask.
+
+    Note:
+        The private key is stored in plaintext (hex-encoded).
+        TODO: Implement encryption-at-rest (e.g. age/AEAD) before v1.0.
+    """
+    ensure_dir()
+    fd = os.open(str(KEY_FILE), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, 'w') as f:
+        f.write(key_hex)
+    return KEY_FILE
+
+
+def load_private_key() -> Optional[str]:
+    """Load private key hex from ~/.elpis/private.key."""
+    if not KEY_FILE.exists():
+        return None
+    try:
+        return KEY_FILE.read_text().strip()
+    except OSError:
+        return None
+
+
+def identity_exists() -> bool:
+    """Check if an identity has been initialized."""
+    return IDENTITY_FILE.exists() and KEY_FILE.exists()

elpis_cli/identity.py

@@ -0,0 +1,127 @@
+"""Ed25519 identity management for Elpis Protocol."""
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Dict, Tuple
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives import serialization
+
+
+def generate_keypair() -> Tuple[bytes, bytes]:
+    """Generate an Ed25519 keypair.
+
+    Returns:
+        (private_seed_32bytes, public_key_32bytes)
+    """
+    private_key = Ed25519PrivateKey.generate()
+    private_seed = private_key.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_key = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return private_seed, public_key
+
+
+def load_keypair_from_file(key_path: str) -> Tuple[bytes, bytes]:
+    """Load an existing Ed25519 private key from a file.
+
+    Supports hex-encoded raw seed (64 hex chars) or PEM format.
+
+    Args:
+        key_path: Path to the key file.
+
+    Returns:
+        (private_seed_32bytes, public_key_32bytes)
+    """
+    with open(key_path, "r") as f:
+        content = f.read().strip()
+
+    if content.startswith("-----BEGIN"):
+        # PEM format
+        private_key = serialization.load_pem_private_key(
+            content.encode(), password=None
+        )
+        if not isinstance(private_key, Ed25519PrivateKey):
+            raise ValueError("Key file is not an Ed25519 key")
+    else:
+        # Hex-encoded raw seed
+        seed = bytes.fromhex(content)
+        if len(seed) != 32:
+            raise ValueError(f"Expected 32-byte seed, got {len(seed)} bytes")
+        private_key = Ed25519PrivateKey.from_private_bytes(seed)
+
+    private_seed = private_key.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_key = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return private_seed, public_key
+
+
+def create_did(network: str = "testnet", public_key: bytes = b"") -> str:
+    """Create a DID from a public key.
+
+    Format: did:xrpl:{nanoid}#{fragment}
+    - nanoid: 8-char hex derived from public key hash
+    - fragment: opaque UUID (Section A.3 Privacy by Default)
+
+    Args:
+        network: XRPL network (testnet, mainnet).
+        public_key: 32-byte Ed25519 public key.
+
+    Returns:
+        DID string.
+    """
+    # Derive nanoid from public key hash (first 8 hex chars)
+    key_hash = hashlib.sha256(public_key).hexdigest()[:8]
+    # Fragment derived deterministically from public key for reproducibility
+    fragment = hashlib.sha256(public_key + b"fragment").hexdigest()[:8]
+    return f"did:xrpl:{key_hash}#{fragment}"
+
+
+def build_identity(
+    name: str,
+    provider: str = "",
+    role: str = "",
+    network: str = "testnet",
+    private_seed: bytes = b"",
+    public_key: bytes = b"",
+    did: str = "",
+) -> Dict:
+    """Build an identity document.
+
+    Args:
+        name: Agent/user display name.
+        provider: Provider name (e.g. "efiniti").
+        role: Role description.
+        network: XRPL network.
+        private_seed: Raw 32-byte private key seed.
+        public_key: Raw 32-byte public key.
+        did: Pre-generated DID (or auto-generated from public_key).
+
+    Returns:
+        Identity dict suitable for JSON serialization.
+    """
+    if not did:
+        did = create_did(network, public_key)
+
+    return {
+        "version": "1.0",
+        "did": did,
+        "name": name,
+        "provider": provider,
+        "role": role,
+        "network": network,
+        "public_key": public_key.hex(),
+        "cert_hash": hashlib.sha256(public_key).hexdigest()[:16],
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }

elpis_cli/signer.py

@@ -0,0 +1,58 @@
+"""Ed25519 request signing for Elpis Protocol.
+
+Produces X-Elpis-* headers compatible with elpis-proxy, elpis-signer,
+and the Pandora Agent SDK.
+"""
+
+import base64
+import hashlib
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Dict
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+# ARGUS H1 alignment: reject control characters in canonical fields
+_SAFE_FIELD_RE = re.compile(r"^[^\n\r\x00-\x1f]+$")
+
+
+def sign_request(
+    private_seed: bytes,
+    method: str,
+    url: str,
+    body: bytes = b"",
+) -> Dict[str, str]:
+    """Sign an HTTP request with Ed25519.
+
+    Canonical format (identical to elpis-proxy/elpis-signer):
+        {method}\\n{url}\\n{body_hash}\\n{timestamp}\\n{nonce}
+
+    Args:
+        private_seed: 32-byte Ed25519 private key seed.
+        method: HTTP method (GET, POST, etc.).
+        url: Full target URL.
+        body: Request body bytes.
+
+    Returns:
+        Dict of X-Elpis-* headers (Timestamp, Nonce, Signature).
+    """
+    for name, val in [("method", method), ("url", url)]:
+        if not val or not _SAFE_FIELD_RE.match(val):
+            raise ValueError(f"sign_request: {name} contains invalid characters")
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    nonce = str(uuid.uuid4())
+    body_hash = hashlib.sha256(body).hexdigest()
+
+    canonical = f"{method}\n{url}\n{body_hash}\n{timestamp}\n{nonce}"
+
+    key = Ed25519PrivateKey.from_private_bytes(private_seed)
+    signature = key.sign(canonical.encode())
+    signature_b64 = base64.b64encode(signature).decode()
+
+    return {
+        "X-Elpis-Timestamp": timestamp,
+        "X-Elpis-Nonce": nonce,
+        "X-Elpis-Signature": signature_b64,
+    }