@agent-cards/sdk 0.23.5 → 0.23.7

package/dist/cybersource-secure-acceptance.js

@@ -28,10 +28,14 @@
  *     and holds, as every unsupported refusal does;
  *   - no card_number, or an empty one, as in a payment with a stored payment_token: continue untouched;
  *   - a body the adapter could not read: stop that request alone, since nothing proves it carries no card.
- * A request the synced registry recognizes as a card request belongs to that recognizer instead; no
- * build serves one today. Hosted Checkout, the same hosts without /silent/, takes the card on
- * CyberSource's own page, and neither adapter arms it.
+ * A request the synced registry recognizes as a card request belongs to the Secure Acceptance lane
+ * instead (below): the API serves that recognizer only to a build that declares
+ * `cybersource_sa_token_create` and only for a company Agentcard turned the lane on for, and it covers
+ * exactly the token create, POST https://<host>/silent/embedded/token/create on the production or the
+ * test host. Every other company, and every other /silent/ path, keeps the stop above. Hosted Checkout,
+ * the same hosts without /silent/, takes the card on CyberSource's own page, and neither adapter arms it.
  */
+import { SECURE_ACCEPTANCE_MERCHANTS, SECURE_ACCEPTANCE_PAGE_CONTENT_TYPE, isSecureAcceptanceTokenRequest, secureAcceptanceMerchantEntry, secureAcceptanceReplyOutcome, } from './cybersource-secure-acceptance.generated.js';
 export const CYBERSOURCE_SECURE_ACCEPTANCE_REASON = 'unsupported_cybersource_secure_acceptance';
 /** Where the stopped page says the card was going. */
 export const CYBERSOURCE_SECURE_ACCEPTANCE_RECIPIENT = 'CyberSource';
@@ -212,3 +216,240 @@ function formFields(body) {
             fields.push(pair);
     return fields;
 }
