@agent-cards/sdk 0.22.0 → 0.23.0

package/dist/card-endpoint.js

@@ -2,18 +2,26 @@
 //
 // Some merchants post the typed card from their own checkout page straight to their
 // own server, with no processor in between (AT&T, Italo, Universal Orlando, Target
-// Optical, Opus Virtual Offices). Agentcard reviews each one and pins it as a profile
-// in the payment core (merchant-card-endpoints.generated.ts, the SDK's copy of the
-// same rules the API and the Vault run): the page the card is typed into, the exact
-// origin, path and query of the card request, which session headers and cookies it
-// needs, and which answer headers may travel back.
+// Optical, Opus Virtual Offices, Delta, Hilton, IHG, American Airlines, EconomyBookings,
+// The Verb Hotel, RunSignUp, Mindbody, LookFantastic), some after their page encrypts it
+// under a key the merchant publishes (Hyatt, LifeMiles, Southwest, United): the paused
+// body then holds the placeholder card only as the page encrypted it. Agentcard reviews
+// each one and pins it as a profile in the payment core (merchant-card-endpoints.generated.ts,
+// the SDK's copy of the same rules the API and the Vault run): the page the card is
+// typed into, the exact origin, path and query of the card request, which session
+// headers and cookies it needs, and which answer headers may travel back.
 //
 // The adapters arm every profile's endpoint. A POST that is exactly a profile's card
-// request pauses. While this build's copy of the profile does not take payments
-// (observe, a fact only a partner HAR can pin, no reviewed HAR, a recurring charge)
-// the request is aborted as an unsupported checkout and nothing is created. Otherwise
+// request URL pauses when it carries a card (cardEndpointCarriesCard); one that carries
+// none, such as a stay paid with points or a card a processor's own fields tokenized,
+// is the merchant's own business and continues untouched. While this build's copy of
+// the profile does not take payments (observe, a fact only a partner HAR can pin, no
+// reviewed HAR, a recurring charge) the card request is aborted as an unsupported
+// checkout and nothing is created. Otherwise
 // the adapter captures the request's session (the profile's own header list, the
-// endpoint's cookie jar for a cookie profile, a Referer on the checkout page) and
+// endpoint's cookie jar for a cookie profile, a Referer on the page the request is sent
+// from: the merchant's card vault frame when the profile names one, else the checkout
+// page) and
 // hands it with the paused body, which holds only the placeholder card the agent
 // typed, to the create. The cardholder's device sends the real card request to the
 // merchant itself, over the checkout relay, and reports the merchant's answer; the
@@ -22,11 +30,28 @@
 // write replaces) and answers the paused request with it. The real card never reaches
 // this process or the agent's page.
 //
+// Some merchants' pages submit the card form as a page load, not a fetch (a profile
+// whose `navigation` is 'top', or 'frame' for a form inside an iframe): MyRec, Conduent
+// eTIMS, the D-EDGE card frame. For those the adapters let a post that carries no card
+// through untouched (a cancel, another payment method), refuse a card post that is not
+// that navigation, answer the paid one with the merchant's page or a GET redirect, and
+// answer every stopped one with a page that says what happened (card-endpoint-page.ts),
+// never with an aborted load that invites another click on Pay.
+//
+// Some merchants need more (FastSpring's popup checkout for Lexicon). The card is typed
+// into a frame the merchant's page embeds, so for a profile with checkout_frame the page
+// a request pauses on is that frame's own document. The same URL also takes card-free
+// payments (PayPal, wallets), which continue untouched (cardEndpointPasses). A request
+// that sends the typed card again outside the card request is aborted in every status
+// (cardEndpointResendFor). And the merchant's own record of the order, which its page
+// reads from the endpoint origin, is recorded read-only (card-endpoint-facts.ts) and sent
+// with the create, so the agent's amount is held to the merchant's total.
+//
 // The endpoint URL (it carries cart, booking and instance ids), the paused body, the
 // session and the answer are cardholder data even with no real card in them: no
 // event, error or log line from this module names any of them. Events name the
 // profile id and the endpoint origin only.
