API Reference
Security Capabilities

Security Features

The SecurityCapabilities interface defines the security features added to an agent by the secureConnect() function.

Interface

interface SecurityCapabilities {
  getIdentity(): Promise<Identity>;
  verifyIdentity(): Promise<boolean>;
  can(action: string, context?: Record<string, unknown>): Promise<boolean>;
  secureCall(targetId: string, action: string, payload?: Record<string, unknown>): Promise<unknown>;
}

Methods

Identity Management

getIdentity()

Get the agent's SPIFFE identity.

async function getIdentity(): Promise<Identity>
  • Returns: Promise resolving to the agent's Identity
  • Throws: IdentityError if identity retrieval fails
  • Example:
const identity = await agent.getIdentity();
console.log('SPIFFE ID:', identity.spiffeId);

verifyIdentity()

Verify the agent's current identity is valid.

async function verifyIdentity(): Promise<boolean>
  • Returns: Promise resolving to true if identity is valid
  • Throws: ValidationError if verification fails
  • Example:
const isValid = await agent.verifyIdentity();
if (!isValid) {
  throw new Error('Invalid identity');
}

Policy Enforcement

can()

Check if an action is allowed by policy.

async function can(
  action: string, 
  context?: Record<string, unknown>
): Promise<boolean>
  • Parameters:
    • action: Action to check
    • context: Optional context for policy evaluation
  • Returns: Promise resolving to true if action is allowed
  • Throws: Error if policy manager not configured
  • Example:
const canAccess = await agent.can('read_data', {
  resource: 'customer_records',
  sensitivity: 'high'
});
if (!canAccess) {
  throw new Error('Access denied');
}

Secure Communication

secureCall()

Make a secure RPC call to another agent.

async function secureCall(
  targetId: string,
  action: string,
  payload?: Record<string, unknown>
): Promise<unknown>
  • Parameters:
    • targetId: Target agent's identifier
    • action: Action to perform
    • payload: Optional data to send
  • Returns: Promise resolving to the call result
  • Throws: Error if RPC client not configured
  • Example:
const result = await agent.secureCall(
  'data-processor',
  'process_data',
  { data: myData }
);

Usage Example

// Secure an agent
const agent = await secureConnect(myAgent, {
  spiffe: {
    trustDomain: "company.local",
    keyDir: "./certs"
  },
  policy: {
    endpoint: "http://localhost:8181"
  }
});
 
// Use security features
async function processData(data: any) {
  // 1. Verify identity
  const isValid = await agent.verifyIdentity();
  if (!isValid) {
    throw new Error('Invalid identity');
  }
 
  // 2. Check policy
  const canProcess = await agent.can('process_data', {
    dataType: data.type,
    sensitivity: data.sensitivity
  });
  if (!canProcess) {
    throw new Error('Not allowed to process this data');
  }
 
  // 3. Make secure call
  return agent.secureCall('processor', 'process', { data });
}
Secure FunctionIdentity Only Pattern