agentrail-core 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,246 @@
1
+ /**
2
+ * The part of HTTP Structured Fields (RFC 8941) that HTTP Message Signatures
3
+ * (RFC 9421) and Web Bot Auth put in headers: a Dictionary whose members are
4
+ * Items or Inner Lists, each with Parameters; Strings, Tokens, Integers,
5
+ * Decimals, Booleans and Byte Sequences as bare items. Read strictly, as the
6
+ * RFC's algorithms read them: a header that does not parse is no signature.
7
+ */
8
+ /** A header that is not the structured field its name promises. */
9
+ export class StructuredFieldError extends Error {
10
+ name = 'StructuredFieldError';
11
+ }
12
+ const TOKEN_START = /^[A-Za-z*]$/u;
13
+ const TOKEN_CHAR = /^[A-Za-z0-9!#$%&'*+\-.^_`|~:/]$/u;
14
+ const KEY_START = /^[a-z*]$/u;
15
+ const KEY_CHAR = /^[a-z0-9_\-.*]$/u;
16
+ const BASE64 = /^[A-Za-z0-9+/=]*$/u;
17
+ class Reader {
18
+ text;
19
+ position = 0;
20
+ constructor(text) {
21
+ this.text = text;
22
+ }
23
+ peek() {
24
+ return this.text.charAt(this.position);
25
+ }
26
+ next() {
27
+ const char = this.text.charAt(this.position);
28
+ this.position += 1;
29
+ return char;
30
+ }
31
+ done() {
32
+ return this.position >= this.text.length;
33
+ }
34
+ /** Skips spaces, as the RFC's "discard any leading SP characters". */
35
+ skipSpaces() {
36
+ while (this.peek() === ' ')
37
+ this.position += 1;
38
+ }
39
+ /** Skips optional whitespace: spaces and tabs. */
40
+ skipWhitespace() {
41
+ while (this.peek() === ' ' || this.peek() === '\t')
42
+ this.position += 1;
43
+ }
44
+ expect(char) {
45
+ if (this.next() !== char)
46
+ throw new StructuredFieldError(`Expected "${char}" at ${this.position}.`);
47
+ }
48
+ }
49
+ function readKey(reader) {
50
+ if (!KEY_START.test(reader.peek()))
51
+ throw new StructuredFieldError(`A key starts with a letter or "*".`);
52
+ let key = '';
53
+ while (!reader.done() && KEY_CHAR.test(reader.peek()))
54
+ key += reader.next();
55
+ return key;
56
+ }
57
+ function readString(reader) {
58
+ reader.expect('"');
59
+ let value = '';
60
+ for (;;) {
61
+ if (reader.done())
62
+ throw new StructuredFieldError('An unclosed string.');
63
+ const char = reader.next();
64
+ if (char === '\\') {
65
+ const escaped = reader.next();
66
+ if (escaped !== '"' && escaped !== '\\')
67
+ throw new StructuredFieldError('A string escapes only quotes and backslashes.');
68
+ value += escaped;
69
+ }
70
+ else if (char === '"')
71
+ return value;
72
+ else if (char < ' ' || char > '~')
73
+ throw new StructuredFieldError('A string holds printable ASCII only.');
74
+ else
75
+ value += char;
76
+ }
77
+ }
78
+ function readToken(reader) {
79
+ let value = '';
80
+ while (!reader.done() && TOKEN_CHAR.test(reader.peek()))
81
+ value += reader.next();
82
+ return value;
83
+ }
84
+ function readNumber(reader) {
85
+ let text = '';
86
+ if (reader.peek() === '-')
87
+ text += reader.next();
88
+ while (!reader.done() && /^[0-9.]$/u.test(reader.peek()))
89
+ text += reader.next();
90
+ if (!/^-?[0-9]+(?:\.[0-9]{1,3})?$/u.test(text) || text.length > 16)
91
+ throw new StructuredFieldError(`"${text}" is not a number.`);
92
+ return text.includes('.')
93
+ ? { kind: 'decimal', value: Number(text) }
94
+ : { kind: 'integer', value: Number(text) };
95
+ }
96
+ function readBytes(reader) {
97
+ reader.expect(':');
98
+ let encoded = '';
99
+ while (!reader.done() && reader.peek() !== ':')
100
+ encoded += reader.next();
101
+ reader.expect(':');
102
+ if (!BASE64.test(encoded))
103
+ throw new StructuredFieldError('A byte sequence is base64.');
104
+ let binary;
105
+ try {
106
+ binary = atob(encoded);
107
+ }
108
+ catch (error) {
109
+ // Base64 of a length no bytes have: a field that does not parse.
110
+ if (error instanceof DOMException)
111
+ throw new StructuredFieldError('A byte sequence is whole base64.');
112
+ throw error;
113
+ }
114
+ return Uint8Array.from(binary, (char) => char.charCodeAt(0));
115
+ }
116
+ function readBareItem(reader) {
117
+ const char = reader.peek();
118
+ if (char === '"')
119
+ return { kind: 'string', value: readString(reader) };
120
+ if (char === ':')
121
+ return { kind: 'bytes', value: readBytes(reader) };
122
+ if (char === '?') {
123
+ reader.next();
124
+ const flag = reader.next();
125
+ if (flag !== '0' && flag !== '1')
126
+ throw new StructuredFieldError('A boolean is ?0 or ?1.');
127
+ return { kind: 'boolean', value: flag === '1' };
128
+ }
129
+ if (char === '-' || /^[0-9]$/u.test(char))
130
+ return readNumber(reader);
131
+ if (TOKEN_START.test(char))
132
+ return { kind: 'token', value: readToken(reader) };
133
+ throw new StructuredFieldError(`No item starts with "${char}".`);
134
+ }
135
+ function readParameters(reader) {
136
+ const parameters = new Map();
137
+ while (reader.peek() === ';') {
138
+ reader.next();
139
+ reader.skipSpaces();
140
+ const key = readKey(reader);
141
+ let value = { kind: 'boolean', value: true };
142
+ if (reader.peek() === '=') {
143
+ reader.next();
144
+ value = readBareItem(reader);
145
+ }
146
+ parameters.set(key, value);
147
+ }
148
+ return parameters;
149
+ }
150
+ function readItem(reader) {
151
+ const value = readBareItem(reader);
152
+ return { kind: 'item', value, parameters: readParameters(reader) };
153
+ }
154
+ function readInnerList(reader) {
155
+ reader.expect('(');
156
+ const items = [];
157
+ for (;;) {
158
+ reader.skipSpaces();
159
+ if (reader.peek() === ')') {
160
+ reader.next();
161
+ return { kind: 'inner-list', items, parameters: readParameters(reader) };
162
+ }
163
+ items.push(readItem(reader));
164
+ const after = reader.peek();
165
+ if (after !== ' ' && after !== ')')
166
+ throw new StructuredFieldError('Inner list items are separated by spaces.');
167
+ }
168
+ }
169
+ function readMember(reader) {
170
+ return reader.peek() === '(' ? readInnerList(reader) : readItem(reader);
171
+ }
172
+ /** A Dictionary: `key=value, key=(a b);p=1, flag`. A key given twice keeps the last. */
173
+ export function parseDictionary(text) {
174
+ const reader = new Reader(text);
175
+ const dictionary = new Map();
176
+ reader.skipSpaces();
177
+ while (!reader.done()) {
178
+ const key = readKey(reader);
179
+ if (reader.peek() === '=') {
180
+ reader.next();
181
+ dictionary.set(key, readMember(reader));
182
+ }
183
+ else
184
+ dictionary.set(key, {
185
+ kind: 'item',
186
+ value: { kind: 'boolean', value: true },
187
+ parameters: readParameters(reader),
188
+ });
189
+ reader.skipWhitespace();
190
+ if (reader.done())
191
+ return dictionary;
192
+ reader.expect(',');
193
+ reader.skipWhitespace();
194
+ if (reader.done())
195
+ throw new StructuredFieldError('A trailing comma.');
196
+ }
197
+ return dictionary;
198
+ }
199
+ /** One Item on its own: `"https://signer.example"` or `token;p=1`. */
200
+ export function parseItem(text) {
201
+ const reader = new Reader(text);
202
+ reader.skipSpaces();
203
+ const item = readItem(reader);
204
+ reader.skipSpaces();
205
+ if (!reader.done())
206
+ throw new StructuredFieldError('More than one item where one was expected.');
207
+ return item;
208
+ }
209
+ function serializeString(value) {
210
+ return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
211
+ }
212
+ /** A bare item as the RFC writes it, for a signature base's component lines. */
213
+ export function serializeBareItem(item) {
214
+ switch (item.kind) {
215
+ case 'string':
216
+ return serializeString(item.value);
217
+ case 'token':
218
+ return item.value;
219
+ case 'integer':
220
+ return String(item.value);
221
+ case 'decimal':
222
+ // A decimal keeps a fractional digit, as the RFC writes `1.0`.
223
+ return Number.isInteger(item.value)
224
+ ? item.value.toFixed(1)
225
+ : String(item.value);
226
+ case 'boolean':
227
+ return item.value ? '?1' : '?0';
228
+ case 'bytes':
229
+ return `:${btoa(String.fromCharCode(...item.value))}:`;
230
+ }
231
+ }
232
+ export function serializeParameters(parameters) {
233
+ let text = '';
234
+ for (const [key, value] of parameters)
235
+ text +=
236
+ value.kind === 'boolean' && value.value
237
+ ? `;${key}`
238
+ : `;${key}=${serializeBareItem(value)}`;
239
+ return text;
240
+ }
241
+ export function serializeItem(item) {
242
+ return `${serializeBareItem(item.value)}${serializeParameters(item.parameters)}`;
243
+ }
244
+ export function serializeInnerList(list) {
245
+ return `(${list.items.map(serializeItem).join(' ')})${serializeParameters(list.parameters)}`;
246
+ }
@@ -0,0 +1,58 @@
1
+ import type { SpanContext } from './event.js';
2
+ export declare const TRACE_HANDOFF_HEADER = "x-agentrail-trace-handoff";
3
+ export interface TraceHandoffInput {
4
+ readonly traceparent: string;
5
+ readonly hashKeyId: string;
6
+ readonly issuedAt: number;
7
+ readonly method: string;
8
+ /** Exact origin-form target sent on the wire, after path/query rewrites. */
9
+ readonly target: string;
10
+ }
11
+ interface Expectation {
12
+ readonly traceparent: string | null;
13
+ readonly method: string;
14
+ readonly target: string;
15
+ readonly now: number;
16
+ }
17
+ export interface TraceHandoffVerificationInput extends Expectation {
18
+ readonly hashKey: string;
19
+ }
20
+ export interface TraceHandoffRefusal {
21
+ readonly kind: 'refused';
22
+ readonly reason: 'missing' | 'malformed' | 'key_mismatch' | 'context_mismatch' | 'expired' | 'future' | 'signature_invalid';
23
+ }
24
+ interface Context {
25
+ readonly context: SpanContext;
26
+ readonly traceparent: string;
27
+ readonly hashKeyId: string;
28
+ readonly issuedAt: number;
29
+ }
30
+ export type TraceHandoffVerification = (Context & {
31
+ readonly kind: 'verified';
32
+ }) | TraceHandoffRefusal;
33
+ export declare class TraceHandoffInputError extends Error {
34
+ readonly name = "TraceHandoffInputError";
35
+ constructor();
36
+ }
37
+ /** A fragment never reaches the origin; a trailing empty query still can. */
38
+ export declare function traceHandoffTarget(url: string | URL): string;
39
+ /** Shared canonical bytes for runtimes whose OTel hooks require synchronous HMAC. */
40
+ export declare function encodeTraceHandoff(input: TraceHandoffInput): {
41
+ bytes: Uint8Array<ArrayBuffer>;
42
+ tokenPrefix: string;
43
+ };
44
+ export declare function signTraceHandoff(input: TraceHandoffInput, hashKey: string): Promise<string>;
45
+ /**
46
+ * Unverified candidate only. Node's synchronous OTel propagator checks its MAC
47
+ * with node:crypto; other runtimes use verifyTraceHandoff below. Never continue
48
+ * a trace from this result until the signature over bytes has been verified.
49
+ */
50
+ export declare function readTraceHandoff(token: string | null, expected: Expectation & {
51
+ readonly hashKeyId: string;
52
+ }): (Context & {
53
+ readonly kind: 'candidate';
54
+ readonly bytes: Uint8Array<ArrayBuffer>;
55
+ readonly signature: Uint8Array<ArrayBuffer>;
56
+ }) | TraceHandoffRefusal;
57
+ export declare function verifyTraceHandoff(token: string | null, input: TraceHandoffVerificationInput): Promise<TraceHandoffVerification>;
58
+ export {};
@@ -0,0 +1,141 @@
1
+ import { hashKeyIdOf } from './hash.js';
2
+ import { parseTraceparent } from './trace.js';
3
+ export const TRACE_HANDOFF_HEADER = 'x-agentrail-trace-handoff';
4
+ const MAX_AGE_MS = 60_000;
5
+ const encoder = new TextEncoder();
6
+ const TOKEN = /^ah1\.([0-9a-f]{16})\.(0|[1-9][0-9]{0,15})\.(00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2})\.([0-9a-f]{64})$/u;
7
+ const METHOD = /^[!#$%&'*+.^_`|~0-9a-z-]{1,64}$/iu;
8
+ const keys = new Map();
9
+ export class TraceHandoffInputError extends Error {
10
+ name = 'TraceHandoffInputError';
11
+ constructor() {
12
+ super('Configure a valid trace context, hash key ID, timestamp, method and origin-form target for trace handoff.');
13
+ }
14
+ }
15
+ async function keyOf(hashKey) {
16
+ const held = keys.get(hashKey);
17
+ if (held !== undefined)
18
+ return held;
19
+ const imported = Promise.all([
20
+ crypto.subtle.importKey('raw', encoder.encode(hashKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']),
21
+ hashKeyIdOf(hashKey),
22
+ ]).then(([key, id]) => ({ key, id }));
23
+ keys.set(hashKey, imported);
24
+ return imported;
25
+ }
26
+ /** A fragment never reaches the origin; a trailing empty query still can. */
27
+ export function traceHandoffTarget(url) {
28
+ const parsed = new URL(url);
29
+ const fragmentAt = parsed.href.indexOf('#');
30
+ const sent = fragmentAt < 0 ? parsed.href : parsed.href.slice(0, fragmentAt);
31
+ return `${parsed.pathname}${parsed.search}${parsed.search === '' && sent.endsWith('?') ? '?' : ''}`;
32
+ }
33
+ function validRequest(method, target) {
34
+ return (METHOD.test(method) &&
35
+ target.startsWith('/') &&
36
+ target.isWellFormed() &&
37
+ !/[\u0000\r\n#]/u.test(target));
38
+ }
39
+ function payload(input) {
40
+ return encoder.encode(`agentrail.trace-handoff\u0000${JSON.stringify([
41
+ 1,
42
+ input.hashKeyId,
43
+ input.issuedAt,
44
+ input.traceparent,
45
+ input.method,
46
+ input.target,
47
+ ])}`);
48
+ }
49
+ /** Shared canonical bytes for runtimes whose OTel hooks require synchronous HMAC. */
50
+ export function encodeTraceHandoff(input) {
51
+ if (!/^[0-9a-f]{16}$/u.test(input.hashKeyId) ||
52
+ input.traceparent !== input.traceparent.trim() ||
53
+ parseTraceparent(input.traceparent) === null ||
54
+ !Number.isSafeInteger(input.issuedAt) ||
55
+ input.issuedAt < 0 ||
56
+ !validRequest(input.method, input.target))
57
+ throw new TraceHandoffInputError();
58
+ return {
59
+ bytes: payload(input),
60
+ tokenPrefix: `ah1.${input.hashKeyId}.${input.issuedAt}.${input.traceparent}.`,
61
+ };
62
+ }
63
+ export async function signTraceHandoff(input, hashKey) {
64
+ const key = await keyOf(hashKey);
65
+ if (input.hashKeyId !== key.id)
66
+ throw new TraceHandoffInputError();
67
+ const encoded = encodeTraceHandoff(input);
68
+ const mac = await crypto.subtle.sign('HMAC', key.key, encoded.bytes);
69
+ const hex = [...new Uint8Array(mac)]
70
+ .map((byte) => byte.toString(16).padStart(2, '0'))
71
+ .join('');
72
+ return encoded.tokenPrefix + hex;
73
+ }
74
+ function parsedToken(token) {
75
+ if (token.length > 256)
76
+ return null;
77
+ const [, hashKeyId, time, traceparent, signature] = TOKEN.exec(token) ?? [];
78
+ if (hashKeyId === undefined ||
79
+ time === undefined ||
80
+ traceparent === undefined ||
81
+ signature === undefined)
82
+ return null;
83
+ const context = parseTraceparent(traceparent);
84
+ const issuedAt = Number(time);
85
+ if (context === null || !Number.isSafeInteger(issuedAt))
86
+ return null;
87
+ return {
88
+ hashKeyId,
89
+ issuedAt,
90
+ traceparent,
91
+ context,
92
+ signature: Uint8Array.from({ length: 32 }, (_, index) => Number.parseInt(signature.slice(index * 2, index * 2 + 2), 16)),
93
+ };
94
+ }
95
+ /**
96
+ * Unverified candidate only. Node's synchronous OTel propagator checks its MAC
97
+ * with node:crypto; other runtimes use verifyTraceHandoff below. Never continue
98
+ * a trace from this result until the signature over bytes has been verified.
99
+ */
100
+ export function readTraceHandoff(token, expected) {
101
+ if (token === null)
102
+ return { kind: 'refused', reason: 'missing' };
103
+ const parsed = parsedToken(token);
104
+ if (parsed === null ||
105
+ !validRequest(expected.method, expected.target) ||
106
+ !Number.isSafeInteger(expected.now))
107
+ return { kind: 'refused', reason: 'malformed' };
108
+ if (parsed.hashKeyId !== expected.hashKeyId)
109
+ return { kind: 'refused', reason: 'key_mismatch' };
110
+ if (parsed.traceparent !== expected.traceparent)
111
+ return { kind: 'refused', reason: 'context_mismatch' };
112
+ const age = expected.now - parsed.issuedAt;
113
+ if (age < 0)
114
+ return { kind: 'refused', reason: 'future' };
115
+ if (age > MAX_AGE_MS)
116
+ return { kind: 'refused', reason: 'expired' };
117
+ return {
118
+ ...parsed,
119
+ kind: 'candidate',
120
+ bytes: payload({
121
+ ...parsed,
122
+ method: expected.method,
123
+ target: expected.target,
124
+ }),
125
+ };
126
+ }
127
+ export async function verifyTraceHandoff(token, input) {
128
+ const key = await keyOf(input.hashKey);
129
+ const candidate = readTraceHandoff(token, { ...input, hashKeyId: key.id });
130
+ if (candidate.kind === 'refused')
131
+ return candidate;
132
+ if (!(await crypto.subtle.verify('HMAC', key.key, candidate.signature, candidate.bytes)))
133
+ return { kind: 'refused', reason: 'signature_invalid' };
134
+ return {
135
+ kind: 'verified',
136
+ context: candidate.context,
137
+ traceparent: candidate.traceparent,
138
+ hashKeyId: candidate.hashKeyId,
139
+ issuedAt: candidate.issuedAt,
140
+ };
141
+ }
@@ -0,0 +1,7 @@
1
+ import type { SpanContext } from './event.js';
2
+ export declare function newTraceId(): string;
3
+ export declare function newSpanId(): string;
4
+ /** The context a `traceparent` header names, or null when it names none validly. */
5
+ export declare function parseTraceparent(header: string | null): SpanContext | null;
6
+ /** A sampled `traceparent` naming this span as the parent. */
7
+ export declare function formatTraceparent(context: SpanContext): string;
package/dist/trace.js ADDED
@@ -0,0 +1,33 @@
1
+ /**
2
+ * W3C trace context (`traceparent`), which every component speaks with
3
+ * OpenTelemetry's field names, without the OpenTelemetry SDK.
4
+ */
5
+ const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/u;
6
+ const INVALID_TRACE = '0'.repeat(32);
7
+ const INVALID_SPAN = '0'.repeat(16);
8
+ function hex(bytes) {
9
+ return [...crypto.getRandomValues(new Uint8Array(bytes))]
10
+ .map((byte) => byte.toString(16).padStart(2, '0'))
11
+ .join('');
12
+ }
13
+ export function newTraceId() {
14
+ return hex(16);
15
+ }
16
+ export function newSpanId() {
17
+ return hex(8);
18
+ }
19
+ /** The context a `traceparent` header names, or null when it names none validly. */
20
+ export function parseTraceparent(header) {
21
+ const match = header === null ? null : TRACEPARENT.exec(header.trim());
22
+ const traceId = match?.[1];
23
+ const spanId = match?.[2];
24
+ if (traceId === undefined || spanId === undefined)
25
+ return null;
26
+ if (traceId === INVALID_TRACE || spanId === INVALID_SPAN)
27
+ return null;
28
+ return { traceId, spanId };
29
+ }
30
+ /** A sampled `traceparent` naming this span as the parent. */
31
+ export function formatTraceparent(context) {
32
+ return `00-${context.traceId}-${context.spanId}-01`;
33
+ }
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The version of every Agentrail package in this repository. They are
3
+ * released together, at one version, and each component reports it as its
4
+ * own in every call. `test/version.test.ts` holds it to every package's
5
+ * manifest.
6
+ */
7
+ export declare const VERSION = "0.2.0";
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The version of every Agentrail package in this repository. They are
3
+ * released together, at one version, and each component reports it as its
4
+ * own in every call. `test/version.test.ts` holds it to every package's
5
+ * manifest.
6
+ */
7
+ export const VERSION = '0.2.0';
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Web Bot Auth (draft-ietf-webbotauth-httpsig-protocol): an agent signs its
3
+ * requests with HTTP Message Signatures (RFC 9421) and names, in
4
+ * `Signature-Agent`, the HTTPS URL it publishes its keys at. A verified
5
+ * signature says who operates the agent; an unverified one is a claim. This
6
+ * checks a request's signature against that directory and reports the
7
+ * outcome with its reason, so a directory that is down is never read as a
8
+ * forged signature (docs/research/agent-journey-correlation.md, 12.3).
9
+ *
10
+ * What it reads: the dictionary form of `Signature-Agent` (`sig="https://…"`)
11
+ * and the bare string signers sent before it; a signature tagged
12
+ * `web-bot-auth` covering `@authority` or `@target-uri` and the agent header;
13
+ * Ed25519, RSA-PSS-SHA512 and ECDSA-P256 keys, matched by the JWK thumbprint
14
+ * the draft makes the key id. Anything else it does not read is reported as
15
+ * unsupported, never as invalid.
16
+ */
17
+ /** What a check here ends as: every outcome but `unchecked`, which is a component that did not check. */
18
+ export declare const SIGNATURE_CHECK_OUTCOMES: readonly ["verified", "invalid", "directory_unreachable", "unsupported"];
19
+ export type SignatureCheckOutcome = (typeof SIGNATURE_CHECK_OUTCOMES)[number];
20
+ /** A request's signed agent: who it says it is, and whether that checked. */
21
+ export interface SignedAgent {
22
+ /** The URL the agent names itself by, where its keys are published. */
23
+ readonly agent: string;
24
+ /** The key id the signature names; null when the headers did not parse that far. */
25
+ readonly keyId: string | null;
26
+ readonly outcome: SignatureCheckOutcome;
27
+ }
28
+ /** What of a request the signature covers: its method, URL and headers. */
29
+ export interface SignedRequest {
30
+ readonly method: string;
31
+ readonly url: string;
32
+ readonly headers: Headers;
33
+ }
34
+ /**
35
+ * The operators known to publish keys for their agents, by the registrable
36
+ * host of the directory: the only hosts a directory is read from unless a
37
+ * site names more. A name the caller chose is otherwise never contacted,
38
+ * since even a public-looking name may resolve to an address inside the
39
+ * network the edge runs in, which the Fetch API gives no way to see.
40
+ */
41
+ export declare const KNOWN_SIGNERS: readonly ["chatgpt.com", "openai.com", "google.com", "anthropic.com", "claude.ai", "perplexity.ai"];
42
+ export interface SignatureVerifierOptions {
43
+ /** The fetch directories are read with; the platform's own by default. */
44
+ readonly fetch?: typeof fetch;
45
+ /**
46
+ * Registrable hosts, beside the known signers, whose key directories may
47
+ * be read (`signer.example.com` covers `keys.signer.example.com`). A
48
+ * signature by any other host is recorded as an unsupported claim.
49
+ */
50
+ readonly signers?: readonly string[];
51
+ /** The clock, milliseconds since the epoch; `Date.now` by default. */
52
+ readonly now?: () => number;
53
+ }
54
+ export type SignatureVerifier = (request: SignedRequest) => Promise<SignedAgent | null>;
55
+ interface Jwk {
56
+ readonly kty: string;
57
+ readonly crv?: string;
58
+ readonly x?: string;
59
+ readonly y?: string;
60
+ readonly n?: string;
61
+ readonly e?: string;
62
+ readonly kid?: string;
63
+ }
64
+ /**
65
+ * The JWK thumbprint (RFC 7638; RFC 8037 for Ed25519) the draft makes a
66
+ * signature's `keyid`: the SHA-256 of the key's required members in
67
+ * lexicographic order, base64url. Null for a key this verifier does not read.
68
+ */
69
+ export declare function keyThumbprint(key: Jwk): Promise<string | null>;
70
+ /**
71
+ * A verifier of requests' Web Bot Auth signatures. One per runtime: it keeps
72
+ * the directories it has read, so a signer's keys are fetched once per
73
+ * `max-age`, not once per request.
74
+ */
75
+ export declare function createSignatureVerifier(options?: SignatureVerifierOptions): SignatureVerifier;
76
+ export {};