@myzonerocks/pact 0.1.4 → 0.1.7

package/README.md

@@ -105,9 +105,9 @@ webhooks, so run them on a server, never in a browser bundle.
 
 ## Conformance
 
-The Go, TypeScript, and Dart SDKs are held to one wire format by shared vectors: a
-fixed intent produces a fixed canonical preimage, hash, and signature that all
-three reproduce byte-for-byte.
+The Go, TypeScript, Dart, Swift, and Kotlin SDKs are held to one wire format by
+shared vectors: a fixed intent produces a fixed canonical preimage, hash, and
+signature that every one of them reproduces byte-for-byte.
 
 ```
 bun run test

package/dist/src/adapters/erc20.d.ts

@@ -28,6 +28,22 @@ export interface Erc20Config {
     ids: () => string;
     decimals: number;
     minConfirmations?: number;
+    store?: SentStore;
+}
+export interface SentRecord {
+    intentId: string;
+    txHash: string;
+    to: string;
+    amount: bigint;
+}
+export interface SentStore {
+    save(rec: SentRecord): Promise<void>;
+    byIntent(intentId: string): Promise<SentRecord | undefined>;
+}
+export declare class MemorySentStore implements SentStore {
+    private readonly byIntentMap;
+    save(rec: SentRecord): Promise<void>;
+    byIntent(intentId: string): Promise<SentRecord | undefined>;
 }
 export declare class Erc20Leg implements PayInLeg, PayOutLeg {
     readonly id: string;
@@ -38,7 +54,7 @@ export declare class Erc20Leg implements PayInLeg, PayOutLeg {
     private readonly ids;
     private readonly decimals;
     private readonly minConf;
-    private readonly sent;
+    private readonly store;
     constructor(cfg: Erc20Config);
     private checkScale;
     payInCapabilities(): PayInCapabilities;

package/dist/src/adapters/erc20.js

@@ -14,6 +14,16 @@ const transferSelector = "a9059cbb";
 // success can still be reorged out, so a settlement waits for enough blocks on
 // top of it.
 const defaultMinConfirmations = 12;
+// MemorySentStore is the default in-process store.
+export class MemorySentStore {
+    byIntentMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+}
 // Erc20Leg settles a payment as an ERC-20 token transfer. Refunds are a
 // counter-transfer only, because a token transfer is irreversible.
 export class Erc20Leg {
@@ -25,9 +35,9 @@ export class Erc20Leg {
     ids;
     decimals;
     minConf;
-    // Each broadcast transfer and what it was meant to move, so a settlement can
-    // confirm the mined transaction really matches the payment.
-    sent = new Map();
+    // Broadcast transfers, so a settlement can confirm the mined transaction really
+    // matches the payment, and a repeat returns the first transfer.
+    store;
     constructor(cfg) {
         if (!cfg.token || !cfg.currency) {
             throw new Error("erc20: config requires a token address and currency");
@@ -45,6 +55,7 @@ export class Erc20Leg {
         this.ids = cfg.ids;
         this.decimals = cfg.decimals;
         this.minConf = cfg.minConfirmations ?? defaultMinConfirmations;
+        this.store = cfg.store ?? new MemorySentStore();
     }
     // checkScale refuses an amount whose exponent does not match the token's
     // decimals, so a quote priced at the wrong scale never moves the wrong number
@@ -71,12 +82,12 @@ export class Erc20Leg {
         const net = quote.srcAmount.sub(quote.fees);
         // A repeat for the same intent returns the transfer already broadcast rather
         // than sending the payer's tokens twice.
-        const prev = this.sent.get(intentId);
+        const prev = await this.store.byIntent(intentId);
         if (prev) {
             return { providerRef: prev.txHash, received: net };
         }
         const txHash = await this.transfer(deliverTo, net.value());
-        this.sent.set(intentId, { txHash, to: normalizeAddress(deliverTo), amount: net.value() });
+        await this.store.save({ intentId, txHash, to: normalizeAddress(deliverTo), amount: net.value() });
         return { providerRef: txHash, received: net };
     }
     // disburse delivers the recipient's tokens.
@@ -84,13 +95,13 @@ export class Erc20Leg {
         this.checkScale(quote.dstAmount);
         // A repeat for the same intent returns the transfer already broadcast rather
         // than delivering the recipient's tokens twice.
-        const prev = this.sent.get(intentId);
+        const prev = await this.store.byIntent(intentId);
         if (prev) {
             return { providerRef: prev.txHash };
         }
         const amount = quote.dstAmount.value();
         const txHash = await this.transfer(recipientRef, amount);
-        this.sent.set(intentId, { txHash, to: normalizeAddress(recipientRef), amount });
+        await this.store.save({ intentId, txHash, to: normalizeAddress(recipientRef), amount });
         return { providerRef: txHash };
     }
     // refundIn refuses: an ERC-20 collection is irreversible and the leg holds no
@@ -113,7 +124,7 @@ export class Erc20Leg {
     // shallow success stays submitted so the host keeps polling; a revert or a
     // mismatch fails, so a dropped, reorged, or spoofed transfer never settles.
     async settlementEvent(intentId) {
-        const rec = this.sent.get(intentId);
+        const rec = await this.store.byIntent(intentId);
         if (!rec) {
             throw new Error("erc20: no broadcast transaction for intent");
         }

package/dist/src/adapters/mpesa.d.ts

@@ -20,6 +20,7 @@ export interface B2CParams {
     phone: string;
     reference: string;
     remarks: string;
+    idempotencyKey: string;
 }
 export interface B2CResult {
     conversationId: string;
@@ -35,19 +36,37 @@ export interface DarajaApi {
     b2cPayment(params: B2CParams): Promise<B2CResult>;
     query(checkoutRequestId: string): Promise<StkQueryResult>;
 }
+export interface PushRecord {
+    intentId: string;
+    checkoutId: string;
+    payerPhone: string;
+    amount: number;
+}
+export interface PushStore {
+    save(rec: PushRecord): Promise<void>;
+    byIntent(intentId: string): Promise<PushRecord | undefined>;
+    byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+}
+export declare class MemoryPushStore implements PushStore {
+    private readonly byIntentMap;
+    private readonly byCheckoutMap;
+    save(rec: PushRecord): Promise<void>;
+    byIntent(intentId: string): Promise<PushRecord | undefined>;
+    byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+}
 export interface MpesaConfig {
     id?: string;
     api: DarajaApi;
     callbackURL: string;
     ids: () => string;
+    store?: PushStore;
 }
 export declare class MpesaLeg implements PayInLeg, PayOutLeg {
     readonly id: string;
     private readonly api;
     private readonly callbackURL;
     private readonly ids;
-    private readonly byIntent;
-    private readonly byCheckout;
+    private readonly store;
     constructor(cfg: MpesaConfig);
     payInCapabilities(): PayInCapabilities;
     payOutCapabilities(): PayOutCapabilities;

package/dist/src/adapters/mpesa.js

@@ -9,14 +9,29 @@ const defaultBaseURL = "https://api.safaricom.co.ke";
 // checkout id to one we started is the authentication: an unrecognized id is
 // rejected rather than acted on.
 export const ErrUnknownCheckout = "mpesa: callback for an unknown checkout request";
+// MemoryPushStore is the default in-process store.
+export class MemoryPushStore {
+    byIntentMap = new Map();
+    byCheckoutMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+        if (rec.checkoutId)
+            this.byCheckoutMap.set(rec.checkoutId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+    async byCheckout(checkoutId) {
+        return this.byCheckoutMap.get(checkoutId);
+    }
+}
 // MpesaLeg moves mobile money over M-Pesa.
 export class MpesaLeg {
     id;
     api;
     callbackURL;
     ids;
-    byIntent = new Map();
-    byCheckout = new Map();
+    store;
     constructor(cfg) {
         if (!cfg.callbackURL) {
             throw new Error("mpesa: config requires a callback URL");
@@ -25,6 +40,7 @@ export class MpesaLeg {
         this.api = cfg.api;
         this.callbackURL = cfg.callbackURL;
         this.ids = cfg.ids;
+        this.store = cfg.store ?? new MemoryPushStore();
     }
     payInCapabilities() {
         return { rails: ["mpesa"], currencies: ["KES"], refunds: RefundKind.CounterTransfer };
@@ -45,7 +61,6 @@ export class MpesaLeg {
         if (!phone) {
             throw new Error("mpesa: collect requires the payer's phone");
         }
-        const rec = { intentId, payerPhone: phone, amount, state: State.Unspecified };
         const result = await this.api.stkPush({
             amount,
             payerPhone: phone,
@@ -53,8 +68,7 @@ export class MpesaLeg {
             description: "payment",
             callbackURL: this.callbackURL,
         });
-        this.byIntent.set(intentId, rec);
-        this.byCheckout.set(result.checkoutRequestId, rec);
+        await this.store.save({ intentId, checkoutId: result.checkoutRequestId, payerPhone: phone, amount });
         return { providerRef: result.checkoutRequestId, received: net };
     }
     // disburse delivers the recipient's shillings by a business-to-customer payout
@@ -65,7 +79,7 @@ export class MpesaLeg {
         if (!phone) {
             throw new Error("mpesa: disburse requires the recipient's phone");
         }
-        const result = await this.api.b2cPayment({ amount, phone, reference: intentId, remarks: "payout" });
+        const result = await this.api.b2cPayment({ amount, phone, reference: intentId, remarks: "payout", idempotencyKey: `pact:payout:${intentId}` });
         return { providerRef: result.conversationId };
     }
     // refundIn answers a collected payment with a business-to-customer payout back
@@ -76,7 +90,7 @@ export class MpesaLeg {
             throw new Error("mpesa: a collection can only be refunded by counter-transfer");
         }
         const shillings = wholeShillings(amount);
-        const rec = this.byIntent.get(intentId);
+        const rec = await this.store.byIntent(intentId);
         if (!rec) {
             throw new Error(`mpesa: no push for intent ${intentId}`);
         }
@@ -89,6 +103,7 @@ export class MpesaLeg {
             phone: rec.payerPhone,
             reference: intentId,
             remarks: reason,
+            idempotencyKey: `pact:refund:${intentId}`,
         });
         return {
             intentId,
@@ -116,7 +131,7 @@ export class MpesaLeg {
     async parseWebhook(raw, _headers) {
         const envelope = JSON.parse(new TextDecoder().decode(raw));
         const cb = envelope.Body?.stkCallback;
-        const rec = cb ? this.byCheckout.get(cb.CheckoutRequestID) : undefined;
+        const rec = cb ? await this.store.byCheckout(cb.CheckoutRequestID) : undefined;
         if (!cb || !rec) {
             throw new Error(ErrUnknownCheckout);
         }
@@ -127,7 +142,6 @@ export class MpesaLeg {
             return [];
         }
         if (confirmed.resultCode !== 0) {
-            rec.state = State.Failed;
             return [
                 {
                     intentId: rec.intentId,
@@ -146,7 +160,6 @@ export class MpesaLeg {
             throw new Error(`mpesa: confirmed amount ${paid} does not match the authorized ${rec.amount}`);
         }
         const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
-        rec.state = State.Settled;
         return [
             {
                 intentId: rec.intentId,
@@ -301,6 +314,7 @@ class HttpDarajaApi {
     async b2cPayment(params) {
         const token = await this.token();
         const body = {
+            OriginatorConversationID: params.idempotencyKey,
             InitiatorName: this.creds.shortCode,
             CommandID: "BusinessPayment",
             Amount: params.amount,

package/dist/src/adapters/paypal.d.ts

@@ -52,14 +52,31 @@ export interface PaypalConfig {
     currencies: string[];
     api: PaypalApi;
     ids: () => string;
+    store?: CaptureStore;
+}
+export interface CaptureRecord {
+    intentId: string;
+    captureId: string;
+    expected: {
+        value: string;
+        currency: string;
+    };
+}
+export interface CaptureStore {
+    save(rec: CaptureRecord): Promise<void>;
+    byIntent(intentId: string): Promise<CaptureRecord | undefined>;
+}
+export declare class MemoryCaptureStore implements CaptureStore {
+    private readonly byIntentMap;
+    save(rec: CaptureRecord): Promise<void>;
+    byIntent(intentId: string): Promise<CaptureRecord | undefined>;
 }
 export declare class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
     readonly id: string;
     private readonly currencies;
     private readonly api;
     private readonly ids;
-    private readonly captures;
-    private readonly expected;
+    private readonly store;
     constructor(cfg: PaypalConfig);
     payInCapabilities(): PayInCapabilities;
     payOutCapabilities(): PayOutCapabilities;

package/dist/src/adapters/paypal.js

@@ -17,21 +17,29 @@ const defaultBaseURL = "https://api-m.paypal.com";
 const referencePrefix = "pact:";
 // ErrSignatureMismatch reports a webhook PayPal could not authenticate.
 export const ErrSignatureMismatch = "paypal: webhook signature does not verify";
+// MemoryCaptureStore is the default in-process store.
+export class MemoryCaptureStore {
+    byIntentMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+}
 // PaypalLeg moves money over PayPal, serving both sides of a corridor.
 export class PaypalLeg {
     id;
     currencies;
     api;
     ids;
-    captures = new Map();
-    // What each intent was quoted to collect, so a capture webhook can be
-    // cross-checked: the paid amount and currency must match before it settles.
-    expected = new Map();
+    store;
     constructor(cfg) {
         this.id = cfg.id ?? "paypal";
         this.currencies = cfg.currencies;
         this.api = cfg.api;
         this.ids = cfg.ids;
+        this.store = cfg.store ?? new MemoryCaptureStore();
     }
     payInCapabilities() {
         return {
@@ -54,10 +62,10 @@ export class PaypalLeg {
             payee: deliverTo,
             referenceId: referencePrefix + intentId,
         });
-        this.captures.set(intentId, capture.captureId);
-        this.expected.set(intentId, {
-            value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent),
-            currency: quote.srcAmount.currency,
+        await this.store.save({
+            intentId,
+            captureId: capture.captureId,
+            expected: { value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent), currency: quote.srcAmount.currency },
         });
         return { providerRef: capture.captureId, received: quote.srcAmount.sub(quote.fees) };
     }
@@ -78,9 +86,10 @@ export class PaypalLeg {
             params.platformFee = majorAmount(quote.fees.minor(), quote.fees.exponent);
         }
         const order = await this.api.createOrder(params);
-        this.expected.set(intentId, {
-            value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent),
-            currency: quote.srcAmount.currency,
+        await this.store.save({
+            intentId,
+            captureId: "",
+            expected: { value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent), currency: quote.srcAmount.currency },
         });
         return { providerRef: order.id, clientSecret: order.id, method: "paypal" };
     }
@@ -102,10 +111,11 @@ export class PaypalLeg {
         if (kind !== RefundKind.Full && kind !== RefundKind.Partial) {
             throw new Error(`paypal: cannot perform refund kind ${kind}`);
         }
-        const captureId = this.captures.get(intentId);
-        if (!captureId) {
+        const rec = await this.store.byIntent(intentId);
+        if (!rec || !rec.captureId) {
             throw new Error(`paypal: no capture for intent ${intentId}`);
         }
+        const captureId = rec.captureId;
         // A partial refund names the amount in major units; a full refund leaves it
         // absent so PayPal returns the whole capture.
         const params = kind === RefundKind.Partial
@@ -146,10 +156,11 @@ export class PaypalLeg {
                 // created the order, so a genuine, signed capture for a different order can
                 // carry a target intent's id. Settle only when the captured amount and
                 // currency match what the intent was quoted to collect.
-                const want = this.expected.get(intentId);
-                if (!want) {
+                const rec = await this.store.byIntent(intentId);
+                if (!rec) {
                     throw new Error(`paypal: capture for unknown intent ${JSON.stringify(intentId)}`);
                 }
+                const want = rec.expected;
                 if (resource.amount?.value !== want.value || resource.amount?.currency_code !== want.currency) {
                     throw new Error(`paypal: captured ${resource.amount?.value} ${resource.amount?.currency_code} does not match the quoted ${want.value} ${want.currency}`);
                 }

package/dist/src/adapters/stripe.js

@@ -232,8 +232,15 @@ function parseEvent(payload, header, secret, now, tolerance) {
     verifySignature(payload, header, secret, now, tolerance);
     const event = JSON.parse(new TextDecoder().decode(payload));
     switch (event.type) {
-        case "payment_intent.succeeded":
-            return oneEvent(decodePaymentIntent(event.data.object), State.Settled, "");
+        case "payment_intent.succeeded": {
+            // The webhook is signed by Stripe, so its amounts are authentic. A capture for
+            // less than the authorized amount must not settle the corridor as fully paid.
+            const pi = decodePaymentIntent(event.data.object);
+            if (pi.amountReceived < pi.amount) {
+                return oneEvent(pi, State.Failed, "captured amount is less than the authorized amount");
+            }
+            return oneEvent(pi, State.Settled, "");
+        }
         case "payment_intent.payment_failed":
             return oneEvent(decodePaymentIntent(event.data.object), State.Failed, "payment failed");
         case "charge.refunded":
@@ -244,13 +251,19 @@ function parseEvent(payload, header, secret, now, tolerance) {
 }
 function decodePaymentIntent(raw) {
     const obj = raw;
-    return { id: obj.id ?? "", metadata: obj.metadata ?? {}, created: obj.created ?? 0 };
+    return {
+        id: obj.id ?? "",
+        metadata: obj.metadata ?? {},
+        created: obj.created ?? 0,
+        amount: obj.amount ?? 0,
+        amountReceived: obj.amount_received ?? 0,
+    };
 }
 // decodeRefundedIntent reads the pact intent id off a refunded charge. A charge
 // carries the originating PaymentIntent id and copies its metadata.
 function decodeRefundedIntent(raw) {
     const charge = raw;
-    return { id: charge.payment_intent ?? "", metadata: charge.metadata ?? {}, created: charge.created ?? 0 };
+    return { id: charge.payment_intent ?? "", metadata: charge.metadata ?? {}, created: charge.created ?? 0, amount: 0, amountReceived: 0 };
 }
 function oneEvent(pi, state, reason) {
     return [
@@ -341,7 +354,7 @@ class HttpStripeApi {
     }
     async send(path, init) {
         const headers = {
-            ...(init.headers ?? {}),
+            ...init.headers,
             Authorization: `Bearer ${this.secretKey}`,
             "Stripe-Version": apiVersion,
         };

package/dist/src/canonical.js

@@ -51,6 +51,8 @@ export class CanonicalWriter {
     // byte value so the encoding never depends on insertion order. The sort is on
     // encoded bytes, not on UTF-16 code units, to match the other SDKs exactly.
     stringMap(kv) {
+        // Object.keys returns a fresh array, so sorting it in place mutates nothing shared.
+        // oxlint-disable-next-line unicorn/no-array-sort
         const keys = Object.keys(kv).sort(compareUtf8);
         this.u64(keys.length);
         for (const k of keys) {

package/dist/src/client.d.ts

@@ -65,6 +65,7 @@ export declare class Client {
     private pickBridge;
     select(quotes: Quote[], identity: string): Promise<Quote>;
     authorize(intent: Intent, quote: Quote, signer: Signer): Promise<Authorization>;
+    private resolvePayIn;
     initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State>;
     interactiveInitiate(intent: Intent, quote: Quote, auth: Authorization): Promise<{
         preparation: PayInPreparation;
@@ -76,6 +77,7 @@ export declare class Client {
     }>;
     private holdAndDisburse;
     private settleBridged;
+    private claimRefund;
     private unwind;
     refund(intentId: string, amount: Money, reason: string): Promise<{
         settlement: Settlement;

package/dist/src/client.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { State } from "./state.js";
+import { State, stateName } from "./state.js";
 import { Money } from "./money.js";
 import { DEFAULT_SKEW_MILLIS, domain } from "./protocol.js";
 import { CanonicalWriter, hashPreimage } from "./canonical.js";
@@ -98,6 +98,9 @@ export class Client {
                 continue;
             }
             try {
+                // Corridors are priced in order so the router sees a stable ranking, matching
+                // the other SDKs; the loop is bounded by the configured funding options.
+                // eslint-disable-next-line no-await-in-loop
                 quotes.push(await this.composeQuote(intent, payInLeg, f));
             }
             catch (err) {
@@ -223,11 +226,9 @@ export class Client {
     // driven forward by advance as provider events arrive, so no promise or
     // connection is held open per payment and durable state lives only in the
     // ledger.
-    async initiate(intent, quote, auth) {
-        verifyAuthorization(auth, intent, quote, this.verifier);
-        if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
-            throw new Error("pact: signer is not authorized to act for the intent's sender");
-        }
+    // resolvePayIn rejects an expired intent and returns the corridor's pay-in leg — the
+    // expiry-and-leg check the immediate and interactive starts share.
+    resolvePayIn(intent, quote) {
         if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
             throw new Error("pact: intent has expired");
         }
@@ -235,12 +236,26 @@ export class Client {
         if (!payInLeg) {
             throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
         }
+        return payInLeg;
+    }
+    async initiate(intent, quote, auth) {
+        verifyAuthorization(auth, intent, quote, this.verifier);
+        if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
+            throw new Error("pact: signer is not authorized to act for the intent's sender");
+        }
+        const payInLeg = this.resolvePayIn(intent, quote);
         // A retry of an already-submitted corridor must not collect a second time. The
         // pay-in leg carries its own provider idempotency for the narrow window where a
         // collection completed but its record was lost.
-        const submitted = this.ledger.state(intent.id);
-        if (submitted === State.Submitted || submitted === State.Collecting) {
-            return submitted;
+        const current = this.ledger.state(intent.id);
+        if (current === State.Submitted || current === State.Collecting) {
+            return current;
+        }
+        // Collection may only start from an authorized intent. Without this a replayed
+        // or out-of-order call would charge the payer through collect before the ledger
+        // rejected the transition, so the guard is enforced before any money moves.
+        if (current !== State.Authorized) {
+            throw new Error(`pact: cannot initiate an intent in state ${stateName[current]}; it must be authorized first`);
         }
         // A direct corridor collects straight to the recipient; a bridged one
         // collects into escrow first.
@@ -269,16 +284,16 @@ export class Client {
         if (!isDirect(quote)) {
             throw new Error("pact: interactive pay-in is only available on a direct corridor");
         }
-        if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
-            throw new Error("pact: intent has expired");
-        }
-        const payInLeg = this.payIn.get(quote.payInAdapterId);
-        if (!payInLeg) {
-            throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
-        }
+        const payInLeg = this.resolvePayIn(intent, quote);
         if (!isInteractivePayInLeg(payInLeg)) {
             throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} does not offer interactive collection`);
         }
