@atumlabs/payment-gateway-client 3.0.0 → 4.0.0

package/docs/idempotency.md

@@ -129,21 +129,24 @@ altogether is from a gateway predating it.
 
 ## Reading the outcome (payments)
 
-`status` is on every payment response, and the three endings mean different things for a
-retry:
+`status` is on every payment response, and its endings mean different things for a retry:
 
 | `status`               | What it means                     | What to do                                             |
 | ---------------------- | --------------------------------- | ------------------------------------------------------ |
 | `completed`            | Settled.                          | Nothing. `fulfillment_confirmation` carries the proof. |
 | `pending`              | Accepted, still settling.         | Re-submit the **same** `request_id`, or read the status endpoint. Do not start a new payment. |
-| `failed` / `cancelled` | Terminal — it can never complete. | A fresh attempt needs a **new** `request_id`.          |
+| `finalizing`           | Paid on chain, collecting confirmations. Not final. | As `pending`. Do not treat it as delivered. |
+| `failed`               | Terminal — it can never complete. | A fresh attempt needs a **new** `request_id`.          |
+| `refunding`            | Not delivered, the escrowed funds are being returned. Not final. | As `pending`. |
+| `refund_available`     | Not delivered, funds still in escrow. The status endpoint returns `refund_signature`. Not final. | Submit `refund_signature` to the source escrow to return the funds. Do not start a new payment until it is `refunded`: a late delivery can still complete it. |
+| `refunded`             | Terminal, not delivered. The funds were returned. | A fresh attempt needs a **new** `request_id`. |
 
 `pending` is not success. Cross-chain settlement can outrun the gateway's
 synchronous window, so a payment that has been accepted may still have no result
 when you get your response.
 
-A terminal failure **keeps** its `request_id`. Re-submitting that id returns the
-same failed payment for good, which is why recovering from one means minting a
+A terminal payment **keeps** its `request_id`. Re-submitting that id returns the
+same payment for good, which is why recovering from one means minting a
 new id — the opposite of what a pending payment needs. Getting these two the
 wrong way round is how a caller either pays twice or waits for something that
 will never happen.

package/docs/signing.md

