TypeScript: @dnsid-ai/web-bot-auth

DNSid Web Bot Auth profile helpers.

This package signs outbound HTTP requests per the Web Bot Auth draft (RFC 9421 HTTP Message Signatures with the web-bot-auth tag) and serves the /.well-known/http-message-signatures-directory document so origins can discover and verify an agent’s keys.

It builds on @dnsid-ai/http-signatures and @dnsid-ai/protocol contracts and performs no DNS or HTTPS transport itself. Signing requires an Ed25519 operational key; the profile throws ArgumentError for other key types.

Install

npm install @dnsid-ai/web-bot-auth @dnsid-ai/protocol

Example

Sign an outbound request:

import { createWebBotAuthProfile } from '@dnsid-ai/web-bot-auth';

const profile = createWebBotAuthProfile({
  domain: 'agent.example',
  keyProvider, // Ed25519 operational key
});

const signed = await profile.createWebBotAuthSignedRequest(
  new Request('https://origin.example/api'),
);
await fetch(signed);

Serve the key directory (mount at /.well-known/http-message-signatures-directory):

const response = await profile.serveHttpMessageSignaturesDirectory(request);

The directory response is itself signed with the http-message-signatures-directory tag and served as application/http-message-signatures-directory+json.

Options

signatureAgent — the discovery URI and type advertised in Signature-Agent. It defaults to the domain’s HTTPS origin with type=directory; use type=jwks_uri for a direct JWKS endpoint.
directoryURL — deprecated compatibility option interpreted as a direct jwks_uri endpoint. Use signatureAgent.uri instead.
signatureTTL / directorySignatureTTL — signature lifetimes in seconds (defaults: 60 for requests, 300 for the directory).
includeSignatureAgent — set false to omit the Signature-Agent header.

You can also build the profile from a signing identity manager with WebBotAuthProfile.fromIdentityManager(idm).

DNSid Web Bot Auth profile.

Signs outbound HTTP requests per Web Bot Auth (RFC 9421 HTTP Message Signatures with the web-bot-auth tag) and serves the signed /.well-known/http-message-signatures-directory document that advertises the agent’s public keys.

Web Bot Auth requires an Ed25519 operational key; signing with any other key type raises ArgumentError.

Classes

WebBotAuthProfile

Defined in: index.ts:105

Web Bot Auth signing profile for a single agent domain.

Signs outbound requests with the agent’s Ed25519 operational key per RFC 9421 (tag web-bot-auth) and serves the signed key directory that verifiers fetch to resolve the signature’s key.

Example

const profile = createWebBotAuthProfile({
  domain: 'agent.example',
  keyProvider: myEd25519KeyProvider,
});

const signed = await profile.createWebBotAuthSignedRequest(
  new Request('https://api.example/v1/items', { method: 'GET' }),
);
await fetch(signed);

Constructors

Constructor

new WebBotAuthProfile(opts): WebBotAuthProfile;

Defined in: index.ts:126

Parameters

opts

WebBotAuthProfileOptions

Returns

WebBotAuthProfile

Throws

ArgumentError If opts.domain is not a valid agent FQDN.

Methods

createWebBotAuthSignedRequest()

createWebBotAuthSignedRequest(req, opts?): Promise<Request>;

Defined in: index.ts:153

Returns a copy of req carrying a Web Bot Auth signature (tag web-bot-auth).

Covers @authority plus, when applicable, content-digest (a SHA-256 Content-Digest header is added for requests with a body) and signature-agent (added unless disabled). The signature includes a nonce, created/expires timestamps, and the operational key’s JWK thumbprint as keyid. The original request is not modified.

Parameters

req

Request

Outbound request to sign.

opts?

WebBotAuthSigningOptions = {}

Per-request overrides for covered components, Signature-Agent, and TTL.

Returns

Promise<Request>

A new signed Request.

Throws

ArgumentError If the operational key is not Ed25519, the resolved Signature-Agent URI is invalid, or an additional component identifier is invalid.

serveHttpMessageSignaturesDirectory()