+// ---- The Secure Acceptance lane (dark launch) ----
+//
+// For a company Agentcard turned it on for, the API serves one recognizer (payment-core definitions.js,
+// capability cybersource_sa_token_create) for one request: POST /silent/embedded/token/create on
+// secureacceptance.cybersource.com (production) or testsecureacceptance.cybersource.com (sandbox), a
+// create_payment_token at a signed amount of 0, with the merchant's signed fields and the four unsigned
+// card fields. The rules that judge that request and CyberSource's reply live in payment-core and reach
+// this SDK as cybersource-secure-acceptance.generated.ts; the API and the cardholder's device run the same
+// ones. The lane pays the request only through a prepared checkout, approved before the agent clicks
+// Save, and only as the merchant's hidden frame sends it:
+//   - the pre-claim gate holds a card-bearing post to that URL to a navigation of a frame (pre-claim.ts);
+//     a top navigation, a fetch or an XHR is stopped as an unrecognized post is;
+//   - the claim binds the preparation only to the request payment-core admits for the preparation's
+//     environment, profile id and page origin (prepared-processor.ts);
+//   - the cardholder's device sends the real card to CyberSource through the checkout relay, and the API
+//     hands back CyberSource's own reply page once neither it nor the device finds a card in it;
+//   - the adapters answer the paused frame navigation with that page, status 200 and its one content type
+//     (secureAcceptanceFrameAnswer), so Chrome commits it as CyberSource's own document and its auto-post
+//     reaches the merchant's receipt page in the agent's own session, as it would with no Agentcard.
+// The clocks fit Arrow's page, which asks its frame 30 times, a second apart, from Save: reads every
+// 500 ms for 30 s after the create; a pause with nothing being handed over 20 s after it is retired (the
+// send window, amadeus.ts armSendWindow); a reply not read 45 s after the pause is an unknown outcome;
+// and once the page is delivered, a merchant whose reviewed entry names its next request is watched for
+// it for 10 s.
+/** The processor id, as the registry and the API name it. */
+export const SECURE_ACCEPTANCE_PSP = 'cybersource_secure_acceptance';
+/** The dark-launch capability the API serves the Secure Acceptance recognizer behind (payment-core definitions.js). */
+export const SECURE_ACCEPTANCE_CAPABILITY = 'cybersource_sa_token_create';
+/** How long after the pause a paused token request may still be sent; past it, nothing being handed over, it is retired. */
+export const SECURE_ACCEPTANCE_SEND_WINDOW_MS = 20_000;
+/** How long after the pause CyberSource's reply may still be read; past it the outcome is unknown. */
+export const SECURE_ACCEPTANCE_REPLY_WINDOW_MS = 45_000;
+/** How long after the create the authorization is read every 500 ms instead of at the caller's interval. */
+export const SECURE_ACCEPTANCE_FAST_POLL_MS = 30_000;
+/** How long after the page is delivered the merchant's follow-up request is watched for. */
+export const SECURE_ACCEPTANCE_FOLLOW_UP_MS = 10_000;
+/** The one content type the paused frame's answer carries, as CyberSource serves its page. */
+export const SECURE_ACCEPTANCE_ANSWER_CONTENT_TYPE = SECURE_ACCEPTANCE_PAGE_CONTENT_TYPE;
+/** A CyberSource Secure Acceptance profile id: a UUID shape, 36 characters, hex in either case. */
+const PROFILE_ID = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+/** This build's reviewed entries, or the ones a test passes. */
+function reviewedEntries(entries) {
+    return entries ?? SECURE_ACCEPTANCE_MERCHANTS;
+}
+/** The reviewed entry that lists this profile id for this origin, through payment-core's own lookup, or null. */
+function entryFor(profileId, merchantOrigin, entries) {
+    try {
+        return secureAcceptanceMerchantEntry(profileId, merchantOrigin, entries) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The profile id a Secure Acceptance checkout prepares, or null when it can name none. A profile id the
+ * caller passes must have CyberSource's UUID shape, and is the one the bound request must carry. On the
+ * production host the caller may leave it out when exactly one entry this build reviewed lists the
+ * checkout page's origin, under exactly one profile id: that one is used, so the agent names nothing it
+ * cannot see. The test host has no entries (it takes only CyberSource's test cards), so a sandbox
+ * checkout always names its own. `entries` is for tests.
+ */
+export function secureAcceptanceCheckoutProfile(input, entries) {
+    if (input.profileId !== undefined)
+        return typeof input.profileId === 'string' && PROFILE_ID.test(input.profileId) ? input.profileId : null;
+    if (input.environment !== 'production')
+        return null;
+    const listing = reviewedEntries(entries).filter((entry) => entry.environment === 'production' && entry.origins.includes(input.merchantOrigin));
+    if (listing.length !== 1 || listing[0].profileIds.length !== 1)
+        return null;
+    const [profileId] = listing[0].profileIds;
+    return typeof profileId === 'string' && PROFILE_ID.test(profileId) ? profileId : null;
+}
+/**
+ * Why a Secure Acceptance checkout may not be prepared under `merchant`, or null when it may:
+ * `secure_acceptance_profile_id_invalid` when it names no profile id this build can stand behind
+ * (secureAcceptanceCheckoutProfile), and, on the production host, `merchant_profile_mismatch` when the
+ * entry this build reviewed for that profile id and origin names another merchant, the one the approval
+ * shows. A profile id this build has not reviewed is the API's to judge (unsupported_checkout), as an
+ * eProtect paypageId is. `entries` is for tests.
+ */
+export function secureAcceptanceCheckoutRefusal(input, entries) {
+    const profileId = secureAcceptanceCheckoutProfile(input, entries);
+    if (profileId === null)
+        return 'secure_acceptance_profile_id_invalid';
+    if (input.environment !== 'production')
+        return null;
+    const entry = entryFor(profileId, input.merchantOrigin, entries);
+    return entry && entry.merchant !== input.merchant ? 'merchant_profile_mismatch' : null;
+}
+/**
+ * Whether a paused request is the one shape the lane pays: a POST to the exact token-create URL on one of
+ * the two hosts (payment-core isSecureAcceptanceTokenRequest), sent as a navigation of a frame, as a
+ * merchant's form targeted at its hidden iframe sends it. A top navigation, a fetch and an XHR are not.
+ */
+export function isSecureAcceptanceFramePost(request) {
+    if (request.navigation !== 'frame')
+        return false;
+    try {
+        return isSecureAcceptanceTokenRequest(request.url, String(request.method).toUpperCase()) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The answer a paused token request gets, or null when the approved reply is not one to hand the frame:
+ * CyberSource's own page, byte for byte as the API stored it, with status 200 and the one content type
+ * CyberSource serves it with, and no other header. The page must pass payment-core's reply rule for the
+ * paused request (secureAcceptanceReplyOutcome: one hidden-input form posting to the receipt page the
+ * request signed, the request's own echoes, a masked number, a token, no card), run here with no card and
+ * no last four: the device and the API checked those.
+ */
+export function secureAcceptanceFrameAnswer(request, response) {
+    if (!request || typeof request.url !== 'string' || typeof request.body !== 'string' || !response || typeof response.body !== 'string')
+        return null;
+    let verdict;
+    try {
+        // No card and no last four: the device and the API checked the page against the card.
+        verdict = secureAcceptanceReplyOutcome({ status: response.status, headers: { ...(response.headers ?? {}) }, bodyText: response.body }, { url: request.url, body: request.body }, undefined, undefined);
+    }
+    catch {
+        return null;
+    }
+    if (verdict?.outcome !== 'token' || verdict.page !== response.body)
+        return null;
+    return { status: 200, headers: { 'content-type': SECURE_ACCEPTANCE_ANSWER_CONTENT_TYPE }, body: response.body };
+}
+/**
+ * The request a reviewed merchant's page sends once its receipt page answered (Arrow: the payment-method
+ * set), for a production preparation whose profile id and origin an entry lists with one; null otherwise,
+ * the test host included. `entries` is for tests.
+ */
+export function secureAcceptanceFollowUp(preparation, entries) {
+    if (preparation.environment !== 'production' || typeof preparation.secureAcceptanceProfileId !== 'string')
+        return null;
+    const followUp = entryFor(preparation.secureAcceptanceProfileId, preparation.merchantOrigin, entries)?.followUp;
+    if (!followUp || typeof followUp.method !== 'string' || typeof followUp.url !== 'string')
+        return null;
+    try {
+        return { method: followUp.method.toUpperCase(), url: new URL(followUp.url).href };
+    }
+    catch {
+        return null;
+    }
+}
+const INPUT_TAG = /<input\b((?:[^>"']|"[^"]*"|'[^']*')*)>/gi;
+const ATTRIBUTE = /([^\s=/>"']+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+const NAMED_ENTITIES = { amp: '&', quot: '"', apos: "'", lt: '<', gt: '>' };
+function decodeEntities(value) {
+    return value.replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]+);/gi, (whole, entity) => {
+        if (entity[0] === '#') {
+            const code = entity[1] === 'x' || entity[1] === 'X' ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10);
+            return Number.isInteger(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+        }
+        return NAMED_ENTITIES[entity.toLowerCase()] ?? whole;
+    });
+}
+/**
+ * The last four digits of the masked number CyberSource's reply page echoes (req_card_number, masked as
+ * x's and the last four), or null when the page carries no single such field. The page passed the reply
+ * rule before it was delivered, so this only reads it back for the follow-up event; it never carries more
+ * than those four digits.
+ */
+export function secureAcceptanceReplyLast4(page) {
+    if (typeof page !== 'string')
+        return null;
+    const values = [];
+    for (const tag of page.matchAll(INPUT_TAG)) {
+        const attributes = new Map();
+        for (const attribute of tag[1].matchAll(ATTRIBUTE)) {
+            const name = attribute[1].toLowerCase();
+            if (!attributes.has(name))
+                attributes.set(name, decodeEntities(attribute[2] ?? attribute[3] ?? attribute[4] ?? ''));
+        }
+        if (attributes.get('name') === 'req_card_number')
+            values.push(attributes.get('value') ?? '');
+    }
+    return values.length === 1 ? /^[xX]{9,15}([0-9]{4})$/.exec(values[0])?.[1] ?? null : null;
+}
+/** A URL's origin and path, the part a follow-up request is matched on (its query is the page's own). */
+function originAndPath(url) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One attachment's watch for the merchant's follow-up request after a delivered reply. Read-only: it
+ * pauses, changes and delays nothing. The adapters report every request the page sends (CDP
+ * Network.requestWillBeSent, Playwright page.on('request')) through saw(); when none matches the
+ * merchant's follow-up within SECURE_ACCEPTANCE_FOLLOW_UP_MS, the event `secure_acceptance_reply_unused`
+ * names the authorization and the masked number's last four, so the agent can find the card the merchant
+ * may have kept (in its saved cards, ending in those four) before it ever asks for a new checkout.
+ */
+export class SecureAcceptanceFollowUpWatch {
+    onEvent;
+    ms;
+    watching = null;
+    constructor(onEvent, ms = SECURE_ACCEPTANCE_FOLLOW_UP_MS) {
+        this.onEvent = onEvent;
+        this.ms = ms;
+    }
+    /** Start watching for `followUp` after the reply for `authorizationId` was delivered; a watch already running ends unreported. */
+    begin(followUp, detail) {
+        this.end();
+        const target = originAndPath(followUp.url);
+        if (target === null)
+            return;
+        const timer = setTimeout(() => {
+            if (this.watching?.timer !== timer)
+                return;
+            this.watching = null;
+            this.onEvent?.({ type: 'secure_acceptance_reply_unused', detail: { authorizationId: detail.authorizationId, last4: detail.last4 } });
+        }, this.ms);
+        timer.unref?.();
+        this.watching = { target, method: String(followUp.method).toUpperCase(), timer };
+    }
+    /** A request the page sent: the follow-up, when it is the one being watched for, ends the watch. */
+    saw(method, url) {
+        if (!this.watching || typeof method !== 'string' || typeof url !== 'string')
+            return;
+        if (method.toUpperCase() === this.watching.method && originAndPath(url) === this.watching.target)
+            this.end();
+    }
+    /** True while a watch runs. */
+    get active() { return this.watching !== null; }
+    /** End the watch with no event. */
+    end() {
+        if (!this.watching)
+            return;
+        clearTimeout(this.watching.timer);
+        this.watching = null;
+    }
+}

package/dist/eprotect.d.ts

@@ -18,8 +18,8 @@ export interface EprotectMerchantPin {
  * (merchant_profile_mismatch) before any preparation exists. When this build pins the paypageId
  * too, it refuses another name first, before any network call, as a Fiserv checkout must name its
  * key pin's merchant. A paypageId this build does not pin is the API's to judge (unsupported_checkout
- * with no pin); none is pinned on either side yet. The pre-live host takes only the guide's test
- * cards and needs no pin. `pins` is for tests.
+ * with no pin). This build pins SmartPak Equine and Nordstrom, under those exact names. The pre-live
+ * host takes only the guide's test cards and needs no pin. `pins` is for tests.
  */
 export declare function eprotectCheckoutRefusal(input: {
     environment: string;

package/dist/eprotect.generated.d.ts

@@ -4,22 +4,61 @@ declare var EPROTECT_HOSTS: Readonly<{
     sandbox: "request.eprotect.vantivprelive.com";
 }>;
 declare var EPROTECT_SECONDARY_HOST: string;
-declare var EPROTECT_KEYS: Readonly<{
-    production: Readonly<{
-        keyId: "26455500012";
-        exponent: "10001";
-        modulus: "b9c7095ff203475347a932a6e11bacbb61cfb66a877158683634e5fb1dbf9923401bd7f82c21b67ffd3c82bdc64797c5e2ba4b57c68b1aaccb7fbe847da7234a21df910dfcc0aebacbbd4d36b35c0c35f7ee27358610d2e2fb2aa87d359deda0b5f4d77e31ac5ab98741da5b6052cb657087da05ad496154b8954939ee6fd463301ff15ebca94f210f4627a255a95ca8833728c1ab80b6cc3a874e4d3dce5d40f66c043ba1b042717bb9cc5d89434fa489a51c2ba9a3843b310df58c9e8a54c36cdd5fd66e76651b6fc88850b60e0739abfcf7d0d0cb44beb7e768da3bcea7e743b8c2d57edef59643f54432ccf60c49d4f5f84410ecf9c5a7af19bc5e792801";
-    }>;
-    sandbox: Readonly<{
-        keyId: "1";
-        exponent: "10001";
-        modulus: "bc637dd74ba76507dad5af1c7ad6f97dbef5298c3b9f74caea7301347db7b4a8c37f26491863100667246fd45071f3346bf62239f9b117d06fb67861b66ad0d158beeddd2f6f28be93d846f4c8f9ba1bd7e8f186f36cab0e432f22b3d732c221a9ff00a9bfacb88b24503e2695fd7237835d4936477b21289478906a49b164f52503c20eb29f11fcbda2af94deb9a0bfde5a4589276897436315c5d664d60bf10650164f509283aed39747ad5d6cb2bbe54e1b42306e5db37dfd42dcbfcc689e0ddfe3bc9cb22ae7018e5a4a1ff39813584ac7bd6d6d65ca763f0a672da454081ea20e8b1d403316d80b9353ba396bea8962b1a7d2f775c76612d857c1f7594f";
-    }>;
-}>;
+declare var EPROTECT_KEY_SOURCES: any;
+declare var EPROTECT_KEY_SCRIPT_MAX_BYTES: number;
 declare var EPROTECT_TEST_PANS: Readonly<Set<unknown>>;
 declare var EPROTECT_REFUSAL_CODES: readonly string[];
 declare function eprotectEnvironment(hostname: any): "production" | "sandbox" | null;
 declare function eprotectPreparationUrl(environment: any): string;
+declare function eprotectKeySourceUrl(environment: any): string;
+declare function eprotectScriptFacts(bytes: any): {
+    literals: number;
+    keyId?: undefined;
+    modulus?: undefined;
+    exponent?: undefined;
+    modulusSha256?: undefined;
+    maskedSha256?: undefined;
+} | {
+    literals: number;
+    keyId: string;
+    modulus: string;
+    exponent: string;
+    modulusSha256: string;
+    maskedSha256: string;
+};
+declare function eprotectKeyScriptVerdict(environment: any, bytes: any, sources?: any): {
+    ok: boolean;
+    reason: string;
+    maskedSha256?: undefined;
+    keyId?: undefined;
+    modulus?: undefined;
+    modulusSha256?: undefined;
+} | {
+    ok: boolean;
+    reason: string;
+    maskedSha256: string | undefined;
+    keyId?: undefined;
+    modulus?: undefined;
+    modulusSha256?: undefined;
+} | {
+    ok: boolean;
+    keyId: string;
+    modulus: string;
+    modulusSha256: string;
+    maskedSha256: string;
+    reason?: undefined;
+};
+declare function readEprotectKeyScript(environment: any, bytes: any, sources?: any): Readonly<{
+    environment: any;
+    keyId: string | undefined;
+    modulus: string | undefined;
+    exponent: "10001";
+    modulusSha256: string | undefined;
+}>;
+declare function eprotectKeyReport(key: any): Readonly<{
+    key_id: any;
+    modulus_sha256: any;
+}>;
 declare function isEprotectTokenRequest(url: any, method: any): boolean;
 declare function isEprotectRequest(request: any): boolean;
 declare function eprotectRequestFacts(url: any): {
@@ -35,7 +74,7 @@ declare function eprotectSecondaryAttempt(url: any): {
     paypageId: any;
     id: any;
 } | null;
-declare function isEprotectDeviceRequest(templateUrl: any, deviceUrl: any): boolean;
+declare function isEprotectDeviceRequest(templateUrl: any, deviceUrl: any, sessionKeyId: any): boolean;
 declare function isPreparedEprotectRequest(url: any, method: any, body: any, environment: any, paypageId: any): boolean;
 declare var EPROTECT_MERCHANT_PINS: any;
 declare function eprotectMerchantPin(paypageId: any, merchantOrigin: any, pins?: any): any;
@@ -43,7 +82,7 @@ declare function eprotectMerchantRefusal(environment: any, paypageId: any, merch
 declare function defaultRandom(bytes: any): void;
 declare function eprotectEncrypt(text: any, key: any, random?: typeof defaultRandom): string;
 declare function eprotectCardRefusal(environment: any, cardNumber: any): "unsupported_environment" | "sandbox_host_requires_documented_test_card" | "invalid_card_number" | "live_host_refuses_documented_test_card" | null;
-declare function eprotectDeviceRequest(templateUrl: any, card: any, random?: typeof defaultRandom): {
+declare function eprotectDeviceRequest(templateUrl: any, card: any, sessionKey: any, random?: typeof defaultRandom): {
     url: string;
     method: string;
     headers: {};
@@ -74,4 +113,4 @@ declare function eprotectGiveUp(url: any): {
     code: any;
 } | null;
 declare function eprotectRefusalCode(bodyText: any): any;
-export { EPROTECT_HOSTS, EPROTECT_KEYS, EPROTECT_MERCHANT_PINS, EPROTECT_PATH, EPROTECT_REFUSAL_CODES, EPROTECT_SECONDARY_HOST, EPROTECT_TEST_PANS, eprotectCardRefusal, eprotectDeviceRequest, eprotectEncrypt, eprotectEnvironment, eprotectGiveUp, eprotectJsonp, eprotectMerchantPin, eprotectMerchantRefusal, eprotectOutcome, eprotectPreparationUrl, eprotectRefusalCode, eprotectRequestFacts, eprotectSecondaryAttempt, isEprotectDeviceRequest, isEprotectRequest, isEprotectTokenRequest, isPreparedEprotectRequest, sanitizeEprotectRegistration };
+export { EPROTECT_HOSTS, EPROTECT_KEY_SCRIPT_MAX_BYTES, EPROTECT_KEY_SOURCES, EPROTECT_MERCHANT_PINS, EPROTECT_PATH, EPROTECT_REFUSAL_CODES, EPROTECT_SECONDARY_HOST, EPROTECT_TEST_PANS, eprotectCardRefusal, eprotectDeviceRequest, eprotectEncrypt, eprotectEnvironment, eprotectGiveUp, eprotectJsonp, eprotectKeyReport, eprotectKeyScriptVerdict, eprotectKeySourceUrl, eprotectMerchantPin, eprotectMerchantRefusal, eprotectOutcome, eprotectPreparationUrl, eprotectRefusalCode, eprotectRequestFacts, eprotectScriptFacts, eprotectSecondaryAttempt, isEprotectDeviceRequest, isEprotectRequest, isEprotectTokenRequest, isPreparedEprotectRequest, readEprotectKeyScript, sanitizeEprotectRegistration };