@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/eprotect.js

@@ -0,0 +1,222 @@
+// Worldpay eProtect (Vantiv / Litle PayPage): the adapters' side of its card registration.
+//
+// The vendor's browser script (eProtect-api2/3, litle-api2/3, and the Worldpay iframe, which runs
+// them in a Worldpay-origin frame) encrypts the card in the page and sends it as ONE JSONP
+// <script> GET to /eProtect/paypage; the answer is `<callback>({...})`. The rules that judge that
+// request (the query grammar, the pinned keys, the failover and give-up reports, the answer
+// allowlist) live in payment-core and reach this SDK as eprotect.generated.ts. This module holds
+// only what an attachment decides from them:
+//   - which request on eProtect's hosts is the registration to pause for the vault;
+//   - which is the vendor's failover re-send of a registration the page already sent (aborted
+//     quietly: it carries the placeholder's ciphertext and is never a destination);
+//   - which is the vendor's own report that it gave up (/eProtect/ppstats 900 or 901), which ends
+//     the approval running for that registration;
+//   - the script answer the paused registration gets once the cardholder's device registered the
+//     real card: the registration Agentcard stored, wrapped in the callback the paused URL named.
+import { EPROTECT_HOSTS, EPROTECT_PATH, EPROTECT_SECONDARY_HOST, eprotectGiveUp, eprotectJsonp, eprotectMerchantPin, eprotectOutcome, eprotectRequestFacts, eprotectSecondaryAttempt, isEprotectRequest, } from './eprotect.generated.js';
+/** The processor id, as the registry and the API name it. */
+export const EPROTECT_PSP = 'worldpay_eprotect';
+/** The dark-launch capability the API serves the eProtect recognizer behind (payment-core definitions.js). */
+export const EPROTECT_CAPABILITY = 'worldpay_eprotect_jsonp';
+/** What Worldpay answers a registration with on both of its card hosts, and what the paused script gets. */
+export const EPROTECT_SCRIPT_CONTENT_TYPE = 'application/x-javascript;charset=UTF-8';
+const EPROTECT_HOSTNAMES = [EPROTECT_HOSTS.production, EPROTECT_HOSTS.sandbox, EPROTECT_SECONDARY_HOST];
+/**
+ * Why a Worldpay eProtect checkout may not be prepared under `merchant`, or null when it may. On the
+ * production host the API admits only a paypageId payment-core pins for the merchant origin, under
+ * that pin's merchant name, the one the approval shows, and refuses another name
+ * (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.
+ */
+export function eprotectCheckoutRefusal(input, pins) {
+    if (input.environment !== 'production')
+        return null;
+    const pin = eprotectMerchantPin(input.paypageId, input.merchantOrigin, pins);
+    return pin && pin.merchant !== input.merchant ? 'merchant_profile_mismatch' : null;
+}
+/** Which eProtect request this is, or null for a URL that is not on one of Worldpay eProtect's hosts. */
+export function classifyEprotectRequest(url, method) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'https:' || parsed.port || parsed.username || parsed.password
+        || !EPROTECT_HOSTNAMES.includes(parsed.hostname))
+        return null;
+    const get = typeof method === 'string' && method.toUpperCase() === 'GET';
+    // Every spelling of the registration path belongs to the registration family: the exact path
+    // carries the card, and any neighbour of it is nothing this SDK completes.
+    if (parsed.pathname.toLowerCase().startsWith(EPROTECT_PATH.toLowerCase())) {
+        const facts = get ? eprotectRequestFacts(url) : null;
+        if (facts)
+            return { kind: 'registration', paypageId: facts.paypageId, id: facts.id };
+        const repeat = get ? eprotectSecondaryAttempt(url) : null;
+        if (repeat)
+            return { kind: 'failover', paypageId: repeat.paypageId, id: repeat.id };
+        return { kind: 'unsupported' };
+    }
+    const report = get ? eprotectGiveUp(url) : null;
+    if (report)
+        return { kind: 'give_up', code: report.code, paypageId: report.paypageId, id: report.txnId };
+    return { kind: 'sibling' };
+}
+/** The registration GET exactly as payment-core admits it: its URL alone, with no body. */
+export function isEprotectRegistration(request) {
+    return (request.method ?? 'POST').toUpperCase() === 'GET'
+        && isEprotectRequest({ url: request.url, method: 'GET', body: request.body ?? '' });
+}
+/**
+ * The answer a paused registration script gets, or null when the stored answer is not one to hand
+ * the page: Worldpay's own shape, `<callback>(<registration>)` under its script type, with the
+ * callback the paused URL named. The registration must be one payment-core's judge accepts for that
+ * exact URL (response 870, the page's own id, only allowlisted fields), byte for byte what the API
+ * stored after running the same judge.
+ */
+export function eprotectScriptAnswer(templateUrl, response) {
+    const facts = eprotectRequestFacts(templateUrl);
+    if (!facts || response.status !== 200 || typeof response.body !== 'string')
+        return null;
+    let body;
+    try {
+        body = eprotectJsonp(facts.callback, response.body);
+    }
+    catch {
+        return null;
+    }
+    const verdict = eprotectOutcome(200, body, templateUrl, undefined);
+    if (verdict.outcome !== 'registered' || verdict.sanitizedJson !== response.body)
+        return null;
+    return { status: 200, headers: { 'content-type': EPROTECT_SCRIPT_CONTENT_TYPE }, body };
+}
+const attemptKey = (attempt) => JSON.stringify([attempt.paypageId, attempt.id]);
+/**
+ * How long a paused registration's re-send is still recognized as a known repeat. The vendor
+ * scripts re-send 5 seconds after an unanswered primary and give up at the merchant's own timeout
+ * (10 to 15 seconds at the merchants this SDK covers), so a minute leaves room for a timer a busy
+ * page delays. A re-send that comes later still is aborted all the same, as unsupported (pre-claim).
+ */
+export const EPROTECT_REPEAT_WINDOW_MS = 60_000;
+/** At most this many paused registrations are remembered at once; the oldest is forgotten first. */
+export const EPROTECT_REPEAT_LIMIT = 64;
+/**
+ * One attachment's eProtect state. A failover re-send or a give-up report names a registration by
+ * paypageId and id; each is matched against what this attachment itself paused and answered, never
+ * taken on the page's word. Inert (classify returns null) until the registry serves eProtect, which
+ * a client reaches only by syncing with the capability for an org the API enabled, so a build, an
+ * org or an API that never served it leaves every eProtect request exactly as before.
+ */
+export class EprotectGate {
+    vault;
+    now;
+    /** Paused registrations, oldest first, each with the time its re-send window closes. */
+    seen = new Map();
+    running = null;
+    answered = null;
+    constructor(vault, now = Date.now) {
+        this.vault = vault;
+        this.now = now;
+    }
+    /** What this request is, when the registry serves eProtect and the URL is on its hosts; null leaves it to the other gates. */
+    classify(url, method) {
+        if (typeof this.vault?.recognizesProcessor !== 'function' || !this.vault.recognizesProcessor(EPROTECT_PSP))
+            return null;
+        return classifyEprotectRequest(url, method);
+    }
+    /** Playwright's route predicate sees only the URL: route the registration family and the give-up reports, never the scripts. */
+    matches(url) {
+        const request = this.classify(url, 'GET');
+        return request !== null && request.kind !== 'sibling';
+    }
+    /**
+     * The page sent this registration and this attachment paused it: its re-send is then a known
+     * repeat for EPROTECT_REPEAT_WINDOW_MS. Seeing it again restarts that window. A long-lived
+     * attachment keeps at most EPROTECT_REPEAT_LIMIT of them, so repeated attempts never grow it.
+     */
+    saw(attempt) {
+        const now = this.now();
+        this.forgetBefore(now);
+        const key = attemptKey(attempt);
+        this.seen.delete(key);
+        this.seen.set(key, now + EPROTECT_REPEAT_WINDOW_MS);
+        for (const oldest of this.seen.keys()) {
+            if (this.seen.size <= EPROTECT_REPEAT_LIMIT)
+                break;
+            this.seen.delete(oldest);
+        }
+    }
+    /** Drops every registration whose re-send window closed: the map is in window order. */
+    forgetBefore(now) {
+        for (const [key, until] of this.seen) {
+            if (until > now)
+                break;
+            this.seen.delete(key);
+        }
+    }
+    /**
+     * A re-send of a registration this attachment paused, whether its approval is running, answered,
+     * or never started. The vendor script re-sends 5 seconds after an unanswered primary and has no
+     * error path, so a primary the adapters refused before any approval (no ready preparation, another
+     * paypageId, an approval already outstanding) or answered just as that timer fired is re-sent
+     * too. Such a re-send is aborted quietly, like one during the approval, and never replaces that
+     * refusal's own state with `unsupported`. A re-send of a registration this attachment never paused
+     * means the primary went somewhere it does not cover, and pre-claim aborts that one as unsupported.
+     * Both carry the placeholder's ciphertext, and both are aborted. A registration is remembered
+     * only for its re-send window (saw).
+     */
+    repeats(attempt) {
+        this.forgetBefore(this.now());
+        return this.seen.has(attemptKey(attempt));
+    }
+    /**
+     * An approval is running for this paused request, when it is a registration; `stop` ends it as the
+     * page abandoning its request. A new attempt also retires the last answered registration: a
+     * give-up report for it now belongs to a checkout the lifecycle has moved past, and must not end
+     * the attempt that just began (see gaveUp).
+     */
+    begin(url, method, stop) {
+        const request = classifyEprotectRequest(url, method);
+        this.running = request?.kind === 'registration' ? { key: attemptKey(request), stop } : null;
+        this.answered = null;
+    }
+    /**
+     * The approval's answer reached this registration; `lost` reports that the page had already given
+     * up on it. Kept after the attempt ends, since the vendor's report can land just after the answer,
+     * and only until the next attempt begins.
+     */
+    delivered(url, lost) {
+        const request = classifyEprotectRequest(url, 'GET');
+        if (request?.kind === 'registration')
+            this.answered = { key: attemptKey(request), lost };
+    }
+    /** The approval for the paused request ended, answered or not. */
+    end() { this.running = null; }
+    /**
+     * The vendor's give-up report: end the approval still running for that registration (the
+     * adapter cancels the authorization, which the API confirms only before the device registered
+     * the card, and aborts the paused script instead of answering it), or report that the answer
+     * already handed to it came too late. Returns which one, or null when the report names neither,
+     * including a registration answered before the current attempt began.
+     */
+    gaveUp(attempt) {
+        const key = attemptKey(attempt);
+        if (this.running?.key === key) {
+            const { stop } = this.running;
+            this.running = null;
+            stop();
+            return 'running';
+        }
+        if (this.answered?.key === key) {
+            const { lost } = this.answered;
+            this.answered = null;
+            lost();
+            return 'answered';
+        }
+        return null;
+    }
+}

