@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/cse-body.js

@@ -3,6 +3,7 @@
 import { substituteEncryptedFields } from './substitute.js';
 import { substituteMerchantHostedBody } from './merchant-hosted.js';
 import { fiservCapturePinId, isFiservCaptureHost, substituteFiservEnvelope } from './fiserv.js';
+import { substituteVerifoneBody } from './verifone.js';
 /**
  * The cse continuation: the paused body with the vault's ciphertext in place
  * of the dummy blobs. The adapters send it as postData ALONE. Chromium
@@ -25,8 +26,17 @@ import { fiservCapturePinId, isFiservCaptureHost, substituteFiservEnvelope } fro
  * a Fiserv capture host. Every refusal throws before anything is sent.
  */
 export function cseBody(body, replay, url, preparation) {
+    // A Verifone approval is always a prepared one for the profile it pays, and continues only the
+    // leg that profile reviewed, with the device's blob written into the LIVE paused body, which
+    // must still be the body the API checked at create (verifone.ts).
+    if (preparation?.psp === 'verifone' || replay.kind === 'verifone') {
+        if (replay.kind !== 'verifone' || preparation?.psp !== 'verifone' || preparation.merchantProfile !== replay.profile) {
+            throw new Error('Refusing to substitute: the paused request is not the Verifone card request the cardholder approved.');
+        }
+        return substituteVerifoneBody({ url, method: 'POST', body }, replay);
+    }
     if (preparation?.psp === 'fiserv') {
-        if (replay.kind === 'merchant_hosted' || !isFiservCaptureHost(url) || fiservCapturePinId(url, body) !== preparation.merchantProfile) {
+        if (replay.kind !== undefined || !isFiservCaptureHost(url) || fiservCapturePinId(url, body) !== preparation.merchantProfile) {
             throw new Error('Refusing to substitute: the paused request is not a Fiserv capture under the key pin the cardholder approved.');
         }
         return substituteFiservEnvelope(body, replay.substitutions);

package/dist/cybersource-flex.d.ts

@@ -0,0 +1,183 @@
+/** The processor id, as the registry and the API name it. */
+export declare 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 declare const CYBERSOURCE_FLEX_CAPABILITY = "capture_context";
+/** The Microform v2 card fields the cardholder's device can rebuild. */
+export type MicroformField = 'number' | 'securityCode';
+/**
+ * The Microform fields of one payment, as the create carries them: the field iframe's version,
+ * the fields that loaded (the number field always, the security code field when the merchant
+ * created it), and the field whose iframe sent this request. The device rebuilds the iframe's
+ * exact plaintext from them, and the triggering field's data comes first in it.
+ */
+export interface MicroformSidecar {
+    version: string;
+    fields: MicroformField[];
+    trigger: MicroformField;
+}
+/** request.capture_context and request.microform on the create. */
+export interface CybersourceFlexSidecar {
+    /** The capture context, byte for byte as the field iframe's URL fragment carries it. */
+    capture_context: string;
+    microform: MicroformSidecar;
+}
+/** A Flex card request the claim flow may take over. */
+export interface CybersourceFlexPause {
+    sidecar: CybersourceFlexSidecar;
+    /**
+     * The request's shape for the retry rule (cdp.ts sameCheckoutRequest): microform type, fields,
+     * the context's key id and the verified capture context itself. Every createToken seals a fresh
+     * JWE, so the body itself never repeats; a retry under the same context and fields carries this
+     * same shape, and a field reloaded under any other context never reuses the approval, even one
+     * whose key id is the same.
+     */
+    shape: string;
+}
+/**
+ * Why a Flex card request is not one this build can pay; reported on the unsupported_checkout
+ * event. Each is a fact about the page that its next request repeats: a request that is not a
+ * Microform card field's (including one from a frame this attachment read and found to be no
+ * Microform field), an unreviewed field version, or fields the device cannot rebuild.
+ */
+export type MicroformUnsupportedReason = 'microform_request_unrecognized' | 'microform_version_unreviewed' | 'microform_fields_unsupported';
+/**
+ * Why this one request is refused while the next may pass; reported on the blocked event.
+ * `microform_frame_unread`: the frame that sent it could not be read (a missed event, a frame
+ * tree read that failed or timed out), which the page's next request may not repeat.
+ */
+export type CybersourceFlexRefusal = 'capture_context_invalid' | 'capture_context_mismatch' | 'request_body_unreadable' | 'microform_frame_unread';
+export type CybersourceFlexDecision = {
+    kind: 'pause';
+    flex: CybersourceFlexPause;
+} | {
+    kind: 'continue';
+} | {
+    kind: 'unsupported';
+    reason: MicroformUnsupportedReason;
+} | {
+    kind: 'refuse';
+    reason: CybersourceFlexRefusal;
+    cause?: string;
+};
+/** The paused request, as the pre-claim gates see it. */
+export interface FlexRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+}
+/** An https URL on flex.cybersource.com or testflex.cybersource.com, with no port or credentials. */
+export declare function isCybersourceFlexHost(url: string): boolean;
+/**
+ * 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 declare function refusedRequestFailure(url: string): 'failed' | 'aborted';
+/** A Microform field iframe's URL, read: payment-core's parseMicroformFragment. */
+type MicroformFrame = {
+    environment: string;
+    version: string;
+    reviewed: boolean;
+    microformType: string;
+    microformId: string | null;
+    fieldType: string;
+    captureContext: string;
+};
+type VerifiedContext = {
+    url: string;
+    environment: string;
+    exp: number;
+    jwk: {
+        kid: string;
+    };
+};
+type Verification = {
+    ok: true;
+    context: VerifiedContext;
+} | {
+    ok: false;
+    cause: string;
+};
+/**
+ * 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 declare class CaptureContexts {
+    private readonly entries;
+    verify(jwt: string): Verification | Promise<Verification>;
+    /** Start the check of a card field iframe's capture context from the frame's URL, when it is one. */
+    warm(url: string | undefined): void;
+}
+/**
+ * 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 declare function judgeMicroformRequest(request: FlexRequest, issuing: MicroformFrame | null | undefined, frames: Iterable<MicroformFrame>, contexts: CaptureContexts): CybersourceFlexDecision | Promise<CybersourceFlexDecision>;
+/**
+ * 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 declare class MicroformFrames {
+    private readonly frames;
+    readonly contexts: CaptureContexts;
+    /** Start the capture context's check from a navigation that has not committed; records nothing. */
+    warm(url: string | undefined): void;
+    /** A frame's committed document URL, fragment included. A URL that is not a field iframe's forgets the frame. */
+    observe(frameId: unknown, url: unknown): void;
+    forget(frameId: unknown): void;
+    /**
+     * 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: FlexRequest, frameId: string | undefined, reread?: () => Promise<string | undefined>): CybersourceFlexDecision | Promise<CybersourceFlexDecision>;
+}
+/**
+ * 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 declare function judgeMicroformFrameUrls(request: FlexRequest, issuingUrl: string | undefined, frameUrls: Iterable<string | undefined>, contexts: CaptureContexts): CybersourceFlexDecision | Promise<CybersourceFlexDecision>;
+/**
+ * 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 declare function validCybersourceFlexSidecar(captureContext: unknown, microform: unknown): boolean;
+export {};

package/dist/cybersource-flex.generated.d.ts

@@ -0,0 +1,92 @@
+declare var CYBERSOURCE_FLEX_RULES_SOURCE: Readonly<{
+    version: "2.12.1";
+    sha256: "8429ebae83e9745cd53ad8ff0d9ba69bee0087c1435ed0695a25444bed418327";
+}>;
+declare var CybersourceFlexError: {
+    new (reason: any, message: any): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare function isVerifiedCaptureContext(value: any): boolean;
+declare function flexHostEnvironment(hostname: any): "production" | "sandbox" | null;
+declare var CYBERSOURCE_FLEX_PSP: string;
+declare var CYBERSOURCE_FLEX_CONTENT_TYPE: string;
+declare var CYBERSOURCE_FLEX_TOKENS_URLS: Readonly<{
+    production: `https://flex.cybersource.com${string}`;
+    sandbox: `https://testflex.cybersource.com${string}`;
+}>;
+declare var CYBERSOURCE_FLEX_CAPTURE_CONTEXT_MAX_LENGTH: number;
+declare var CYBERSOURCE_FLEX_REVIEWED_IFRAME_VERSIONS: readonly string[];
+declare var CYBERSOURCE_FLEX_SIGNING_KEYS: any;
+declare var CYBERSOURCE_FLEX_TEST_PANS: Readonly<Set<string>>;
+declare function verifyCaptureContext(jwt: any, { crypto, now }?: {}): Promise<Readonly<{
+    raw: any;
+    signingKid: any;
+    environment: any;
+    origin: string;
+    path: string;
+    url: string;
+    jwk: Readonly<{
+        kty: "RSA";
+        n: any;
+        e: any;
+        kid: any;
+    }>;
+    modulusBytes: number;
+    index: any;
+    contextType: any;
+    allowedCardNetworks: readonly any[] | null;
+    targetOrigins: readonly any[];
+    iat: any;
+    exp: any;
+}>>;
+declare function cybersourceFlexEnvironment(url: any): "production" | "sandbox" | undefined;
+declare function parseMicroformFragment(rawUrl: any): Readonly<{
+    environment: "production" | "sandbox";
+    version: string;
+    reviewed: boolean;
+    microformType: any;
+    microformId: any;
+    fieldType: any;
+    keyId: string | null;
+    captureContext: any;
+}> | null;
+declare function detectCardTypes(pan: any, allowedCardNetworks: any): {
+    codes: any[];
+    valid: boolean;
+    cards: {
+        code: any;
+        name: any;
+        valid: any;
+    }[];
+    securityCode: {
+        required: boolean;
+        length: any;
+    };
+};
+declare function cybersourceFlexTemplateKid(body: any): any;
+declare function isCybersourceFlexTemplateBody(body: any): boolean;
+declare function isCybersourceFlexMediaType(value: any): boolean;
+declare function isCybersourceFlexRequest(url: any, method: any, body: any, headers: any): boolean;
+declare function assertCybersourceFlexTemplate(body: any, verified: any): void;
+declare function buildCardPlaintext(verified: any, card: any, { fields, trigger, now }?: {
+    trigger?: string | undefined;
+}): string;
+declare function sealForContext(verified: any, plaintext: any, { crypto }?: {}): Promise<string>;
+declare var CYBERSOURCE_FLEX_REFUSAL_REASONS: readonly string[];
+declare function cybersourceFlexRefusalCode(text: any): string | null;
+declare function isCybersourceFlexTokenShape(text: any): boolean;
+declare function transientTokenSigned(status: any, body: any, verified: any, { crypto }?: {}): Promise<{
+    confirmed: boolean;
+    reason: any;
+}>;
+declare function transientTokenFacts(status: any, body: any, verified: any, card: any, { crypto }?: {}): Promise<{
+    confirmed: boolean;
+    reason: any;
+}>;
+declare function cybersourceFlexPreparationUrl(environment: any): any;
+declare function isPreparedCybersourceFlexRequest(url: any, method: any, body: any, environment: any, headers: any): boolean;
+export { CYBERSOURCE_FLEX_CAPTURE_CONTEXT_MAX_LENGTH, CYBERSOURCE_FLEX_CONTENT_TYPE, CYBERSOURCE_FLEX_PSP, CYBERSOURCE_FLEX_REFUSAL_REASONS, CYBERSOURCE_FLEX_REVIEWED_IFRAME_VERSIONS, CYBERSOURCE_FLEX_RULES_SOURCE, CYBERSOURCE_FLEX_SIGNING_KEYS, CYBERSOURCE_FLEX_TEST_PANS, CYBERSOURCE_FLEX_TOKENS_URLS, CybersourceFlexError, assertCybersourceFlexTemplate, buildCardPlaintext, cybersourceFlexEnvironment, flexHostEnvironment as cybersourceFlexHostEnvironment, cybersourceFlexPreparationUrl, cybersourceFlexRefusalCode, cybersourceFlexTemplateKid, detectCardTypes, isCybersourceFlexMediaType, isCybersourceFlexRequest, isCybersourceFlexTemplateBody, isCybersourceFlexTokenShape, isPreparedCybersourceFlexRequest, isVerifiedCaptureContext, parseMicroformFragment, sealForContext, transientTokenFacts, transientTokenSigned, verifyCaptureContext };