Harden integration auth secret handling and enforce fixed policy

Co-Authored-By: GPT-5 Codex <noreply@openai.com>

Author: dcramer

specs/capabilities.md

@@ -56,6 +56,7 @@ per-user credential isolation rules.
 - Capability auth flow handles are short-lived, unguessable, and bound to the requesting user scope.
 - Capability execution emits structured audit events without logging raw bearer tokens.
 - Capability responses must never include raw credential artifacts (access tokens, refresh tokens, cookie jars, client secrets).
+- Provider auth `credential_material` must contain only opaque references/metadata (no raw tokens/secrets).
 - Provider-side credential artifacts must be persisted via a dedicated vault abstraction (not graph collections or sandbox-readable mounts).
 
 ### SHOULD
@@ -257,6 +258,7 @@ Rules:
 - Provider responses are user-facing payloads and must be credential-safe.
 - Host rejects provider outputs containing credential-like keys (`access_token`,
   `refresh_token`, `id_token`, `client_secret`, cookie/auth headers).
+- Host rejects provider auth `credential_material` containing credential-like keys.
 
 ### RPC Methods
 

specs/capability-auth.md

@@ -8,7 +8,7 @@ Parent spec: `specs/capabilities.md`
 
 ## Status
 
-Spec only — not yet implemented.
+Implemented.
 
 ## Intent
 

specs/config.md

@@ -99,6 +99,7 @@ timeout_seconds = 30
 [skills.code-review]
 model = "sonnet"
 
+
 [sandbox]
 timeout = 60
 memory_limit = "512m"

specs/integration-auth-security.md

@@ -0,0 +1,36 @@
+# Integration Auth Security
+
+> Unified secret-handling policy for tools, skills, and integration providers.
+
+## Intent
+
+Ash should not hand raw API keys, OAuth access tokens, refresh tokens, or client
+secrets directly to tool/skill execution environments.
+
+Authentication and authorization for sensitive external systems must be mediated by
+host-managed boundaries (capabilities, provider bridges, authenticated proxies).
+
+## Requirements
+
+### MUST
+
+- Tools/skills MUST NOT receive secret-like env vars by default.
+- Secret-like env var names are detected by fixed built-in name patterns.
+- Delivery of secret-like env vars to skills/tools is blocked by policy.
+- Capability/provider auth responses MUST NOT include raw credential material.
+- `credential_material` from providers is limited to opaque references (for example
+  `credential_key`) and metadata.
+- Provider-side credential artifacts MUST be persisted in host vault storage.
+- Capability invocation responses MUST remain credential-safe.
+- Identity/routing for auth and invoke MUST be token-derived (`ASH_CONTEXT_TOKEN`),
+  not caller-provided ids.
+
+### SHOULD
+
+- External provider bridges should run with minimal inherited process environment.
+- Authenticated sidecar/proxy patterns should inject authorization headers server-side
+  from vault-backed references when feasible.
+
+## Policy
+
+The secret-delivery block is enforced as a runtime policy and is not user-configurable.

specs/interactive-agents.md

@@ -186,7 +186,12 @@ The provider runs a while loop that processes TurnResults until it needs user in
 
 ```python
 while True:
-    result = execute_turn(stack.top, user_message=..., tool_result=...)
+    result = execute_turn(
+        stack.top,
+        user_message=...,
+        tool_result=...,
+        tool_overrides={"send_message": progress_tool},
+    )
 
     match result.action:
         case SEND_TEXT:
@@ -217,14 +222,23 @@ while True:
             # Same as MAX_ITERATIONS but with error text
 ```
 
