armoriq-iap

ArmorIQ Intent Assurance Plane (IAP) — Agent Security Skill

ArmorIQ's IAP is a cryptographic security layer that sits between an agent's reasoning and its tool execution. The core guarantee: every tool call must be traceable to a cryptographically signed plan. If a tool wasn't in the plan, it doesn't run.

This closes the gap that IAM and Zero Trust leave open: those frameworks verify who acted and what was accessed, but can't verify why an action occurred. IAP governs intent.

Both a Python SDK and a TypeScript SDK are available — choose based on the developer's stack. For deeper theory (Merkle proofs, Trust Update, sub-agent delegation), read references/concepts.md. For TypeScript-specific patterns, see references/typescript-sdk.md.

---

Core Concepts

CSRG (Canonical Structured Reasoning Graph) — An agent's natural-language plan gets converted into a deterministic graph of allowed steps, tools, data domains, and outputs. This graph is what gets enforced.

Intent Commit — A Merkle root computed from the CSRG, cryptographically signed by the IAP. Any mutation, insertion, or reordering of steps invalidates the root.

Composite Ephemeral Identity — The signed intent is bound to user + agent + context. Delegation across sub-agents is explicitly scoped; sub-agents cannot exceed the parent's approved plan.

Intent Token — A short-lived JWT that proves an action belongs to the committed plan. Agents pass this token at every tool invocation. Default TTL: 60 seconds.

Fail-Closed — If the IAP can't verify (network down, token expired, tool not in plan), the action is blocked. No silent fallbacks.

---

Quick Setup

Python

pip install armoriq-sdk

from armoriq_sdk import ArmorIQClient

client = ArmorIQClient(
    api_key="ak_your_key_here",   # from platform.armoriq.ai
    user_id="your-user-id",
    agent_id="your-agent-id"
)

TypeScript / Node.js

npm install @armoriq/sdk
# or: yarn add @armoriq/sdk

import { ArmorIQClient } from '@armoriq/sdk';

const client = new ArmorIQClient({
  apiKey: process.env.ARMORIQ_API_KEY!,   // from platform.armoriq.ai
  userId: process.env.USER_ID!,
  agentId: process.env.AGENT_ID!,
});

Store credentials in environment variables, not code:

export ARMORIQ_API_KEY="ak_your_key_here"
export USER_ID="your-user-id"
export AGENT_ID="your-agent-id"

---

Core Workflow (Three Phases)

Every IAP-secured agent run follows the same three phases regardless of language.

Phase 1 — Capture the Plan

Submit the agent's structured plan before any tools run. The IAP converts it into a CSRG and returns a planCapture / plan_capture object anchored to a Merkle root.

Python:

plan = {
    "goal": "Analyze Q4 sales data and write a summary report",
    "steps": [
        {"action": "read_file",      "tool": "filesystem",     "inputs": {"path": "sales_q4.csv"}},
        {"action": "compute_metrics","tool": "python_executor","inputs": {"operation": "aggregate"}},
        {"action": "write_report",   "tool": "filesystem",     "inputs": {"path": "report.md"}}
    ]
}

plan_capture = client.capture_plan(
    llm="claude-sonnet-4-6",
    prompt="Analyze Q4 sales and generate a summary",
    plan=plan
)

TypeScript:

const plan = {
  goal: 'Analyze Q4 sales data and write a summary report',
  steps: [
    { action: 'read_file',       tool: 'filesystem',      inputs: { path: 'sales_q4.csv' } },
    { action: 'compute_metrics', tool: 'python_executor', inputs: { operation: 'aggregate' } },
    { action: 'write_report',    tool: 'filesystem',      inputs: { path: 'report.md' } },
  ],
};

const planCapture = await client.capturePlan('claude-sonnet-4-6',
  'Analyze Q4 sales and generate a summary', plan);

Phase 2 — Get an Intent Token

# Python
token = client.get_intent_token(plan_capture)

// TypeScript
const token = await client.getIntentToken(planCapture);

