@atumlabs/payment-gateway-client 3.0.0 → 3.0.1

package/docs/idempotency.md

@@ -136,7 +136,8 @@ retry:
 | ---------------------- | --------------------------------- | ------------------------------------------------------ |
 | `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`.          |
 
 `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

package/docs/signing.md

@@ -0,0 +1,218 @@
+# 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 two names are confusingly close, and that is not an accident of this client: the upstream
+> library calls its document signer `signPaymentRequest` too. This package exports it as
+> `signDeclaration` so the two cannot be confused for one another, matching `SignDeclaration`
+> in the Go client.
+
+## 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. It does
+not check that the terms inside those messages are the ones you agreed to, and neither does the
+Go client — the same is true of building the request in the first place, because the permit's
+spender, escrow and amounts come from the gateway's chain defaults.
+
+That is a deliberate division of labour, not an oversight: the SDK holds no notion of what you
+intended. But it means a gateway that returned hostile defaults would have your wallet sign a
+permit naming an address you never chose, and nothing in the signing path would object.
+
+If you are signing on behalf of someone else's funds, 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 actually 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 a CAIP-19 identifier — it differs in shape from
+the request's own `source.asset_identifier`, which is full CAIP-19. Passing the CAIP form here
+fails to match and rejects a request that was in fact correct.
+
+**Pass those three fields.** Called bare, `verifyPaymentRequest` takes the token, network and
+amount *from the request itself*, so it proves only that the signatures are self-consistent with
+the request's own stated fields — which a hostile gateway controls. It is the `sourceAsset` /
+`network` / `maxSourceAmount` arguments that turn it into a check against your terms, and
+omitting them is the difference between a real check and a reassuring one.
+
+It is strict by design: every entry must be a bindable permit, and a malformed one throws rather
+than being skipped. A caller with deliberately mixed messages — say an EVM setup approval
+alongside the permit — must compose the per-entry adapter calls itself and own the skip policy.
+
+In Go, `senderauth.GetChainAdapter(caip2).RecoverAndVerify(signed, source, expected)` returns the
+same signed terms for the same comparison.
+
+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.
+
+One precision, because this page is about what your signatures cover: the embedded copies can be
+overridden by an environment variable intended for development against a modified snapshot. It
+reads from local disk, never the network, and nothing in normal operation sets it — but if it is
+set, the library now says so on first use rather than substituting the contexts silently.
+
+This is structural: 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.
+
+## The identity envelope
+
+**Read this before the example: you need an issuer-signed credential about yourself, and
+originators do not hold one yet.** The schema requires at least one credential and rejects an
+empty bag, so until issuance exists this surface cannot be exercised end to end. It
+is documented because the shape is stable and the signing half is done, not because it is
+callable today.
+
+`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.** The schema requires it and an empty bag is rejected — see the
+  prerequisite above.
+- **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,6 +1,6 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "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",
@@ -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",
@@ -50,15 +61,18 @@
     "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",
     "tweetnacl": "^1.0.3",
     "zod": "^3.25.0"
   },
@@ -66,6 +80,8 @@
     "@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:*",
@@ -90,11 +106,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');