capforge 0.4.0__py3-none-any.whl

capforge/cli/main.py

@@ -0,0 +1,347 @@
+"""Command-line interface for CapForge (ACM protocol).
+
+Usage
+-----
+
+    capforge keygen --output ./keys/my-key
+    capforge create --spiffe-id spiffe://org/agent/bot \\
+                   --sponsor user@org.com \\
+                   --capability kb:read \\
+                   --key-file keys/my-key.pem \\
+                   --output manifest.json
+    capforge verify manifest.json --trusted-roots root.pub
+    capforge info manifest.json
+    capforge delegate --parent manifest.json \\
+                      --child-spiffe-id spiffe://org/agent/sub \\
+                      --capability kb:read
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import click
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from capforge import ACM, Capability, Constraints, __version__
+from capforge._crypto import (
+    generate_private_key,
+    write_key_pair,
+)
+from capforge._exceptions import ACMError
+
+# ── keygen ────────────────────────────────────────────────────────
+
+
+@click.command()
+@click.option(
+    "--output",
+    "-o",
+    default="capforge-key",
+    show_default=True,
+    help="Path prefix for key files (creates {prefix}.pem and {prefix}.pub).",
+)
+def keygen(output: str) -> None:
+    """Generate a new Ed25519 key pair for signing ACM documents."""
+    priv_key = generate_private_key()
+    priv_path, pub_path = write_key_pair(priv_key, path_prefix=output)
+    click.echo(f"Private key: {priv_path}")
+    click.echo(f"Public key:  {pub_path}")
+    click.echo("Keep the private key secure. Never share it.")
+
+
+# ── create ────────────────────────────────────────────────────────
+
+
+@click.command()
+@click.option("--spiffe-id", required=True, help="SPIFFE ID of the agent.")
+@click.option("--sponsor", required=True, help="Email or SPIFFE ID of the human sponsor.")
+@click.option(
+    "--capability",
+    "-c",
+    multiple=True,
+    required=True,
+    help="Capability in 'resource:action' format (can be repeated).",
+)
+@click.option(
+    "--constraint",
+    "-C",
+    multiple=True,
+    help="Constraint in 'key=value' format (can be repeated).",
+)
+@click.option("--model", help="LLM model name (e.g., 'gpt-5').")
+@click.option("--provider", help="Model provider (e.g., 'openai').")
+@click.option(
+    "--key-file",
+    type=click.Path(exists=True, dir_okay=False),
+    help="Path to Ed25519 private key PEM file for signing.",
+)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(dir_okay=False),
+    help="Write the ACM document to a file instead of stdout.",
+)
+@click.option("--ttl", default=3600, show_default=True, help="Time-to-live in seconds.")
+@click.option("--not-before", help="ISO 8601 timestamp for not_before (default: now).")
+@click.option("--metadata", help="JSON string of metadata to attach.")
+def create(
+    spiffe_id: str,
+    sponsor: str,
+    capability: tuple[str, ...],
+    constraint: tuple[str, ...],
+    model: str | None,
+    provider: str | None,
+    key_file: str | None,
+    output: str | None,
+    ttl: int,
+    not_before: str | None,
+    metadata: str | None,
+) -> None:
+    """Create a new ACM document, optionally sign it, and write to stdout or file."""
+    caps: list[Capability] = []
+    for cap_str in capability:
+        parts = cap_str.split(":", 1)
+        if len(parts) != 2:
+            click.echo(
+                f"Invalid capability: {cap_str!r} (expected 'resource:action')",
+                err=True,
+            )
+            sys.exit(1)
+        caps.append(Capability(resource=parts[0], action=parts[1]))
+
+    cons: dict[str, object] = {}
+    for c_str in constraint:
+        kv = c_str.split("=", 1)
+        if len(kv) == 2:
+            key, raw = kv[0], kv[1]
+            try:
+                cons[key] = float(raw) if "." in raw else int(raw)
+            except ValueError:
+                cons[key] = raw
+
+    meta: dict[str, object] | None = None
+    if metadata:
+        try:
+            meta = json.loads(metadata)
+        except json.JSONDecodeError as exc:
+            click.echo(f"Invalid metadata JSON: {exc}", err=True)
+            sys.exit(1)
+
+    nb: datetime | None = None
+    if not_before:
+        try:
+            nb = datetime.fromisoformat(not_before)
+        except ValueError as exc:
+            click.echo(f"Invalid not_before: {exc}", err=True)
+            sys.exit(1)
+
+    constraints_obj = Constraints.model_validate(cons) if cons else None
+
+    manifest = ACM.create(
+        spiffe_id=spiffe_id,
+        sponsor=sponsor,
+        capabilities=caps,
+        constraints=constraints_obj,
+        ttl=ttl,
+        not_before=nb,
+        model=model,
+        provider=provider,
+        metadata=meta,
+    )
+
+    if key_file:
+        manifest.sign(key_file)
+
+    result = manifest.to_json()
+    if output:
+        manifest.save(output)
+        click.echo(f"Written to {output}")
+    else:
+        click.echo(result)
+
+
+# ── verify ────────────────────────────────────────────────────────
+
+
+@click.command()
+@click.argument("manifest_path", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--trusted-roots",
+    type=click.Path(exists=True, dir_okay=False),
+    multiple=True,
+    help="Public key PEM file(s) of trusted issuers (can be repeated).",
+)
+def verify(manifest_path: str, trusted_roots: tuple[str, ...]) -> None:
+    """Verify an ACM document — temporal, structural, and optionally signature."""
+    manifest = ACM.load(manifest_path)
+
+    trusted_key_list: list[str | Path | Ed25519PublicKey] = (
+        [Path(p) for p in trusted_roots] if trusted_roots else []
+    )
+
+    try:
+        if trusted_key_list:
+            manifest.verify(trusted_keys=trusted_key_list)
+            click.echo("Verification PASSED (signature valid)")
+        else:
+            manifest.verify()
+            click.echo("Verification PASSED (temporal + structural)")
+
+        click.echo(f"  Agent:       {manifest.spiffe_id}")
+        click.echo(f"  Sponsor:     {manifest.sponsor}")
+        click.echo(f"  Capabilities: {len(manifest.capabilities_list)}")
+        click.echo(f"  Expires at:  {manifest.expires_at}")
+        if manifest.signature:
+            click.echo(f"  Signature:   {manifest.signature[:32]}...")
+        if manifest.delegation_chain:
+            click.echo(f"  Delegation:  {len(manifest.delegation_chain)} hops")
+    except ACMError as exc:
+        click.echo(f"Verification FAILED: {exc}", err=True)
+        sys.exit(1)
+
+
+# ── info ──────────────────────────────────────────────────────────
+
+
+@click.command()
+@click.argument("manifest_path", type=click.Path(exists=True, dir_okay=False))
+def info(manifest_path: str) -> None:
+    """Display human-readable information about an ACM document."""
+    manifest = ACM.load(manifest_path)
+
+    click.echo(f"ACM Version:         {manifest.acm_version}")
+    click.echo(f"Agent SPIFFE ID:     {manifest.spiffe_id}")
+    if manifest.agent_model:
+        click.echo(f"Model:               {manifest.agent_model}")
+    if manifest.agent_provider:
+        click.echo(f"Provider:            {manifest.agent_provider}")
+    click.echo(f"Human Sponsor:       {manifest.sponsor}")
+    click.echo(f"Issuer:              {manifest.issuer}")
+    click.echo(f"Expires At:          {manifest.expires_at}")
+    if manifest.not_before:
+        click.echo(f"Not Before:          {manifest.not_before}")
+    click.echo(f"Capabilities ({len(manifest.capabilities_list)}):")
+    for cap in manifest.capabilities_list:
+        line = f"  - {cap.resource}:{cap.action}"
+        if cap.constraints:
+            line += f" [{cap.constraints}]"
+        click.echo(line)
+    if manifest.constraints_obj:
+        click.echo(f"Constraints:  {manifest.constraints_obj.model_dump(exclude_none=True)}")
+    if manifest.delegation_chain:
+        hops = len(manifest.delegation_chain)
+        click.echo(f"Delegation Chain ({hops} hops):")
+        for entry in manifest.delegation_chain:
+            click.echo(f"  -> {entry}")
+    click.echo(f"Has Signature:       {manifest.signature is not None}")
+    click.echo(f"Valid Now:           {manifest.is_valid()}")
+
+
+# ── validate ──────────────────────────────────────────────────────
+
+
+@click.command()
+@click.argument("manifest_path", type=click.Path(exists=True, dir_okay=False))
+def validate(manifest_path: str) -> None:
+    """Validate an ACM document (temporal + structural, no signature check)."""
+    manifest = ACM.load(manifest_path)
+    try:
+        manifest.verify()
+        click.echo("Validation PASSED (temporal + structural)")
+        click.echo(f"  Agent:       {manifest.spiffe_id}")
+        click.echo(f"  Capabilities: {len(manifest.capabilities_list)}")
+        click.echo(f"  Expires at:  {manifest.expires_at}")
+    except ACMError as exc:
+        click.echo(f"Validation FAILED: {exc}", err=True)
+        sys.exit(1)
+
+
+# ── delegate ──────────────────────────────────────────────────────
+
+
+@click.command()
+@click.option(
+    "--parent",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False),
+    help="Parent ACM manifest JSON file.",
+)
+@click.option("--child-spiffe-id", required=True, help="SPIFFE ID of the child agent.")
+@click.option(
+    "--capability",
+    "-c",
+    multiple=True,
+    required=True,
+    help="Capability to delegate (can be repeated). Must be subset of parent's.",
+)
+@click.option(
+    "--key-file",
+    type=click.Path(exists=True, dir_okay=False),
+    help="Path to the parent's private key to sign the delegation.",
+)
+@click.option(
+    "--output", "-o", type=click.Path(dir_okay=False), help="Write delegated ACM to a file."
+)
+@click.option("--ttl", default=3600, show_default=True, help="Time-to-live in seconds.")
+def delegate(
+    parent: str,
+    child_spiffe_id: str,
+    capability: tuple[str, ...],
+    key_file: str | None,
+    output: str | None,
+    ttl: int,
+) -> None:
+    """Create a delegated ACM document with narrowed scope."""
+    parent_manifest = ACM.load(parent)
+
+    caps: list[Capability] = []
+    for cap_str in capability:
+        parts = cap_str.split(":", 1)
+        if len(parts) != 2:
+            click.echo(
+                f"Invalid capability: {cap_str!r} (expected 'resource:action')",
+                err=True,
+            )
+            sys.exit(1)
+        caps.append(Capability(resource=parts[0], action=parts[1]))
+
+    try:
+        child = parent_manifest.delegate(
+            child_spiffe_id=child_spiffe_id,
+            capabilities=caps,
+            ttl=ttl,
+            key=key_file,
+        )
+        result = child.to_json()
+        if output:
+            child.save(output)
+            click.echo(f"Written to {output}")
+        else:
+            click.echo(result)
+    except (ValueError, ACMError) as exc:
+        click.echo(f"Delegation FAILED: {exc}", err=True)
+        sys.exit(1)
+
+
+# ── CLI group ─────────────────────────────────────────────────────
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="capforge")
+def cli() -> None:
+    """CapForge — Agent Capability Manifest (ACM) management."""
+
+
+cli.add_command(keygen)
+cli.add_command(create)
+cli.add_command(verify)
+cli.add_command(info)
+cli.add_command(validate)
+cli.add_command(delegate)
+
+if __name__ == "__main__":
+    cli()