@conto_finance/sdk 0.6.1 → 0.7.0

package/README.md

@@ -80,6 +80,9 @@ if (checkpoint.stage === 'AWAITING_APPROVAL') {
   // The agent's rules need the owner. Throws if the owner rejects or the approval expires.
   checkpoint = await conto.checkout.waitForApproval(checkpoint, { timeoutMs: 15 * 60_000 });
 }
+if (checkpoint.stage !== 'APPROVED') {
+  throw new Error('Inspect the existing purchase before continuing.');
+}
 // Open Link. The buyer signs in and the final total appears.
 
 const confirmed = await conto.checkout.confirm(checkpoint, {
@@ -107,6 +110,68 @@ await conto.checkout.reportOutcome(confirmed.id, { outcome: 'PAID', reference: o
 - Conto records what your checkout reports and does not see the charge. For control at the
   moment of payment, pay with a Conto-managed wallet or a card Conto authorizes.
 
+## Stripe Link cards
+
+The Stripe Link card integration ships in SDK 0.7.0 and later (`npm install @conto_finance/sdk`).
+The Link controls integration kit bundles the same SDK.
+The [minimal trusted-runtime example](https://github.com/Conto-Finance/conto/tree/main/examples/link-wallet-agent)
+uses the existing agent SDK key, requires no shopping frontend, and never pays.
+
+Stripe Link is Stripe's payment wallet, and Conto integrates with it. `conto.checkout.getLinkCard()`
+asks Conto first, then asks Stripe Link for a card only after Conto approves the purchase, for
+exactly the approved amount at that store. Stripe Link issues the card. It runs Stripe's `link-cli`
+on your machine with your own Link login (`npm i -g @stripe/link-cli`, then `link-cli auth login`).
+The person approves each card in Link, in the app or on the web. Conto does not receive the card. It stores only the
+Link request ID.
+
+```typescript
+import { linkCliWallet } from '@conto_finance/sdk/link-wallet';
+
+const wallet = linkCliWallet({ test: true });
+
+// At the payment step, once the final total with shipping and tax is known.
+const result = await conto.checkout.getLinkCard({
+  idempotencyKey: order.id,
+  merchant: { id: 'acme-retail', name: 'ACME Retail', checkoutUrl: page.url() },
+  amountMinor: 8532,
+  purpose: 'Drip coffee maker the shopper chose',
+  lineItems: [{ name: 'Drip coffee maker', quantity: 1, unitAmountMinor: 7900 }],
+  wallet,
+});
+
+// Fill in result.card in the store's card form, then right before paying:
+const confirmed = await conto.checkout.confirm(result.checkpoint, {
+  amountMinor: 8532,
+  lineItems: observedItems,
+  totals: observedCharges,
+  paymentReference: result.paymentReference,
+});
+// Pay, then report the outcome with the same paymentReference.
+```
+
+- Link is never asked for a card before Conto approves. A denial at Conto throws before any Link
+  call. When a rule requires approval, `getLinkCard()` waits for the owner first.
+- When the person declines in Link, the request expires, the wait passes `linkApprovalTimeoutMs`,
+  or `link-cli` is missing or logged out, `getLinkCard()` cancels the checkpoint to release the
+  held spend and throws `LinkCardDeniedError`, `LinkCardExpiredError`, `LinkCardTimeoutError`, or
+  `LinkWalletUnavailableError`. All extend `LinkCardError`. Do not pay.
+- Retrying with the same input resumes the same checkpoint and Link request.
+- The card (`number`, `securityValue` for the CVC, `expMonth`, `expYear`, `validUntil`, `last4`,
+  `brand`) stays in this process. Printing or serializing the result shows only the last four
+  digits. It never appears in an error.
+- The card covers the approved total, so `confirm()` with a `paymentReference` refuses a
+  different total. Call `conto.checkout.replaceLinkCard(result, { wallet, amountMinor })` to
+  cancel the old card and checkpoint and get a card for the final total.
+- Any `LinkWallet` works in place of `linkCliWallet()`: it creates a card request, waits for
+  approval, retrieves the card, and cancels.
+- The protection holds only when the agent cannot also run `link-cli`, use a shell, or call Link
+  with your credentials itself.
+- Pass observed final items and charges to `confirm()` even when the total is unchanged.
+  The server rejects a changed cart against the approved intent. The trusted host must
+  validate the actual merchant and checkout, own a durable one-use payment dispatch
+  claim, and keep card use outside model tools. Replaying a confirmed checkpoint is
+  not permission to submit payment again.
+
 ## External-card Policy Overlay
 
 The admin client registers only a masked card alias and assigns cooperative

package/dist/browserbase.d.mts

@@ -1,6 +1,7 @@
 import { Browser } from 'playwright-core';
 import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.mjs';
 import './index.mjs';
+import './link-wallet.mjs';
 
 /** Exact provider endpoints verified against Browserbase's session API; never use a wildcard. */
 declare const BROWSERBASE_CONNECT_ORIGINS: readonly string[];
@@ -150,4 +151,5 @@ declare function createBrowserbaseSessionManager(config: BrowserbaseSessionConfi
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionManager, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };
+export { BROWSERBASE_CONNECT_ORIGINS, BrowserbaseSessionError, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };
+export type { BrowserbaseAttachedSession, BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, BrowserbaseOwnedLiveView, BrowserbaseOwnedSession, BrowserbaseSessionBinding, BrowserbaseSessionBindingState, BrowserbaseSessionBindingStore, BrowserbaseSessionConfig, BrowserbaseSessionErrorCode, BrowserbaseSessionHandoff, BrowserbaseSessionHandoffAssertionInput, BrowserbaseSessionLifecycleOwner, BrowserbaseSessionManager, BrowserbaseSessionStatus };

package/dist/browserbase.d.ts

@@ -1,6 +1,7 @@
 import { Browser } from 'playwright-core';
 import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.js';
 import './index.js';
+import './link-wallet.js';
 
 /** Exact provider endpoints verified against Browserbase's session API; never use a wildcard. */
 declare const BROWSERBASE_CONNECT_ORIGINS: readonly string[];
@@ -150,4 +151,5 @@ declare function createBrowserbaseSessionManager(config: BrowserbaseSessionConfi
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionManager, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };
+export { BROWSERBASE_CONNECT_ORIGINS, BrowserbaseSessionError, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };
+export type { BrowserbaseAttachedSession, BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, BrowserbaseOwnedLiveView, BrowserbaseOwnedSession, BrowserbaseSessionBinding, BrowserbaseSessionBindingState, BrowserbaseSessionBindingStore, BrowserbaseSessionConfig, BrowserbaseSessionErrorCode, BrowserbaseSessionHandoff, BrowserbaseSessionHandoffAssertionInput, BrowserbaseSessionLifecycleOwner, BrowserbaseSessionManager, BrowserbaseSessionStatus };

package/dist/browserbase.js

@@ -322,13 +322,16 @@ function createEncryptedPlaywrightCheckoutTargetStore(config) {
         if (envelope.version !== TARGET_STORE_ENVELOPE_VERSION || typeof envelope.iv !== "string" || typeof envelope.ciphertext !== "string" || typeof envelope.tag !== "string") {
           throw new Error("invalid envelope");
         }
+        const tag = Buffer.from(envelope.tag, "base64url");
+        if (tag.length !== 16) throw new Error("invalid envelope");
         const decipher = (0, import_node_crypto2.createDecipheriv)(
           "aes-256-gcm",
           key,
-          Buffer.from(envelope.iv, "base64url")
+          Buffer.from(envelope.iv, "base64url"),
+          { authTagLength: 16 }
         );
         decipher.setAAD(Buffer.from(storageKey));
-        decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
+        decipher.setAuthTag(tag);
         const plaintext = Buffer.concat([
           decipher.update(Buffer.from(envelope.ciphertext, "base64url")),
           decipher.final()

package/dist/browserbase.mjs

@@ -1,8 +1,8 @@
 import {
   createGuardedPlaywrightCheckoutRuntimeHost
-} from "./chunk-VSIO6PYA.mjs";
+} from "./chunk-JBTJXIMI.mjs";
 import "./chunk-O5RAAB2U.mjs";
-import "./chunk-WSIKPUZJ.mjs";
+import "./chunk-TGOYFBKZ.mjs";
 
 // src/browserbase.ts
 import { createHmac, timingSafeEqual } from "crypto";

package/dist/checkout-verifier.d.mts

@@ -92,4 +92,5 @@ interface VerifyCheckoutIntegrationOptions {
  */
 declare function verifyCheckoutIntegration(value: CheckoutCapabilityManifest | unknown, options?: VerifyCheckoutIntegrationOptions): Promise<CheckoutIntegrationVerificationReport>;
 
-export { CHECKOUT_CAPABILITY_KINDS, CHECKOUT_CAPABILITY_MANIFEST_VERSION, CHECKOUT_CONFORMANCE_PROBE_IDS, CHECKOUT_METHOD_IDS, CHECKOUT_VERIFICATION_REPORT_VERSION, type CheckoutCapabilityDescriptor, type CheckoutCapabilityExposure, type CheckoutCapabilityInventoryScope, type CheckoutCapabilityKind, type CheckoutCapabilityManifest, type CheckoutCapabilityPaymentBoundary, type CheckoutConformanceProbeId, type CheckoutConformanceProbeObservation, type CheckoutConformanceProbeOutcome, type CheckoutConformanceProbeRequest, type CheckoutConformanceProbeResult, type CheckoutConformanceProbeRunner, type CheckoutIntegrationComponent, type CheckoutIntegrationStatus, type CheckoutIntegrationVerificationReport, type CheckoutMethodId, type CheckoutSessionBinding, type CheckoutVerificationFinding, type CheckoutVerificationFindingCode, type VerifyCheckoutIntegrationOptions, verifyCheckoutIntegration };
+export { CHECKOUT_CAPABILITY_KINDS, CHECKOUT_CAPABILITY_MANIFEST_VERSION, CHECKOUT_CONFORMANCE_PROBE_IDS, CHECKOUT_METHOD_IDS, CHECKOUT_VERIFICATION_REPORT_VERSION, verifyCheckoutIntegration };
+export type { CheckoutCapabilityDescriptor, CheckoutCapabilityExposure, CheckoutCapabilityInventoryScope, CheckoutCapabilityKind, CheckoutCapabilityManifest, CheckoutCapabilityPaymentBoundary, CheckoutConformanceProbeId, CheckoutConformanceProbeObservation, CheckoutConformanceProbeOutcome, CheckoutConformanceProbeRequest, CheckoutConformanceProbeResult, CheckoutConformanceProbeRunner, CheckoutIntegrationComponent, CheckoutIntegrationStatus, CheckoutIntegrationVerificationReport, CheckoutMethodId, CheckoutSessionBinding, CheckoutVerificationFinding, CheckoutVerificationFindingCode, VerifyCheckoutIntegrationOptions };

package/dist/checkout-verifier.d.ts

@@ -92,4 +92,5 @@ interface VerifyCheckoutIntegrationOptions {
  */
 declare function verifyCheckoutIntegration(value: CheckoutCapabilityManifest | unknown, options?: VerifyCheckoutIntegrationOptions): Promise<CheckoutIntegrationVerificationReport>;
 
-export { CHECKOUT_CAPABILITY_KINDS, CHECKOUT_CAPABILITY_MANIFEST_VERSION, CHECKOUT_CONFORMANCE_PROBE_IDS, CHECKOUT_METHOD_IDS, CHECKOUT_VERIFICATION_REPORT_VERSION, type CheckoutCapabilityDescriptor, type CheckoutCapabilityExposure, type CheckoutCapabilityInventoryScope, type CheckoutCapabilityKind, type CheckoutCapabilityManifest, type CheckoutCapabilityPaymentBoundary, type CheckoutConformanceProbeId, type CheckoutConformanceProbeObservation, type CheckoutConformanceProbeOutcome, type CheckoutConformanceProbeRequest, type CheckoutConformanceProbeResult, type CheckoutConformanceProbeRunner, type CheckoutIntegrationComponent, type CheckoutIntegrationStatus, type CheckoutIntegrationVerificationReport, type CheckoutMethodId, type CheckoutSessionBinding, type CheckoutVerificationFinding, type CheckoutVerificationFindingCode, type VerifyCheckoutIntegrationOptions, verifyCheckoutIntegration };
+export { CHECKOUT_CAPABILITY_KINDS, CHECKOUT_CAPABILITY_MANIFEST_VERSION, CHECKOUT_CONFORMANCE_PROBE_IDS, CHECKOUT_METHOD_IDS, CHECKOUT_VERIFICATION_REPORT_VERSION, verifyCheckoutIntegration };
+export type { CheckoutCapabilityDescriptor, CheckoutCapabilityExposure, CheckoutCapabilityInventoryScope, CheckoutCapabilityKind, CheckoutCapabilityManifest, CheckoutCapabilityPaymentBoundary, CheckoutConformanceProbeId, CheckoutConformanceProbeObservation, CheckoutConformanceProbeOutcome, CheckoutConformanceProbeRequest, CheckoutConformanceProbeResult, CheckoutConformanceProbeRunner, CheckoutIntegrationComponent, CheckoutIntegrationStatus, CheckoutIntegrationVerificationReport, CheckoutMethodId, CheckoutSessionBinding, CheckoutVerificationFinding, CheckoutVerificationFindingCode, VerifyCheckoutIntegrationOptions };

package/dist/checkout-verifier.mjs

@@ -1,4 +1,4 @@
-import "./chunk-WSIKPUZJ.mjs";
+import "./chunk-TGOYFBKZ.mjs";
 
 // src/checkout-verifier.ts
 import { createHash, randomUUID } from "crypto";

package/dist/{chunk-VSIO6PYA.mjs → chunk-JBTJXIMI.mjs}

@@ -184,13 +184,16 @@ function createEncryptedPlaywrightCheckoutTargetStore(config) {
         if (envelope.version !== TARGET_STORE_ENVELOPE_VERSION || typeof envelope.iv !== "string" || typeof envelope.ciphertext !== "string" || typeof envelope.tag !== "string") {
           throw new Error("invalid envelope");
         }
+        const tag = Buffer.from(envelope.tag, "base64url");
+        if (tag.length !== 16) throw new Error("invalid envelope");
         const decipher = createDecipheriv(
           "aes-256-gcm",
           key,
-          Buffer.from(envelope.iv, "base64url")
+          Buffer.from(envelope.iv, "base64url"),
+          { authTagLength: 16 }
         );
         decipher.setAAD(Buffer.from(storageKey));
-        decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
+        decipher.setAuthTag(tag);
         const plaintext = Buffer.concat([
           decipher.update(Buffer.from(envelope.ciphertext, "base64url")),
           decipher.final()

package/dist/{chunk-WSIKPUZJ.mjs → chunk-TGOYFBKZ.mjs}

@@ -34,11 +34,13 @@ var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot
 var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
 export {
   __commonJS,
   __toESM,
   __privateGet,
   __privateAdd,
-  __privateSet
+  __privateSet,
+  __privateMethod
 };