package/dist/gmo.d.ts

@@ -0,0 +1,63 @@
+import { GMO_PSP, isGmoTokenHost } from './gmo.generated.js';
+export { GMO_PSP, isGmoTokenHost };
+/** The dark-launch capability a build declares when it pauses only what isGmoSharedPkRequest accepts. */
+export declare const GMO_CAPABILITY = "gmo_shared_pk";
+/**
+ * Why a GMO request was aborted as an unsupported checkout, reported as the `reason` of the
+ * `unsupported_checkout` event and of the attachment's `unsupported` state:
+ *   unsupported_gmo_request   a request to GMO's CreateToken.json that is not mp-token.js's SHARED_PK
+ *                             getToken for one token
+ *   unsupported_gmo_token_v1  GMO token v1's JSONP GET to /ext/api/getToken
+ */
+export type GmoUnsupportedReason = 'unsupported_gmo_request' | 'unsupported_gmo_token_v1';
+/**
+ * Fetch interception patterns for GMO token v1's JSONP GET, armed only for an org the API served GMO
+ * to. A CDP pattern matches the URL as written, path case included, while isGmoTokenV1Request
+ * accepts any path case, a trailing dot on the host and any port. So each v1 host is armed whole,
+ * in those four spellings, and the pre-claim gate classifies every paused request with
+ * isGmoTokenV1Request: the v1 GET is aborted, and anything else on the host continues untouched.
+ * Chrome writes the host in lower case, and it blocks a subresource URL that carries credentials.
+ */
+export declare const GMO_TOKEN_V1_PATTERNS: readonly string[];
+/**
+ * Whether the vault's current registry recognizes GMO's card request: true only after
+ * syncRegistry() for an org the API serves the dark entry to.
+ */
+export declare function recognizesGmo(vault: {
+    isCardRequest?: (url: string, method?: string) => boolean;
+} | null | undefined): boolean;
+/**
+ * GMO token v1's card request: a GET (or, with no method, a URL a route matcher is asked about)
+ * to /ext/api/getToken on either v1 host, in any case or with a trailing dot, since the servers
+ * behind it need not care.
+ */
+export declare function isGmoTokenV1Request(rawUrl: string, method?: string): boolean;
+/**
+ * Whether a POST the registry recognized on a GMO token host is anything but mp-token.js's
+ * SHARED_PK getToken for one token: null when the guard accepts it (it pauses for approval), else
+ * the reason it is aborted. A guard that throws refuses.
+ */
+export declare function gmoRequestRefusal(request: {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body: string | null;
+}): GmoUnsupportedReason | null;
+/**
+ * The shop a GMO token request names (encryptionParameters.apiKey), as part of that request's
+ * identity. GMO mints a token for that one shop, so a retry that names another shop is a new
+ * question and never takes the first request's approval. Undefined when the URL is not a GMO token
+ * host; null when the body names no shop that can be read.
+ */
+export declare function gmoRequestShop(url: string, body: string): string | null | undefined;
+/**
+ * The only answer the page may receive for an approved GMO request: status 200, and GMO's body
+ * reduced to the five fields mp-token.js reads with exactly one 64-hex token
+ * (sanitizeGmoTokenResponse), under a JSON content type. Null for anything else, including
+ * several tokens, which one approval never pays for.
+ */
+export declare function gmoTokenAnswer(status: number, body: string): {
+    status: 200;
+    headers: Record<string, string>;
+    body: string;
+} | null;