-import { MERCHANT_CARD_ENDPOINT_MODE as SHARED_MODE, MERCHANT_CARD_ENDPOINT_PSP as SHARED_PSP, MERCHANT_CARD_ENDPOINT_RECOGNIZERS as SHARED_RECOGNIZERS, matchMerchantCardEndpoint as sharedMatch, merchantCardEndpointLive as sharedLive, merchantCardEndpointSessionRefusal as sharedSessionRefusal, } from './merchant-card-endpoints.generated.js';
+import { MERCHANT_CARD_ENDPOINT_MODE as SHARED_MODE, MERCHANT_CARD_ENDPOINT_PSP as SHARED_PSP, MERCHANT_CARD_ENDPOINT_RECOGNIZERS as SHARED_RECOGNIZERS, matchMerchantCardEndpoint as sharedMatch, matchMerchantCardEndpointResend as sharedResend, merchantCardEndpointBodyRefusal as sharedBodyRefusal, merchantCardEndpointCarriesCard as sharedCarriesCard, merchantCardEndpointLive as sharedLive, merchantCardEndpointNavigationAnswer as sharedNavigationAnswer, merchantCardEndpointPasses as sharedPasses, merchantCardEndpointSessionRefusal as sharedSessionRefusal, } from './merchant-card-endpoints.generated.js';
 /** The psp and mode a card endpoint authorization carries; neither is a processor. */
 export const CARD_ENDPOINT_PSP = SHARED_PSP;
 export const CARD_ENDPOINT_MODE = SHARED_MODE;
@@ -43,7 +68,7 @@ export class CardEndpointRefusedError extends Error {
         this.name = 'CardEndpointRefusedError';
     }
     /** True when every later request on the attachment would be refused the same way. */
