agirails-security

AGIRAILS Security Guide

Security is critical when handling payments. Follow these guidelines to protect user funds and maintain trust.

Key Resolution Order

The SDK resolves signing keys in this priority:

1. ACTP_PRIVATE_KEY env var (explicit key, for CI/testing)
2. .actp/keystore.json + ACTP_KEY_PASSWORD (encrypted at rest, recommended)
3. wallet: 'auto' (Smart Wallet + micro-airdrop gas, zero-config)

The address is always derived from the key automatically -- never specify requesterAddress manually.

Critical Security Rules

1. Never Hardcode Private Keys

// WRONG - Private key exposed in code
const client = await ACTPClient.create({
  mode: 'mainnet',
  privateKey: '0x1234567890abcdef...', // CRITICAL BUG
});

// CORRECT - SDK auto-detects from keystore
const client = await ACTPClient.create({ mode: 'mainnet' });
// Key loaded from .actp/keystore.json + ACTP_KEY_PASSWORD env var

2. Never Log Sensitive Data

// WRONG - Key could appear in logs
console.log('Initializing with key:', privateKey);
logger.debug({ privateKey, address });

// CORRECT - Never log keys
console.log('Initializing wallet:', address);
logger.debug({ address, mode });

3. Always Use .gitignore

# AGIRAILS
.actp/
.env
.env.local
.env.*.local

4. Validate All Inputs

// WRONG - No validation
async function pay(to: string, amount: string) {
  return client.basic.pay({ to, amount });
}

// CORRECT - Validate inputs
async function pay(to: string, amount: string) {
  if (!isValidAddress(to)) {
    throw new Error('Invalid address');
  }
  if (!isValidAmount(amount)) {
    throw new Error('Invalid amount');
  }
  if (to.toLowerCase() === myAddress.toLowerCase()) {
    throw new Error('Cannot pay yourself');
  }
  return client.basic.pay({ to, amount });
}

Key Management

Development (Mock Mode)

No key needed -- mock mode generates ephemeral keys:

const client = await ACTPClient.create({ mode: 'mock' });