feat(oauth): add bidirectional OAuth phantom token swap

Extend sluice's phantom token system to handle OAuth credentials
bidirectionally. Previously, phantom swap was request-only (phantom to
real in outbound requests). This adds response-side interception: when
an OAuth token endpoint returns new access/refresh tokens, sluice
captures the real tokens, stores them in the vault, and replaces them
with phantom tokens in the response body before it reaches the agent.

Key changes:

Vault: new OAuthCredential type storing access_token, refresh_token,
token_url, and expires_at as JSON blob in age-encrypted files. Phantom
tokens are deterministic (SLUICE_PHANTOM:name.access/refresh).

Store: new credential_meta table (migration 000002) tracking credential
type and token_url. CRUD operations with upsert semantics.

CLI: --type oauth and --token-url flags on sluice cred add. Tokens
read from stdin to avoid shell history exposure. Two phantom files
per OAuth credential (CRED_ACCESS, CRED_REFRESH).

Proxy: OAuthIndex maps token URLs to credential names for fast lookup
during response interception. Response handler uses singleflight for
concurrent refresh dedup. Supports both JSON and form-encoded token
responses per RFC 6749. Request-side swap extended to handle OAuth
phantom pairs alongside static credentials.

API: OpenAPI spec and REST handlers updated with type/token_url fields
for credential CRUD endpoints.

Hot-reload: OAuth index rebuilt on StoreResolver calls. Async vault
writes after response interception do not block HTTP response delivery.

Author: nnemirovsky

CLAUDE.md

@@ -73,7 +73,8 @@ sluice mcp list
 sluice mcp remove <name>
 sluice mcp                          # start MCP gateway
 
-sluice cred add <name> [--destination host] [--ports 443] [--header Authorization] [--template "Bearer {value}"]
+sluice cred add <name> [--type static|oauth] [--destination host] [--ports 443] [--header Authorization] [--template "Bearer {value}"]
+sluice cred add <name> --type oauth --token-url <url> --destination <host> --ports 443
 sluice cred list
 sluice cred remove <name>
 
@@ -83,13 +84,15 @@ sluice audit verify                 # verify audit log hash chain integrity
 
 When `--destination` is provided, `sluice cred add` also creates an allow rule and binding in the store. For HTTP/WebSocket upstreams, `--command` holds the URL. Env values prefixed with `vault:` are resolved from the credential vault at upstream spawn time.
 
+Two credential types: `static` (default) for API keys and `oauth` for OAuth access/refresh token pairs. OAuth credentials prompt for tokens via stdin (not CLI flags) to avoid shell history exposure.
+
 ## Policy Store
 
 All runtime policy state in SQLite (default: `sluice.db`). TOML files for initial seeding only via `sluice policy import`. See `examples/config.toml` for the full seed format.
 
 Rules use `[[allow]]`/`[[deny]]`/`[[ask]]`/`[[redact]]` sections. Each entry carries exactly one of: `destination` (network), `tool` (MCP), or `pattern` (content inspection). The `rules` table uses a CHECK constraint enforcing mutual exclusivity of these columns. Import uses merge semantics (skip duplicates).
 
-Store uses `modernc.org/sqlite` (pure Go, no CGO), WAL mode, `golang-migrate` for schema. 5 tables: `rules`, `config`, `bindings`, `mcp_upstreams`, `channels`.
+Store uses `modernc.org/sqlite` (pure Go, no CGO), WAL mode, `golang-migrate` for schema. 6 tables: `rules`, `config`, `bindings`, `mcp_upstreams`, `channels`, `credential_meta`.
 
 ## Credential Injection: Phantom Token Swap
 
@@ -104,6 +107,27 @@ Three-pass injection in MITM: (1) binding-specific header injection, (2) scoped
 
 All HTTPS connections are MITMed (not just those with bindings) so phantom tokens can never leak upstream. `SecureBytes.Release()` zeroes credentials immediately after injection.
 
+### OAuth dynamic phantom swap
+
+Extends phantom swap to handle OAuth credentials bidirectionally. Static credentials are request-only (phantom -> real). OAuth credentials add response-side interception for transparent token lifecycle management.
+
+**Request side:** OAuth credentials produce two phantom pairs. `SLUICE_PHANTOM:cred.access` and `SLUICE_PHANTOM:cred.refresh` are swapped to real tokens in outbound requests. Works alongside static phantom pairs in the same three-pass injection.
+
+**Response side:** When an OAuth token endpoint returns new tokens, sluice intercepts the response. Real tokens are replaced with deterministic phantoms before the response reaches the agent. Vault is updated asynchronously. If the vault write fails, the agent still receives phantom tokens (not real ones). The next refresh cycle corrects the state.
+
+**Concurrent refresh protection:** `singleflight` keyed on credential name deduplicates async vault writes when multiple requests trigger simultaneous token refreshes. Each response is independently processed (phantom swap happens per-response), but vault persistence is deduplicated.
+
+**Data model:** `credential_meta` table stores credential type and token_url. `OAuthIndex` maps token URLs to credential names for fast response matching. Both are hot-reloaded via `StoreResolver()`.
+
+**Phantom file generation:** `GeneratePhantomEnv(credNames []string, providers ...Provider)` accepts an optional `Provider` to detect OAuth credentials. When a provider is given, OAuth credentials produce two files (`CRED_ACCESS`, `CRED_REFRESH`) instead of one. Callers without a provider get static phantom files only.
+
+**Key files:**
+- `internal/vault/oauth.go` -- OAuthCredential struct, parse/marshal, token update
+- `internal/vault/phantom.go` -- `GeneratePhantomEnv`, `WriteOAuthPhantoms`
+- `internal/proxy/oauth_index.go` -- Token URL index for response matching
+- `internal/proxy/oauth_response.go` -- Response interception, phantom swap, async vault persistence
+- `internal/store/migrations/000002_credential_meta.up.sql` -- Schema for credential metadata
+
 ### Protocol-specific handling
 
 | Protocol | Credential injection | Content inspection |

