{"_id":"@danielbiegler/vendure-plugin-user-registration-guard","_rev":"3-e67d7595f65e85e135e1ef6e13c77865","name":"@danielbiegler/vendure-plugin-user-registration-guard","dist-tags":{"latest":"1.0.1"},"versions":{"0.1.0":{"name":"@danielbiegler/vendure-plugin-user-registration-guard","version":"0.1.0","keywords":["vendure","plugin","vendure-plugin","ecommerce","headless","graphql","typescript","whitelist","allowlist","blacklist","blocklist"],"author":{"url":"https://www.danielbiegler.de","name":"Daniel Biegler"},"license":"MIT","_id":"@danielbiegler/vendure-plugin-user-registration-guard@0.1.0","maintainers":[{"name":"danielbiegler","email":"danielbiegler.de@gmail.com"}],"homepage":"https://github.com/DanielBiegler/bieglers-vendure-plugins#readme","bugs":{"url":"https://github.com/DanielBiegler/bieglers-vendure-plugins/issues"},"dist":{"shasum":"3e60b63fe77ab28a81406297986cbb878f7ad9d7","tarball":"https://registry.npmjs.org/@danielbiegler/vendure-plugin-user-registration-guard/-/vendure-plugin-user-registration-guard-0.1.0.tgz","fileCount":18,"integrity":"sha512-GM61r1mbCCDrgiUAbdjWQS5AMEe678JQA7P7s4nzkjPFjvURl5Mi7L4iJeBB05TfxQfKx1IVUFyTb8rhiYfiIg==","signatures":[{"sig":"MEUCID6wc2YKx7rTWCjyjQfUqb2QBxW3lTQX/I6yAo598OpBAiEA7wyHmUEdi60RQkBoeZb0qqCvgZUVeu67IZz63jcBbRM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":454882},"main":"./dist/index.js","types":"./dist/index.d.ts","gitHead":"58c8841747f3a32a5171f79b846b8a6b3b13e0cf","private":false,"scripts":{"dev":"ts-node dev-server/index.ts","e2e":"cross-env PACKAGE=user-registration-guard vitest -c ../../utils/e2e/vitest.config.mts","build":"rimraf dist && tsc -p ./tsconfig.build.json","codegen":"ts-node generate-types.ts"},"_npmUser":{"name":"danielbiegler","email":"danielbiegler.de@gmail.com"},"repository":{"url":"git+https://github.com/DanielBiegler/bieglers-vendure-plugins.git","type":"git"},"_npmVersion":"10.2.3","description":"Let's you flexibly customize if and how you prevent users from registering with your Vendure instance.","directories":{},"_nodeVersion":"20.10.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/vendure-plugin-user-registration-guard_0.1.0_1745780039106_0.31090997086659367","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@danielbiegler/vendure-plugin-user-registration-guard","version":"1.0.0","keywords":["vendure","plugin","vendure-plugin","ecommerce","headless","graphql","typescript","whitelist","allowlist","blacklist","blocklist"],"author":{"url":"https://www.danielbiegler.de","name":"Daniel Biegler"},"license":"MIT","_id":"@danielbiegler/vendure-plugin-user-registration-guard@1.0.0","maintainers":[{"name":"danielbiegler","email":"danielbiegler.de@gmail.com"}],"homepage":"https://github.com/DanielBiegler/bieglers-vendure-plugins#readme","bugs":{"url":"https://github.com/DanielBiegler/bieglers-vendure-plugins/issues"},"dist":{"shasum":"dce37c352de70b849456cb31b2749eb2536cb042","tarball":"https://registry.npmjs.org/@danielbiegler/vendure-plugin-user-registration-guard/-/vendure-plugin-user-registration-guard-1.0.0.tgz","fileCount":18,"integrity":"sha512-iWQ+khBCmMmdWHqRZ/y471efGwIjL63BKHD3NvDeIM6Zz9d6esY8/d4ewiUwQoyQLPqasarJ4aIeOP44A6uFSA==","signatures":[{"sig":"MEQCIDsxv8G1Rc2h+XcqtVqIOKuB5t7owZcVVXd/duDso3fhAiA7nhjTpk+nhGoHCd72VVfkH+IBpyiKoCpjgWUPb/sF9Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":457137},"main":"./dist/index.js","types":"./dist/index.d.ts","gitHead":"62cab17058906377f2d5e880326584c1e29f24b7","private":false,"scripts":{"dev":"ts-node dev-server/index.ts","e2e":"cross-env PACKAGE=user-registration-guard vitest -c ../../utils/e2e/vitest.config.mts","build":"rimraf dist && tsc -p ./tsconfig.build.json","codegen":"ts-node generate-types.ts"},"_npmUser":{"name":"danielbiegler","email":"danielbiegler.de@gmail.com"},"repository":{"url":"git+https://github.com/DanielBiegler/bieglers-vendure-plugins.git","type":"git"},"_npmVersion":"10.9.2","description":"Let's you flexibly customize if and how you prevent users from registering with your Vendure instance.","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/vendure-plugin-user-registration-guard_1.0.0_1746198428735_0.2277641493471072","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@danielbiegler/vendure-plugin-user-registration-guard","description":"Let's you flexibly customize if and how you prevent users from registering with your Vendure instance.","version":"1.0.1","license":"MIT","scripts":{"dev":"ts-node dev-server/index.ts","codegen":"ts-node generate-types.ts","build":"rimraf dist && tsc -p ./tsconfig.build.json","e2e":"cross-env PACKAGE=user-registration-guard vitest -c ../../utils/e2e/vitest.config.mts"},"author":{"name":"Daniel Biegler","url":"https://www.danielbiegler.de"},"repository":{"type":"git","url":"git+https://github.com/DanielBiegler/bieglers-vendure-plugins.git"},"keywords":["vendure","plugin","vendure-plugin","ecommerce","headless","graphql","typescript","whitelist","allowlist","blacklist","blocklist"],"private":false,"publishConfig":{"access":"public"},"main":"./dist/index.js","types":"./dist/index.d.ts","_id":"@danielbiegler/vendure-plugin-user-registration-guard@1.0.1","gitHead":"d12435c443a035636d542f7a22b27e6909f767e2","bugs":{"url":"https://github.com/DanielBiegler/bieglers-vendure-plugins/issues"},"homepage":"https://github.com/DanielBiegler/bieglers-vendure-plugins#readme","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-4BuQFI+6r+MpuKwJE4Sa3frY1ZAUVZJe8RxIsDcKRXoXjLGuiM4t4spiGBinGllSU5VFA98BKvU3dGSvrTgEGw==","shasum":"5f65af2f72db8bdaab9b1d2f6553c489379f33f3","tarball":"https://registry.npmjs.org/@danielbiegler/vendure-plugin-user-registration-guard/-/vendure-plugin-user-registration-guard-1.0.1.tgz","fileCount":18,"unpackedSize":457736,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIE2NrB5pEgzoJSp77HaeASsQNEVWPpizlbsunaSmxPYZAiAdUcDNQPT8DO2SlLxmlYRDMulA1q+9PFWlErTPoF4Phw=="}]},"_npmUser":{"name":"danielbiegler","email":"danielbiegler.de@gmail.com"},"directories":{},"maintainers":[{"name":"danielbiegler","email":"danielbiegler.de@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vendure-plugin-user-registration-guard_1.0.1_1756544114709_0.46798947367666743"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-27T18:53:59.050Z","modified":"2025-08-30T08:55:15.116Z","0.1.0":"2025-04-27T18:53:59.309Z","1.0.0":"2025-05-02T15:07:08.917Z","1.0.1":"2025-08-30T08:55:14.897Z"},"bugs":{"url":"https://github.com/DanielBiegler/bieglers-vendure-plugins/issues"},"author":{"name":"Daniel Biegler","url":"https://www.danielbiegler.de"},"license":"MIT","homepage":"https://github.com/DanielBiegler/bieglers-vendure-plugins#readme","keywords":["vendure","plugin","vendure-plugin","ecommerce","headless","graphql","typescript","whitelist","allowlist","blacklist","blocklist"],"repository":{"type":"git","url":"git+https://github.com/DanielBiegler/bieglers-vendure-plugins.git"},"description":"Let's you flexibly customize if and how you prevent users from registering with your Vendure instance.","maintainers":[{"name":"danielbiegler","email":"danielbiegler.de@gmail.com"}],"readme":"![Banner Image](https://raw.githubusercontent.com/DanielBiegler/bieglers-vendure-plugins/master/packages/user-registration-guard/assets/thumbnail_16x9.png)\n\n# Vendure Plugin: User Registration Guard\n\nLet's you flexibly customize if and how you prevent users from registering with your Vendure instance.\n\nFor example, reduce fraud by blocking disposable email providers or IP ranges from registering with your Vendure instance or harden your admin accounts by only allowing specific domains in email addresses.\n\n<a href=\"https://www.npmjs.com/package/@danielbiegler/vendure-plugin-user-registration-guard\" target=\"_blank\">\n  <img src=\"https://badge.fury.io/js/@danielbiegler%2Fvendure-plugin-user-registration-guard.svg\" alt=\"npm version badge\" height=\"18\">\n</a>\n\n## Features\n\n- Let's you create arbitrarily complex assertions for Customer registrations and Administrator creations\n- Logical operators (`AND`, `OR`) for when you have multiple checks\n- Publishes a [`BlockedCustomerRegistrationEvent`](https://github.com/DanielBiegler/bieglers-vendure-plugins/blob/master/packages/user-registration-guard/src/events/user-registration-blocked.event.ts) or [`BlockedCreateAdministratorEvent`](https://github.com/DanielBiegler/bieglers-vendure-plugins/blob/master/packages/user-registration-guard/src/events/user-registration-blocked.event.ts) on the [EventBus](https://docs.vendure.io/guides/developer-guide/events/) for your consumption, for example if you'd like to monitor failed attempts\n- Works via [Nestjs Interceptor](https://docs.nestjs.com/interceptors) and does not(!) override the existing mutation APIs ([`registerCustomerAccount`](https://docs.vendure.io/reference/graphql-api/shop/mutations#registercustomeraccount), [`createAdministrator`](https://docs.vendure.io/reference/graphql-api/admin/mutations#createadministrator)), which makes this plugin integrate seamlessly with your own [resolver overrides](https://docs.vendure.io/guides/developer-guide/extend-graphql-api/#override-built-in-resolvers)\n  - Also supports TypeScript Generics so you can use your own extended types!\n  - Also let's you inject providers into your assertions i.e. use Vendure's or your own custom services\n- Nicely commented and documented\n- No dependencies\n\n### End-To-End Tests\n\n```\n ✓ user-registration-guard/e2e/email.e2e-spec.ts (4)\n ✓ user-registration-guard/e2e/events.e2e-spec.ts (4)\n ✓ user-registration-guard/e2e/injector.e2e-spec.ts (2)\n ✓ user-registration-guard/e2e/ip.e2e-spec.ts (2)\n ✓ user-registration-guard/e2e/logical-and_fail.e2e-spec.ts (2)\n ✓ user-registration-guard/e2e/logical-and_ok.e2e-spec.ts (2)\n ✓ user-registration-guard/e2e/logical-or_fail.e2e-spec.ts (2)\n ✓ user-registration-guard/e2e/logical-or_ok.e2e-spec.ts (2)\n ✓ user-registration-guard/e2e/reject.e2e-spec.ts (2)\n\n Test Files  9 passed (9)\n      Tests  22 passed (22)\n```\n\n## How To: Usage\n\nThe plugin does not extend the API, has no dependencies and requires no migration.\n\n### 1. Add the plugin to your Vendure Config\n\nYou can find the package over on [npm](https://www.npmjs.com/package/@danielbiegler/vendure-plugin-user-registration-guard) and install it via:\n\n```bash\nnpm i @danielbiegler/vendure-plugin-user-registration-guard\n```\n\n```ts\nimport { UserRegistrationGuardPlugin } from \"@danielbiegler/vendure-plugin-user-registration-guard\";\nexport const config: VendureConfig = {\n  // ...\n  plugins: [\n    UserRegistrationGuardPlugin.init({\n      shop: {\n        assert: {\n          /* AND means every single assertion must\n             be true to allow user registration */\n          logicalOperator: \"AND\",\n          functions: [ /* Insert your assertions here */ ],\n        },\n      },\n      admin: {\n        assert: {\n          /* OR means user registration is allowed\n             if a single assertion is true */\n          logicalOperator: \"OR\",\n          functions: [ /* You may leave this empty too */ ],\n        },\n      },\n    }),\n  ],\n}\n```\n\nPlease refer to the specific [docs](https://github.com/DanielBiegler/bieglers-vendure-plugins/blob/master/packages/user-registration-guard/src/types.ts) for how and what you can customize.\n\n### 2. Create an assertion\n\nHere's an example assertion where we block customer registrations if the email ends with `example.com`:\n\n```ts\nconst blockExampleDotCom: AssertFunctionShopApi = async (ctx, args, injector) => {\n  const isAllowed = !args.input.emailAddress.endsWith(\"example.com\");\n  return {\n    isAllowed,\n    reason: !isAllowed ? 'Failed because email ends with \"example.com\"' : undefined,\n  };\n};\n```\n\nThe `reason` field is helpful for when you're subscribing to the published [events](https://github.com/DanielBiegler/bieglers-vendure-plugins/blob/master/packages/user-registration-guard/src/events/user-registration-blocked.event.ts) and want to log or understand why somebody got blocked.\n\nIn your assertions, see the [types](https://github.com/DanielBiegler/bieglers-vendure-plugins/blob/master/packages/user-registration-guard/src/types.ts), you'll receive these arguments:\n\n- [`RequestContext`](https://docs.vendure.io/reference/typescript-api/request/request-context)\n- GraphQL arguments of the mutation, which by default are either [`RegisterCustomerInput`](https://docs.vendure.io/reference/graphql-api/shop/input-types#registercustomerinput) or [`CreateAdministratorInput`](https://docs.vendure.io/reference/graphql-api/admin/input-types#createadministratorinput) depending on the API type.\n- [`Injector`](https://docs.vendure.io/reference/typescript-api/common/injector) \n\nFor example, if you'd like to block IP ranges you can access the underlying [Express Request](https://docs.vendure.io/reference/typescript-api/request/request-context#req) object through the `RequestContext` .\n\n```ts\nexport const onlyAllowLocalIp: AssertFunctionShopApi = async (ctx, args) => {\n  // `includes` instead of strict comparison because local ips may include other bits\n  return {\n    isAllowed: ctx.req?.ip?.includes(\"127.0.0.1\") ?? false,\n  };\n};\n```\n\nIf you'd like to delegate the decision to a service you may inject it like so:\n\n```ts\nexport const example: AssertFunctionShopApi = async (ctx, args, injector) => {\n  const service = injector.get(BlacklistService);\n\n  // Make sure to handle errors in a real environment\n  return service.canUserRegister(ctx, args);\n};\n```\n\nIf you've extended your GraphQL API types you may override the TypeScript Generic to get completions in your assertion functions like so:\n\n```ts\nconst example: AssertFunctionShopApi<{ example: boolean; /* ... */ }> = async (ctx, args, injector) => {\n  return { isAllowed: args.example };\n};\n```\n\n### 3. Add it to the plugin\n\n```ts\nimport { UserRegistrationGuardPlugin } from \"@danielbiegler/vendure-plugin-user-registration-guard\";\nexport const config: VendureConfig = {\n  // ...\n  plugins: [\n    UserRegistrationGuardPlugin.init({\n      shop: {\n        assert: {\n          logicalOperator: \"AND\",\n          functions: [ blockExampleDotCom ],\n        },\n      },\n      admin: {\n        assert: {\n          logicalOperator: \"AND\",\n          functions: [],\n        },\n      },\n    }),\n  ],\n}\n```\n\n### 4. Try registering new customers\n\n```graphql\nmutation {\n  registerCustomerAccount(input: {\n    emailAddress: \"example@example.com\",\n    # ...\n  }) {\n    __typename\n  }\n}\n```\n\nThis user will now be blocked from registering according to our `blockExampleDotCom` assertion.\n\n#### Handling errors\n\nThe plugin is non-intrusive and does not extend the API itself to avoid introducing unhandled errors in your code.\n\nIt respects [`RegisterCustomerAccountResult`](https://docs.vendure.io/reference/graphql-api/shop/object-types#registercustomeraccountresult) being a Union, so we don't throw an error, but return a [`NativeAuthStrategyError`](https://docs.vendure.io/reference/graphql-api/shop/object-types#nativeauthstrategyerror). You may handle the error just like the other `RegisterCustomerAccountResult` types like [`PasswordValidationError`](https://docs.vendure.io/reference/graphql-api/shop/object-types#passwordvalidationerror) for example.\n\nIn contrast, for admins we do throw the error! This is a little different because by default the [`createAdministrator`](https://docs.vendure.io/reference/graphql-api/admin/mutations#createadministrator) mutation does not return a Union with error types.\n\nGranted, the `NativeAuthStrategyError` is technically not correct for blocking registrations and doesn't communicate the blocking properly, but it's the only reasonable error type in the Union for a default non-api-extended Vendure instance. You might want to add some comments in your registration logic that the error means blockage.\n\n### 5. Subscribe to events\n\nYou may want to [subscribe](https://docs.vendure.io/guides/developer-guide/events/#subscribing-to-events) to the [EventBus](https://docs.vendure.io/reference/typescript-api/events/event-bus) to monitor blocked registration attempts.\n\n```ts\nthis.eventBus\n  .ofType(BlockedCustomerRegistrationEvent<MutationRegisterCustomerAccountArgs>)\n  .subscribe(async (event) => {\n    const rejecteds = event.assertions.filter((a) => !a.isAllowed);\n    console.log(`Blocked customer registration! ${rejecteds.length}/${event.assertions.length} assertions failed, see reasons:`);\n    rejecteds.forEach(r => console.log(\"  -\", r.reason));\n\n    // Example output:\n    // Blocked customer registration! 1/1 assertions failed, see reasons:\n    //   - Failed because email ends with \"example.com\"\n  });\n\nthis.eventBus\n  // You can even override the passed in args if you've extended your Graphql API\n  .ofType(BlockedCreateAdministratorEvent<{ example: boolean }>).subscribe(async (event) => {\n    event.args.example // is typed now! :)\n  });\n```\n\n---\n\n#### Credits\n\n- Traffic Light Photo by Caroline Cagnin from [Pexels](https://www.pexels.com/photo/white-building-with-fire-escape-stairs-1786758/), edited by [Daniel Biegler](https://www.danielbiegler.de/)\n","readmeFilename":"README.md"}