aztp-client

AZTP Client TypeScript

A TypeScript client library for the AZTP Identity Service, providing secure identity management and verification capabilities.

Installation

npm install aztp-client

Trusted Domains

The AZTP client maintains a whitelist of trusted domains for use with the trustDomain parameter. When you specify a domain that isn't in this whitelist, the client will display a warning and suggest valid alternatives from the approved list. If no trust domain is specified, the system defaults to aztp.network.

import aztp, {whiteListTrustDomains} from 'aztp-client';

# Check available trusted domains
console.log("Available trusted domains:", whiteListTrustDomains);

# Create a secure connection with a trusted domain

const otherSecuredAgentWithTrustDomain = await aztpClient.secureConnect(otherAgentB, otherAgentNameB, {
  trustDomain: whiteListTrustDomains["gptarticles.xyz"],
  isGlobalIdentity: false
});
console.log("Other AZTP ID with trust domain and linked identity:", otherSecuredAgentWithTrustDomain);

Current Trusted Domains

• gptarticles.xyz
• gptapps.ai
• vcagents.ai

Quick Start

import aztp, { whiteListTrustDomains } from "aztp-client";

async function main() {
  // Initialize the client with API key from environment
  const API_KEY = process.env.AZTP_API_KEY;
  if (!API_KEY) {
    throw new Error("AZTP_API_KEY is not set");
  }

  const client = aztp.initialize({
    apiKey: API_KEY,
  });

  // Create base agents
  const crewAgent = {};
  const otherAgentA = {};
  const otherAgentB = {};
  const agentName = "MyAgent-01";
  const otherAgentNameA = "MyAgent-01-A";
  const otherAgentNameB = "MyAgent-01-B";

  try {
    // Initialize AZTP client with all configuration
    const aztpClient = aztp.initialize({
      apiKey: API_KEY,
    });

    // Check available trusted domains
    console.log("Available trusted domains:", whiteListTrustDomains);

    // Issue identity
    // Example 1: Identity will be issued with global identity
    console.log("1. Issuing identity for agent:", agentName);
    const securedAgent = await aztpClient.secureConnect(crewAgent, agentName, {
      isGlobalIdentity: true,
    });
    console.log("AZTP ID:", securedAgent);

    // Example 2: Issue identity
    console.log("2. Issuing identity:", otherAgentNameA);
    const otherSecuredAgentA = await aztpClient.secureConnect(
      otherAgentA,
      otherAgentNameA,
      {
        isGlobalIdentity: false,
      }
    );
    console.log("Other AZTP ID:", otherSecuredAgentA);

    // Example 3: Issue identity with trust domain and parent identity
    // Identity will be issued with trust domain and parent identity
    // Trust domain must be verified in astha.ai
    console.log("3. Issuing identity with trust domain:", otherAgentNameB);
    const otherSecuredAgentWithTrustDomain = await aztpClient.secureConnect(
      otherAgentB,
      otherAgentNameB,
      {
        trustDomain: whiteListTrustDomains["gptarticles.xyz"],
        parentIdentity: securedAgent.identity.aztpId,
        isGlobalIdentity: false,
      }
    );
    console.log(
      "Other AZTP ID with trust domain:",
      otherSecuredAgentWithTrustDomain
    );

    // Verify identity
    console.log("\nVerify identity", "AgentName:", agentName);
    const isValid = await aztpClient.verifyIdentity(securedAgent);
    console.log("Identity Valid:", isValid);

    // Verify identity connection
    console.log(
      "\nVerify identity connection from agent",
      agentName,
      "to agent",
      otherAgentNameB
    );
    const isValidConnection =
      await aztpClient.verifyAuthorizeIdentityConnection(
        securedAgent.identity.aztpId,
        otherSecuredAgentWithTrustDomain.identity.aztpId
      );
    console.log("Valid Connection:", isValidConnection);

    // Get existing identity
    console.log("\nGet identity for", "AgentName:", agentName);
    const existingIdentity = await aztpClient.getIdentity(securedAgent);
    console.log("Get Identity:", existingIdentity);

    // Discoverable identities
    // Discoverable identities are identities that are discoverable by other agents
    console.log("\nDiscoverable identities");
    const discoveredIdentities = await aztpClient.discoverIdentity();
    console.log("Discovered Identities:", discoveredIdentities);

    // Discover identity with trust domain
    // Discoverable identities with trust domain are identities that are discoverable by other agents
    // Trust domain must be verified in astha.ai
    console.log("\nDiscoverable identities with trust domain");
    const discoveredIdentitiesWithTrustDomain =
      await aztpClient.discoverIdentity({
        trustDomain: whiteListTrustDomains["gptarticles.xyz"],
        requestorIdentity: securedAgent.identity.aztpId,
      });
    console.log(
      "Discovered Identities with Trust Domain:",
      discoveredIdentitiesWithTrustDomain
    );

    // Example: Revoking an identity
    console.log("\nRevoking identity for", "AgentName:", otherAgentNameA);
    const revokeResult = await aztpClient.revokeIdentity(
      otherSecuredAgentA.identity.aztpId,
      "Testing revocation functionality"
    );
    console.log("Revoke Result:", revokeResult);

    // Example: Reissuing a revoked identity
    console.log("\nReissuing identity for", "AgentName:", otherAgentNameA);
    const reissueResult = await aztpClient.reissueIdentity(
      otherSecuredAgentA.identity.aztpId
    );
    console.log("Reissue Result:", reissueResult);

    // Policy Example
    const identityAccessPolicy = await aztpClient.getPolicy(
      securedAgent.identity.aztpId
    );

    const policy = aztpClient.getPolicyValue(
      identityAccessPolicy.data,
      "code",
      "policy:0650537f8614"
    );

    if (policy) {
      const isAllow = aztpClient.isActionAllowed(policy, "list_users");
      console.log({ isAllow });
      if (isAllow) {
        console.log({ actions });
      }
    } else {
      console.log("Policy not found");
    }
  } catch (error) {
    console.error("Error:", error);
  }
}

