> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conto Guard

> Run a customer-hosted payment tool that requires Conto approval before customer card code can execute.

# Conto Guard

Conto Guard is a customer-hosted payment gate for agents that use an existing
customer-owned card. Conto evaluates purchase policy and atomically claims the
approval before the customer's payment executor can run.

Guard is a separate product package:

```bash theme={null}
npm install @conto_finance/sdk @conto_finance/guard
```

<Warning>
  Conto Guard does not make an existing card non-bypassable. The card can still be used outside the
  guarded agent path, so every Guard result reports `canBypass: true`.
</Warning>

## What Guard Controls

| Guard controls                             | Guard does not control                           |
| ------------------------------------------ | ------------------------------------------------ |
| The customer-hosted agent payment endpoint | Issuer or card-network authorization             |
| Conto policy approval before execution     | Human or system use of the card elsewhere        |
| One atomic execution claim per approval    | PAN, CVC, expiry, or vault-token custody         |
| Confirmation and operator reconciliation   | Independent observation of all card transactions |
| Receipt fields returned to the agent       | 3DS and issuer challenges                        |

Guard uses the external-card policy overlay as its policy backend. It does not
rename or replace the overlay, checkout relay, or card issuing.

## Dashboard

Open **Conto Guard** in the Conto dashboard to see whether the policy backend is enabled, register
or manage masked card aliases, review active agent assignments, and monitor reconciliation work.
The dashboard cannot verify that the customer's credential store is isolated from the agent, so
the final deployment check remains a customer responsibility.

## Request Path

```text theme={null}
agent
  -> authenticated customer payment endpoint
  -> Conto Guard
  -> Conto policy approval
  -> atomic execution claim
  -> customer credential store and payment executor
  -> Conto confirmation
```

The customer payment endpoint must be the agent's only payment tool. Do not
import the credential store or executor into the agent process.

## Create a Guard

```typescript theme={null}
import { Conto } from '@conto_finance/sdk';
import { ContoGuard } from '@conto_finance/guard';

const conto = new Conto({
  apiKey: process.env.CONTO_AGENT_API_KEY!,
});

const guard = new ContoGuard({
  policy: conto.cards,
  integrationId: 'procurement-agent-production',
  deployment: {
    credentialCustody: 'CUSTOMER',
    agentHasRawCredentialAccess: false,
    unguardedAgentPaymentPath: false,
  },
  executor: async (purchase) => {
    const credential = await customerSecretStore.getCard(purchase.cardId);
    const result = await customerPaymentTool.charge({
      credential,
      amount: purchase.amount,
      currency: purchase.currency,
      merchantName: purchase.merchantName,
    });

    return {
      externalTxId: result.receiptId,
      authorizationCode: result.authorizationCode,
      actualAmount: result.amount,
      receipt: result,
    };
  },
});
```

The executor receives the approved merchant and amount. It does not receive the
Conto approval token. Guard rejects likely card numbers, credential fields,
secrets, and tokens before sending a purchase intent to Conto.

## Expose the Agent Tool

Use the framework-neutral handler from the package:

```typescript theme={null}
import { createContoGuardHandler } from '@conto_finance/guard';

export const handlePayment = createContoGuardHandler({
  guard,
  authenticate(request) {
    return customerAgentAuth.verify(request.headers.get('authorization'));
  },
  serializeReceipt(receipt) {
    return {
      id: receipt.receiptId,
      amount: receipt.amount,
      merchant: receipt.merchantName,
    };
  },
});
```

Authentication and a receipt serializer are required. Raw processor responses
are never returned by default. Guard scans the serialized receipt and rejects
sensitive fields or likely card numbers before responding to the agent.

## Handle Uncertain Confirmation

If payment code runs but confirmation to Conto fails, Guard raises
`ContoGuardConfirmationPendingError`. Persist the receipt and confirmation input
securely. Retry only `guard.retryConfirmation(error)`. Never execute the
purchase again.

## Production Checklist

* Remove raw credentials from agent prompts, tools, environment variables, and
  readable logs.
* Remove all unguarded payment tools from the agent.
* Keep the executor private to the customer-hosted service.
* Authenticate every request to the Guard endpoint.
* Use one stable idempotency key per purchase intent.
* Filter receipt fields returned to the agent.
* Reconcile confirmation-pending executions.
* Keep the organization allowlisted until every open request is resolved.