Registry / web-framework / brownstone-middleware

brownstone-middleware

JSON →
library0.1.4jsnpmunverified

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.

web-frameworkllm-agentshttp-networkingauth-securityobservability
npm install brownstone-middleware
package ↗
INSTALL
IMPORT
SIG · BROWNSTONE-MIDDLEW
B
brownstone-middleware
web-frameworkjavascriptv0.1.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

brownstone
✓ const brownstone = require('brownstone-middleware');
✗ import brownstone from '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.

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.'); });
Debug
Known issues
gotchaAn `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.
affects: >=0.1.0
gotchaThe `<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.
affects: >=0.1.0
breakingAs 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.
affects: <1.0.0
gotchaBrownstone 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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: brownstone is not a function
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.
Brownstone API Error: API Key missing or invalid.
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 })`.
Upgrade
Version history
0.1.4latest on npm
Audit
Dependencies
expressrequiredCore web framework integration; peer dependency for the middleware function.
Agent activity
21 hits · last 30 days
node
20
OpenAI (training)
1
Resources
packagehttps://www.npmjs.com/package/brownstone-middleware ↗
brownstone-middleware — npm install brownstone-middleware · libregistry