serveHttpMessageSignaturesDirectory(req): Promise<Response>;

Defined in: index.ts:206

Builds the signed key directory response for HTTP_MESSAGE_SIGNATURES_DIRECTORY_PATH.

The JSON body lists the agent’s public operational key as a JWK. The response is signed with tag http-message-signatures-directory, covering the requesting authority, Content-Type, Cache-Control, and Content-Digest.

Parameters

req

Request

Incoming directory request; its @authority is bound into the signature.

Returns

Promise<Response>

A 200 response with media type HTTP_MESSAGE_SIGNATURES_DIRECTORY_MEDIA_TYPE.

Throws

ArgumentError If the operational key is not Ed25519.

fromIdentityManager()

static fromIdentityManager(identityManager, webBotAuth?): WebBotAuthProfile;

Defined in: index.ts:111

Builds a profile from a signing identity manager, reusing its domain and key provider.

Parameters

identityManager

SigningIdentityManager

Manager whose domain and operational key provider back the profile.

webBotAuth?

WebBotAuthConfig

Optional Web Bot Auth configuration overrides.

Returns

WebBotAuthProfile

Interfaces

SignatureAgentConfig

Defined in: index.ts:39

Signature-Agent discovery configuration.

Properties

type?

optional type?: SignatureAgentType;

Defined in: index.ts:43

Discovery interpretation. Default: directory.

uri?

optional uri?: string;

Defined in: index.ts:41

HTTPS origin for directory, or the direct HTTPS endpoint for jwks_uri.

WebBotAuthConfig

Defined in: index.ts:47

Profile-level Web Bot Auth configuration. All members are optional; defaults are noted per member.

Properties

clockSkew?

optional clockSkew?: number;

Defined in: index.ts:62

Allowed verification clock skew in seconds. Reserved for the future verifier API. Default: 5.

directorySignatureTTL?

optional directorySignatureTTL?: number;

Defined in: index.ts:60

Directory-signature lifetime in seconds; also sets the response Cache-Control max-age. Defaults to DEFAULT_DIRECTORY_SIGNATURE_TTL_SECONDS.

directoryURL?

optional directoryURL?: string;

Defined in: index.ts:54

Deprecated

Use signatureAgent.uri. Retained as a direct jwks_uri endpoint.

includeSignatureAgent?

optional includeSignatureAgent?: boolean;

Defined in: index.ts:58

Whether signed requests include (and cover) the Signature-Agent header. Defaults to true.

signatureAgent?

optional signatureAgent?: SignatureAgentConfig;

Defined in: index.ts:52

Signature-Agent URI and discovery type. Defaults to the domain’s HTTPS origin with type=directory.

signatureTTL?

optional signatureTTL?: number;

Defined in: index.ts:56

Request-signature lifetime in seconds. Defaults to DEFAULT_WEB_BOT_AUTH_SIGNATURE_TTL_SECONDS.

WebBotAuthProfileOptions

Defined in: index.ts:66

Constructor options for WebBotAuthProfile.

Properties

domain

domain: string;

Defined in: index.ts:68

Agent FQDN the profile signs for (e.g. agent.example). Normalized on construction.

keyProvider

keyProvider: KeyProvider;

Defined in: index.ts:70

Key provider holding the agent’s Ed25519 operational key.

webBotAuth?

optional webBotAuth?: WebBotAuthConfig;

Defined in: index.ts:72

Optional Web Bot Auth configuration overrides.

WebBotAuthSigningOptions

Defined in: index.ts:76

Per-request overrides for WebBotAuthProfile.createWebBotAuthSignedRequest.

Properties

additionalComponents?

optional additionalComponents?: ComponentIdentifier[];

Defined in: index.ts:78

Extra covered components appended to the defaults (@authority, plus content-digest/signature-agent when present). Duplicates are ignored.

signatureAgent?

optional signatureAgent?: boolean;

Defined in: index.ts:80

Overrides WebBotAuthConfig.includeSignatureAgent for this request.

ttl?

optional ttl?: number;

Defined in: index.ts:82

Overrides WebBotAuthConfig.signatureTTL for this request (seconds).

