cli commands

rcholic · rcholic · commit 48fc1d32a7fa · 2026-02-16T15:59:05.000-08:00
diff --git a/README.md b/README.md
@@ -123,6 +123,37 @@ See runnable examples in:
 - `examples/mcp_tool_guard_example.py`
 - `examples/outbound_http_guard_example.py`
 
+## Operations CLI (Phase 2)
+
+`predicate-authority` provides an ops-focused CLI for sidecar/runtime workflows.
+
+### Sidecar health and status
+
+```bash
+predicate-authority sidecar health --host 127.0.0.1 --port 8787
+predicate-authority sidecar status --host 127.0.0.1 --port 8787
+```
+
+### Policy validation and reload
+
+```bash
+predicate-authority policy validate --file examples/authorityd/policy.json
+predicate-authority policy reload --host 127.0.0.1 --port 8787
+```
+
+### Revocation controls
+
+```bash
+predicate-authority revoke principal --host 127.0.0.1 --port 8787 --id agent:orders-01
+predicate-authority revoke intent --host 127.0.0.1 --port 8787 --hash <intent_hash>
+```
+
+### Daemon startup
+
+```bash
+predicate-authorityd --host 127.0.0.1 --port 8787 --mode local_only --policy-file examples/authorityd/policy.json
+```
+
 ## Security: Local Kill-Switch Path
 
 The current Phase 1 runtime supports fail-closed checks and local proof emission. The sidecar model (`predicate-authorityd`) is planned to provide instant local revocation and managed token lifecycle for long-running production agents.
