Vercel BotID

Overview

The @laioutr/app-botid package makes Vercel BotID the bot-protection provider of a Laioutr storefront. It checks the actions the project lists (a newsletter sign-up, a login, a contact form) and rejects a request that BotID does not classify as a person. For how bot protection works in a storefront, read Bot Protection.

The app uses BotID's Basic check level only. It runs only on storefronts hosted on Vercel.

Configuration requirements

Install the module

export default defineNuxtConfig({
  modules: ['@laioutr/app-botid'],
});

The module has no options.

List the protected actions

List the orchestr action tokens to protect in the config block of the project's laioutrrc.json:

{
  "config": {
    "botProtection": {
      "actions": ["newsletter/subscribe", "ecommerce/auth/login"],
      "whenUnavailable": "open"
    }
  }
}

Runtime behaviour

In the browser, the app hands the protected paths to BotID. BotID wraps fetch and loads nothing on page load. Its challenge script loads on the first request to a protected action, and BotID attaches its headers to that request.

On the server, the app asks BotID about each request to a protected action:

• A request BotID classifies as a person runs the action.
• Any other request is rejected with 403, including verified bots such as search-engine crawlers.
• When BotID cannot answer, the project's whenUnavailable decides.

A rejected request reaches the storefront as an error. Show a message with botProtectionErrorOf(error) from #frontend/bot-protection, which returns 'rejected' or 'unavailable' for these errors. BotID never shows an interactive challenge, so 'cancelled' does not occur.

In development (nuxi dev), BotID classifies every request as a person without contacting Vercel.

Limits

• Vercel only. On a production server that is not on Vercel, the app registers no check, and every protected action is rejected. The build logs a warning when it targets another host.
• Do not enable Deep Analysis in the Vercel dashboard. The browser then loads the Kasada script whatever the app configures, and every check is billed.
• Test in a browser, not with curl. BotID rejects a request that did not pass through its client script. To call a protected action from a script, send a signed bypass.
• The first protected request is slower, because it loads BotID's challenge script first.

Consent

The app starts BotID only when a visitor triggers a protected action, and it adds no consent integration. Whether BotID needs consent for your storefront is your decision. Read what Vercel states about BotID in its documentation and its data processing terms before you enable it.

Backend requirements

• A storefront deployed on Vercel.
• @laioutr-core/frontend-core installed in the host app.

Summary checklist

• Add @laioutr/app-botid to Nuxt modules.
• List the actions to protect under config.botProtection.actions in laioutrrc.json.
• Choose whenUnavailable if open does not fit.
• Leave Deep Analysis off in the Vercel dashboard.
• Handle rejected actions in the UI with botProtectionErrorOf.

Changelog

Version history is maintained in CHANGELOG.md in the public repository laioutr/app-botid.