@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/cybersource-flex.js

@@ -0,0 +1,275 @@
+// CyberSource Flex Microform v2 in the checkout SDK (design cybersource_flex, revised).
+//
+// The card field is CyberSource's own iframe, and the request it sends (a POST of a compact JWE
+// to /flex/v2/tokens) is sealed under a capture context the merchant minted for this checkout.
+// The paused body is ciphertext of the agent's placeholder card, so nothing in it can be swapped:
+// the cardholder's device seals the real card itself under the same context and sends it to
+// CyberSource, and the transient token that comes back answers the paused request. The context
+// lives only in the field iframe's URL fragment, so this module reads it there, verifies it
+// offline against the signing keys payment-core pins (no network), and hands it to authorize()
+// beside the paused request. The API and the device verify it again.
+//
+// Recognition is not coverage: Microform v0.x and Flex API direct traffic post to the same URL.
+// A POST pauses only when it comes from a Microform v2 card field of a reviewed version whose
+// committed document URL this attachment read, sealed under the context that URL carries. A check
+// (eCheck) Microform carries no card and continues untouched; everything else is refused before
+// any authorization exists.
+//
+// The API serves the Flex recognizer only to an org Agentcard enabled for CyberSource Flex, so
+// for every other org nothing here runs: the SDK never recognizes a Flex host and the field's
+// request goes through untouched, as it did before this build.
+import { assertCybersourceFlexTemplate, cybersourceFlexHostEnvironment, cybersourceFlexTemplateKid, isCybersourceFlexRequest, parseMicroformFragment, verifyCaptureContext, } from './cybersource-flex.generated.js';
+/** The processor id, as the registry and the API name it. */
+export const CYBERSOURCE_FLEX_PSP = 'cybersource_flex';
+/**
+ * The dark-launch capability the Flex recognizer names: the capture-context sidecar a create
+ * must carry. syncRegistry declares it (SUPPORTED_CAPABILITIES), because this build reads the
+ * context and sends it; the API serves the recognizer only to a client that does.
+ */
+export const CYBERSOURCE_FLEX_CAPABILITY = 'capture_context';
+const MICROFORM_FIELDS = ['number', 'securityCode'];
+/** An https URL on flex.cybersource.com or testflex.cybersource.com, with no port or credentials. */
+export function isCybersourceFlexHost(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' && !parsed.port && !parsed.username && !parsed.password
+            && cybersourceFlexHostEnvironment(parsed.hostname) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * How an adapter fails a card request it will not let through: a CyberSource Flex request as a
+ * network error (Playwright 'failed', CDP 'Failed', net::ERR_FAILED), every other request as an
+ * abort (net::ERR_ABORTED). Microform 2.12.1's field reports a failed request to the merchant's page
+ * at once (createToken's callback gets CREATE_TOKEN_XHR_ERROR), so the page runs its own error path:
+ * a message, a retry under the same capture context, or GetPay's reload under a new one. It never
+ * reports an aborted request, so after a refusal or a decline the page's createToken would wait with
+ * no answer. Both were observed with the real field on CyberSource's sandbox.
+ */
+export function refusedRequestFailure(url) {
+    return isCybersourceFlexHost(url) ? 'failed' : 'aborted';
+}
+function frameOf(url) {
+    if (typeof url !== 'string' || !url)
+        return null;
+    try {
+        return parseMicroformFragment(url);
+    }
+    catch {
+        return null;
+    }
+}
+/** payment-core's own clock allowance on a context's exp. */
+const CLOCK_SKEW_MS = 60_000;
+const MAX_CONTEXTS = 32;
+const MAX_FRAMES = 64;
+function causeOf(error) {
+    const reason = error?.reason;
+    return typeof reason === 'string' && /^[a-z_]{1,32}$/.test(reason) ? reason : 'crypto';
+}
+/**
+ * Each capture context verified once, offline, against the keys payment-core pins, and
+ * remembered for the attachment. The adapters start a context's check when its field iframe
+ * loads, so by the time the page sends its card the answer is usually settled and the pause
+ * stays synchronous. Bounded: the oldest context is dropped past 32.
+ */
+export class CaptureContexts {
+    entries = new Map();
+    verify(jwt) {
+        let entry = this.entries.get(jwt);
+        if (!entry) {
+            if (this.entries.size >= MAX_CONTEXTS)
+                this.entries.delete(this.entries.keys().next().value);
+            const created = { promise: Promise.resolve({ ok: false, cause: 'crypto' }) };
+            created.promise = Promise.resolve()
+                .then(() => verifyCaptureContext(jwt, { crypto: globalThis.crypto }))
+                .then((context) => (created.settled = { ok: true, context: context }), (error) => (created.settled = { ok: false, cause: causeOf(error) }));
+            this.entries.set(jwt, created);
+            entry = created;
+        }
+        return entry.settled ?? entry.promise;
+    }
+    /** Start the check of a card field iframe's capture context from the frame's URL, when it is one. */
+    warm(url) {
+        const frame = frameOf(url);
+        if (frame && frame.microformType === 'card' && frame.reviewed)
+            void this.verify(frame.captureContext);
+    }
+}
+/**
+ * The fields that loaded for the issuing frame's Microform: every frame sharing its capture
+ * context, microform id, version, host and type. Null when they are not a number field plus an
+ * optional security code field, which is all the device can rebuild.
+ */
+function fieldsOf(issuing, frames) {
+    const types = new Set([issuing.fieldType]);
+    for (const frame of frames) {
+        if (frame.captureContext === issuing.captureContext && frame.microformId === issuing.microformId
+            && frame.version === issuing.version && frame.environment === issuing.environment
+            && frame.microformType === issuing.microformType)
+            types.add(frame.fieldType);
+    }
+    if (!types.has('number') || [...types].some((type) => !MICROFORM_FIELDS.includes(type)))
+        return null;
+    return MICROFORM_FIELDS.filter((field) => types.has(field));
+}
+function afterVerification(request, issuing, fields, verification) {
+    if (!verification.ok)
+        return { kind: 'refuse', reason: 'capture_context_invalid', cause: verification.cause };
+    const context = verification.context;
+    if (!(context.exp * 1000 > Date.now() - CLOCK_SKEW_MS))
+        return { kind: 'refuse', reason: 'capture_context_invalid', cause: 'expired' };
+    if (context.url !== request.url || context.environment !== issuing.environment) {
+        return { kind: 'refuse', reason: 'capture_context_invalid', cause: 'url_mismatch' };
+    }
+    try {
+        assertCybersourceFlexTemplate(request.body, context);
+    }
+    catch {
+        return { kind: 'refuse', reason: 'capture_context_mismatch' };
+    }
+    const trigger = issuing.fieldType;
+    return {
+        kind: 'pause',
+        flex: {
+            sidecar: { capture_context: issuing.captureContext, microform: { version: issuing.version, fields, trigger } },
+            shape: `jwe:${issuing.microformType}:${fields.join(',')}:${cybersourceFlexTemplateKid(request.body)}:${issuing.captureContext}`,
+        },
+    };
+}
+/**
+ * Judge one POST to a Flex host, given the frame that sent it and every Microform frame this
+ * attachment knows. `issuing` is that frame read as a Microform field: `undefined` when its URL
+ * could not be read at all, `null` when it was read and is no Microform v2 field (the merchant's
+ * own page or frame, which is where Flex API direct traffic comes from). In order:
+ *   1. a check (eCheck) Microform: continue, it carries no card;
+ *   2. a body the adapter could not read: refuse this request;
+ *   3. not a field iframe's sealed card (application/jwt, a Microform JWE, the exact tokens
+ *      URL): unsupported, Microform v0.x and Flex API direct post here too;
+ *   4. a frame that could not be read: refuse this request, since the read can fail for a
+ *      reason the page's next request does not repeat (a missed event, a slow frame tree read);
+ *   5. a frame read and found to be no Microform field, an unreviewed version, or fields the
+ *      device cannot rebuild: unsupported, as the page's next request repeats each of them;
+ *   6. a capture context that does not verify, has expired, names another URL or host, or did
+ *      not seal this body: refuse this request;
+ *   7. otherwise pause, with the sidecar the create carries.
+ * Returns synchronously when the context's verification already settled.
+ */
+export function judgeMicroformRequest(request, issuing, frames, contexts) {
+    if (issuing && issuing.microformType !== 'card')
+        return { kind: 'continue' };
+    if (request.body === null)
+        return { kind: 'refuse', reason: 'request_body_unreadable' };
+    if (!isCybersourceFlexRequest(request.url, 'POST', request.body, request.headers)) {
+        return { kind: 'unsupported', reason: 'microform_request_unrecognized' };
+    }
+    if (issuing === undefined)
+        return { kind: 'refuse', reason: 'microform_frame_unread' };
+    if (issuing === null)
+        return { kind: 'unsupported', reason: 'microform_request_unrecognized' };
+    if (!issuing.reviewed)
+        return { kind: 'unsupported', reason: 'microform_version_unreviewed' };
+    const fields = fieldsOf(issuing, frames);
+    if (!fields || !MICROFORM_FIELDS.includes(issuing.fieldType)) {
+        return { kind: 'unsupported', reason: 'microform_fields_unsupported' };
+    }
+    const withBody = request;
+    const verification = contexts.verify(issuing.captureContext);
+    return verification instanceof Promise
+        ? verification.then((settled) => afterVerification(withBody, issuing, fields, settled))
+        : afterVerification(withBody, issuing, fields, verification);
+}
+/**
+ * The CDP adapter's record of Microform field iframes, keyed by frame id (an out-of-process
+ * iframe's target id is its frame id). Fed only from CDP sources that report a document the
+ * frame COMMITTED, with its fragment: Page.frameNavigated (the child's own session for an
+ * out-of-process iframe, the parent's for an in-process one), the iframe target's url on
+ * Target.attachedToTarget when the SDK attaches to a form that already rendered, and the
+ * pausing session's Page.getFrameTree as a last read. A document request (Network.
+ * requestWillBeSent, Fetch.requestPaused) is only a hint that warms the context's check: a page
+ * can start a navigation to a genuine field URL in a frame it scripts and stop it before it
+ * commits, and that frame then still runs the page's own document. A frame that navigates
+ * elsewhere or detaches is forgotten. Bounded to the 64 most recent frames.
+ */
+export class MicroformFrames {
+    frames = new Map();
+    contexts = new CaptureContexts();
+    /** Start the capture context's check from a navigation that has not committed; records nothing. */
+    warm(url) {
+        this.contexts.warm(url);
+    }
+    /** A frame's committed document URL, fragment included. A URL that is not a field iframe's forgets the frame. */
+    observe(frameId, url) {
+        if (typeof frameId !== 'string' || !frameId || frameId.length > 256)
+            return;
+        const frame = frameOf(url);
+        if (!frame) {
+            if (typeof url === 'string' && url)
+                this.frames.delete(frameId);
+            return;
+        }
+        this.frames.delete(frameId);
+        if (this.frames.size >= MAX_FRAMES)
+            this.frames.delete(this.frames.keys().next().value);
+        this.frames.set(frameId, frame);
+        // Warm the verification so the card request's pause stays synchronous.
+        if (frame.microformType === 'card' && frame.reviewed)
+            void this.contexts.verify(frame.captureContext);
+    }
+    forget(frameId) {
+        if (typeof frameId === 'string')
+            this.frames.delete(frameId);
+    }
+    /**
+     * Judge a POST the frame `frameId` sent. When that frame is not on record, `reread` reads the
+     * pausing session's frame tree once (recording what it finds) and resolves to the frame's
+     * committed URL, or undefined when the frame was not found or the read failed: a frame read and
+     * found to be no field is judged as such, one never read is refused for this request alone.
+     */
+    judge(request, frameId, reread) {
+        const issuing = frameId ? this.frames.get(frameId) : undefined;
+        if (!issuing && frameId && reread) {
+            return reread().catch(() => undefined).then((url) => judgeMicroformRequest(request, this.frames.get(frameId) ?? (url === undefined ? undefined : frameOf(url)), this.frames.values(), this.contexts));
+        }
+        return judgeMicroformRequest(request, issuing, this.frames.values(), this.contexts);
+    }
+}
+/**
+ * The Playwright adapter's judge: Playwright keeps a frame's fragment in frame.url() (checked in
+ * cybersource-flex-browser.test.mjs) and moves frame.url() only when a navigation commits, so the
+ * issuing frame and its siblings are read at pause time. `issuingUrl` is undefined when the
+ * request's frame could not be read at all.
+ */
+export function judgeMicroformFrameUrls(request, issuingUrl, frameUrls, contexts) {
+    const frames = [];
+    for (const url of frameUrls) {
+        const frame = frameOf(url);
+        if (frame)
+            frames.push(frame);
+    }
+    return judgeMicroformRequest(request, issuingUrl === undefined ? undefined : frameOf(issuingUrl), frames, contexts);
+}
+/**
+ * Whether a create's sidecar has the shape the API admits (routes/api/v2/checkout.ts
+ * createSchema): a capture context of 1 to 16384 characters, and a Microform version with a
+ * number field, an optional security code field and a trigger among them. authorize() checks
+ * it before any create, so a hand-built request fails locally rather than at the API.
+ */
+export function validCybersourceFlexSidecar(captureContext, microform) {
+    if (typeof captureContext !== 'string' || captureContext.length < 1 || captureContext.length > 16384)
+        return false;
+    if (!microform || typeof microform !== 'object' || Array.isArray(microform))
+        return false;
+    const value = microform;
+    if (Object.keys(value).some((key) => !['version', 'fields', 'trigger'].includes(key)))
+        return false;
+    if (typeof value.version !== 'string' || !/^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$/.test(value.version))
+        return false;
+    const fields = value.fields;
+    if (!Array.isArray(fields) || fields.length < 1 || fields.length > 2 || new Set(fields).size !== fields.length
+        || fields.some((field) => !MICROFORM_FIELDS.includes(field)) || !fields.includes('number'))
+        return false;
+    return value.trigger === undefined || fields.includes(value.trigger);
+}

package/dist/datatrans.d.ts

@@ -0,0 +1,96 @@
+import { DATATRANS_CARD_ON_FILE_REFUSED, DATATRANS_INVALID_REQUEST } from './datatrans.generated.js';
+import type { ReplayResponse } from './client.js';
+export declare const DATATRANS_PSP = "datatrans";
+/** The dark-launch capability the API serves the datatrans recognizer behind. */
+export declare const DATATRANS_CAPABILITY = "datatrans_secure_fields_tokenize";
+/**
+ * Why the SDK refuses a Datatrans card post before anything is claimed, created or prompted. The
+ * API answers the same two codes at create, so a refusal here only saves the round trip:
+ *   - `invalid_datatrans_request`: not a sound Secure Fields TOKENIZE card post. That covers
+ *     another mode, a payment or 3-D Secure post (`transactionId`, `3D`, `dccSelected`), a key
+ *     field.js never sends, a URL variant (a query, a case or dot spelling) or a content type that
+ *     is not jQuery's form type. The cardholder's device could never fill it.
+ *   - `datatrans_card_on_file_refused`: a sound post that asks PCI Proxy to keep the card on file
+ *     (usage=REGISTRATION: a reusable alias plus a network token, so the merchant could charge the
+ *     card again later), while the card-on-file policy the API served refuses that
+ *     (datatransCardOnFilePolicy). British Airways's Nexus checkout sends it for every new card.
+ */
+export type DatatransRefusalReason = typeof DATATRANS_INVALID_REQUEST | typeof DATATRANS_CARD_ON_FILE_REFUSED;
+/** True when the URL's host is one of Datatrans's two pay hosts. */
+export declare function isDatatransHost(url: string): boolean;
+/**
+ * The card-on-file policy this build applies to a Datatrans card post: the one the API served with
+ * the datatrans recognizer (Recognizer.cardOnFile, VaultClient.cardOnFilePolicy) when payment-core
+ * defines it (`refuse`, `disclose`, `agentcard_single_use`), and `refuse` for anything else, an entry
+ * that names none included. The decision is payment-core's DATATRANS_REGISTRATION_POLICY, which the
+ * API reads each time it serves the catalog and again at create, so a change to that one line
+ * reaches every build already published at its next syncRegistry(), with no SDK release.
+ */
+export declare function datatransCardOnFilePolicy(served: unknown): string;
+/**
+ * The pause decision for a POST the registry recognized on a Datatrans pay host, by payment-core's
+ * classifyDatatransRequest under the card-on-file policy the API served (datatransCardOnFilePolicy):
+ *   'card'  the exact card URL with jQuery's form type and a sound TOKENIZE card body: it pauses. A
+ *           usage=REGISTRATION post is one too once the served policy allows card on file, and the
+ *           API and the cardholder's device then apply that policy;
+ *   a DatatransRefusalReason: it is refused in the browser;
+ *   null    no card in the body (a wallet, bank-account or CVV-only post) or not the card path:
+ *           the SDK's ordinary handling decides, and such a post continues untouched.
+ */
+export declare function datatransPauseDecision(request: {
+    url: string;
+    headers: Record<string, string>;
+    body: string | null;
+}, servedPolicy?: unknown): 'card' | DatatransRefusalReason | null;
+/**
+ * How long an approved Datatrans answer is replayed to its own frame: the token's own lifetime
+ * (PCI Proxy keeps a tokenization readable for 30 minutes). Past it the stored transactionId names a
+ * token the merchant can no longer read, so a later post is a new question.
+ */
+export declare const DATATRANS_REPEAT_WINDOW_MS: number;
+/**
+ * How long a stored answer waits for its form's next post. British Airways re-submits while the agent
+ * finishes the card form, right after the approved answer. A form that posts nothing for this long has
+ * moved on: the order was placed or abandoned, which the SDK cannot tell apart without reconcile(). Its
+ * next post is a new approval. Each answered re-submit restarts the wait, and the token's lifetime
+ * still ends every answer.
+ */
+export declare const DATATRANS_REPEAT_IDLE_MS: number;
+/** A stored answer handed to a repeat, with the approval it came from. */
+export interface DatatransRepeatAnswer {
+    authorizationId: string;
+    response: {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+}
+/**
+ * The approved Datatrans answers one attachment handed to a card post, per frame. `frame` is the
+ * adapter's identity for the request's frame (the CDP frameId, the Playwright Frame); a request
+ * whose frame is unknown is never remembered and never answered. Only an answer payment-core reads
+ * as approved ({transactionId, cardInfo}) is kept: an error answer leaves the next post a new
+ * question, so the page can try again.
+ */
+export declare class DatatransRepeats {
+    private readonly windowMs;
+    private readonly now;
+    private readonly idleMs;
+    private remembered;
+    constructor(windowMs?: number, now?: () => number, idleMs?: number);
+    /**
+     * Keep the answer a token replay handed to this card post, when Datatrans approved it. Called
+     * after the answer reached the browser, so it never throws: a failure here only leaves the
+     * page's next post a new question.
+     */
+    remember(frame: unknown, url: string, body: string | null, replay: ReplayResponse): void;
+    /**
+     * The stored answer for a repeat of an answered card post from the same frame, or null. Only an
+     * answer from `authorizationId`, the approval the attachment is handing off now, is handed out,
+     * and every answer from another approval is dropped: a later authorization ends the window of
+     * every earlier one. An answer whose form stayed quiet past the idle bound is dropped too, and
+     * handing one out restarts that bound.
+     */
+    answerFor(frame: unknown, url: string, body: string | null, authorizationId: string | null): DatatransRepeatAnswer | null;
+    private prune;
+}

package/dist/datatrans.generated.d.ts

@@ -0,0 +1,64 @@
+declare var DATATRANS_HOSTS: readonly string[];
+declare var DATATRANS_TOKENIZE_PATH: string;
+declare var DATATRANS_REFUSAL_REASONS: readonly string[];
+declare var DATATRANS_INVALID_REQUEST: string;
+declare var DATATRANS_CARD_ON_FILE_REFUSED: string;
+declare var DATATRANS_REGISTRATION_POLICIES: readonly string[];
+declare var DATATRANS_REGISTRATION_POLICY: string;
+declare var DATATRANS_REVIEWED_MERCHANT_IDS: Readonly<{
+    "pay.datatrans.com": readonly never[];
+    "pay.sandbox.datatrans.com": readonly string[];
+}>;
+declare var DATATRANS_PAYMENT_METHODS: readonly string[];
+declare var DATATRANS_TEST_PANS: readonly string[];
+declare function encodeDatatransFormValue(value: any): string;
+declare function parseDatatransForm(body: any): {
+    key: string;
+    value: string;
+    rawKey: string;
+    raw: string;
+}[] | null;
+declare function serializeDatatransForm(pairs: any): any;
+declare function isDatatransTokenizeUrl(url: any, method?: string): boolean;
+declare function datatransRegistrationRefusal(usage: any, card: any, policy?: string): "card_on_file" | null;
+declare function datatransCardOnFileDisclosure(body: any, policy?: string): boolean;
+declare function datatransBodyRefusal(body: any, card: any, policy?: string): "unsupported" | "card_on_file" | null;
+declare function datatransMerchantId(body: any): string | null | undefined;
+declare function classifyDatatransRequest(url: any, method: any, body: any, headers: any, policy?: string): "card" | "unsupported" | "card_on_file" | null;
+declare function datatransTokenizeRefusal(request: any, card: any, policy?: string): "unsupported" | "card_on_file" | null;
+declare function isDatatransTokenizeRequest(request: any, card: any): boolean;
+declare function datatransMerchantRefusal(url: any, body: any, merchants?: Readonly<{
+    "pay.datatrans.com": readonly never[];
+    "pay.sandbox.datatrans.com": readonly string[];
+}>): "unregistered_merchant" | null;
+declare function datatransDeviceRefusal(request: any, card: any, policy?: string, merchants?: Readonly<{
+    "pay.datatrans.com": readonly never[];
+    "pay.sandbox.datatrans.com": readonly string[];
+}>): "unsupported" | "card_on_file" | "brand_mismatch" | "unregistered_merchant" | null;
+declare function datatransRefusalMessage(reason: any): string;
+declare function datatransCardBrand(number: any): "VIS" | "ECA" | "AMX" | null;
+declare function datatransBrandRefusal(body: any, card: any): "unsupported" | "brand_mismatch" | null;
+declare function injectDatatransCard(body: any, card: any, policy?: string): {
+    body: string;
+    where: string[];
+};
+declare function datatransErrorCode(message: any): string | RegExp;
+declare function datatransResponseOutcome(status: any, body: any, card: any): {
+    outcome: string;
+    reason: string;
+    code?: undefined;
+} | {
+    outcome: string;
+    code: string | RegExp;
+    reason?: undefined;
+} | {
+    outcome: string;
+    reason?: undefined;
+    code?: undefined;
+};
+declare function sanitizeDatatransTokenResponse(body: any): string;
+declare function datatransFacts(status: any, body: any): {
+    outcome: string;
+    refusalCode: string | RegExp | null | undefined;
+};
+export { DATATRANS_CARD_ON_FILE_REFUSED, DATATRANS_HOSTS, DATATRANS_INVALID_REQUEST, DATATRANS_PAYMENT_METHODS, DATATRANS_REFUSAL_REASONS, DATATRANS_REGISTRATION_POLICIES, DATATRANS_REGISTRATION_POLICY, DATATRANS_REVIEWED_MERCHANT_IDS, DATATRANS_TEST_PANS, DATATRANS_TOKENIZE_PATH, classifyDatatransRequest, datatransBodyRefusal, datatransBrandRefusal, datatransCardBrand, datatransCardOnFileDisclosure, datatransDeviceRefusal, datatransErrorCode, datatransFacts, datatransMerchantId, datatransMerchantRefusal, datatransRefusalMessage, datatransRegistrationRefusal, datatransResponseOutcome, datatransTokenizeRefusal, encodeDatatransFormValue, injectDatatransCard, isDatatransTokenizeRequest, isDatatransTokenizeUrl, parseDatatransForm, sanitizeDatatransTokenResponse, serializeDatatransForm };