diff --git a/docs/pypi-release-guide.md b/docs/pypi-release-guide.md
@@ -0,0 +1,92 @@
+# PyPI Release Guide
+
+This repo publishes two Python packages in strict order:
+
+1. `predicate-contracts`
+2. `predicate-authority` (depends on `predicate-contracts`)
+
+## 1) One-time setup
+
+### Reserve package names on PyPI
+
+Ensure both package names exist under your organization:
+
+- `predicate-contracts`
+- `predicate-authority`
+
+### Add GitHub repository secrets
+
+In GitHub repository settings -> Secrets and variables -> Actions, add:
+
+- `PYPI_TOKEN_PREDICATE_CONTRACTS`
+- `PYPI_TOKEN_PREDICATE_AUTHORITY`
+
+Use PyPI API tokens scoped to each package where possible.
+
+## 2) Prepare a release
+
+1. Update versions:
+   - `predicate_contracts/pyproject.toml` -> `project.version`
+   - `predicate_authority/pyproject.toml` -> `project.version`
+2. If `predicate-contracts` version changes, update dependency pin in:
+   - `predicate_authority/pyproject.toml` (`predicate-contracts>=X,<Y`)
+3. Run local checks:
+
+```bash
+make test
+make lint
+make verify-release-order
+python -m build predicate_contracts
+python -m build predicate_authority
+```
+
+## 3) Publish via GitHub Actions (recommended)
+
+1. Push your release commit to `main`.
+2. Open Actions -> `phase1-ci-and-release`.
+3. Click **Run workflow** with input `publish=true`.
+4. Workflow order is enforced:
+   - `publish-predicate-contracts`
+   - `publish-predicate-authority` (runs only after contracts publish succeeds)
+
+## 4) Verify published artifacts
+
+```bash
+python -m pip install --upgrade predicate-contracts predicate-authority
+python - <<'PY'
+import predicate_contracts
+import predicate_authority
+print("ok", predicate_contracts.__name__, predicate_authority.__name__)
+PY
+```
+
+## 5) Optional: create git tags per package release
+
+Tags are not required for publishing in this repo, but they are recommended for traceability.
+
+Suggested tag format:
+
+- `predicate-contracts-vX.Y.Z`
+- `predicate-authority-vX.Y.Z`
+
+Example commands (after publish succeeds):
+
+```bash
+git tag -a predicate-contracts-v0.1.0 -m "predicate-contracts v0.1.0"
+git tag -a predicate-authority-v0.1.0 -m "predicate-authority v0.1.0"
+git push origin predicate-contracts-v0.1.0
+git push origin predicate-authority-v0.1.0
+```
+
+## 6) Manual fallback publish (if needed)
+
+```bash
+python -m pip install --upgrade build twine
+python -m build predicate_contracts
+twine check predicate_contracts/dist/*
+TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN_PREDICATE_CONTRACTS" twine upload predicate_contracts/dist/*
+
+python -m build predicate_authority
+twine check predicate_authority/dist/*
+TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN_PREDICATE_AUTHORITY" twine upload predicate_authority/dist/*
+```
diff --git a/predicate_authority/cli.py b/predicate_authority/cli.py
@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+import http.client
+import json
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from predicate_authority.policy_source import PolicyFileSource
+
+
+def _request_json(
+    method: str, url: str, payload: dict[str, str] | None = None
+) -> tuple[int, dict[str, object]]:
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise RuntimeError(f"Unsupported URL scheme: {parsed.scheme}")
+    if parsed.netloc == "":
+        raise RuntimeError("URL must include host:port.")
+    path = parsed.path or "/"
+    if parsed.query:
+        path = f"{path}?{parsed.query}"
+    body = None
+    headers: dict[str, str] = {}
+    if payload is not None:
+        body = json.dumps(payload)
+        headers["Content-Type"] = "application/json"
+    connection_cls = (
+        http.client.HTTPSConnection if parsed.scheme == "https" else http.client.HTTPConnection
+    )
+    connection = connection_cls(parsed.netloc, timeout=5.0)
+    try:
+        connection.request(method.upper(), path, body=body, headers=headers)
+        response = connection.getresponse()
+        raw = response.read().decode("utf-8")
+    finally:
+        connection.close()
+    if raw.strip() == "":
+        return int(response.status), {}
+    loaded = json.loads(raw)
+    if not isinstance(loaded, dict):
+        raise RuntimeError("Expected JSON object response.")
+    return int(response.status), loaded
+
+
+def _base_url(host: str, port: int) -> str:
+    return f"http://{host}:{port}"
+
+
+def _print_json(payload: dict[str, object]) -> None:
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+def _cmd_sidecar_health(args: argparse.Namespace) -> int:
+    status, payload = _request_json("GET", f"{_base_url(args.host, args.port)}/health")
+    _print_json(payload)
+    return 0 if status < 400 else 1
+
+
+def _cmd_sidecar_status(args: argparse.Namespace) -> int:
+    status, payload = _request_json("GET", f"{_base_url(args.host, args.port)}/status")
+    _print_json(payload)
+    return 0 if status < 400 else 1
+
+
+def _cmd_policy_validate(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    if not path.exists():
+        print(f"Policy file not found: {path}", file=sys.stderr)
+        return 1
+    try:
+        rules = PolicyFileSource(str(path)).load_rules()
+    except Exception as exc:  # noqa: BLE001
+        print(f"Policy validation failed: {exc}", file=sys.stderr)
+        return 1
+    _print_json({"valid": True, "rule_count": len(rules), "file": str(path)})
+    return 0
+
+
+def _cmd_policy_reload(args: argparse.Namespace) -> int:
+    status, payload = _request_json("POST", f"{_base_url(args.host, args.port)}/policy/reload")
+    _print_json(payload)
+    return 0 if status < 400 else 1
+
+
+def _cmd_revoke_principal(args: argparse.Namespace) -> int:
+    status, payload = _request_json(
+        "POST",
+        f"{_base_url(args.host, args.port)}/revoke/principal",
+        payload={"principal_id": args.id},
+    )
+    _print_json(payload)
+    return 0 if status < 400 else 1
+
+
+def _cmd_revoke_intent(args: argparse.Namespace) -> int:
+    status, payload = _request_json(
+        "POST",
+        f"{_base_url(args.host, args.port)}/revoke/intent",
+        payload={"intent_hash": args.hash},
+    )
+    _print_json(payload)
+    return 0 if status < 400 else 1
+
+
+def _add_host_port_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8787)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="predicate-authority operational CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    sidecar_parser = subparsers.add_parser("sidecar", help="Sidecar inspection commands")
+    sidecar_sub = sidecar_parser.add_subparsers(dest="sidecar_command", required=True)
+
+    sidecar_health = sidecar_sub.add_parser("health", help="Query sidecar /health")
+    _add_host_port_args(sidecar_health)
+    sidecar_health.set_defaults(func=_cmd_sidecar_health)
+
+    sidecar_status = sidecar_sub.add_parser("status", help="Query sidecar /status")
+    _add_host_port_args(sidecar_status)
+    sidecar_status.set_defaults(func=_cmd_sidecar_status)
+
+    policy_parser = subparsers.add_parser("policy", help="Policy utility commands")
+    policy_sub = policy_parser.add_subparsers(dest="policy_command", required=True)
+
+    policy_validate = policy_sub.add_parser("validate", help="Validate policy file")
+    policy_validate.add_argument("--file", required=True)
+    policy_validate.set_defaults(func=_cmd_policy_validate)
+
+    policy_reload = policy_sub.add_parser("reload", help="Request sidecar policy reload")
+    _add_host_port_args(policy_reload)
+    policy_reload.set_defaults(func=_cmd_policy_reload)
+
+    revoke_parser = subparsers.add_parser("revoke", help="Revocation commands")
+    revoke_sub = revoke_parser.add_subparsers(dest="revoke_command", required=True)
+
+    revoke_principal = revoke_sub.add_parser("principal", help="Revoke by principal_id")
+    _add_host_port_args(revoke_principal)
+    revoke_principal.add_argument("--id", required=True)
+    revoke_principal.set_defaults(func=_cmd_revoke_principal)
+
+    revoke_intent = revoke_sub.add_parser("intent", help="Revoke by intent hash")
+    _add_host_port_args(revoke_intent)
+    revoke_intent.add_argument("--hash", required=True)
+    revoke_intent.set_defaults(func=_cmd_revoke_intent)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    exit_code = args.func(args)
+    raise SystemExit(exit_code)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/predicate_authority/daemon.py b/predicate_authority/daemon.py
@@ -64,10 +64,53 @@ def do_GET(self) -> None:  # noqa: N802
             return
         self._send_json(404, {"error": "not_found"})
 
