authbox

Instructions

Implementation Reference

• packages/mcp-protocol/src/server.ts:242-295 (handler)

  The toolGetCredential method handles the logic for executing the 'get_credential' tool, including policy enforcement, user approval, and calling the bridge to fetch the credential.

  private async toolGetCredential(
    session: MCPSession,
    policies: AgentPolicy[],
    args: Record<string, unknown>,
  ): Promise<ToolCallResult> {
    const serviceName = args.service_name as string;
    const fields = args.fields as string[] | undefined;
  
    const request: AccessRequest = {
      agentId: session.agentId,
      action: 'read',
    };
  
    const decision = this.policyEngine.evaluate(policies, request);
  
    // Handle step-up approval: wait for user decision
    if (!decision.allowed && decision.pendingApprovalId) {
      const approved = await this.policyEngine.requestApproval(
        decision.pendingApprovalId,
        request,
      );
      if (!approved) {
        decision.reason = 'Step-up approval denied by user';
        await this.logAccess(session, 'get_credential', serviceName, decision);
        return {
          content: [{ type: 'text', text: 'Access denied: step-up approval was denied by the user' }],
          isError: true,
        };
      }
      // User approved -- continue with credential retrieval
      decision.allowed = true;
      decision.reason = 'Step-up approval granted by user';
    }
  
    await this.logAccess(session, 'get_credential', serviceName, decision);
  
    if (!decision.allowed) {
      return {
        content: [{ type: 'text', text: `Access denied: ${decision.reason}` }],
        isError: true,
      };
    }
  
    const credential = await this.bridge.getCredential(session.userId, serviceName);
    if (!credential) {
      return {
        content: [{ type: 'text', text: `No credential found for service: ${serviceName}` }],
        isError: true,
      };
    }
  
    // Filter fields if requested
    const filtered = fields
      ? Object.fromEntries(Object.entries(credential).filter(([k]) => fields.includes(k)))

• packages/mcp-protocol/src/tools.ts:8-28 (schema)

  Defines the schema and description for the 'get_credential' tool.

  {
    name: 'get_credential',
    description:
      'Retrieve a credential from the Auth Box vault. Returns credential fields filtered by the agent\'s access policy. Never returns the raw secret unless the policy explicitly allows "read" action.',
    inputSchema: {
      type: 'object',
      properties: {
        service_name: {
          type: 'string',
          description: 'Name of the service to retrieve credentials for (e.g., "GitHub", "AWS")',
        },
        fields: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific fields to retrieve. Omit to get all permitted fields.',
        },
      },
      required: ['service_name'],
    },
  },
  {