guzli-cli 0.2.0__py3-none-any.whl

guzli/commands/admin.py

@@ -0,0 +1,421 @@
+from __future__ import annotations
+
+import argparse
+
+from guzli.commands.common import add_json_flag as _add_json_flag
+from guzli.commands.common import add_org_arg as _add_org_arg
+from guzli.commands.common import require_org_id as _require_org_id
+from guzli.errors import ValidationError
+from guzli.runtime import RuntimeContext
+
+
+def _add_api_keys_list(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("list", help="List workspace API keys")
+    _add_org_arg(parser)
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_api_keys_list)
+
+
+def _add_api_keys_create(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("create", help="Create a workspace API key (secret returned once)")
+    _add_org_arg(parser)
+    parser.add_argument("--name", required=True, help="Human-readable name")
+    parser.add_argument(
+        "--usage-type",
+        choices=["server", "client"],
+        default="server",
+        help="server = signing/automation; client = browser/widget (default: server)",
+    )
+    parser.add_argument("--environment", default="production")
+    parser.add_argument(
+        "--allowed-domains",
+        nargs="*",
+        default=[],
+        help="Domain bindings for client-type keys (e.g. example.com app.example.com)",
+    )
+    parser.add_argument("--rate-limit", type=int, dest="rate_limit")
+    parser.add_argument(
+        "--expires-at",
+        dest="expires_at",
+        help="ISO-8601 expiry. API-created server keys cap at created_at + 365d.",
+    )
+    parser.add_argument(
+        "--allow-identity-signing", action="store_true", dest="allow_identity_signing"
+    )
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_api_keys_create)
+
+
+def _add_api_keys_update(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("update", help="Update a workspace API key")
+    _add_org_arg(parser)
+    parser.add_argument("api_key_id")
+    parser.add_argument("--name")
+    parser.add_argument("--allowed-domains", nargs="*", dest="allowed_domains")
+    parser.add_argument("--rate-limit", type=int, dest="rate_limit")
+    parser.add_argument("--is-active", dest="is_active", choices=["true", "false"])
+    parser.add_argument("--expires-at", dest="expires_at")
+    parser.add_argument("--usage-type", dest="usage_type", choices=["server", "client"])
+    parser.add_argument(
+        "--allow-identity-signing",
+        dest="allow_identity_signing",
+        choices=["true", "false"],
+    )
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_api_keys_update)
+
+
+def _add_api_keys_delete(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("delete", help="Soft-deactivate a workspace API key")
+    _add_org_arg(parser)
+    parser.add_argument("api_key_id")
+    parser.add_argument("--confirm", action="store_true", help="Required to proceed")
+    parser.set_defaults(handler=handle_api_keys_delete)
+
+
+def handle_api_keys_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    payload = context.api_keys.list_keys(org)
+    if getattr(args, "json", False):
+        context.renderer.print_json(payload)
+        return
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    if not items:
+        print("No API keys.")
+        return
+    for k in items:
+        expires = k.get("expires_at") or "(never)"
+        status_tag = "active" if k.get("is_active") else "inactive"
+        print(
+            f"{k.get('id')}  {k.get('name')}  [{k.get('usage_type')}]  "
+            f"prefix={k.get('key_prefix')}  expires={expires}  {status_tag}"
+        )
+
+
+def handle_api_keys_create(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    result = context.api_keys.create_key(
+        org,
+        name=args.name,
+        environment=args.environment,
+        allowed_domains=args.allowed_domains or None,
+        rate_limit=args.rate_limit,
+        expires_at=args.expires_at,
+        usage_type=args.usage_type,
+        allow_identity_signing=args.allow_identity_signing,
+    )
+    if getattr(args, "json", False):
+        context.renderer.print_json(result)
+        return
+    secret = result.get("secret") if isinstance(result, dict) else None
+    key = result.get("key", {}) if isinstance(result, dict) else {}
+    print("IMPORTANT: secret_value shown ONCE — save it now.")
+    print(f"secret_value: {secret}")
+    print(f"id:           {key.get('id')}")
+    print(f"name:         {key.get('name')}")
+    print(f"usage_type:   {key.get('usage_type')}")
+    print(f"key_prefix:   {key.get('key_prefix')}")
+    print(f"expires_at:   {key.get('expires_at') or '(never)'}")
+
+
+def handle_api_keys_update(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    updates: dict[str, object] = {}
+    if args.name is not None:
+        updates["name"] = args.name
+    if args.allowed_domains is not None:
+        updates["allowed_domains"] = args.allowed_domains
+    if args.rate_limit is not None:
+        updates["rate_limit"] = args.rate_limit
+    if args.is_active is not None:
+        updates["is_active"] = args.is_active == "true"
+    if args.expires_at is not None:
+        updates["expires_at"] = args.expires_at
+    if args.usage_type is not None:
+        updates["usage_type"] = args.usage_type
+    if args.allow_identity_signing is not None:
+        updates["allow_identity_signing"] = args.allow_identity_signing == "true"
+    result = context.api_keys.update_key(org, args.api_key_id, **updates)  # type: ignore[arg-type]
+    if getattr(args, "json", False):
+        context.renderer.print_json(result)
+    else:
+        print(f"Updated {args.api_key_id}")
+
+
+def handle_api_keys_delete(context: RuntimeContext, args: argparse.Namespace) -> None:
+    if not args.confirm:
+        raise ValidationError("--confirm flag required to delete")
+    org = _require_org_id(context, args)
+    context.api_keys.delete_key(org, args.api_key_id)
+    print(f"Deactivated {args.api_key_id}")
+
+
+def _add_webhooks_list(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("list", help="List webhook integrations for the org")
+    _add_org_arg(parser)
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_webhooks_list)
+
+
+def _add_webhooks_get(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("get", help="Get one webhook integration")
+    _add_org_arg(parser)
+    parser.add_argument("integration_id")
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_webhooks_get)
+
+
+def _add_webhooks_create(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("create", help="Create a webhook integration")
+    _add_org_arg(parser)
+    parser.add_argument("--name", required=True)
+    parser.add_argument("--agent-id", dest="webhook_agent_id", required=True, help="Agent UUID")
+    parser.add_argument(
+        "--url", required=True, help="Receiver URL (must match org domain allowlist if set)"
+    )
+    parser.add_argument(
+        "--api-key-id",
+        dest="api_key_id",
+        required=True,
+        help="Workspace server API key id used to sign deliveries",
+    )
+    parser.add_argument(
+        "--events",
+        nargs="+",
+        default=[],
+        help="Event names to subscribe (e.g. lead_tagged voice_session_status)",
+    )
+    parser.add_argument("--signature-version", dest="signature_version", default="v1")
+    parser.add_argument("--status", default="active", choices=["active", "inactive"])
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_webhooks_create)
+
+
+def _add_webhooks_update(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("update", help="Update a webhook integration")
+    _add_org_arg(parser)
+    parser.add_argument("integration_id")
+    parser.add_argument("--name")
+    parser.add_argument("--agent-id", dest="webhook_agent_id")
+    parser.add_argument("--url")
+    parser.add_argument("--api-key-id", dest="api_key_id")
+    parser.add_argument("--events", nargs="+")
+    parser.add_argument("--signature-version", dest="signature_version")
+    parser.add_argument("--status", choices=["active", "inactive"])
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_webhooks_update)
+
+
+def _add_webhooks_delete(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("delete", help="Soft-deactivate a webhook integration")
+    _add_org_arg(parser)
+    parser.add_argument("integration_id")
+    parser.add_argument("--confirm", action="store_true", help="Required to proceed")
+    parser.set_defaults(handler=handle_webhooks_delete)
+
+
+def handle_webhooks_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    payload = context.webhooks.list(org)
+    if getattr(args, "json", False):
+        context.renderer.print_json(payload)
+        return
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    if not items:
+        print("No webhook integrations.")
+        return
+    for w in items:
+        print(
+            f"{w.get('id')}  {w.get('name')}  status={w.get('status')}  "
+            f"url={w.get('url')}  events={','.join(w.get('events', []))}"
+        )
+
+
+def handle_webhooks_get(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    payload = context.webhooks.get(org, args.integration_id)
+    if getattr(args, "json", False):
+        context.renderer.print_json(payload)
+    else:
+        context.renderer.print_json(payload)
+
+
+def handle_webhooks_create(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    result = context.webhooks.create(
+        org,
+        name=args.name,
+        agent_id=args.webhook_agent_id,
+        url=args.url,
+        api_key_id=args.api_key_id,
+        events=args.events,
+        signature_version=args.signature_version,
+        status=args.status,
+    )
+    if getattr(args, "json", False):
+        context.renderer.print_json(result)
+        return
+    if isinstance(result, dict):
+        print(f"Created webhook integration {result.get('id')}")
+        print(f"  url:    {result.get('url')}")
+        print(f"  events: {','.join(result.get('events', []))}")
+        print(f"  health: {result.get('health_reason') or 'ok'}")
+
+
+def handle_webhooks_update(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    result = context.webhooks.update(
+        org,
+        args.integration_id,
+        name=args.name,
+        agent_id=args.webhook_agent_id,
+        url=args.url,
+        api_key_id=args.api_key_id,
+        events=args.events,
+        signature_version=args.signature_version,
+        status=args.status,
+    )
+    if getattr(args, "json", False):
+        context.renderer.print_json(result)
+    else:
+        print(f"Updated {args.integration_id}")
+
+
+def handle_webhooks_delete(context: RuntimeContext, args: argparse.Namespace) -> None:
+    if not args.confirm:
+        raise ValidationError("--confirm flag required to delete")
+    org = _require_org_id(context, args)
+    context.webhooks.delete(org, args.integration_id)
+    print(f"Deactivated {args.integration_id}")
+
+
+def _add_webhook_domain_policy_get(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "get", help="Show the current allowed-domains list (empty = permissive)"
+    )
+    _add_org_arg(parser)
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_webhook_domain_policy_get)
+
+
+def _add_webhook_domain_policy_set(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("set", help="Replace the allowed-domains list")
+    _add_org_arg(parser)
+    parser.add_argument(
+        "domains",
+        nargs="*",
+        help="Hostnames or *.wildcard patterns (e.g. campaigns.guzli.ai *.example.com). Empty = permissive.",
+    )
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_webhook_domain_policy_set)
+
+
+def handle_webhook_domain_policy_get(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    payload = context.webhook_domain_policy.get(org)
+    if getattr(args, "json", False):
+        context.renderer.print_json(payload)
+        return
+    if isinstance(payload, dict):
+        domains = payload.get("allowed_domains") or []
+        if not domains:
+            print("(permissive — no allowlist set, all webhook URLs accepted)")
+        else:
+            print("Allowed domains:")
+            for d in domains:
+                print(f"  - {d}")
+
+
+def handle_webhook_domain_policy_set(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    result = context.webhook_domain_policy.set(org, list(args.domains))
+    if getattr(args, "json", False):
+        context.renderer.print_json(result)
+    else:
+        print("Policy updated.")
+
+
+def _add_audit_list(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("list", help="List integration security audit events")
+    _add_org_arg(parser)
+    parser.add_argument(
+        "--entity-type",
+        dest="entity_type",
+        help="Filter (e.g. api_key, webhook_integration)",
+    )
+    parser.add_argument("--entity-id", dest="entity_id")
+    parser.add_argument(
+        "--event-type",
+        dest="event_type",
+        help="Filter (e.g. api_key_created, webhook_integration_deleted)",
+    )
+    parser.add_argument("--limit", type=int)
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_audit_list)
+
+
+def handle_audit_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    org = _require_org_id(context, args)
+    payload = context.audit.list(
+        org,
+        entity_type=args.entity_type,
+        entity_id=args.entity_id,
+        event_type=args.event_type,
+        limit=args.limit,
+    )
+    if getattr(args, "json", False):
+        context.renderer.print_json(payload)
+        return
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    if not items:
+        print("No audit events.")
+        return
+    for e in items:
+        actor = e.get("actor_user_id") or e.get("actor_api_key_id") or "(unknown)"
+        summary = e.get("webhook_url_host") or e.get("api_key_prefix") or e.get("entity_id") or ""
+        # auth_source is more precise than auth_mode: distinguishes dashboard_supabase_jwt
+        # vs cli_oauth_session vs api_key vs engine_access_token. Fall back to auth_mode
+        # for older audit rows written before the source column existed.
+        source = e.get("auth_source") or e.get("auth_mode") or "?"
+        cli_sess = e.get("cli_session_id")
+        suffix = f"  cli_sess={cli_sess}" if cli_sess else ""
+        print(
+            f"{e.get('created_at')}  {source:24}  {e.get('event_type'):32}  "
+            f"actor={actor}  {summary}{suffix}"
+        )
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    api_keys = subparsers.add_parser(
+        "api-keys",
+        help="Manage workspace API keys (requires JWT bearer; api-key auth rejected)",
+    )
+    api_keys_sub = api_keys.add_subparsers(dest="api_keys_command", required=True)
+    _add_api_keys_list(api_keys_sub)
+    _add_api_keys_create(api_keys_sub)
+    _add_api_keys_update(api_keys_sub)
+    _add_api_keys_delete(api_keys_sub)
+
+    webhooks = subparsers.add_parser(
+        "webhooks", help="Manage webhook integrations (requires JWT bearer)"
+    )
+    webhooks_sub = webhooks.add_subparsers(dest="webhooks_command", required=True)
+    _add_webhooks_list(webhooks_sub)
+    _add_webhooks_get(webhooks_sub)
+    _add_webhooks_create(webhooks_sub)
+    _add_webhooks_update(webhooks_sub)
+    _add_webhooks_delete(webhooks_sub)
+
+    domain_policy = subparsers.add_parser(
+        "webhook-domain-policy",
+        help="Get / set the per-org webhook URL domain allowlist (requires JWT bearer)",
+    )
+    policy_sub = domain_policy.add_subparsers(dest="webhook_domain_policy_command", required=True)
+    _add_webhook_domain_policy_get(policy_sub)
+    _add_webhook_domain_policy_set(policy_sub)
+
+    audit = subparsers.add_parser(
+        "audit", help="Inspect the integration security audit log (requires JWT bearer)"
+    )
+    audit_sub = audit.add_subparsers(dest="audit_command", required=True)
+    _add_audit_list(audit_sub)