@agent-cards/sdk 0.23.22 → 0.23.24

package/dist/tap-payments.js

@@ -0,0 +1,72 @@
+// Tap Payments' card frame, the token request as the SDK sees it (payment-core tap-payments.js has the request's shape,
+// the merchant pins, the device's encryption and the substitution). Tap's frame encrypts the card itself, under the
+// merchant's own RSA key, and sends it in one request:
+//   POST https://sdk.tap.company/v2/card/token
+//   Content-Type: application/json, Authorization: <the merchant's publishable key>
+//   {"encryptedData":"<base64>","purpose":"CHARGE",...,"order":{...},"device":{...},"browser":{...},"app":{...}}
+// The agent's page encrypts a placeholder card, so encryptedData carries the placeholder. This build holds that request
+// and writes over it the approved card's own ciphertext: the one the cardholder's device made under the key payment-core
+// pins for the request's publishable key (never a key from a row, a request or a page). Every other byte goes as the
+// frame wrote it (mode cse), so the full card number never reaches the agent's runtime. Tap answers a token; 3-D
+// Secure and the merchant's charge then run in the agent's browser, card free.
+//
+// The generic Adyen swap takes only JWEs at a named holder, and Tap's ciphertext is RSA base64 at the body root, so
+// this lane is dispatched by the token URL to substituteTapPayments, as 2C2P is to its own swap. The ciphertext names no
+// session and no time: it would ask Tap for a token at the same merchant again, so the continuation writes it only into
+// the one request the approval was created from, byte for byte.
+//
+// The registry entry ships dark (capability tap_card_sdk_token). Until this build declares the capability, the API
+// serves the recognizer to no client of it, so nothing here fires. Autopilot never pays this processor: the API, the
+// authority and the enclave refuse it.
+import { TAP_PAYMENTS_FIELD, isTapPaymentsTokenUrl, substituteTapPayments, tapPaymentsRequestKey } from './tap-payments.generated.js';
+/** The PSP id the API and the recognizer name this lane, re-exported so the client dispatches by it. */
+export { TAP_PAYMENTS_PSP } from './tap-payments.generated.js';
+/** The dark-launch capability a build declares when it fills a Tap token request with the device's ciphertext. */
+export const TAP_PAYMENTS_CAPABILITY = 'tap_card_sdk_token';
+/**
+ * Whether an approved Tap authorization's served substitution is one this SDK can continue: JSON at the body root (`at`
+ * is ''), no sibling to remove, and exactly the one ciphertext, a non-empty string. substituteTapPayments checks its
+ * size and range against the pin for the request's publishable key; this is the shape gate the client runs first.
+ */
+export function isTapPaymentsServedSubstitution(sub) {
+    if (!sub || typeof sub !== 'object' || Array.isArray(sub))
+        return false;
+    const { encoding, at, fields, remove } = sub;
+    if (encoding !== 'json' || at !== '' || !fields || typeof fields !== 'object' || Array.isArray(fields))
+        return false;
+    if (remove !== undefined && !(Array.isArray(remove) && remove.length === 0))
+        return false;
+    const named = fields;
+    return Object.keys(named).length === 1 && typeof named[TAP_PAYMENTS_FIELD] === 'string' && named[TAP_PAYMENTS_FIELD].length > 0;
+}
+/**
+ * The continuation of an approved Tap token request: the paused body with the device's ciphertext written over the
+ * placeholder's at encryptedData (payment-core substituteTapPayments, which runs the frame's request rule again on the
+ * headers of the request that continues, and refuses a ciphertext that does not have the size and range of one under
+ * the pin for its publishable key, or one already in the paused body).
+ *
+ * Only into `approved`, the paused request the approval was created from: `url` and `body` must equal it byte for byte.
+ * A ciphertext under the merchant's key would ask Tap for a token in any later request of the same shape; binding it
+ * to the one request keeps this lane from ever writing one checkout's card into another. `headers` are those of the
+ * request that continues, the paused one or the page's retry of it, and the browser sends them as they are: they
+ * must name the publishable key the approved request named, so a retry under another merchant's key never carries the
+ * card.
+ *
+ * Null when neither URL is Tap's token URL, so every other processor keeps its own swap. Throws for any other body,
+ * URL or key, and for a substitution the shape gate or the swap refuses, in each case before anything continues. The
+ * approval is not retired on a refusal: the runtime already read the ciphertext, so the API keeps the row and its hold.
+ */
+export function tapPaymentsContinuation(url, body, headers, sub, approved) {
+    if (!isTapPaymentsTokenUrl(url) && !isTapPaymentsTokenUrl(approved.url))
+        return null;
+    if (url !== approved.url || body !== approved.body)
+        throw new Error('Refusing to substitute: the paused request is not the Tap card request the cardholder approved.');
+    const key = tapPaymentsRequestKey({ headers: headers ?? {} });
+    if (key === null || key !== tapPaymentsRequestKey({ headers: approved.headers ?? {} })) {
+        throw new Error('Refusing to substitute: the Tap card request does not name the merchant key the cardholder approved.');
+    }
+    if (!isTapPaymentsServedSubstitution(sub))
+        throw new Error('Refusing to substitute: the Tap approval is not one encrypted card.');
+    const request = { url, method: 'POST', headers: headers ?? {}, body };
+    return { body: substituteTapPayments(request, { [TAP_PAYMENTS_FIELD]: sub.fields[TAP_PAYMENTS_FIELD] }) };
+}

