AstraCipher Documentation

AstraCipher is a cryptographic identity and trust protocol for AI agents. It provides W3C-standard Decentralized Identifiers (DIDs) and Verifiable Credentials secured with post-quantum cryptography, enabling agents to prove their identity, capabilities, and authorization chain.

Installation

Node.js / TypeScript

npm install @astracipher/core @astracipher/crypto

For the CLI tool:

npm install -g @astracipher/cli

Python

pip install astracipher

Quick Start

import { AstraCipher } from '@astracipher/core';

// Initialize AstraCipher
const ap = new AstraCipher({ network: 'testnet' });

// Create an agent identity (DID + PQC keys)
const { did, didId } = await ap.createAgent({
  name: 'my-agent',
  description: 'My first AstraCipher agent',
});

// Issue a credential with capabilities
const credential = await ap.issueCredential({
  subjectDID: didId,
  capabilities: ['data:read', 'data:write'],
  permissions: [
    { resource: 'api/*', actions: ['read', 'write'] },
  ],
  trustLevel: 7,
  expiresIn: '90d',
});

// Verify the credential
const result = await ap.verifyCredential(credential);
console.log(result.valid); // true

// Check specific permissions
const allowed = ap.hasPermission(credential, 'api/users', 'read');
console.log(allowed); // true

Decentralized Identifiers (DIDs)

Every AstraCipher agent gets a unique DID in the format did:astracipher:{network}:{identifier}. The DID document contains hybrid verification methods:

Verifiable Credentials

Credentials are the core trust primitive. They define what an agent can do, are signed by the issuer's PQC keys, and can be verified offline without contacting the issuer.

Key fields in an AstraCipher credential:

• capabilities — Named capabilities (e.g., market-data:read)
• permissions — Resource + action pairs with optional conditions
• trustLevel — Numeric trust score (1-10)
• rateLimits — Per-minute/hour/day request limits
• compliance — Regulatory framework attestations

Trust Chains

Trust chains model delegation of authority: Creator → Authorizer → Agent → Sub-agent. Each link in the chain has:

• A maximum delegation depth
• Capability intersection (child can only have subset of parent capabilities)
• Cryptographic proof of each delegation step

Post-Quantum Cryptography

AstraCipher uses NIST-standardized post-quantum algorithms via the @noble/post-quantum library:

• ML-DSA-65 (FIPS 204) — Digital signatures, ~2.4KB public keys
• ML-KEM-768 (FIPS 203) — Key encapsulation, ~1.2KB ciphertexts
• Hybrid mode — Both PQC and classical signatures required (defense in depth)

@astracipher/crypto

Low-level cryptographic primitives. Use this if you need direct access to key generation, signing, and KEM operations.

import { AstraCipherCrypto } from '@astracipher/crypto';

const crypto = new AstraCipherCrypto();

// Generate hybrid identity keys
const keys = crypto.generateIdentityKeys();
// { publicKey, secretKey, algorithm: 'hybrid', pqcPublicKey, classicalPublicKey }

// Sign data
const sig = crypto.sign(new TextEncoder().encode('hello'), keys.secretKey);

// Verify
const valid = crypto.verify(new TextEncoder().encode('hello'), sig.signature, keys.publicKey);
// true

@astracipher/core

The main protocol package. DID management, credential issuance/verification, trust chains, and the high-level AstraCipher API.

@astracipher/cli

Command-line tool for DevOps workflows:

# Create a new agent
astracipher create --name my-agent

# Scan a project for agent configs
astracipher scan --dir ./my-project

# Resolve a DID from the registry
astracipher resolve --did did:astracipher:testnet:abc123

# Issue a credential
astracipher issue --subject did:astracipher:testnet:abc123 --capabilities data:read

@astracipher/compliance-*

Pluggable compliance engine with modules for:

MCP Server Integration

Expose AstraCipher as MCP tools for any AI agent:

npx @astracipher/mcp-server

Available tools: create_agent_identity, verify_agent, check_permissions, inspect_credential

Google A2A Adapter

Full Google Agent-to-Agent protocol implementation with AstraCipher identity bridge:

import { A2AServer } from '@astracipher/a2a-adapter';

const server = new A2AServer({
  astracipherUrl: 'http://localhost:3456',
  port: 3457,
  agentCard: {
    did: 'did:astracipher:testnet:abc123',
    name: 'My A2A Agent',
    url: 'http://localhost:3457',
    skills: [
      { id: 'summarize', name: 'Summarize Text' },
    ],
  },
  taskHandler: async (task, message, ctx) => {
    // Your agent logic here
    return {
      status: 'completed',
      messages: [{ id: '1', role: 'agent', parts: [{ type: 'text', text: 'Done!' }] }],
    };
  },
});

await server.start();
// Agent Card at: http://localhost:3457/.well-known/agent-card.json

Python SDK

from astracipher import AstraCipherClient

async with AstraCipherClient(
    base_url="http://localhost:3456",
    api_key="ap_your_key",
) as client:
    # Create agent
    agent = await client.create_agent(name="my-agent")

    # Verify credential
    result = await client.verify_credential(credential_data)
    print(result.valid)  # True

    # Query audit trail
    entries = await client.query_audit_trail(agent_did=agent.did_id)

Compliance Guide

AstraCipher compliance modules validate agent configurations against regulatory frameworks and generate audit-ready reports. Use the compliance engine to check gaps, build payloads for credential issuance, and produce period reports.

import { ComplianceEngine } from '@astracipher/compliance-core';
import { DPDPComplianceModule } from '@astracipher/compliance-dpdp';

const engine = new ComplianceEngine();
engine.registerModule(new DPDPComplianceModule());

// Check compliance gaps
const gaps = engine.checkGaps({
  consentReference: 'CONSENT-001',
  purposeLimitation: ['analytics'],
  dataMinimization: true,
  retentionPeriod: '365d',
  crossBorderTransfer: false,
  dataFiduciary: 'Acme Corp',
  breachNotificationContact: 'dpo@acme.com',
  dataResidency: 'IN',
});

console.log(gaps); // [] — fully compliant!

Deployment

AstraCipher server can be deployed via Docker:

# Start with Docker Compose
docker compose -f docker/docker-compose.yml up -d

# Environment variables
DATABASE_URL=postgresql://user:pass@host:5432/astracipher
ASTRACIPHER_API_KEY=ap_your_master_key
PORT=3456