@@ -0,0 +1,221 @@
+# Signing a PaymentRequest
+
+A PaymentRequest carries **three unrelated signatures**. They are produced by different calls,
+cover different things, and none substitutes for another. Choosing the wrong one is the mistake
+this page exists to prevent.
+
+| What you are signing | Call | What it authorizes |
+|---|---|---|
+| `sender_auth.signed_messages[]` | `signPaymentRequest` | the on-chain **transfer** |
+| the document's `proof` | `signDeclaration` | that the **document** came from its signer |
+| `presentation` | `buildEnvelope` | the **originator's identity** |
+
+A request with a valid `sender_auth` and no identity envelope authorizes a transfer by an
+unidentified originator. The reverse identifies an originator who has authorized nothing. Most
+integrations need the first two; the third applies once the originator holds credentials about
+itself.
+
+> The underlying declaration library also names its document signer `signPaymentRequest`. This
+> package exports it as `signDeclaration`, matching `SignDeclaration` in the Go client, so the two
+> cannot be confused.
+
+## Keys never reach this package
+
+Every signing surface takes a **signer**, not a private key:
+
+```ts
+export interface DeclarationSigner {
+  getAddress(): Promise<string> | string;
+  signDigest(digest: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+```
+
+That is deliberate. A hex key forces raw key material into a JavaScript string, which cannot be
+zeroized, is copied on assignment, and lands in heap snapshots and any log line that stringifies
+the surrounding object. It also excludes every custodian: a holder whose key sits in a KMS, an
+HSM, or a provider like Turnkey has no key to hand over.
+
+For a local key, use ethers — a library built to hold keys:
+
+```ts
+import { Wallet } from 'ethers';
+import { signerFromEthersWallet } from '@atum-labs/payment-gateway-client/signing';
+
+const signer = signerFromEthersWallet(new Wallet(process.env.PRIVATE_KEY!));
+```
+
+For a custodian, implement the interface over its own digest-signing call — `buildEnvelope`
+needs only `signDigest`. Two details the implementation must get right:
+
+- **Sign the raw digest.** Not `signMessage` — that applies the EIP-191 prefix, and the
+  resulting signature will not verify as a Data Integrity proof.
+- **Return `v ∈ {0, 1}`.** The `+27` alignment is applied once downstream. A signature whose `v`
+  is already 27 or 28 is **refused**, because applying it twice recovers a *different* address:
+  a well-formed signature that verifies as somebody else.
+
+## Signing both surfaces
+
+```ts
+import { Wallet } from 'ethers';
+import {
+  PaymentGatewayClient,
+  signPaymentRequest,     // transfer authorization — lives at the package root
+  createSenderSigner,
+} from '@atum-labs/payment-gateway-client';
+import {
+  signDeclaration,        // document proof — the signing surface is its own subpath
+  signerFromEthersWallet,
+} from '@atum-labs/payment-gateway-client/signing';
+
+const wallet = new Wallet(process.env.PRIVATE_KEY!);
+
+// 1. Authorize the transfer. Fills every sender_auth.signed_messages[] entry, and attaches
+//    payload.delegate_signer on chains whose signatures are not recoverable (Solana).
+const authorized = await signPaymentRequest(request, createSenderSigner(/* ... */));
+
+// 2. Attest the document.
+const signed = await signDeclaration(authorized, signerFromEthersWallet(wallet), { chainId: 1 });
+
+// 3. Submit.
+await new PaymentGatewayClient({ BASE: gateway }).payments.submitPayment({ requestBody: signed });
+```
+
+## Check what you are signing
+
+`signPaymentRequest` signs **every** entry in `sender_auth.signed_messages[]` as given, in both
+the TypeScript and Go clients. The permit's spender, escrow and amounts come from the gateway's
+chain defaults, and the signer has no notion of what you intended.
+
+Bind the signed permit to the terms **you** agreed before the request leaves your process.
+`verifyPaymentRequest` recovers every `signed_messages[]` entry and checks the terms it commits
+to:
+
+```ts
+import { verifyPaymentRequest } from '@atum-labs/payment-gateway-client/signing';
+
+// Sign locally, then bind the result to your own terms before submitting.
+const { recoveredAccount } = verifyPaymentRequest(signed, {
+  sourceAsset: agreedTokenAddress,
+  network: 'eip155:1',
+  maxSourceAmount: agreedMaxAmount,
+});
+```
+
+`sourceAsset` is the **bare token address**, not the CAIP-19 identifier used in the request's
+`source.asset_identifier`. Passing the CAIP form fails to match.
+
+**Pass those three fields.** Without them, `verifyPaymentRequest` takes the token, network and
+amount from the request itself, which proves only that the signatures are consistent with the
+request's own fields.
+
+It always checks the payee: the deposit must commit to the request's own `destination` and
+`request_id`, so a request whose payee or request id was changed after signing is refused.
+
+If you hold the request as JSON text, call `verifyPaymentRequestJSON(json, expected)` instead. It
+also refuses a repeated member name, including names that differ only in letter case, where it is
+read: any top-level name, or inside `source`, `destination`, `request_id` or `sender_auth`.
+On a refusal, `commitmentResultOf(error)` returns the outcome (for example
+`destination_mismatch`) and both copies of the payee, ready to log. A verified entry carries the
+same result as `results[i].commitment`.
+
+**Contract-account payers.** `verifyPaymentRequest` recovers each signer, so it refuses a payer
+that is a contract account (ERC-1271, such as a Safe): its signature comes from an owner key, never
+from the account itself. For such a payer, call `verifyRequestCommitment(json)`. It checks the
+payee and request id the deposit commits to without recovering the signer; Permit2 checks the
+signature on chain when the deposit is made.
+
+Every entry must be a bindable permit; a malformed entry throws. A caller with mixed messages
+(for example an EVM setup approval alongside the permit) composes the per-entry adapter calls
+itself.
+
+In Go, `senderauth.VerifyRequestCommitment(raw, solanaDomain)` is the payee check alone,
+`senderauth.VerifyPaymentRequestJSON(raw, expected)` and
+`senderauth.VerifyPaymentRequest(request, expected)` run the same checks,
+`senderauth.CommitmentResultOf(err)` reads the outcome from an error, and
+`senderauth.GetChainAdapter(caip2).RecoverAndVerify(signed, source, commitment, expected)` checks
+one signed message against a `CommitmentExpectation` built from the request's `destination` and
+`request_id`.
+
+A custodial signer is the natural place to enforce this: it is the component that can refuse.
+
+## Verifying
+
+`verifyDeclaration` **throws** on an invalid proof rather than returning a flag — a boolean can
+be ignored by accident, an exception cannot. It also refuses a document whose signature recovers
+a signer other than the one the document claims, which is what makes a tampered document fail
+rather than verify as its original signer.
+
+It returns a **discriminated** signer:
+
+```ts
+const { signer } = await verifyDeclaration(signed);
+
+if (signer.kind === 'recovered-secp256k1') {
+  // The address was recovered FROM the signature: self-evident proof of which key signed.
+  console.log(signer.address);
+} else {
+  // Self-asserted: the ed25519 key came from the document itself. A successful verify proves
+  // the signature matches that key — NOT that the key belongs to anyone in particular. Bind it
+  // to a trusted source before relying on it.
+}
+```
+
+## What the proof does and does not cover
+
+The proof is computed over the **URDNA2015-canonicalized** document, so it is stable across key
+reordering and whitespace, and it excludes signing artifacts and the deprecated credential
+carriers.
+
+One consequence worth knowing: **canonicalization drops terms the declaration `@context` does not
+define.** A field this client's types do not model travels inside the signed document without
+being covered by the proof, and can be altered without invalidating it. Making a new field
+tamper-evident means adding it to the declaration context, not just to the payload.
+
+Any `@context` on the input is **replaced** before hashing, so a caller-supplied one cannot
+influence what gets signed.
+
+## Contexts are local, always
+
+JSON-LD contexts are compiled into the bundle. **Nothing is fetched over the network** — there is
+no HTTP client in the signing libraries, and the JSON-LD processor is always handed the local
+loader in place of its built-in fetcher. A document whose `@context` names an unregistered URL is
+refused rather than resolved, since an attacker-served context could otherwise change what each
+term means, and therefore what the signature covers.
+
+For development against a modified snapshot, an environment variable can override the embedded
+copies. It reads from local disk only, and the library reports it on first use when it is set.
+
+## The identity envelope
+
+**Prerequisite: at least one issuer-signed credential about the originator.** The schema rejects
+an envelope without one.
+
+`buildEnvelope` wraps the originator's issuer-signed credentials in a holder-signed
+PaymentRequestEnvelope. It takes the same kind of signer as the other surfaces, so a custodial
+key works here too.
+
+```ts
+import { buildEnvelopeForAccount, computeRequestHash, signerFromEthersWallet } from '@atum-labs/payment-gateway-client/signing';
+
+const envelope = await buildEnvelopeForAccount('eip155:1', wallet.address.toLowerCase(), {
+  holderVCs: [knownToAtumCredential],
+  signer: signerFromEthersWallet(wallet),
+  // The challenge is the request's content hash, which the gateway recomputes.
+  challenge: await computeRequestHash(request),
+  // The domain the gateway you are calling expects. It is compared exactly, so an envelope built
+  // for one environment is rejected by another, and it is NOT derived from the gateway URL —
+  // take it from that environment's configuration rather than assuming it.
+  domain: envelopeDomainForYourEnvironment,
+});
+```
+
+Three things the verifier enforces, so they are not optional:
+
+- **At least one credential.** An empty bag is rejected.
+- **The challenge binds one request** and **the domain binds one environment**. Both are checked
+  against the values the gateway expects, so an envelope cannot be replayed across either.
+- **The declaration type is bound into the signature**, not merely present in the document —
+  editing the `type` array does not make a PaymentRequestEnvelope pass where a FulfillmentQuoteEnvelope is expected.
+
+Sign the inner document with the **same key**: the gateway asserts the document's signer is
+the envelope's holder, and rejects the pair otherwise.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "TypeScript client for Atum Payment Gateway API",
   "author": "Atum Labs, Inc.",
