@permaegis/sdk

Embed AI agent security — KYA scoring, policy gates, HITL approvals, prompt-injection scans, deterministic sub-keys — into any TypeScript application.

PermAegis is a 5-layer enterprise security platform for AI agents (DeFAI, autonomous workflows, MCP tooling). This SDK is the client surface: a thin TypeScript wrapper around the PermAegis HTTP API.

npm install @permaegis/sdk
# or
pnpm add @permaegis/sdk

Quick start

import { PermAegis } from '@permaegis/sdk';

const pa = new PermAegis({
  apiKey: process.env.PERMAEGIS_API_KEY!,   // pa_live_…
  orgId:  process.env.PERMAEGIS_ORG_ID!,
});

// 1. Check a tool call against your org's policy
const decision = await pa.policy.evaluate({
  agentId:    'agent_123',
  capability: 'transfer:usdc',
  chain:      'base',
  amountUsd:  5_000,
});

if (decision.action === 'block') throw new Error(decision.reason);
if (decision.action === 'hitl')  await pa.hitl.wait(decision.wfid!);
// 'allow' | 'alert' | 'simulate_first' — continue

Deterministic sub-keys

Random tokens don't scale when an orchestrator agent spawns hundreds of short-lived sub-agents per day. PermAegis SDK derives scoped sub-keys from a single Ed25519 keypair — no DB row per sub-agent, no plaintext over the wire.

const pa  = new PermAegis({ apiKey, orgId });
const sub = await pa.derive('sub-task-42');

// Sub-client has the same API; every request is auto-signed
// with a fresh Ed25519 signature (300s skew window).
await sub.agents.list();

Revocation:

• Revoke the parent API key → all sub-clients dead within 60s
• DELETE /api/v1/sdk/keypairs/:id → that SDK instance's sub-keys dead
• Process restart with no keypair passed → fresh keypair, old one orphaned

API surface

| Namespace | Methods | Purpose | |---|---|---| | pa.agents | list, get, create, update, delete | Manage registered agents | | pa.scans | create, get, list | Run/inspect KYA + prompt-injection scans | | pa.threats | list, get, dismiss | Threat inbox + triage | | pa.policy | evaluate | Pre-action policy gate (allow/block/hitl/alert) | | pa.hitl | list, wait, approve, reject | Human-in-the-loop approval flow |

Configuration

new PermAegis({
  apiKey:           'pa_live_…',                       // required
  orgId:            'org_…',                           // required
  baseUrl:          'https://your-permaegis.example',  // optional — defaults to the hosted API
  timeout:          30_000,                            // ms, default 30s
  ed25519Keypair:   existingKeypair,                   // reuse across SDK reinitialisations
});

What PermAegis does

• L1 — Persistence: Prisma 5 + Neon Postgres + pgvector self-learning attack KB
• L2 — Identity: Clerk + ERC-8004 on-chain badges + Phala TEE attestation + Safe spending caps
• L3 — Runtime: SES/HardenedJS compartments + LLM Guard scanners (DeBERTa + Rebuff canaries + 384-dim vector RAG)
• L4 — Policy: MITRE ATLAS catalogue + composable policy DSL + Temporal durable workflows + OOAK intent hash binding
• L5 — Trust Surface: Dashboard + this SDK + verifiable VRF for audit sampling

Status

v0.1.0 — first public release. API is stable for the documented surface; advanced primitives (pa.canary.*, pa.encrypted.*) are SDK-internal until the corresponding hosted endpoints stabilise.

License

MIT — see LICENSE.