1claw

What this skill does

# 1Claw — HSM-Backed Secrets for AI Agents

1Claw is a policy-gated secrets vault for autonomous agents. Secrets are encrypted with keys that never leave hardware security modules (HSMs); agents fetch values at runtime through MCP or the REST API instead of embedding credentials in prompts.

| Resource | URL |
| --- | --- |
| API | `https://api.1claw.xyz` |
| Dashboard | `https://1claw.xyz` |
| Docs | `https://docs.1claw.xyz` |
| Shroud (TEE LLM + signing) | `https://shroud.1claw.xyz` |
| OpenAPI spec | `@1claw/openapi-spec` on npm |
| Canonical skill (full) | `https://github.com/1clawAI/1claw-skill` |

---

## Key capabilities

- **HSM envelope encryption** — AES-256-GCM DEKs wrapped by Google Cloud KMS (HSM-backed) KEKs
- **Policy-based access control** — agents get zero access until a human explicitly grants path-level policies
- **36 MCP tools** — secrets CRUD, signing, transactions, Bankr key leasing, treasury proposals, platform bootstrap, approvals, security inspection
- **Multi-chain signing keys** — Ethereum, Bitcoin, Solana, XRP, Cardano, Tron (private keys never leave the vault)
- **Transaction guardrails** — per-agent chain allowlists, address allowlists, per-tx caps, daily spend limits
- **OIDC federation** — 1claw is a JWKS-published issuer; agents can get RS256 tokens for external services (Anthropic WIF, GCP STS, AWS STS) without static keys
- **MPC secret storage** — DEKs split across 2-of-3 HSMs (GCP + AWS + Azure) or XOR 2-of-2 client custody
- **Exfil protection** — MCP server blocks secret leakage by default (tracks fetched values and blocks re-emission)
- **`inspect_content` (free, no vault)** — prompt injection / threat scanning without any credentials
- **Shroud TEE proxy** — inspected LLM traffic + confidential signing in AMD SEV-SNP enclaves
- **Platform API** — build applications on top of 1claw (bootstrap users, provision vaults, issue `plt_` keys)
- **Treasury multisig** — Safe proposals with threshold signing and auto-execute
- **Human-in-the-loop approvals** — agents request policy changes; humans approve/deny
- **Secret versioning and rotation** — every write creates a new version; server-generated rotation with configurable charset
- **Webhooks** — subscribe to wallet, proposal, transaction, policy, and signing key events

