@agent-cards/sdk 0.21.0 → 0.23.0

package/dist/card-endpoint.js

@@ -0,0 +1,438 @@
+// A reviewed merchant's own card endpoint: the SDK's half of the card endpoint mode.
+//
+// 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, 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 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 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
+// adapter writes its Set-Cookie values into the agent's browser on the endpoint host
+// (or on the parent domain of a cookie the browser already holds there, which the
+// 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, 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;
+const PROFILES = SHARED_RECOGNIZERS;
+export class CardEndpointRefusedError extends Error {
+    profile;
+    reason;
+    detail;
+    constructor(profile, reason, detail = null) {
+        super(`refused a payment to the ${profile} card endpoint (${reason})${detail ? `: ${detail}` : ''}. Nothing was created and nothing was charged.`);
+        this.profile = profile;
+        this.reason = reason;
+        this.detail = detail;
+        this.name = 'CardEndpointRefusedError';
+    }
+    /** True when every later request on the attachment would be refused the same way. */
+    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) {
+    try {
+        return sharedMatch(url, method, undefined) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The reviewed profile with this id, or null. */
+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 };
+}
+// A CDP URL pattern treats '*' and '?' as wildcards and '\' as their escape.
+const globEscape = (text) => text.replace(/[\\*?]/g, (char) => `\\${char}`);
+/**
+ * Fetch.enable patterns covering every profile's card request, in any status: its
+ * origin and path with each `:name` segment and the query as wildcards. A coarse
+ * pre-filter, like cardUrlPatterns for processors; cardEndpointFor is the exact check
+ * each paused request is held to, and anything it refuses continues untouched.
+ */
+export function cardEndpointPatterns() {
+    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 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.frame ?? profile.checkout) && url.href === value && !url.username && !url.password ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 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.
+ */
+export async function captureCardEndpointSession(profile, capture) {
+    const headers = {};
+    const seen = new Set();
+    let referer;
+    for (const [name, value] of Object.entries(capture.headers ?? {})) {
+        const lower = name.toLowerCase();
+        if (seen.has(lower))
+            throw new CardEndpointRefusedError(profile.id, 'request_unsupported', 'the paused request names one header twice');
+        seen.add(lower);
+        if (lower === 'referer') {
+            referer = keptReferer(profile, value);
+            continue;
+        }
+        if (NEVER_KEPT.test(lower) || !profile.session.headers.includes(lower))
+            continue;
+        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();
+        // 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;
+    const refusal = sharedSessionRefusal(profile.id, session);
+    if (refusal)
+        throw new CardEndpointRefusedError(profile.id, 'request_unsupported', refusal);
+    return session;
+}
+/**
+ * The headers the paused request is answered with: the profile's answer headers the
+ * merchant sent, and never Set-Cookie (cookies reach the browser through
+ * cardEndpointCookies, on the endpoint host only).
+ */
+export function cardEndpointAnswerHeaders(profile, headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (lower === 'set-cookie' || !profile.response.headers.includes(lower) || typeof value !== 'string' || !/^[\x20-\x7e\t]*$/.test(value))
+            continue;
+        out[lower] = value;
+    }
+    return out;
+}
+/**
+ * The fixed answer a paused request gets when the cardholder's device withheld the
+ * merchant's answer (it carried the card, or a compressed stream the device cannot
+ * read): an error the merchant's page stops on. The card request was sent; whether
+ * the merchant took the payment is unknown until the order is checked.
+ */
+export const CARD_ENDPOINT_WITHHELD_ANSWER = Object.freeze({
+    status: 502,
+    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]*")$/;
+const COOKIE_PATH = /^\/[\x21-\x3a\x3c-\x7e]{0,1023}$/;
+// Browsers keep a cookie for at most 400 days.
+const MAX_COOKIE_AGE_S = 400 * 24 * 60 * 60;
+/** RFC 6265 5.1.4: the directory of the request path, the path a cookie with no Path attribute gets. */
+function defaultCookiePath(requestUrl) {
+    let path;
+    try {
+        path = new URL(requestUrl).pathname;
+    }
+    catch {
+        return '/';
+    }
+    const last = path.lastIndexOf('/');
+    return last <= 0 ? '/' : path.slice(0, last);
+}
+/**
+ * One Set-Cookie line as the cookie to write, or null when a browser would not store it
+ * or it cannot be written safely. `jar` is the endpoint's cookies (null when they could
+ * not be read). A Domain attribute the endpoint host does not belong to drops the cookie
+ * (RFC 6265 5.3), as a browser does. One the host belongs to puts the cookie on that
+ * domain when the jar already holds a domain cookie of this name there, so the rotation
+ * replaces it; otherwise the cookie stays host-only. With the jar unread, a cookie that
+ * names a Domain is not written, since its write could leave two cookies of one name.
+ */
+function parseSetCookie(profile, requestUrl, line, nowS, jar) {
+    if (typeof line !== 'string' || line.length > 8192 || /[\x00-\x08\x0a-\x1f\x7f]/.test(line))
+        return null;
+    const [pair, ...attributes] = line.split(';');
+    const eq = pair.indexOf('=');
+    if (eq <= 0)
+        return null;
+    const name = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1).trim();
+    if (!COOKIE_NAME.test(name) || !COOKIE_VALUE.test(value))
+        return null;
+    let path = defaultCookiePath(requestUrl);
+    let secure = false;
+    let httpOnly = false;
+    let sameSite;
+    let expires;
+    let maxAge;
+    let named;
+    for (const attribute of attributes) {
+        const at = attribute.indexOf('=');
+        const key = (at === -1 ? attribute : attribute.slice(0, at)).trim().toLowerCase();
+        const text = at === -1 ? '' : attribute.slice(at + 1).trim();
+        if (key === 'path') {
+            if (COOKIE_PATH.test(text))
+                path = text;
+        }
+        else if (key === 'secure')
+            secure = true;
+        else if (key === 'httponly')
+            httpOnly = true;
+        else if (key === 'samesite') {
+            const lower = text.toLowerCase();
+            sameSite = lower === 'strict' ? 'Strict' : lower === 'lax' ? 'Lax' : lower === 'none' ? 'None' : undefined;
+        }
+        else if (key === 'max-age') {
+            if (/^-?\d{1,12}$/.test(text))
+                maxAge = Number(text);
+        }
+        else if (key === 'expires') {
+            const at = Date.parse(text);
+            if (Number.isFinite(at))
+                expires = Math.floor(at / 1000);
+        }
+        // RFC 6265 5.2.3: the last non-empty Domain counts, without a leading dot, in lower case.
+        else if (key === 'domain') {
+            const domain = text.replace(/^\./, '').toLowerCase();
+            if (domain !== '')
+                named = domain;
+        }
+    }
+    if (maxAge !== undefined)
+        expires = maxAge <= 0 ? 1 : nowS + Math.min(maxAge, MAX_COOKIE_AGE_S);
+    else if (expires !== undefined)
+        expires = expires <= nowS ? 1 : Math.min(expires, nowS + MAX_COOKIE_AGE_S);
+    // The prefixes a browser enforces on the merchant's own line: __Secure- needs Secure,
+    // __Host- also needs Path=/.
+    if ((name.startsWith('__Secure-') || name.startsWith('__Host-')) && !secure)
+        return null;
+    if (name.startsWith('__Host-') && path !== '/')
+        return null;
+    const host = new URL(profile.endpoint).hostname;
+    let domain;
+    if (named !== undefined) {
+        // __Host- cookies never name a Domain; a Domain the endpoint host is not inside is refused by a browser.
+        if (name.startsWith('__Host-') || (host !== named && !host.endsWith(`.${named}`)))
+            return null;
+        if (jar === null)
+            return null;
+        if (jar.some((held) => held.name === name && String(held.domain).toLowerCase() === `.${named}`))
+            domain = named;
+    }
+    return {
+        name, value, origin: profile.endpoint, host, ...(domain !== undefined ? { domain } : {}), path, secure: true, httpOnly,
+        ...(sameSite ? { sameSite } : {}), ...(expires !== undefined ? { expires } : {}),
+    };
+}
+/**
+ * The merchant's Set-Cookie values as cookies to write (parseSetCookie), and how many
+ * could not be written as one (a malformed line, a prefix or a Domain the browser would
+ * refuse, a Domain with the jar unread). `jar` is the endpoint's cookies as the adapter
+ * read them, null when the read failed. Only a profile whose answer may carry cookies
+ * has any.
+ */
+export function cardEndpointCookies(profile, requestUrl, setCookies, nowMs = Date.now(), jar = []) {
+    if (!profile.response.headers.includes('set-cookie'))
+        return { cookies: [], skipped: setCookies.length };
+    const cookies = [];
+    let skipped = 0;
+    for (const line of setCookies) {
+        const cookie = parseSetCookie(profile, requestUrl, line, Math.floor(nowMs / 1000), jar);
+        if (cookie)
+            cookies.push(cookie);
+        else
+            skipped += 1;
+    }
+    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;
+}

package/dist/card-fields.generated.d.ts

@@ -1,3 +1,5 @@
-declare function carriesCardFields(recognizer: any, body: any): boolean;
-declare function requestWithoutCard(recognizer: any, url: any, body: any): "continue" | "refuse" | null;
-export { carriesCardFields, requestWithoutCard };
+declare function carriesCardFields(recognizer: any, body: any): any;
+declare function splitCardLeg(recognizer: any, body: any): "absorb" | "pass" | null;
+declare function requestWithoutCard(recognizer: any, url: any, body: any): "refuse" | "continue" | null;
+declare function cardRequestRefusal(recognizer: any, url: any, body: any): any;
+export { cardRequestRefusal, carriesCardFields, requestWithoutCard, splitCardLeg };