Authorize an AI Agent to Perform Tasks on Your Behalf

/**
 * Requests an access token using Client Credentials flow
 * This is used for autonomous actions that don't require user permission
 */
async function getClientCredentialsToken(scope: string): Promise<string> {
  console.log(`Requesting client credentials token for scope: ${scope}`);

  // Create Basic auth credentials from environment variables
  const credentials = Buffer.from(
    `${process.env.PINGONE_CLIENT_ID}:${process.env.PINGONE_CLIENT_SECRET}`
  ).toString('base64');

  // Make token request to P1AIC
  const response = await fetch(process.env.PINGONE_TOKEN_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      // Use Basic auth with base64 encoded client_id:client_secret
      'Authorization': `Basic ${credentials}`,
    },
    body: new URLSearchParams({
      'grant_type': 'client_credentials',
      scope, // Request specific scope (e.g., 'prices' for deals API)
    }),
  });

  const data = await response.json();
  console.log('Client credentials token obtained successfully');

  return data.access_token;
}

// Added around existing code from the Client Credentials section above

import { SignJWT, importJWK } from 'jose';

// Type definition for CIBA initiate responses
interface CibaInitiateResponse {
  auth_req_id: string;
  expires_in: number;
  interval: number;
}

/**
 * Creates a contextual binding message based on the scope and context.
 * This is displayed to users as part of the push notification
 */
function createBindingMessage(scope: string, context: string): string {
  switch (scope) {
    case 'payment':
      return context
        ? `Allow agent to place order for ${context}?`
        : 'Allow agent to place an order on your behalf?';
    case 'address':
      return 'Allow agent to access your address information?';
    default:
      throw new Error(`Unknown CIBA scope requested: ${scope}`);
  }
}

/**
 * Creates and signs a CIBA request JWT
 */
async function createCibaRequestJWT(scope: string, userId: string, context: string): Promise<string> {
  const bindingMessage = createBindingMessage(scope, context);
  const currentTime = Date.now();
  const iat = Math.floor(currentTime / 1000);
  const exp = iat + 600; // Have the request be valid for 10 minutes

  const payload = {
    aud: process.env.PINGONE_CIBA_AUDIENCE,
    binding_message: bindingMessage,
    acr_values: process.env.PINGONE_CIBA_ACR_VALUES, // e.g., "push"
    exp, // expiration time for the authentication request
    iss: process.env.PINGONE_CIBA_ISSUER,
    login_hint: userId,
    scope: `openid ${scope}`,
    iat, // time at which the request was created
    nbf, // time before which the request is unacceptable
  };

  // Import JWK and sign JWT
  const jwk = JSON.parse(process.env.PINGONE_CIBA_JWK);
  const privateKey = await importJWK(jwk, 'ES256');
  const jwt = await new SignJWT(payload)
    .setProtectedHeader({
      alg: 'ES256',
      typ: 'JWT',
      kid: jwk.kid,
    })
    .sign(privateKey);
  return jwt;
}

/**
 * Initiates CIBA flow with P1AIC
 */
