IronWall SDK

The official client-side SDK for the IronWall Protocol.

IronWall is a Proof-of-Work (PoW) rate-limiting protocol designed to protect high-value API endpoints (AI generation, Auth, SMS triggers) from automated abuse.

Instead of challenging the user's humanity (CAPTCHA), IronWall challenges the device's computational capacity. It forces clients to solve a cryptographic puzzle (Argon2) before their request is accepted by the backend.

🛡️ Security & Privacy Promise

• NOT A CRYPTO MINER: This library calculates a single hash for authentication purposes only. It runs for approximately 1–2 seconds and then stops.
• Zero Tracking: No cookies, no fingerprinting, no data collection.
• Open Source: This repository is open for audit to ensure compliance and safety.

📦 Installation

Option A: NPM (Recommended)

Perfect for React, Next.js, Vue, and modern stacks.

npm install ironwall-sdk

Option B: CDN

Perfect for Vanilla HTML/JS projects.

<script src="https://ironwall-backend.vercel.app/dist/ironwall.min.js"></script>

🚀 Usage

1. Configuration

Initialize the SDK once in your application's entry point (e.g., App.tsx or layout.js).

import { IronWall } from 'ironwall-sdk';

IronWall.configure({
  apiKey: 'iw_live_YOUR_PUBLIC_KEY', // Get this from the Dashboard
  debug: false // Set to true to see logs in console
});

2. Guarding an Action

Call guard() before performing a sensitive action. This function is asynchronous and will pause execution until the puzzle is solved.

const handleLogin = async () => {
  try {
    // 1. Pause execution until Proof-of-Work is complete (~1–2s)
    const passport = await IronWall.guard();

    // 2. IronWall Proxy automatically validates the request at the edge.
    // If you are using your own backend, send the passport in headers:
    // headers: { 'x-ironwall-passport': passport }

    await api.post('/login', { username, password });

  } catch (error) {
    // Handle rejection (e.g., User closed tab, or Bot detected)
    console.error("Access Denied", error);
  }
};

🧩 Error Handling

| Error Code | Description | Mitigation | |------------------|-------------------------------------------------------------------|---------------------------------| | IRONWALL_BLOCK | Request blocked by security policy (Geo-Fencing or IP Reputation) | Check Dashboard Settings | | PAYMENT_REQUIRED | Monthly request quota exceeded | Upgrade plan in Billing | | 401_UNAUTHORIZED | Invalid or missing API Key | Verify IronWall.configure() key | | TIMEOUT | Puzzle took too long (>60s) | Client device under heavy load |

📄 License

MIT.