agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/payment_manager.py

@@ -0,0 +1,605 @@
+"""Payment manager add/remove (port of src/cli/primitives/PaymentManagerPrimitive.ts).
+
+Adding a manager also wires the payments capability shim into eligible (Python Strands HTTP)
+agents. Connectors are managed by ``payment_connector``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+import typer
+
+from agentcore.cli import interactive
+from agentcore.cli.constants import ANSI
+from agentcore.cli.errors import get_error_message
+from agentcore.lib import remove_env_vars
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok, serialize_result
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.primitives.base import (
+    SOURCE_CODE_NOTE,
+    BasePrimitive,
+    RemovableResource,
+    RemovalPreview,
+    SchemaChange,
+    emit_json,
+)
+from agentcore.primitives.credential_utils import (
+    compute_payment_credential_env_var_names,
+    compute_stripe_privy_credential_env_var_names,
+)
+from agentcore.primitives.payment_eligible import is_payment_eligible_runtime
+from agentcore.schema import DEFAULT_AUTO_PAYMENT, DEFAULT_SPEND_LIMIT
+
+PAYMENT_AUTHORIZER_TYPES = ("AWS_IAM", "CUSTOM_JWT")
+_IMPORT_LINE = "from capabilities.payments.payments import create_payments_plugin, PAYMENT_SYSTEM_PROMPT"
+
+
+def compute_import_insertion_point(source: str) -> int:
+    """Offset just after any shebang/comments, module docstring and ``from __future__`` imports."""
+    pos, length = 0, len(source)
+    while pos < length:
+        if source[pos] == "\n":
+            pos += 1
+            continue
+        line_end = source.find("\n", pos)
+        line_end_pos = length if line_end == -1 else line_end
+        line = source[pos:line_end_pos]
+        trimmed = line.strip()
+        if trimmed.startswith("#"):
+            pos = line_end_pos + 1
+            continue
+        if trimmed.startswith(('"""', "'''")):
+            quote = trimmed[:3]
+            rest = trimmed[3:]
+            if rest.endswith(quote) and len(rest) >= 3:
+                pos = line_end_pos + 1
+                continue
+            close = source.find(quote, pos + 3)
+            if close == -1:
+                break
+            after = source.find("\n", close + 3)
+            pos = length if after == -1 else after + 1
+            continue
+        if re.match(r"^from __future__ import\b", trimmed):
+            open_paren = line.find("(")
+            if open_paren != -1 and ")" not in line[open_paren:]:
+                close_paren = source.find(")", pos)
+                if close_paren == -1:
+                    break
+                after = source.find("\n", close_paren)
+                pos = length if after == -1 else after + 1
+            else:
+                pos = line_end_pos + 1
+            continue
+        break
+    return pos
+
+
+def _plugin_setup(indent: str) -> list[str]:
+    return [
+        f"{indent}# Payment plugin (per-invocation — different user/instrument/session per request)",
+        f'{indent}user_id = payload.get("user_id") or getattr(context, "user_id", "default-user")',
+        f'{indent}instrument_id = payload.get("payment_instrument_id")',
+        f'{indent}session_id = payload.get("payment_session_id")',
+        f"{indent}payments_plugin = create_payments_plugin(user_id, instrument_id, session_id)",
+        f"{indent}plugins = [payments_plugin] if payments_plugin else []",
+        "",
+    ]
+
+
+def wire_payment_capability(config_root: str, code_location: str) -> bool:
+    """Copy the payments capability into a Strands agent and patch its main.py (idempotent)."""
+    from agentcore.templates.template_root import get_template_path
+
+    project_root = os.path.dirname(config_root)
+    agent_dir = os.path.abspath(os.path.join(project_root, code_location))
+    cap_dir = os.path.join(agent_dir, "capabilities", "payments")
+    main_path = os.path.join(agent_dir, "main.py")
+    if not os.path.exists(main_path):
+        return False
+    with open(main_path, encoding="utf-8") as fh:
+        main = fh.read()
+
+    is_strands = bool(re.search(r"^from strands(\.|\s)", main, re.M)) or "from strands import" in main
+    if not is_strands:
+        return False
+
+    template_dir = get_template_path("python", "http", "strands", "capabilities", "payments")
+    if not template_dir.is_dir():
+        return False
+
+    if not os.path.exists(os.path.join(cap_dir, "payments.py")):
+        os.makedirs(cap_dir, exist_ok=True)
+        with open(os.path.join(cap_dir, "payments.py"), "w", encoding="utf-8") as fh:
+            fh.write((template_dir / "payments.py").read_text(encoding="utf-8"))
+    for init_path in (os.path.join(cap_dir, "__init__.py"), os.path.join(agent_dir, "capabilities", "__init__.py")):
+        if not os.path.exists(init_path):
+            with open(init_path, "w", encoding="utf-8"):
+                pass
+
+    if "create_payments_plugin" in main:
+        return True
+
+    insert = compute_import_insertion_point(main)
+    patched = main[:insert] + _IMPORT_LINE + "\n" + main[insert:]
+
+    agent_call = re.search(r"^([^\S\n]*)agent = get_or_create_agent\(\)[ \t]*(#[^\n]*)?$", patched, re.M)
+    if agent_call:
+        indent = agent_call.group(1)
+        uses_config_bundle = bool(re.search(r"\bConfigBundleHook\b", patched))
+        replacement = "\n".join(
+            [
+                *_plugin_setup(indent),
+                f"{indent}agent = Agent(",
+                f"{indent}    model=load_model(),",
+                f"{indent}    system_prompt=DEFAULT_SYSTEM_PROMPT + PAYMENT_SYSTEM_PROMPT,",
+                f"{indent}    tools=tools,",
+                f"{indent}    plugins=plugins,",
+                *([f"{indent}    hooks=[ConfigBundleHook()],"] if uses_config_bundle else []),
+                f"{indent})",
+            ]
+        )
+        patched = patched[: agent_call.start()] + replacement + patched[agent_call.end() :]
+        singleton = re.compile(
+            r"^_agent(?:\s*:[^=\n]+)?\s*=\s*None\n\n+def get_or_create_agent\(\):[\s\S]+?return _agent\n", re.M
+        )
+        before = patched
+        patched = singleton.sub("", patched, count=1)
+        if patched == before:
+            raise Exception(
+                f"Could not safely auto-wire payments into {main_path}: the agent= call was replaced but the cached "
+                "`_agent` / `get_or_create_agent` definition has an unrecognised shape. Edit main.py manually — see "
+                "docs/payments.md for the expected pattern."
+            )
+    else:
+        byo = re.search(r"^(\s*)(agent = Agent\()", patched, re.M)
+        if byo:
+            indent = byo.group(1)
+            setup = "\n".join(
+                [
+                    *_plugin_setup(indent),
+                    f"{indent}# TODO: Add plugins=plugins to your Agent() constructor below",
+                    f"{indent}{byo.group(2)}",
+                ]
+            )
+            patched = patched[: byo.start()] + setup + patched[byo.end() :]
+
+    with open(main_path, "w", encoding="utf-8") as fh:
+        fh.write(patched)
+    return True
+
+
+@dataclass
+class AddPaymentManagerOptions:
+    name: str
+    authorizer_type: str = "AWS_IAM"
+    discovery_url: str | None = None
+    allowed_clients: list[str] | None = None
+    allowed_audience: list[str] | None = None
+    allowed_scopes: list[str] | None = None
+    description: str | None = None
+    auto_payment: bool | None = None
+    default_spend_limit: str | None = None
+    payment_tool_allowlist: list[str] | None = None
+    network_preferences: list[str] | None = None
+
+
+def _parse_list(value: str | None) -> list[str] | None:
+    return [s.strip() for s in value.split(",") if s.strip()] if value else None
+
+
+def _cleanup_credential_env(credential_name: str, provider: str | None, config_root: str | None) -> None:
+    try:
+        if provider == "StripePrivy":
+            v = compute_stripe_privy_credential_env_var_names(credential_name)
+            remove_env_vars([v.app_id, v.app_secret, v.authorization_private_key, v.authorization_id], config_root)
+        else:
+            p = compute_payment_credential_env_var_names(credential_name)
+            remove_env_vars([p.api_key_id, p.api_key_secret, p.wallet_secret], config_root)
+    except Exception:  # noqa: BLE001 - best-effort cleanup
+        pass
+
+
+class PaymentManagerPrimitive(BasePrimitive):
+    kind = "payment-manager"
+    label = "Payment Manager"
+
+    def _project(self) -> dict[str, Any]:
+        project = to_jsonable(self.read_project_spec())
+        if project.get("payments") is None:
+            project["payments"] = []
+        return project
+
+    def add(self, options: AddPaymentManagerOptions) -> Ok[dict[str, Any]] | Err[Exception]:
+        try:
+            project = self._project()
+            if any(p["name"] == options.name for p in project["payments"]):
+                raise ValueError(f'Payment manager "{options.name}" already exists.')
+            if options.authorizer_type == "CUSTOM_JWT" and not options.discovery_url:
+                return Err(Exception("--discovery-url is required when --authorizer-type is CUSTOM_JWT"))
+
+            manager: dict[str, Any] = {"name": options.name, "authorizerType": options.authorizer_type}
+            if options.authorizer_type == "CUSTOM_JWT":
+                jwt: dict[str, Any] = {"discoveryUrl": options.discovery_url}
+                if options.allowed_clients is not None:
+                    jwt["allowedClients"] = options.allowed_clients
+                if options.allowed_audience is not None:
+                    jwt["allowedAudience"] = options.allowed_audience
+                if options.allowed_scopes is not None:
+                    jwt["allowedScopes"] = options.allowed_scopes
+                manager["authorizerConfiguration"] = {"customJWTAuthorizer": jwt}
+            manager["connectors"] = []
+            if options.description:
+                manager["description"] = options.description
+            auto_payment = DEFAULT_AUTO_PAYMENT if options.auto_payment is None else options.auto_payment
+            spend_limit = (
+                options.default_spend_limit if options.default_spend_limit is not None else DEFAULT_SPEND_LIMIT
+            )
+            manager["autoPayment"] = auto_payment
+            manager["defaultSpendLimit"] = spend_limit
+            if options.payment_tool_allowlist:
+                manager["paymentToolAllowlist"] = options.payment_tool_allowlist
+            if options.network_preferences:
+                manager["networkPreferences"] = options.network_preferences
+            project["payments"].append(manager)
+            self.write_project_spec(project)
+
+            config_root = find_config_root()
+            skipped: list[str] = []
+            if config_root:
+                for runtime in project.get("runtimes") or []:
+                    if not is_payment_eligible_runtime(runtime):
+                        skipped.append(runtime["name"])
+                        continue
+                    if not wire_payment_capability(config_root, runtime.get("codeLocation", "")):
+                        skipped.append(runtime["name"])
+
+            warning = (
+                f'auto-payment is ENABLED for manager "{options.name}". Agents will automatically settle '
+                "402 Payment Required responses up to the per-session spend limit "
+                f"(${spend_limit}) with no human approval. "
+                "Re-run with --auto-payment false to require manual approval."
+                if auto_payment
+                else None
+            )
+            return Ok(
+                {
+                    "managerName": options.name,
+                    "skippedRuntimes": skipped,
+                    "autoPaymentWarning": warning,
+                }
+            )
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def remove(self, name: str) -> Ok[None] | Err[Exception]:
+        try:
+            project = self._project()
+            payments = project["payments"]
+            index = next((i for i, p in enumerate(payments) if p["name"] == name), -1)
+            if index == -1:
+                return Err(Exception(f'Payment manager "{name}" not found.'))
+            manager = payments[index]
+            connector_info = [
+                (c.get("credentialName"), c.get("provider"))
+                for c in manager.get("connectors") or []
+                if c.get("provisionMode") != "QUICK_CREATE"
+            ]
+            payments.pop(index)
+
+            def still_referenced(credential: str) -> bool:
+                return any(c.get("credentialName") == credential for m in payments for c in m.get("connectors") or [])
+
+            for credential, _ in connector_info:
+                if not still_referenced(credential):
+                    project["credentials"] = [c for c in project.get("credentials") or [] if c["name"] != credential]
+            self.write_project_spec(project)
+
+            config_root = self.config_io.get_config_root()
+            for credential, provider in connector_info:
+                if not still_referenced(credential):
+                    _cleanup_credential_env(credential, provider, config_root)
+            return Ok(None)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def preview_remove(self, name: str) -> RemovalPreview:
+        project = self._project()
+        manager = next((p for p in project["payments"] if p["name"] == name), None)
+        if manager is None:
+            raise Exception(f'Payment manager "{name}" not found.')
+        connectors = manager.get("connectors") or []
+        summary = [f"Removing payment manager: {name}"]
+        if connectors:
+            summary.append(f"Note: {len(connectors)} connector(s) within this manager will also be removed")
+            for c in connectors:
+                summary.append(
+                    f"  - Connector: {c['name']} (Quick Create)"
+                    if c.get("provisionMode") == "QUICK_CREATE"
+                    else f"  - Connector: {c['name']} (credential: {c.get('credentialName')})"
+                )
+        for c in connectors:
+            if c.get("provisionMode") == "QUICK_CREATE":
+                continue
+            credential = c.get("credentialName")
+            shared = any(
+                m["name"] != name
+                and any(
+                    o.get("provisionMode") != "QUICK_CREATE" and o.get("credentialName") == credential
+                    for o in m.get("connectors") or []
+                )
+                for m in project["payments"]
+            )
+            summary.append(
+                f'Credential "{credential}" is shared by other managers and will be kept'
+                if shared
+                else f'Associated credential "{credential}" will also be removed'
+            )
+        after = {**project, "payments": [p for p in project["payments"] if p["name"] != name]}
+        return RemovalPreview(summary, [], [SchemaChange("agentcore/agentcore.json", project, after)])
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [RemovableResource(p["name"]) for p in self._project()["payments"]]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_existing_managers(self) -> list[str]:
+        return [r.name for r in self.get_removable()]
+
+    # --- CLI ----------------------------------------------------------------------------
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:
+        from agentcore.cli.commands.add._commander import optional_value, optional_value_command
+
+        @add_app.command(
+            "payment-manager",
+            help="Add a payment manager to the project",
+            cls=optional_value_command("--auto-payment"),
+        )
+        def add_command(
+            name: str | None = typer.Option(None, "--name", help="Payment manager name [non-interactive]"),
+            authorizer_type: str | None = typer.Option(
+                None,
+                "--authorizer-type",
+                help="Authorizer type: AWS_IAM or CUSTOM_JWT (default: AWS_IAM) [non-interactive]",
+            ),
+            discovery_url: str | None = typer.Option(
+                None, "--discovery-url", help="OIDC discovery URL (required for CUSTOM_JWT) [non-interactive]"
+            ),
+            allowed_clients: str | None = typer.Option(
+                None,
+                "--allowed-clients",
+                help="Comma-separated allowed client IDs (for CUSTOM_JWT) [non-interactive]",
+            ),
+            allowed_audience: str | None = typer.Option(
+                None,
+                "--allowed-audience",
+                help="Comma-separated allowed audiences (for CUSTOM_JWT) [non-interactive]",
+            ),
+            allowed_scopes: str | None = typer.Option(
+                None, "--allowed-scopes", help="Comma-separated allowed scopes (for CUSTOM_JWT) [non-interactive]"
+            ),
+            auto_payment: str | None = typer.Option(
+                None,
+                "--auto-payment",
+                metavar="[VALUE]",
+                help="Enable auto payment: true or false (default: true) [non-interactive]",
+            ),
+            default_spend_limit: str | None = typer.Option(
+                None,
+                "--default-spend-limit",
+                help="Spend cap (USD) for sessions created by `invoke --auto-session` ONLY; not a deployed-agent "
+                "budget (default: 10.00) [non-interactive]",
+            ),
+            tool_allowlist: str | None = typer.Option(
+                None, "--tool-allowlist", help="Comma-separated tool names eligible for payment [non-interactive]"
+            ),
+            network_preferences: str | None = typer.Option(
+                None,
+                "--network-preferences",
+                help="Comma-separated network identifiers e.g. eip155:84532 [non-interactive]",
+            ),
+            description: str | None = typer.Option(
+                None, "--description", help="Payment manager description [non-interactive]"
+            ),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            auto = optional_value(auto_payment)
+            try:
+                if not find_config_root():
+                    typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                    raise typer.Exit(1)
+                if name is None and not authorizer_type and not as_json:
+                    interactive.require_tty()
+                    self.add_interactive()
+                    raise typer.Exit(0)
+                self._run_add_cli(
+                    name,
+                    authorizer_type,
+                    discovery_url,
+                    allowed_clients,
+                    allowed_audience,
+                    allowed_scopes,
+                    auto,
+                    default_spend_limit,
+                    tool_allowlist,
+                    network_preferences,
+                    description,
+                    as_json,
+                )
+            except typer.Exit:
+                raise
+            except Exception as exc:  # noqa: BLE001
+                if as_json:
+                    emit_json({"success": False, "error": get_error_message(exc)})
+                else:
+                    typer.echo(f"Error: {get_error_message(exc)}", err=True)
+                raise typer.Exit(1) from None
+
+        @remove_app.command("payment-manager", help="Remove a payment manager from the project")
+        def remove_command(
+            name: str | None = typer.Option(None, "--name", help="Name of resource to remove [non-interactive]"),
+            yes: bool = typer.Option(False, "-y", "--yes", help="Skip confirmation prompt [non-interactive]"),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            _run_named_remove(self, name, yes, as_json, name)
+
+    def _run_add_cli(
+        self,
+        name: str | None,
+        authorizer_type: str | None,
+        discovery_url: str | None,
+        allowed_clients: str | None,
+        allowed_audience: str | None,
+        allowed_scopes: str | None,
+        auto_payment: str | bool | None,
+        default_spend_limit: str | None,
+        tool_allowlist: str | None,
+        network_preferences: str | None,
+        description: str | None,
+        as_json: bool,
+    ) -> None:
+        from agentcore.cli.commands.add._common import first_issue
+        from agentcore.schema import PaymentManagerName
+
+        def fail(error: str) -> None:
+            if as_json:
+                emit_json({"success": False, "error": error})
+            else:
+                typer.echo(error, err=True)
+            raise typer.Exit(1)
+
+        if not name:
+            fail("--name is required")
+        issue = first_issue(PaymentManagerName, name)
+        if issue:
+            fail(f"Invalid name: {issue}")
+        resolved_auth = authorizer_type if authorizer_type is not None else "AWS_IAM"
+        if resolved_auth not in PAYMENT_AUTHORIZER_TYPES:
+            fail(f'Invalid authorizer type "{authorizer_type}". Valid: AWS_IAM, CUSTOM_JWT')
+        if default_spend_limit is not None:
+            from agentcore.primitives._harness_cli import _js_number
+
+            num = _js_number(default_spend_limit)
+            if num is None or num != num or num < 0:
+                fail('Invalid --default-spend-limit: must be a valid non-negative number (e.g., "10.00")')
+
+        auto: bool | None = None
+        if auto_payment is not None:
+            val = "true" if auto_payment is True else str(auto_payment).lower()
+            if val not in ("true", "false", "yes", "no", "1", "0", "on", "off"):
+                raise Exception(f'Invalid --auto-payment value "{auto_payment}". Use true or false.')
+            auto = val not in ("false", "no", "0", "off")
+
+        result = self.add(
+            AddPaymentManagerOptions(
+                name=name or "",
+                authorizer_type=resolved_auth,
+                discovery_url=discovery_url,
+                allowed_clients=_parse_list(allowed_clients),
+                allowed_audience=_parse_list(allowed_audience),
+                allowed_scopes=_parse_list(allowed_scopes),
+                auto_payment=auto,
+                default_spend_limit=default_spend_limit,
+                payment_tool_allowlist=_parse_list(tool_allowlist),
+                network_preferences=_parse_list(network_preferences),
+                description=description,
+            )
+        )
+        if as_json:
+            if result.success:
+                payload = {k: v for k, v in result.value.items() if k != "autoPaymentWarning"}
+                emit_json(serialize_result(Ok(payload)))
+            else:
+                emit_json(serialize_result(result))
+        elif result.success:
+            value = result.value
+            typer.echo(f"Added payment manager '{value['managerName']}'")
+            if value.get("autoPaymentWarning"):
+                sys.stderr.write(f"{ANSI.yellow}Warning: {value['autoPaymentWarning']}{ANSI.reset}\n")
+            if value.get("skippedRuntimes"):
+                sys.stderr.write(
+                    "\nWarning: payment capability auto-wiring skipped for non-Strands runtime(s): "
+                    f"{', '.join(value['skippedRuntimes'])}.\n"
+                )
+                sys.stderr.write(
+                    "Payments are only auto-wired into Strands agents today. You will need to wire payment plugins "
+                    "manually for these runtimes.\n"
+                )
+            else:
+                typer.echo("\nPayment capability code has been added to your agent(s).")
+            typer.echo(
+                f"Add a payment connector with `agentcore add payment-connector --manager {value['managerName']}`"
+            )
+        else:
+            typer.echo(get_error_message(result.error), err=True)
+        raise typer.Exit(0 if result.success else 1)
+
+    # --- interactive (port of tui/screens/payment AddPaymentFlow, manager path) ---------
+
+    def add_interactive(self) -> None:
+        from agentcore.primitives._payment_wizard import run_add_payment_manager_wizard
+
+        run_add_payment_manager_wizard(self)
+
+
+def _run_named_remove(
+    primitive: BasePrimitive, name: str | None, yes: bool, as_json: bool, key: str | None, label_name: str | None = None
+) -> None:
+    """Payment remove CLI: like the base remove, but plain text (not JSON) without --json."""
+    try:
+        if not find_config_root():
+            typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+            raise typer.Exit(1)
+        if name or yes or as_json:
+            if not name:
+                if as_json:
+                    emit_json({"success": False, "error": "--name is required"})
+                else:
+                    typer.echo("--name is required", err=True)
+                raise typer.Exit(1)
+            result = primitive.remove(key or name)
+            if as_json:
+                emit_json(
+                    {
+                        "success": result.success,
+                        "resourceType": primitive.kind,
+                        "resourceName": name,
+                        "message": f"Removed {primitive.label.lower()} '{name}'" if result.success else None,
+                        "note": SOURCE_CODE_NOTE if result.success else None,
+                        "error": None if result.success else get_error_message(result.error),
+                    }
+                )
+            elif result.success:
+                typer.echo(f"Removed {primitive.label.lower()} '{name}'")
+            else:
+                typer.echo(get_error_message(result.error), err=True)
+            raise typer.Exit(0 if result.success else 1)
+        interactive.require_tty()
+        primitive.remove_interactive()
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        if as_json:
+            emit_json({"success": False, "error": get_error_message(exc)})
+        else:
+            typer.echo(f"Error: {get_error_message(exc)}", err=True)
+        raise typer.Exit(1) from None
+
+
+__all__ = [
+    "AddPaymentManagerOptions",
+    "PaymentManagerPrimitive",
+    "compute_import_insertion_point",
+    "wire_payment_capability",
+]
+
+PRIMITIVE = PaymentManagerPrimitive()

agentcore/primitives/payment_validation.py

@@ -0,0 +1,68 @@
+"""Client-side format validation for payment connector secrets (port of payment-validation.ts).
+
+Each validator returns ``True`` when valid or a human-readable error string.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from typing import Literal
+
+_BASE64 = re.compile(r"^[A-Za-z0-9+/]+=*$")
+ED25519_MIN_BYTES = 32
+ED25519_MAX_BYTES = 64
+P256_MIN_BYTES = 100
+P256_MAX_BYTES = 200
+WALLET_AUTH_PREFIX = "wallet-auth:"
+
+
+def _decode_base64(value: str) -> bytes | None:
+    """Node's lenient ``Buffer.from(value, 'base64')`` after the character-set check."""
+    if not _BASE64.match(value):
+        return None
+    stripped = value.rstrip("=")
+    usable = len(stripped) - (len(stripped) % 4 == 1)  # a lone trailing sextet decodes to nothing
+    stripped = stripped[:usable]
+    return base64.b64decode(stripped + "=" * (-len(stripped) % 4))
+
+
+def validate_api_key_secret(value: str) -> Literal[True] | str:
+    decoded = _decode_base64(value.strip())
+    if decoded is None:
+        return "apiKeySecret must be a base64-encoded Ed25519 private key"
+    if not ED25519_MIN_BYTES <= len(decoded) <= ED25519_MAX_BYTES:
+        return "apiKeySecret must be a base64-encoded Ed25519 private key (unexpected length)"
+    return True
+
+
+def validate_wallet_secret(value: str) -> Literal[True] | str:
+    decoded = _decode_base64(value.strip())
+    if decoded is None:
+        return "walletSecret must be a base64-encoded EC P-256 private key"
+    if not P256_MIN_BYTES <= len(decoded) <= P256_MAX_BYTES:
+        return "walletSecret must be a base64-encoded EC P-256 private key (unexpected length)"
+    return True
+
+
+def strip_wallet_auth_prefix(value: str) -> str:
+    trimmed = value.strip()
+    return trimmed[len(WALLET_AUTH_PREFIX) :] if trimmed.startswith(WALLET_AUTH_PREFIX) else trimmed
+
+
+def validate_authorization_private_key(value: str) -> Literal[True] | str:
+    decoded = _decode_base64(strip_wallet_auth_prefix(value))
+    if decoded is None:
+        return "authorizationPrivateKey must be base64-encoded"
+    if not P256_MIN_BYTES <= len(decoded) <= P256_MAX_BYTES:
+        return "authorizationPrivateKey must be a base64-encoded EC P-256 private key (unexpected length)"
+    return True
+
+
+__all__ = [
+    "WALLET_AUTH_PREFIX",
+    "strip_wallet_auth_prefix",
+    "validate_api_key_secret",
+    "validate_authorization_private_key",
+    "validate_wallet_secret",
+]