@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/shiji-sts.js

@@ -0,0 +1,222 @@
+// Shiji Payment Solutions STS, the card leg of the MyCheck Wallet V3 (Shiji Group), as the SDK sees it.
+//
+// La Quinta by Wyndham's booking page loads MyCheck's wallet, whose Shiji proxy (sts.proxy.v2.1.js)
+// encrypts the typed card with RSAES-PKCS1-v1_5 under the RSA-1024 key it hardcodes and sends one
+// fetch from the page:
+//   POST https://iframe.vault.eu.prod.shijipayment.com/v1/token/getTokenId   (UAT: iframe.vault.eu.uat...)
+//   {"accessToken":"<STS token>","pan":"<b64>","expires":"<b64>","keySequence":"<clientKey>"}
+// and, after MyCheck's payment-methods call, the CVV the same way to /v1/token/getCvvId. The agent's
+// page encrypts the placeholder card. The cardholder's device encrypts the real one under the key
+// payment-core pins (never a key from a row, a request or a page), and the runtime swaps those
+// ciphertexts over the page's own, byte for byte, at the body root, so the accessToken, the
+// keySequence and the origin stay the page's (mode cse).
+//
+// The registry entry ships dark (capability shiji_sts_pinned_key). This build declares the
+// capability on syncRegistry, and the API serves the entry only to an org Agentcard enabled for
+// shiji_sts, so for every other org nothing here fires: isCardRequest never recognizes an STS URL
+// and Shiji's requests go through untouched, exactly as before.
+//
+// For an org in the dark launch, a POST the registry recognizes on an STS host is judged by
+// payment-core's classifier (shiji-sts.generated.ts classifyShijiStsRequest), the same rules the API
+// runs at create and the device runs before it encrypts:
+//   - a getTokenId in the proxy's shape is the one prompt, but only once the card-on-file decision is
+//     made: the token Shiji mints guarantees a hotel stay, so while SHIJI_STS_KEEP_ON_FILE is
+//     'refuse' every one is refused in the browser (shiji_sts_keep_on_file) before any create or
+//     prompt, and the page's card never reaches Shiji. Once asked, the device's ciphertext goes only
+//     into that paused request, byte for byte: if the page abandons it, the approval is cancelled
+//     (merchant_request_aborted) and no later getTokenId is answered from it, because one of the
+//     same shape can name another Shiji merchant's accessToken and keySequence;
+//   - a getCvvId never prompts. It continues with the device's CVV ciphertext only when it is the
+//     companion of the getTokenId this attachment continued with the Vault's ciphertexts (same host,
+//     same page, same accessToken, a keySequence the API reviewed as that page's getCvvId key and
+//     served with the approval, within 120 s, once), and is refused otherwise, so the agent's
+//     placeholder CVV never rides beside a real card and the real one goes to no unreviewed key. The
+//     binding, and the CVV ciphertext it holds, is dropped as soon as the attachment can no longer
+//     use it: a cancel, the page, frame or target that sent the getTokenId going away, or that frame
+//     committing a new document, which never obtained the approval;
+//   - anything else on those two URLs is refused as an unsupported checkout.
+// Autopilot never pays this processor: the API, the authority and the enclave refuse it.
+import { SHIJI_STS_COMPANION_WINDOW_MS, SHIJI_STS_PSP, ShijiStsError, classifyShijiStsRequest, createShijiStsCompanion, isShijiStsCiphertext, isShijiStsHost, shijiStsEndpoint, substituteShijiSts, } from './shiji-sts.generated.js';
+export { SHIJI_STS_COMPANION_WINDOW_MS, SHIJI_STS_PSP, ShijiStsError, isShijiStsHost };
+/** The dark-launch capability a build declares when it swaps Shiji's ciphertexts and binds its getCvvId companion. */
+export const SHIJI_STS_CAPABILITY = 'shiji_sts_pinned_key';
+const REFUSED = Object.freeze({
+    keep_on_file: 'shiji_sts_keep_on_file',
+    foreign_key: 'shiji_sts_foreign_key',
+    unsupported: 'unsupported_shiji_sts_request',
+    companion_unbound: 'shiji_sts_companion_unbound',
+    companion_expired: 'shiji_sts_companion_expired',
+    companion_used: 'shiji_sts_companion_used',
+});
+/**
+ * The verdict on a request to an STS host that the registry recognized: 'pause' for the one prompt
+ * (a getTokenId in the proxy's shape once the card-on-file decision allows it), 'companion' for a
+ * getCvvId in the proxy's shape, and 'refuse' with a reason for everything else. A classifier that
+ * throws refuses.
+ */
+export function shijiStsVerdict(request) {
+    let verdict;
+    try {
+        verdict = classifyShijiStsRequest(request.url, request.method.toUpperCase(), request.body);
+    }
+    catch {
+        verdict = null;
+    }
+    if (verdict === 'card')
+        return { kind: 'pause' };
+    if (verdict === 'companion')
+        return { kind: 'companion' };
+    return { kind: 'refuse', reason: (verdict && REFUSED[verdict]) || 'unsupported_shiji_sts_request' };
+}
+const SERVED_FIELDS = ['pan', 'expires', 'cvv'];
+/**
+ * Whether an approved Shiji STS authorization's served substitution is one this SDK can continue:
+ * JSON at the body root (`at` is ''), no sibling to remove, and exactly pan, expires and cvv, each a
+ * 128-byte ciphertext as JSEncrypt writes one. Anything else is not acted on.
+ */
+export function isShijiStsServedSubstitution(sub) {
+    if (!sub || typeof sub !== 'object' || Array.isArray(sub))
+        return false;
+    const { encoding, at, fields, remove } = sub;
+    if (encoding !== 'json' || at !== '' || !fields || typeof fields !== 'object' || Array.isArray(fields))
+        return false;
+    if (remove !== undefined && !(Array.isArray(remove) && remove.length === 0))
+        return false;
+    const names = Object.keys(fields);
+    return names.length === SERVED_FIELDS.length
+        && SERVED_FIELDS.every((name) => isShijiStsCiphertext(fields[name]));
+}
+const SERVED_KEY_SEQUENCE = /^[\x21-\x7e]{1,256}$/;
+const SERVED_KEY_SEQUENCES_LIMIT = 16;
+/**
+ * Whether the API's `shiji_sts_companion` beside an approved Shiji STS set is one this SDK can bind
+ * the companion getCvvId to: exactly `{ key_sequences }`, 1 to 16 non-empty keySequences of printable
+ * ASCII. Anything else, an API that serves none included, is not acted on: the approval reads as
+ * malformed and the getTokenId is not continued, so no card reaches Shiji while its CVV has no
+ * reviewed key to go to.
+ */
+export function isShijiStsServedCompanion(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const names = Object.keys(value);
+    if (names.length !== 1 || names[0] !== 'key_sequences')
+        return false;
+    const keys = value.key_sequences;
+    return Array.isArray(keys) && keys.length > 0 && keys.length <= SERVED_KEY_SEQUENCES_LIMIT
+        && keys.every((key) => typeof key === 'string' && SERVED_KEY_SEQUENCE.test(key));
+}
+/**
+ * The continuation of an approved getTokenId: the paused body with the device's pan and expires
+ * written over the page's own at the body root (payment-core substituteShijiSts, which refuses a
+ * value that is not a ciphertext under the pinned key), the device's cvv, which this body does not
+ * carry and the runtime keeps in memory for the one companion getCvvId, and the reviewed getCvvId
+ * keys that companion may carry it under (`companion`, the replay's shijiStsCompanion, which the
+ * client read from the API's shiji_sts_companion).
+ *
+ * Only into `approved`, the paused getTokenId the approval was created from: `url` and `body` must
+ * equal it byte for byte, so the accessToken and keySequence are the ones the API reviewed at create
+ * (its merchant binding). Every Shiji merchant's card is encrypted under the one pinned key, so the
+ * device's ciphertext would tokenize the card in any STS session a later request of the same shape
+ * names. The adapters never hand a Shiji approval to a retry either (cdp.ts survivesAbandonment).
+ *
+ * Null when neither URL is on an STS host, so every other processor keeps the generic swap. Throws
+ * for any other body or URL, an STS URL that is not getTokenId, a substitution
+ * isShijiStsServedSubstitution refuses (`sub` is whatever the approval served, of any processor's
+ * shape), no reviewed getCvvId key to bind the companion to, and while the card-on-file decision is
+ * open: in each case before anything continues.
+ */
+export function shijiStsTokenContinuation(url, body, sub, approved, companion) {
+    if (!isShijiStsHost(url) && !isShijiStsHost(approved.url))
+        return null;
+    if (url !== approved.url || body !== approved.body)
+        throw new ShijiStsError('unsupported');
+    if (shijiStsEndpoint(url, 'POST') !== 'token' || !isShijiStsServedSubstitution(sub))
+        throw new ShijiStsError('unsupported');
+    const keys = companion && Array.isArray(companion.keySequences) ? [...companion.keySequences] : null;
+    if (!keys || !isShijiStsServedCompanion({ key_sequences: keys }))
+        throw new ShijiStsError('unsupported');
+    return { body: substituteShijiSts(url, body, { pan: sub.fields.pan, expires: sub.fields.expires }), cvv: sub.fields.cvv, cvvKeySequences: keys };
+}
+/**
+ * One attachment's getCvvId companion: at most one binding, to the getTokenId it last continued with
+ * the Vault's ciphertexts. `bind` runs right before that continue, `release` when the continue
+ * fails or the attachment is cancelled or its page goes away, `releasePage` when the frame or target
+ * the getTokenId came from goes away or commits a new document, and `claim` for every getCvvId in the
+ * proxy's shape. The binding is payment-core's (createShijiStsCompanion: same host, same page, same
+ * accessToken, a reviewed getCvvId key, within 120 s, once). The CVV ciphertext leaves memory with the
+ * one body it goes into or with the teardown that releases it, and the binding itself is dropped a
+ * little after its window, so a later getCvvId reads as unbound.
+ */
+export class ShijiStsCompanions {
+    bound = null;
+    /**
+     * Bind the companion of `tokenRequest` (the paused getTokenId: its URL, method and body) for the
+     * page `page` (the adapter's opaque id for the frame that sent it) and keep `cvv`, the device's
+     * CVV ciphertext, for it, to go only into a getCvvId whose keySequence is one of `cvvKeySequences`
+     * (the reviewed getCvvId keys the approval served). Replaces any earlier binding. Throws
+     * ShijiStsError for a request that is not a getTokenId in the proxy's shape, a key list
+     * payment-core refuses (none, empty or malformed), and while the card-on-file decision is open.
+     */
+    bind(tokenRequest, page, cvv, cvvKeySequences, now = Date.now()) {
+        this.release();
+        if (!isShijiStsCiphertext(cvv))
+            throw new ShijiStsError('unsupported');
+        const companion = createShijiStsCompanion({ url: tokenRequest.url, method: tokenRequest.method.toUpperCase(), body: tokenRequest.body }, { page, now, cvvKeySequences: Array.isArray(cvvKeySequences) ? [...cvvKeySequences] : cvvKeySequences });
+        const timer = setTimeout(() => { if (this.bound?.timer === timer)
+            this.bound = null; }, SHIJI_STS_COMPANION_WINDOW_MS + 1000);
+        timer.unref?.();
+        this.bound = { companion, cvv, page, timer };
+    }
+    /** Drop the binding and the CVV ciphertext it holds. */
+    release() {
+        if (this.bound)
+            clearTimeout(this.bound.timer);
+        this.bound = null;
+    }
+    /**
+     * Drop the binding only when its page is one `gone` names: the adapter calls it with a test for the
+     * page ids of a frame or target that went away, so the CVV ciphertext never outlives the frame its
+     * getCvvId would have to come from, and a binding on another frame stays.
+     */
+    releasePage(gone) {
+        if (this.bound && gone(this.bound.page))
+            this.release();
+    }
+    /** Whether a binding is held (its window may have closed; claim decides). */
+    isBound() {
+        return this.bound !== null;
+    }
+    /** The page id the binding is held for, or null with none: an adapter compares its own ids to it. */
+    boundPage() {
+        return this.bound?.page ?? null;
+    }
+    /**
+     * The body to continue a getCvvId with, the device's CVV written over the page's own at the body
+     * root, or why the request is refused. Only the first getCvvId the binding answers 'swap' for gets
+     * a body; the CVV ciphertext is dropped as it is written, so a second one reads as used.
+     */
+    claim(request, page, now = Date.now()) {
+        const bound = this.bound;
+        if (!bound)
+            return { reason: 'shiji_sts_companion_unbound' };
+        let answer;
+        try {
+            answer = bound.companion.claim({ url: request.url, method: request.method.toUpperCase(), body: request.body }, { page, now });
+        }
+        catch {
+            answer = 'unsupported';
+        }
+        if (answer !== 'swap')
+            return { reason: REFUSED[answer] ?? 'unsupported_shiji_sts_request' };
+        const cvv = bound.cvv;
+        bound.cvv = null;
+        if (cvv === null)
+            return { reason: 'shiji_sts_companion_used' };
+        try {
+            return { body: substituteShijiSts(request.url, request.body, { cvv }) };
+        }
+        catch {
+            return { reason: 'unsupported_shiji_sts_request' };
+        }
+    }
+}