Tokens are short-lived by design (default 60s). Refresh before expiry for long sequences.

Phase 3 — Invoke Tools with Enforcement

# Python
result = client.invoke(
    mcp_name="filesystem",
    action="read_file",          # must match a step in the committed plan
    intent_token=token,
    inputs={"path": "sales_q4.csv"}
)

// TypeScript
const result = await client.invoke('filesystem', 'read_file', token, {
  path: 'sales_q4.csv',
});

If the action isn't in the CSRG, the call throws IntentViolationError / IntentMismatchException immediately — no partial execution, no silent failure.

---

Full Examples

Python — Secured Agent Run

import os
from armoriq_sdk import ArmorIQClient, IntentViolationError

client = ArmorIQClient(
    api_key=os.environ["ARMORIQ_API_KEY"],
    user_id=os.environ["USER_ID"],
    agent_id=os.environ["AGENT_ID"]
)

def run_secured_agent(user_prompt: str, steps: list[dict]):
    plan = {"goal": user_prompt, "steps": steps}
    try:
        plan_capture = client.capture_plan("claude-sonnet-4-6", user_prompt, plan)
        token = client.get_intent_token(plan_capture)

        results = []
        for step in steps:
            result = client.invoke(
                mcp_name=step["tool"],
                action=step["action"],
                intent_token=token,
                inputs=step.get("inputs", {})
            )
            results.append(result)
        return results

    except IntentViolationError as e:
        print(f"[IAP] Blocked: {e}")   # log & surface — don't swallow
        raise
    except Exception as e:
        print(f"[IAP] Unreachable — halting: {e}")  # fail closed
        raise

TypeScript — Secured Agent Run

import { ArmorIQClient, IntentMismatchException, TokenExpiredException } from '@armoriq/sdk';

const client = new ArmorIQClient({
  apiKey: process.env.ARMORIQ_API_KEY!,
  userId: process.env.USER_ID!,
  agentId: process.env.AGENT_ID!,
});

async function runSecuredAgent(userPrompt: string, steps: Step[]) {
  const plan = { goal: userPrompt, steps };

  try {
    const planCapture = await client.capturePlan('claude-sonnet-4-6', userPrompt, plan);
    let token = await client.getIntentToken(planCapture);

    const results = [];
    for (const step of steps) {
      // Refresh token if needed for long-running sequences
      if (await client.verifyToken(token) === false) {
        token = await client.getIntentToken(planCapture);
      }
      const result = await client.invoke(step.tool, step.action, token, step.inputs ?? {});
      results.push(result);
    }
    return results;

  } catch (err) {
    if (err instanceof IntentMismatchException || err instanceof TokenExpiredException) {
      console.error('[IAP] Enforcement blocked action:', err.message);
    } else {
      console.error('[IAP] Service unavailable — halting agent:', err);
    }
    throw err;  // fail closed
  } finally {
    await client.close();  // clean up resources
  }
}

---

Policy Configuration

Policies add a fast, locally-evaluated enforcement layer on top of CSRG enforcement. They apply to both SDKs via config — see references/policy-reference.md for the full schema.

Python:

client = ArmorIQClient(
    api_key=os.environ["ARMORIQ_API_KEY"],
    user_id=os.environ["USER_ID"],
    agent_id=os.environ["AGENT_ID"],
    policy={
        "allow": ["read_file", "web_search", "compute", "write_file"],
        "deny":  ["bash", "exec", "web_fetch", "delete_file"]
    }
)

TypeScript:

const client = new ArmorIQClient({
  apiKey: process.env.ARMORIQ_API_KEY!,
  userId: process.env.USER_ID!,
  agentId: process.env.AGENT_ID!,
  // policy passed as SDKConfig option
});

deny is evaluated before allow — deny always wins on conflict.

---

Sub-Agent Delegation

Both SDKs support the delegate() method, which issues a scoped Trust Update — a new intent token bound to a sub-agent that can only do a subset of the parent's plan. This cryptographically prevents sub-agent escalation.