Client Options

The client can be initialized with several options:

const client = aztp.initialize({
  apiKey: "your_api_key_here",
  // Additional options will be added in future versions
});

API Reference

Initialize Client

const client = aztp.initialize({
  apiKey: string,
});

Secure Connect

const securedAgent = await client.secureConnect(baseAgent, {
  name: string,
});

Verify Identity

const isValid = await client.verifyIdentity(securedAgent);

Verify Identity Connection

const isValid = await client.verifyAuthorizeIdentityConnection(fromAgentId, toAgentId, policyCode?);

• Parameters:
  • fromAgentId (string): The source AZTP ID (must start with 'aztp://')
  • toAgentId (string): The target AZTP ID (must start with 'aztp://')
  • policyCode (string, optional): The policy code to use for authorization (e.g., 'policy:xxxx')
• Returns: Promise indicating if the connection is authorized

Example:

const isAuthorized = await client.verifyAuthorizeIdentityConnection(
  securedAgent.identity.aztpId,
  otherSecuredAgent.identity.aztpId,
  "policy:0650537f8614" // Optional
);
if (isAuthorized) {
  console.log("Connection is authorized!");
} else {
  console.log("Connection is NOT authorized.");
}

Get Identity

const identity = await client.getIdentity(securedAgent);

Check Identity Policy Permissions

// Example 1: Get all action permissions for an identity
const allPermissions = await client.checkIdentityPolicyPermissions(aztpId);

// Example 2: Get permissions for a specific policy
const policyPermissions = await client.checkIdentityPolicyPermissions(aztpId, {
  policyCode: "policy:1589246d7b16",
});

// Example 3: Get permissions for specific actions
const actionPermissions = await client.checkIdentityPolicyPermissions(aztpId, {
  actions: ["list_users"],
});

// Example 4: Get permissions for multiple actions
const multipleActionPermissions = await client.checkIdentityPolicyPermissions(
  aztpId,
  {
    actions: ["list_users", "read", "write"],
  }
);

// Example 5: Get permissions for a specific trust domain
const trustDomainPermissions = await client.checkIdentityPolicyPermissions(
  aztpId,
  {
    trustDomain: "aztp.network",
  }
);

// Example 6: Get permissions for a specific policy and action combination
const policyAndActionPermissions = await client.checkIdentityPolicyPermissions(
  aztpId,
  {
    policyCode: "policy:1589246d7b16",
    actions: ["list_users"],
  }
);

• Parameters:
  • aztpId (string): The AZTP ID to get action permissions for
  • options (optional):
    • policyCode: Optional policy code to filter permissions
    • actions: Optional array of actions to check permissions for
    • trustDomain: Optional trust domain to scope the permissions
• Returns: Promise containing the API response with action permissions

Create Workload Identity Link

const linkResult = await client.linkIdentities(
  "aztp://astha.ai/workload/production/node/shova/doverman", // sourceIdentity
  "aztp://astha.ai/workload/production/node/mobile", // targetIdentity
  "linked" // relationshipType: 'linked' or 'parent'
);

Discoverable identities

const discoveredIdentities = await aztpClient.discoverIdentity();

Discoverable identities with trust domain and requestor identity

const discoveredIdentities = await aztpClient.discoverIdentity(
  trustDomain,
  requestorIdentity
);

Access Policy

The AZTP client provides methods to retrieve and inspect access policies for identities. The main methods are:

1. getPolicy(aztpId)

Retrieves the access policy for a specific AZTP identity.

