@agent-cards/sdk 0.20.0 → 0.21.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/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 };