**Pair with Bankr (recommended — Dynamic Key Vending):** Org admins configure `BANKR_PARTNER_KEY` on Vault. Agents lease short-lived, scoped `bk_usr_` keys via `lease_bankr_key` (MCP), `1claw agent bankr-key lease`, or the dashboard — no manual `put_secret` / rotation. Shroud auto-resolves leased keys for `X-Shroud-Provider: bankr`. See [Bankr Key Vending guide](https://docs.1claw.xyz/docs/guides/bankr-key-vending).

**Legacy static path:** Store a long-lived Bankr key at `keys/bankr-api-key` or `providers/bankr/api-key` via `put_secret`, then `get_secret` when calling Bankr endpoints. Manual rotation when the key expires. Never paste `bk_...` or `ocv_...` keys into chat.

---

## When to use

- Store or rotate API keys, tokens, passwords, or env bundles
- Retrieve credentials at runtime without exposing them in the conversation
- Share a secret back to the registering human or another principal
- Sign or simulate EVM transactions under agent guardrails (Intents API)
- Provision or list per-chain signing keys (Ethereum, Bitcoin, Solana, XRP, Cardano, Tron)
- Create treasury multisig proposals (when delegated to a Safe)
- Get OIDC federation tokens for external services (no static API keys on the relying party)
- Scan arbitrary text for prompt injection, command injection, and social engineering (free, local-only)
- Request human approval for sensitive actions
- Lease a short-lived Bankr wallet API key for LLM Gateway or agent API access (dynamic key vending)

## When NOT to use

- Natural-language trading, swaps, or portfolio queries → **bankr** skill
- x402 pay-per-call to third-party APIs → Bankr `x402 call` or provider-specific skills
- Human-only treasury wallet generation/send/swap → 1Claw dashboard or CLI (agents get 403)

---

## Prerequisites

1. **Agent API key** (`ocv_...`) from the 1Claw dashboard (Agents → your agent → API key), or complete **self-enrollment** (below) and wait for human approval.
2. **Access policy** on the vault path you need (agents have **zero access by default** until a human grants read/write).
3. **Intents API** (optional): Human must enable **Intents API** on the agent for `submit_transaction`, `sign_transaction`, and unified `sign_*` tools. Private key paths are blocked when Intents is on — use the transaction proxy instead.

### Self-enrollment (no credentials yet)

```bash
curl -s -X POST https://api.1claw.xyz/v1/agents/enroll \
  -H "Content-Type: application/json" \
  -d '{"name":"my-bankr-agent","human_email":"[email protected]","description":"Bankr trading agent with vault-backed key management"}'
```

Response: `{ "agent_id": "...", "message": "...", "approval_url": "..." }`. The `ocv_` API key is emailed to the human after approval — never returned in the response.

---

## Setup (recommended): MCP over stdio

For Cursor, Claude Desktop, Codex, and other local MCP clients, use the **stdio** server. Only **`ONECLAW_AGENT_API_KEY`** is required — the server exchanges it for a short-lived JWT, auto-discovers **agent ID** and **vault**, and refreshes before expiry.

```json
{
  "mcpServers": {
    "1claw": {
      "command": "npx",
      "args": ["-y", "@1claw/[email protected]"],
      "env": {
        "ONECLAW_AGENT_API_KEY": "ocv_your_key_here"
      }
    }
  }
}
```

> **Supply-chain safety:** Always pin to a known-good version (e.g. `@1claw/[email protected]`). Running `npx -y @1claw/mcp` without a version tag risks executing compromised code if the package is ever hijacked. Verify the latest trusted version at [npmjs.com/package/@1claw/mcp](https://www.npmjs.com/package/@1claw/mcp) before updating the pin.

Optional overrides:

| Variable | Purpose |
| --- | --- |
| `ONECLAW_AGENT_ID` | Agent UUID if you want to pin identity (usually auto-discovered) |
| `ONECLAW_VAULT_ID` | Vault UUID when the agent can access multiple vaults |
| `ONECLAW_BASE_URL` | Self-hosted API — **only** `https://api.1claw.xyz` or `https://shroud.1claw.xyz` accepted by default; custom hosts require `--allow-custom-base-url` flag on the validation script (see below) |
| `ONECLAW_LOCAL_ONLY` | `true` — security tools only (`inspect_content`), no vault |

> **Base URL safety:** The setup script and MCP server default to `https://api.1claw.xyz`. Only HTTPS is accepted. If `ONECLAW_BASE_URL` is set to an untrusted host, your API key will be sent there. The validation script rejects non-HTTPS URLs and unknown hosts unless you explicitly pass `--allow-custom-base-url` (for self-hosted or development instances).

**Do not** configure IDE MCP with a static Bearer JWT against `https://mcp.1claw.xyz` — tokens expire in ~1 hour. Stdio + `ocv_` key is the supported long-running pattern.

### Security-only mode (no credentials needed)

Run the MCP server with `ONECLAW_LOCAL_ONLY=true` to get the `inspect_content` tool for free — scan prompts for injection, command injection, social engineering, PII, encoding tricks, and more:

```json
{
  "mcpServers": {
    "1claw-security": {
      "command": "npx",
      "args": ["-y", "@1claw/[email protected]"],
      "env": {
        "ONECLAW_LOCAL_ONLY": "true"
      }
    }
  }
}
```

### Validate your setup

```bash
./1claw/scripts/validate-setup.sh
```

The script enforces:
- **HTTPS required** — rejects `http://` URLs (credentials would be cleartext)
- **Trusted hosts only** — only `https://api.1claw.xyz` and `https://shroud.1claw.xyz` accepted by default
- **Explicit override for custom hosts** — pass `--allow-custom-base-url` for self-hosted/dev instances (shows a warning)

```bash
# Self-hosted example (requires explicit opt-in):
ONECLAW_BASE_URL=https://vault.mycompany.com ./1claw/scripts/validate-setup.sh --allow-custom-base-url
```

See `references/mcp-and-api