web-bot-auth

library0.0.1jsnpmunverified

web-bot-auth is a TypeScript library developed by Cloudflare Research that implements HTTP Message Signatures for the purpose of Web Bot Authentication. It adheres to the draft-meunier-web-bot-auth-architecture specification. Currently at version 0.1.3, the library provides utilities for signing and verifying HTTP requests using cryptographic keys, including features like JWK (JSON Web Key) thumbprint pre-computation. Its release cadence is likely tied to research advancements and RFC progression, as it's an early-stage project. Key differentiators include its specific focus on bot authentication, direct implementation of a draft RFC, and shipping with full TypeScript type definitions, making it suitable for type-safe applications. It is designed to work with standard Web API `Request` objects.

auth-security http-networking web-framework

npm install web-bot-auth

github ↗package ↗

INSTALL

IMPORT

SIG · WEB-BOT-AUTH

web-bot-auth

auth-securityjavascriptv0.0.1

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.

signatureHeaders

✓ import { signatureHeaders } from 'web-bot-auth';

✗ const { signatureHeaders } = require('web-bot-auth');

The library is primarily designed for ESM environments. Use named imports for core signing functionality.

signerFromJWK

✓ import { signerFromJWK } from 'web-bot-auth/crypto';

✗ import { signerFromJWK } from 'web-bot-auth';

Crypto utility functions are located in a subpath import. Forgetting `/crypto` is a common mistake.

verify

✓ import { verify } from 'web-bot-auth';

✗ import verify from 'web-bot-auth';

Verification functions are named exports from the main package entry point.

verifierFromJWK

✓ import { verifierFromJWK } from 'web-bot-auth/crypto';

✗ const verifierFromJWK = require('web-bot-auth/crypto').verifierFromJWK;

Like `signerFromJWK`, verifier utilities require the `/crypto` subpath and are named exports.

Demonstrates how to sign an HTTP request using a test JWK, adding 'Signature' and 'Signature-Input' headers for Web Bot Authentication.

import { signatureHeaders } from 'web-bot-auth'; import { signerFromJWK } from 'web-bot-auth/crypto'; const RFC_9421_ED25519_TEST_KEY = { kty: 'OKP', crv: 'Ed25519', kid: 'test-key-ed25519', d: 'n4Ni-HpISpVObnQMW0wOhCKROaIKqKtW_2ZYb2p9KcU', x: 'JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs' }; async function signRequest() { const request = new Request('https://example.com'); const now = new Date(); const headers = await signatureHeaders( request, await signerFromJWK(RFC_9421_ED25519_TEST_KEY), { created: now, expires: new Date(now.getTime() + 300_000) // now + 5 min } ); const signedRequest = new Request('https://example.com', { headers: { 'Signature': headers['Signature'], 'Signature-Input': headers['Signature-Input'] } }); console.log('Signed Request Headers:', Object.fromEntries(signedRequest.headers.entries())); return signedRequest; } signRequest().catch(console.error);

Debug

Known issues

gotchaThis software has not been audited for security. It is developed by Cloudflare Research and should be used with extreme caution, especially in production environments, until it has undergone independent security reviews.

fix

Do not use in production without a thorough security audit. Closely monitor for updates and security advisories.

affects: >=0.1.0

breakingAs a pre-1.0 release (current version 0.1.3), the API is subject to significant changes without prior warning. Breaking changes may be introduced in minor or patch versions.

fix

Pin your dependency to an exact version and review release notes thoroughly for any updates. Be prepared for refactoring when upgrading.

affects: >=0.1.0

gotchaThe library heavily relies on standard Web API `Request` and `Response` objects. If used in a Node.js environment, these globals might not be available, leading to runtime errors.

fix

Ensure `Request` and `Response` are globally available (e.g., using `node-fetch` or a web framework that provides them) or explicitly import them if your environment supports it.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: signerFromJWK is not a function

Attempting to import `signerFromJWK` from the main `web-bot-auth` package path instead of its specific crypto subpath.

fix

Change your import statement from `import { signerFromJWK } from 'web-bot-auth';` to `import { signerFromJWK } from 'web-bot-auth/crypto';`.

ReferenceError: Request is not defined

The code is being run in a Node.js environment without a global `Request` object being present, which the library expects.

fix

Install a polyfill like `node-fetch` and ensure `Request` is made globally available, or manually import it if your environment permits. For example: `import { Request } from 'node-fetch';`

Error: Signature verification failed: Signature-Input parameter 'sig1' is missing 'keyid'

The JWK used for signing or verification does not contain a 'kid' (Key ID) property, or the 'keyid' parameter was omitted from the 'Signature-Input' during signing.

fix

Ensure your JWK includes a unique 'kid' property and that the signing process correctly includes this 'keyid' in the 'Signature-Input' headers.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cloudflare/web-bot-auth ↗

packagehttps://www.npmjs.com/package/web-bot-auth ↗