@codios/sdk

TypeScript SDK for Codios — the A2A Agent Security Layer.

Sign capability contracts between AI agents, verify identities with Ed25519, and enforce action scope — entirely offline, zero added latency.

Install

npm install @codios/sdk

Quick start

Generate a keypair (agent registration)

import { generateAgentKeyPair } from "@codios/sdk";

const keypair = generateAgentKeyPair();
// keypair.publicKey  → register this in Codios dashboard
// keypair.privateKey → store in AGENT_PRIVATE_KEY env var, never share
// keypair.did        → did:key:z6Mk...

Issue a contract (Codios platform side)

import { issueContract } from "@codios/sdk";

const contract = issueContract({
  issuerAgentId: "agt_abc",
  issuerDid: "did:key:z6Mk...",
  targetAgentId: "agt_xyz",
  targetDid: "did:key:z6Ml...",
  allowedActions: ["summarize", "translate"],
  forbiddenActions: ["delete", "write"],
  resourceLimits: { maxCalls: 50 },
  ttlSeconds: 3600,
}, process.env.CODIOS_PRIVATE_KEY!);

Verify a contract (receiving agent side)

import { verifyContract, decodeContract } from "@codios/sdk";

const contract = decodeContract(req.headers["x-codios-contract"]);
const { valid, reason } = verifyContract(contract, process.env.CODIOS_PUBLIC_KEY!, "summarize");

if (!valid) throw new Error(`Contract rejected: ${reason}`);

Express middleware

import { codiosGuard } from "@codios/sdk/middleware/express";

app.post("/summarize", codiosGuard({
  codiosPublicKey: process.env.CODIOS_PUBLIC_KEY!,
  gatewayUrl: process.env.CODIOS_GATEWAY_URL,   // enables nonce/replay check
  requiredAction: "summarize",
}), handler);

Next.js App Router

import { withCodios } from "@codios/sdk/middleware/fetch";

export const POST = withCodios(
  { codiosPublicKey: process.env.CODIOS_PUBLIC_KEY!, requiredAction: "summarize" },
  async (req, contract) => {
    return Response.json({ result: "done" });
  },
);

Deny reasons

| Reason | Meaning | |---|---| | contract_expired | expires_at is in the past | | action_forbidden | Action is in forbidden_actions | | action_not_permitted | Action is not in allowed_actions | | invalid_signature | Signature verification failed | | missing_signature | Contract has no signature field |

License

MIT — Midlantics