agentsecure 0.1.1__tar.gz → 0.1.3__tar.gz

{agentsecure-0.1.1/agentsecure.egg-info → agentsecure-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentsecure
-Version: 0.1.1
+Version: 0.1.3
 Summary: Local-first security runtime for AI coding agents
 Home-page: https://github.com/ShellFrameAI/agentsecure-community
 Author: ShellFrame AI
@@ -18,11 +18,10 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Security
 Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: dataclasses; python_version < "3.7"
 Dynamic: license-file
 
 # AgentSecure Community
@@ -33,7 +32,9 @@ Dynamic: license-file
 [![CI](https://github.com/ShellFrameAI/agentsecure-community/actions/workflows/ci.yml/badge.svg)](https://github.com/ShellFrameAI/agentsecure-community/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-AgentSecure Community is a local-first CLI for AI coding-agent workflows. It demonstrates a simple idea: the agent can work in a real project, but it should see virtual or masked secrets instead of raw `.env` values.
+AI coding agents run where developer secrets already live: `.env` files, shell environments, MCP configs, local credentials, and project settings. GitGuardian's 2026 State of Secrets Sprawl report found [28.65 million new hardcoded secrets in public GitHub commits in 2025](https://blog.gitguardian.com/the-state-of-secrets-sprawl-2026/) and [24,008 unique secrets in MCP-related configuration files, including 2,117 valid credentials](https://blog.gitguardian.com/the-state-of-secrets-sprawl-2026/). Reported testing has also shown agent tools reading `.env` files despite ignore-file expectations; [The Register reproduced Claude Code reading `.env` with `.claudeignore` and `.gitignore` entries present](https://www.theregister.com/2026/01/28/claude_code_ai_secrets_files/), while [Anthropic's current docs recommend explicit file-access deny rules for sensitive files](https://code.claude.com/docs/en/configuration).
+
+AgentSecure Community is a local-first CLI for AI coding-agent workflows. It demonstrates a simple idea: ignore files are not a secret boundary, so the agent should see virtual or masked secrets instead of raw `.env` values.
 
 The community release is intentionally scoped to local CLI, local command guard, basic policy config, local secret virtualization, and tests. Hosted cloud sync, enterprise policy management, billing/licensing, and sensitive commercial detection logic are not part of this release.
 
@@ -106,6 +107,52 @@ By default, `--protect-all` virtualizes discovered secrets. The command output s
 
 Denied values are removed only when policy sets `mode: "deny"` for that environment variable. The built-in `agentsecure demo` includes that policy for `DATABASE_URL_PROD` so you can see both behaviors: virtualize and deny.
 
+## Provider Proxy Preview
+
+Virtual secrets keep real values out of the agent context. Provider proxy mode goes one step further for tools and SDKs that honor `OPENAI_BASE_URL`: the agent gets a virtual key and a local base URL, while AgentSecure injects the real key only when forwarding to the configured provider.
+
+Configure OpenAI from `agentsecure.json.provider_catalog.openai`:
+
+```bash
+agentsecure proxy setup openai
+```
+
+Then run the agent:
+
+```bash
+agentsecure run --protect-all -- codex
+```
+
+The agent-visible environment includes:
+
+```text
+OPENAI_API_KEY=virt_openai_...
+OPENAI_BASE_URL=http://127.0.0.1:8765/providers/openai/v1
+```
+
+AgentSecure forwards provider calls to the configured upstream:
+
+```json
+{
+  "provider_proxy": {
+    "providers": {
+      "openai": {
+        "upstream": "https://api.openai.com",
+        "local_path": "/providers/openai"
+      }
+    }
+  }
+}
+```
+
+Run the proxy proof:
+
+```bash
+agentsecure receipts --proxy
+```
+
+Provider proxy mode is local-only. It is not a system-wide proxy, not TLS MITM, and not browser-wide interception. Tools must use the provider base URL environment variable.
+
 ## What It Demonstrates
 
 - Discover likely secrets in `.env` files and environment variables.
@@ -155,6 +202,9 @@ agentsecure suggest
 agentsecure env
 agentsecure keys list
 agentsecure network list
+agentsecure proxy setup openai
+agentsecure proxy doctor
+agentsecure receipts --proxy
 ```
 
 Run an agent or command through local command guard:

{agentsecure-0.1.1 → agentsecure-0.1.3}/README.md

@@ -6,7 +6,9 @@
 [![CI](https://github.com/ShellFrameAI/agentsecure-community/actions/workflows/ci.yml/badge.svg)](https://github.com/ShellFrameAI/agentsecure-community/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-AgentSecure Community is a local-first CLI for AI coding-agent workflows. It demonstrates a simple idea: the agent can work in a real project, but it should see virtual or masked secrets instead of raw `.env` values.
+AI coding agents run where developer secrets already live: `.env` files, shell environments, MCP configs, local credentials, and project settings. GitGuardian's 2026 State of Secrets Sprawl report found [28.65 million new hardcoded secrets in public GitHub commits in 2025](https://blog.gitguardian.com/the-state-of-secrets-sprawl-2026/) and [24,008 unique secrets in MCP-related configuration files, including 2,117 valid credentials](https://blog.gitguardian.com/the-state-of-secrets-sprawl-2026/). Reported testing has also shown agent tools reading `.env` files despite ignore-file expectations; [The Register reproduced Claude Code reading `.env` with `.claudeignore` and `.gitignore` entries present](https://www.theregister.com/2026/01/28/claude_code_ai_secrets_files/), while [Anthropic's current docs recommend explicit file-access deny rules for sensitive files](https://code.claude.com/docs/en/configuration).
+
+AgentSecure Community is a local-first CLI for AI coding-agent workflows. It demonstrates a simple idea: ignore files are not a secret boundary, so the agent should see virtual or masked secrets instead of raw `.env` values.
 
 The community release is intentionally scoped to local CLI, local command guard, basic policy config, local secret virtualization, and tests. Hosted cloud sync, enterprise policy management, billing/licensing, and sensitive commercial detection logic are not part of this release.
 
@@ -79,6 +81,52 @@ By default, `--protect-all` virtualizes discovered secrets. The command output s
 
 Denied values are removed only when policy sets `mode: "deny"` for that environment variable. The built-in `agentsecure demo` includes that policy for `DATABASE_URL_PROD` so you can see both behaviors: virtualize and deny.
 
+## Provider Proxy Preview
+
+Virtual secrets keep real values out of the agent context. Provider proxy mode goes one step further for tools and SDKs that honor `OPENAI_BASE_URL`: the agent gets a virtual key and a local base URL, while AgentSecure injects the real key only when forwarding to the configured provider.
+
+Configure OpenAI from `agentsecure.json.provider_catalog.openai`:
+
+```bash
+agentsecure proxy setup openai
+```
+
+Then run the agent:
+
+```bash
+agentsecure run --protect-all -- codex
+```
+
+The agent-visible environment includes:
+
+```text
+OPENAI_API_KEY=virt_openai_...
+OPENAI_BASE_URL=http://127.0.0.1:8765/providers/openai/v1
+```
+
+AgentSecure forwards provider calls to the configured upstream:
+
+```json
+{
+  "provider_proxy": {
+    "providers": {
+      "openai": {
+        "upstream": "https://api.openai.com",
+        "local_path": "/providers/openai"
+      }
+    }
+  }
+}
+```
+
+Run the proxy proof:
+
+```bash
+agentsecure receipts --proxy
+```
+
+Provider proxy mode is local-only. It is not a system-wide proxy, not TLS MITM, and not browser-wide interception. Tools must use the provider base URL environment variable.
+
 ## What It Demonstrates
 
 - Discover likely secrets in `.env` files and environment variables.
@@ -128,6 +176,9 @@ agentsecure suggest
 agentsecure env
 agentsecure keys list
 agentsecure network list
+agentsecure proxy setup openai
+agentsecure proxy doctor
+agentsecure receipts --proxy
 ```
 
 Run an agent or command through local command guard:

{agentsecure-0.1.1 → agentsecure-0.1.3}/agentsecure/__init__.py

@@ -1,4 +1,3 @@
 """AgentSecure local-first security runtime."""
 
-__version__ = "0.1.0"
-
+__version__ = "0.1.3"

{agentsecure-0.1.1 → agentsecure-0.1.3}/agentsecure/cli/main.py

@@ -1,4 +1,5 @@
 import argparse
+import hashlib
 import getpass
 import json
 import os
@@ -31,6 +32,8 @@ from agentsecure.cli.project import (
     show_status,
     uninstall_agentsecure,
 )
+from agentsecure.cli.proxy import add_proxy_subparser, handle_proxy
+from agentsecure.cli.receipts import handle_receipts
 from agentsecure.cli.secrets import (
     discover_secrets,
     handle_keys,
@@ -56,6 +59,7 @@ from agentsecure.core.capabilities import broker_url_for_env
 from agentsecure.core.container import Container
 from agentsecure.core.key_service import KeyManagementError, KeyManagementService
 from agentsecure.core.models import AgentSecureConfig, DiscoveredSecret, ProcessRequest, SecretReplacement
+from agentsecure.core.provider_proxy import configured_provider_base_url, provider_base_local_path
 from agentsecure.core.product import ProductService
 from agentsecure.core.time import DurationError
 from agentsecure.daemon.commands import CommandExecutor, CommandPoller
@@ -115,6 +119,10 @@ def main(argv: Optional[List[str]] = None) -> int:
         return handle_files(args)
     if args.command == "network":
         return handle_network(args)
+    if args.command == "proxy":
+        return handle_proxy(args)
+    if args.command == "receipts":
+        return handle_receipts(args)
     if args.command == "policy":
         return handle_policy(args)
     if args.command == "setup":
@@ -224,6 +232,9 @@ def build_parser() -> argparse.ArgumentParser:
     network_remove_parser = network_subparsers.add_parser("remove", help="Remove domains from credential allowlist")
     network_remove_parser.add_argument("domains", nargs="+")
 
+    add_proxy_subparser(subparsers)
+    receipts_parser = subparsers.add_parser("receipts", help="Run replayable AgentSecure proof receipts")
+    receipts_parser.add_argument("--proxy", action="store_true", help="Run provider proxy receipts")
     add_policy_subparser(subparsers)
 
     setup_parser = subparsers.add_parser("setup", help="Install local protected agent command wrappers")
@@ -265,9 +276,10 @@ def run_agent(args: argparse.Namespace) -> int:
         if isinstance(replacements, int):
             return replacements
     container = Container.from_config_path(args.config)
+    replacements.extend(_configured_secret_replacements(container, replacements))
     run_cwd = os.getcwd()
     workspace_session = None
-    materializer = WorkspaceMaterializer()
+    materializer = WorkspaceMaterializer(_workspace_base_for_runtime(run_cwd, args.runtime))
     should_create_workspace = bool(replacements or container.config.files.protect_write)
     if args.runtime == "command-guard":
         print("AgentSecure runtime: command-guard", flush=True)
@@ -345,6 +357,7 @@ def run_agent(args: argparse.Namespace) -> int:
     env = os.environ.copy()
     for env_name in container.config.env_policy.rules:
         env.pop(env_name, None)
+    _strip_backing_secret_environment(env, container)
     env.update(container.virtual_env_provider.build_environment())
     if args.runtime == "command-guard":
         CommandGuardWrapperInstaller(args.config).install(env)
@@ -353,6 +366,7 @@ def run_agent(args: argparse.Namespace) -> int:
         env["AGENTSECURE_SESSION_ID"] = session_id
     proxy_url = _proxy_url(gateway_host, gateway_port, session_id)
     _apply_proxy_environment(env, proxy_url)
+    _apply_provider_proxy_environment(env, container, gateway_host, gateway_port)
     command_metadata = safe_command_metadata(argv)
     container.audit_logger.record(
         "agent_started",
@@ -389,7 +403,8 @@ def run_agent(args: argparse.Namespace) -> int:
             os.environ["AGENTSECURE_CLOUD_DEBUG"] = "true"
     session_finished = False
     try:
-        process = _start_agent_process(argv, env, run_cwd)
+        output_sanitizer = SecretOutputSanitizer.from_config_path(args.config)
+        process = _start_agent_process(argv, env, run_cwd, sanitize_output=True)
         process_group_id = _process_group_id(process)
         if cloud_session and cloud and cloud.status().get("enrolled"):
             command_executor = _run_command_executor(
@@ -414,7 +429,7 @@ def run_agent(args: argparse.Namespace) -> int:
         elif command_executor:
             command_poller = CommandPoller(cloud, command_executor)
             command_poller.start()
-        exit_code = process.wait()
+        exit_code = _wait_for_agent_process(process, output_sanitizer)
         if exit_code is None or exit_code >= 0:
             _wait_for_process_group_exit(process_group_id)
         final_status = "killed" if exit_code is not None and exit_code < 0 else "finished"
@@ -452,10 +467,51 @@ def run_agent(args: argparse.Namespace) -> int:
             )
 
 
-def _start_agent_process(argv: List[str], env, cwd: str):
+def _workspace_base_for_runtime(source_root: str, runtime: str) -> str:
+    if runtime != "workspace":
+        return ".agentsecure/workspaces"
+    digest = hashlib.sha256(os.path.abspath(source_root).encode("utf-8")).hexdigest()[:16]
+    return os.path.join(tempfile.gettempdir(), "agentsecure-workspaces", digest)
+
+
+def _start_agent_process(argv: List[str], env, cwd: str, sanitize_output: bool = False):
+    stdout = subprocess.PIPE if sanitize_output else None
+    stderr = subprocess.PIPE if sanitize_output else None
     if os.name == "posix":
-        return subprocess.Popen(argv, env=env, cwd=cwd, preexec_fn=os.setsid)
-    return subprocess.Popen(argv, env=env, cwd=cwd)
+        return subprocess.Popen(argv, env=env, cwd=cwd, stdout=stdout, stderr=stderr, preexec_fn=os.setsid)
+    return subprocess.Popen(argv, env=env, cwd=cwd, stdout=stdout, stderr=stderr)
+
+
+def _wait_for_agent_process(process, sanitizer: SecretOutputSanitizer) -> int:
+    if process.stdout is None and process.stderr is None:
+        return process.wait()
+
+    stdout_thread = _start_output_forwarder(process.stdout, sys.stdout.buffer, sanitizer)
+    stderr_thread = _start_output_forwarder(process.stderr, sys.stderr.buffer, sanitizer)
+    exit_code = process.wait()
+    if stdout_thread:
+        stdout_thread.join()
+    if stderr_thread:
+        stderr_thread.join()
+    return int(exit_code)
+
+
+def _start_output_forwarder(source, target, sanitizer: SecretOutputSanitizer):
+    if source is None:
+        return None
+
+    def forward() -> None:
+        while True:
+            chunk = source.readline()
+            if not chunk:
+                break
+            target.write(sanitizer.sanitize_bytes(chunk))
+            target.flush()
+
+    thread = threading.Thread(target=forward)
+    thread.daemon = True
+    thread.start()
+    return thread
 
 
 def _process_group_id(process) -> int:
@@ -582,6 +638,7 @@ def _start_local_gateway_thread(container: Container, host: str, port: int):
         container.token_resolver,
         container.audit_logger,
         container.bindings,
+        container.config.provider_proxy,
     )
 
     def run_gateway_thread() -> None:
@@ -766,6 +823,59 @@ def _apply_proxy_environment(env, proxy_url: str) -> None:
     env["no_proxy"] = no_proxy
 
 
+def _apply_provider_proxy_environment(env, container: Container, gateway_host: str, gateway_port: int) -> None:
+    if not container.config.provider_proxy.enabled:
+        return
+    raw = dict(container.config.raw)
+    gateway = dict(raw.get("gateway", {}))
+    gateway["host"] = gateway_host
+    gateway["port"] = gateway_port
+    raw["gateway"] = gateway
+    for provider in container.config.provider_proxy.providers.values():
+        provider_data = {
+            "local_path": provider_base_local_path(provider.local_path, provider.allow_paths),
+        }
+        env[provider.base_url_env] = configured_provider_base_url(raw, provider_data)
+
+
+def _strip_backing_secret_environment(env, container: Container) -> None:
+    for binding in container.config.secrets:
+        if binding.real_secret_env:
+            env.pop(binding.real_secret_env, None)
+
+
+def _configured_secret_replacements(container: Container, existing: List[SecretReplacement]) -> List[SecretReplacement]:
+    existing_names = set(replacement.name for replacement in existing)
+    replacements = []
+    for binding in container.config.secrets:
+        if binding.env_name in existing_names:
+            continue
+        real_value = container.token_resolver.resolve(binding.virtual_token) or ""
+        if not real_value:
+            continue
+        rule = container.config.env_policy.rule_for(binding.env_name)
+        if rule.mode == "deny":
+            replacements.append(
+                SecretReplacement(
+                    source="configured",
+                    name=binding.env_name,
+                    real_value=real_value,
+                    virtual_value="",
+                    action="remove",
+                )
+            )
+        elif rule.mode != "broker":
+            replacements.append(
+                SecretReplacement(
+                    source="configured",
+                    name=binding.env_name,
+                    real_value=real_value,
+                    virtual_value=binding.virtual_token,
+                )
+            )
+    return replacements
+
+
 def _merge_no_proxy(existing: str) -> str:
     defaults = [
         "localhost",
@@ -782,6 +892,8 @@ def _merge_no_proxy(existing: str) -> str:
         if not value:
             continue
         key = value.lower()
+        if key == "*":
+            continue
         if key not in seen:
             values.append(value)
             seen.add(key)

agentsecure-0.1.3/agentsecure/cli/proxy.py

@@ -0,0 +1,283 @@
+import argparse
+import os
+import re
+import socket
+import sys
+from typing import Any, Dict
+from urllib.parse import urlsplit
+
+from agentsecure.cli.common import load_config_data, normalize_domain
+from agentsecure.core.config import ConfigError, JsonConfigLoader, JsonConfigWriter
+from agentsecure.core.models import Destination
+from agentsecure.core.provider_proxy import configured_provider_base_url, provider_base_local_path, upstream_host
+from agentsecure.core.product import default_config
+from agentsecure.implementations.policy import StrictDestinationValidator
+
+
+def add_proxy_subparser(subparsers) -> None:
+    proxy_parser = subparsers.add_parser("proxy", help="Configure local provider proxy")
+    proxy_subparsers = proxy_parser.add_subparsers(dest="proxy_command")
+
+    setup_parser = proxy_subparsers.add_parser("setup", help="Configure a provider proxy")
+    setup_subparsers = setup_parser.add_subparsers(dest="provider")
+    openai_parser = setup_subparsers.add_parser("openai", help="Activate provider_catalog.openai")
+    openai_parser.add_argument(
+        "--trust-local-catalog",
+        action="store_true",
+        help="Allow provider_catalog.openai values that differ from the packaged default",
+    )
+
+    custom_parser = setup_subparsers.add_parser("custom", help="Configure a custom provider proxy")
+    custom_parser.add_argument("--name", required=True, help="Provider name used in the local path")
+    custom_parser.add_argument("--upstream", required=True, help="Provider upstream, for example https://api.example.com")
+    custom_parser.add_argument("--env", required=True, help="Environment variable that contains the provider key")
+    custom_parser.add_argument("--base-url-env", required=True, help="Environment variable used by the SDK for base URL")
+    custom_parser.add_argument("--allow-path", action="append", default=[], help="Allowed upstream path prefix")
+
+    proxy_subparsers.add_parser("doctor", help="Check provider proxy setup")
+
+
+def handle_proxy(args: argparse.Namespace) -> int:
+    if args.proxy_command == "setup":
+        return setup_proxy(args)
+    if args.proxy_command == "doctor":
+        return doctor_proxy(args)
+    sys.stderr.write("agentsecure: missing proxy subcommand\n")
+    return 2
+
+
+def setup_proxy(args: argparse.Namespace) -> int:
+    if args.provider == "openai":
+        return _activate_catalog_provider(args.config, "openai", args.trust_local_catalog)
+    if args.provider == "custom":
+        return _activate_custom_provider(args)
+    sys.stderr.write("agentsecure: missing proxy provider\n")
+    return 2
+
+
+def doctor_proxy(args: argparse.Namespace) -> int:
+    try:
+        config = JsonConfigLoader().load(args.config)
+    except (ConfigError, OSError, ValueError) as exc:
+        sys.stderr.write("agentsecure: invalid config: %s\n" % exc)
+        return 1
+
+    if not config.provider_proxy.enabled:
+        print("Provider proxy: disabled")
+        return 1
+
+    ok = True
+    if _can_bind(config.gateway.host, config.gateway.port):
+        print("Gateway bind: ok (%s:%s)" % (config.gateway.host, config.gateway.port))
+    else:
+        print("Gateway bind: blocked or busy (%s:%s)" % (config.gateway.host, config.gateway.port))
+        ok = False
+
+    bindings = {(binding.env_name, binding.provider): binding for binding in config.secrets}
+    network_validator = StrictDestinationValidator(config.network)
+    for provider in config.provider_proxy.providers.values():
+        host = normalize_domain(urlsplit(provider.upstream).hostname or "")
+        print("Provider %s:" % provider.name)
+        local_path = provider_base_local_path(provider.local_path, provider.allow_paths)
+        print("  local: http://%s:%s%s" % (config.gateway.host, config.gateway.port, local_path))
+        print("  upstream: %s" % provider.upstream)
+        print("  env: %s" % provider.env_name)
+        print("  base url env: %s" % provider.base_url_env)
+        if (provider.env_name, provider.name) in bindings:
+            print("  binding: ok")
+        else:
+            print("  binding: missing (run with --protect-all after adding the key for provider %s)" % provider.name)
+            ok = False
+        parsed = urlsplit(provider.upstream)
+        port = parsed.port or 443
+        decision = network_validator.validate(Destination("https", host, port, credentials_present=True))
+        if decision.allowed:
+            print("  network allowlist: ok")
+        else:
+            print("  network policy: blocked (%s)" % decision.reason)
+            ok = False
+    return 0 if ok else 1
+
+
+def _activate_catalog_provider(config_path: str, provider_name: str, trust_local_catalog: bool = False) -> int:
+    config = load_config_data(config_path)
+    catalog = config.get("provider_catalog", {})
+    provider = catalog.get(provider_name)
+    if not isinstance(provider, dict):
+        sys.stderr.write(
+            "agentsecure: provider_catalog.%s is missing from %s\n" % (provider_name, config_path)
+        )
+        return 1
+    default_provider = default_config().get("provider_catalog", {}).get(provider_name)
+    if default_provider and not trust_local_catalog and _canonical_provider(provider) != _canonical_provider(default_provider):
+        sys.stderr.write(
+            "agentsecure: provider_catalog.%s differs from the packaged default; "
+            "use proxy setup custom or pass --trust-local-catalog\n" % provider_name
+        )
+        return 2
+    return _activate_provider(config_path, config, provider_name, provider)
+
+
+def _activate_custom_provider(args: argparse.Namespace) -> int:
+    config = load_config_data(args.config)
+    name = _slug(args.name)
+    upstream = str(args.upstream).rstrip("/")
+    parsed = urlsplit(upstream)
+    try:
+        parsed_port = parsed.port
+    except ValueError:
+        sys.stderr.write("agentsecure: custom upstream port is invalid\n")
+        return 2
+    if parsed.scheme != "https" or not parsed.hostname:
+        sys.stderr.write("agentsecure: custom upstream must be https and include a host\n")
+        return 2
+    _ = parsed_port
+    provider = {
+        "env_name": args.env,
+        "base_url_env": args.base_url_env,
+        "upstream": upstream,
+        "local_path": "/providers/%s" % name,
+        "inject_as": "authorization_bearer",
+        "allow_paths": args.allow_path or ["/"],
+        "allow_domains": [parsed.hostname],
+    }
+    config.setdefault("provider_catalog", {})[name] = dict(provider)
+    return _activate_provider(args.config, config, name, provider)
+
+
+def _activate_provider(
+    config_path: str,
+    config: Dict[str, Any],
+    provider_name: str,
+    provider: Dict[str, Any],
+) -> int:
+    error = _validate_provider(provider_name, provider)
+    if error:
+        sys.stderr.write("agentsecure: %s\n" % error)
+        return 2
+
+    provider_proxy = config.setdefault("provider_proxy", {})
+    provider_proxy["enabled"] = True
+    providers = provider_proxy.setdefault("providers", {})
+    providers[provider_name] = {
+        "env_name": str(provider["env_name"]),
+        "base_url_env": str(provider["base_url_env"]),
+        "upstream": str(provider["upstream"]).rstrip("/"),
+        "local_path": _normalize_path(str(provider["local_path"])),
+        "inject_as": "authorization_bearer",
+        "allow_paths": [_normalize_allow_path(path) for path in provider.get("allow_paths", ["/"])],
+    }
+
+    env_name = str(provider["env_name"])
+    env_policy = config.setdefault("env_policy", {})
+    rule = dict(env_policy.get(env_name, {}))
+    rule.setdefault("mode", "virtualize")
+    rule.setdefault(
+        "reason",
+        "Agent sees a virtual token; AgentSecure injects the real key only at the configured provider proxy.",
+    )
+    rule["approved_hosts"] = list(provider.get("allow_domains") or [upstream_host(provider)])
+    env_policy[env_name] = rule
+
+    network = config.setdefault("network", {})
+    allowed = list(network.get("allow_domains", []))
+    for domain in provider.get("allow_domains") or [upstream_host(provider)]:
+        normalized = normalize_domain(str(domain))
+        if normalized and normalized not in allowed:
+            allowed.append(normalized)
+    network["allow_domains"] = allowed
+
+    JsonConfigWriter().save(config_path, config)
+    active_provider = dict(providers[provider_name])
+    active_provider["local_path"] = provider_base_local_path(
+        str(active_provider["local_path"]),
+        list(active_provider.get("allow_paths") or []),
+    )
+    print("Configured provider proxy: %s" % provider_name)
+    print("  %s=%s" % (provider["base_url_env"], configured_provider_base_url(config, active_provider)))
+    print("  %s stays virtualized" % provider["env_name"])
+    print("  upstream: %s" % provider["upstream"])
+    return 0
+
+
+def _validate_provider(provider_name: str, provider: Dict[str, Any]) -> str:
+    for key in ("env_name", "base_url_env", "upstream", "local_path"):
+        if not str(provider.get(key, "")).strip():
+            return "provider_catalog.%s.%s is required" % (provider_name, key)
+    upstream = str(provider.get("upstream", "")).strip()
+    parsed = urlsplit(upstream)
+    try:
+        parsed_port = parsed.port
+    except ValueError:
+        return "provider_catalog.%s.upstream port is invalid" % provider_name
+    if parsed.scheme != "https" or not parsed.hostname:
+        return "provider_catalog.%s.upstream must be an https URL with a host" % provider_name
+    _ = parsed_port
+    if _normalize_path(str(provider.get("local_path", ""))) == "/":
+        return "provider_catalog.%s.local_path must not be /" % provider_name
+    if not isinstance(provider.get("allow_paths", []), list):
+        return "provider_catalog.%s.allow_paths must be a list" % provider_name
+    for key in ("env_name", "base_url_env"):
+        error = _validate_env_name(str(provider[key]), "provider_catalog.%s.%s" % (provider_name, key))
+        if error:
+            return error
+    if str(provider.get("inject_as", "authorization_bearer")) != "authorization_bearer":
+        return "provider_catalog.%s.inject_as must be authorization_bearer" % provider_name
+    return ""
+
+
+def _validate_env_name(value: str, path: str) -> str:
+    if not re.match(r"^[A-Z_][A-Z0-9_]*$", value):
+        return "%s must be an uppercase environment variable name" % path
+    blocked = {
+        "PATH",
+        "HOME",
+        "SHELL",
+        "PYTHONPATH",
+        "HTTP_PROXY",
+        "HTTPS_PROXY",
+        "NO_PROXY",
+    }
+    if value in blocked:
+        return "%s must not override critical process environment" % path
+    return ""
+
+
+def _canonical_provider(provider: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "env_name": str(provider.get("env_name", "")),
+        "base_url_env": str(provider.get("base_url_env", "")),
+        "upstream": str(provider.get("upstream", "")).rstrip("/"),
+        "local_path": _normalize_path(str(provider.get("local_path", ""))),
+        "inject_as": str(provider.get("inject_as", "authorization_bearer")),
+        "allow_paths": [_normalize_allow_path(path) for path in provider.get("allow_paths", [])],
+        "allow_domains": [normalize_domain(str(domain)) for domain in provider.get("allow_domains", [])],
+    }
+
+
+def _normalize_path(path: str) -> str:
+    return "/" + path.strip().strip("/")
+
+
+def _normalize_allow_path(path: str) -> str:
+    normalized = "/" + str(path).strip().strip("/")
+    return "/" if normalized == "/" else normalized.rstrip("/") + "/"
+
+
+def _slug(value: str) -> str:
+    slug = "".join(ch.lower() if ch.isalnum() else "-" for ch in value).strip("-")
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    return slug or "custom"
+
+
+def _can_bind(host: str, port: int) -> bool:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind((host, port))
+        return True
+    except OSError:
+        return False
+    finally:
+        sock.close()