+        // The provider intent may only be prepared from an authorized intent, so a
+        // replayed or out-of-order call cannot open a second collection.
+        const current = this.ledger.state(intent.id);
+        if (current !== State.Authorized) {
+            throw new Error(`pact: cannot initiate an intent in state ${stateName[current]}; it must be authorized first`);
+        }
         const preparation = await payInLeg.prepare(intent.id, quote, auth, recipientDestination(intent));
         // Record the same shape a direct collection would, so the confirming webhook
         // advances the corridor to settled through the unchanged pay-in path.
@@ -335,6 +350,31 @@ export class Client {
                 return this.unwind(intentId, quote, authHash, event.reason);
             return this.settleBridged(intentId, quote, authHash, events);
         }
+        // A refund reported out of band — an operator refunds in the provider's
+        // dashboard, say — is recorded against the settled intent so the ledger matches
+        // where the money actually is. The provider has already returned the funds, so
+        // this only claims the refunding step (once, so a duplicate webhook is a no-op)
+        // and records the refunded outcome; it moves no money itself.
+        if (event.state === State.Refunded && current === State.Settled) {
+            const { created } = this.ledger.apply({
+                intentId,
+                to: State.Refunding,
+                payloadHash: hashString(domain("refunding"), event.reason),
+            });
+            if (!created)
+                return { settlement: lastSettlement(events), state: this.ledger.state(intentId) };
+            const settlement = {
+                intentId,
+                state: State.Refunded,
+                adapterId,
+                providerTxRef: event.providerTxRef,
+                onchainTxHash: "",
+                receiptHash: corridorReceipt(authHash, "", event.providerTxRef, quote.srcAmount, "", State.Refunded),
+                reason: event.reason,
+                settledAt: this.clock(),
+            };
+            return this.finishAdvance(intentId, State.Refunded, settlement);
+        }
         // Any other event — a duplicate webhook, or one for a phase already past — is
         // a no-op. This is what makes a re-delivered provider callback settle once.
         return { settlement: lastSettlement(events), state: current };