package/dist/transbank.d.ts

@@ -43,3 +43,36 @@ export declare function servesTransbank(vault: {
 export declare function isArmedTransbankUrl(vault: {
     isCardRequest(url: string, method?: string): boolean;
 } | undefined, url: string): boolean;
+/**
+ * A reviewed Webpay shop, as this build reads it to send the browser back: the hosts of its checkout pages, the host of
+ * its return page, and the return page itself, exactly as its transactions name it (null while nobody has read it).
+ */
+export interface TransbankReturnPage {
+    readonly hosts: readonly string[];
+    readonly returnHost: string;
+    readonly returnUrl: string | null;
+}
+/**
+ * payment-core's TRANSBANK_MERCHANTS, every row that names its commerce code, with these three fields. A row without a
+ * code names no shop there, so it is not listed here. transbank.test.mjs pins this list to payment-core's, so a reviewed
+ * change that codes a shop there fails this package's tests until the shop is listed here too. Teleférico Santiago's
+ * row names no code yet, so no paused entry is sent back anywhere.
+ */
+export declare const TRANSBANK_RETURN_PAGES: readonly TransbankReturnPage[];
+/**
+ * Where the paused Webpay entry `entryUrl` goes once the cardholder's phone has paid it: the return page of the one
+ * reviewed shop whose checkout pages include `pageOrigin` (the origin the create named, written exactly as an origin),
+ * with the entry's token as `token_ws`. The same navigation payment-core's transbankMerchantReturn builds, and the one
+ * Webpay itself sends the phone's session to. Null for a link that is not Webpay's entry, a page no reviewed shop
+ * lists, a page two list, or a shop whose return page no token can follow. `pages` is for tests.
+ */
+export declare function transbankMerchantReturn(entryUrl: unknown, pageOrigin: unknown, pages?: readonly TransbankReturnPage[]): string | null;
+/**
+ * The answer the paused entry gets: a 303 to the shop's return page, which the browser follows with a GET, and which no
+ * cache keeps (the URL carries Webpay's token).
+ */
+export declare function transbankMerchantReturnAnswer(returnUrl: string): {
+    status: 303;
+    headers: Record<string, string>;
+    body: string;
+};

package/dist/transbank.js

@@ -71,3 +71,65 @@ export function servesTransbank(vault) {
 export function isArmedTransbankUrl(vault, url) {
     return isTransbankHost(url) && servesTransbank(vault);
 }
+/**
+ * payment-core's TRANSBANK_MERCHANTS, every row that names its commerce code, with these three fields. A row without a
+ * code names no shop there, so it is not listed here. transbank.test.mjs pins this list to payment-core's, so a reviewed
+ * change that codes a shop there fails this package's tests until the shop is listed here too. Teleférico Santiago's
+ * row names no code yet, so no paused entry is sent back anywhere.
+ */
+export const TRANSBANK_RETURN_PAGES = Object.freeze([]);
+// Webpay's own return fields (payment-core processors/transbank.js RETURN_FIELDS): a return page never carries one.
+const RETURN_FIELDS = new Set(['token_ws', 'TBK_TOKEN', 'TBK_ORDEN_COMPRA', 'TBK_ID_SESION']);
+/** `page.returnUrl` when a token can follow it, as payment-core's pinnedReturnUrl reads a row's; null otherwise. */
+function returnPageUrl(page) {
+    const raw = page?.returnUrl;
+    if (typeof raw !== 'string' || raw.length > 1024)
+        return null;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' || url.hostname !== page.returnHost || url.port || url.username || url.password || url.href !== raw
+        || /#|\?$|\?&|&&|&$/.test(raw))
+        return null;
+    for (const [name] of url.searchParams)
+        if (RETURN_FIELDS.has(name))
+            return null;
+    return raw;
+}
+/**
+ * Where the paused Webpay entry `entryUrl` goes once the cardholder's phone has paid it: the return page of the one
+ * reviewed shop whose checkout pages include `pageOrigin` (the origin the create named, written exactly as an origin),
+ * with the entry's token as `token_ws`. The same navigation payment-core's transbankMerchantReturn builds, and the one
+ * Webpay itself sends the phone's session to. Null for a link that is not Webpay's entry, a page no reviewed shop
+ * lists, a page two list, or a shop whose return page no token can follow. `pages` is for tests.
+ */
+export function transbankMerchantReturn(entryUrl, pageOrigin, pages = TRANSBANK_RETURN_PAGES) {
+    if (!isTransbankEntryUrl(entryUrl) || typeof pageOrigin !== 'string' || pageOrigin.length > 256)
+        return null;
+    const token = new URL(entryUrl).searchParams.get('token_ws');
+    let origin;
+    try {
+        origin = new URL(pageOrigin);
+    }
+    catch {
+        return null;
+    }
+    if (origin.protocol !== 'https:' || origin.origin !== pageOrigin || origin.port)
+        return null;
+    const listing = pages.filter((page) => Array.isArray(page?.hosts) && page.hosts.includes(origin.hostname));
+    const returnUrl = listing.length === 1 ? returnPageUrl(listing[0]) : null;
+    if (!returnUrl || !token)
+        return null;
+    return `${returnUrl}${new URL(returnUrl).search ? '&' : '?'}token_ws=${token}`;
+}
+/**
+ * The answer the paused entry gets: a 303 to the shop's return page, which the browser follows with a GET, and which no
+ * cache keeps (the URL carries Webpay's token).
+ */
+export function transbankMerchantReturnAnswer(returnUrl) {
+    return { status: 303, headers: { location: returnUrl, 'cache-control': 'no-store' }, body: '' };
+}

package/dist/url-mask-parts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The parts every URL mask is built from (client.ts redactUrl). A processor whose card request carries its own
+ * credential in the URL path writes its mask in src/url-masks/<psp id>.ts, exported as `mask`, and the build
+ * collects every such file into src/url-masks.generated.ts (scripts/generate-url-masks.mjs).
+ */
+/**
+ * `mask` reads a text that names the processor's host; `pathMask`, where a processor has one, reads the path of a
+ * URL already parsed on that host, which `mask` reads otherwise.
+ */
+export interface UrlMask {
+    host: RegExp;
+    named: RegExp;
+    mask: (path: string) => string;
+    pathMask?: (path: string) => string;
+}
+/**
+ * A slash as the masks read one: plain, or escaped once or more in either case (%2F, %2f, %252F). A path keeps
+ * an escape as it was written, and the id behind it is the same id, so every slash a mask names reads in any of these
+ * spellings. The slashes right before an id read as a run, and a doubled slash hides nothing either.
+ */
+export declare const SLASH = "(?:/|%(?:25)*2f)";
+/** A hyphen inside an id: plain, or escaped once or more in either case (%2D, %252d). */
+export declare const HYPHEN = "(?:-|%(?:25)*2d)";
+export declare function maskUuids(path: string, label: string): string;

package/dist/url-mask-parts.js

@@ -0,0 +1,22 @@
+/**
+ * The parts every URL mask is built from (client.ts redactUrl). A processor whose card request carries its own
+ * credential in the URL path writes its mask in src/url-masks/<psp id>.ts, exported as `mask`, and the build
+ * collects every such file into src/url-masks.generated.ts (scripts/generate-url-masks.mjs).
+ */
+/**
+ * A slash as the masks read one: plain, or escaped once or more in either case (%2F, %2f, %252F). A path keeps
+ * an escape as it was written, and the id behind it is the same id, so every slash a mask names reads in any of these
+ * spellings. The slashes right before an id read as a run, and a doubled slash hides nothing either.
+ */
+export const SLASH = '(?:/|%(?:25)*2f)';
+/** A hyphen inside an id: plain, or escaped once or more in either case (%2D, %252d). */
+export const HYPHEN = '(?:-|%(?:25)*2d)';
+/**
+ * The masks that find a uuid by its shape take it in any case, with or without its hyphens, each hyphen in any
+ * spelling HYPHEN reads. The pattern reads a percent escape as one unit and keeps it, so the hex digits of an escaped
+ * separator before the id (%2F, %252F, %3D) never start a match and leave the id's last digits showing.
+ */
+const UUID_OR_ESCAPE = new RegExp(`%(?:25)*[0-9a-f]{2}|[0-9a-f]{8}${HYPHEN}?[0-9a-f]{4}${HYPHEN}?[0-9a-f]{4}${HYPHEN}?[0-9a-f]{4}${HYPHEN}?[0-9a-f]{12}`, 'gi');
+export function maskUuids(path, label) {
+    return path.replace(UUID_OR_ESCAPE, (token) => (token.startsWith('%') ? token : label));
+}

package/dist/url-masks.generated.d.ts

@@ -0,0 +1,3 @@
+import type { UrlMask } from './url-mask-parts.js';
+/** The masks of the processors registered in src/url-masks/: none yet. */
+export declare const URL_MASKS: readonly UrlMask[];

package/dist/url-masks.generated.js

@@ -0,0 +1,2 @@
+/** The masks of the processors registered in src/url-masks/: none yet. */
+export const URL_MASKS = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/sdk",
-  "version": "0.23.22",
+  "version": "0.23.24",
   "description": "Agentcard's SDK: one client, Agentcard, with two modules. checkout pauses a browser purchase and pays it with the person's own card; voice connects a person to your product once and approves a purchase by voice inside it. Card data never enters your process.",
   "type": "module",
   "main": "dist/index.js",
@@ -25,12 +25,12 @@
   },
   "scripts": {
     "_comment_build": "The public SDK keeps zero runtime dependencies. Its build vendors deterministic metadata and substitution artifacts from the internal payment core (src/*.generated.ts), the voice streaming door from packages/voice/src/core (the phone package, @agent-cards/voice, ships it to phones), and the Kernel kit's inventory from the built catalog; git ignores every file it writes. TypeScript remains pinned.",
-    "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && node scripts/generate-voice-stream.mjs && npx -y -p typescript@5.9.3 tsc && node scripts/generate-preflight-contract.mjs && node scripts/generate-kernel-native-inventory.mjs",
+    "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && node scripts/generate-voice-stream.mjs && node scripts/generate-url-masks.mjs && node scripts/generate-capabilities.mjs && node scripts/generate-agent-amount.mjs && npx -y -p typescript@5.9.3 tsc && node scripts/generate-preflight-contract.mjs && node scripts/generate-kernel-native-inventory.mjs",
     "prepublishOnly": "pnpm build",
     "_comment_test": "check:built runs first and names the command when a file the build generates (the copies in src/, the preflight contracts in dist/, the Kernel inventory) is missing or stale; verify:pack runs last, on the same dist.",
-    "check:built": "node scripts/generate-payment-core.mjs --check && node scripts/generate-voice-stream.mjs --check && node scripts/generate-preflight-contract.mjs --check && node scripts/generate-kernel-native-inventory.mjs --check",
+    "check:built": "node scripts/generate-payment-core.mjs --check && node scripts/generate-voice-stream.mjs --check && node scripts/generate-url-masks.mjs --check && node scripts/generate-capabilities.mjs --check && node scripts/generate-agent-amount.mjs --check && node scripts/generate-preflight-contract.mjs --check && node scripts/generate-kernel-native-inventory.mjs --check",
     "verify:pack": "node scripts/verify-pack.mjs",
-    "test": "npm run check:built && node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs pre-claim.test.mjs ekashu.test.mjs redsys.test.mjs quickpay.test.mjs paypal-hosted-fields.test.mjs paypal-card-forms.test.mjs cybersource-secure-acceptance.test.mjs ebanx.test.mjs payrexx.test.mjs payrexx-follow-ups.test.mjs payrexx-adapters.test.mjs autopilot.test.mjs stripe-checkout.test.mjs stripe-setup.test.mjs stripe-legacy-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs merchant-hosted.test.mjs merchant-total.test.mjs sandbox-declaration.test.mjs minimum-delay.test.mjs paysafe.test.mjs wix-payments.test.mjs hipay.test.mjs payu.test.mjs attachment.test.mjs worker-targets.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs amadeus.test.mjs pelecard.test.mjs aci.test.mjs primer.test.mjs payrails.test.mjs elavon-converge.test.mjs voice.test.mjs agentcard.test.mjs buy.test.mjs readme.test.mjs gmo.test.mjs cybersource-flex.test.mjs juspay-gate.test.mjs card-endpoint.test.mjs card-endpoint-fastspring.test.mjs card-endpoint-navigation.test.mjs merchant-session-probe.test.mjs datatrans.test.mjs authorize-net-dpm.test.mjs creditguard.test.mjs eprotect.test.mjs wspay.test.mjs shiji-sts.test.mjs worldline-mycheckout.test.mjs verifone.test.mjs gravy.test.mjs paddle-vgs.test.mjs hold.test.mjs paddle-tokenex.test.mjs lyra.test.mjs gopay.test.mjs paygent.test.mjs twoc2p.test.mjs pay-nl.test.mjs toast.test.mjs redact-url.test.mjs hosted-entry.test.mjs comgate.test.mjs przelewy24.test.mjs tokenex-iframe.test.mjs transbank.test.mjs sumup.test.mjs clover.test.mjs eximbay.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs browser-tests.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs && node scripts/verify-pack.mjs",
+    "test": "npm run check:built && node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs pre-claim.test.mjs ekashu.test.mjs redsys.test.mjs quickpay.test.mjs paytrail.test.mjs paypal-hosted-fields.test.mjs paypal-card-forms.test.mjs cybersource-secure-acceptance.test.mjs ebanx.test.mjs payrexx.test.mjs payrexx-follow-ups.test.mjs payrexx-adapters.test.mjs autopilot.test.mjs stripe-checkout.test.mjs stripe-setup.test.mjs stripe-legacy-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs merchant-hosted.test.mjs merchant-total.test.mjs sandbox-declaration.test.mjs minimum-delay.test.mjs paysafe.test.mjs wix-payments.test.mjs hipay.test.mjs openpay.test.mjs payu.test.mjs attachment.test.mjs worker-targets.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs amadeus.test.mjs pelecard.test.mjs aci.test.mjs primer.test.mjs payrails.test.mjs elavon-converge.test.mjs voice.test.mjs agentcard.test.mjs buy.test.mjs readme.test.mjs gmo.test.mjs cybersource-flex.test.mjs juspay-gate.test.mjs card-endpoint.test.mjs card-endpoint-fastspring.test.mjs card-endpoint-navigation.test.mjs merchant-session-probe.test.mjs datatrans.test.mjs authorize-net-dpm.test.mjs creditguard.test.mjs eprotect.test.mjs wspay.test.mjs shiji-sts.test.mjs worldline-mycheckout.test.mjs verifone.test.mjs gravy.test.mjs paddle-vgs.test.mjs sbps.test.mjs hold.test.mjs paddle-tokenex.test.mjs lyra.test.mjs gopay.test.mjs paygent.test.mjs twoc2p.test.mjs tap-payments.test.mjs pay-nl.test.mjs toast.test.mjs redact-url.test.mjs hosted-entry.test.mjs comgate.test.mjs przelewy24.test.mjs tokenex-iframe.test.mjs transbank.test.mjs sumup.test.mjs clover.test.mjs eximbay.test.mjs xendit.test.mjs omise.test.mjs fastspring.test.mjs amazon-payment-services.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs browser-tests.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs && node scripts/verify-pack.mjs",
     "test:browser": "node browser-tests.mjs",
     "check:payment-core": "node scripts/generate-payment-core.mjs --check",
     "check:voice-stream": "node scripts/generate-voice-stream.mjs --check",