k9guard 1.0.0

package/README.md

@@ -0,0 +1,235 @@
+![Banner](https://www.upload.ee/image/18782156/k9guard.png)
+
+[Türkçe Dokümantasyon](docs/tr/README.md)
+
+# K9Guard
+
+A secure, lightweight, and flexible CAPTCHA module for TypeScript/JavaScript projects with cryptographic security and multi-language support.
+
+## Features
+
+- **Cryptographically Secure**: NIST SP 800-90A compliant random generation
+- **Multi-Language Support**: English and Turkish locales for riddles and logic questions
+- **9 CAPTCHA Types**: Math, text, riddle, sequence, scramble, logic, reverse, mixed, and multi-step challenges
+- **Security First**: SHA-256 salted hashing, nonce-based session management, and 5-minute expiry
+- **Input Validation**: Length limits, type checking, and sanitization to prevent injection attacks
+- **Custom Questions**: Support for your own questions with validation and sanitization
+- **Zero Dependencies**: Lightweight with no external dependencies
+- **Well Tested**: Comprehensive test coverage including edge cases and security scenarios
+- **OWASP Compliant**: Follows OWASP Top 10 security guidelines
+- **Privacy Compliant**: GDPR/KVKK compliant with no personal data storage
+
+## Installation
+
+```bash
+npm install k9guard
+```
+
+## Quick Start
+
+```typescript
+import K9Guard from "k9guard";
+
+const captcha = new K9Guard({
+  type: 'math',
+  difficulty: 'medium',
+  locale: 'en'
+});
+
+// generate a challenge
+const challenge = captcha.generate();
+console.log(challenge.question); // "15 + 7"
+
+// validate user answer
+const isValid = captcha.validate(challenge, "22");
+if (isValid) {
+  console.log("Access granted!");
+} else {
+  console.log("Wrong answer!");
+}
+```
+
+## Usage Examples
+
+### Math CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'math', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Output: "5 + 3"
+// Answer: "8"
+```
+
+### Text CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'text', difficulty: 'medium' });
+const challenge = captcha.generate();
+// Output: "aB2xY9"
+// Answer: "aB2xY9"
+```
+
+### Riddle CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'riddle', difficulty: 'easy', locale: 'en' });
+const challenge = captcha.generate();
+// Output: "What has keys but can't open locks?"
+// Answer: "piano"
+```
+
+### Sequence CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'sequence', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Output: "2, 4, 6, ?"
+// Answer: "8"
+```
+
+### Scramble CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'scramble', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Output: "tac"
+// Answer: "cat"
+```
+
+### Logic CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'logic', difficulty: 'easy', locale: 'en' });
+const challenge = captcha.generate();
+// Output: "Water is dry. True or False?"
+// Answer: "false"
+```
+
+### Reverse CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'reverse', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Output: "god"
+// Answer: "dog"
+```
+
+### Mixed CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'mixed', difficulty: 'medium' });
+const challenge = captcha.generate();
+// Randomly picks one of the above types
+```
+
+### Multi-Step CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'multi', difficulty: 'easy' });
+const challenge = captcha.generate();
+
+if (challenge.steps) {
+  // user must solve both steps
+  const answers = challenge.steps.map(step => step.answer.toString());
+  const userInput = JSON.stringify(answers);
+  const isValid = captcha.validate(challenge, userInput);
+}
+```
+
+### Custom Questions
+
+```typescript
+const captcha = new K9Guard({
+  type: 'custom',
+  questions: [
+    { question: 'What is the capital of France?', answer: 'paris', difficulty: 'easy' },
+    { question: 'What is 2+2?', answer: '4', difficulty: 'easy' },
+    { question: 'What color is the sky?', answer: 'blue', difficulty: 'easy' }
+  ]
+});
+
+const challenge = captcha.generate();
+const isValid = captcha.validate(challenge, "paris");
+```
+
+## API Reference
+
+### Constructor Options
+
+#### Standard CAPTCHA Options
+
+```typescript
+interface K9GuardOptions {
+  type: 'math' | 'text' | 'riddle' | 'sequence' | 'scramble' | 'logic' | 'reverse' | 'mixed' | 'multi';
+  difficulty: 'easy' | 'medium' | 'hard';
+  locale?: 'en' | 'tr'; // default: 'en'
+}
+```
+
+#### Custom CAPTCHA Options
+
+```typescript
+interface K9GuardCustomOptions {
+  type: 'custom';
+  questions: CustomQuestion[];
+}
+
+interface CustomQuestion {
+  question: string; // 5-500 characters
+  answer: string; // 1-200 characters
+  difficulty: 'easy' | 'medium' | 'hard';
+}
+```
+
+### Methods
+
+#### `generate(): CaptchaChallenge`
+
+Generates a new CAPTCHA challenge with unique nonce, expiry time, and hashed answer.
+
+```typescript
+const challenge = captcha.generate();
+console.log(challenge.question); // the question to show user
+console.log(challenge.nonce); // unique session identifier
+console.log(challenge.expiry); // timestamp when challenge expires
+```
+
+#### `validate(challenge: CaptchaChallenge, userInput: string): boolean`
+
+Validates user input against the challenge. Returns `true` if correct, `false` otherwise.
+
+```typescript
+const isValid = captcha.validate(challenge, userAnswer);
+```
+
+## Testing
+
+Run the included test suite:
+
+```bash
+bun run src/test.ts
+```
+
+Tests include:
+- All CAPTCHA types with correct/incorrect/edge case inputs
+- Custom question validation
+- Locale switching
+- Multi-step challenges
+- Input sanitization
+- Security validations
+
+## Contributing
+
+We welcome contributions! Here's how you can help:
+
+1. **Fork the repository**
+2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
+3. **Add tests** for your changes
+4. **Run tests**: `bun run src/test.ts`
+5. **Commit your changes**: `git commit -m 'feat: add amazing feature'`
+6. **Push to branch**: `git push origin feature/amazing-feature`
+7. **Open a Pull Request**
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/docs/tr/README.md

@@ -0,0 +1,235 @@
+![Banner](https://www.upload.ee/image/18782156/k9guard.png)
+
+[English Documentation](../../README.md)
+
+# K9Guard
+
+TypeScript/JavaScript projeleri için kriptografik güvenlik ve çok dilli destek sunan güvenli, hafif ve esnek bir CAPTCHA modülü.
+
+## Özellikler
+
+- **Kriptografik Güvenlik**: NIST SP 800-90A standardına uyumluluk sağlanmıştır
+- **Çok Dilli Destek**: Bulmaca ve mantık soruları için İngilizce ve Türkçe dil desteği mevcuttur
+- **9 CAPTCHA Türü**: Matematik, metin, bulmaca, dizi, karıştırma, mantık, ters çevirme, karma ve çok adımlı doğrulama yöntemleri
+- **Güvenlik Odaklı**: SHA-256 tuzlu hash algoritması, nonce tabanlı oturum yönetimi ve 5 dakikalık geçerlilik süresi
+- **Girdi Doğrulama**: Enjeksiyon saldırılarını önlemek için uzunluk sınırlamaları, tip kontrolü ve sanitizasyon
+- **Özel Sorular**: Doğrulama ve sanitizasyon ile kendi sorularınızı tanımlama desteği
+- **Sıfır Bağımlılık**: Harici bağımlılık gerektirmeyen hafif yapı
+- **Kapsamlı Test Edilmiş**: Uç durumlar ve güvenlik senaryoları dahil olmak üzere geniş test kapsama alanı
+- **OWASP Uyumlu**: OWASP Top 10 güvenlik yönergelerine uygun geliştirme
+- **Gizlilik Uyumlu**: Kişisel veri saklamayan GDPR/KVKK uyumlu mimari
+
+## Kurulum
+
+```bash
+npm install k9guard
+```
+
+## Hızlı Başlangıç
+
+```typescript
+import K9Guard from "k9guard";
+
+const captcha = new K9Guard({
+  type: 'math',
+  difficulty: 'medium',
+  locale: 'tr'
+});
+
+// doğrulama sorusu oluştur
+const challenge = captcha.generate();
+console.log(challenge.question); // "15 + 7"
+
+// kullanıcı yanıtını doğrula
+const isValid = captcha.validate(challenge, "22");
+if (isValid) {
+  console.log("Erişim izni verildi!");
+} else {
+  console.log("Yanlış cevap!");
+}
+```
+
+## Kullanım Örnekleri
+
+### Matematik CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'math', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Çıktı: "5 + 3"
+// Cevap: "8"
+```
+
+### Metin CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'text', difficulty: 'medium' });
+const challenge = captcha.generate();
+// Çıktı: "aB2xY9"
+// Cevap: "aB2xY9"
+```
+
+### Bulmaca CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'riddle', difficulty: 'easy', locale: 'tr' });
+const challenge = captcha.generate();
+// Çıktı: "Tuşları vardır ama kilit açamaz. Nedir?"
+// Cevap: "piyano"
+```
+
+### Dizi CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'sequence', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Çıktı: "2, 4, 6, ?"
+// Cevap: "8"
+```
+
+### Karıştırma CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'scramble', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Çıktı: "iked"
+// Cevap: "kedi"
+```
+
+### Mantık CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'logic', difficulty: 'easy', locale: 'tr' });
+const challenge = captcha.generate();
+// Çıktı: "Su kuru bir maddedir. Doğru mu Yanlış mı?"
+// Cevap: "yanlış"
+```
+
+### Ters Çevirme CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'reverse', difficulty: 'easy' });
+const challenge = captcha.generate();
+// Çıktı: "köpek"
+// Cevap: "kepök"
+```
+
+### Karma CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'mixed', difficulty: 'medium' });
+const challenge = captcha.generate();
+// Yukarıdaki türlerden birini rastgele seçer
+```
+
+### Çok Adımlı CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'multi', difficulty: 'easy' });
+const challenge = captcha.generate();
+
+if (challenge.steps) {
+  // kullanıcı her iki adımı da çözmelidir
+  const answers = challenge.steps.map(step => step.answer.toString());
+  const userInput = JSON.stringify(answers);
+  const isValid = captcha.validate(challenge, userInput);
+}
+```
+
+### Özel Sorular
+
+```typescript
+const captcha = new K9Guard({
+  type: 'custom',
+  questions: [
+    { question: 'Türkiye\'nin başkenti neresidir?', answer: 'ankara', difficulty: 'easy' },
+    { question: '2+2 işleminin sonucu nedir?', answer: '4', difficulty: 'easy' },
+    { question: 'Gökyüzü ne renktir?', answer: 'mavi', difficulty: 'easy' }
+  ]
+});
+
+const challenge = captcha.generate();
+const isValid = captcha.validate(challenge, "ankara");
+```
+
+## API Referansı
+
+### Yapıcı Metod Seçenekleri
+
+#### Standart CAPTCHA Seçenekleri
+
+```typescript
+interface K9GuardOptions {
+  type: 'math' | 'text' | 'riddle' | 'sequence' | 'scramble' | 'logic' | 'reverse' | 'mixed' | 'multi';
+  difficulty: 'easy' | 'medium' | 'hard';
+  locale?: 'en' | 'tr'; // varsayılan: 'en'
+}
+```
+
+#### Özel CAPTCHA Seçenekleri
+
+```typescript
+interface K9GuardCustomOptions {
+  type: 'custom';
+  questions: CustomQuestion[];
+}
+
+interface CustomQuestion {
+  question: string; // 5-500 karakter arası
+  answer: string; // 1-200 karakter arası
+  difficulty: 'easy' | 'medium' | 'hard';
+}
+```
+
+### Metotlar
+
+#### `generate(): CaptchaChallenge`
+
+Benzersiz nonce, geçerlilik süresi ve hash'lenmiş cevap içeren yeni bir CAPTCHA doğrulaması oluşturur.
+
+```typescript
+const challenge = captcha.generate();
+console.log(challenge.question); // kullanıcıya gösterilecek soru
+console.log(challenge.nonce); // benzersiz oturum tanımlayıcısı
+console.log(challenge.expiry); // doğrulamanın geçerlilik süresi sona erme zamanı
+```
+
+#### `validate(challenge: CaptchaChallenge, userInput: string): boolean`
+
+Kullanıcı girdisini doğrulama ile karşılaştırır. Doğruysa `true`, yanlışsa `false` değeri döndürür.
+
+```typescript
+const isValid = captcha.validate(challenge, userAnswer);
+```
+
+## Test Etme
+
+Dahil edilen test paketini çalıştırın:
+
+```bash
+bun run src/test.ts
+```
+
+Testler şunları içerir:
+- Tüm CAPTCHA türleri için doğru/yanlış/uç durum girdileri
+- Özel soru doğrulama senaryoları
+- Dil değiştirme işlemleri
+- Çok adımlı doğrulamalar
+- Girdi sanitizasyonu
+- Güvenlik doğrulamaları
+
+## Katkıda Bulunma
+
+Katkılarınızı memnuniyetle karşılıyoruz! Nasıl yardımcı olabilirsiniz:
+
+1. **Depoyu fork edin**
+2. **Özellik dalı oluşturun**: `git checkout -b feature/harika-ozellik`
+3. **Değişiklikleriniz için testler ekleyin**
+4. **Testleri çalıştırın**: `bun run src/test.ts`
+5. **Değişikliklerinizi commit edin**: `git commit -m 'feat: harika özellik eklendi'`
+6. **Dalınıza push edin**: `git push origin feature/harika-ozellik`
+7. **Pull Request oluşturun**
+
+## Lisans
+
+Bu proje MIT Lisansı altında lisanslanmıştır. Detaylar için [LICENSE](LICENSE) dosyasını inceleyebilirsiniz.

package/index.ts

@@ -0,0 +1,4 @@
+export { K9Guard as default } from './src/K9Guard';
+export * from './src/types';
+export { CustomQuestionValidator } from './src/validators/customQuestionValidator';
+export { CustomQuestionGenerator } from './src/utils/customQuestionGenerator';

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "k9guard",
+  "version": "1.0.0",
+  "description": "A secure, lightweight, and flexible CAPTCHA module for TypeScript/JavaScript projects with cryptographic security and multi-language support",
+  "main": "index.ts",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "captcha",
+    "security",
+    "cryptography",
+    "typescript",
+    "javascript",
+    "authentication",
+    "verification",
+    "bot-protection",
+    "spam-prevention",
+    "nist",
+    "owasp",
+    "gdpr",
+    "kvkk",
+    "sha256",
+    "multi-language",
+    "i18n",
+    "math-captcha",
+    "riddle-captcha",
+    "logic-captcha",
+    "k9crypt"
+  ],
+  "author": {
+    "name": "K9Crypt",
+    "url": "https://k9crypt.xyz/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/K9Crypt/k9guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/K9Crypt/k9guard/issues"
+  },
+  "homepage": "https://github.com/K9Crypt/k9guard#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/K9Guard.ts