+    def do_POST(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if parsed.path == "/policy/reload":
+            reloaded = self.server.daemon_ref.reload_policy_now()  # type: ignore[attr-defined]
+            self._send_json(200, {"reloaded": reloaded})
+            return
+        if parsed.path == "/revoke/principal":
+            payload = self._read_json_body()
+            principal_id = payload.get("principal_id")
+            if not isinstance(principal_id, str) or principal_id.strip() == "":
+                self._send_json(400, {"error": "principal_id is required"})
+                return
+            self.server.daemon_ref.revoke_principal(principal_id.strip())  # type: ignore[attr-defined]
+            self._send_json(200, {"ok": True, "principal_id": principal_id.strip()})
+            return
+        if parsed.path == "/revoke/intent":
+            payload = self._read_json_body()
+            intent_hash = payload.get("intent_hash")
+            if not isinstance(intent_hash, str) or intent_hash.strip() == "":
+                self._send_json(400, {"error": "intent_hash is required"})
+                return
+            self.server.daemon_ref.revoke_intent(intent_hash.strip())  # type: ignore[attr-defined]
+            self._send_json(200, {"ok": True, "intent_hash": intent_hash.strip()})
+            return
+        self._send_json(404, {"error": "not_found"})
+
     def log_message(self, format: str, *args: Any) -> None:  # noqa: A003
         # Keep daemon output deterministic and quiet by default.
         return
 
+    def _read_json_body(self) -> dict[str, Any]:
+        raw_length = self.headers.get("Content-Length", "0")
+        try:
+            content_length = int(raw_length)
+        except ValueError:
+            return {}
+        if content_length <= 0:
+            return {}
+        payload = self.rfile.read(content_length).decode("utf-8")
+        try:
+            loaded = json.loads(payload)
+        except json.JSONDecodeError:
+            return {}
+        if isinstance(loaded, dict):
+            return loaded
+        return {}
+
     def _send_json(self, code: int, payload: dict[str, Any]) -> None:
         encoded = json.dumps(payload).encode("utf-8")
         self.send_response(code)
@@ -143,6 +186,19 @@ def status_payload(self) -> dict[str, Any]:
         )
         return payload
 
+    def reload_policy_now(self) -> bool:
+        changed = self._sidecar.hot_reload_policy()
+        if changed:
+            self._runtime.policy_reload_count += 1
+            self._runtime.last_policy_reload_epoch_s = time.time()
+        return changed
+
+    def revoke_principal(self, principal_id: str) -> None:
+        self._sidecar.revoke_by_invariant(principal_id)
+
+    def revoke_intent(self, intent_hash: str) -> None:
+        self._sidecar.revoke_intent_hash(intent_hash)
+
     def _policy_poll_loop(self) -> None:
         while not self._stop_event.is_set():
             try:
diff --git a/predicate_authority/pyproject.toml b/predicate_authority/pyproject.toml
@@ -20,6 +20,7 @@ dependencies = [
 ]
 
 [project.scripts]
+predicate-authority = "predicate_authority.cli:main"
 predicate-authorityd = "predicate_authority.daemon:main"
 
 [project.optional-dependencies]
diff --git a/predicate_authority/sidecar.py b/predicate_authority/sidecar.py
@@ -131,6 +131,9 @@ def exchange_access_token(
     def revoke_by_invariant(self, principal_id: str) -> None:
         self._revocation_cache.revoke_principal(principal_id)
 
+    def revoke_intent_hash(self, intent_hash: str) -> None:
+        self._revocation_cache.revoke_intent_hash(intent_hash)
+
     def hot_reload_policy(self) -> bool:
         if self._policy_source is None:
             return False
diff --git a/tests/test_cli_phase2.py b/tests/test_cli_phase2.py
diff --git a/tests/test_daemon_phase2.py b/tests/test_daemon_phase2.py

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@ dependencies = [`
`20`	`20`	`]`
`21`	`21`
`22`	`22`	`[project.scripts]`
	`23`	`+predicate-authority = "predicate_authority.cli:main"`
`23`	`24`	`predicate-authorityd = "predicate_authority.daemon:main"`
`24`	`25`
`25`	`26`	`[project.optional-dependencies]`