npm package: @globance-lab/agent-secrets-guard
Description: agent-secrets-guard-server: zero-trust credential broker for AI agents
Latest version: 0.1.0

# agent-secrets-guard

Secure token broker for AI agents.

> ⚠️ Security-focused project. Please read the threat model section before production use.

Replace long-lived API keys on agent machines with short-lived scoped tokens, policy checks, approvals, and audit logs.

## Why this exists

Most agent setups still rely on `.env` keys and long-lived refresh tokens. If that machine is compromised, your providers are compromised.

`agent-secrets-guard` keeps long-lived secrets on the server side and only returns ephemeral, action-scoped JWTs to agents.

## When to use agent-secrets-guard

Use this if:

- You deploy AI agents on developer workstations or shared servers
- You want to eliminate long-lived API keys from agent machines
- You need auditable, policy-enforced agent actions
- You operate in regulated or security-sensitive environments

You may not need this if:

- You are running a local hobby script
- Your agent has no external provider credentials
- You are already using a full enterprise identity platform

## Core capabilities

- Encrypted secret vault (AES-256-GCM) with versioned rotation
- Ephemeral token minting (RS256 JWT, scoped, org/agent/action-bound)
- Policy engine (allow, block, approval-required)
- Optional action approval workflow for sensitive operations
- Append-only audit event log
- Token revocation and introspection support
- Agent authentication with hashed API keys + optional device fingerprint

## Design principles

- Zero trust between agent and provider
- Least privilege via scoped tokens
- Short-lived credentials only
- No plaintext secret exposure through public APIs
- Auditability by default
- Explicit trade-offs documented

## Architecture

```text
AI Agent
   |
   |  (Authenticated request: agent-id + key/session)
   v
agent-secrets-guard
   |- Secret Vault (AES-256-GCM, versioned)
   |- Policy Engine (allow / block / approval)
   |- Token Minting Engine (RS256 JWT, short-lived)
   |- Revocation Store (jti blacklist)
   |- Approval Workflow
   |- Audit Log (append-only)
   |
   v
Downstream Provider (Google, OpenAI, AWS, etc.)
```

Ephemeral JWTs are scoped and never include raw downstream provider secrets.

## Quick start (60 seconds)

```bash
npm i -D agent-secrets-guard
npx asg dev
# copy printed env snippet into your agent app
```

For local persistence across restarts:

```bash
npx asg dev --persist
```

### Docker

```bash
docker build -t agent-secrets-guard .
docker run --rm -p 3000:3000 --env-file .env agent-secrets-guard
```

Or with compose:

```bash
docker compose up --build
```

## CLI commands

- `asg dev` - zero-config local bootstrap and run
- `asg dev --persist` - run with SQLite-backed local persistence
- `asg init --policy minimal --docker` - generate `.asg/config.json` and starter files
- `asg doctor` - run environment/security health checks
- `asg policy apply preset agent:calendar-assistant --org org_123 --agent agent_456` - apply preset policy

Built-in policy presets:

- `dev:allow-all`
- `safe:read-only`
- `agent:calendar-assistant`
- `agent:email-drafter`

## Use in another Node project

Install:

```bash
npm i agent-secrets-guard
```

Start the guard service from your own app:

```ts
import { buildApp, loadConfig } from "agent-secrets-guard";

const app = await buildApp(loadConfig());
await app.listen({ host: "0.0.0.0", port: 3000 });
```

## SDK client

Use the typed client instead of ad-hoc `fetch()` calls:

```ts
import { createGuardClient } from "agent-secrets-guard/client";

const guard = createGuardClient({
  baseUrl: process.env.AGENT_SECRETS_GUARD_URL!,
  agentId: process.env.AGENT_ID!,
  agentApiKey: process.env.AGENT_API_KEY!,
  deviceFingerprint: process.env.DEVICE_FINGERPRINT
});

const { token, expiresAt } = await guard.mint({
  orgId: process.env.ORG_ID!,
  action: "calendar.create_event",
  resource: "google_calendar",
  constraints: { maxEvents: 10, expiresIn: 600 }
});
```

## First integration flow

1. Register an agent (`POST /internal/v1/agents`)
2. Attach a policy (`POST /internal/v1/policies`)
3. Mint token (`POST /api/v1/token/mint`)
4. Use token downstream
5. Introspect/revoke when needed

Token mint example:

```bash
curl -X POST http://localhost:3000/api/v1/token/mint \
  -H "content-type: application/json" \
  -H "x-agent-id: agent_456" \
  -H "x-agent-api-key: agent-api-key" \
  -d "{\"orgId\":\"org_123\",\"agentId\":\"agent_456\",\"action\":\"calendar.create_event\",\"resource\":\"google_calendar\"}"
```

