{"id":13761968,"url":"https://github.com/neg4n/next-hcaptcha","last_synced_at":"2025-05-04T06:55:37.313Z","repository":{"id":119380604,"uuid":"394956557","full_name":"neg4n/next-hcaptcha","owner":"neg4n","description":"🤖 Robust, dependency free and highly configurable solution for guarding Next.js API Routes through higher order function with HCaptcha","archived":false,"fork":false,"pushed_at":"2023-02-08T14:46:06.000Z","size":877,"stargazers_count":24,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T00:35:39.050Z","etag":null,"topics":["captcha","hcaptcha","nextjs","nextjs-plugin","react-captcha","react-recaptcha","recaptcha"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/next-hcaptcha","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/neg4n.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-11T10:53:11.000Z","updated_at":"2024-08-08T22:59:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"a2de042c-2a6d-425e-877e-7b0f87c660e7","html_url":"https://github.com/neg4n/next-hcaptcha","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fnext-hcaptcha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fnext-hcaptcha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fnext-hcaptcha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fnext-hcaptcha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neg4n","download_url":"https://codeload.github.com/neg4n/next-hcaptcha/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252134223,"owners_count":21699675,"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":["captcha","hcaptcha","nextjs","nextjs-plugin","react-captcha","react-recaptcha","recaptcha"],"created_at":"2024-08-03T14:00:32.208Z","updated_at":"2025-05-03T02:36:04.773Z","avatar_url":"https://github.com/neg4n.png","language":"TypeScript","funding_links":[],"categories":["miscellaneous"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eNext.js HCaptcha\u003c/h1\u003e\n  \u003cbr /\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/next-hcaptcha\"\u003e\u003cimg alt=\"npm version badge\" src=\"https://badgen.net/npm/v/next-hcaptcha\"\u003e\u003c/a\u003e  \n  \u003cimg alt=\"types information\" src=\"https://badgen.net/npm/types/next-hcaptcha\"\u003e\n  \u003cimg alt=\"npm bundle size\" src=\"https://badgen.net/bundlephobia/minzip/next-hcaptcha\"\u003e\n  \u003cimg alt=\"license badge\" src=\"https://badgen.net/npm/license/next-hcaptcha\"\u003e\n  \n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## Introduction\n\nThis library provides simple higher order function  \nwith responsibility of _\"guarding\"_ specific [Next.js API route][next-api-routes].\n\nSample usage:\n\n```js\nimport { withHCaptcha } from 'next-hcaptcha'\n\nexport default withHCaptcha((req, res) =\u003e {\n  res.status(200).json({ name: 'John Doe' })\n})\n```\n\n## Configuration\n\nConfiguration is done by passing options object as second `withHCaptcha` function call argument.\n\nDefault options with all properties explained:\n\n```js\nconst defaultOptions = {\n  // HCaptcha token verification url. Read more at\n  // https://docs.hcaptcha.com/#verify-the-user-response-server-side\n  captchaVerifyUrl: 'https://hcaptcha.com/siteverify',\n  // Whether to pass request ip address or not\n  // The ip resolving is done by checking cf-connecting-ip, x-forwarded-for headers\n  // or evetually request.socket.remoteAddress property\n  // (if the two mentioned earlier are undefined).\n  passRequestIpAddress: false,\n  // Whether to skip HCaptcha requests optimization or not.\n  // Requests optimization are simple static checks if some\n  // properties from the payload exist and if they are not empty.\n  skipCaptchaRequestsOptimization: false,\n  // Whether to throw when HCaptcha response is considered invalid.\n  // (success property is false or score is not met when threshold is set)\n  exceptions: false,\n  // Whether to clean h-captcha-response and g-recaptcha-response from body\n  // from intercepted Next.js request object. Useful when next-hcaptcha is\n  // part of middleware chain and you dont want these props e.g. in validation layer\n  cleanInterception: true,\n  // Error display mode. If set to 'message', it will show error's descriptions\n  // from https://docs.hcaptcha.com/#siteverify-error-codes-table. If set to 'code' it will\n  // show the error code instead.\n  errorDisplayMode: 'message',\n  // Whether to forward HCaptcha response parameters to Next.js API Route handler request parameter.\n  // Accessible under request.hcaptcha (for TypeScript users - there is NextApiRequestWithHCaptcha type).\n  // Forwarded only if HCaptcha response is success and (when specified) if passed `enterprise.scoreThreshold` check.\n  forwardCaptchaResponse: false,\n  // Features that works only if you have HCaptcha enterprise\n  enterprise: {\n    // Minimum score threshold. Value between 1 (bot) and 0 (human).\n    // If scoreThreshold is specified, and no score is returned from HCaptcha\n    // response - it will result in an exception.\n    scoreThreshold: null,\n  },\n  // Env vars names object. Key is type of env var and value is your custom name.\n  // Value can be any string as long as it matches your .env* file.\n  envVarNames: { secret: 'HCAPTCHA_SECRET' },\n}\n```\n\n### Configuration sharing\n\nConfiguration sharing can be done by creating `next-hcaptcha.config.js` in root of your [Next.js][next-homepage] project and simply importing it and passing as argument in every (or specific) route(s).\n\n`next-hcaptcha.config.js`\n\n```js\nconst config = {\n  // ...\n}\n\nexport default config\n```\n\n`pages/api/your-route.js`\n\n```js\nimport { withHCaptcha } from 'next-hcaptcha'\nimport config from '../../next-hcaptcha.config'\n\nexport default withHCaptcha((req, res) =\u003e {\n  res.status(200).json({ name: 'John Doe' })\n}, config)\n```\n\n## Errors\n\n`next-hcaptcha` informs about errors as described in the [official HCaptcha docs][hcaptcha-docs-errors] with some _(i believe)_ tweaks.\n\n**NOTE**: Error optimization described in point **2.** and **3.** can be disabled by setting `skipCaptchaRequestsOptimization` in configuration to `true` and way of informing about errors described in point **1.**\ncan be restored to traditional way by setting `errorDisplayMode` to `'code'`\n\n1. Error messages (_descriptions_ in [docs][hcaptcha-docs-errors]) are shown directly instead of informing about the error code. This has purpose of improving overall work with the library and reduce eventual frustration caused by jumping between loads of documentation.\n\n2. `missing-input-secret` is handled by the library before sending request to HCaptcha verification endpoint by checking sanity of `HCAPTCHA_SECRET` environment variable. and **results in runtime exception**.\n\n3. `missing-input-response` is also handled by the library before sending request to HCaptcha verification endpoint and results in standard error respecting the first point.\n\n4. If `enterprise.scoreThreshold` is specified and no `score` is returned from HCaptcha API, it will result in runtime exception.\n\n## Ending speech\n\nThis project is licensed under the MIT license.\nAll contributions are welcome.\n\n[hcaptcha-docs-errors]: https://docs.hcaptcha.com/#siteverify-error-codes-table\n[next-homepage]: https://nextjs.org/\n[next-api-routes]: https://nextjs.org/docs/api-routes/introduction\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneg4n%2Fnext-hcaptcha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneg4n%2Fnext-hcaptcha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneg4n%2Fnext-hcaptcha/lists"}