nastaliq-captcha

Generate CAPTCHA images using random numbers spelled out in Persian (Farsi) words, rendered in the Nastaliq script with randomized colors, noise, and rotation to resist OCR.

Note: This README assumes the package is published as nastaliq-captcha. Adjust the install command below if your package.json uses a different name.

Features

• 🔢 Random number generated with crypto.randomInt (cryptographically secure, not predictable)
• 🖋 Rendered as Persian words in the Nastaliq font, not digits — harder for digit-based OCR to crack
• 🎨 Randomized background/foreground colors with a built-in contrast check, so the text never becomes unreadable
• 🌪 Visual noise: scattered dots + interference lines to defeat naive image-based bots
• 📐 Auto-fitting font size and slight random rotation for additional distortion
• 🖼 Outputs a plain PNG Buffer — works with any web framework

Installation

npm install nastaliq-captcha

This package depends on canvas for image rendering, which uses native bindings. On most systems this installs automatically via npm install, but if you hit build errors, see node-canvas's platform-specific setup guide (Cairo/Pango system libraries are required on Linux/macOS).

Quick start

import { NastaliqCaptcha } from "nastaliq-captcha";

const captcha = new NastaliqCaptcha();

const { image, answer } = captcha.generate();
// image  -> PNG Buffer, send this to the client
// answer -> Number, e.g. 419

Custom dimensions

const { image, answer } = captcha.generate({
  width: 240,
  height: 80,
  difficulty: 5,
});

Both width and height are optional and independently default to 200 and 60 respectively.

⚠️ Important: handling the answer securely

generate() returns both the rendered image and the number answer in the same object. This is intentional — the package itself doesn't assume how you store sessions — but it means the calling code is responsible for keeping answer away from the client.

If you send the full { image, answer } object straight back in an API response, the CAPTCHA provides no protection at all: anyone can read the answer directly out of the response body without ever looking at the image.

✅ Correct usage pattern

Generate the challenge, store the answer server-side (session, cache, or database) keyed by some challenge ID, and send only the image to the client:

import { NastaliqCaptcha } from "nastaliq-captcha";
import { randomUUID } from "crypto";

const captcha = new NastaliqCaptcha();

// --- On challenge creation (e.g. GET /captcha) ---
app.get("/captcha", (req, res) => {
  const { image, answer } = captcha.generate();
  const challengeId = randomUUID();

  // Store server-side only — e.g. in Redis, a session store, or a short-lived DB row.
  // Example using an in-memory session for illustration:
  req.session.captcha = { id: challengeId, answer };

  res.set("Content-Type", "image/png");
  res.json({
    challengeId,
    image: image.toString("base64"), // or stream the Buffer directly
  });
});

// --- On verification (e.g. POST /captcha/verify) ---
app.post("/captcha/verify", (req, res) => {
  const { challengeId, userAnswer } = req.body;
  const stored = req.session.captcha;

  if (!stored || stored.id !== challengeId) {
    return res.status(400).json({ valid: false, reason: "Challenge expired or not found" });
  }

  const valid = stored.answer === userAnswer;
  delete req.session.captcha; // one-time use

  res.json({ valid });
});

❌ Avoid this

// DON'T: ships the answer to the client alongside the image.
app.get("/captcha", (req, res) => {
  const { image, answer } = captcha.generate();
  res.json({ image: image.toString("base64"), answer }); // anyone can read `answer` here
});

API

new NastaliqCaptcha()

Creates a new CAPTCHA generator instance. No configuration needed at construction time.

.generate(config?)

Generates a new random challenge and renders it as an image.

| Param | Type | Default | Description | | ------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | config.width | number | 200 | Output image width in pixels | | config.height | number | 60 | Output image height in pixels | | config.difficulty | number | 5 | Visual distortion level from 0 (minimal noise) to 10 (maximum noise). Controls the density of interference dots and lines, and the degree of text rotation. |

Returns { image: Buffer; answer: string }

| Field | Type | Description | | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | image | Buffer | PNG image buffer | | answer | number | The correct answer (e.g. 23). Handle this server-side only — see security section above. |

How it works

1. CaptchaCore picks a random number and converts it to Persian words via numberToPersian().
2. CanvasRenderer draws that text onto a canvas with a randomized, contrast-checked color pair, adds noise (dots + curved lines), fits the font size to the canvas, and applies a slight random rotation before exporting a PNG buffer.
3. NastaliqCaptcha ties the two together and exposes the single generate() entry point.

NastaliqCaptcha.generate()
  ├─ CaptchaCore.create()        → { answer, raw }
  └─ CanvasRenderer.render()     → PNG Buffer

Testing

npm install -D jest ts-jest @types/jest typescript @types/node
npx jest

Tests mock the native canvas dependency, so the suite runs without needing Cairo/Pango or the Nastaliq font file installed.

Requirements

• Node.js (with crypto.randomInt support — Node 14.10+)
• A Nastaliq-compatible .ttf font file at src/assets/fonts/nastaliq.ttf (bundled with the package)

License

Nastaliq CAPTCHA is source-available package. The source code is publicly visible for transparency and contribution purposes, but redistribution, derivative works, and competing products are prohibited without permission.