secflow-cli 0.1.0__py3-none-any.whl

secflow_cli/main.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+import getpass
+from importlib.metadata import PackageNotFoundError, version as distribution_version
+import json
+import math
+import os
+import sys
+from urllib.error import HTTPError, URLError
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from secflow_sdk import SecFlowAdminClient, SecFlowConfigError, SecFlowHttpError, SecFlowSdkError
+
+from secflow_cli.config import Profiles, credential_ref, endpoint, profile_name
+from secflow_cli.credentials import CredentialStore
+from secflow_cli.errors import CliError
+from secflow_cli import account_commands, role_commands, namespace_commands, access_profile_commands
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        # argparse includes raw invalid values in its default error messages.
+        raise CliError(2, "INVALID_INPUT", "Invalid or missing arguments. Use --help for command syntax.")
+
+
+def parser():
+    result = Parser(prog="secflowctl", description="SecFlow operator CLI (independent of the service CLI).")
+    try:
+        version = distribution_version("secflow-cli")
+    except PackageNotFoundError:
+        version = "development"
+    result.add_argument("--version", action="version", version=f"secflowctl {version}")
+    result.add_argument("--profile")
+    result.add_argument("--base-url")
+    result.add_argument("--output", choices=("table", "json", "jsonl"))
+    result.add_argument("--non-interactive", action="store_true")
+    result.add_argument("--timeout", type=float, default=5.0)
+    groups = result.add_subparsers(dest="group", required=True)
+    login = groups.add_parser("login")
+    login.add_argument("--no-browser", action="store_true", help="Print the login URL without opening a browser.")
+    login.set_defaults(action="login", browser=True, ephemeral=False, token_stdin=False)
+    profiles = groups.add_parser("profile").add_subparsers(dest="action", required=True)
+    for action in ("add", "list", "show", "use", "remove"):
+        command = profiles.add_parser(action)
+        if action in ("add", "use", "remove"):
+            command.add_argument("name")
+        if action == "show":
+            command.add_argument("name", nargs="?")
+        if action == "add":
+            command.add_argument("--base-url", required=True)
+    auth = groups.add_parser("auth").add_subparsers(dest="action", required=True)
+    for action in ("login", "status", "whoami", "logout", "forget"):
+        command = auth.add_parser(action)
+        if action != "forget":
+            command.add_argument("--token-stdin", action="store_true")
+        if action == "login":
+            command.add_argument("--ephemeral", action="store_true")
+            command.add_argument("--browser", action="store_true", help="Log in through Intflow in a browser.")
+            command.add_argument("--no-browser", action="store_true", help="With --browser, print the URL without opening it.")
+    groups.add_parser("health")
+    access_profile_commands.add_commands(groups)
+    for resource in ("namespaces", "accounts", "tokens", "roles"):
+        commands = groups.add_parser(resource).add_subparsers(dest="action", required=True)
+        listing = commands.add_parser("list")
+        if resource != "roles":
+            listing.add_argument("--query")
+        listing.add_argument("--page-size", type=int, default=50)
+        listing.add_argument("--page-token")
+        listing.add_argument("--all", action="store_true")
+        listing.add_argument("--max-pages", type=int, default=100)
+        listing.add_argument("--token-stdin", action="store_true")
+        if resource == "tokens":
+            listing.add_argument("--namespace")
+            listing.add_argument("--status", choices=("active", "revoked", "expired"))
+        if resource == "accounts":
+            account_commands.add_commands(commands)
+        if resource == "roles":
+            role_commands.add_commands(commands)
+        if resource == "namespaces":
+            namespace_commands.add_commands(commands)
+    from secflow_cli.help import enrich
+    enrich(result)
+    return result
+
+
+def safe_fields(value, fields):
+    if not isinstance(value, Mapping):
+        raise CliError(7, "INVALID_RESPONSE", "The server returned an invalid metadata response.")
+    return {key: value[key] for key in fields if key in value and (value[key] is None or isinstance(value[key], (str, bool, int)))}
+
+
+ACCOUNT_FIELDS = ("account_id", "email", "domain", "display_name", "status", "source", "created_at", "last_login_at")
+NAMESPACE_FIELDS = ("namespace", "environment", "service", "owner", "administrator", "audit_logging", "status")
+TOKEN_FIELDS = ("token_id", "account_id", "scope_type", "scope", "issued_at", "expires_at", "revoked_at", "last_used_at", "status")
+ROLE_FIELDS = role_commands.FIELDS
+
+
+def account_metadata(value):
+    result = safe_fields(value, ACCOUNT_FIELDS)
+    roles = value.get("roles")
+    if isinstance(roles, list):
+        result["roles"] = [role for role in roles if role in ("org_admin", "namespace_admin", "secret_writer", "secret_reader")]
+    return result
+
+
+def envelope(command, data=None, *, cursor=None, error=None):
+    return {"schema_version": 1, "command": command, "data": data, "request_id": None, "trace_id": None,
+            "pagination": {"next_page_token": cursor},
+            "error": {"code": error.code, "message": error.message} if error else None}
+
+
+def render(record, output):
+    if output in ("json", "jsonl"):
+        print(json.dumps(record, ensure_ascii=True, separators=(",", ":")))
+        return
+    data = record["data"]
+    rows = data if isinstance(data, list) else [data] if data is not None else []
+    if not rows and not record["error"]:
+        print("No results.")
+    for row in rows:
+        if isinstance(row, dict):
+            print("  ".join(f"{key}: {json.dumps(value, ensure_ascii=True) if isinstance(value, (dict, list)) else _terminal(value)}" for key, value in row.items()))
+        else:
+            print(_terminal(row))
+    if record["pagination"]["next_page_token"]:
+        print("More results available; use --page-token or --all.", file=sys.stderr)
+
+
+def _terminal(value):
+    return "".join(c if c.isprintable() else "?" for c in str(value))
+
+
+def mapped_error(error):
+    if isinstance(error, CliError):
+        return error
+    if isinstance(error, SecFlowHttpError):
+        status, code, message = {
+            401: (3, "AUTHENTICATION_FAILED", "The server rejected the Admin session. Sign in again with secflowctl login, or import a new Slack session with secflowctl auth login."),
+            403: (4, "ACCESS_DENIED", "The server denied this operation. Check secflowctl auth status and ask your administrator to review roles and scope."),
+            404: (5, "NOT_FOUND", "The requested resource was not found."),
+            409: (6, "CONFLICT", "The server reported a conflict."),
+            412: (6, "PRECONDITION_CHANGED", "The server precondition changed."),
+            400: (2, "INVALID_INPUT", "The server rejected the request inputs."),
+            422: (2, "INVALID_INPUT", "The server rejected the request inputs."),
+        }.get(error.status_code, (7, "DEPENDENCY_FAILED", "The server request could not be completed."))
+        return CliError(status, code, message)
+    if isinstance(error, SecFlowConfigError):
+        return CliError(2, "INVALID_INPUT", "The client configuration or request inputs are invalid.")
+    if isinstance(error, (SecFlowSdkError, URLError, TimeoutError)):
+        return CliError(7, "DEPENDENCY_FAILED", "The server request could not be completed.")
+    return CliError(1, "LOCAL_FAILURE", "The CLI could not complete this operation.")
+
+
+def read_token(args, *, prompt=False):
+    if getattr(args, "token_stdin", False):
+        value = sys.stdin.read(16385)
+        if len(value) > 16384:
+            raise CliError(2, "INVALID_CREDENTIAL_INPUT", "Credential input exceeds the supported size.")
+        value = value.rstrip("\r\n")
+    elif os.environ.get("SECFLOW_ADMIN_SESSION_TOKEN"):
+        value = os.environ["SECFLOW_ADMIN_SESSION_TOKEN"]
+    elif prompt and not args.non_interactive and sys.stdin.isatty():
+        value = getpass.getpass("Admin session token: ")
+    else:
+        return None
+    if not value or any(c.isspace() or ord(c) < 33 or ord(c) > 126 for c in value):
+        raise CliError(2, "INVALID_CREDENTIAL_INPUT", "Provide one non-empty Admin session token.")
+    return value
+
+
+def resolve_client(args, profile, url, store):
+    token = read_token(args)
+    if token is None:
+        if url != profile["base_url"]:
+            raise CliError(3, "CREDENTIAL_ORIGIN_MISMATCH", "An endpoint override cannot reuse credentials from another origin. Supply an explicit Admin session.")
+        try:
+            token = store.get(profile["credential_ref"])
+        except CliError as error:
+            if error.code == "CREDENTIAL_STORE_UNAVAILABLE":
+                raise CliError(3, "AUTHENTICATION_REQUIRED", "Run secflowctl login, or supply an Admin session through --token-stdin, SECFLOW_ADMIN_SESSION_TOKEN, or secflowctl auth login.") from None
+            raise
+    if not token:
+        raise CliError(3, "AUTHENTICATION_REQUIRED", "Run secflowctl login, or supply an Admin session through --token-stdin, SECFLOW_ADMIN_SESSION_TOKEN, or secflowctl auth login.")
+    return SecFlowAdminClient(url, admin_session_token=token, timeout=args.timeout)
+
+
+def profile_command(args, profiles):
+    entries = profiles.data["profiles"]
+    if args.action == "list":
+        return [{"name": name, "base_url": item["base_url"], "current": name == profiles.data["current"]} for name, item in sorted(entries.items())]
+    if args.action == "show":
+        name, item = profiles.select(args.name or args.profile)
+        return {"name": name, "base_url": item["base_url"], "current": name == profiles.data["current"]}
+    name = profile_name(args.name)
+    if args.action == "add":
+        if name in entries:
+            raise CliError(6, "PROFILE_EXISTS", "The profile already exists; use a new profile name.")
+        url = endpoint(args.base_url)
+        entries[name] = {"base_url": url, "credential_ref": credential_ref(name, url)}
+        if profiles.data["current"] is None:
+            profiles.data["current"] = name
+    else:
+        if name not in entries:
+            raise CliError(5, "PROFILE_NOT_FOUND", "The profile does not exist.")
+        if args.action == "use":
+            profiles.data["current"] = name
+        else:
+            # Local configuration removal does not revoke a server session.
+            CredentialStore(allow_interaction=not args.non_interactive and sys.stdin.isatty()).delete(entries[name]["credential_ref"])
+            del entries[name]
+            if profiles.data["current"] == name:
+                profiles.data["current"] = None
+    profiles.save()
+    return {"name": name, "action": args.action}
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def health(url, timeout):
+    result = {}
+    opener = build_opener(NoRedirect)
+    for path in ("healthz", "readyz"):
+        try:
+            with opener.open(Request(f"{url}/{path}", headers={"Accept": "application/json"}), timeout=timeout) as response:
+                raw = response.read(65537)
+                if len(raw) > 65536:
+                    raise ValueError
+                value = json.loads(raw)
+                status = value.get("status") if isinstance(value, dict) else None
+                result[path] = {"status": status if status in ("ok", "ready", "not_ready") else "unknown"}
+        except (HTTPError, URLError, OSError, ValueError):
+            result[path] = {"status": "unavailable"}
+    ok = result["healthz"]["status"] == "ok" and result["readyz"]["status"] == "ready"
+    return result, None if ok else CliError(7, "UNHEALTHY", "Health or readiness did not succeed.")
+
+
+def collection_pages(args, client, command, output):
+    if not 1 <= args.page_size <= 200 or not 1 <= args.max_pages <= 1000:
+        raise CliError(2, "INVALID_INPUT", "Page size must be 1-200 and max pages must be 1-1000.")
+    rows, cursor, seen = [], args.page_token, set()
+    if cursor:
+        seen.add(cursor)
+    fetch = {"namespaces": client.list_namespaces, "accounts": client.list_accounts, "tokens": client.list_sdk_tokens, "roles": client.list_role_bindings}[args.group]
+    filters = {"namespace": args.namespace, "status": args.status} if args.group == "tokens" else {}
+    if args.group != "roles":
+        filters["q"] = args.query
+    for index in range(args.max_pages if args.all else 1):
+        try:
+            page = fetch(page_token=cursor, page_size=args.page_size, **filters)
+            items = page.get("items")
+            if not isinstance(items, list):
+                raise CliError(7, "INVALID_RESPONSE", "The server returned an invalid page.")
+            fields = {"namespaces": NAMESPACE_FIELDS, "tokens": TOKEN_FIELDS, "roles": ROLE_FIELDS}
+            page_rows = [account_metadata(item) if args.group == "accounts" else safe_fields(item, fields[args.group]) for item in items]
+            next_cursor = page.get("next_page_token")
+            if next_cursor is not None and (not isinstance(next_cursor, str) or not next_cursor or len(next_cursor) > 8192):
+                raise CliError(7, "INVALID_RESPONSE", "The server returned an invalid page cursor.")
+            rows.extend(page_rows)
+            cursor = next_cursor
+            if output == "jsonl":
+                render(envelope(command, page_rows, cursor=cursor), output)
+            if not args.all or cursor is None:
+                if output != "jsonl":
+                    render(envelope(command, rows, cursor=cursor), output)
+                return 0
+            if cursor in seen:
+                raise CliError(8, "PAGINATION_INCOMPLETE", "The server repeated a page cursor; results are incomplete.")
+            seen.add(cursor)
+        except (CliError, SecFlowSdkError) as caught:
+            error = mapped_error(caught)
+            if rows:
+                error = CliError(8, "PAGINATION_INCOMPLETE", "Page retrieval stopped; results are incomplete.")
+            render(envelope(command, [] if output == "jsonl" else rows, cursor=cursor, error=error), output)
+            print(error.message, file=sys.stderr)
+            return error.status
+    error = CliError(8, "PAGE_BOUND_REACHED", "The page bound was reached; use the next page token to continue.")
+    render(envelope(command, [] if output == "jsonl" else rows, cursor=cursor, error=error), output)
+    print(error.message, file=sys.stderr)
+    return 8
+
+
+def main(argv=None):
+    output = "table" if sys.stdout.isatty() else "json"
+    command = "cli"
+    try:
+        arguments = list(sys.argv[1:] if argv is None else argv)
+        root = parser()
+        if not arguments:
+            root.print_help()
+            return 0
+        args = root.parse_args(arguments)
+        quick_login = args.group == "login"
+        if quick_login:
+            if args.non_interactive or not sys.stdin.isatty():
+                raise CliError(2, "INTERACTIVE_LOGIN_REQUIRED", "Use an interactive terminal for login; automation can use auth login --token-stdin.")
+            args.group = "auth"
+        output = args.output or output
+        command = args.group + (" " + args.action if hasattr(args, "action") else "")
+        if not math.isfinite(args.timeout) or not 0 < args.timeout <= 300:
+            raise CliError(2, "INVALID_INPUT", "Timeout must be greater than zero and at most 300 seconds.")
+        if output == "jsonl" and command not in ("profile list", "namespaces list", "accounts list", "tokens list", "roles list"):
+            raise CliError(2, "INVALID_INPUT", "JSONL output is available for collection commands only.")
+        profiles = Profiles()
+        if quick_login and not profiles.data["profiles"] and not args.profile and not os.environ.get("SECFLOW_PROFILE"):
+            url = endpoint(args.base_url or os.environ.get("SECFLOW_BASE_URL") or "https://secflow.intflow.dev")
+            profiles.data["profiles"]["production"] = {"base_url": url, "credential_ref": credential_ref("production", url)}
+            profiles.data["current"] = "production"
+            profiles.save()
+        error = None
+        if args.group == "profile":
+            data = profile_command(args, profiles)
+        else:
+            name, profile = profiles.select(args.profile)
+            url = endpoint(args.base_url or os.environ.get("SECFLOW_BASE_URL") or profile["base_url"])
+            store = CredentialStore(allow_interaction=not args.non_interactive and sys.stdin.isatty())
+            if args.group == "health":
+                data, error = health(url, args.timeout)
+            elif args.group == "auth" and args.action == "login":
+                if url != profile["base_url"]:
+                    raise CliError(2, "PROFILE_ORIGIN_MISMATCH", "Create a profile for the login server origin.")
+                if args.no_browser and not args.browser:
+                    raise CliError(2, "INVALID_INPUT", "--no-browser requires --browser.")
+                if args.browser:
+                    if args.non_interactive or not sys.stdin.isatty() or args.ephemeral or args.token_stdin:
+                        raise CliError(2, "INTERACTIVE_LOGIN_REQUIRED", "Browser login requires an interactive terminal and OS credential storage; omit --token-stdin and --ephemeral.")
+                    from secflow_cli.browser_login import login
+                    account, expires_at = login(url, args.timeout, store, profile["credential_ref"], no_browser=args.no_browser)
+                    render(envelope(command, {"account": account_metadata(account), "credential_storage": "os-store", "expires_at": expires_at}), output)
+                    from secflow_cli.help import login_hint
+                    login_hint(args, account)
+                    return 0
+                if not args.ephemeral:
+                    store.check()
+                token = read_token(args, prompt=True)
+                if token is None:
+                    raise CliError(3, "AUTHENTICATION_REQUIRED", "Provide --token-stdin or SECFLOW_ADMIN_SESSION_TOKEN; interactive login accepts a hidden prompt.")
+                client = SecFlowAdminClient(url, admin_session_token=token, timeout=args.timeout)
+                account = account_metadata(client.get_current_account())
+                if not args.ephemeral:
+                    store.set(profile["credential_ref"], token)
+                data = {"account": account, "credential_storage": "ephemeral" if args.ephemeral else "os-store"}
+                if args.ephemeral:
+                    print("Session validated for this invocation only. Supply the credential again for subsequent commands.", file=sys.stderr)
+            elif args.group == "auth" and args.action == "forget":
+                store.delete(profile["credential_ref"])
+                data = {"local_credential_cleared": True, "server_revocation": "not_attempted"}
+            else:
+                account_mutation = args.group == "accounts" and args.action in account_commands.ACTIONS
+                role_mutation = args.group == "roles" and args.action in role_commands.ACTIONS
+                namespace_mutation = args.group == "namespaces" and args.action in namespace_commands.ACTIONS
+                access_profile_mutation = args.group == "access-profile" and args.action == "set"
+                mutation_module = account_commands if account_mutation else role_commands if role_mutation else namespace_commands if namespace_mutation else access_profile_commands if access_profile_mutation else None
+                mutation_values = mutation_module.prepare(args) if mutation_module else None
+                client = resolve_client(args, profile, url, store)
+                if access_profile_mutation:
+                    data, error = access_profile_commands.execute(client, mutation_values, mapped_error=mapped_error)
+                elif args.group == "access-profile":
+                    data = access_profile_commands.metadata(client.get_default_access_profile())
+                elif account_mutation:
+                    data, error = account_commands.execute(args, client, mutation_values, account_metadata=account_metadata, mapped_error=mapped_error)
+                elif role_mutation:
+                    data, error = role_commands.execute(args, client, mutation_values, safe_fields=safe_fields, mapped_error=mapped_error)
+                elif namespace_mutation:
+                    data, error = namespace_commands.execute(args, client, mutation_values, safe_fields=safe_fields, mapped_error=mapped_error)
+                elif args.group in ("namespaces", "accounts", "tokens", "roles"):
+                    return collection_pages(args, client, command, output)
+                elif args.action in ("status", "whoami"):
+                    data = {"account": account_metadata(client.get_current_account()), "expires_at": None, "capabilities": None}
+                elif args.action == "logout":
+                    if url != profile["base_url"]:
+                        raise CliError(2, "PROFILE_ORIGIN_MISMATCH", "Logout must use the selected profile origin.")
+                    error = None
+                    try:
+                        client.revoke_current_session()
+                    except SecFlowSdkError as caught:
+                        error = mapped_error(caught)
+                    data = {"server_revocation": "failed_or_unknown" if error else "confirmed", "local_credential_cleared": False}
+                    try:
+                        store.delete(profile["credential_ref"])
+                        data["local_credential_cleared"] = True
+                    except CliError as caught:
+                        error = error or caught
+                    print("Environment and caller-managed stdin credentials are not erased by logout.", file=sys.stderr)
+                else:
+                    raise CliError(2, "INVALID_INPUT", "Unsupported command.")
+        render(envelope(command, data, error=error), output)
+        if command == "auth login" and not error and not args.ephemeral:
+            from secflow_cli.help import login_hint
+            login_hint(args, account)
+        if error:
+            print(error.message, file=sys.stderr)
+        return error.status if error else 0
+    except KeyboardInterrupt:
+        error = CliError(130, "INTERRUPTED", "Operation interrupted; completion is not guaranteed.")
+    except Exception as caught:
+        error = mapped_error(caught)
+    render(envelope(command, error=error), output)
+    print(error.message, file=sys.stderr)
+    return error.status

