casper-agent-permissions

CAPP SDK — The TypeScript implementation of the Casper Agent Permission Protocol (CAPP-0001).

Grant, scope, verify, and revoke AI agent authority over Casper Network accounts using the native add_associated_key protocol primitive. No smart contracts. No trusted intermediaries. Every validator enforces it.

Why CAPP?

Every other approach to AI agent authority is broken:

| Approach | Problem | |---|---| | Smart contract permission layer | Requires separate deployment, gas overhead, audit surface | | Custom middleware | Off-chain — any validator ignores it | | Unconstrained agent keys | Agent can drain the account |

Casper's add_associated_key is a protocol-level primitive baked into the account model and enforced by every validator. CAPP wraps it into a clean grant / verify / revoke / audit API.

Install

npm install casper-agent-permissions

Quick start

import { createCapp } from "casper-agent-permissions";

const capp = createCapp({
  network: "testnet",
  signer: "017d96b9e3613fc48de02e08b9b0b5b1a6a88c8be929ed6da94c3e5f6f97d0a1e",
});

// Grant an AI agent bounded signing authority
const { deployHash } = await capp.grant({
  agentPublicKey: "0202b5e2b9d3c8a7f6e1d4c5b8a2e7f0d3c6b9a4e8f1d2c5b8a3e6f9d2c5b8a3",
  maxTransferMotes: 100_000_000_000n,   // 100 CSPR ceiling
  allowedContracts: ["hash-abc123..."], // contract whitelist
  actionTypes: ["transfer"],
  expiresInBlocks: 1000,
  keyWeight: 1,                         // weight 1, deploy threshold 3 → can never act alone
});

// Verify a deploy was signed by an authorized agent
const result = await capp.verify(deployHash);
console.log(result.authorized); // true
console.log(result.scope);      // { maxTransferMotes, allowedContracts, ... }

// Audit all agent grants for an account
const entries = await capp.audit();
// [{ agentPublicKey, scope, grantedAt, deployHash, status: "active" }]

// Revoke — agent loses signing power at next block
await capp.revoke({ agentPublicKey: "0202b5e2b9d..." });

API

createCapp(config): CasperAgentPermissions

Factory function. Creates a CAPP client.

interface CappConfig {
  network: "testnet" | "mainnet";
  signer: string;            // account public key hex
  nodeUrl?: string;          // override default RPC URL
  registryContractHash?: string; // AgentRegistry contract (optional)
}

.grant(scope): Promise<GrantResult>

Adds the agent's public key as an associated key with the specified weight. Returns the deploy hash for the caller to broadcast via their wallet.

interface PermissionScope {
  agentPublicKey: string;
  maxTransferMotes?: bigint;       // max CSPR the agent can move per deploy
  allowedContracts?: string[];     // contract hash whitelist
  actionTypes?: ("transfer" | "call" | "deploy")[];
  expiresInBlocks?: number;
  keyWeight?: number;              // default: 1
}

.verify(deployHash): Promise<VerifyResult>

Fetches the deploy from Casper RPC and checks the signer against the CAPP ledger.

.revoke(params): Promise<{ deployHash: string }>

Calls remove_associated_key for the given agent public key.

.audit(accountHash?): Promise<AuditEntry[]>

Returns all grant/revoke entries for the account, including status (active, revoked, expired).

Key weight model

The security guarantee comes from Casper's key weight threshold system:

Agent key weight:       1
Action threshold:       1   ← agent can sign routine deploys alone
Deploy threshold:       3   ← agent cannot send arbitrary deploys alone
Key management threshold: 3 ← agent cannot add/remove keys

Adjust thresholds to match your security requirements. The agent is physically incapable of exceeding its mandate — not just contractually restricted.

Protocol

This SDK implements CAPP-0001, the Casper Agent Permission Protocol specification.

Three-layer standard:

1. AgentRegistry.wasm — on-chain contract indexing all CAPP-registered agents
2. casper-agent-permissions — this SDK
3. Reference application — AgentForge, a task marketplace where AI agents bid using CAPP-scoped authority

License

MIT © codeswithroh