-    get permanent() { return this.reason !== 'request_unsupported'; }
+    get permanent() { return !['request_unsupported', 'facts_unavailable', 'facts_refused'].includes(this.reason); }
 }
 /** The reviewed profile (any status) whose card request `url` and `method` are exactly, or null. */
 export function cardEndpointFor(url, method) {
@@ -58,10 +83,99 @@ export function cardEndpointFor(url, method) {
 export function cardEndpointById(id) {
     return PROFILES.find((profile) => profile.id === id) ?? null;
 }
+/**
+ * Whether a request to the profile's card endpoint is a card-free payment (the profile's
+ * payment_method names another method in the body): it is never Agentcard's and
+ * continues untouched, in every status. False for anything the rule cannot read, which
+ * is then held to the card request's rules.
+ */
+export function cardEndpointPasses(profile, body, contentType) {
+    if (typeof body !== 'string')
+        return false;
+    try {
+        return sharedPasses(profile.id, body, contentType) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The reviewed profile (any status) one of whose resend requests `url` and `method` are, or null: the adapters abort it. */
+export function cardEndpointResendFor(url, method) {
+    try {
+        return sharedResend(url, method) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The origins of the profiles whose merchant keeps its own record of the order: the only responses card-endpoint-facts.ts records. */
+export function cardEndpointFactsOrigins() {
+    return [...new Set(PROFILES.filter((profile) => profile.facts).map((profile) => profile.endpoint))];
+}
+/**
+ * The checkout session a request on the endpoint of a profile with facts belongs to: the
+ * endpoint origin and the profile's card path up to its bind placeholder, written with the
+ * request's own segments, the session payment-core binds the record to
+ * ('https://rekordcloud.onfastspring.com/popup-lexicon/session/<id>'). Null for any other
+ * request. card-endpoint-facts.ts counts what it keeps, and what a checkout lost, by it.
+ * When the paths of two profiles on one origin both fit, the shorter session is the one:
+ * every request on a card request's session then gets the card request's own.
+ */
+export function cardEndpointFactsSession(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const segments = parsed.pathname.split('/');
+    let shortest = null;
+    for (const profile of PROFILES) {
+        if (!profile.facts || profile.endpoint !== parsed.origin)
+            continue;
+        const template = profile.path.split('/');
+        const at = template.indexOf(`:${profile.facts.bind}`);
+        if (at < 1 || segments.length <= at || (shortest !== null && at >= shortest))
+            continue;
+        if (template.slice(0, at + 1).every((part, i) => (part.startsWith(':') ? segments[i] !== '' : part === segments[i])))
+            shortest = at;
+    }
+    return shortest === null ? null : `${parsed.origin}${segments.slice(0, shortest + 1).join('/')}`;
+}
 /** Whether this build's copy of the profile takes payments (enabled, nothing pending, a reviewed HAR, not recurring). */
 export function cardEndpointLive(profile) {
     return sharedLive(typeof profile === 'string' ? profile : profile.id) === true;
 }
+/**
+ * Whether a paused request to the profile's card request URL carries a card, so the
+ * adapters hold it (payment-core merchantCardEndpointCarriesCard): anything at the
+ * profile's card number field, or a Luhn-valid number of 12 to 19 digits anywhere in
+ * the body, however it is written. A body the adapter could not read (null), an empty
+ * one, and any answer the rule cannot give count as carrying one. A post to a
+ * navigation profile carries none only when it also reads under the profile's
+ * encoding, its card fields are empty and it holds no card number anywhere: no run of
+ * 12 to 19 digits, spaces, dots and dashes dropped, that passes the card check digit.
+ * Its page posts such a body for a cancel, another payment method or a bank payment,
+ * and it continues untouched.
+ */
+export function cardEndpointCarriesCard(profile, body, contentType) {
+    try {
+        return sharedCarriesCard(profile.id, body, contentType) !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/** Whether a paused body is the card request the profile reviewed (its body rules, never its status). */
+export function cardEndpointReviewed(profile, body, contentType) {
+    try {
+        return typeof body === 'string' && sharedBodyRefusal(profile.id, body, contentType) === null;
+    }
+    catch {
+        return false;
+    }
+}
 /** What an event may say about a card endpoint request: the profile and the endpoint origin, never the URL's path or query. */
 export function cardEndpointDetail(profile) {
     return { profile: profile.id, endpoint: profile.endpoint };
@@ -75,19 +189,26 @@ const globEscape = (text) => text.replace(/[\\*?]/g, (char) => `\\${char}`);
  * each paused request is held to, and anything it refuses continues untouched.
  */
 export function cardEndpointPatterns() {
-    return [...new Set(PROFILES.map((profile) => `${globEscape(profile.endpoint)}${profile.path.split('/').map((segment) => (segment.startsWith(':') ? '*' : globEscape(segment))).join('/')}*`))];
+    const pattern = (origin, path) => `${globEscape(origin)}${path.split('/').map((segment) => (segment.startsWith(':') ? '*' : globEscape(segment))).join('/')}*`;
+    return [...new Set(PROFILES.flatMap((profile) => [pattern(profile.endpoint, profile.path),
+            // Each resend is paused only to be refused (cardEndpointResendFor).
+            ...(profile.resends ?? []).map((resend) => pattern(profile.endpoint, resend.path))]))];
 }
 // Header names a capture never keeps, whatever a profile lists: the device's transport
 // writes Cookie, Origin and Host itself, the connection's own headers are its own, and
 // the Referer travels in its own member. payment-core's session check refuses the same.
 const NEVER_KEPT = /^(?:cookie|cookie2|set-cookie|origin|referer|host|content-length|transfer-encoding|connection|keep-alive|upgrade|te|trailer|expect|proxy-.*|:.*)$/;
-/** The paused request's Referer when it is a page on the profile's checkout origin, written as a browser serializes it; else nothing. */
+/**
+ * The paused request's Referer when it is a page on the origin the request is sent from
+ * (the profile's card vault frame when it names one, else its checkout origin), written
+ * as a browser serializes it; else nothing.
+ */
 function keptReferer(profile, value) {
     if (typeof value !== 'string' || value.includes('#'))
         return undefined;
     try {
         const url = new URL(value);
-        return url.origin === profile.checkout && url.href === value && !url.username && !url.password ? value : undefined;
+        return url.origin === (profile.frame ?? profile.checkout) && url.href === value && !url.username && !url.password ? value : undefined;
     }
     catch {
         return undefined;
@@ -95,8 +216,9 @@ function keptReferer(profile, value) {
 }
 /**
  * The session the create carries for a paused card endpoint request: the profile's own
- * header names and nothing else, the Referer only when it is a page on the checkout
- * origin, the endpoint's cookies only for a cookie profile, and the body. Checked with
+ * header names and nothing else, the Referer only when it is a page on the origin the
+ * request is sent from (the profile's card vault frame when it names one, else the
+ * checkout page), the endpoint's cookies only for a cookie profile, and the body. Checked with
  * the same rules the API and the device run (payment-core
  * merchantCardEndpointSessionRefusal), so a request they would refuse never leaves this
  * process: a CardEndpointRefusedError (`request_unsupported`) instead, naming no value.
@@ -119,9 +241,13 @@ export async function captureCardEndpointSession(profile, capture) {
         headers[lower] = typeof value === 'string' ? value : String(value);
     }
     const session = { url: capture.url, page_origin: capture.pageOrigin ?? '', headers, body: capture.body };
+    if (capture.navigation !== undefined)
+        session.navigation = capture.navigation;
     if (profile.session.cookies) {
         const jar = await capture.cookies();
-        session.cookies = (Array.isArray(jar) ? jar : []).map(({ name, value }) => ({ name, value }));
+        // Only the names the profile lists leave this process; every other cookie of the jar stays in the browser.
+        session.cookies = (Array.isArray(jar) ? jar : []).map(({ name, value }) => ({ name, value }))
+            .filter(({ name }) => cookieListed(profile, name));
     }
     if (referer !== undefined)
         session.referer = referer;
@@ -156,6 +282,17 @@ export const CARD_ENDPOINT_WITHHELD_ANSWER = Object.freeze({
     headers: Object.freeze({ 'content-type': 'application/json', 'cache-control': 'no-store' }),
     body: JSON.stringify({ error: { code: 'agentcard_answer_withheld', message: 'The merchant answered, and Agentcard withheld the answer because it could carry card data. Check the order with the merchant before trying again.' } }),
 });
+/**
+ * The fixed answer for a merchant answer the device withheld because it asks the page
+ * for a step the review refuses (withheld `refused_step_in_response`: FastSpring's EBANX
+ * step, which reads the typed card back and sends it again). The card request was sent,
+ * so the outcome is unknown until the order is checked.
+ */
+export const CARD_ENDPOINT_REFUSED_STEP_ANSWER = Object.freeze({
+    status: 502,
+    headers: Object.freeze({ 'content-type': 'application/json', 'cache-control': 'no-store' }),
+    body: JSON.stringify({ error: { code: 'agentcard_step_refused', message: 'The merchant asked for a payment step Agentcard does not take part in, so Agentcard withheld its answer. Check the order with the merchant before trying again.' } }),
+});
 // RFC 6265 cookie-name (a token) and cookie-value, as payment-core checks a session cookie.
 const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]{1,256}$/;
 const COOKIE_VALUE = /^(?:[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]*|"[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]*")$/;
@@ -280,6 +417,21 @@ export function cardEndpointCookies(profile, requestUrl, setCookies, nowMs = Dat
     }
     return { cookies, skipped };
 }
+/** Whether a cookie name is one the profile lets travel (payment-core reads the same list). */
+function cookieListed(profile, name) {
+    const names = profile.session.cookie_names;
+    if (names === null)
+        return true;
+    return typeof name === 'string' && names.some((entry) => (entry.endsWith('*') ? name.startsWith(entry.slice(0, -1)) && name.length > entry.length - 1 : name === entry));
+}
+/**
+ * How a paused navigation is answered from the merchant's answer (payment-core
+ * merchantCardEndpointNavigationAnswer): the page, a 301, 302 or 303 to one https URL,
+ * or refused (a redirect that repeats the post, or a Location that is not one https URL).
+ */
+export function cardEndpointNavigationAnswer(profile, answer, requestUrl) {
+    return sharedNavigationAnswer(profile.id, answer, requestUrl);
+}
 /** Why a session is not one the profile lets travel (payment-core merchantCardEndpointSessionRefusal), or null. Names no value. */
 export function cardEndpointSessionRefusal(profile, session) {
     return sharedSessionRefusal(profile.id, session) ?? null;