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.
- package/LICENSE +201 -0
- package/README.md +50 -0
- package/dist/collector.d.ts +75 -0
- package/dist/collector.js +182 -0
- package/dist/event.d.ts +154 -0
- package/dist/event.js +23 -0
- package/dist/hash.d.ts +17 -0
- package/dist/hash.js +40 -0
- package/dist/id.d.ts +10 -0
- package/dist/id.js +17 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +16 -0
- package/dist/marker.d.ts +40 -0
- package/dist/marker.js +102 -0
- package/dist/session.d.ts +40 -0
- package/dist/session.js +69 -0
- package/dist/structured-fields.d.ts +51 -0
- package/dist/structured-fields.js +246 -0
- package/dist/trace-handoff.d.ts +58 -0
- package/dist/trace-handoff.js +141 -0
- package/dist/trace.d.ts +7 -0
- package/dist/trace.js +33 -0
- package/dist/version.d.ts +7 -0
- package/dist/version.js +7 -0
- package/dist/web-bot-auth.d.ts +76 -0
- package/dist/web-bot-auth.js +534 -0
- package/package.json +28 -3
|
@@ -0,0 +1,534 @@
|
|
|
1
|
+
import { StructuredFieldError, parseDictionary, parseItem, serializeInnerList, serializeItem, } from './structured-fields.js';
|
|
2
|
+
/**
|
|
3
|
+
* Web Bot Auth (draft-ietf-webbotauth-httpsig-protocol): an agent signs its
|
|
4
|
+
* requests with HTTP Message Signatures (RFC 9421) and names, in
|
|
5
|
+
* `Signature-Agent`, the HTTPS URL it publishes its keys at. A verified
|
|
6
|
+
* signature says who operates the agent; an unverified one is a claim. This
|
|
7
|
+
* checks a request's signature against that directory and reports the
|
|
8
|
+
* outcome with its reason, so a directory that is down is never read as a
|
|
9
|
+
* forged signature (docs/research/agent-journey-correlation.md, 12.3).
|
|
10
|
+
*
|
|
11
|
+
* What it reads: the dictionary form of `Signature-Agent` (`sig="https://…"`)
|
|
12
|
+
* and the bare string signers sent before it; a signature tagged
|
|
13
|
+
* `web-bot-auth` covering `@authority` or `@target-uri` and the agent header;
|
|
14
|
+
* Ed25519, RSA-PSS-SHA512 and ECDSA-P256 keys, matched by the JWK thumbprint
|
|
15
|
+
* the draft makes the key id. Anything else it does not read is reported as
|
|
16
|
+
* unsupported, never as invalid.
|
|
17
|
+
*/
|
|
18
|
+
/** What a check here ends as: every outcome but `unchecked`, which is a component that did not check. */
|
|
19
|
+
export const SIGNATURE_CHECK_OUTCOMES = [
|
|
20
|
+
/** The signature checks against a key the agent's directory publishes. */
|
|
21
|
+
'verified',
|
|
22
|
+
/** It does not: a forged or stale signature, or a key the directory does not hold. */
|
|
23
|
+
'invalid',
|
|
24
|
+
/** The directory could not be read, so nothing is known either way. */
|
|
25
|
+
'directory_unreachable',
|
|
26
|
+
/** The signature uses a component, algorithm or key this verifier does not read. */
|
|
27
|
+
'unsupported',
|
|
28
|
+
];
|
|
29
|
+
/**
|
|
30
|
+
* The operators known to publish keys for their agents, by the registrable
|
|
31
|
+
* host of the directory: the only hosts a directory is read from unless a
|
|
32
|
+
* site names more. A name the caller chose is otherwise never contacted,
|
|
33
|
+
* since even a public-looking name may resolve to an address inside the
|
|
34
|
+
* network the edge runs in, which the Fetch API gives no way to see.
|
|
35
|
+
*/
|
|
36
|
+
export const KNOWN_SIGNERS = [
|
|
37
|
+
'chatgpt.com',
|
|
38
|
+
'openai.com',
|
|
39
|
+
'google.com',
|
|
40
|
+
'anthropic.com',
|
|
41
|
+
'claude.ai',
|
|
42
|
+
'perplexity.ai',
|
|
43
|
+
];
|
|
44
|
+
/** Where an agent publishes its keys, under the URL it names. */
|
|
45
|
+
const DIRECTORY_PATH = '/.well-known/http-message-signatures-directory';
|
|
46
|
+
const DIRECTORY_MEDIA_TYPE = 'application/http-message-signatures-directory+json';
|
|
47
|
+
/** How long a directory read may take: a signed request's answer is already sent. */
|
|
48
|
+
const DIRECTORY_TIMEOUT_MS = 5_000;
|
|
49
|
+
/** How long a directory is kept when it names no `max-age`, and the most it is kept. */
|
|
50
|
+
const DIRECTORY_DEFAULT_TTL_MS = 60 * 60 * 1_000;
|
|
51
|
+
const DIRECTORY_MAX_TTL_MS = 24 * 60 * 60 * 1_000;
|
|
52
|
+
/** How long a directory that could not be read is not asked again, so a down signer is not fetched on every request. */
|
|
53
|
+
const DIRECTORY_RETRY_MS = 60 * 1_000;
|
|
54
|
+
/** How far in the future a signature's `created` may be, for clocks that disagree. */
|
|
55
|
+
const CREATED_SKEW_MS = 5 * 60 * 1_000;
|
|
56
|
+
/** The tag the draft gives these signatures. */
|
|
57
|
+
const TAG = 'web-bot-auth';
|
|
58
|
+
/** The longest agent URL and key id the collector takes; a claim is cut to them. */
|
|
59
|
+
const AGENT_LENGTH = 256;
|
|
60
|
+
const KEY_ID_LENGTH = 256;
|
|
61
|
+
/** The most directories kept at once, and the most failures remembered: a caller names the hosts, so neither may grow without bound. */
|
|
62
|
+
const MAX_DIRECTORIES = 256;
|
|
63
|
+
const MAX_FAILURES = 1_024;
|
|
64
|
+
const encoder = new TextEncoder();
|
|
65
|
+
function base64url(bytes) {
|
|
66
|
+
const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
|
|
67
|
+
return btoa(String.fromCharCode(...view))
|
|
68
|
+
.replaceAll('+', '-')
|
|
69
|
+
.replaceAll('/', '_')
|
|
70
|
+
.replace(/=+$/u, '');
|
|
71
|
+
}
|
|
72
|
+
/** The key's algorithm and members, from what kind of key it is; null for a kind this verifier does not read, or a key missing a member. */
|
|
73
|
+
function publicKeyOf(key) {
|
|
74
|
+
if (key.kty === 'OKP' && key.crv === 'Ed25519' && key.x !== undefined)
|
|
75
|
+
return {
|
|
76
|
+
algorithm: 'ed25519',
|
|
77
|
+
jwk: { crv: 'Ed25519', kty: 'OKP', x: key.x },
|
|
78
|
+
};
|
|
79
|
+
if (key.kty === 'RSA' && key.e !== undefined && key.n !== undefined)
|
|
80
|
+
return {
|
|
81
|
+
algorithm: 'rsa-pss-sha512',
|
|
82
|
+
jwk: { e: key.e, kty: 'RSA', n: key.n },
|
|
83
|
+
};
|
|
84
|
+
if (key.kty === 'EC' &&
|
|
85
|
+
key.crv === 'P-256' &&
|
|
86
|
+
key.x !== undefined &&
|
|
87
|
+
key.y !== undefined)
|
|
88
|
+
return {
|
|
89
|
+
algorithm: 'ecdsa-p256-sha256',
|
|
90
|
+
jwk: { crv: 'P-256', kty: 'EC', x: key.x, y: key.y },
|
|
91
|
+
};
|
|
92
|
+
return null;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* The JWK thumbprint (RFC 7638; RFC 8037 for Ed25519) the draft makes a
|
|
96
|
+
* signature's `keyid`: the SHA-256 of the key's required members in
|
|
97
|
+
* lexicographic order, base64url. Null for a key this verifier does not read.
|
|
98
|
+
*/
|
|
99
|
+
export async function keyThumbprint(key) {
|
|
100
|
+
const read = publicKeyOf(key);
|
|
101
|
+
if (read === null)
|
|
102
|
+
return null;
|
|
103
|
+
return base64url(await crypto.subtle.digest('SHA-256', encoder.encode(JSON.stringify(read.jwk))));
|
|
104
|
+
}
|
|
105
|
+
function importKey(key) {
|
|
106
|
+
switch (key.algorithm) {
|
|
107
|
+
case 'ed25519':
|
|
108
|
+
return crypto.subtle.importKey('jwk', key.jwk, { name: 'Ed25519' }, false, ['verify']);
|
|
109
|
+
case 'rsa-pss-sha512':
|
|
110
|
+
return crypto.subtle.importKey('jwk', key.jwk, { name: 'RSA-PSS', hash: 'SHA-512' }, false, ['verify']);
|
|
111
|
+
case 'ecdsa-p256-sha256':
|
|
112
|
+
return crypto.subtle.importKey('jwk', key.jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
function verifyParameters(algorithm) {
|
|
116
|
+
switch (algorithm) {
|
|
117
|
+
case 'ed25519':
|
|
118
|
+
return { name: 'Ed25519' };
|
|
119
|
+
case 'rsa-pss-sha512':
|
|
120
|
+
return { name: 'RSA-PSS', saltLength: 64 };
|
|
121
|
+
case 'ecdsa-p256-sha256':
|
|
122
|
+
return { name: 'ECDSA', hash: 'SHA-256' };
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* The agent URLs a `Signature-Agent` header names, by dictionary label (the
|
|
127
|
+
* bare form has none): every HTTPS URL it names, each marked whether its
|
|
128
|
+
* directory may be read, so a claim is always recorded against the agent
|
|
129
|
+
* the signature named, readable or not.
|
|
130
|
+
*/
|
|
131
|
+
function agentsOf(header, readable) {
|
|
132
|
+
const agents = new Map();
|
|
133
|
+
let members;
|
|
134
|
+
try {
|
|
135
|
+
members = parseDictionary(header);
|
|
136
|
+
}
|
|
137
|
+
catch (error) {
|
|
138
|
+
if (!(error instanceof StructuredFieldError))
|
|
139
|
+
throw error;
|
|
140
|
+
members = new Map();
|
|
141
|
+
}
|
|
142
|
+
for (const [label, member] of members) {
|
|
143
|
+
if (member.kind !== 'item' || member.value.kind !== 'string')
|
|
144
|
+
continue;
|
|
145
|
+
const type = member.parameters.get('type');
|
|
146
|
+
// A directory is the one type this reads; the draft says to ignore others.
|
|
147
|
+
if (type !== undefined &&
|
|
148
|
+
!(type.kind === 'token' && type.value === 'directory'))
|
|
149
|
+
continue;
|
|
150
|
+
if (isHttpsUrl(member.value.value))
|
|
151
|
+
agents.set(label, {
|
|
152
|
+
url: member.value.value,
|
|
153
|
+
readable: readable(member.value.value),
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
if (agents.size === 0) {
|
|
157
|
+
// The bare string signers sent before the dictionary form.
|
|
158
|
+
try {
|
|
159
|
+
const item = parseItem(header);
|
|
160
|
+
if (item.value.kind === 'string' && isHttpsUrl(item.value.value))
|
|
161
|
+
agents.set(null, {
|
|
162
|
+
url: item.value.value,
|
|
163
|
+
readable: readable(item.value.value),
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
catch (error) {
|
|
167
|
+
if (!(error instanceof StructuredFieldError))
|
|
168
|
+
throw error;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
return agents;
|
|
172
|
+
}
|
|
173
|
+
function isHttpsUrl(value) {
|
|
174
|
+
const url = URL.parse(value);
|
|
175
|
+
return url !== null && url.protocol === 'https:';
|
|
176
|
+
}
|
|
177
|
+
/** A hostname that is an address rather than a name, or a name that is never public. */
|
|
178
|
+
const ADDRESS_OR_PRIVATE_HOST = /^(?:\d{1,3}(?:\.\d{1,3}){3}|\[.*\]|localhost|.*\.(?:localhost|local|internal|arpa))$/iu;
|
|
179
|
+
/**
|
|
180
|
+
* A URL this verifier will read a directory from: HTTPS, on its default
|
|
181
|
+
* port, with no credentials, at a public name that is a listed signer's or
|
|
182
|
+
* under one. The caller chooses the URL, so nothing else is ever contacted
|
|
183
|
+
* from the edge that runs this.
|
|
184
|
+
*/
|
|
185
|
+
function isAgentUrl(value, signers) {
|
|
186
|
+
const url = URL.parse(value);
|
|
187
|
+
if (url === null)
|
|
188
|
+
return false;
|
|
189
|
+
if (url.protocol !== 'https:' ||
|
|
190
|
+
url.port !== '' ||
|
|
191
|
+
url.username !== '' ||
|
|
192
|
+
url.password !== '' ||
|
|
193
|
+
!url.hostname.includes('.') ||
|
|
194
|
+
ADDRESS_OR_PRIVATE_HOST.test(url.hostname))
|
|
195
|
+
return false;
|
|
196
|
+
const host = url.hostname.toLowerCase();
|
|
197
|
+
for (const signer of signers)
|
|
198
|
+
if (host === signer || host.endsWith(`.${signer}`))
|
|
199
|
+
return true;
|
|
200
|
+
return false;
|
|
201
|
+
}
|
|
202
|
+
/** The parameters the draft requires on the signature, or null where one is missing or mistyped. */
|
|
203
|
+
function parametersOf(list) {
|
|
204
|
+
const keyId = list.parameters.get('keyid');
|
|
205
|
+
const created = list.parameters.get('created');
|
|
206
|
+
const expires = list.parameters.get('expires');
|
|
207
|
+
const alg = list.parameters.get('alg');
|
|
208
|
+
if (keyId?.kind !== 'string' ||
|
|
209
|
+
created?.kind !== 'integer' ||
|
|
210
|
+
expires?.kind !== 'integer' ||
|
|
211
|
+
(alg !== undefined && alg.kind !== 'string'))
|
|
212
|
+
return null;
|
|
213
|
+
return {
|
|
214
|
+
keyId: keyId.value,
|
|
215
|
+
created: created.value,
|
|
216
|
+
expires: expires.value,
|
|
217
|
+
alg: alg === undefined ? null : alg.value,
|
|
218
|
+
};
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* A covered component's value, as RFC 9421 derives it from the request: the
|
|
222
|
+
* derived components an agent signs, and a header, whole or one member of
|
|
223
|
+
* it. A component this does not derive is unsupported, never guessed.
|
|
224
|
+
*/
|
|
225
|
+
function componentValue(component, request, url) {
|
|
226
|
+
if (component.value.kind !== 'string')
|
|
227
|
+
return { kind: 'unsupported' };
|
|
228
|
+
const name = component.value.value;
|
|
229
|
+
const parameters = component.parameters;
|
|
230
|
+
if (name.startsWith('@')) {
|
|
231
|
+
if (parameters.size > 0)
|
|
232
|
+
return { kind: 'unsupported' };
|
|
233
|
+
switch (name) {
|
|
234
|
+
case '@method':
|
|
235
|
+
// As sent: a method's name is case-sensitive.
|
|
236
|
+
return { kind: 'value', value: request.method };
|
|
237
|
+
case '@target-uri':
|
|
238
|
+
return { kind: 'value', value: url.href };
|
|
239
|
+
case '@authority':
|
|
240
|
+
return { kind: 'value', value: url.host.toLowerCase() };
|
|
241
|
+
case '@scheme':
|
|
242
|
+
return { kind: 'value', value: url.protocol.slice(0, -1) };
|
|
243
|
+
case '@path':
|
|
244
|
+
return { kind: 'value', value: url.pathname };
|
|
245
|
+
case '@query':
|
|
246
|
+
return { kind: 'value', value: url.search === '' ? '?' : url.search };
|
|
247
|
+
default:
|
|
248
|
+
return { kind: 'unsupported' };
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
const held = request.headers.get(name.toLowerCase());
|
|
252
|
+
if (held === null)
|
|
253
|
+
return { kind: 'missing' };
|
|
254
|
+
const key = parameters.get('key');
|
|
255
|
+
for (const flag of parameters.keys())
|
|
256
|
+
if (flag !== 'key')
|
|
257
|
+
return { kind: 'unsupported' };
|
|
258
|
+
if (key === undefined)
|
|
259
|
+
return { kind: 'value', value: held.trim() };
|
|
260
|
+
if (key.kind !== 'string')
|
|
261
|
+
return { kind: 'unsupported' };
|
|
262
|
+
let members;
|
|
263
|
+
try {
|
|
264
|
+
members = parseDictionary(held);
|
|
265
|
+
}
|
|
266
|
+
catch (error) {
|
|
267
|
+
if (!(error instanceof StructuredFieldError))
|
|
268
|
+
throw error;
|
|
269
|
+
return { kind: 'missing' };
|
|
270
|
+
}
|
|
271
|
+
const member = members.get(key.value);
|
|
272
|
+
if (member === undefined)
|
|
273
|
+
return { kind: 'missing' };
|
|
274
|
+
return {
|
|
275
|
+
kind: 'value',
|
|
276
|
+
value: member.kind === 'item'
|
|
277
|
+
? serializeItem(member)
|
|
278
|
+
: serializeInnerList(member),
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
/** The signature base (RFC 9421, 2.5): each covered component's line, then the parameters. */
|
|
282
|
+
function signatureBase(list, request, url) {
|
|
283
|
+
const lines = [];
|
|
284
|
+
for (const component of list.items) {
|
|
285
|
+
const value = componentValue(component, request, url);
|
|
286
|
+
if (value.kind !== 'value')
|
|
287
|
+
return { kind: value.kind };
|
|
288
|
+
lines.push(`${serializeItem(component)}: ${value.value}`);
|
|
289
|
+
}
|
|
290
|
+
lines.push(`"@signature-params": ${serializeInnerList(list)}`);
|
|
291
|
+
return { kind: 'base', text: lines.join('\n') };
|
|
292
|
+
}
|
|
293
|
+
function isJwk(value) {
|
|
294
|
+
return (typeof value === 'object' &&
|
|
295
|
+
value !== null &&
|
|
296
|
+
'kty' in value &&
|
|
297
|
+
typeof value.kty === 'string');
|
|
298
|
+
}
|
|
299
|
+
/** The seconds a `Cache-Control` lets a directory be kept, or null when it says none. */
|
|
300
|
+
function maxAgeOf(cacheControl) {
|
|
301
|
+
const match = /(?:^|,)\s*max-age=(\d+)/iu.exec(cacheControl ?? '');
|
|
302
|
+
return match?.[1] === undefined ? null : Number(match[1]);
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* The directories read so far, kept until their `max-age` passes; one read
|
|
306
|
+
* at a time per directory, shared by the requests waiting on it; a
|
|
307
|
+
* directory that could not be read is not asked again for a minute, and an
|
|
308
|
+
* earlier copy of it stays, since an outage is not evidence.
|
|
309
|
+
*/
|
|
310
|
+
class Directories {
|
|
311
|
+
fetcher;
|
|
312
|
+
now;
|
|
313
|
+
held = new Map();
|
|
314
|
+
reading = new Map();
|
|
315
|
+
failedAt = new Map();
|
|
316
|
+
constructor(fetcher, now) {
|
|
317
|
+
this.fetcher = fetcher;
|
|
318
|
+
this.now = now;
|
|
319
|
+
}
|
|
320
|
+
async read(agent) {
|
|
321
|
+
const address = new URL(DIRECTORY_PATH, agent).href;
|
|
322
|
+
const now = this.now();
|
|
323
|
+
const kept = this.held.get(address);
|
|
324
|
+
if (kept !== undefined && kept.until > now)
|
|
325
|
+
return { kind: 'read', directory: kept.directory };
|
|
326
|
+
const failed = this.failedAt.get(address);
|
|
327
|
+
if (failed !== undefined && now - failed < DIRECTORY_RETRY_MS)
|
|
328
|
+
return kept === undefined
|
|
329
|
+
? { kind: 'unreachable' }
|
|
330
|
+
: { kind: 'read', directory: kept.directory };
|
|
331
|
+
const underWay = this.reading.get(address);
|
|
332
|
+
if (underWay !== undefined)
|
|
333
|
+
return underWay;
|
|
334
|
+
const reading = (async () => {
|
|
335
|
+
try {
|
|
336
|
+
const read = await this.fetchDirectory(address);
|
|
337
|
+
if (read.kind === 'read')
|
|
338
|
+
this.failedAt.delete(address);
|
|
339
|
+
else {
|
|
340
|
+
this.remember(this.failedAt, address, this.now(), MAX_FAILURES);
|
|
341
|
+
if (kept !== undefined)
|
|
342
|
+
return { kind: 'read', directory: kept.directory };
|
|
343
|
+
}
|
|
344
|
+
return read;
|
|
345
|
+
}
|
|
346
|
+
finally {
|
|
347
|
+
// Whatever became of it, the next check reads again.
|
|
348
|
+
this.reading.delete(address);
|
|
349
|
+
}
|
|
350
|
+
})();
|
|
351
|
+
this.reading.set(address, reading);
|
|
352
|
+
return reading;
|
|
353
|
+
}
|
|
354
|
+
/** Keeps a value, and forgets the oldest once more than `most` are kept. */
|
|
355
|
+
remember(kept, address, value, most) {
|
|
356
|
+
kept.delete(address);
|
|
357
|
+
kept.set(address, value);
|
|
358
|
+
for (const oldest of kept.keys()) {
|
|
359
|
+
if (kept.size <= most)
|
|
360
|
+
break;
|
|
361
|
+
kept.delete(oldest);
|
|
362
|
+
}
|
|
363
|
+
}
|
|
364
|
+
async fetchDirectory(address) {
|
|
365
|
+
let body;
|
|
366
|
+
let cacheControl;
|
|
367
|
+
try {
|
|
368
|
+
const response = await this.fetcher(address, {
|
|
369
|
+
headers: { accept: DIRECTORY_MEDIA_TYPE },
|
|
370
|
+
// The draft forbids following a redirect to a directory.
|
|
371
|
+
redirect: 'manual',
|
|
372
|
+
signal: AbortSignal.timeout(DIRECTORY_TIMEOUT_MS),
|
|
373
|
+
});
|
|
374
|
+
if (response.status !== 200)
|
|
375
|
+
return { kind: 'unreachable' };
|
|
376
|
+
cacheControl = response.headers.get('cache-control');
|
|
377
|
+
body = await response.json();
|
|
378
|
+
}
|
|
379
|
+
catch (error) {
|
|
380
|
+
// The network, TLS, the deadline (on the headers or the body) or a
|
|
381
|
+
// body that is not JSON: the directory is unreachable, which is what
|
|
382
|
+
// the caller is told; the reason is not evidence either.
|
|
383
|
+
if (error instanceof DOMException ||
|
|
384
|
+
error instanceof TypeError ||
|
|
385
|
+
error instanceof SyntaxError)
|
|
386
|
+
return { kind: 'unreachable' };
|
|
387
|
+
throw error;
|
|
388
|
+
}
|
|
389
|
+
if (typeof body !== 'object' ||
|
|
390
|
+
body === null ||
|
|
391
|
+
!('keys' in body) ||
|
|
392
|
+
!Array.isArray(body.keys))
|
|
393
|
+
return { kind: 'unreachable' };
|
|
394
|
+
const directory = { keys: body.keys.filter(isJwk) };
|
|
395
|
+
const maxAge = maxAgeOf(cacheControl);
|
|
396
|
+
const ttl = maxAge === null
|
|
397
|
+
? DIRECTORY_DEFAULT_TTL_MS
|
|
398
|
+
: Math.min(maxAge * 1_000, DIRECTORY_MAX_TTL_MS);
|
|
399
|
+
this.remember(this.held, address, { directory, until: this.now() + ttl }, MAX_DIRECTORIES);
|
|
400
|
+
return { kind: 'read', directory };
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
/** The key in a directory a signature names, by the thumbprint the draft requires or the `kid` the key carries. */
|
|
404
|
+
async function keyNamed(directory, keyId) {
|
|
405
|
+
for (const key of directory.keys) {
|
|
406
|
+
if (key.kid === keyId)
|
|
407
|
+
return key;
|
|
408
|
+
if ((await keyThumbprint(key)) === keyId)
|
|
409
|
+
return key;
|
|
410
|
+
}
|
|
411
|
+
return null;
|
|
412
|
+
}
|
|
413
|
+
/**
|
|
414
|
+
* A verifier of requests' Web Bot Auth signatures. One per runtime: it keeps
|
|
415
|
+
* the directories it has read, so a signer's keys are fetched once per
|
|
416
|
+
* `max-age`, not once per request.
|
|
417
|
+
*/
|
|
418
|
+
export function createSignatureVerifier(options = {}) {
|
|
419
|
+
const now = options.now ?? Date.now;
|
|
420
|
+
const directories = new Directories(options.fetch ?? fetch, now);
|
|
421
|
+
const signers = new Set([...KNOWN_SIGNERS, ...(options.signers ?? [])].map((host) => host.toLowerCase()));
|
|
422
|
+
const readable = (url) => isAgentUrl(url, signers);
|
|
423
|
+
return async (request) => {
|
|
424
|
+
const agentHeader = request.headers.get('signature-agent');
|
|
425
|
+
if (agentHeader === null)
|
|
426
|
+
return null;
|
|
427
|
+
const agents = agentsOf(agentHeader, readable);
|
|
428
|
+
const first = agents.values().next();
|
|
429
|
+
const named = first.done ? agentHeader.trim() : first.value.url;
|
|
430
|
+
// An empty header names no one: no claim was made.
|
|
431
|
+
if (named === '')
|
|
432
|
+
return null;
|
|
433
|
+
// Cut to what the collector takes, so a claim never refuses the call
|
|
434
|
+
// that carries it; the check itself read the values whole.
|
|
435
|
+
const claim = (outcome, keyId = null, agent = named) => ({
|
|
436
|
+
agent: agent.slice(0, AGENT_LENGTH),
|
|
437
|
+
keyId: keyId?.slice(0, KEY_ID_LENGTH) ?? null,
|
|
438
|
+
outcome,
|
|
439
|
+
});
|
|
440
|
+
// A header naming no HTTPS URL at all is a claim of nothing checkable.
|
|
441
|
+
if (first.done)
|
|
442
|
+
return claim('invalid');
|
|
443
|
+
const inputHeader = request.headers.get('signature-input');
|
|
444
|
+
const signatureHeader = request.headers.get('signature');
|
|
445
|
+
if (inputHeader === null || signatureHeader === null)
|
|
446
|
+
return claim('invalid');
|
|
447
|
+
let inputs;
|
|
448
|
+
let signatures;
|
|
449
|
+
try {
|
|
450
|
+
inputs = parseDictionary(inputHeader);
|
|
451
|
+
signatures = parseDictionary(signatureHeader);
|
|
452
|
+
}
|
|
453
|
+
catch (error) {
|
|
454
|
+
if (!(error instanceof StructuredFieldError))
|
|
455
|
+
throw error;
|
|
456
|
+
return claim('invalid');
|
|
457
|
+
}
|
|
458
|
+
const signed = [...inputs].flatMap(([name, member]) => {
|
|
459
|
+
const tag = member.parameters.get('tag');
|
|
460
|
+
return member.kind === 'inner-list' &&
|
|
461
|
+
tag?.kind === 'string' &&
|
|
462
|
+
tag.value === TAG
|
|
463
|
+
? [[name, member]]
|
|
464
|
+
: [];
|
|
465
|
+
})[0];
|
|
466
|
+
if (signed === undefined)
|
|
467
|
+
return claim('invalid');
|
|
468
|
+
const [label, list] = signed;
|
|
469
|
+
const parameters = parametersOf(list);
|
|
470
|
+
if (parameters === null)
|
|
471
|
+
return claim('invalid');
|
|
472
|
+
const { keyId } = parameters;
|
|
473
|
+
const agentComponent = list.items.find((item) => item.value.kind === 'string' && item.value.value === 'signature-agent');
|
|
474
|
+
const coversTarget = list.items.some((item) => item.value.kind === 'string' &&
|
|
475
|
+
(item.value.value === '@authority' ||
|
|
476
|
+
item.value.value === '@target-uri'));
|
|
477
|
+
if (agentComponent === undefined || !coversTarget)
|
|
478
|
+
return claim('invalid', keyId);
|
|
479
|
+
const memberKey = agentComponent.parameters.get('key');
|
|
480
|
+
const signedAgent = memberKey === undefined
|
|
481
|
+
? first.value
|
|
482
|
+
: memberKey.kind === 'string'
|
|
483
|
+
? agents.get(memberKey.value)
|
|
484
|
+
: undefined;
|
|
485
|
+
if (signedAgent === undefined)
|
|
486
|
+
return claim('invalid', keyId);
|
|
487
|
+
const agent = signedAgent.url;
|
|
488
|
+
// A URL this verifier will not read a directory from (an address, a
|
|
489
|
+
// private name, a port, credentials) is a claim it cannot check, never
|
|
490
|
+
// one it found false, and never one it checks against another member.
|
|
491
|
+
if (!signedAgent.readable)
|
|
492
|
+
return claim('unsupported', keyId, agent);
|
|
493
|
+
const moment = now();
|
|
494
|
+
if (parameters.created * 1_000 > moment + CREATED_SKEW_MS)
|
|
495
|
+
return claim('invalid', keyId, agent);
|
|
496
|
+
if (parameters.expires * 1_000 <= moment)
|
|
497
|
+
return claim('invalid', keyId, agent);
|
|
498
|
+
const signature = signatures.get(label);
|
|
499
|
+
if (signature?.kind !== 'item' || signature.value.kind !== 'bytes')
|
|
500
|
+
return claim('invalid', keyId, agent);
|
|
501
|
+
const url = URL.parse(request.url);
|
|
502
|
+
if (url === null)
|
|
503
|
+
return claim('invalid', keyId, agent);
|
|
504
|
+
const base = signatureBase(list, request, url);
|
|
505
|
+
if (base.kind === 'unsupported')
|
|
506
|
+
return claim('unsupported', keyId, agent);
|
|
507
|
+
if (base.kind === 'missing')
|
|
508
|
+
return claim('invalid', keyId, agent);
|
|
509
|
+
const read = await directories.read(agent);
|
|
510
|
+
if (read.kind === 'unreachable')
|
|
511
|
+
return claim('directory_unreachable', keyId, agent);
|
|
512
|
+
const key = await keyNamed(read.directory, keyId);
|
|
513
|
+
if (key === null)
|
|
514
|
+
return claim('invalid', keyId, agent);
|
|
515
|
+
const publicKey = publicKeyOf(key);
|
|
516
|
+
if (publicKey === null)
|
|
517
|
+
return claim('unsupported', keyId, agent);
|
|
518
|
+
if (parameters.alg !== null && parameters.alg !== publicKey.algorithm)
|
|
519
|
+
return claim('invalid', keyId, agent);
|
|
520
|
+
let imported;
|
|
521
|
+
try {
|
|
522
|
+
imported = await importKey(publicKey);
|
|
523
|
+
}
|
|
524
|
+
catch (error) {
|
|
525
|
+
// A key the directory published that WebCrypto cannot read is the
|
|
526
|
+
// signer's defect, not a forgery.
|
|
527
|
+
if (error instanceof DOMException || error instanceof TypeError)
|
|
528
|
+
return claim('unsupported', keyId, agent);
|
|
529
|
+
throw error;
|
|
530
|
+
}
|
|
531
|
+
const checks = await crypto.subtle.verify(verifyParameters(publicKey.algorithm), imported, signature.value.value, encoder.encode(base.text));
|
|
532
|
+
return claim(checks ? 'verified' : 'invalid', keyId, agent);
|
|
533
|
+
};
|
|
534
|
+
}
|
package/package.json
CHANGED
|
@@ -1,11 +1,36 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentrail-core",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "What every Agentrail component shares: the event the collector takes, markers, the keyed hash, W3C trace context, and the client that sends events.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://github.com/agentrail-co/agentrail-js.git",
|
|
9
9
|
"directory": "packages/core"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/agentrail-co/agentrail-js/tree/main/packages/core#readme",
|
|
12
|
+
"type": "module",
|
|
13
|
+
"exports": {
|
|
14
|
+
".": {
|
|
15
|
+
"types": "./dist/index.d.ts",
|
|
16
|
+
"import": "./dist/index.js"
|
|
17
|
+
}
|
|
18
|
+
},
|
|
19
|
+
"files": [
|
|
20
|
+
"dist",
|
|
21
|
+
"README.md",
|
|
22
|
+
"LICENSE"
|
|
23
|
+
],
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=22"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"@types/node": "24.13.3",
|
|
29
|
+
"agentrail-contract": "0.0.0"
|
|
30
|
+
},
|
|
31
|
+
"scripts": {
|
|
32
|
+
"build": "tsc -p tsconfig.build.json",
|
|
33
|
+
"typecheck": "tsc --noEmit",
|
|
34
|
+
"test": "vitest run"
|
|
10
35
|
}
|
|
11
|
-
}
|
|
36
|
+
}
|