{"id":20365987,"url":"https://github.com/altcha-org/altcha-lib","last_synced_at":"2025-04-05T18:06:28.146Z","repository":{"id":229298626,"uuid":"756450577","full_name":"altcha-org/altcha-lib","owner":"altcha-org","description":"A JavaScript library for creating and verifying ALTCHA challenges.","archived":false,"fork":false,"pushed_at":"2024-12-21T00:44:59.000Z","size":120,"stargazers_count":43,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T17:09:36.933Z","etag":null,"topics":["altcha","captcha","javascript","typescript","webcrypto"],"latest_commit_sha":null,"homepage":"https://altcha.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/altcha-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-12T17:30:40.000Z","updated_at":"2025-03-03T06:20:29.000Z","dependencies_parsed_at":"2024-04-18T13:59:34.410Z","dependency_job_id":"723fed21-cf8f-497d-b288-0da2d88578bd","html_url":"https://github.com/altcha-org/altcha-lib","commit_stats":null,"previous_names":["altcha-org/altcha-lib"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/altcha-org","download_url":"https://codeload.github.com/altcha-org/altcha-lib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378140,"owners_count":20929296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["altcha","captcha","javascript","typescript","webcrypto"],"created_at":"2024-11-15T00:21:41.652Z","updated_at":"2025-04-05T18:06:28.129Z","avatar_url":"https://github.com/altcha-org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ALTCHA JS Library\n\nALTCHA JS Library is a lightweight, zero-dependency library designed for creating and verifying [ALTCHA](https://altcha.org) challenges.\n\n## Compatibility\n\nThis library utilizes [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto).\n\n- Node.js 16+\n- Bun 1+\n- Deno 1+\n- WinterCG-compatible runtimes\n- All modern browsers\n\n## Usage\n\n```ts\nimport { createChallenge, verifySolution } from 'altcha-lib';\n\nconst hmacKey = 'secret hmac key';\n\n// Create a new challenge and send it to the client:\nconst challenge = await createChallenge({\n  hmacKey,\n  maxNumber: 100000, // the maximum random number\n});\n\n// When submitted, verify the payload:\nconst ok = await verifySolution(payload, hmacKey);\n```\n\n### Usage with Node.js 16\n\nIn Node.js version 16, there is no global reference to crypto by default. To use this library, you need to add the following code to your codebase:\n\n```ts\nglobalThis.crypto = require('node:crypto').webcrypto;\n```\n\nOr with `import` syntax:\n\n```ts\nimport { webcrypto } from 'node:crypto';\n\nglobalThis.crypto = webcrypto;\n```\n\n## API\n\n### `createChallenge(options)`\n\nCreates a new challenge for ALTCHA.\n\nParameters:\n\n- `options: ChallengeOptions`:\n  - `algorithm?: string`: Algorithm to use (`SHA-1`, `SHA-256`, `SHA-512`, default: `SHA-256`).\n  - `expires?: Date`: Optional `expires` time (as `Date` set into the future date).\n  - `hmacKey: string` (required): Signature HMAC key.\n  - `maxnumber?: number`: Optional maximum number for the random number generator (defaults to 1,000,000).\n  - `number?: number`: Optional number to use. If not provided, a random number will be generated.\n  - `params?: Record\u003cstring, string\u003e`: Optional parameters to be added to the salt as URL-encoded query string. Use `extractParams()` to read them.\n  - `salt?: string`: Optional salt string. If not provided, a random salt will be generated.\n  - `saltLength?: number`: Optional maximum lenght of the random salt (in bytes, defaults to 12).\n\nReturns: `Promise\u003cChallenge\u003e`\n\n### `extractParams(payload)`\n\nExtracts optional parameters from the challenge or payload.\n\nParameters:\n\n- `payload: string | Payload | Challenge`\n\nReturns: `Record\u003cstring, string\u003e`\n\n### `verifySolution(payload, hmacKey, checkExpires = true)`\n\nVerifies an ALTCHA solution. The payload can be a Base64-encoded JSON payload (as submitted by the widget) or an object.\n\nParameters:\n\n- `payload: string | Payload`\n- `hmacKey: string`\n- `checkExpires: boolean = true`: Whether to perform a check on the optional `expires` parameter. Will return `false` if challenge expired.\n\nReturns: `Promise\u003cboolean\u003e`\n\n### `verifyServerSignature(payload, hmacKey)`\n\nVerifies the server signature returned by the API. The payload can be a Base64-encoded JSON payload or an object.\n\nParameters:\n\n- `payload: string | ServerSignaturePayload`\n- `hmacKey: string`\n\nReturns: `Promise\u003c{ verificationData: ServerSignatureVerificationData | null, verified: boolean }\u003e`\n\n### `verifyFieldsHash(formData, fields, fieldsHash, algorithm?)`\n\nVerifies the hash of form fields returned by the Spam Filter.\n\nParameters:\n\n- `formData: FormData | Record\u003cstring, unknown\u003e`\n- `fields: string[]`\n- `fieldsHash: string`\n- `algorithm: Algorithm = 'SHA-256'`\n\nReturns: `Promise\u003cboolean\u003e`\n\n### `solveChallenge(challenge, salt, algorithm?, max?, start?)`\n\nFinds a solution to the given challenge. \n\nParameters:\n\n- `challenge: string` (required): The challenge hash.\n- `salt: string` (required): The challenge salt.\n- `algorithm?: string`: Optional algorithm (default: `SHA-256`).\n- `maxnumber?: string`: Optional `maxnumber` to iterate to (default: 1e6).\n- `start?: string`: Optional starting number (default: 0).\n\nReturns: `{ controller: AbortController, promise: Promise\u003cSolution | null\u003e }`\n\n### `solveChallengeWorkers(workerScript, concurrency, challenge, salt, algorithm?, max?, start?)`\n\nFinds a solution to the given challenge with [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker) running concurrently. \n\nParameters:\n\n- `workerScript: string` (required): The path or URL of the worker script.\n- `concurrency: number` (required): The concurrency (number of workers).\n- `challenge: string` (required): The challenge hash.\n- `salt: string` (required): The challenge salt.\n- `algorithm?: string`: Optional algorithm (default: `SHA-256`).\n- `maxnumber?: string`: Optional `maxnumber` to iterate to (default: 1e6).\n- `start?: string`: Optional starting number (default: 0).\n\nReturns: `Promise\u003cSolution | null\u003e`\n\nUsage with `altcha-lib/worker`:\n\n```ts\nimport { solveChallengeWorkers } from 'altcha-lib';\n\nconst solution = await solveChallengeWorkers(\n  'altcha-lib/worker', // Worker script URL or path\n  8, // Spawn 8 workers\n  challenge,\n  salt,\n);\n```\n\n## Benchmarks\n\n```\n\u003e solveChallenge()\n- n = 1,000...............................        312 ops/s ±2.90%\n- n = 10,000..............................         31 ops/s ±1.50%\n- n = 50,000..............................          6 ops/s ±0.82%\n- n = 100,000.............................          3 ops/s ±0.37%\n- n = 500,000.............................          0 ops/s ±0.31%\n\n\u003e solveChallengeWorkers() (8 workers)\n- n = 1,000...............................         62 ops/s ±3.99%\n- n = 10,000..............................         31 ops/s ±6.83%\n- n = 50,000..............................         11 ops/s ±4.00%\n- n = 100,000.............................          7 ops/s ±2.32%\n- n = 500,000.............................          1 ops/s ±1.89%\n```\n\nRun with Bun on MacBook Pro M3-Pro. See [/benchmark](/benchmark/) folder for more details.\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltcha-org%2Faltcha-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltcha-org%2Faltcha-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltcha-org%2Faltcha-lib/lists"}