@datalayer/agent-runtimes 1.5.7 → 1.5.9

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

@@ -0,0 +1,185 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Visa's Trusted Agent Protocol as a profile over Web Bot Auth
+ * (AGENT_PROTOCOLS PR-24) — the twin of
+ * `agent_runtimes.protocols.web_bot_auth.tap`.
+ *
+ * **Draft.** Built on 2026-10-13 from Visa's public *Merchant
+ * Specifications* and its reference repository (`TAP_SOURCES`), not
+ * confirmed by Visa: the product says it *arriving* until it is. Visa
+ * publishes no test vector; `fixtures/tap.json` is one computed in Python
+ * and reproduced here byte for byte.
+ *
+ * The agent-recognition signature: `Signature-Input` and `Signature` alone
+ * (Visa names no `Signature-Agent`, so keys are handed in by `keyid`),
+ * covering at least `@authority` and `@path`, with `created`, `keyid`,
+ * `alg="Ed25519"`, `expires`, `nonce` and `tag` — `agent-browser-auth` to
+ * browse, `agent-payer-auth` to pay —, `created` and `expires` at most 8
+ * minutes apart, a nonce seen in the last 8 minutes a replay. Signed and
+ * verified with Cloudflare's `http-message-sig`, the RFC 9421 library under
+ * `web-bot-auth`.
+ *
+ * @module protocols/web-bot-auth/tap
+ */
+import { createSignature, verifySignature, webcrypto } from 'http-message-sig';
+import { generateNonce, jwkThumbprint, } from './index';
+/** Draft until Visa confirms it. */
+export const TAP_STATUS = 'draft';
+/** Where the profile was read, 2026-10-13. */
+export const TAP_SOURCES = [
+    'https://developer.visa.com/capabilities/trusted-agent-protocol/trusted-agent-protocol-specifications',
+    'https://developer.visa.com/capabilities/trusted-agent-protocol/overview',
+    'https://github.com/visa/trusted-agent-protocol',
+];
+/** Visa's key directory, as its page says it. */
+export const VISA_JWKS = 'https://mcp.visa.com/.well-known/jwks';
+export const TAP_BROWSE_TAG = 'agent-browser-auth';
+export const TAP_PAY_TAG = 'agent-payer-auth';
+export const TAP_TAGS = {
+    browse: TAP_BROWSE_TAG,
+    pay: TAP_PAY_TAG,
+};
+export const TAP_REQUIRED_COMPONENTS = ['@authority', '@path'];
+export const TAP_REQUIRED_PARAMS = [
+    'created',
+    'keyid',
+    'alg',
+    'expires',
+    'nonce',
+    'tag',
+];
+/** `alg` as Visa writes it. */
+export const TAP_ALG = 'Ed25519';
+/** The longest window, and how long a nonce is remembered. */
+export const TAP_MAX_WINDOW_SECONDS = 8 * 60;
+/** Sign one request as a TAP agent browsing or paying, under an Ed25519 key. */
+export async function signTapRequest(request, signer, options) {
+    if (signer.algorithm !== 'ed25519') {
+        throw new Error('a TAP signature is Ed25519');
+    }
+    const components = options.components ?? [...TAP_REQUIRED_COMPONENTS];
+    const missing = TAP_REQUIRED_COMPONENTS.filter(name => !components.includes(name));
+    if (missing.length) {
+        throw new Error(`a TAP signature covers ${missing.join(', ')}`);
+    }
+    const lifetime = options.lifetime ?? TAP_MAX_WINDOW_SECONDS;
+    if (!(lifetime > 0 && lifetime <= TAP_MAX_WINDOW_SECONDS)) {
+        throw new Error(`a TAP signature lives at most ${TAP_MAX_WINDOW_SECONDS}s (8 minutes)`);
+    }
+    const created = options.created ?? Math.floor(Date.now() / 1000);
+    const fields = await createSignature({
+        kind: 'request',
+        method: request.method,
+        targetUri: request.url,
+        fields: [],
+    }, {
+        label: options.label ?? 'sig2',
+        components,
+        parameters: {
+            created,
+            keyid: signer.keyid,
+            alg: TAP_ALG,
+            expires: created + lifetime,
+            nonce: options.nonce ?? generateNonce(),
+            tag: TAP_TAGS[options.intent],
+        },
+        signer: { algorithm: TAP_ALG, sign: data => signer.sign(data) },
+    });
+    return {
+        'Signature-Input': fields.signatureInput,
+        Signature: fields.signature,
+    };
+}
+const TAP_LABEL = /(?:^|,)\s*([a-z*][a-z0-9_.*-]*)=\([^)]*\)[^,]*;tag="(?:agent-browser-auth|agent-payer-auth)"/g;
+/**
+ * Verify the TAP signature of one request against Ed25519 keys known by
+ * `keyid` (Visa's directory, or a registry's). A request with no TAP tag is
+ * no trusted agent's; the merchant decides what to do with it.
+ */
+export async function verifyTapRequest(request, keys, options) {
+    const input = request.headers.get('signature-input');
+    if (!input || !request.headers.get('signature')) {
+        return { verified: false, reason: 'the request is not signed' };
+    }
+    const labels = [...input.matchAll(TAP_LABEL)].map(match => match[1]);
+    if (labels.length === 0) {
+        return { verified: false, reason: 'no signature carries a TAP tag' };
+    }
+    if (labels.length > 1) {
+        return {
+            verified: false,
+            reason: 'more than one signature carries a TAP tag',
+        };
+    }
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    let keyid;
+    let unknownKey = false;
+    try {
+        const verified = await verifySignature(request, {
+            label: labels[0],
+            policy: {
+                algorithms: [TAP_ALG],
+                requiredComponents: [...TAP_REQUIRED_COMPONENTS],
+                requiredParameters: [...TAP_REQUIRED_PARAMS],
+                now,
+                validate: signature => {
+                    const { created, expires, tag } = signature.parameters;
+                    return ((tag === TAP_BROWSE_TAG || tag === TAP_PAY_TAG) &&
+                        created !== undefined &&
+                        expires !== undefined &&
+                        expires - created <= TAP_MAX_WINDOW_SECONDS &&
+                        now < expires);
+                },
+            },
+            resolveVerifier: async (candidate) => {
+                keyid = candidate.parameters.keyid;
+                const jwk = keyid === undefined ? undefined : keys.get(keyid);
+                if (!jwk || jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {
+                    unknownKey = true;
+                    throw new Error('the key is not a known Ed25519 key');
+                }
+                const key = await crypto.subtle.importKey('jwk', jwk, { name: 'Ed25519' }, false, ['verify']);
+                const verifier = webcrypto.verifier(key);
+                return {
+                    algorithm: TAP_ALG,
+                    verify: (data, signature) => verifier.verify(data, signature),
+                };
+            },
+        });
+        const { tag, nonce } = verified.parameters;
+        if (nonce === undefined || keyid === undefined) {
+            return { verified: false, reason: 'the signature has no nonce', keyid };
+        }
+        const fresh = await options.nonceStore.checkAndRecord(`tap ${keyid}`, nonce, new Date((now + TAP_MAX_WINDOW_SECONDS) * 1000));
+        if (!fresh) {
+            return { verified: false, reason: 'the nonce was seen before', keyid };
+        }
+        return {
+            verified: true,
+            intent: tag === TAP_PAY_TAG ? 'pay' : 'browse',
+            keyid,
+            nonce,
+        };
+    }
+    catch (error) {
+        return {
+            verified: false,
+            reason: unknownKey
+                ? 'the key is not a known Ed25519 key'
+                : error.message,
+            keyid,
+        };
+    }
+}
+/** The `keyid` of an Ed25519 public JWK, as a TAP key list is indexed when it says none. */
+export async function tapKeys(jwks) {
+    const keys = new Map();
+    for (const jwk of jwks) {
+        const kid = jwk.kid;
+        keys.set(kid ?? (await jwkThumbprint(jwk)), jwk);
+    }
+    return keys;
+}

package/lib/specs/apps.js

@@ -194,6 +194,7 @@ export const BOOKKEEPING_DESK_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [
             {
                 id: 'northwind',
@@ -1570,6 +1571,7 @@ export const EXCHANGE_DESK_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [],
         company: {
             enabled: true,
@@ -1902,6 +1904,7 @@ export const LIVE_SHOP_CHAT_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [
             {
                 id: 'manzanita',
@@ -2474,10 +2477,11 @@ export const ORDER_DESK_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [
             {
                 id: 'manzanita',
-                company: 'manzanita.example',
+                company: 'manzanita.examples.datalayer.run',
                 access: 'write',
                 as: 'user',
                 scopes: ['orders:read', 'orders:write'],
@@ -2582,7 +2586,7 @@ export const ORDER_DESK_APP_0_0_1 = {
                 "The journey is the Personal Agent Protocol SDK's recorded journey user-with-a-company (Datalayer's protocol examples, personal-agent-protocol 0.16.0), shown as recorded data, not live.",
             ],
             unverified: [
-                'No company answers on Datalayer yet: no test company is served on r1, so it has not run in the Studio against one.',
+                'It has not run in the Studio against the hosted Manzanita (manzanita.examples.datalayer.run) from this example yet.',
             ],
         },
     },
@@ -2642,6 +2646,7 @@ export const ORDER_TRACKER_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [
             {
                 id: 'manzanita',
@@ -3650,6 +3655,7 @@ export const RETURNS_DESK_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [
             {
                 id: 'manzanita',
@@ -4175,6 +4181,7 @@ export const SHOP_CONCIERGE_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [
             {
                 id: 'manzanita',
@@ -4340,7 +4347,7 @@ export const SHOPPING_DESK_APP_0_0_1 = {
             {
                 id: 'example-store',
                 protocol: 'ucp',
-                merchant: 'store.example',
+                merchant: 'store.examples.datalayer.run',
                 access: 'write',
                 limit: {
                     amount: '50',
@@ -4350,7 +4357,7 @@ export const SHOPPING_DESK_APP_0_0_1 = {
             {
                 id: 'example-outfitters',
                 protocol: 'acp',
-                merchant: 'outfitters.example',
+                merchant: 'outfitters.examples.datalayer.run',
                 access: 'write',
                 limit: {
                     amount: '150',
@@ -4437,13 +4444,15 @@ export const SHOPPING_DESK_APP_0_0_1 = {
             },
         ],
         verified: {
-            live: [],
+            live: [
+                "Drilled on r1 on 13 October 2026 against the hosted test merchants, as its Preview's runtime reaches the gateway's ucp and acp toolsets: at Example Store (store.examples.datalayer.run) a search, a checkout filled, the exact purchase asked of the person, approved on Waiting for you, bought once and refused a second time, its order read; at Example Outfitters (outfitters.examples.datalayer.run) the same checkout over ACP. Test merchants only: paid with a test instrument.",
+            ],
             recorded: [
                 "The purchase is the developers' UCP example (examples/protocols/ucp/shopping.py) against its local test store, Example Store, run in its own tests.",
                 "The checkout at Example Outfitters is the developers' ACP example (examples/protocols/agentic_commerce/checkout.py), run in its own tests.",
             ],
             unverified: [
-                "No shop answers UCP or ACP on Datalayer yet: the gateway's ucp and acp toolsets are built, not deployed.",
+                "A model's turns in the Studio's Preview were not watched in that drill (no dev server ran).",
             ],
         },
     },
@@ -4473,8 +4482,8 @@ export const SHOPPING_DESK_APP_0_0_1 = {
         documents: [],
         alternatives: [],
     },
-    enabled: false,
-    unavailable_because: 'It buys at shops for you over UCP and ACP, and the services that reach a shop for you are not shipped yet.',
+    enabled: true,
+    unavailable_because: '',
     tags: ['example', 'companies'],
     icon: 'apps',
     emoji: '🛍️',
@@ -4503,6 +4512,7 @@ export const SIGN_IN_DESK_APP_0_0_1 = {
     protocols: ['pap'],
     ui: [],
     pap: {
+        profile: 'draft-01',
         connections: [
             {
                 id: 'manzanita',
@@ -5191,12 +5201,18 @@ export const TRAVEL_DESK_APP_0_0_1 = {
         connections: [
             {
                 id: 'example-air',
-                brand: 'air.example',
-                audience: 'https://provider.example/a2a',
+                brand: 'air.examples.datalayer.run',
+                audience: 'https://air.examples.datalayer.run/a2a',
                 access: 'write',
                 scopes: ['bookings:read', 'bookings:change'],
             },
         ],
+        business: {
+            enabled: false,
+            brand: '',
+            scopes: {},
+            registeredAgents: [],
+        },
     },
     rules: [
         {
@@ -5267,12 +5283,15 @@ export const TRAVEL_DESK_APP_0_0_1 = {
             },
         ],
         verified: {
-            live: [],
+            live: [
+                "Drilled on r1 on 13 October 2026 against the hosted Example Air (air.examples.datalayer.run), as its Preview's runtime reaches the gateway's pact toolset: its card read, asked as the application alone, the person's sign-in by device code approved at the Brand, then asked for the person and answered from the booking (bookings:read used, its receipt verified).",
+            ],
             recorded: [
                 "The journey is the developers' PACT example (examples/protocols/pact/personal_agent.py) against its local Provider, Example Air, run in its own tests (version 1.3.112).",
             ],
             unverified: [
-                "No airline answers PACT on Datalayer yet: the gateway's pact toolset is built, not deployed.",
+                'The hosted Example Air keeps registrations in memory: an application is registered there (POST /example/register, its issuer and keys) again after each restart.',
+                "A model's turns in the Studio's Preview were not watched in that drill (no dev server ran); the step-up to bookings:change was not drilled live.",
             ],
         },
     },
@@ -5302,8 +5321,8 @@ export const TRAVEL_DESK_APP_0_0_1 = {
         documents: [],
         alternatives: [],
     },
-    enabled: false,
-    unavailable_because: 'It asks an airline for you over PACT, and the services that reach a business for you are not shipped yet.',
+    enabled: true,
+    unavailable_because: '',
     tags: ['example', 'companies'],
     icon: 'apps',
     emoji: '✈️',
@@ -5621,6 +5640,7 @@ export const APP_SOURCES = {
         ],
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             connections: [
                 {
                     id: 'northwind',
@@ -6460,6 +6480,7 @@ export const APP_SOURCES = {
         ],
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             company: {
                 enabled: true,
                 interfaces: ['agent', 'openapi'],
@@ -6662,6 +6683,7 @@ export const APP_SOURCES = {
         instructions: "You relay the person's questions to Manzanita Outfitters' own agent, through its tools, and show what the shop writes as it arrives, as the shop's words. Never finish the shop's sentences for it.",
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             connections: [
                 {
                     id: 'manzanita',
@@ -7013,10 +7035,11 @@ export const APP_SOURCES = {
         instructions: 'You work with Manzanita Outfitters for the person you talk to, through its tools. Ask the shop before saying anything about an order; when it asks the person to sign in, say so and wait. Never confirm what the shop proposes on your own: the person approves it, word for word, on Waiting for you.',
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             connections: [
                 {
                     id: 'manzanita',
-                    company: 'manzanita.example',
+                    company: 'manzanita.examples.datalayer.run',
                     access: 'write',
                     scopes: ['orders:read', 'orders:write'],
                     extensions: ['operations'],
@@ -7080,7 +7103,7 @@ export const APP_SOURCES = {
                     "The journey is the Personal Agent Protocol SDK's recorded journey user-with-a-company (Datalayer's protocol examples, personal-agent-protocol 0.16.0), shown as recorded data, not live.",
                 ],
                 unverified: [
-                    'No company answers on Datalayer yet: no test company is served on r1, so it has not run in the Studio against one.',
+                    'It has not run in the Studio against the hosted Manzanita (manzanita.examples.datalayer.run) from this example yet.',
                 ],
             },
         },
@@ -7107,6 +7130,7 @@ export const APP_SOURCES = {
         instructions: "You read the person's orders at Manzanita Outfitters, through its tools, and change nothing. When the shop asks the person to sign in, say so and wait. If they ask to stop, tell them Disconnect under In your name ends the sign-in.",
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             connections: [
                 {
                     id: 'manzanita',
@@ -7852,6 +7876,7 @@ export const APP_SOURCES = {
         instructions: 'You arrange returns and repairs at Manzanita Outfitters for the person, through its tools. The shop proposes each one with its terms: show them, word for word, and never confirm on your own; the person approves it on Waiting for you.',
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             connections: [
                 {
                     id: 'manzanita',
@@ -8157,6 +8182,7 @@ export const APP_SOURCES = {
         instructions: "You talk with Manzanita Outfitters' own agent for the person, through its tools, in one conversation. When they ask for a person at the shop, ask the shop for one of its people and say who answers. Every message to the shop goes out in their name: send it only once they agreed.",
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             connections: [
                 {
                     id: 'manzanita',
@@ -8247,7 +8273,7 @@ export const APP_SOURCES = {
                 {
                     id: 'example-store',
                     protocol: 'ucp',
-                    merchant: 'store.example',
+                    merchant: 'store.examples.datalayer.run',
                     access: 'write',
                     limit: {
                         amount: '50',
@@ -8257,7 +8283,7 @@ export const APP_SOURCES = {
                 {
                     id: 'example-outfitters',
                     protocol: 'acp',
-                    merchant: 'outfitters.example',
+                    merchant: 'outfitters.examples.datalayer.run',
                     access: 'write',
                     limit: {
                         amount: '150',
@@ -8317,12 +8343,15 @@ export const APP_SOURCES = {
                 },
             ],
             verified: {
+                live: [
+                    "Drilled on r1 on 13 October 2026 against the hosted test merchants, as its Preview's runtime reaches the gateway's ucp and acp toolsets: at Example Store (store.examples.datalayer.run) a search, a checkout filled, the exact purchase asked of the person, approved on Waiting for you, bought once and refused a second time, its order read; at Example Outfitters (outfitters.examples.datalayer.run) the same checkout over ACP. Test merchants only: paid with a test instrument.",
+                ],
                 recorded: [
                     "The purchase is the developers' UCP example (examples/protocols/ucp/shopping.py) against its local test store, Example Store, run in its own tests.",
                     "The checkout at Example Outfitters is the developers' ACP example (examples/protocols/agentic_commerce/checkout.py), run in its own tests.",
                 ],
                 unverified: [
-                    "No shop answers UCP or ACP on Datalayer yet: the gateway's ucp and acp toolsets are built, not deployed.",
+                    "A model's turns in the Studio's Preview were not watched in that drill (no dev server ran).",
                 ],
             },
         },
@@ -8333,8 +8362,6 @@ export const APP_SOURCES = {
         deployment: {
             hosted: {},
         },
-        enabled: false,
-        unavailable_because: 'It buys at shops for you over UCP and ACP, and the services that reach a shop for you are not shipped yet.',
         tags: ['example', 'companies'],
         emoji: '🛍️',
     },
@@ -8349,6 +8376,7 @@ export const APP_SOURCES = {
         instructions: 'You help the person at Manzanita Outfitters, through its tools. When the shop needs them signed in, show its protected form and wait. Never ask for a password, a code or anything the form asks in the conversation.',
         protocols: ['pap'],
         pap: {
+            profile: 'draft-01',
             connections: [
                 {
                     id: 'manzanita',
@@ -8812,8 +8840,8 @@ export const APP_SOURCES = {
             connections: [
                 {
                     id: 'example-air',
-                    brand: 'air.example',
-                    audience: 'https://provider.example/a2a',
+                    brand: 'air.examples.datalayer.run',
+                    audience: 'https://air.examples.datalayer.run/a2a',
                     access: 'write',
                     scopes: ['bookings:read', 'bookings:change'],
                 },
@@ -8861,11 +8889,15 @@ export const APP_SOURCES = {
                 },
             ],
             verified: {
+                live: [
+                    "Drilled on r1 on 13 October 2026 against the hosted Example Air (air.examples.datalayer.run), as its Preview's runtime reaches the gateway's pact toolset: its card read, asked as the application alone, the person's sign-in by device code approved at the Brand, then asked for the person and answered from the booking (bookings:read used, its receipt verified).",
+                ],
                 recorded: [
                     "The journey is the developers' PACT example (examples/protocols/pact/personal_agent.py) against its local Provider, Example Air, run in its own tests (version 1.3.112).",
                 ],
                 unverified: [
-                    "No airline answers PACT on Datalayer yet: the gateway's pact toolset is built, not deployed.",
+                    'The hosted Example Air keeps registrations in memory: an application is registered there (POST /example/register, its issuer and keys) again after each restart.',
+                    "A model's turns in the Studio's Preview were not watched in that drill (no dev server ran); the step-up to bookings:change was not drilled live.",
                 ],
             },
         },
@@ -8876,8 +8908,6 @@ export const APP_SOURCES = {
         deployment: {
             hosted: {},
         },
-        enabled: false,
-        unavailable_because: 'It asks an airline for you over PACT, and the services that reach a business for you are not shipped yet.',
         tags: ['example', 'companies'],
         emoji: '✈️',
     },