@datalayer/agent-runtimes 1.3.111 → 1.3.113

package/lib/protocols/web-bot-auth/index.js

@@ -0,0 +1,427 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Web Bot Auth: an agent's requests signed, and verified
+ * (AGENT_PROTOCOLS PR-20 to PR-23).
+ *
+ * Implements `draft-ietf-webbotauth-httpsig-protocol-00` (2026-09-01) by
+ * wrapping Cloudflare's `web-bot-auth` 0.2.0, which reproduces the draft's
+ * Ed25519 vector E.2.1 byte for byte. What is added here is what an agent
+ * runtime needs around it:
+ *
+ * - a signer that is a callable the host owns (`protocols.httpSigner`; Vault
+ *   transit in Datalayer): the key never reaches the runtime;
+ * - `signedFetch`, a `fetch` that signs every request it sends;
+ * - the key directory and its signed response (Appendix B);
+ * - verification with keys found by (agent URL, keyid), freshness and an
+ *   atomic nonce check, answering `verified`, `invalid` or `unverified`.
+ *
+ * The Python package `agent_runtimes.protocols.web_bot_auth` is the same
+ * protocol, and both read `fixtures/vectors.json` (PR-51).
+ *
+ * @module protocols/web-bot-auth
+ */
+import { HTTP_MESSAGE_SIGNATURES_DIRECTORY, HTTP_MESSAGE_SIGNATURE_TAG, SIGNATURE_AGENT_HEADER, generateNonce, jwkToKeyID, parseSignatureAgentHeader, sign, verify, } from 'web-bot-auth';
+import { verifierFromJWK } from 'web-bot-auth/crypto';
+import { contribution, defineContributionPoint, definePlugin, } from '@datalayer/reactor';
+import { DEFAULT_ORDER, ProtocolDescriptions, firstContribution, optionalContribution, } from '../core';
+/** The specification implemented. */
+export const WEB_BOT_AUTH_SPECIFICATION = 'draft-ietf-webbotauth-httpsig-protocol-00';
+/** Where an agent's key directory is served. */
+export const DIRECTORY_PATH = HTTP_MESSAGE_SIGNATURES_DIRECTORY;
+/** The directory's media type. */
+export const DIRECTORY_MEDIA_TYPE = 'application/http-message-signatures-directory+json';
+/** The tag of a directory response's signature. */
+export const DIRECTORY_TAG = 'http-message-signatures-directory';
+export const TAG = HTTP_MESSAGE_SIGNATURE_TAG;
+export { generateNonce };
+function base64url(bytes) {
+    return base64(bytes)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+/** The base64url SHA-256 thumbprint of a public JWK (RFC 7638, RFC 8037): the draft's `keyid`. */
+export function jwkThumbprint(jwk) {
+    return jwkToKeyID(jwk, (data) => crypto.subtle.digest('SHA-256', data), (hash) => base64url(new Uint8Array(hash)));
+}
+function toWebBotSigner(signer) {
+    return {
+        keyid: signer.keyid,
+        algorithm: signer.algorithm,
+        sign: (data) => signer.sign(data),
+    };
+}
+/** A signer whose key is in this page or process: tests and examples only. */
+export async function localSigner(privateJwk) {
+    if (privateJwk.kty !== 'OKP' ||
+        privateJwk.crv !== 'Ed25519' ||
+        !privateJwk.d) {
+        throw new Error('a local signer takes an Ed25519 private JWK');
+    }
+    const key = await crypto.subtle.importKey('jwk', privateJwk, { name: 'Ed25519' }, false, ['sign']);
+    const keyid = await jwkThumbprint(publicJwkOf(privateJwk));
+    return {
+        keyid,
+        algorithm: 'ed25519',
+        async sign(data) {
+            return new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, data));
+        },
+    };
+}
+export async function generateLocalSigner() {
+    const pair = (await crypto.subtle.generateKey({ name: 'Ed25519' }, true, [
+        'sign',
+        'verify',
+    ]));
+    const privateJwk = await crypto.subtle.exportKey('jwk', pair.privateKey);
+    const signer = await localSigner(privateJwk);
+    return {
+        signer,
+        publicJwk: { ...publicJwkOf(privateJwk), kid: signer.keyid },
+    };
+}
+/** The public members of a JWK. */
+export function publicJwkOf(jwk) {
+    if (jwk.kty === 'OKP') {
+        return { kty: 'OKP', crv: jwk.crv, x: jwk.x };
+    }
+    if (jwk.kty === 'EC') {
+        return { kty: 'EC', crv: jwk.crv, x: jwk.x, y: jwk.y };
+    }
+    throw new Error(`key type ${jwk.kty} is not supported`);
+}
+/**
+ * Sign one request: the `Signature-Agent` member, `@authority`, and —
+ * narrower than the draft's minimum, as its §5.2 advises — `@method` and
+ * `@path`.
+ */
+export async function signRequest(request, signer, options) {
+    if (!options.agent.startsWith('https://')) {
+        throw new Error('a Signature-Agent is an https URI');
+    }
+    const label = options.label ?? 'sig1';
+    const discovery = options.discovery ?? 'directory';
+    const agentHeader = `${label}="${options.agent}"` +
+        (discovery === 'directory' ? '' : `;type=${discovery}`);
+    const created = options.created ?? new Date();
+    const lifetime = options.lifetime ?? 60;
+    if (lifetime > 24 * 60 * 60) {
+        throw new Error('a Web Bot Auth signature lives at most 24 hours');
+    }
+    const expires = options.expires ?? new Date(created.getTime() + lifetime * 1000);
+    const headers = new Headers(request.headers);
+    headers.set(SIGNATURE_AGENT_HEADER, agentHeader);
+    const withAgent = new Request(request, { headers });
+    const fields = await sign(withAgent, {
+        signer: toWebBotSigner(signer),
+        created,
+        expires,
+        label,
+        nonce: options.nonce ?? generateNonce(),
+        signatureAgentKey: label,
+        additionalComponents: (options.components ?? ['@method', '@path', '@query']).filter(name => name !== '@authority'),
+    });
+    return {
+        'Signature-Agent': agentHeader,
+        'Signature-Input': fields.signatureInput,
+        Signature: fields.signature,
+    };
+}
+/** A `fetch` that signs every request it sends. */
+export function signedFetch(signer, options, fetchImpl = fetch) {
+    return async (input, init) => {
+        const request = new Request(input, init);
+        const signed = await signRequest(request, signer, options);
+        const headers = new Headers(request.headers);
+        for (const [name, value] of Object.entries(signed)) {
+            headers.set(name, value);
+        }
+        return fetchImpl(new Request(request, { headers }));
+    };
+}
+/** The directory's body: public keys only, each `kid` its thumbprint. */
+export async function directoryBody(keys) {
+    const out = [];
+    for (const jwk of keys) {
+        if ('d' in jwk && jwk.d) {
+            throw new Error('a key directory publishes public keys only');
+        }
+        const kid = await jwkThumbprint(publicJwkOf(jwk));
+        if (jwk.kid &&
+            jwk.kid !== kid) {
+            throw new Error("a directory key's kid is its thumbprint");
+        }
+        out.push({ ...jwk, kid });
+    }
+    return JSON.stringify({ keys: out });
+}
+function base64(bytes) {
+    let text = '';
+    for (const byte of bytes) {
+        text += String.fromCharCode(byte);
+    }
+    return btoa(text);
+}
+/** The `Content-Digest` of a body, SHA-256 (RFC 9530). */
+export async function contentDigest(body) {
+    const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : body;
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+    return `sha-256=:${base64(digest)}:`;
+}
+function authorityOf(url) {
+    return new URL(url).host.toLowerCase();
+}
+/**
+ * Sign a directory response with every key it lists (Appendix B): the
+ * signature covers `"@authority";req` and `content-digest`.
+ */
+export async function signDirectoryResponse(body, authorityUrl, signers, options = {}) {
+    if (!signers.length) {
+        throw new Error('a directory is signed by the keys it publishes');
+    }
+    const listed = new Set(JSON.parse(body).keys.map(key => key.kid));
+    const created = options.created ?? Math.floor(Date.now() / 1000);
+    const expires = options.expires ?? created + (options.lifetime ?? 300);
+    const digest = await contentDigest(body);
+    const inputs = [];
+    const signatures = [];
+    for (const [index, signer] of signers.entries()) {
+        if (!listed.has(signer.keyid)) {
+            throw new Error(`key ${signer.keyid} signs a directory that does not list it`);
+        }
+        const label = index === 0 ? 'binding' : `binding${index}`;
+        const params = `("@authority";req "content-digest");created=${created};expires=${expires}` +
+            `;keyid="${signer.keyid}";tag="${DIRECTORY_TAG}"`;
+        const base = `"@authority";req: ${authorityOf(authorityUrl)}\n` +
+            `"content-digest": ${digest}\n` +
+            `"@signature-params": ${params}`;
+        const signature = await signer.sign(new TextEncoder().encode(base));
+        inputs.push(`${label}=${params}`);
+        signatures.push(`${label}=:${base64(signature)}:`);
+    }
+    return {
+        'Content-Type': DIRECTORY_MEDIA_TYPE,
+        'Content-Digest': digest,
+        'Signature-Input': inputs.join(', '),
+        Signature: signatures.join(', '),
+    };
+}
+/** A nonce store for one page or process. */
+export class InMemoryNonceStore {
+    seen = new Map();
+    async checkAndRecord(scope, nonce, until) {
+        const now = Date.now();
+        for (const [key, end] of this.seen) {
+            if (end < now) {
+                this.seen.delete(key);
+            }
+        }
+        const key = `${scope} ${nonce}`;
+        if (this.seen.has(key)) {
+            return false;
+        }
+        this.seen.set(key, until.getTime());
+        return true;
+    }
+}
+async function fetchChecked(fetchImpl, url, insecureHosts) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' &&
+        !insecureHosts.includes(parsed.hostname)) {
+        throw new Error('a key directory is fetched over https');
+    }
+    const response = await fetchImpl(url, {
+        headers: { Accept: DIRECTORY_MEDIA_TYPE },
+        redirect: 'manual',
+    });
+    if (response.status !== 200) {
+        throw new Error(`the key directory answered ${response.status}`);
+    }
+    return response;
+}
+/** `type=directory`: the origin's well-known directory, its Content-Digest checked. */
+export function directoryDiscovery(fetchImpl = (input, init) => fetch(input, init), insecureHosts = []) {
+    return {
+        async keys(agent) {
+            const origin = new URL(agent);
+            const url = `${origin.protocol}//${origin.host}${DIRECTORY_PATH}`;
+            const response = await fetchChecked(fetchImpl, url, insecureHosts);
+            const body = await response.text();
+            if (response.headers.get('content-digest') !== (await contentDigest(body))) {
+                throw new Error("the directory's Content-Digest does not match its body");
+            }
+            return JSON.parse(body).keys.map(publicJwkOf);
+        },
+    };
+}
+/** `type=jwks_uri`: a JWK Set at the URL itself. */
+export function jwksUriDiscovery(fetchImpl = (input, init) => fetch(input, init), insecureHosts = []) {
+    return {
+        async keys(agent) {
+            const response = await fetchChecked(fetchImpl, agent, insecureHosts);
+            return (await response.json()).keys.map(publicJwkOf);
+        },
+    };
+}
+/** A resolver over one discovery per `Signature-Agent` type; a type with none answers nothing. */
+export function keyResolver(discoveries) {
+    return async (agent, discovery) => {
+        const found = discoveries[discovery];
+        if (!found) {
+            return undefined;
+        }
+        try {
+            const keys = new Map();
+            for (const jwk of await found.keys(agent)) {
+                keys.set(await jwkThumbprint(jwk), jwk);
+            }
+            return keys;
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+/** The two discoveries this package implements, over one fetch. */
+export function directoryResolver(fetchImpl = (input, init) => fetch(input, init), insecureHosts = []) {
+    return keyResolver({
+        directory: directoryDiscovery(fetchImpl, insecureHosts),
+        jwks_uri: jwksUriDiscovery(fetchImpl, insecureHosts),
+    });
+}
+export const WEB_BOT_AUTH_PLUGIN = 'agent-runtimes.protocols.web-bot-auth';
+/** The host's signer: no default, the key is the host's. */
+export const WebBotAuthSigners = defineContributionPoint('web_bot_auth.signer');
+export const WebBotAuthNonceStores = defineContributionPoint('web_bot_auth.nonceStore');
+export const WebBotAuthDirectoryDiscoveries = defineContributionPoint('web_bot_auth.extension.directory');
+export const WebBotAuthJwksUriDiscoveries = defineContributionPoint('web_bot_auth.extension.jwks_uri');
+export const WebBotAuthCimdDiscoveries = defineContributionPoint('web_bot_auth.extension.cimd');
+const DISCOVERY_POINTS = {
+    directory: WebBotAuthDirectoryDiscoveries,
+    jwks_uri: WebBotAuthJwksUriDiscoveries,
+    cimd: WebBotAuthCimdDiscoveries,
+};
+const WEB_BOT_AUTH_POINTS = [
+    WebBotAuthSigners,
+    WebBotAuthNonceStores,
+    ...Object.values(DISCOVERY_POINTS),
+];
+export const WebBotAuthPlugin = definePlugin({
+    name: WEB_BOT_AUTH_PLUGIN,
+    version: '1.0.0',
+    description: `Web Bot Auth (${WEB_BOT_AUTH_SPECIFICATION}): sign an agent's requests, verify an agent's.`,
+    contributionPoints: WEB_BOT_AUTH_POINTS,
+    contributes: [
+        contribution(ProtocolDescriptions, {
+            id: 'web_bot_auth',
+            name: 'Web Bot Auth (HTTP Message Signatures for automated traffic)',
+            layer: 'identity',
+            version: WEB_BOT_AUTH_SPECIFICATION,
+            roles: ['signer', 'verifier', 'directory'],
+            status: 'implemented',
+            specification: 'https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/',
+            plugin: WEB_BOT_AUTH_PLUGIN,
+            points: WEB_BOT_AUTH_POINTS.map(point => point.id),
+        }, { id: 'web_bot_auth', order: DEFAULT_ORDER }),
+        contribution(WebBotAuthDirectoryDiscoveries, directoryDiscovery(), {
+            id: 'fetch',
+            order: DEFAULT_ORDER,
+        }),
+        contribution(WebBotAuthJwksUriDiscoveries, jwksUriDiscovery(), {
+            id: 'fetch',
+            order: DEFAULT_ORDER,
+        }),
+    ],
+    // One nonce store per reactor, not one per module: a store is state.
+    register: ctx => {
+        ctx.contribute(WebBotAuthNonceStores, new InMemoryNonceStore(), {
+            id: 'memory',
+            order: DEFAULT_ORDER,
+        });
+    },
+});
+/** The host's signer; throws when the host contributed none. */
+export function signerOf(reactor) {
+    return firstContribution(reactor, WebBotAuthSigners, 'Web Bot Auth signer');
+}
+/** A resolver over the discoveries contributed: one per type that has one. */
+export function resolverOf(reactor) {
+    const discoveries = {};
+    for (const [type, point] of Object.entries(DISCOVERY_POINTS)) {
+        const found = optionalContribution(reactor, point, `Web Bot Auth ${type} discovery`);
+        if (found) {
+            discoveries[type] = found;
+        }
+    }
+    return keyResolver(discoveries);
+}
+/**
+ * Verify the Web Bot Auth signature of one request. Keys are found by the
+ * pair (the covered `Signature-Agent` URL, `keyid`), never by `keyid` alone.
+ */
+export async function verifyRequest(request, resolveKeys, options = {}) {
+    if (!request.headers.get('signature') ||
+        !request.headers.get('signature-input')) {
+        return { outcome: 'unverified', reason: 'the request is not signed' };
+    }
+    const agentHeader = request.headers.get(SIGNATURE_AGENT_HEADER);
+    if (!agentHeader) {
+        return {
+            outcome: 'invalid',
+            reason: 'the request names no Signature-Agent',
+        };
+    }
+    let unresolved;
+    try {
+        const verified = await verify(request, {
+            now: options.now,
+            clockSkew: options.clockSkew,
+            resolver: async (candidate) => {
+                const entry = candidate.signatureAgent;
+                if (!entry) {
+                    throw new Error('the signature does not cover its Signature-Agent member');
+                }
+                const keys = await resolveKeys(entry.uri, entry.type);
+                const jwk = keys?.get(candidate.keyid);
+                if (!jwk) {
+                    unresolved = entry.uri;
+                    throw new Error('the key is not in the agent’s directory');
+                }
+                return (await verifierFromJWK(jwk));
+            },
+        });
+        const agent = verified.signatureAgent?.uri;
+        if (verified.nonce && options.nonceStore) {
+            const fresh = await options.nonceStore.checkAndRecord(`${agent} ${verified.keyid}`, verified.nonce, verified.expires);
+            if (!fresh) {
+                return {
+                    outcome: 'invalid',
+                    reason: 'the nonce was seen before',
+                    agent,
+                };
+            }
+        }
+        return {
+            outcome: 'verified',
+            agent,
+            keyid: verified.keyid,
+            created: verified.created,
+            expires: verified.expires,
+            nonce: verified.nonce,
+        };
+    }
+    catch (error) {
+        if (unresolved) {
+            return {
+                outcome: 'unverified',
+                reason: 'the key is not in the agent’s directory',
+                agent: unresolved,
+            };
+        }
+        return { outcome: 'invalid', reason: error.message };
+    }
+}
+export { parseSignatureAgentHeader };

package/lib/specs/actions.js

@@ -739,6 +739,7 @@ export const APP_BEHAVIOURS = {
         'earthdata.search_earth_datasets': 'do_it',
     },
     'event-response': {},
+    'exchange-desk': {},
     'inbox-triage': {
         'google-workspace.append_table_rows': 'leave_to_me',
         'google-workspace.batch_modify_gmail_message_labels': 'do_it',
@@ -913,6 +914,7 @@ export const APP_BEHAVIOURS = {
         'odoo-accounting.odoo_accounting_trial_balance': 'do_it',
         'odoo-accounting.odoo_accounting_unreconcile_lines': 'leave_to_me',
     },
+    'order-desk': {},
     'pipeline-report': {},
     'quote-calculator': {},
     'report-from-a-file': {},
@@ -941,6 +943,7 @@ export const APP_ESCALATIONS = {
     decide: {},
     'disaster-assessment': {},
     'event-response': {},
+    'exchange-desk': {},
     'inbox-triage': {
         'google-workspace.batch_modify_gmail_message_labels': [
             {
@@ -977,6 +980,7 @@ export const APP_ESCALATIONS = {
     },
     'model-choice': {},
     'month-end-close': {},
+    'order-desk': {},
     'pipeline-report': {},
     'quote-calculator': {},
     'report-from-a-file': {},

package/lib/specs/apps.d.ts

@@ -16,9 +16,11 @@ export declare const DATA_QUALITY_APP_0_0_1: AppSpec;
 export declare const DECIDE_APP_0_0_1: AppSpec;
 export declare const DISASTER_ASSESSMENT_APP_0_0_1: AppSpec;
 export declare const EVENT_RESPONSE_APP_0_0_1: AppSpec;
+export declare const EXCHANGE_DESK_APP_0_0_1: AppSpec;
 export declare const INBOX_TRIAGE_APP_0_0_1: AppSpec;
 export declare const MODEL_CHOICE_APP_0_0_1: AppSpec;
 export declare const MONTH_END_CLOSE_APP_0_0_1: AppSpec;
+export declare const ORDER_DESK_APP_0_0_1: AppSpec;
 export declare const PIPELINE_REPORT_APP_0_0_1: AppSpec;
 export declare const QUOTE_CALCULATOR_APP_0_0_1: AppSpec;
 export declare const REPORT_FROM_A_FILE_APP_0_0_1: AppSpec;