async function initiateCibaFlow(requestJWT: string): Promise<CibaInitiateResponse> {
  console.log('Initiating CIBA flow with P1AIC');

  // Create Basic auth credentials
  const credentials = Buffer.from(
    `${process.env.PINGONE_CLIENT_ID}:${process.env.PINGONE_CLIENT_SECRET}`
  ).toString('base64');

  const response = await fetch(process.env.PINGONE_CIBA_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`,
    },
    body: new URLSearchParams({
      'request': requestJWT,
    }),
  });

  const data = await response.json() as CibaInitiateResponse;
  return data;
}

/**
 * Polls for CIBA token after user approval
 */
async function pollForCibaToken(authReqId: string, interval: number): Promise<string> {
  console.log('Waiting for user approval...');

  const maxAttempts = Math.ceil(600 / initialInterval); // 10 minutes max
  let attempts = 0;

  // Create Basic auth credentials
  const credentials = Buffer.from(
    `${process.env.PINGONE_CLIENT_ID}:${process.env.PINGONE_CLIENT_SECRET}`
  ).toString('base64');

  while (attempts < maxAttempts) {
    // Wait before polling
    await new Promise(resolve => setTimeout(resolve, interval * 1000));
    attempts++;

    console.log(`Checking for approval (attempt ${attempts}/${maxAttempts})`);

    try {
      const response = await fetch(process.env.PINGONE_TOKEN_ENDPOINT, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Authorization': `Basic ${credentials}`,
        },
        body: new URLSearchParams({
          'grant_type': 'urn:openid:params:grant-type:ciba',
          'auth_req_id': authReqId,
        }),
      });

      const data = await response.json();
      if (data.access_token) {
        // Success! The user approved
        return data.access_token;
      }

      if (data.error === 'authorization_pending') {
        // Continue polling
        continue;
      } else if (data.error === 'access_denied') {
        throw new Error('User denied the permission request');
      } else if (data.error) {
        throw new Error(`CIBA error: ${data.error}`);
      }
    }

    throw new Error('CIBA flow timed out - user did not respond');
  }
}

/**
 * Complete CIBA flow to get user permission token
 */
async function getCibaToken(scope: string, userId: string, context: string): Promise<string> {
  console.log(`Starting CIBA flow for scope: ${scope} and context ${context}`);

  // 1. Create signed JWT request
  const requestJWT = createCibaRequestJWT(scope, userId, context);

  // 2. Initiate CIBA flow
  const cibaResponse = await initiateCibaFlow(requestJWT);

  // 3. Poll for user approval
  const token = await pollForCibaToken(cibaResponse.auth_req_id, cibaResponse.interval);

  return token;
}

// Export the CIBA function along with client credentials
export { getClientCredentialsToken, getCibaToken };

import { getClientCredentialsToken, getCibaToken } from './P1AICAuthService';
import { getAvailableDeals } from './tools/getAvailableDeals';
import { placeOrder } from './tools/placeOrder';

// Tool configuration mapping tools to their auth requirements
const TOOL_AUTH_CONFIG = {
  'getAvailableDeals': { type: 'client_credentials', scope: 'prices' }, // Business API access
  'placeOrder': { type: 'ciba', scope: 'payment' }, // Requires user permission
  //... other tool to authentication mappings
};

/**
 * Permission-aware tool execution that handles different auth types
 * This is called by the main agent when the LLM decides to use a tool
 */
async function executeToolWithPermissions(toolName: string, args: Record<string, unknown>, userId: string) {
  // Look up what authorization this tool requires
  const authConfig = TOOL_AUTH_CONFIG[toolName];

  let token
  if (authConfig?.type === 'client_credentials') {
    // Use Client Credentials to get access token from P1AIC for this scope
    token = await getClientCredentialsToken(authConfig.scope);
  } else if (authConfig?.type === 'ciba') {
    // Use context from args to create meaningful permission message
    const context = args.productName;
    token = await getCibaToken(authConfig.scope, userId, context);
  }

  // Execute the tool with the token
  return executeTool(toolName, args, userId, token);
}

/**
 * Central tool execution function that routes to specific implementations
 * This is where you add new tools as your agent capabilities grow
 */
private async executeTool(toolName: string, args: any, userId: string, token?: string): Promise<string> {
  switch (toolName) {
    case 'getAvailableDeals':
      return getAvailableDeals(token);
    case 'placeOrder':
      return placeOrder(args, userId, token);
    default:
      throw new Error(`Unknown tool: ${toolName}`);
  }
}

// Export for use by your main agent logic
export { executeToolWithPermissions };
Step 3: Add the placeOrder tool
The placeOrder tool is implemented similarly to the deals tool, but it will be calling a different and more sensitive API endpoint.

// src/tools/placeOrder.ts

export async function placeOrder(args: { productId: string; quantity: number }, userId: string, token: string): Promise<unknown> {
  try {
    const response = await fetch('https://api.example.com/purchase', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      },
      body: JSON.stringify({
        productId: args.productId,
        userId,
        quantity: args.quantity,
      }),
    });
    const data = await response.json();
    return data;
  } catch(error) {
    return `Failed to process purchase: ${error.message}`;
  }
}