ethiopian-captcha 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# EthiopianCaptcha 🇪🇹
+
+A lightweight, secure, and extensible CAPTCHA library designed for Ethiopian languages (starting with Amharic Fidel).
+
+EthiopianCaptcha provides:
+
+- Server-side CAPTCHA generation & validation
+- Secure hashed answers (no plaintext storage)
+- TTL & attempt limiting
+- Optional React UI component
+- Zero external dependencies
+
+---
+
+## Features
+
+- 🇪🇹 Amharic (Fidel) CAPTCHA support
+- Hashed answers (security-first)
+- Configurable expiration (TTL)
+- Attempt limiting
+- Optional React component
+
+---
+
+## Installation
+
+```bash
+npm install ethiopian-captcha
+```
+
+---
+
+## Server-side Usage (Node.js)
+
+```js
+import { generateCaptcha, validateCaptcha } from "ethiopian-captcha";
+
+// Generate captcha
+const captchaData = generateCaptcha();
+
+console.log(captchaData);
+/*
+{
+  success: true,
+  type: "fidel",
+  captchaId: "ETH-...",
+  captcha: ["ኩ", "ቴ", "ኃ", "ሀ"]
+}
+*/
+
+// Validate captcha
+const result = validateCaptcha(captchaData.captchaId, "ኩቴኃሀ");
+
+if (result.success) {
+  console.log("Captcha verified");
+} else {
+  console.log(result.message);
+}
+```
+
+---
+
+## React Component (Optional)
+
+```jsx
+import { EtCaptcha } from "ethiopian-captcha/react";
+
+<EtCaptcha
+  captcha={captcha}
+  captchaId={captchaId}
+  loading={loading}
+  onRefresh={fetchNewCaptcha}
+  onVerify={({ captchaId, input }) => {
+    validateCaptcha({ captchaId, input });
+  }}
+/>;
+```
+
+The React component:
+
+- Does NOT handle validation logic
+- Does NOT make HTTP requests
+- Is fully controlled by props
+
+---
+
+## Configuration
+
+```js
+export const captchaConfig = {
+  type: "fidel",
+  count: 4,
+  ttl: 2 * 60 * 1000,
+  attempts: 3,
+};
+```
+
+---
+
+## Security Notes
+
+- Answers are stored as hashes
+- Captchas auto-expire
+- Entries are removed after success or failure
+- In-memory storage (stateless & fast)
+
+⚠️ For distributed systems, use Redis or a shared store.
+
+---
+
+## Roadmap
+
+- Numeric CAPTCHA
+- Mixed-type CAPTCHA
+- Redis adapter
+- TypeScript support
+- Canvas-based CAPTCHA rendering
+
+---
+
+## License
+
+MIT © EthiopianCaptcha

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "ethiopian-captcha",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./react": "./src/react/EtCaptcha.jsx"
+  },
+  "keywords": [
+    "captcha",
+    "ethiopia",
+    "amharic",
+    "fidel",
+    "security"
+  ],
+  "author": "Amenadam Solomon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amenadam/ethiopian-captcha"
+  }
+}

package/src/config/config.js

@@ -0,0 +1,6 @@
+export const captchaConfig = {
+  type: "fidel",
+  count: 4,
+  ttl: 2 * 60 * 1000,
+  maxAttempts: 3,
+};

package/src/constants/amharicLetters.js

@@ -0,0 +1,35 @@
+export const AMHARIC_LETTERS = [
+  'ሀ','ሁ','ሂ','ሃ','ሄ','ህ','ሆ',
+  'ለ','ሉ','ሊ','ላ','ሌ','ል','ሎ',
+  'ሐ','ሑ','ሒ','ሓ','ሔ','ሕ','ሖ',
+  'መ','ሙ','ሚ','ማ','ሜ','ም','ሞ',
+  'ሠ','ሡ','ሢ','ሣ','ሤ','ሥ','ሦ',
+  'ረ','ሩ','ሪ','ራ','ሬ','ር','ሮ',
+  'ሰ','ሱ','ሲ','ሳ','ሴ','ስ','ሶ',
+  'ሸ','ሹ','ሺ','ሻ','ሼ','ሽ','ሾ',
+  'ቀ','ቁ','ቂ','ቃ','ቄ','ቅ','ቆ',
+  'በ','ቡ','ቢ','ባ','ቤ','ብ','ቦ',
+  'ተ','ቱ','ቲ','ታ','ቴ','ት','ቶ',
+  'ቸ','ቹ','ቺ','ቻ','ቼ','ች','ቾ',
+  'ኀ','ኁ','ኂ','ኃ','ኄ','ኅ','ኆ',
+  'ነ','ኑ','ኒ','ና','ኔ','ን','ኖ',
+  'ኘ','ኙ','ኚ','ኛ','ኜ','ኝ','ኞ',
+  'አ','ኡ','ኢ','ኣ','ኤ','እ','ኦ',
+  'ከ','ኩ','ኪ','ካ','ኬ','ክ','ኮ',
+  'ኸ','ኹ','ኺ','ኻ','ኼ','ኽ','ኾ',
+  'ወ','ዉ','ዊ','ዋ','ዌ','ው','ዎ',
+  'ዐ','ዑ','ዒ','ዓ','ዔ','ዕ','ዖ',
+  'ዘ','ዙ','ዚ','ዛ','ዜ','ዝ','ዞ',
+  'ዠ','ዡ','ዢ','ዣ','ዤ','ዥ','ዦ',
+  'የ','ዩ','ዪ','ያ','ዬ','ይ','ዮ',
+  'ደ','ዱ','ዲ','ዳ','ዴ','ድ','ዶ',
+  'ጀ','ጁ','ጂ','ጃ','ጄ','ጅ','ጆ',
+  'ገ','ጉ','ጊ','ጋ','ጌ','ግ','ጎ',
+  'ጠ','ጡ','ጢ','ጣ','ጤ','ጥ','ጦ',
+  'ጨ','ጩ','ጪ','ጫ','ጬ','ጭ','ጮ',
+  'ጰ','ጱ','ጲ','ጳ','ጴ','ጵ','ጶ',
+  'ጸ','ጹ','ጺ','ጻ','ጼ','ጽ','ጾ',
+  'ፀ','ፁ','ፂ','ፃ','ፄ','ፅ','ፆ',
+  'ፈ','ፉ','ፊ','ፋ','ፌ','ፍ','ፎ',
+  'ፐ','ፑ','ፒ','ፓ','ፔ','ፕ','ፖ'
+];