-  "homepage": "https://github.com/Atum-Labs/protocol/tree/main/payment-gateway-client#readme",
+  "homepage": "https://github.com/Atum-Labs/protocol/tree/main/schemas/apis/payment-gateway/v1/bindings/payment-gateway-client#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Atum-Labs/protocol.git",
-    "directory": "payment-gateway-client"
+    "directory": "schemas/apis/payment-gateway/v1/bindings/payment-gateway-client"
   },
   "bugs": {
     "url": "https://github.com/Atum-Labs/protocol/issues"
@@ -31,6 +31,17 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./signing": {
+      "types": "./dist/signing.d.ts",
+      "default": "./dist/signing.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "send-payment": "./dist/cli/send-payment.js",
     "request-quote": "./dist/cli/request-quote.js",
@@ -39,9 +50,9 @@
     "approve-permit2": "./dist/cli/approve-permit2.js"
   },
   "scripts": {
-    "generate": "openapi-ts --input ../schemas/apis/payment-gateway/v1/openapi.yaml --output \"${PGC_GEN_OUT:-./src/generated}\" --client axios --name PaymentGatewayClient --useOptions",
+    "generate": "openapi-ts --input ../../openapi.yaml --output \"${PGC_GEN_OUT:-./src/generated}\" --client axios --name PaymentGatewayClient --useOptions",
     "lint": "eslint . --max-warnings 0",
-    "prebuild:deps": "node -e \"if(!require('fs').existsSync('../pnpm-workspace.yaml')){console.error('protocol workspace not found at ../pnpm-workspace.yaml. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
+    "prebuild:deps": "node -e \"if(!require('fs').existsSync('../../../../../../pnpm-workspace.yaml')){console.error('protocol workspace not found at ../../../../../../pnpm-workspace.yaml. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
     "build:deps": "pnpm --filter \"@atum-labs/payment-gateway-client^...\" run build",
     "build": "tsup && chmod +x dist/cli/*.js && node scripts/stamp-entry-headers.mjs",
     "typecheck:tests": "tsc -p tsconfig.test.json",
@@ -50,15 +61,19 @@
     "check:publishable": "node scripts/check-publishable.mjs",
     "gen:notices": "node scripts/gen-third-party-notices.mjs",
     "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run build && pnpm run check:publishable"
+    "prepublishOnly": "pnpm run build && pnpm run check:publishable",
+    "prebuild": "node scripts/gen-pre-context.mjs",
+    "check:pre-context": "node scripts/gen-pre-context.mjs --check"
   },
   "dependencies": {
     "@solana/web3.js": "^1.91.0",
-    "axios": "1.13.2",
+    "axios": "1.20.0",
     "bs58": "^6.0.0",
     "commander": "^12.0.0",
     "dotenv": "^16.6.1",
     "ethers": "^6.11.0",
+    "jsonld": "8.3.3",
+    "rdf-canonize": "3.4.0",
     "tweetnacl": "^1.0.3",
     "zod": "^3.25.0"
   },