package/dist/stripe-checkout.generated.d.ts

@@ -23,7 +23,7 @@ declare var STRIPE_CHECKOUT_VALIDATION_CODES: Readonly<{
     synthetic_payment_method: "synthetic_payment_method";
     required_final_fields: "required_final_fields";
 }>;
-declare function stripeCheckoutValidationCode(error: any): "unclassified" | "request_shape" | "request_body_bounds" | "request_headers" | "form_encoding" | "form_field_unknown" | "form_field_duplicate" | "form_value_bounds" | "context_invalid" | "session_binding" | "publishable_key" | "mode_binding" | "attribution_session" | "tokenization_fields" | "billing_email" | "billing_binding" | "billing_conflict" | "expected_amount" | "payment_method_type" | "synthetic_payment_method" | "required_final_fields";
+declare function stripeCheckoutValidationCode(error: any): "payment_method_type" | "unclassified" | "request_shape" | "request_body_bounds" | "request_headers" | "form_encoding" | "form_field_unknown" | "form_field_duplicate" | "form_value_bounds" | "context_invalid" | "session_binding" | "publishable_key" | "mode_binding" | "attribution_session" | "tokenization_fields" | "billing_email" | "billing_binding" | "billing_conflict" | "expected_amount" | "synthetic_payment_method" | "required_final_fields";
 declare function validateStripeCheckoutIdentity(value: any): Readonly<{
     environment: any;
     livemode: boolean;