secflow_cli/namespace_commands.py

@@ -0,0 +1,151 @@
+"""Namespace metadata operations using the existing Admin API."""
+import re
+import sys
+from collections.abc import Mapping
+from uuid import uuid4
+
+from secflow_sdk import SecFlowConfigError, SecFlowSdkError
+from secflow_cli.account_commands import required_input
+from secflow_cli.errors import CliError
+
+ACTIONS = ("create", "update", "delete")
+FIELDS = ("namespace", "environment", "service", "owner", "administrator", "audit_logging", "status")
+
+
+def add_commands(commands):
+    for action in ACTIONS:
+        command = commands.add_parser(action)
+        command.add_argument("--namespace")
+        command.add_argument("--token-stdin", action="store_true")
+        command.add_argument("--idempotency-key")
+        if action == "delete":
+            command.add_argument("--yes", action="store_true")
+            continue
+        command.add_argument("--owner")
+        command.add_argument("--administrator")
+        command.add_argument("--audit-logging", choices=("true", "false"))
+        command.add_argument("--max-secret-ttl-days", help="1-3660, or none for no maximum")
+        command.add_argument("--warn-before-days", type=int)
+        if action == "update":
+            command.add_argument("--clear-expiration-policy", action="store_true")
+
+
+def prepare(args):
+    target = required_input(args, "namespace", "namespace")
+    if not re.fullmatch(r"(dev|stage|prod|shared)/[a-z0-9][a-z0-9._-]{1,62}", target):
+        raise CliError(2, "INVALID_INPUT", "Supply an exact namespace in environment/service form.")
+    key = args.idempotency_key or "cli-namespace-" + str(uuid4())
+    if not re.fullmatch(r"[A-Za-z0-9_.:-]{16,128}", key):
+        raise CliError(2, "INVALID_INPUT", "Supply a normalized idempotency key of 16-128 characters.")
+    environment, service = target.split("/")
+    values = dict(environment=environment, service=service, idempotency_key=key)
+    if args.action == "delete":
+        confirm_delete(args, target)
+        return values
+    if args.action == "update":
+        choose_update(args)
+    for field in ("owner", "administrator", "audit_logging"):
+        if args.action == "update" and getattr(args, field) is None:
+            continue
+        value = required_input(args, field, field.replace("_", " "))
+        if field == "audit_logging":
+            if value not in ("true", "false"):
+                raise CliError(2, "INVALID_INPUT", "Audit logging must be true or false.")
+            value = value == "true"
+        values[field] = value
+    ttl = args.max_secret_ttl_days
+    if ttl is None and environment == "prod" and args.action == "create":
+        ttl = required_input(args, "max_secret_ttl_days", "maximum secret TTL days (1-3660 or none)")
+    if ttl is not None:
+        if ttl != "none" and (not re.fullmatch(r"[0-9]{1,4}", ttl) or not 1 <= int(ttl) <= 3660):
+            raise CliError(2, "INVALID_INPUT", "Maximum secret TTL must be 1-3660 or none.")
+        values["expiration_policy"] = {"max_secret_ttl_days": None if ttl == "none" else int(ttl)}
+    if args.warn_before_days is not None:
+        if ttl in (None, "none") or not 1 <= args.warn_before_days <= 365:
+            raise CliError(2, "INVALID_INPUT", "Warning days require a finite maximum TTL and must be 1-365.")
+        values["expiration_policy"]["warn_before_days"] = args.warn_before_days
+    if getattr(args, "clear_expiration_policy", False):
+        if ttl is not None or args.warn_before_days is not None or environment == "prod":
+            raise CliError(2, "INVALID_INPUT", "Policy clearing cannot be combined with policy fields or used for production.")
+        values["expiration_policy"] = None
+    if environment == "prod" and values.get("audit_logging") is False:
+        raise CliError(2, "INVALID_INPUT", "Production namespaces require audit logging.")
+    return values
+
+
+def confirm_delete(args, target):
+    print("Delete namespace: " + target, file=sys.stderr)
+    print("Operation semantics, not a server impact preview: removes the namespace and related secrets, SDK tokens, role bindings, and policies. Affected counts are unknown.", file=sys.stderr)
+    if args.yes:
+        return
+    if args.non_interactive or args.token_stdin or not sys.stdin.isatty():
+        raise CliError(2, "CONFIRMATION_REQUIRED", "Supply the exact namespace and --yes for unattended execution or when stdin carries a token.")
+    print("Type the namespace to confirm: ", end="", file=sys.stderr, flush=True)
+    try:
+        answer = input()
+    except EOFError:
+        answer = None
+    if answer != target:
+        raise CliError(2, "CONFIRMATION_CANCELLED", "Namespace deletion cancelled; no mutation was sent.")
+
+
+def choose_update(args):
+    fields = ("owner", "administrator", "audit_logging", "max_secret_ttl_days", "warn_before_days")
+    if args.clear_expiration_policy or any(getattr(args, field) is not None for field in fields):
+        return
+    if args.non_interactive or args.token_stdin or not sys.stdin.isatty():
+        raise CliError(2, "INVALID_INPUT", "Supply at least one namespace field to update.")
+    args.update_field = None
+    field = required_input(args, "update_field", "field to update (owner, administrator, audit_logging, max_secret_ttl_days, clear_expiration_policy)")
+    if field == "clear_expiration_policy":
+        args.clear_expiration_policy = True
+    elif field in fields and field != "warn_before_days":
+        setattr(args, field, required_input(args, field, field.replace("_", " ")))
+    else:
+        raise CliError(2, "INVALID_INPUT", "Select a supported namespace field.")
+
+
+def metadata(response, safe_fields):
+    result = safe_fields(response, FIELDS)
+    if "expiration_policy" in response:
+        policy = response["expiration_policy"]
+        if policy is None:
+            result["expiration_policy"] = None
+        elif isinstance(policy, Mapping):
+            result["expiration_policy"] = {key: policy[key] for key in ("max_secret_ttl_days", "warn_before_days") if key in policy and (policy[key] is None or type(policy[key]) is int)}
+        else:
+            raise CliError(7, "INVALID_RESPONSE", "The server returned invalid expiration metadata.")
+    return result
+
+
+def execute(args, client, values, *, safe_fields, mapped_error):
+    key = values["idempotency_key"]
+    print("Idempotency key: " + key, file=sys.stderr)
+    data = dict(idempotency_key=key, outcome="unknown", namespace=None)
+    if args.action == "delete":
+        data["deletion"] = None
+    try:
+        target = values["environment"] + "/" + values["service"]
+        if args.action == "delete":
+            response = client.delete_namespace(**values)
+            if (not isinstance(response, Mapping) or response.get("kind") != "namespace"
+                    or response.get("id") != target or response.get("label") != target or response.get("deleted") is not True):
+                raise CliError(7, "INVALID_RESPONSE", "The server did not confirm deletion of the selected namespace.")
+            data.update(outcome="confirmed", deletion={field: response[field] for field in ("kind", "id", "label", "deleted")})
+            return data, None
+        method = client.create_namespace if args.action == "create" else client.patch_namespace
+        result = metadata(method(**values), safe_fields)
+        if (result.get("namespace") != target or (args.action == "create" and result.get("status") != "active")
+                or any(result.get(field) != value for field, value in values.items() if field != "idempotency_key")):
+            raise CliError(7, "INVALID_RESPONSE", "The server did not confirm the requested namespace metadata.")
+        data.update(outcome="confirmed", namespace=result)
+        return data, None
+    except (SecFlowSdkError, CliError) as caught:
+        error = mapped_error(caught)
+        if isinstance(caught, SecFlowConfigError):
+            data["outcome"] = "not_sent"
+        elif error.status in (2, 3, 4, 5, 6):
+            data["outcome"] = "not_confirmed"
+        else:
+            error = CliError(7, "MUTATION_OUTCOME_UNKNOWN", "Mutation completion is unknown. Inspect current state; any retry must use identical inputs and the same idempotency key.")
+        return data, error