package/dist/gmo.generated.d.ts

@@ -0,0 +1,60 @@
+declare var GMO_PSP: string;
+declare var GMO_CLIENT_TYPE: string;
+declare var GMO_CONTENT_TYPE: string;
+declare var GMO_TOKEN_PATH: string;
+declare var GMO_TOKEN_HOSTS: Readonly<{
+    production: "token.mul-pay.jp";
+    sandbox: "stg.token.mul-pay.jp";
+}>;
+declare var GMO_TOKEN_URLS: Readonly<{
+    production: `https://token.mul-pay.jp${string}`;
+    sandbox: `https://stg.token.mul-pay.jp${string}`;
+}>;
+declare var GMO_SHARED_KEYS: Readonly<{
+    "token.mul-pay.jp": Readonly<{
+        spki: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzJ6Ps4kEHAoUxWoTQM2YzvCnJrCpYo3kUKV6G8Pbl7NU1eAkF+rGKhGQVOqULbOa7bS+67txfK+p+WhYIVpxoCzkL9rFKKSb1qeW+phosmN3sXYo0IUa658adLvvpPzpwAqqTu+WNiANZrlstuCC2/dRBwGVl9i8W1pxJZbz2j2lPD7G/jxnqWgfDw+d/EXUAKazS/G6Dk+WoZkmTqkIzsJij5QX4xqmXbdyfsj6BXfmBS1RLAsngJ8bxtshRY9uQ6faSCuTaEF5l38Qh9HhXBoFB+MsOKQ4biUwgW/WaFc5KZ75VDFadrJtUn+5XOlY+iXIQhgdp/zewoZda0rGnQIDAQAB";
+        sha256: "c12555cbac901b38910f7f5034a97e353767e1ab6d7c8362c13d0b82f618e142";
+    }>;
+    "stg.token.mul-pay.jp": Readonly<{
+        spki: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoRuXDRz86jW+7es/BxzFJAmSxsjt69NvjrRCBsmBZb29luUsayl0Ge0pFDXYasVcv0V53S2AZXsikg+dxl3Ykxv0578LMNrKoMvuSDAOZP44/wIaEhN7375754kdubdvK+fHDdW48Q4t2GLrkzMcWjoYgflSW4ldIA/jvnIAine2fK+3ho2WRbIOLHSSwKmAOPI6CKs5v8yN9fg9MvX8IOi2rmFxu0NnYYv32w5qW5BHVzqD1w1ZKfrQHhhFk1Ngkle66NUoyCpVYCsXCJyLwfeN6M2vOIM/ob/K89XXUuAJzSSOgLBVUlSwOoxH35nr1TaKIu5VXp9irYBfiLmJewIDAQAB";
+        sha256: "0b065ee8e674fd50f01f9906c1e2393032dfe739eebc9d7b36ba7628312a63d8";
+    }>;
+}>;
+declare var GMO_REFUSAL_REASONS: readonly string[];
+declare var GmoError: {
+    new (reason: any, message: any): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare function gmoTokenEnvironment(rawUrl: any): "production" | "sandbox" | null;
+declare function isGmoTokenHost(rawUrl: any): boolean;
+declare function parseGmoSharedPkBody(body: any, environment: any): {
+    createCount: any;
+    apiKey: any;
+} | {
+    apiKey: any;
+    createCount?: undefined;
+} | null;
+declare function isGmoSharedPkRequest(request: any): boolean;
+declare function gmoShopId(request: any): any;
+declare function buildGmoSharedPkBody(templateBody: any, card: any, { crypto, host }?: {}): Promise<string>;
+declare function sanitizeGmoTokenResponse(text: any): string | null;
+declare function gmoTokenMatchesCard(sanitized: any, card: any): boolean;
+declare function gmoRefusalCode(text: any): any;
+declare function gmoResponseFacts(status: any, text: any): {
+    outcome: string;
+    body: string;
+    code?: undefined;
+} | {
+    outcome: string;
+    body?: undefined;
+    code?: undefined;
+} | {
+    outcome: string;
+    code: any;
+    body?: undefined;
+};
+export { GMO_CLIENT_TYPE, GMO_CONTENT_TYPE, GMO_PSP, GMO_REFUSAL_REASONS, GMO_SHARED_KEYS, GMO_TOKEN_HOSTS, GMO_TOKEN_PATH, GMO_TOKEN_URLS, GmoError, buildGmoSharedPkBody, gmoRefusalCode, gmoResponseFacts, gmoShopId, gmoTokenEnvironment, gmoTokenMatchesCard, isGmoSharedPkRequest, isGmoTokenHost, parseGmoSharedPkBody, sanitizeGmoTokenResponse };