+Provider orchestration SHOULD pass a per-request `send_message` override that
+funnels subagent progress into the current response thread (thinking/progress
+buffer) rather than emitting separate direct messages.
+
 Every iteration either `return`s (waiting for user input) or `continue`s (cascading). No recursion.
 
 ### execute_turn (AgentExecutor)
 
 Runs one logical turn for a stack frame:
 
 ```python
-async def execute_turn(frame, user_message=None, tool_result=None) -> TurnResult:
+async def execute_turn(
+    frame,
+    user_message=None,
+    tool_result=None,
+    tool_overrides=None,
+) -> TurnResult:
     session = frame.session
 
     if user_message: session.add_user_message(user_message)
@@ -245,7 +259,11 @@ async def execute_turn(frame, user_message=None, tool_result=None) -> TurnResult
             if tool_use.name == "complete":
                 return TurnResult(COMPLETE, text=tool_use.input["result"])
             try:
-                result = await tools.execute(tool_use.name, tool_use.input, ctx)
+                tool_impl = tool_overrides.get(tool_use.name) if tool_overrides else None
+                if tool_impl:
+                    result = await tool_impl.execute(tool_use.input, ctx)
+                else:
+                    result = await tools.execute(tool_use.name, tool_use.input, ctx)
                 session.add_tool_result(tool_use.id, result.content, result.is_error)
             except ChildActivated as ca:
                 return TurnResult(CHILD_ACTIVATED, child_frame=ca.child_frame)

specs/skills.md

@@ -9,7 +9,7 @@ Files: src/ash/skills/base.py, src/ash/skills/registry.py, src/ash/tools/builtin
 Skills are markdown files that define specialized subagents. Unlike the current model where the main agent reads skill files, skills are now **invoked explicitly** via the `use_skill` tool and run in **isolated LLM loops** with scoped environments.
 
 This enables:
-- **API key isolation**: Skills declare needed env vars, config provides values
+- **Scoped env injection**: Skills declare non-secret env vars, config provides values
 - **Tool restrictions**: Skills can limit which tools the subagent uses
 - **Context compression**: Main agent passes relevant context, not full history
 - **Model flexibility**: Skills can specify different models (e.g., haiku for simple tasks)
@@ -47,6 +47,7 @@ skills consume those capabilities through stable public surfaces.
 - Invoke skills via `use_skill` tool (not by reading files)
 - Run skill as subagent with isolated session
 - Inject env vars from config into skill execution
+- Block secret-like env var delivery to skills by policy
 - Support capability-mediated calls for sensitive external systems (contract in `specs/capabilities.md`)
 - Keep skill execution on public host interfaces; no direct integration hook registration path for skills
 - Treat bundled skills as regular skill surfaces (no privileged wiring semantics)
@@ -91,7 +92,7 @@ access:
   chat_types:                   # Optional invocation chat-type allowlist
     - private
 env:                           # Env vars to inject from config
-  - PERPLEXITY_API_KEY
+  - SERVICE_ENDPOINT
 packages:                      # System packages to install (apt)
   - jq
   - curl
@@ -108,7 +109,7 @@ You are a research assistant with access to Perplexity AI.
 Given a research query, search for accurate, up-to-date information
 and return a structured summary with sources.
 
-Use the PERPLEXITY_API_KEY environment variable for API calls.
+Use the SERVICE_ENDPOINT environment variable for API calls.
 ```
 
 ### Capability-Backed Skills (Contract)
@@ -158,7 +159,7 @@ declare container/command wiring.
 # ~/.ash/config.toml
 
 [skills.research]
-PERPLEXITY_API_KEY = "pplx-..."  # Direct match - injected as $PERPLEXITY_API_KEY
+SERVICE_ENDPOINT = "https://api.example.com"  # Direct match - injected as $SERVICE_ENDPOINT
 model = "haiku"                   # Override skill's default model
 enabled = true                    # Can disable without removing file
 allow_chat_ids = ["12345"]        # Optional per-skill chat allowlist override
@@ -181,6 +182,7 @@ enabled = false                   # Disabled
 
 Config keys match env var names exactly (UPPER_CASE). No case conversion.
 `allow_chat_ids` can be set globally in `[skills.defaults]` and overridden per skill.
+Secret-like env var names are blocked by policy and must use host-managed capability/proxy auth.
 
 `[skills.gog].enabled = true` applies default `gog` provider wiring.
 `[skills.gog.capability_provider]` can override provider command/namespace/timeout

src/ash/agents/base.py

@@ -11,6 +11,8 @@
 Use `send_message` to keep the user informed during long-running tasks:
 - Share what you're working on at each major step
 - Keep updates brief (one line)
+- Use it for progress only, not final instructions or final results
+- If user action is needed (auth codes, confirmations), provide that once in the final response path
 
 Example: "Searching documentation...", "Found 3 results, analyzing..."""
 

src/ash/agents/executor.py