TypeScript:

// Parent agent delegates a research subtask
const delegatedToken = await client.delegate(
  token,           // parent's intent token
  subAgentId,      // the sub-agent's identifier
  ['web_search', 'summarize']  // subset of allowed actions
);

// Sub-agent uses delegatedToken — it cannot call anything outside this list
const result = await subAgentClient.invoke('search', 'web_search', delegatedToken, {
  query: 'Q4 revenue reports'
});

Python:

delegated_token = client.delegate(
    token,
    sub_agent_id,
    allowed_actions=["web_search", "summarize"]
)

For the full Trust Update theory, see references/concepts.md.

---

Integration Patterns

With Claude Agents SDK (TypeScript)

import Anthropic from '@anthropic-ai/sdk';
import { ArmorIQClient } from '@armoriq/sdk';

const anthropic = new Anthropic();
const iap = new ArmorIQClient({ apiKey, userId, agentId });

async function securedClaudeAgent(userTask: string) {
  // Step 1: Ask Claude to produce a structured plan
  const planningResponse = await anthropic.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: `Plan as JSON steps: ${userTask}` }],
  });

  const plan = extractPlan(planningResponse);  // parse JSON from content

  // Step 2: Commit plan to IAP
  const planCapture = await iap.capturePlan('claude-sonnet-4-6', userTask, plan);
  const token = await iap.getIntentToken(planCapture);

  // Step 3: Execute each step through enforcement
  for (const step of plan.steps) {
    await iap.invoke(step.tool, step.action, token, step.inputs);
  }
}

With OpenClaw (CLI — no code changes needed)

curl -fsSL https://armoriq.ai/install-armorclaw.sh | bash
openclaw config set plugins.entries.armorclaw.config.apiKey "ak_live_xxx"
openclaw config set plugins.entries.armorclaw.config.userId "your-user-id"
openclaw config set plugins.entries.armorclaw.config.agentId "your-agent-id"
openclaw gateway restart

---

Advanced: CSRG Cryptographic Proofs

For regulated/compliance workloads, enable Merkle inclusion proofs for every action:

export CSRG_VERIFY_ENABLED=true
export REQUIRE_CSRG_PROOFS=true
export CSRG_URL=https://your-csrg-endpoint.com

Every invoke call then verifies its inclusion in the committed Merkle tree — cryptographically proving the action was in the original plan. See references/concepts.md for the proof format and audit log structure.

---

What IAP Blocks Automatically

Attack	How IAP Blocks It
Prompt injection via file	Injected instructions request unplanned tools → blocked
Data exfiltration	web_fetch / upload not in plan → blocked at invoke
Intent drift	Plan mutated after commit → Merkle root mismatch → token invalid
Credential harvesting	.env / secret files not in plan → blocked
Sub-agent escalation	Delegated token can't exceed parent's CSRG scope
Token replay	Tokens expire (default 60s); expired tokens → blocked

---

Error Reference

Python	TypeScript	Meaning
IntentViolationError	IntentMismatchException	Action not in committed plan
IntentViolationError	TokenExpiredException	Token TTL elapsed — refresh it
IntentViolationError	InvalidTokenException	Token malformed or tampered
PolicyViolationError	(policy deny)	Local policy blocked the tool
ArmorIQServiceError	MCPInvocationException	IAP backend unreachable

For diagnostic steps on each error, see references/troubleshooting.md.

---

Resources

• Python SDK: pip install armoriq-sdk | github.com/armoriq/armoriq-sdk-customer
• TypeScript SDK: npm install @armoriq/sdk | github.com/armoriq/armoriq-sdk-customer-ts
• Platform / API Keys: platform.armoriq.ai
• Docs: docs.armoriq.ai
• ArmorClaw (OpenClaw plugin): github.com/armoriq/armorclaw
• IAP Research Paper: "Verifiable Reasoning and Identity Composition for AI Agents" (ArmorIQ + Google)
• Support: [email protected]