@myzonerocks/pact 0.1.6 → 0.1.7

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.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";
@@ -247,9 +247,15 @@ export class Client {
         // 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.
@@ -282,6 +288,12 @@ export class Client {
         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.
@@ -338,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 };

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;

package/dist/src/message.js

@@ -20,9 +20,11 @@ export function intentHash(i) {
 // The bridge that moves value unchanged when the payer and recipient already
 // share a currency. Its identifier is a stable wire value carried in a quote.
 export const BRIDGE_PASSTHROUGH = "passthrough";
-export function quotePreimage(q) {
-    return new CanonicalWriter()
-        .str(domain("quote"))
+// writeQuoteFields appends a quote's fields to a writer in the one canonical order
+// shared by the signing preimage and the wire codec. The two callers differ only in
+// what frames the fields: the preimage prepends a domain tag, the wire form does not.
+export function writeQuoteFields(w, q) {
+    return w
         .str(q.id)
         .str(q.intentId)
         .str(q.payInAdapterId)
@@ -36,8 +38,11 @@ export function quotePreimage(q) {
         .str(q.fxRate)
         .u64(q.expiresAt)
         .str(q.providerQuoteRef)
-        .u64(q.latencyEstimateMs)
-        .preimage();
+        .u64(q.latencyEstimateMs);
+}
+export function quotePreimage(q) {
+    const w = new CanonicalWriter().str(domain("quote"));
+    return writeQuoteFields(w, q).preimage();
 }
 export function quoteHash(q) {
     return hashPreimage(quotePreimage(q));

package/dist/src/wire.js

@@ -1,6 +1,7 @@
 import { Money } from "./money.js";
 import { stateName } from "./state.js";
 import { CanonicalWriter } from "./canonical.js";
+import { writeQuoteFields } from "./message.js";
 // The wire codec serializes messages for transport. It is distinct from the
 // canonical signing preimage: signing binds a fixed subset of fields under a
 // domain tag, while the wire form carries every field so a peer can reconstruct
@@ -27,22 +28,7 @@ export function encodeIntent(i) {
         .preimage();
 }
 export function encodeQuote(q) {
-    return new CanonicalWriter()
-        .str(q.id)
-        .str(q.intentId)
-        .str(q.payInAdapterId)
-        .str(q.payInRail)
-        .str(q.payOutAdapterId)
-        .str(q.payOutRail)
-        .str(q.bridgeId)
-        .money(q.srcAmount)
-        .money(q.dstAmount)
-        .money(q.fees)
-        .str(q.fxRate)
-        .u64(q.expiresAt)
-        .str(q.providerQuoteRef)
-        .u64(q.latencyEstimateMs)
-        .preimage();
+    return writeQuoteFields(new CanonicalWriter(), q).preimage();
 }
 export function encodeAuthorization(a) {
     return new CanonicalWriter()

package/dist/test/initiate-guard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/initiate-guard.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { Client } from "../src/client.js";
+import { Money } from "../src/money.js";
+import { State } from "../src/state.js";
+import { FakeLeg } from "./fake.js";
+import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
+import { fromHex } from "../src/crypto.js";
+// Initiate may only collect from an authorized intent. This guards against a
+// replayed or out-of-order call charging the payer a second time, matching the
+// same guard in the Go, Dart, Swift, and Kotlin SDKs.
+describe("initiate state guard", () => {
+    it("refuses to initiate from any state but authorized", async () => {
+        const now = 1_700_000_000_000;
+        const seed = fromHex("00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff");
+        const signer = Ed25519Signer.fromSeed("alice", seed);
+        const verifier = new Ed25519Verifier(new Map([["alice", signer.publicKey]]));
+        let n = 0;
+        const ids = () => `id-${String(++n).padStart(3, "0")}`;
+        const wallet = new FakeLeg("wallet", "wallet", "USD", ids);
+        const client = new Client({ payIn: [wallet], payOut: [wallet], verifier, clock: () => now, idGen: ids });
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("USD", 2, "1500"),
+            expiresAt: now + 600_000,
+            allowedRails: ["wallet"],
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "wallet", currency: "USD", exponent: 2 }]);
+        const quote = await client.select(quotes, signer.identity());
+        // Before authorizing, the intent is only quoted, so initiate is refused.
+        await expect(client.initiate(intent, quote, { intentId: intent.id })).rejects.toThrow();
+        const auth = await client.authorize(intent, quote, signer);
+        await client.initiate(intent, quote, auth);
+        await client.advance(intent.id, "wallet", { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 });
+        // Once settled, a replayed initiate must not collect again.
+        await expect(client.initiate(intent, quote, auth)).rejects.toThrow();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myzonerocks/pact",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "TypeScript SDK for the PACT payment abstraction protocol",
   "license": "Apache-2.0",
   "repository": {

package/src/adapters/stripe.ts

@@ -353,8 +353,15 @@ function parseEvent(
   const event = JSON.parse(new TextDecoder().decode(payload)) as StripeEvent;
 
   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":
@@ -368,18 +375,26 @@ interface WebhookIntent {
   id: string;
   metadata: Record<string, string>;
   created: number;
+  amount: number;
+  amountReceived: number;
 }
 
 function decodePaymentIntent(raw: unknown): WebhookIntent {
-  const obj = raw as { id?: string; metadata?: Record<string, string>; created?: number };
-  return { id: obj.id ?? "", metadata: obj.metadata ?? {}, created: obj.created ?? 0 };
+  const obj = raw as { id?: string; metadata?: Record<string, string>; created?: number; amount?: number; amount_received?: number };
+  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: unknown): WebhookIntent {
   const charge = raw as { payment_intent?: string; metadata?: Record<string, string>; created?: number };
-  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: WebhookIntent, state: State, reason: string): AdapterEvent[] {
@@ -483,7 +498,7 @@ class HttpStripeApi implements StripeApi {
 
   private async send<T>(path: string, init: RequestInit): Promise<T> {
     const headers: Record<string, string> = {
-      ...((init.headers as Record<string, string>) ?? {}),
+      ...(init.headers as Record<string, string> | undefined),
       Authorization: `Bearer ${this.secretKey}`,
       "Stripe-Version": apiVersion,
     };

package/src/canonical.ts

@@ -61,6 +61,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: Readonly<Record<string, string>>): this {
+    // 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/src/client.ts

@@ -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";
@@ -315,9 +315,15 @@ export class Client {
     // 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
@@ -352,6 +358,12 @@ export class Client {
     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.
@@ -410,6 +422,31 @@ export class Client {
       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: 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 };

package/src/message.ts

@@ -60,9 +60,11 @@ export interface Quote {
   latencyEstimateMs: number;
 }
 
-export function quotePreimage(q: Quote): Uint8Array {
-  return new CanonicalWriter()
-    .str(domain("quote"))
+// writeQuoteFields appends a quote's fields to a writer in the one canonical order
+// shared by the signing preimage and the wire codec. The two callers differ only in
+// what frames the fields: the preimage prepends a domain tag, the wire form does not.
+export function writeQuoteFields(w: CanonicalWriter, q: Quote): CanonicalWriter {
+  return w
     .str(q.id)
     .str(q.intentId)
     .str(q.payInAdapterId)
@@ -76,8 +78,12 @@ export function quotePreimage(q: Quote): Uint8Array {
     .str(q.fxRate)
     .u64(q.expiresAt)
     .str(q.providerQuoteRef)
-    .u64(q.latencyEstimateMs)
-    .preimage();
+    .u64(q.latencyEstimateMs);
+}
+
+export function quotePreimage(q: Quote): Uint8Array {
+  const w = new CanonicalWriter().str(domain("quote"));
+  return writeQuoteFields(w, q).preimage();
 }
 
 export function quoteHash(q: Quote): Uint8Array {

package/src/wire.ts

@@ -1,6 +1,7 @@
 import { Money } from "./money.js";
 import { State, stateName } from "./state.js";
 import { CanonicalWriter } from "./canonical.js";
+import { writeQuoteFields } from "./message.js";
 import type { Intent, Quote, Authorization, Settlement } from "./message.js";
 
 // The wire codec serializes messages for transport. It is distinct from the
@@ -32,22 +33,7 @@ export function encodeIntent(i: Intent): Uint8Array {
 }
 
 export function encodeQuote(q: Quote): Uint8Array {
-  return new CanonicalWriter()
-    .str(q.id)
-    .str(q.intentId)
-    .str(q.payInAdapterId)
-    .str(q.payInRail)
-    .str(q.payOutAdapterId)
-    .str(q.payOutRail)
-    .str(q.bridgeId)
-    .money(q.srcAmount)
-    .money(q.dstAmount)
-    .money(q.fees)
-    .str(q.fxRate)
-    .u64(q.expiresAt)
-    .str(q.providerQuoteRef)
-    .u64(q.latencyEstimateMs)
-    .preimage();
+  return writeQuoteFields(new CanonicalWriter(), q).preimage();
 }
 
 export function encodeAuthorization(a: Authorization): Uint8Array {