altcha-lib 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Daniel Regeci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# ALTCHA JS Library
+
+ALTCHA JS Library is a lightweight, zero-dependency library designed for creating and verifying [ALTCHA](https://altcha.org) challenges specifically tailored for Node.js, Bun, and Deno environments.
+
+## Compatibility
+
+This library utilizes [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) and is intended for server-side use.
+
+- Node.js 16+
+- Bun 1+
+- Deno 1+
+
+## Usage
+
+```ts
+import { createChallenge, verifySolution } from 'altcha-lib';
+
+const hmacKey = 'secret hmac key';
+
+// Create a new challenge and send it to the client:
+const challenge = await createChallenge({
+  hmacKey,
+});
+
+// When submitted, verify the payload:
+const ok = await verifySolution(payload, hmacKey);
+```
+
+## API
+
+### `createChallenge(options)`
+
+Creates a new challenge for ALTCHA.
+
+Parameters:
+
+- `options: ChallengeOptions`:
+  - `algorithm?: string`: Algorithm to use (`SHA-1`, `SHA-256`, `SHA-512`, default: `SHA-256`).
+  - `hmacKey: string` (required): Signature HMAC key.
+  - `number?: number`: Optional number to use. If not provided, a random number will be generated.
+  - `salt?: string`: Optional salt string. If not provided, a random salt will be generated.
+
+### `verifySolution(payload, hmacKey)`
+
+Verifies an ALTCHA solution. The payload can be a Base64-encoded JSON payload (as submitted by the widget) or an object.
+
+Parameters:
+
+- `payload: string | Payload`
+- `hmacKey: string`
+
+## License
+
+MIT

package/dist/helpers.d.ts

@@ -0,0 +1,6 @@
+import type { Algorithm } from './types.js';
+export declare function ab2hex(ab: ArrayBuffer | Uint8Array): string;
+export declare function hash(algorithm: Algorithm, str: string): Promise<string>;
+export declare function hmac(algorithm: Algorithm, str: string, secret: string): Promise<string>;
+export declare function randomBytes(length: number): Uint8Array;
+export declare function randomInt(max: number): number;

package/dist/helpers.js

@@ -0,0 +1,31 @@
+const encoder = new TextEncoder();
+if (!('crypto' in globalThis)) {
+    // @ts-ignore
+    globalThis.crypto = (await import('node:crypto')).webcrypto;
+}
+export function ab2hex(ab) {
+    return [...new Uint8Array(ab)]
+        .map((x) => x.toString(16).padStart(2, '0'))
+        .join('');
+}
+export async function hash(algorithm, str) {
+    return ab2hex(await crypto.subtle.digest(algorithm.toUpperCase(), encoder.encode(str)));
+}
+export async function hmac(algorithm, str, secret) {
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), {
+        name: 'HMAC',
+        hash: algorithm,
+    }, false, ['sign', 'verify']);
+    return ab2hex(await crypto.subtle.sign('HMAC', key, encoder.encode(str)));
+}
+export function randomBytes(length) {
+    const ab = new Uint8Array(length);
+    crypto.getRandomValues(ab);
+    return ab;
+}
+export function randomInt(max) {
+    const ab = new Uint32Array(1);
+    crypto.getRandomValues(ab);
+    const randomNumber = ab[0] / (0xffffffff + 1);
+    return Math.floor(randomNumber * max + 1);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Challenge, ChallengeOptions, Payload } from './types.js';
+export declare function createChallenge(options: ChallengeOptions): Promise<Challenge>;
+export declare function verifySolution(payload: string | Payload, hmacKey: string): Promise<boolean>;

package/dist/index.js

@@ -0,0 +1,28 @@
+import { ab2hex, hash, hmac, randomBytes, randomInt } from './helpers.js';
+const DEFAULT_MAX_NUMBER = 1e7;
+const DEFAULT_ALG = 'SHA-256';
+export async function createChallenge(options) {
+    const algorithm = options.algorithm || DEFAULT_ALG;
+    const salt = options.salt || ab2hex(randomBytes(12));
+    const number = options.number === void 0 ? randomInt(DEFAULT_MAX_NUMBER) : options.number;
+    const challenge = await hash(algorithm, salt + number);
+    return {
+        algorithm,
+        challenge,
+        salt,
+        signature: await hmac(algorithm, challenge, options.hmacKey),
+    };
+}
+export async function verifySolution(payload, hmacKey) {
+    if (typeof payload === 'string') {
+        payload = JSON.parse(atob(payload));
+    }
+    const check = await createChallenge({
+        algorithm: payload.algorithm,
+        hmacKey,
+        number: payload.number,
+        salt: payload.salt,
+    });
+    return (check.challenge === payload.challenge &&
+        check.signature === payload.signature);
+}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+export type Algorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
+export interface Challenge {
+    algorithm: Algorithm;
+    challenge: string;
+    salt: string;
+    signature: string;
+}
+export interface ChallengeOptions {
+    algorithm?: Algorithm;
+    hmacKey: string;
+    number?: number;
+    salt?: string;
+}
+export interface Payload {
+    algorithm: Algorithm;
+    challenge: string;
+    number: number;
+    salt: string;
+    signature: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "altcha-lib",
+  "version": "0.1.0",
+  "description": "A library for creating and verifying ALTCHA challenges for Node.js, Bun and Deno.",
+  "author": "Daniel Regeci",
+  "license": "MIT",
+  "keywords": [
+    "altcha",
+    "captcha",
+    "antispam",
+    "captcha alternative"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "denoify": "rimraf deno_dist && denoify && find deno_dist/. -type f -exec sed -i '' -e 's/node:node:/node:/g' {} +",
+    "eslint": "eslint ./lib/**/*",
+    "format": "prettier --write './(lib|tests)/**/*'",
+    "test": "vitest",
+    "test:deno": "deno test tests/deno.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "types": [
+        "./dist/types"
+      ]
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "denoify": "^1.6.9",
+    "eslint": "^8.56.0",
+    "prettier": "^3.2.5",
+    "rimraf": "^5.0.5",
+    "ts-node": "^10.9.1",
+    "tsx": "^4.0.0",
+    "typescript": "^5.2.2",
+    "vitest": "^1.0.1"
+  }
+}