@@ -0,0 +1,83 @@
+import type { K9GuardOptions, K9GuardCustomOptions, CaptchaChallenge, CustomQuestion } from './types';
+import { CaptchaGenerator } from './core/captchaGenerator';
+import { CaptchaValidator } from './core/captchaValidator';
+import { CustomQuestionValidator } from './validators/customQuestionValidator';
+
+export class K9Guard {
+  private options: K9GuardOptions | K9GuardCustomOptions;
+  private generator: CaptchaGenerator;
+
+  constructor(options: K9GuardOptions | K9GuardCustomOptions | { type: 'custom'; questions: CustomQuestion[] } = { type: 'math', difficulty: 'medium' }) {
+    const processedOptions = this.processOptions(options);
+    this.generator = new CaptchaGenerator(processedOptions);
+    this.options = processedOptions;
+  }
+
+  private processOptions(options: unknown): K9GuardOptions | K9GuardCustomOptions {
+    if (typeof options !== 'object' || options === null) {
+      return { type: 'math', difficulty: 'medium', locale: 'en' };
+    }
+
+    const opt = options as Record<string, unknown>;
+
+    if (opt.type === 'custom') {
+      if (!Array.isArray(opt.questions)) {
+        throw new Error('Custom type requires questions array');
+      }
+
+      const validation = CustomQuestionValidator.validate(opt.questions);
+      if (!validation.valid) {
+        throw new Error(`Invalid custom questions: ${validation.error}`);
+      }
+
+      return {
+        type: 'custom',
+        questions: CustomQuestionValidator.sanitize(opt.questions as CustomQuestion[])
+      } as K9GuardCustomOptions;
+    }
+
+    return {
+      type: opt.type || 'math',
+      difficulty: opt.difficulty || 'medium',
+      locale: opt.locale || 'en'
+    } as K9GuardOptions;
+  }
+
+  generate(): CaptchaChallenge {
+    return this.generator.generate();
+  }
+
+  validate(challenge: CaptchaChallenge, userInput: string): boolean {
+    if (!this.isValidChallenge(challenge)) {
+      return false;
+    }
+
+    if (typeof userInput !== 'string') {
+      return false;
+    }
+
+    const now = Date.now();
+    if (now > challenge.expiry) {
+      return false;
+    }
+
+    return CaptchaValidator.validate(challenge, userInput);
+  }
+
+  private isValidChallenge(challenge: unknown): boolean {
+    if (typeof challenge !== 'object' || challenge === null) {
+      return false;
+    }
+
+    const c = challenge as Record<string, unknown>;
+
+    return (
+      typeof c.type === 'string' &&
+      typeof c.question === 'string' &&
+      typeof c.nonce === 'string' &&
+      typeof c.expiry === 'number' &&
+      typeof c.hashedAnswer === 'string' &&
+      typeof c.salt === 'string'
+    );
+  }
+}