Alchemy Security Basics

---
name: alchemy-security-basics
description: 'Apply Web3 security best practices for Alchemy-powered applications.

  Use when securing API keys, validating blockchain inputs, preventing

  private key exposure, or hardening dApp infrastructure.

  Trigger: "alchemy security", "web3 security", "protect private key",

  "alchemy API key security", "dApp security".

  '
allowed-tools: Read, Write, Edit, Grep
version: 1.5.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- blockchain
- web3
- alchemy
- security
compatibility: Designed for Claude Code
---
# Alchemy Security Basics

## Overview

Web3 security practices for Alchemy-powered applications: API key protection, private key management, input validation, and smart contract interaction safety.

## Security Checklist

| Category | Requirement | Priority |
|----------|------------|----------|
| API keys | Never expose in client-side code | Critical |
| Private keys | Use environment vars or secret manager | Critical |
| Addresses | Validate and checksum all inputs | High |
| RPC calls | Never pass user input directly to RPC | High |
| Webhooks | Verify HMAC signatures | High |
| Dependencies | Audit npm packages for supply chain | Medium |

## Prerequisites

- A threat model that names provider-key, deployer-key, webhook, public-route,
  and user-input trust boundaries.
- Managed secret storage and a revocation owner for every provider or signing
  credential; do not rely on a developer workstation environment file in
  production.
- Security tests using synthetic inputs and a reviewed incident path for
  suspected key exposure, invalid signatures, or unsafe contract operations.

## Instructions

### Step 1: API Key Protection

```typescript
// WRONG — API key in frontend code
// const alchemy = new Alchemy({ apiKey: 'demo123' }); // NEVER DO THIS

// RIGHT — API key in backend proxy
// src/api/proxy.ts
import express from 'express';
import { Alchemy, Network } from 'alchemy-sdk';

const app = express();
const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY, // Server-side only
  network: Network.ETH_MAINNET,
});

// Proxy endpoint — frontend calls this instead of Alchemy directly
app.get('/api/balance/:address', async (req, res) => {
  const { address } = req.params;
  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
    return res.status(400).json({ error: 'Invalid address format' });
  }
  const balance = await alchemy.core.getBalance(address);
  res.json({ balance: balance.toString() });
});

// Alchemy Dashboard: restrict API key to specific domains/IPs
// Dashboard > App > Settings > Allowed Domains
```

### Step 2: Input Validation for Blockchain Queries

```typescript
// src/security/validators.ts
import { ethers } from 'ethers';

function validateAddress(input: string): string {
  if (!ethers.isAddress(input)) throw new Error(`Invalid address: ${input}`);
  return ethers.getAddress(input); // Returns checksummed address
}

function validateBlockNumber(input: string | number): string {
  if (input === 'latest' || input === 'pending' || input === 'earliest') return input;
  const num = typeof input === 'string' ? parseInt(input) : input;
  if (isNaN(num) || num < 0) throw new Error(`Invalid block number: ${input}`);
  return `0x${num.toString(16)}`;
}

function validateTokenId(input: string): string {
  if (!/^\d+$/.test(input) && !input.startsWith('0x')) {
    throw new Error(`Invalid token ID: ${input}`);
  }
  return input;
}

export { validateAddress, validateBlockNumber, validateTokenId };
```

### Step 3: Private Key Safety

```typescript
// src/security/wallet-safety.ts
// NEVER:
// - Hardcode private keys in source code
// - Log private keys or mnemonic phrases
// - Store private keys in .env files committed to git
// - Accept private keys from user input in a web app

// Safe wallet setup for server-side operations
import { ethers } from 'ethers';
import { Alchemy, Network } from 'alchemy-sdk';

async function createSafeWallet() {
  const alchemy = new Alchemy({
    apiKey: process.env.ALCHEMY_API_KEY,
    network: Network.ETH_SEPOLIA,
  });

  const provider = await alchemy.config.getProvider();

  // Load private key from secret manager (GCP example)
  const { SecretManagerServiceClient } = await import('@google-cloud/secret-manager');
  const client = new SecretManagerServiceClient();
  const [version] = await client.accessSecretVersion({
    name: `projects/${process.env.GCP_PROJECT}/secrets/deployer-private-key/versions/latest`,
  });
  const privateKey = version.payload?.data?.toString() || '';

  const wallet = new ethers.Wallet(privateKey, provider);
  return wallet;
}
```

### Step 4: Webhook Signature Verification

```typescript
// src/security/webhook-verify.ts
import crypto from 'crypto';

function verifyAlchemyWebhookSignature(
  body: string,
  signature: string,
  signingKey: string,
): boolean {
  const hmac = crypto.createHmac('sha256', signingKey);
  hmac.update(body, 'utf8');
  const expectedSig = hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSig),
  );
}
```

## Output

- API key proxy pattern (never expose to client)
- Input validation for addresses, blocks, and token IDs
- Private key loaded from secret manager
- Webhook HMAC signature verification

## Examples

Deploy the balance proxy in staging with an injected managed provider key, then
send a checksummed test address and an invalid address. The valid request should
return the intended public chain result; the invalid request must be rejected
before the provider call, and neither response may contain a credential. Send
one synthetic signed webhook and one signature mismatch to prove the verifier
accepts only the valid event. If a key appears in a bundle, an invalid signature
is processed, or a private key reaches application memory outside the approved
signing boundary, stop deployment, revoke the affected credential where needed,
and investigate before resuming traffic.

## Error Handling

| Failure | Response |
|---------|----------|
| Provider or private key is exposed | Revoke/rotate it, remove the exposure, audit affected artifacts, and redeploy. |
| Address, block, or token input is invalid | Reject before issuing an RPC or contract request. |
| Webhook signature cannot be verified | Reject and record only safe event metadata for investigation. |
| Server-side signer is unavailable | Fail closed; do not accept a replacement private key from a request or fallback file. |

## Resources

- [Alchemy Security Best Practices](https://www.alchemy.com/docs)
- [Ethers.js Security](https://docs.ethers.org/v6/)
- Web3 Security Checklist

## Next Steps

For production deployment, see `alchemy-prod-checklist`.