package/src/core/captchaEngine.js

@@ -0,0 +1,79 @@
+import { AMHARIC_LETTERS } from "../constants/amharicLetters.js";
+import { hashAnswer } from "../utils/hash.js";
+import { captchaConfig } from "../config/config.js";
+
+const getRandomLetter = () => {
+  return AMHARIC_LETTERS[Math.floor(Math.random() * AMHARIC_LETTERS.length)];
+};
+
+const getRandomLetters = (count = 4) => {
+  let last = "";
+  let randomLetters = [];
+  for (let i = 0; i < count; i++) {
+    let letter;
+    do {
+      letter = getRandomLetter();
+    } while (letter === last);
+
+    last = letter;
+    randomLetters.push(letter);
+  }
+
+  return randomLetters;
+};
+
+const generatedCaptchas = new Map();
+
+export const generateCaptcha = (
+  type = captchaConfig.type,
+  count = captchaConfig.count
+) => {
+  if (type !== "fidel") {
+    return { success: false, message: "Unsupported captcha type" };
+  }
+
+  const captcha = getRandomLetters(count);
+  const captchaId = `ETH-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+
+  generatedCaptchas.set(captchaId, {
+    answerHash: hashAnswer(captcha.join("")),
+    generatedAt: Date.now(),
+    attempts: 0,
+  });
+
+  return {
+    success: true,
+    type,
+    captchaId,
+    captcha,
+  };
+};
+
+const CAPTCHA_TTL = captchaConfig.ttl;
+const MAX_ATTEMPTS = captchaConfig.attempts;
+export const validateCaptcha = (captchaId, userInput) => {
+  const captcha = generatedCaptchas.get(captchaId);
+
+  if (!captcha) {
+    return { success: false, message: "Invalid Captcha ID" };
+  }
+
+  if (Date.now() - captcha.generatedAt > CAPTCHA_TTL) {
+    generatedCaptchas.delete(captchaId);
+    return { success: false, message: "Captcha expired" };
+  }
+
+  captcha.attempts++;
+  if (captcha.attempts > MAX_ATTEMPTS) {
+    generatedCaptchas.delete(captchaId);
+    return { success: false, message: "Too many attempts" };
+  }
+
+  const inputHash = hashAnswer(userInput.trim());
+  if (inputHash === captcha.answerHash) {
+    generatedCaptchas.delete(captchaId);
+    return { success: true };
+  }
+
+  return { success: false, message: "Incorrect captcha" };
+};

package/src/index.js

@@ -0,0 +1,2 @@
+export { generateCaptcha, validateCaptcha } from "./core/captchaEngine.js";
+export { captchaConfig } from "./config/config.js";

package/src/react/EtCaptcha.jsx

@@ -0,0 +1,68 @@
+import { useState } from "react";
+
+export function EtCaptcha({
+  captcha = [],
+  captchaId,
+  onVerify,
+  onRefresh,
+  loading = false,
+}) {
+  const [input, setInput] = useState("");
+
+  const handleVerify = () => {
+    if (!input.trim()) return;
+
+    onVerify({
+      captchaId,
+      input: input.trim(),
+    });
+  };
+
+  return (
+    <div
+      style={{
+        border: "1px solid #ddd",
+        borderRadius: 8,
+        padding: 16,
+        width: 260,
+        fontFamily: "system-ui, sans-serif",
+      }}
+    >
+      <div
+        style={{
+          fontSize: 24,
+          letterSpacing: 8,
+          textAlign: "center",
+          marginBottom: 12,
+          userSelect: "none",
+        }}
+      >
+        {captcha.join(" ")}
+      </div>
+
+      <input
+        type="text"
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        placeholder="Type the letters"
+        disabled={loading}
+        style={{
+          width: "100%",
+          padding: 8,
+          fontSize: 14,
+          marginBottom: 10,
+        }}
+      />
+
+      <div style={{ display: "flex", gap: 8 }}>
+        <button onClick={handleVerify} disabled={loading} style={{ flex: 1 }}>
+          Verify
+        </button>
+
+        <button onClick={onRefresh} disabled={loading}>
+          ↻
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/utils/hash.js

@@ -0,0 +1,5 @@
+import crypto from "crypto";
+
+export const hashAnswer = (answer) => {
+  return crypto.createHash("sha256").update(answer).digest("hex");
+};