@agent-cards/checkout 0.18.0 → 0.19.0

package/dist/cse-body.d.ts

@@ -0,0 +1,25 @@
+import type { PreparedCheckout, ReplayResponse } from './client.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
+ * recomputes Content-Length for a continued request itself and refuses a
+ * header override that names it (Fetch.continueRequest answers -32602 "Unsafe
+ * header"), and that refusal would land after the cardholder approved, failing
+ * a paid-for request. Leaving `headers` off the command keeps every other
+ * header the browser's own, untouched, which is the point of continuing rather
+ * than fulfilling.
+ *
+ * The approval picks the substitution, not the URL alone. A Fiserv approval is
+ * always a prepared one (authorize() requires it), so its preparation names
+ * the processor and the key pin the cardholder approved. It continues only a
+ * request on Fiserv's capture hosts, and only when that capture's own pin (its
+ * envelope's key, pinned for its endpoint and its merchant) is the approved
+ * pin; then Fiserv's own substitution writes only the envelope's four members
+ * at source.encryptionData of the live paused body, and throws for a body that
+ * is not the capture Agentcard covers or an envelope under another key than
+ * the one the paused capture names (fiserv.ts). Any other approval never meets
+ * a Fiserv capture host. Every refusal throws before anything is sent.
+ */
+export declare function cseBody(body: string, replay: Extract<ReplayResponse, {
+    mode: 'cse';
+}>, url: string, preparation: PreparedCheckout | undefined): string;

package/dist/cse-body.js

@@ -0,0 +1,41 @@
+// The body a cse approval continues, shared by both adapters (cdp.ts). Kept in its
+// own module, outside the package's published entries, so its tests can reach it.
+import { substituteEncryptedFields } from './substitute.js';
+import { substituteMerchantHostedBody } from './merchant-hosted.js';
+import { fiservCapturePinId, isFiservCaptureHost, substituteFiservEnvelope } from './fiserv.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
+ * recomputes Content-Length for a continued request itself and refuses a
+ * header override that names it (Fetch.continueRequest answers -32602 "Unsafe
+ * header"), and that refusal would land after the cardholder approved, failing
+ * a paid-for request. Leaving `headers` off the command keeps every other
+ * header the browser's own, untouched, which is the point of continuing rather
+ * than fulfilling.
+ *
+ * The approval picks the substitution, not the URL alone. A Fiserv approval is
+ * always a prepared one (authorize() requires it), so its preparation names
+ * the processor and the key pin the cardholder approved. It continues only a
+ * request on Fiserv's capture hosts, and only when that capture's own pin (its
+ * envelope's key, pinned for its endpoint and its merchant) is the approved
+ * pin; then Fiserv's own substitution writes only the envelope's four members
+ * at source.encryptionData of the live paused body, and throws for a body that
+ * is not the capture Agentcard covers or an envelope under another key than
+ * the one the paused capture names (fiserv.ts). Any other approval never meets
+ * a Fiserv capture host. Every refusal throws before anything is sent.
+ */
+export function cseBody(body, replay, url, preparation) {
+    if (preparation?.psp === 'fiserv') {
+        if (replay.kind === 'merchant_hosted' || !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);
+    }
+    if (isFiservCaptureHost(url))
+        throw new Error('Refusing to substitute: a Fiserv capture continues only through a prepared Fiserv approval.');
+    // A merchant-hosted approval is written into the LIVE paused body, which must
+    // still be the body the API checked at create (merchant-hosted.ts).
+    if (replay.kind === 'merchant_hosted')
+        return substituteMerchantHostedBody(body, replay);
+    return substituteEncryptedFields(body, replay.substitutions);
+}

package/dist/fiserv.d.ts

@@ -0,0 +1,65 @@
+import type { Substitutions } from './substitute.js';
+export type FiservEnvironment = 'production' | 'sandbox';
+/** A Fiserv public key Agentcard reviewed: its id, the merchant a cardholder is shown, and the environment it pays in. */
+export interface FiservKeyPin {
+    readonly id: string;
+    readonly merchant: string;
+    readonly environment: FiservEnvironment;
+}
+/** The card-capture endpoint per environment, exactly as the Secure Data Capture frame writes it. */
+export declare const FISERV_CARD_CAPTURE_ENDPOINTS: Readonly<Record<FiservEnvironment, string>>;
+/**
+ * Whether `url` is on one of the two card-capture hosts (connect.fiservapis.com and
+ * connect-cert.fiservapis.com), whatever its path or query. The registry's Fiserv
+ * recognizer lists exactly these hosts, so a card request on one of them is Fiserv's.
+ */
+export declare function isFiservCaptureHost(url: string): boolean;
+/** The pinned key with this id, in either environment, or null. */
+export declare function fiservKeyPinById(id: unknown): FiservKeyPin | null;
+/**
+ * The id of the pin a paused capture's card may be sealed under (its envelope's key,
+ * pinned for its endpoint's environment and for the merchant its body names), or null.
+ */
+export declare function fiservCapturePinId(url: string, body: string | null): string | null;
+/** The card-capture endpoint a Fiserv preparation names for its environment. */
+export declare function fiservPreparationUrl(environment: FiservEnvironment): string;
+/**
+ * Whether the SDK pauses this capture body for the cardholder, or refuses it when no
+ * preparation is ready: every body except the captures that carry no Vault card.
+ * Fastlane (PaymentToken), ACH (PaymentCheck), gift and EBT captures share the endpoint
+ * and continue untouched, each only in its exact source shape. A body not proven
+ * card-free (one the adapter could not read, one over 64 KiB, one that is not JSON, a
+ * PaymentCard with a plaintext card, a non-card type or category that also carries a card
+ * member) is judged as a card capture, so the agent's placeholder never continues to
+ * Fiserv on it.
+ */
+export declare function isFiservPausableBody(body: string | null): boolean;
+/**
+ * Whether this build pays the request only through a prepared checkout because it is
+ * Fiserv's: a recognizer named fiserv, or a request on one of Fiserv's capture hosts.
+ * The served entry says so too (preparationRequired); this build carries Fiserv's own
+ * rules, so it requires the preparation whatever the served registry says, and a
+ * registry that dropped the flag never opens an ordinary Fiserv authorization.
+ */
+export declare function requiresFiservPreparation(psp: string, url: string): boolean;
+/**
+ * Whether a paused request is the capture a Fiserv preparation for `environment`
+ * consents to: that environment's endpoint exactly, the capture rules on the whole
+ * request, headers included, and an envelope under a key pinned for that environment
+ * and for the merchant the body names.
+ */
+export declare function isPreparedFiservRequest(url: string, method: string, body: string | null, environment: FiservEnvironment, headers?: Record<string, string>): boolean;
+/**
+ * Whether an approval's substitution is exactly Fiserv's envelope: `encoding` json,
+ * `at` source.encryptionData, the four members keyId, encryptedKey, encryptionBlock and
+ * aesIv in their exact shape under a pinned key, and nothing removed.
+ */
+export declare function isFiservSubstitution(sub: unknown): boolean;
+/**
+ * The paused Fiserv capture with the approval's envelope written over the four members
+ * its source.encryptionData already carries, and every other byte the frame's own. It
+ * throws, writing nothing, for a body that is not the capture Agentcard covers, for any
+ * substitution but Fiserv's envelope, and for an envelope under another key than the one
+ * the paused capture names. Run this on a Fiserv approval, never substituteEncryptedFields.
+ */
+export declare function substituteFiservEnvelope(body: string, sub: Substitutions): string;

package/dist/fiserv.generated.d.ts

@@ -0,0 +1,73 @@
+declare var FISERV_CARD_CAPTURE_ENDPOINTS: Readonly<{
+    production: "https://connect.fiservapis.com/ch/payments-vas/v1/card-capture";
+    sandbox: "https://connect-cert.fiservapis.com/ch/payments-vas/v1/card-capture";
+}>;
+declare function fiservEnvironment(url: any): "production" | "sandbox" | undefined;
+declare function isFiservCardCaptureUrl(url: any): boolean;
+declare var FISERV_SIMULATOR_PANS: readonly string[];
+declare var FISERV_ENVELOPE_CONSTANTS: Readonly<{
+    aesTagLength: 128;
+    encryptionType: "AES-GCM";
+    encryptionTarget: "MANUAL";
+}>;
+declare function fiservTimestampMs(text2: any): number;
+declare var FISERV_KEY_PINS: any;
+declare function fiservKeyPin(keyId: any, environment: any): any;
+declare function isFiservPinnedKeyId(keyId: any): any;
+declare function fiservKeyRefusal(keyId: any, environment: any, nowMs: any): "fiserv_key_unpinned" | "fiserv_key_inactive" | "fiserv_key_outside_validity" | null;
+declare function parseFiservPublishedKey(text2: any): {
+    keyId: any;
+    encryptionType: any;
+    modulus: any;
+    encodedPublicKey: any;
+    validFrom: any;
+    validTo: any;
+    status: any;
+    symmetric: {
+        encryptionType: any;
+        modulus: any;
+    };
+} | null;
+declare function fiservPublishedKeyRefusal(text2: any, keyId: any, environment: any, nowMs: any): "fiserv_key_unpinned" | "fiserv_key_inactive" | "fiserv_key_outside_validity" | "fiserv_published_key_unreadable" | "fiserv_published_key_rotated" | "fiserv_published_key_mismatch" | null;
+declare function sanitizeFiservCaptureResponse(text2: any): string;
+declare function fiservCaptureCardMismatch(text2: any, card: any): boolean;
+declare function fiservErrorIdentifiers(text2: any): {
+    code: any;
+    type: any;
+};
+declare function fiservCardCaptureRefusal(request: any): "fiserv_request_invalid" | "fiserv_endpoint_invalid" | "fiserv_body_invalid" | "fiserv_body_member_not_allowed" | "fiserv_source_not_encrypted_card" | "fiserv_envelope_invalid" | "fiserv_merchant_invalid" | "fiserv_transaction_details_invalid" | "fiserv_billing_address_invalid" | "fiserv_method_invalid" | "fiserv_headers_invalid" | "fiserv_header_not_allowed" | "fiserv_content_type_invalid" | "fiserv_auth_token_type_invalid" | "fiserv_merchant_header_mismatch" | "fiserv_terminal_header_mismatch" | "fiserv_header_value_invalid" | null;
+declare function isFiservCardCaptureRequest(request: any): boolean;
+declare function isFiservPausableBody(body: any): boolean;
+declare function fiservTemplateKeyId(body: any): any;
+declare function fiservCaptureMerchant(body: any): {
+    merchantId: any;
+    terminalId: any;
+} | null;
+declare function fiservCapturePin(capture: any): any;
+declare function fiservCaptureKeyRefusal(capture: any, nowMs: any): string | null;
+declare function fiservPreparationUrl(environment: any): any;
+declare function isPreparedFiservRequest(url: any, method: any, body: any, environment: any, headers: any): boolean;
+declare function encryptFiservCard(card: any, capture: any, facilities: any): Promise<{
+    keyId: string;
+    encryptedKey: string;
+    encryptionBlock: string;
+    aesIv: string;
+    aesTagLength: 128;
+    encryptionType: "AES-GCM";
+    encryptionTarget: "MANUAL";
+}>;
+declare var FISERV_SUBSTITUTION: Readonly<{
+    at: "source.encryptionData";
+    fields: readonly string[];
+}>;
+declare function fiservSubstitutionFieldsRefusal(fields: any): "fiserv_key_unpinned" | "fiserv_substitution_invalid" | "fiserv_substitution_fields_invalid" | null;
+declare function fiservApprovedEnvelopeRefusal(fields: any, context: any): string | null;
+declare function fiservSubstitutions(envelope: any): {
+    encoding: string;
+    at: "source.encryptionData";
+    fields: {
+        [k: string]: any;
+    };
+};
+declare function substituteFiservEnvelope(body: any, sub: any): string;
+export { FISERV_CARD_CAPTURE_ENDPOINTS, FISERV_ENVELOPE_CONSTANTS, FISERV_KEY_PINS, FISERV_SIMULATOR_PANS, FISERV_SUBSTITUTION, encryptFiservCard, fiservApprovedEnvelopeRefusal, fiservCaptureCardMismatch, fiservCaptureKeyRefusal, fiservCaptureMerchant, fiservCapturePin, fiservCardCaptureRefusal, fiservEnvironment, fiservErrorIdentifiers, fiservKeyPin, fiservKeyRefusal, fiservPreparationUrl, fiservPublishedKeyRefusal, fiservSubstitutionFieldsRefusal, fiservSubstitutions, fiservTemplateKeyId, fiservTimestampMs, isFiservCardCaptureRequest, isFiservCardCaptureUrl, isFiservPausableBody, isFiservPinnedKeyId, isPreparedFiservRequest, parseFiservPublishedKey, sanitizeFiservCaptureResponse, substituteFiservEnvelope };