README.md

@@ -22,7 +22,7 @@ AI agents need credentials to be useful. Giving them real credentials is dangero
 | **MCP Gateway** | Tool names, arguments, responses | File writes, exec, deletions, any MCP tool call |
 | **SOCKS5 Proxy** | Every TCP and UDP connection | HTTP, HTTPS, WebSocket, gRPC, SSH, IMAP, SMTP, DNS, QUIC/HTTP3 |
 
-**Phantom token swap:** OpenClaw gets phantom tokens that look like real API keys. Sluice's MITM proxy swaps them for real credentials in-flight. If a phantom token leaks, it is useless outside the proxy.
+**Phantom token swap:** OpenClaw gets phantom tokens that look like real API keys. Sluice's MITM proxy swaps them for real credentials in-flight. If a phantom token leaks, it is useless outside the proxy. OAuth credentials are handled bidirectionally: sluice intercepts token endpoint responses, captures real tokens, and returns phantom tokens to the agent. The entire OAuth lifecycle (initial auth, token refresh, token rotation) is transparent.
 
 **Human approval:** Connections and tool calls matching "ask" policy rules trigger a notification via Telegram or HTTP webhook. OpenClaw blocks until a human responds with Allow or Deny.
 
@@ -233,6 +233,43 @@ Sluice supports multiple credential backends. Set `provider` in `[vault]` config
 
 Chain multiple providers with `providers = ["1password", "age"]`. First provider with the credential wins.
 
+## OAuth Token Management
+
+Sluice handles OAuth access and refresh tokens transparently through the phantom swap system. The agent never sees real tokens at any point in the OAuth lifecycle.
+
+**Adding OAuth credentials:**
+
+```bash
+# Tokens are read from stdin (not CLI flags) to avoid shell history exposure
+sluice cred add openai_oauth \
+  --type oauth \
+  --token-url https://auth0.openai.com/oauth/token \
+  --destination api.openai.com \
+  --ports 443
+# Prompts for: access token, refresh token (optional)
+```
+
+**Listing credentials shows the type:**
+
+```
+$ sluice cred list
+NAME             TYPE    DESTINATION
+openai_oauth     oauth   api.openai.com
+github_pat       static  api.github.com
+```
+
+**How it works:**
+
+1. Sluice stores real tokens in the vault and generates deterministic phantom tokens
+2. The agent receives phantom tokens and uses them normally with any SDK
+3. On outbound requests, sluice swaps phantom tokens for real tokens (same as static credentials)
+4. On token endpoint responses, sluice intercepts the response, captures new real tokens, and replaces them with phantoms before the response reaches the agent
+5. The vault is updated asynchronously. If the write fails, the agent still sees only phantom tokens
+
+**Token refresh and rotation:** When an access token expires and the agent (or SDK) sends a refresh request, sluice swaps the phantom refresh token for the real one, forwards the request, intercepts the response with new tokens, and returns phantoms. Concurrent refresh requests are deduplicated so only one vault update occurs per credential.
+
+**Supported response formats:** Both `application/json` and `application/x-www-form-urlencoded` token responses per RFC 6749.
+
 ## Approval Channels
 
 Sluice broadcasts "ask" verdicts to all configured approval channels. The first channel to respond wins. Other channels get a cancellation notice.
@@ -255,6 +292,18 @@ Manage sluice from your phone. Approve connections and tool calls, add credentia
 
 REST API on port 3000 for programmatic approval integration. `GET /api/approvals` lists pending requests, `POST /api/approvals/{id}/resolve` resolves them. Use this to build custom approval UIs or integrate with existing workflows.
 
+Credential management endpoints support both static and OAuth types:
+
+```bash
+# Add static credential
+curl -X POST http://localhost:3000/api/credentials \
+  -d '{"name":"github_pat","value":"ghp_xxx","destination":"api.github.com"}'
+
+# Add OAuth credential
+curl -X POST http://localhost:3000/api/credentials \
+  -d '{"name":"openai_oauth","type":"oauth","token_url":"https://auth.example.com/token","access_token":"at-xxx","refresh_token":"rt-xxx","destination":"api.openai.com"}'
+```
+
 ## Audit Log
 
 Tamper-evident JSON Lines log with blake3 hash chaining. Every connection, tool call, approval, and denial is recorded.

api/openapi.yaml

@@ -716,16 +716,37 @@ components:
       properties:
         name:
           type: string
+        type:
+          type: string
+          enum: [static, oauth]
+          description: Credential type (static or oauth)
+        token_url:
+          type: string
+          description: Token endpoint URL (only for oauth type)
 
     CreateCredentialRequest:
       type: object
-      required: [name, value]
+      required: [name]
       properties:
         name:
           type: string
         value:
           type: string
-          description: The credential secret value (stored encrypted)
+          description: The credential secret value (stored encrypted). Required for static type.
+        type:
+          type: string
+          enum: [static, oauth]
+          default: static
+          description: Credential type. Defaults to static.
+        token_url:
+          type: string
+          description: Token endpoint URL (required when type is oauth)
+        access_token:
+          type: string
+          description: OAuth access token (required when type is oauth)
+        refresh_token:
+          type: string
+          description: OAuth refresh token (optional, for token rotation)
         destination:
           type: string
           description: If set, also creates an allow rule and binding