@@ -439,14 +479,29 @@ export class Client {
         };
         return this.finishAdvance(intentId, State.Settled, settlement);
     }
-    // unwind refunds the payer from escrow when a bridged corridor cannot complete
-    // its pay-out, moving to refunding then refunded.
-    async unwind(intentId, quote, authHash, reason) {
-        this.ledger.apply({
+    // claimRefund reserves the refunding step before any money moves. It returns the
+    // recorded outcome to echo when another refund already claimed the step, or null when
+    // this call won it and should proceed to move funds. Both refund paths go through it,
+    // so a refund is issued at most once however the calls race.
+    claimRefund(intentId, reason) {
+        const { created } = this.ledger.apply({
             intentId,
             to: State.Refunding,
             payloadHash: hashString(domain("refunding"), reason),
         });
+        if (created)
+            return null;
+        return { settlement: lastSettlement(this.ledger.events(intentId)), state: this.ledger.state(intentId) };
+    }
+    // unwind refunds the payer from escrow when a bridged corridor cannot complete
+    // its pay-out, moving to refunding then refunded.
+    async unwind(intentId, quote, authHash, reason) {
+        // Claim the refund before moving money. A duplicate pay-out-failed webhook enters
+        // unwind twice; only the call that wins the refunding step may issue the counter-
+        // transfer, so the refund cannot fire a second time.
+        const echo = this.claimRefund(intentId, reason);
+        if (echo)
+            return echo;
         const payInLeg = this.payIn.get(quote.payInAdapterId);
         if (payInLeg) {
             const kind = payInLeg.payInCapabilities().refunds;
@@ -513,6 +568,12 @@ export class Client {
             throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} cannot perform this refund`);
         }
         const authHash = authorizationHash(intentHash(intent), quoteHash(quote), auth.signerIdentity, auth.signedAt);
+        // Claim the refunding step before moving money. Two overlapping refund calls both
+        // pass the settled check above; only the one that wins this step issues the return,
+        // so the payer is never refunded twice.
+        const echo = this.claimRefund(intentId, reason);
+        if (echo)
+            return echo;
         await payInLeg.refundIn(intentId, kind, amount, reason);
         const settlement = {
             intentId,

package/dist/src/message.d.ts

@@ -1,5 +1,6 @@
 import { Money } from "./money.js";
 import { State } from "./state.js";
+import { CanonicalWriter } from "./canonical.js";
 export interface Intent {
     id: string;
     senderRef: string;
@@ -29,6 +30,7 @@ export interface Quote {
     providerQuoteRef: string;
     latencyEstimateMs: number;
 }
+export declare function writeQuoteFields(w: CanonicalWriter, q: Quote): CanonicalWriter;
 export declare function quotePreimage(q: Quote): Uint8Array;
 export declare function quoteHash(q: Quote): Uint8Array;
 export declare function isDirect(q: Quote): boolean;