Brownstone AI Access Control for Express

0.1.4 verified Thu Apr 23 auth: no javascript

This `brownstone-middleware` package, currently at version 0.1.4, integrates with Express.js applications to manage and monetize AI agent access. It operates by detecting known AI crawlers and bots based on their user-agents. The middleware offers capabilities for logging AI hits (metering), enforcing access policies by blocking unauthorized agents with a 403 status, and injecting licensing metadata into HTML responses via a `<meta name="ai-usage">` tag. This allows AI systems to directly read usage terms. A key differentiator is its reliance on an external Brownstone API for comprehensive analytics, centralized licensing configuration, and robust bot detection, providing developers with granular control over how their content is accessed and used by AI models. The project is actively maintained, with ongoing updates to agent detection and API features.

Common errors

error TypeError: brownstone is not a function ↓

cause Attempting to import `brownstone-middleware` using ES Module syntax (`import`) in a CommonJS environment, or misinterpreting the default export.

fix

Ensure you are using const brownstone = require('brownstone-middleware'); if your project is CommonJS. If using ESM, a bundler might be needed to handle the CJS package, or await official ESM support in future versions.

error Brownstone API Error: API Key missing or invalid. ↓

cause The `apiKey` option was either omitted, empty, or contained an invalid key when `metering` or `enforcement` was enabled in the middleware configuration.

fix

Provide a valid apiKey string, obtained from brownstoneai.dev, to the middleware options object: brownstone({ apiKey: 'your_valid_key', metering: true }).

Warnings

gotcha An `apiKey` is mandatory for both `metering` and `enforcement` features to function. Without a valid key, the middleware will operate in a passive detection-only mode or throw errors if an API call is attempted. ↓

fix Obtain an API key from `brownstoneai.dev` and pass it as the `apiKey` option to the middleware configuration object.

gotcha The `<meta name="ai-usage">` tag injection only occurs for HTML responses. If your application primarily serves JSON or other content types, this specific feature will not be active for those routes. ↓

fix Ensure your application serves HTML responses for paths where AI meta-tag injection is desired.

breaking As a pre-1.0 package (current version 0.1.4), internal APIs and configuration options are subject to change in minor or patch releases without strict adherence to SemVer for breaking changes. Developers should review release notes carefully. ↓

fix Monitor the package's GitHub repository and npm release notes for changes before upgrading, especially in production environments.

gotcha Brownstone middleware relies on user-agent strings for AI detection. While a comprehensive list is provided, custom or rapidly evolving AI agents might not be immediately recognized, potentially bypassing metering or enforcement. ↓

fix Regularly update the `brownstone-middleware` package to benefit from the latest AI agent detection rules. Consider supplementing with other bot detection strategies if maximum coverage is critical.

Install

npm install brownstone-middleware

yarn add brownstone-middleware

pnpm add brownstone-middleware

Imports

brownstone
wrong
```
import brownstone from 'brownstone-middleware';
```
correct
```
const brownstone = require('brownstone-middleware');
```
The package is primarily designed for CommonJS (CJS) environments, as shown in the official usage examples. While some bundlers or Node.js with `type: module` might handle ESM imports, `require()` is the officially supported and most reliable method for `0.x` versions.

Quickstart

Initializes an Express application with Brownstone middleware, enabling AI bot detection, logging, and optional enforcement of licensing rules, along with injecting license metadata into HTML responses.

const express = require("express");
const brownstone = require("brownstone-middleware");

const app = express();
const BROWNSTONE_API_KEY = process.env.BROWNSTONE_API_KEY ?? "your-brownstone-api-key";

app.use(
  brownstone({
    apiKey: BROWNSTONE_API_KEY,
    metering: true,
    enforcement: true,
    license: {
      model: "paid",
      rate: "$0.001-per-1000-tokens",
      permission: "allowed",
    },
  }),
);

app.get("/", (req, res) => {
  res.send("<html><head></head><body>Hello, AI world!</body></html>");
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Express server listening on port ${PORT}`);
  console.log('Try visiting / with an AI user-agent (e.g., GPTBot) to see metering and enforcement in action.');
});