# ShieldNode

> ShieldNode is an API key proxy with push approval for AI agents. Developers give their agents revocable virtual keys instead of real credentials. When a key is disabled and an agent calls it, the user receives a push notification on their phone with Approve and Decline buttons. Approved access is time-bounded and auto-disables. Real upstream credentials are encrypted server-side with AES-256-GCM and never exposed to clients.

ShieldNode positions in the Just-In-Time access layer for AI agents, distinct from LLM gateways (LiteLLM, Portkey, OpenRouter, Helicone, Cloudflare AI Gateway) which handle routing but not approval.

## Core concepts

- **Virtual key**: a `sk_live_…` token issued by ShieldNode. Shown once at creation, hashed (SHA-256) for storage, never recoverable. Routes through `proxy.shieldnode.app` to the configured upstream API.
- **Service**: an upstream API configuration (base URL, auth method, encrypted credentials). One service can mint many virtual keys.
- **Push approval**: when a disabled key is called and the user has the mobile app, the proxy returns `403 approval_required` with a `request_id`, and sends a push notification with action buttons. Approved key activates for a bounded window (default 30 min, configurable per call via `X-Approval-Duration`). The user can also identify the requester via `X-Agent-Name`.
- **Limits per virtual key**: optional rate limit (req/min), total request cap, allowed paths (glob), allowed HTTP methods, expiry date, default approval window.
- **Free plan**: 2 services, 500 requests/month, 24-hour log retention.
- **Pro plan**: $9.99/mo or $69.99/yr (-42%), 14-day no-card trial. Unlimited services and keys, 100k requests/month, 7-day log retention, alerts, request packs.

## Docs

- [Documentation](https://shieldnode.app/docs.md): user-facing docs covering setup, virtual keys, security, push approval, FAQs.
- [Docs for AI Agents](https://shieldnode.app/docs/agents.md): how AI agents integrate via the ShieldNode skill, including push approval, headers, polling discipline.

## API reference (Proxy)

- Base URL: `https://proxy.shieldnode.app/{path}` where `{path}` is appended to the configured service base URL.
- Auth: `X-Api-Key: sk_live_…` header on every request.
- Optional approval headers: `X-Approval-Duration: <minutes>` (1..1440), `X-Agent-Name: <short label>` (≤60 chars).
- Response codes: 200 success, 401 invalid/missing virtual key, 403 disabled or restricted (see push-approval flow), 404 upstream path not found, 429 rate limit reached, 502 upstream error, 504 upstream timeout.

## Push approval flow

1. Agent calls a virtual key whose owner has disabled it.
2. Proxy returns `403 approval_required` with `{request_id, requested_minutes, poll_interval_seconds, timeout_seconds}`.
3. Mobile user receives push: title `Access request — {service}`, body `{agent_name or "External agent"} requests {N} min on "{alias}"`, two actions [Approve] [Decline].
4. On approve, the key's `active_until` is set to `now + N minutes` and `is_active` is true. Agent's next poll succeeds.
5. On decline, a short-lived flag is set; agent's next poll returns `403 approval_denied`.
6. After the window passes, the key auto-disables. Next call repeats the flow.

## Agent integration

Agents should always send `X-Agent-Name` (their identity) and `X-Approval-Duration` matching the expected workload size. On `403 approval_required`, wait the response's `poll_interval_seconds` (default 30s) and retry, up to `timeout_seconds` (default 5 min). On `403 approval_denied`, stop and tell the user. Tell the user only once that an approval is pending, then poll silently. Never request absurd durations or retry after explicit decline.

A canonical Python example for the polling loop is included in the [agent skill](https://github.com/RP0-undefined/shieldnode-skill/blob/main/SKILL.md).

## Security model

- Real upstream credentials: AES-256-GCM encrypted at rest, decrypted in memory at request time, never logged.
- Virtual keys: SHA-256 hashed before storage. Plaintext shown once at creation.
- Bodies: request and response bodies are forwarded transparently. Not logged, not stored, not inspected. Only metadata (method, path, status, latency, timestamp) is recorded.
- Transit: TLS 1.2+.
- Revocation: in-memory cache invalidates within 1s. No client-side rotation needed.
- Device security for push approval: Expo Push tokens are stored server-side, never returned in API responses, deleted on logout.

## Optional

- [Pricing](https://shieldnode.app/#pricing): Free and Pro tiers, monthly and annual.
- [GitHub: ShieldNode skill](https://github.com/RP0-undefined/shieldnode-skill): the open-source agent skill repository.
- [Privacy policy](https://shieldnode.app/privacy.md)
- [Terms](https://shieldnode.app/terms.md)