agent-cred
by fxckcode
README.md
# `agent-cred` — Capability-Based Credential Broker & MCP Server for Coding Agents
[](https://github.com/fxckcode/agent-credential-broker/actions/workflows/ci.yml)
[](https://github.com/fxckcode/agent-credential-broker/releases)
[](./LICENSE)
[](https://go.dev/)
**Let agents use approved APIs without handing them your secrets.**
`agent-cred` is a local, capability-based credential broker with a CLI and MCP server for coding agents, software factories, and `rsc-harness`. It performs policy-approved HTTP requests while keeping raw credentials out of prompts, environment variables, process arguments, repository files, and returned output.
> [!IMPORTANT]
> **Security Truth (Same-UID Boundary)**
> No user-space software can prevent arbitrary code running with your OS user privileges (`UID`) from reading a secret if that secret is injected into its environment or `stdin`, or if the untrusted process can invoke the OS keychain directly.
> Therefore, `agent-cred` **does not provide a generic `exec` command that injects secrets**. Safe access is capability-based: the broker attaches the credential inside its own process, enforces strict host/method/path allowlists, and redacts secret material before returning the response.
---
## Quick Start
```bash
# 1. Build and verify the native executable
go test ./...
go build -o agent-cred ./cmd/agent-cred
# 2. Initialize non-secret policy skeleton (.agent-cred/profiles.json, .env.example, .gitignore)
./agent-cred init
# 3. Import a synthetic test credential (human runs this in their own terminal; never prints secret)
cp .env.example .env.local
./agent-cred import \
--profile example-github-readonly \
--env-file .env.local \
GITHUB_READONLY_TOKEN=github_pat_readonly
rm .env.local
# 4. Inspect profile policy metadata (no secrets returned)
./agent-cred inspect --profile example-github-readonly
# 5. Execute a policy-checked HTTPS request
./agent-cred request \
--profile example-github-readonly \
--method GET \
--url https://api.github.com/rate_limit
```
Run the local synthetic verification suite:
```bash
go test ./...
go vet ./...
```
---
## Project status
`agent-cred` is the native Go release (`0.3.0`) for safe local HTTP capabilities for coding agents. Read the [changelog](./CHANGELOG.md), [roadmap](./ROADMAP.md), and [security policy](./SECURITY.md) before adopting it for production credentials.
---
## Core Capabilities & Architecture
| Module | File | Responsibility |
| :--- | :--- | :--- |
| **Policy** | [`internal/policy`](./internal/policy) | Validates explicit non-secret profiles and deny-by-default request policy. |
| **Secret stores** | [`internal/secrets`](./internal/secrets) | Uses Linux Secret Service, macOS Keychain, Windows Credential Manager, or an explicitly acknowledged test-only store. |
| **Broker** | [`internal/broker`](./internal/broker) | Attaches credentials internally, enforces host/method/path/size/rate policies, and returns redacted responses. |
| **Transport** | [`internal/transport`](./internal/transport) | Performs bounded HTTP requests with HTTPS enforcement, DNS/IP SSRF checks, timeouts, and no redirects. |
| **Redaction** | [`internal/redaction`](./internal/redaction) | Removes raw and common encoded secret forms from response data and headers. |
| **CLI** | [`cmd/agent-cred`](./cmd/agent-cred) | Native executable for policy initialization, credential import, requests, safe curl, diagnostics, and MCP. |
| **MCP** | [`internal/mcp`](./internal/mcp) | Implements the stdio JSON-RPC server and four brokered tools. |
| **Legacy oracle** | [`src`](./src) | Temporary Node implementation retained for differential behavior checks during migration. |
---
## CLI Examples (Synthetic Credentials Only)
### 1. Non-Secret Profile Policy (`.agent-cred/profiles.json`)
```json
{
"version": 1,
"profiles": {
"example-github-readonly": {
"name": "example-github-readonly",
"description": "Read-only GitHub API profile for issue and PR metadata",
"credential": {
"name": "github_pat_readonly",
"scheme": "bearer",
"headerName": "Authorization"
},
"allowedHosts": ["api.github.com"],
"allowedMethods": ["GET"],
"allowedPathPrefixes": ["/repos/", "/rate_limit"],
"allowHttpLocalhost": false,
"timeoutMs": 10000,
"maxRequestBytes": 4096,
"maxResponseBytes": 262144,
"rateLimit": {
"maxRequests": 30,
"windowMs": 60000
},
"redactPatterns": ["gh[pousr]_[A-Za-z0-9_]+", "github_pat_[A-Za-z0-9_]+"],
"redactHeaders": ["authorization", "x-github-sso"],
"testRequest": {
"method": "GET",
"url": "https://api.github.com/rate_limit",
"expectedStatuses": [200]
}
}
}
}
```
### 2. Importing Synthetic Credentials for Tests
```bash
# Create a temporary synthetic env file (never use live tokens in repo files)
printf 'GITHUB_TOKEN=SYNTH_FAKE_TOKEN_FOR_LOCAL_TESTING_ONLY_12345\n' > .env.test
# Import into OS keychain (or add --store dev-file --allow-dev-store in headless CI tests)
./agent-cred import \
--profile example-github-readonly \
--env-file .env.test \
GITHUB_TOKEN=github_pat_readonly
rm .env.test
```
### 3. Safe `curl` Compatibility Mode (`agent-cred curl`)
`agent-cred curl` parses a safe subset of `curl` flags (`--profile`, `-X`, `-H`, `-d`, `--json`, `-i`, `-s`, `-m`) without a shell and attaches credentials inside the broker:
```bash
./agent-cred curl \
--profile example-github-readonly \
-X GET \
-H "Accept: application/vnd.github+json" \
https://api.github.com/rate_limit
```
**Rejected `curl` flags (fail closed by design):**
- `-K` / `--config` (arbitrary file read / directive injection)
- `-d @file` (arbitrary local file read/exfiltration)
- `-L` / `--location` / `--location-trusted` (credential leak across redirect hops)
- `-u` / `--user` / `--oauth2-bearer` (secrets in `argv` / process table)
- `-o` / `-O` / `-D` / `-c` (unredacted file writes)
- `-F` / `-T` (file upload exfiltration)
- `-k` / `--insecure` (disabling TLS verification)
- `-x` / `--proxy` (proxy credential interception)
- `-v` / `--verbose` / `--trace` / `--trace-ascii` (header secret leakage)
---
## MCP Client Configuration
Start the stdio MCP server via `agent-cred mcp` (or `node /path/to/agent-credential-broker/bin/agent-cred.js mcp`).
### Claude Code / Cursor / Gemini CLI / Antigravity (`mcpServers`)
```json
{
"mcpServers": {
"agent-cred": {
"command": "node",
"args": [
"/home/fxckcode/agent-credential-broker/bin/agent-cred.js",
"mcp",
"--cwd",
"/path/to/your/project"
]
}
}
}
```
### Exposed MCP Tools
| Tool Name | Purpose | Secret Exposure |
| :--- | :--- | :--- |
| `credential_list_profiles` | Lists configured profiles, allowed hosts/methods, and `secretPresent` boolean. | **Metadata only** |
| `credential_inspect_policy` | Inspects full non-secret policy rules for a named profile. | **Metadata only** |
| `credential_http_request` | Executes a policy-checked HTTP request (`profile`, `method`, `url`, optional `headers`, `body`). Denies non-HTTPS unless both policy and `allowHttpLocalhost` permit loopback testing. | **Redacted output + `<untrusted_api_data>` wrapper** |
| `credential_test_connection` | Runs the profile's `testRequest` health check and reports status/latency. | **Status metadata only** |
---
## Integration with `rsc-harness` & Software Factories
### 1. `rsc-harness` (`skills/agent-credentials/` & `01-TOOLS/`)
- Install or symlink [`skills/agent-credentials/SKILL.md`](./skills/agent-credentials/SKILL.md) into `.rsc/skills/agent-credentials/`.
- In `01-TOOLS/<TOOL>/test_connection`, call `agent-cred test --profile <profile>` instead of sourcing `.env` into an untrusted shell.
### 2. Autonomous Software Factories (`zellia-factory` / `factory.sh`)
- Keep `agent-cred` independent of the target repository.
- Never pass API tokens into `factory.conf`, `Bash($TEST_CMD)`, or agent environment variables.
- Grant planner/checker/reviewer agents access only to the `agent-cred` MCP server (`--mcp-config`) with read-only (`GET`) profiles scoped to the specific issue tracker or API host.
---
## Design Limits
1. **Same-UID Arbitrary Code Execution**: If an agent can run unrestricted Python/Node/Bash commands as the same OS user, it can bypass any user-space broker and talk to the OS keychain or filesystem directly. Combine `agent-cred` with tool gating (`--disallowedTools`) or OS/container user separation for untrusted code execution.
2. **Allowed-Host Abuse**: If a profile permits `POST` to an allowlisted host, a prompt-injected agent can send non-secret workspace data in the `POST` body to that allowlisted host. Use `GET`-only profiles whenever write access is unnecessary, and keep `maxRequestBytes` small.
3. **Transformative Server Echo**: `Redactor` strips literal, URL-encoded, and base64-encoded secrets plus configured regex patterns. It cannot detect a secret if a malicious remote endpoint encrypts or permutes the secret before returning it. Only allowlist trusted API hosts.
See [`SECURITY.md`](./SECURITY.md) and [`docs/THREAT-MODEL.md`](./docs/THREAT-MODEL.md) for the complete threat model.
---
## Verification Checklist
- [x] `go test ./...` — Go unit and security-boundary tests
- [x] `go vet ./...` — Go static analysis
- [x] `go build ./cmd/agent-cred` — Native executable build
- [x] `GOOS=windows GOARCH=amd64 go build ./cmd/agent-cred` — Windows executable cross-build
- [x] `GOOS=darwin GOARCH=arm64 go build ./cmd/agent-cred` — macOS executable cross-build
- [x] Native MCP `initialize`, `tools/list`, and `tools/call` frames
- [x] Synthetic credential import and redaction checks
- [x] Node implementation retained as a differential behavior oracle
## License
[MIT](./LICENSE)
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data