const identityAccessPolicy = await aztpClient.getPolicy(aztpId);

• Parameters:
  • aztpId (string): The AZTP ID to get access policy for (must start with 'aztp://').
• Returns: Promise containing the access policy data with version and policy statements.

2. getPolicyValue(policies, filterKey, filterValue)

Filters the access policy data by a key-value pair and returns the policy statement if found.

const policy = aztpClient.getPolicyValue(
  identityAccessPolicy.data,
  "code", // or "policyName"
  "policy:0650537f8614" // the value to match
);

• Parameters:
  • policies: Array of policy objects (from getPolicy)
  • filterKey: The key to match (e.g., 'code', 'policyName')
  • filterValue: The exact value to match
• Returns: The matched policyStatement object or undefined if not found.

3. isActionAllowed(policy, action)

Checks if a specific action is allowed by the given policy statement.

const isAllow = aztpClient.isActionAllowed(policy, "list_users");

• Parameters:
  • policy: The policy statement object (from getPolicyValue)
  • action: The action string to check (e.g., 'list_users')
• Returns: true if the action is allowed, false otherwise.

Example Usage

const identityAccessPolicy = await aztpClient.getPolicy(aztpId);

// Filter for a specific policy by code
const policy = aztpClient.getPolicyValue(
  identityAccessPolicy.data,
  "code",
  "policy:0650537f8614"
);

if (policy) {
  const isAllow = aztpClient.isActionAllowed(policy, "list_users");
  console.log({ isAllow });
  if (isAllow) {
    console.log({ actions });
  }
} else {
  console.log("Policy not found");
}

Sample Output:

{ isAllow: true }
{ actions: [ 'read', 'write', 'list_users' ] }

**Advanced Examples

Identity Revocation Example

You can revoke an identity using the revokeIdentity method. This requires the AZTP ID (must start with aztp://) and a reason for revocation.

const revokeResult = await aztpClient.revokeIdentity(
  "aztp://your-identity",
  "Identity compromised"
);

console.log("Revoke success:", revokeResult.success);
console.log("Revoke message:", revokeResult.message);

Sample Output:

Revoke success: true
Revoke message: Identity successfully revoked

---

Identity Reissue Example

To reissue a previously revoked identity, use the reissueIdentity method with the AZTP ID:

const reissueResult = await aztpClient.reissueIdentity("aztp://your-identity");

console.log("Reissue success:", reissueResult.success);
console.log("Reissue message:", reissueResult.message);

Sample Output:

Reissue success: true
Reissue message: Identity successfully reissued

---

Workload Identity Link Example

You can create links between workload identities using the linkIdentities method. This allows you to establish relationships between different identities, which can be useful for creating hierarchical structures or peer connections.

const linkResult = await aztpClient.linkIdentities(
  "aztp://astha.ai/workload/production/node/sourceIdentity",
  "aztp://astha.ai/workload/production/node/targetIdentity",
  "linked"
);

console.log("Link created:", linkResult.success);
console.log("Link message:", linkResult.message);
console.log("Relationship type:", linkResult.data.relationshipType);

Parameters:

• sourceIdentity: The source AZTP identity (must start with 'aztp://')
• targetIdentity: The target AZTP identity (must start with 'aztp://')
• relationshipType: The type of relationship - either 'linked' (peer) or 'parent' (hierarchical)
• metadata: Optional metadata about the link, including security context

Sample Output:

Link created: true
Link message: WI-LIN-CRE-S-001 - Workload identity link created successfully
Relationship type: linked

---

Access Policy Example

You can retrieve and inspect the access policy for an identity using getPolicy. To filter for a specific policy, use getPolicyValue.

OIDC Authentication

The AZTP client provides OpenID Connect (OIDC) authentication capabilities through two main methods:

1. OIDC Login

Initiates an OIDC login flow with a specified provider.

const loginResponse = await aztpClient.oidc.login(provider, aztpId, options);

• Parameters:
  • provider (string): The OIDC provider (e.g., 'google')
  • aztpId (string): The AZTP ID for the authentication (must start with 'aztp://')
  • options (object):
    • callbackUrl (string): The URL where the provider should redirect after authentication

Example:

const loginResponse = await aztpClient.oidc.login("google", "aztp://aztp.local/workload/production/node/my-app", {
    callbackUrl: "http://localhost:3000/oidc/callback"
});

2. Token Validation

Validates a JWT token received from the OIDC authentication flow.

const validationResult = await aztpClient.oidc.validateToken(token);

• Parameters:
  • token (string): The JWT token to validate

Example:

const validationResult = await aztpClient.oidc.validateToken("your-jwt-token");
console.log("Token validation result:", validationResult);

Requirements

• Node.js >= 14.0.0
• TypeScript >= 4.9.0

License

MIT

Support

For support, please contact [e-mail]