@usewayn/checkpoint

Wayn Checkpoint

DDOS protection middleware for Express.js and React applications using Proof-of-Work (PoW) challenges. Similar to Cloudflare's "Checking your browser" page, Wayn Checkpoint protects your applications from automated attacks and spam.

Features

• 🛡️ DDOS Protection: Proof-of-Work challenges that are expensive for bots but easy for humans
• 🚀 Easy Integration: Works with Express.js and React applications
• ⚡ Customizable: Configurable difficulty, duration, and appearance
• 🔒 Secure: JWT-based verification with configurable expiration
• 📱 Universal: Works in all modern browsers
• 🎨 Customizable UI: Override the default checkpoint page template
• 🔧 Rate Limiting: Built-in rate limiting for additional protection

Installation

npm install @usewayn/checkpoint

Quick Start

Express.js

const express = require('express');
const { createCheckpoint } = require('@usewayn/checkpoint');

const app = express();

// Protect all routes with checkpoint
app.use(createCheckpoint({
  secret: 'your-secret-key-here',
  questionCount: 5,
  questionHardness: 5,
  jwtTtlHours: 24
}));

app.get('/', (req, res) => {
  res.send('Hello, verified human!');
});

app.listen(3000);

React

import React from 'react';
import { CheckpointProvider } from '@usewayn/checkpoint';

function App() {
  return (
    <CheckpointProvider
      config={{
        questionCount: 5,
        questionHardness: 5,
        jwtTtlHours: 24,
        apiEndpoint: '/__wayn_checkpoint'
      }}
    >
      <div>
        <h1>Protected App</h1>
        <p>Only verified users can see this content.</p>
      </div>
    </CheckpointProvider>
  );
}

export default App;

How It Works

• Request Interception: When a user visits your protected application, the middleware intercepts the request
• Token Check: Checks for a valid verification token (JWT cookie)
• Challenge Page: If no valid token exists, serves a PoW challenge page
• Proof-of-Work: User's browser automatically solves computational puzzles
• Verification: Solution is verified server-side and a JWT token is issued
• Access Granted: User is redirected to the original destination with the verification token

Configuration Options

Option	Type	Default	Description
secret	string	Required	JWT secret key for signing tokens
questionCount	number	5	Number of PoW challenges to solve
questionHardness	number	5	Difficulty level (higher = more computation)
jwtTtlHours	number	24	JWT token validity in hours
apiEndpoint	string	/__wayn_checkpoint	API endpoint for challenges
cookieName	string	__wayn-clarification	Name of the verification cookie
excludePaths	string[]	[]	Paths to exclude from protection
customTemplate	string	undefined	Custom HTML template for checkpoint page
debug	boolean	false	Enable debug logging
rateLimit	object	See below	Rate limiting configuration

Rate Limiting Options

rateLimit: {
  windowMs: 15 * 60 * 1000,  // Time window in milliseconds
  maxAttempts: 5             // Max attempts per window
}

API Reference

Express Middleware

createCheckpoint(config: CheckpointConfig)

Creates an Express middleware function that protects routes with PoW challenges.

import { createCheckpoint } from '@usewayn/checkpoint';

const middleware = createCheckpoint({
  secret: 'your-secret-key',
  questionCount: 5,
  questionHardness: 5
});

app.use(middleware);

WaynCheckpoint Class

For more advanced usage, you can use the WaynCheckpoint class directly:

import { WaynCheckpoint } from '@usewayn/checkpoint';

const checkpoint = new WaynCheckpoint({
  secret: 'your-secret-key',
  questionCount: 5,
  questionHardness: 5
});

app.use(checkpoint.middleware());

React Components

CheckpointProvider

React context provider that protects child components:

import { CheckpointProvider } from '@usewayn/checkpoint';

<CheckpointProvider config={config}>
  <App />
</CheckpointProvider>

withCheckpoint(Component, config)

Higher-order component that wraps a component with checkpoint protection:

import { withCheckpoint } from '@usewayn/checkpoint';

const ProtectedApp = withCheckpoint(App, { config });

useCheckpoint(config)

React hook for checkpoint verification status:

import { useCheckpoint } from '@usewayn/checkpoint';

function MyComponent() {
  const { isVerified, isLoading, error } = useCheckpoint(config);
  
  if (isLoading) return <div>Checking...</div>;
  if (!isVerified) return <div>Verification required</div>;
  
  return <div>Protected content</div>;
}

Security Considerations

• Secret Key: Use a strong, random secret key and keep it secure
• HTTPS: Always use HTTPS in production to protect tokens in transit
• Rate Limiting: Configure appropriate rate limits for your use case
• Difficulty Tuning: Balance security vs. user experience when setting difficulty
• Token Expiration: Set appropriate JWT expiration times

Examples

See examples.md for more detailed usage examples.

Architecture

Wayn Checkpoint consists of:

• Server Component (@usewayn/server): Generates and verifies PoW challenges
• Widget Component (@usewayn/widget): Browser-side PoW solver
• Checkpoint Middleware: Express middleware and React components

Performance

• Client Impact: Minimal - challenges are solved using Web Workers
• Server Impact: Low - stateless verification with JWT tokens
• Network: Small overhead - only challenge data and solutions transmitted

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

Related Projects

• @usewayn/server - Server-side PoW verification
• @usewayn/widget - Browser-side PoW solver widget

Support

For support, please open an issue on GitHub or contact the maintainers.