Type Aliases

SignatureAgentType

type SignatureAgentType = "directory" | "jwks_uri";

Defined in: index.ts:36

Web Bot Auth key-discovery interpretation for the Signature-Agent member.

Variables

DEFAULT_DIRECTORY_SIGNATURE_TTL_SECONDS

const DEFAULT_DIRECTORY_SIGNATURE_TTL_SECONDS: 300 = 300;

Defined in: index.ts:33

Default directory-signature lifetime and Cache-Control max-age (seconds).

DEFAULT_WEB_BOT_AUTH_SIGNATURE_TTL_SECONDS

const DEFAULT_WEB_BOT_AUTH_SIGNATURE_TTL_SECONDS: 60 = 60;

Defined in: index.ts:31

Default request-signature lifetime (seconds) when no TTL is configured.

HTTP_MESSAGE_SIGNATURES_DIRECTORY_MEDIA_TYPE

const HTTP_MESSAGE_SIGNATURES_DIRECTORY_MEDIA_TYPE: "application/http-message-signatures-directory+json" = 'application/http-message-signatures-directory+json';

Defined in: index.ts:29

Media type of the key directory document.

HTTP_MESSAGE_SIGNATURES_DIRECTORY_PATH

const HTTP_MESSAGE_SIGNATURES_DIRECTORY_PATH: "/.well-known/http-message-signatures-directory" = '/.well-known/http-message-signatures-directory';

Defined in: index.ts:27

Well-known path where the agent’s HTTP message signatures key directory is served.

HTTP_MESSAGE_SIGNATURES_DIRECTORY_TAG

const HTTP_MESSAGE_SIGNATURES_DIRECTORY_TAG: "http-message-signatures-directory" = 'http-message-signatures-directory';

Defined in: index.ts:25

RFC 9421 tag parameter identifying a signed key-directory response.

WEB_BOT_AUTH_SIGNATURE_LABEL

const WEB_BOT_AUTH_SIGNATURE_LABEL: "sig1" = 'sig1';

Defined in: index.ts:21

Signature label used for the Web Bot Auth member in the Signature/Signature-Input dictionaries.

WEB_BOT_AUTH_TAG

const WEB_BOT_AUTH_TAG: "web-bot-auth" = 'web-bot-auth';

Defined in: index.ts:23

RFC 9421 tag parameter identifying a Web Bot Auth request signature.

Functions

createWebBotAuthProfile()

function createWebBotAuthProfile(opts): WebBotAuthProfile;

Defined in: index.ts:258

Creates a WebBotAuthProfile for an agent domain.

Parameters

opts

WebBotAuthProfileOptions

Returns

WebBotAuthProfile

Example

const profile = createWebBotAuthProfile({
  domain: 'agent.example',
  keyProvider: myEd25519KeyProvider,
});
const signed = await profile.createWebBotAuthSignedRequest(
  new Request('https://api.example/v1/items'),
);
await fetch(signed);

Throws

ArgumentError If opts.domain is not a valid agent FQDN.

wbaDirectoryJwkFromPublicKey()

function wbaDirectoryJwkFromPublicKey(key): Promise<DnsIdJWK>;

Defined in: index.ts:270

Converts an operational key JWK into its public directory form: private members stripped, kid set to the JWK thumbprint, with alg and use: 'sig'.

Parameters

key

DnsIdJWK

Ed25519 JWK (public or private) to publish.

Returns

Promise<DnsIdJWK>

The public JWK as listed in the key directory’s keys array.

Throws

ArgumentError If the key is not Ed25519.

Known Systems AI, Inc. is an affiliate of Identity Digital that solves identity fragmentation for the AI agent economy. As agents become more autonomous and interoperable, they introduce risk and security challenges existing systems weren't designed for—starting with a consistent way to verify ownership across organizational boundaries. Known Systems AI, Inc. combines Identity Digital's DNS expertise with an Immutable Log to establish a global coordination layer for AI agent identity, and participates in open standards communities, including the Linux Foundation. For more information, visit DNSid.ai.