secflow_cli/role_commands.py

@@ -0,0 +1,99 @@
+"""Role mutations through the existing Admin API."""
+import re
+import sys
+from uuid import UUID, uuid4
+
+from secflow_sdk import SecFlowConfigError, SecFlowSdkError
+from secflow_cli.account_commands import required_input
+from secflow_cli.errors import CliError
+
+ACTIONS = ("grant", "revoke")
+FIELDS = ("binding_id", "principal_type", "principal_id", "role", "scope_type", "scope", "status", "created_at")
+ROLES = ("org_admin", "namespace_admin", "secret_reader", "secret_writer")
+
+
+def add_commands(commands):
+    command = commands.add_parser("grant")
+    command.add_argument("--token-stdin", action="store_true")
+    command.add_argument("--idempotency-key")
+    command.add_argument("--account-id")
+    command.add_argument("--role", choices=ROLES)
+    command.add_argument("--scope-type", choices=("org", "namespace"))
+    command.add_argument("--scope")
+    revoke = commands.add_parser("revoke")
+    revoke.add_argument("--token-stdin", action="store_true")
+    revoke.add_argument("--idempotency-key")
+    revoke.add_argument("--binding-id")
+    revoke.add_argument("--yes", action="store_true")
+
+
+def canonical_id(value):
+    try:
+        return isinstance(value, str) and str(UUID(value)) == value
+    except ValueError:
+        return False
+
+
+def prepare(args):
+    key = args.idempotency_key or "cli-role-" + str(uuid4())
+    if not re.fullmatch(r"[A-Za-z0-9_.:-]{16,128}", key):
+        raise CliError(2, "INVALID_INPUT", "Supply a normalized idempotency key of 16-128 characters.")
+    if args.action == "revoke":
+        binding_id = required_input(args, "binding_id", "binding ID")
+        if not canonical_id(binding_id):
+            raise CliError(2, "INVALID_INPUT", "Supply an exact canonical binding UUID.")
+        confirm_revoke(args, binding_id)
+        return dict(binding_id=binding_id, idempotency_key=key)
+    account = required_input(args, "account_id", "account ID")
+    role = required_input(args, "role", "role")
+    scope_type = required_input(args, "scope_type", "scope type")
+    expected = "org" if role in ("org_admin", "namespace_admin") else "namespace"
+    if not canonical_id(account) or role not in ROLES or scope_type != expected:
+        raise CliError(2, "INVALID_INPUT", "Supply a canonical account UUID and a supported role/scope combination.")
+    scope = required_input(args, "scope", "namespace") if scope_type == "namespace" else args.scope
+    if (scope_type == "org" and scope is not None) or (scope_type == "namespace" and not re.fullmatch(r"(dev|stage|prod|shared)/[a-z0-9][a-z0-9._-]{1,62}", scope)):
+        raise CliError(2, "INVALID_INPUT", "Supply a valid namespace only for namespace scope.")
+    return dict(idempotency_key=key, principal_type="account", principal_id=account, role=role, scope_type=scope_type, scope=scope)
+
+
+def confirm_revoke(args, binding_id):
+    print("Revoke role binding: " + binding_id, file=sys.stderr)
+    print("Operation semantics, not a server impact preview: marks this binding inactive and invalidates affected Admin sessions. Other grants may retain access. Affected counts are unknown.", file=sys.stderr)
+    if args.yes:
+        return
+    if args.non_interactive or args.token_stdin or not sys.stdin.isatty():
+        raise CliError(2, "CONFIRMATION_REQUIRED", "Supply the exact binding ID and --yes for unattended execution or when stdin carries a token.")
+    print("Type the binding ID to confirm: ", end="", file=sys.stderr, flush=True)
+    try:
+        answer = input()
+    except EOFError:
+        answer = None
+    if answer != binding_id:
+        raise CliError(2, "CONFIRMATION_CANCELLED", "Role revocation cancelled; no mutation was sent.")
+
+
+def execute(args, client, values, *, safe_fields, mapped_error):
+    key = values["idempotency_key"]
+    print("Idempotency key: " + key, file=sys.stderr)
+    data = dict(idempotency_key=key, outcome="unknown", binding=None)
+    try:
+        method = client.create_role_binding if args.action == "grant" else client.revoke_role_binding
+        binding = safe_fields(method(**values), FIELDS)
+        if args.action == "revoke":
+            confirmed = binding.get("binding_id") == values["binding_id"] and binding.get("status") == "inactive"
+        else:
+            confirmed = (canonical_id(binding.get("binding_id")) and binding.get("status") == "active"
+                         and all(binding.get(field) == values[field] for field in ("principal_type", "principal_id", "role", "scope_type", "scope")))
+        if not confirmed:
+            raise CliError(7, "INVALID_RESPONSE", "The server did not confirm the requested role assignment.")
+        data.update(outcome="confirmed", binding=binding)
+        return data, None
+    except (SecFlowSdkError, CliError) as caught:
+        error = mapped_error(caught)
+        if isinstance(caught, SecFlowConfigError):
+            data["outcome"] = "not_sent"
+        elif error.status in (2, 3, 4, 5, 6):
+            data["outcome"] = "not_confirmed"
+        else:
+            error = CliError(7, "MUTATION_OUTCOME_UNKNOWN", "Mutation completion is unknown. Inspect current state; any retry must use identical inputs and the same idempotency key.")
+        return data, error