@datalayer/agent-runtimes 1.3.111 → 1.3.112

package/lib/protocols/ucp/index.js

@@ -0,0 +1,277 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Universal Commerce Protocol, `2026-08-25`, as a Reactor Plugin and a
+ * shopping client (AGENT_PROTOCOLS PR-30, PR-31) — the twin of
+ * `agent_runtimes.protocols.ucp`.
+ *
+ * Checkouts are read through the protocol's own TypeScript SDK
+ * (`@ucp-js/sdk` 0.5.1, zod schemas generated from the same JSON Schemas).
+ * A purchase is an exact, revisioned proposal (`proposeCompletion`), approved
+ * by the person through the host's `ucp.approver`, paid with the host's
+ * `ucp.paymentInstruments`, completed once (`ucp.proposalStore`).
+ *
+ * @module protocols/ucp
+ */
+import { contribution, defineContributionPoint, definePlugin, } from '@datalayer/reactor';
+import { ExtendedCheckoutResponseSchema } from '@ucp-js/sdk';
+import { InMemoryProposalStore, digest, } from '../commerce';
+import { DEFAULT_ORDER, ProtocolDescriptions, firstContribution, } from '../core';
+export const UCP_VERSION = '2026-08-25';
+export const SHOPPING_SERVICE = 'dev.ucp.shopping';
+export const CHECKOUT_CAPABILITY = 'dev.ucp.shopping.checkout';
+export const PROFILE_PATH = '/.well-known/ucp';
+export const UCP_PLUGIN = 'agent-runtimes.protocols.ucp';
+/** Each operation's action class (F-10), for Rules (R-05). */
+export const UCP_ACTION_CLASSES = {
+    search: 'read',
+    proposeCompletion: 'read',
+    getCheckout: 'read',
+    createCheckout: 'write',
+    updateCheckout: 'write',
+    cancelCheckout: 'write',
+    complete: 'buy',
+};
+export { InMemoryProposalStore, proposalSummary, } from '../commerce';
+export class UcpError extends Error {
+}
+export const UcpApprovers = defineContributionPoint('ucp.approver');
+export const UcpPaymentInstruments = defineContributionPoint('ucp.paymentInstruments');
+export const UcpProposalStores = defineContributionPoint('ucp.proposalStore');
+export const UcpFulfillmentExtensions = defineContributionPoint('ucp.extension.fulfillment');
+export const UcpDiscountExtensions = defineContributionPoint('ucp.extension.discount');
+export const UcpBuyerConsentExtensions = defineContributionPoint('ucp.extension.buyer_consent');
+const EXTENSION_POINTS = [
+    UcpFulfillmentExtensions,
+    UcpDiscountExtensions,
+    UcpBuyerConsentExtensions,
+];
+const UCP_POINTS = [
+    UcpApprovers,
+    UcpPaymentInstruments,
+    UcpProposalStores,
+    ...EXTENSION_POINTS,
+];
+export const UcpPlugin = definePlugin({
+    name: UCP_PLUGIN,
+    version: '1.0.0',
+    description: `Universal Commerce Protocol ${UCP_VERSION}: shop, propose, buy once approved.`,
+    contributionPoints: UCP_POINTS,
+    contributes: [
+        contribution(ProtocolDescriptions, {
+            id: 'ucp',
+            name: 'Universal Commerce Protocol',
+            layer: 'commerce',
+            version: UCP_VERSION,
+            roles: ['shopper'],
+            status: 'partial',
+            specification: `https://ucp.dev/${UCP_VERSION}/specification/overview`,
+            plugin: UCP_PLUGIN,
+            points: UCP_POINTS.map(point => point.id),
+        }, { id: 'ucp', order: DEFAULT_ORDER }),
+    ],
+    // One store per reactor, not one per module: a store is state.
+    register: ctx => {
+        ctx.contribute(UcpProposalStores, new InMemoryProposalStore(), {
+            id: 'memory',
+            order: DEFAULT_ORDER,
+        });
+    },
+});
+/** The capabilities in use with a business: checkout, and the extensions both support. */
+export function negotiateCapabilities(profile, reactor) {
+    const offered = new Set(Object.keys(profile?.ucp?.capabilities ?? {}));
+    if (!offered.has(CHECKOUT_CAPABILITY)) {
+        throw new UcpError('the business offers no checkout');
+    }
+    const active = [CHECKOUT_CAPABILITY];
+    for (const point of EXTENSION_POINTS) {
+        const [first] = reactor.getContributions(point);
+        if (first && offered.has(first.value.capability)) {
+            active.push(first.value.capability);
+        }
+    }
+    return active;
+}
+/** The revision of what a checkout buys; the same digest as Python's `revision_of`. */
+export function revisionOf(checkout) {
+    return digest({
+        id: checkout.id,
+        currency: checkout.currency,
+        line_items: (checkout.line_items ?? []).map((line) => ({
+            item: line.item?.id ?? null,
+            price: line.item?.price ?? null,
+            quantity: line.quantity,
+        })),
+        totals: (checkout.totals ?? []).map((total) => ({
+            type: total.type,
+            amount: total.amount,
+        })),
+    });
+}
+function readCheckout(body) {
+    if (body?.ucp?.status === 'error') {
+        const said = (body.messages ?? []).map((m) => m.content).join('; ');
+        throw new UcpError(`the business refused: ${said}`);
+    }
+    ExtendedCheckoutResponseSchema.parse(body);
+    return body;
+}
+/** What an agent may see of a checkout: no payment credential, no token. */
+export function checkoutSummary(checkout) {
+    return {
+        id: checkout.id,
+        status: checkout.status,
+        currency: checkout.currency,
+        lines: (checkout.line_items ?? []).map((line) => ({
+            title: line.item?.title ?? line.item?.id,
+            quantity: line.quantity,
+            price: line.item?.price,
+        })),
+        totals: Object.fromEntries((checkout.totals ?? []).map((t) => [t.type, t.amount])),
+        messages: (checkout.messages ?? []).map((m) => m.content),
+        ...(checkout.order ? { order: { id: checkout.order.id } } : {}),
+    };
+}
+/** A platform's client of one business, over the REST binding. */
+export class UcpClient {
+    business;
+    agentProfile;
+    fetchImpl;
+    endpoint;
+    domain;
+    constructor(business, agentProfile, fetchImpl = (input, init) => fetch(input, init)) {
+        this.business = business;
+        this.agentProfile = agentProfile;
+        this.fetchImpl = fetchImpl;
+        this.domain = new URL(business).hostname;
+    }
+    headers(idempotencyKey) {
+        return {
+            'UCP-Agent': `profile="${this.agentProfile}"`,
+            'Request-Id': crypto.randomUUID(),
+            'Content-Type': 'application/json',
+            ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+        };
+    }
+    /** Read the business's profile: the version, shopping over REST, checkout. */
+    async discover() {
+        const answer = await this.fetchImpl(`${this.business.replace(/\/$/, '')}${PROFILE_PATH}`);
+        if (answer.status !== 200) {
+            throw new UcpError(`${PROFILE_PATH} answered ${answer.status}`);
+        }
+        const profile = await answer.json();
+        const ucp = profile.ucp ?? {};
+        const versions = new Set([
+            ucp.version,
+            ...Object.keys(ucp.supported_versions ?? {}),
+        ]);
+        if (!versions.has(UCP_VERSION)) {
+            throw new UcpError(`the business does not speak UCP ${UCP_VERSION}`);
+        }
+        const rest = (ucp.services?.[SHOPPING_SERVICE] ?? []).find((service) => service.transport === 'rest' && service.endpoint);
+        if (!rest) {
+            throw new UcpError('the business offers no shopping service over REST');
+        }
+        if (!ucp.capabilities?.[CHECKOUT_CAPABILITY]) {
+            throw new UcpError('the business offers no checkout');
+        }
+        this.endpoint = String(rest.endpoint).replace(/\/$/, '');
+        return profile;
+    }
+    async call(method, path, body, key) {
+        if (!this.endpoint) {
+            await this.discover();
+        }
+        const answer = await this.fetchImpl(`${this.endpoint}${path}`, {
+            method,
+            headers: this.headers(key),
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (answer.status === 409) {
+            throw new UcpError('the idempotency key was reused with another request');
+        }
+        if (answer.status >= 400) {
+            throw new UcpError(`${method} ${path} answered ${answer.status}`);
+        }
+        return answer.json();
+    }
+    async search(query, limit = 10) {
+        return (await this.call('POST', '/catalog/search', {
+            query,
+            pagination: { limit },
+        })).products;
+    }
+    async createCheckout(lines, buyer) {
+        return readCheckout(await this.call('POST', '/checkout-sessions', {
+            line_items: lines.map(line => ({
+                item: { id: line.id },
+                quantity: line.quantity ?? 1,
+            })),
+            ...(buyer ? { buyer } : {}),
+        }, crypto.randomUUID()));
+    }
+    async updateCheckout(id, update) {
+        return readCheckout(await this.call('PUT', `/checkout-sessions/${id}`, update, crypto.randomUUID()));
+    }
+    async getCheckout(id) {
+        return readCheckout(await this.call('GET', `/checkout-sessions/${id}`));
+    }
+    async cancelCheckout(id) {
+        return readCheckout(await this.call('POST', `/checkout-sessions/${id}/cancel`, {}, crypto.randomUUID()));
+    }
+    /** The exact purchase a `ready_for_complete` checkout would make. */
+    async proposeCompletion(id) {
+        const checkout = await this.getCheckout(id);
+        if (checkout.status !== 'ready_for_complete') {
+            throw new UcpError(`the checkout is ${checkout.status}, not ready_for_complete`);
+        }
+        const total = checkout.totals.find(t => t.type === 'total');
+        if (!total) {
+            throw new UcpError('the checkout says no total');
+        }
+        return {
+            id: crypto.randomUUID(),
+            merchant: this.domain,
+            checkoutId: checkout.id,
+            revision: await revisionOf(checkout),
+            currency: checkout.currency,
+            total: total.amount,
+            lines: checkout.line_items.map(line => ({
+                title: line.item.title ?? line.item.id,
+                quantity: line.quantity,
+                price: line.item.price ?? 0,
+            })),
+            expiresAt: checkout.expires_at,
+        };
+    }
+    /** Complete an approved proposal, once: refused if unapproved, spent, changed or expired. */
+    async complete(proposal, reactor) {
+        if (proposal.expiresAt &&
+            new Date(proposal.expiresAt).getTime() <= Date.now()) {
+            throw new UcpError('the proposal has expired');
+        }
+        const approver = firstContribution(reactor, UcpApprovers, 'UCP approver');
+        const instruments = firstContribution(reactor, UcpPaymentInstruments, 'UCP payment instruments');
+        const store = firstContribution(reactor, UcpProposalStores, 'UCP proposal store');
+        // Spent before the person is asked: a proposal is put to them once, and a
+        // declined one is proposed again, never retried.
+        if (!(await store.take(proposal.id))) {
+            throw new UcpError('this proposal was used already');
+        }
+        if (!(await approver.approve(proposal))) {
+            throw new UcpError('the person did not approve this purchase');
+        }
+        const checkout = await this.getCheckout(proposal.checkoutId);
+        if (checkout.status !== 'ready_for_complete') {
+            throw new UcpError(`the checkout is ${checkout.status}, not ready_for_complete`);
+        }
+        if ((await revisionOf(checkout)) !== proposal.revision) {
+            throw new UcpError('the checkout changed since it was proposed: propose it again');
+        }
+        const instrument = await instruments.instrument(proposal, checkout.ucp?.payment_handlers ?? {});
+        return readCheckout(await this.call('POST', `/checkout-sessions/${proposal.checkoutId}/complete`, { payment: { instruments: [instrument] } }, proposal.id));
+    }
+}

package/lib/protocols/web-bot-auth/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 { generateNonce, parseSignatureAgentHeader, type WebBotAlgorithm } from 'web-bot-auth';
+import { type ReactorPlatformView } from '@datalayer/reactor';
+/** The specification implemented. */
+export declare const WEB_BOT_AUTH_SPECIFICATION = "draft-ietf-webbotauth-httpsig-protocol-00";
+/** Where an agent's key directory is served. */
+export declare const DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+/** The directory's media type. */
+export declare const DIRECTORY_MEDIA_TYPE = "application/http-message-signatures-directory+json";
+/** The tag of a directory response's signature. */
+export declare const DIRECTORY_TAG = "http-message-signatures-directory";
+export declare const TAG = "web-bot-auth";
+export { generateNonce };
+/** The base64url SHA-256 thumbprint of a public JWK (RFC 7638, RFC 8037): the draft's `keyid`. */
+export declare function jwkThumbprint(jwk: JsonWebKey): Promise<string>;
+/**
+ * Signs under one key the host holds. `sign` answers the raw signature
+ * (Ed25519's 64 bytes). The key is never passed to the runtime.
+ */
+export interface HttpSigner {
+    readonly keyid: string;
+    readonly algorithm: WebBotAlgorithm;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+}
+/** A signer whose key is in this page or process: tests and examples only. */
+export declare function localSigner(privateJwk: JsonWebKey): Promise<HttpSigner>;
+/** A fresh Ed25519 key: its signer and its public JWK. Tests and examples only. */
+/** A public JWK as a key directory lists it: its `kid` is its thumbprint. */
+export type PublicJwk = JsonWebKey & {
+    kid: string;
+};
+export declare function generateLocalSigner(): Promise<{
+    signer: HttpSigner;
+    publicJwk: PublicJwk;
+}>;
+/** The public members of a JWK. */
+export declare function publicJwkOf(jwk: JsonWebKey): JsonWebKey;
+/** How a request is signed. */
+export interface SignOptions {
+    /** Where the key directory is: the agent's origin, by default. */
+    agent: string;
+    /** `directory` (the default), `jwks_uri` or `cimd`. */
+    discovery?: 'directory' | 'jwks_uri' | 'cimd';
+    label?: string;
+    /** Seconds the signature lives; 60 by default, at most 24 hours. */
+    lifetime?: number;
+    created?: Date;
+    expires?: Date;
+    nonce?: string;
+    /**
+     * Covered besides `@authority` and the `Signature-Agent` member (always
+     * covered): `@method` and `@path` by default.
+     */
+    components?: string[];
+}
+/** The headers a signed request carries. */
+export interface SignedHeaders {
+    'Signature-Agent': string;
+    'Signature-Input': string;
+    Signature: string;
+}
+/**
+ * Sign one request: the `Signature-Agent` member, `@authority`, and —
+ * narrower than the draft's minimum, as its §5.2 advises — `@method` and
+ * `@path`.
+ */
+export declare function signRequest(request: Request, signer: HttpSigner, options: SignOptions): Promise<SignedHeaders>;
+/** A `fetch` that signs every request it sends. */
+export declare function signedFetch(signer: HttpSigner, options: SignOptions, fetchImpl?: typeof fetch): typeof fetch;
+/** The directory's body: public keys only, each `kid` its thumbprint. */
+export declare function directoryBody(keys: JsonWebKey[]): Promise<string>;
+/** The `Content-Digest` of a body, SHA-256 (RFC 9530). */
+export declare function contentDigest(body: string | Uint8Array): Promise<string>;
+/**
+ * Sign a directory response with every key it lists (Appendix B): the
+ * signature covers `"@authority";req` and `content-digest`.
+ */
+export declare function signDirectoryResponse(body: string, authorityUrl: string, signers: HttpSigner[], options?: {
+    created?: number;
+    expires?: number;
+    lifetime?: number;
+}): Promise<Record<string, string>>;
+/** What verifying a request found. */
+export interface Verification {
+    outcome: 'verified' | 'invalid' | 'unverified';
+    reason?: string;
+    agent?: string;
+    keyid?: string;
+    created?: Date;
+    expires?: Date;
+    nonce?: string;
+}
+/** Where nonces are remembered until their signature expires. */
+export interface NonceStore {
+    checkAndRecord(scope: string, nonce: string, until: Date): Promise<boolean>;
+}
+/** A nonce store for one page or process. */
+export declare class InMemoryNonceStore implements NonceStore {
+    private seen;
+    checkAndRecord(scope: string, nonce: string, until: Date): Promise<boolean>;
+}
+/**
+ * How an agent's keys are found for one `Signature-Agent` type: each type is
+ * an extension of the protocol, the point `web_bot_auth.extension.<type>`.
+ * Throws when the keys cannot be read.
+ */
+export interface KeyDiscovery {
+    keys(agent: string): Promise<JsonWebKey[]>;
+}
+/** `type=directory`: the origin's well-known directory, its Content-Digest checked. */
+export declare function directoryDiscovery(fetchImpl?: typeof fetch, insecureHosts?: string[]): KeyDiscovery;
+/** `type=jwks_uri`: a JWK Set at the URL itself. */
+export declare function jwksUriDiscovery(fetchImpl?: typeof fetch, insecureHosts?: string[]): KeyDiscovery;
+/** Public keys of an agent, by thumbprint; `undefined` when they could not be read. */
+export type KeyResolver = (agent: string, discovery: string) => Promise<Map<string, JsonWebKey> | undefined>;
+/** A resolver over one discovery per `Signature-Agent` type; a type with none answers nothing. */
+export declare function keyResolver(discoveries: Record<string, KeyDiscovery>): KeyResolver;
+/** The two discoveries this package implements, over one fetch. */
+export declare function directoryResolver(fetchImpl?: typeof fetch, insecureHosts?: string[]): KeyResolver;
+export declare const WEB_BOT_AUTH_PLUGIN = "agent-runtimes.protocols.web-bot-auth";
+/** The host's signer: no default, the key is the host's. */
+export declare const WebBotAuthSigners: import("@datalayer/reactor").ContributionPoint<HttpSigner>;
+export declare const WebBotAuthNonceStores: import("@datalayer/reactor").ContributionPoint<NonceStore>;
+export declare const WebBotAuthDirectoryDiscoveries: import("@datalayer/reactor").ContributionPoint<KeyDiscovery>;
+export declare const WebBotAuthJwksUriDiscoveries: import("@datalayer/reactor").ContributionPoint<KeyDiscovery>;
+export declare const WebBotAuthCimdDiscoveries: import("@datalayer/reactor").ContributionPoint<KeyDiscovery>;
+export declare const WebBotAuthPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+/** The host's signer; throws when the host contributed none. */
+export declare function signerOf(reactor: ReactorPlatformView): HttpSigner;
+/** A resolver over the discoveries contributed: one per type that has one. */
+export declare function resolverOf(reactor: ReactorPlatformView): KeyResolver;
+/**
+ * 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 declare function verifyRequest(request: Request, resolveKeys: KeyResolver, options?: {
+    nonceStore?: NonceStore;
+    now?: Date;
+    clockSkew?: number;
+}): Promise<Verification>;
+export { parseSignatureAgentHeader };