## API overview

### Public/Admin endpoints

- `POST /api/v1/secrets`
- `POST /api/v1/token/mint`
- `POST /api/v1/token/revoke`
- `POST /api/v1/actions/approve`
- `GET /api/v1/audit?orgId=org_123`

### Internal endpoints

- `POST /internal/v1/secrets/resolve`
- `POST /internal/v1/agents`
- `POST /internal/v1/policies`
- `POST /api/v1/token/introspect`

### Utility endpoints

- `GET /health`
- `GET /api/v1/.well-known/jwks.json`

## Example JWT claims

Ephemeral tokens include standard claims and scoped security context:

- `iss` - issuer
- `sub` - subject (`<orgId>:<agentId>`)
- `aud` - resource audience
- `jti` - unique token ID
- `exp` - expiration timestamp
- `orgId` - organization ID
- `agentId` - agent identity
- `action` - permitted action
- `resource` - permitted resource
- `constraints` - additional policy constraints

Tokens are RS256 signed and verifiable through `GET /api/v1/.well-known/jwks.json`.

## Threat model

### Protects against

- Accidental credential leakage in agent repos/workstations
- Long-lived token abuse by replacing them with short-lived scoped tokens
- Over-privileged agent behavior via policy checks
- Missing accountability through auditable security events

### Does NOT protect against

- Full host compromise (root/admin-level access)
- Kernel-level malware
- In-memory secret extraction from compromised runtime
- Physical device compromise

## Security notes

- Master key source is currently environment-driven (`MASTER_KEY`) for MVP deployments.
- ⚠️ If `MASTER_KEY` is stored in a plaintext `.env` file on the same host, vault encryption does not protect against full host compromise.
- For production:
  - Store master key in a secure secret manager
  - Or use envelope encryption with external KMS
- Token mint endpoint is rate limited.
- Per-agent and per-IP limits are configurable.
- Agent API key headers are supported now for bootstrap simplicity; session-token auth is a recommended next hardening step.
- `asg dev` stores local bootstrap state under `~/.agent-secrets-guard/` with restrictive file permissions.

## Why not just use HashiCorp Vault?

Vault is excellent for general server-side secret management.

`agent-secrets-guard` is purpose-built for AI agents:

- Agent-aware policy model (action/resource-bound)
- Short-lived JWT minting by default
- Approval workflow for autonomous actions
- Lightweight deployment footprint
- Developer-first integration

It complements Vault but does not attempt to replace full enterprise secret management systems.

## Examples

See `examples/`:

- `examples/example-openclaw`
- `examples/example-langchain-node`
- `examples/example-express-secure-agent`

## Scripts

- `npm run dev` - start with hot reload (tsx)
- `npm run build` - compile TypeScript
- `npm run start` - run compiled server
- `npm run test` - run integration tests
- `npm run lint` - type-check

## Environment variables

Required:

- `MASTER_KEY`
- `ADMIN_API_KEY`
- `INTERNAL_API_KEY`

Common optional:

- `PORT` (default `3000`)
- `JWT_ISSUER` (default `agent-secrets-guard-server`)
- `JWT_DEFAULT_TTL_SECONDS` (default `600`)
- `JWT_MAX_TTL_SECONDS` (default `900`)
- `RATE_LIMIT_MAX` (default `200`)
- `RATE_LIMIT_TIME_WINDOW` (default `1 minute`)
- `MINT_RATE_LIMIT_MAX` (default `60`)
- `MINT_RATE_LIMIT_TIME_WINDOW` (default `1 minute`)
- `KMS_KEY_ID` (recommended for production envelope/KMS mode)

## Production checklist

- Use Postgres + Redis adapters instead of in-memory stores
- Keep internal routes on private network paths only
- Use KMS/envelope encryption for master key handling
- Enable strict rate limits and monitor audit events
- Rotate agent credentials and signing keys regularly

## Security disclosures

If you discover a security issue, please email:

- `security@globance.ai`

Do not open a public issue for sensitive vulnerabilities.

## Roadmap (OSS focus)

- Session-token auth for agents (reduce static key exposure)
- Per-agent/per-org rate limits
- Pluggable persistence adapters (Postgres + Redis)
- OpenClaw integration guide and framework-specific SDK helpers

---

## Maintained by

agent-secrets-guard is built and maintained by the engineering team at Globance, where we deploy AI agents in production environments.

This project is open-source and independent of any Globance product requirements.