@@ -66,9 +81,12 @@
     "@atum-labs/chain-address": "workspace:*",
     "@atum-labs/evm-escrow-encoding": "workspace:*",
     "@atum-labs/km-core": "workspace:*",
+    "@atum-labs/ld-signing": "workspace:*",
+    "@atum-labs/payment-request-ld-signing": "workspace:*",
     "@atum-labs/payment-request-sender-auth": "workspace:*",
     "@atum-labs/payment-request-token-approval": "workspace:*",
     "@atum-labs/publish-guard": "workspace:*",
+    "@atum-labs/schema-declarations": "workspace:*",
     "@atum-labs/solana-escrow-encoding": "workspace:*",
     "@atum-labs/turnkey-signer": "workspace:*",
     "@atum-labs/tvm-escrow-encoding": "workspace:*",
@@ -82,7 +100,7 @@
     "ts-jest": "^29.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.0.0",
-    "uuid": "^9.0.0"
+    "uuid": "^11.1.1"
   },
   "files": [
     "dist/**/*",
@@ -90,11 +108,14 @@
     "CHANGELOG.md",
     "docs/**",
     "LICENSE",
-    "THIRD-PARTY-NOTICES.txt"
+    "NOTICE",
+    "THIRD-PARTY-NOTICES.txt",
+    "signing.js",
+    "signing.d.ts"
   ],
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "Apache-2.0",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "peerDependencies": {
     "tronweb": "^6.0.0"

package/signing.d.ts

@@ -0,0 +1,2 @@
+// Types for the subpath shim. See signing.js for why both exist.
+export * from './dist/signing';

package/signing.js

@@ -0,0 +1,11 @@
+// Subpath shim for the classic Node resolution algorithm.
+//
+// package.json's "exports" map already declares "./signing", but `moduleResolution: "node"` —
+// still the default for plenty of consumers — does not read "exports" at all. It resolves
+// `@atum-labs/payment-gateway-client/signing` by looking for this file on disk. Without it the
+// subpath works under "node16"/"bundler" and fails everywhere else, which is a failure a
+// consumer meets at install rather than one we meet in CI.
+//
+// The publish guard caught exactly that: it type-checks against the packed tarball on the default
+// settings, and the import did not resolve until this existed.
+module.exports = require('./dist/signing.js');