@@ -904,6 +904,7 @@ async def execute_turn(
         user_message: str | None = None,
         tool_result: tuple[str, str, bool] | None = None,
         session_manager: "SessionManager | None" = None,
+        tool_overrides: dict[str, Any] | None = None,
     ) -> TurnResult:
         """Run one logical turn for a stack frame.
 
@@ -917,6 +918,8 @@ async def execute_turn(
             user_message: Optional user message to inject.
             tool_result: Optional (tool_use_id, content, is_error) from completed child.
             session_manager: Optional session manager for logging to context.jsonl.
+            tool_overrides: Optional map of tool name -> tool implementation to use
+                for this turn instead of the shared executor registry.
 
         Returns:
             TurnResult indicating what happened.
@@ -1082,9 +1085,16 @@ async def execute_turn(
                             session_manager=session_manager,
                             tool_use_id=tool_use.id,
                         )
-                        result = await self._tools.execute(
-                            tool_use.name, tool_use.input, per_tool_context
-                        )
+                        override_tool = (tool_overrides or {}).get(tool_use.name)
+                        if override_tool is not None:
+                            result = await override_tool.execute(
+                                tool_use.input,
+                                per_tool_context,
+                            )
+                        else:
+                            result = await self._tools.execute(
+                                tool_use.name, tool_use.input, per_tool_context
+                            )
                         sanitized = self._sanitize_tool_result(
                             tool_name=tool_use.name,
                             tool_use_id=tool_use.id,

src/ash/capabilities/manager.py

@@ -379,6 +379,12 @@ async def auth_complete(
             code="capability_invalid_output",
             message="auth completion must return account_ref",
         )
+        credential_material = dict(complete_result.credential_material)
+        if _find_sensitive_key_path(credential_material, path="credential_material"):
+            raise CapabilityError(
+                "capability_invalid_output",
+                "provider auth completion returned credential material",
+            )
         now = datetime.now(UTC)
         async with self._lock:
             self._accounts[(flow.user_id, flow.capability_id, account_ref)] = (
@@ -387,7 +393,7 @@ async def auth_complete(
                     user_id=flow.user_id,
                     account_ref=account_ref,
                     created_at=now,
-                    credential_material=dict(complete_result.credential_material),
+                    credential_material=credential_material,
                     metadata=dict(complete_result.metadata),
                 )
             )
@@ -465,6 +471,14 @@ async def auth_poll(
                 code="capability_invalid_output",
                 message="auth poll completion must return account_ref",
             )
+            credential_material = dict(poll_result.credential_material)
+            if _find_sensitive_key_path(
+                credential_material, path="credential_material"
+            ):
+                raise CapabilityError(
+                    "capability_invalid_output",
+                    "provider auth poll returned credential material",
+                )
             now = datetime.now(UTC)
             async with self._lock:
                 self._accounts[(flow.user_id, flow.capability_id, account_ref)] = (
@@ -473,7 +487,7 @@ async def auth_poll(
                         user_id=flow.user_id,
                         account_ref=account_ref,
                         created_at=now,
-                        credential_material=dict(poll_result.credential_material),
+                        credential_material=credential_material,
                         metadata=dict(poll_result.metadata),
                     )
                 )

src/ash/capabilities/providers/subprocess.py

@@ -34,6 +34,17 @@
 
 _BRIDGE_PROTOCOL_VERSION = 1
 _BRIDGE_CONTEXT_TOKEN_TTL_SECONDS = 900
+_BRIDGE_BASE_ENV_KEYS = (
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "PATH",
+    "PYTHONPATH",
+    "TMP",
+    "TEMP",
+    "TMPDIR",
+    "USER",
+)
 
 
 class SubprocessCapabilityProvider(CapabilityProvider):
@@ -301,7 +312,14 @@ async def _execute_command(self, payload: dict[str, Any]) -> dict[str, Any]:
         return parsed
 
     def _bridge_environment(self) -> dict[str, str]:
-        env = dict(os.environ)
+        env: dict[str, str] = {}
+        for key in _BRIDGE_BASE_ENV_KEYS:
+            value = os.environ.get(key)
+            if value is not None:
+                env[key] = value
+        for key, value in os.environ.items():
+            if key.startswith("GOGCLI_"):
+                env[key] = value
         if self._extra_env:
             env.update(self._extra_env)
         env[ENV_SECRET] = self._context_token_service.export_verifier_secret()