@cordonhq/guard-node

Application-layer traffic protection for any Node service. @cordonhq/guard-node connects your app to CORDON, a traffic firewall that evaluates every incoming request in real time and lets your application respond only to legitimate visitors — automated, abusive, or unverified traffic is blocked with a safe response.

No reverse proxy and no DNS change: the classification engine runs on CORDON's servers, and this SDK is a thin client that forwards each request's context, receives a decision (allow / verify / block), and enforces it for you.

Install

npm install @cordonhq/guard-node

Create a protection in the dashboard, copy its API key, and set it in your server environment:

CORDON_GUARD_KEY=gk_live_…

Next.js

// middleware.ts
import { NextResponse } from 'next/server';
import { createGuard } from '@cordonhq/guard-node';

const guard = createGuard({
  apiKey: process.env.CORDON_GUARD_KEY!,
  baseUrl: 'https://guard.cordon.cc',
});

export const middleware = guard.middleware(NextResponse);
export const config = { matcher: ['/', '/pricing/:path*'] };

Express

import express from 'express';
import { createGuard } from '@cordonhq/guard-node';

const guard = createGuard({ apiKey: process.env.CORDON_GUARD_KEY!, baseUrl: 'https://guard.cordon.cc' });

const app = express();
app.set('trust proxy', 1); // so the real client IP is read, not your proxy's
app.use(guard.express());

The client IP is the one thing to get right

CORDON evaluates whatever IP you send. Behind a CDN or load balancer, derive the visitor's real IP from x-forwarded-for — a wrong IP silently voids every IP, geo, and network rule. The adapters use getClientIp() for you; set trustedHops to the number of proxies you run if you're behind more than the platform's own.

Options

| Option | Default | | | --- | --- | --- | | apiKey | — | Your protection's API key. Server-side only. | | baseUrl | — | The CORDON API base URL. | | failMode | 'open' | 'open' serves the request if CORDON is unreachable; 'closed' blocks. | | timeoutMs | 500 | Per-request timeout for the API call. |

Decisions are cached in a signed, per-visitor cookie for the decision's lifetime, so only the first request in a session makes an API call.