@zkp2p/zkp2p-attestation 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.5.0
+
+- Change Venmo identity registration to require the captured stories URL in session material. Venmo identity session material now requires `url`, `params` only requires `SENDER_ID`, and `params.SENDER_ID` must match the URL `externalId`.
+- Require `callerAddress` on identity attestation requests and bind it into the signed `IdentityAttestation`; `verifyIdentityAttestation` now requires `expectedCallerAddress`.
+
+## 1.4.0
+
+- Add typed identity flow helpers: `encryptIdentitySessionMaterial`, `createEncryptedIdentitySessionMaterial`, and `requestIdentityAttestation`.
+- Add response signature verifiers for all TEE flows: `verifyBuyerTeePaymentAttestation`, `verifyIdentityAttestation`, and `verifySellerCredentialBundle`.
+- Require caller-provided intent/payee bindings in response verifiers so valid same-domain attestations cannot be replayed for the wrong buyer intent, identity, or seller credential.
+- Export `getUnifiedPaymentVerifierDomainSeparator` and `hashUtf8` so consumers can pin the EIP-712 domain and compute expected payee hashes.
+- Add identity platform/action/params typing for Venmo, PayPal, and Wise. Wrong platform/action pairings now fail at TypeScript compile time.
+- Keep buyer TEE's per-platform param typing and add identity param typing. Seller credential upload keeps its existing Wise-vs-payee-id platform narrowing while leaving `sessionMaterial` flexible because each seller platform can accept multiple credential sources.
+- Move `ethers` to runtime dependencies because public response verifiers recover EIP-712 signers.
+
 ## 1.3.1
 
 - Republish of 1.3.0 from a clean build. The 1.3.0 tarball on npm shipped a stale `dist/` (built from a pre-rebase checkout): the runtime `dist/index.cjs` still posted the legacy `metadata` field and the typings still exported `*BuyerTeeMetadata` / `BuyerTeeMetadataByPlatform`. The new server only accepts `params`, so consumers on 1.3.0 hit a 4xx on every buyer TEE verify call.

package/README.md

@@ -1,6 +1,6 @@
 # @zkp2p/zkp2p-attestation
 
-Client-side verifier and encryptor for ZKP2P Nitro seller credential uploads and buyer TEE session-material requests.
+Client-side verifier and encryptor for ZKP2P Nitro identity attestations, seller credential uploads, and buyer TEE session-material requests.
 
 The package runs in Chrome MV3 service workers, browser DOM contexts, React Native with a Web Crypto polyfill, and Node >= 20. Library entrypoints use `fetch`, `SubtleCrypto`, `crypto.getRandomValues`, and `Uint8Array`; they do not import `node:*` modules or use `Buffer`.
 
@@ -64,8 +64,15 @@ const credentialBundle = await nitro.uploadSellerCredential({
   platform: "wise",
   sessionMaterial: {
     apiToken: "<wise-api-token>",
+    profileId: "41246868",
   },
 });
+
+const verifiedCredentialBundle = verifySellerCredentialBundle(credentialBundle, {
+  trustedSigners,
+  expectedPlatform: "wise",
+  expectedPayeeIdHash: hashUtf8("<wise-recipient-id>"),
+});
 ```
 
 Venmo, Cash App, and PayPal still require a top-level `payeeId`; existing callers can keep using the same call shape:
@@ -77,6 +84,10 @@ const encryptedUpload = await nitro.createEncryptedSellerCredentialUpload({
 });
 ```
 
+Venmo seller uploads can use either the existing session material or Google OAuth. For Google OAuth, pass the numeric Venmo account id as `payeeId` and use `sessionMaterial: { credentialSource: "google_oauth", authorizationCode, redirectUri }`; the service validates Gmail access against venmo.com DKIM-signed incoming payment receipts. To onboard through a partner-owned Google OAuth app instead of Peer's default app, include `oauthClient: { clientId, clientSecret }` inside that encrypted `sessionMaterial`. The client secret is seller credential material: the package only places it in the compact JWE upload plaintext, it reaches the service enclave through that JWE, and the service persists it only inside the KMS-envelope-sealed seller credential bundle that the curator holds as ciphertext. It rides the same encrypted credential envelope as the Gmail refresh token and is reused only for later Gmail token refresh.
+
+PayPal Gmail OAuth seller uploads use the same app-selection model. Pass the seller PayPal email as `payeeId` and use `sessionMaterial: { credentialSource: "google_oauth", authorizationCode, redirectUri }`; the service validates Gmail access against paypal.com DKIM-signed payment receipts. To onboard through a partner-owned Google OAuth app, include `oauthClient: { clientId, clientSecret }` inside the encrypted `sessionMaterial`. The PayPal partner client secret is handled as seller credential material: it rides only in the compact JWE upload plaintext, is sealed with the Gmail refresh token in the KMS-envelope seller credential bundle, and is reused only to refresh that seller's Gmail access token.
+
 Buyer TEE requests use the same attested upload key and compact JWE envelope. The typed helper encrypts the captured
 session material, posts `{ encryptedSessionMaterial, params, chainId, intent }` to
 `POST /buyer/verify/:platform/:actionType`, unwraps the service envelope, and returns a typed `AttestationOutput`.
@@ -93,10 +104,18 @@ const attestation = await nitro.verifyBuyerTeePayment({
     Cookie: "<captured-cookie-header>",
     "User-Agent": "<captured-user-agent>",
   },
-  params: { senderId: "<venmo-account-id>", index: 0 },
+  params: { SENDER_ID: "<venmo-account-id>", index: 0 },
   chainId,
   intent,
 });
+
+const verifiedAttestation = verifyBuyerTeePaymentAttestation(attestation, {
+  trustedSigners,
+  expectedPlatform: "venmo",
+  expectedActionType: "transfer_venmo",
+  expectedDomain: { chainId, verifyingContract },
+  expectedIntentHash: intent.intentHash,
+});
 ```
 
 The helper is a thin wrapper over the existing wire format; callers can still hand-roll the final POST:
@@ -113,7 +132,7 @@ await fetch(`${attestationServiceUrl}/buyer/verify/wise/transfer_wise`, {
   headers: { "content-type": "application/json" },
   body: JSON.stringify({
     encryptedSessionMaterial,
-    params: { profileId: "41246868", transactionId: "123456789" },
+    params: { PROFILE_ID: "41246868", TRANSACTION_ID: "123456789" },
     chainId,
     intent,
   }),
@@ -124,26 +143,69 @@ Buyer TEE platform matrix:
 
 | Platform | `actionType` | Required encrypted session material | Public params fields |
 |---|---|---|---|
-| `venmo` | `transfer_venmo` | `Cookie` | `senderId`, `index` |
-| `cashapp` | `transfer_cashapp` | `Cookie`, `x-csrf-token`, `x-device-name`, `x-request-signature`, `x-request-uuid`, `cash-web-request`, `x-web-device-info`, `x-web-context`, `x-bt-id` | `senderId`, `index` |
-| `luxon` | `transfer_luxon` | `X-Auth-Token` | `transferId` |
-| `monzo` | `transfer_monzo` | `Authorization` | `txId` |
-| `n26` | `transfer_n26` | `Cookie`, `csrf-token`, `body` | `{}` |
-| `wise` | `transfer_wise` | `Cookie` or `X-Access-Token` | `profileId`, `transactionId` |
+| `venmo` | `transfer_venmo` | `Cookie` | `SENDER_ID`, `index` |
+| `cashapp` | `transfer_cashapp` | `Cookie`, `x-csrf-token`, `x-device-name`, `x-request-signature`, `x-request-uuid`, `cash-web-request`, `x-web-device-info`, `x-web-context`, `x-bt-id` | `SENDER_ID`, `index` |
+| `monzo` | `transfer_monzo` | `Authorization` | `TX_ID` |
+| `wise` | `transfer_wise` | `Cookie` or `X-Access-Token` | `PROFILE_ID`, `TRANSACTION_ID` |
 | `revolut` | `transfer_revolut` | `Cookie`, `x-device-id` | `index` |
-| `idfc` | `transfer_idfc` | `Cookie` | `senderId`, `index` |
 | `citi` | `transfer_zelle` | `Cookie` | `index` |
 | `chime` | `transfer_chime` | `Cookie`, `body` | `{}` |
 | `chase` | `transfer_zelle` | `Cookie`, `x-jpmc-channel`, `x-jpmc-csrf-token`, `Referer`, `Origin` | `index` |
 | `bankofamerica` | `transfer_zelle` | `Cookie` | `index` |
-| `mercadopago` | `transfer_mercadopago` | `Cookie` | `paymentId`, `urlParamsFrom` |
-| `paypal` | `transfer_paypal` | `Cookie` | `index` |
-| `alipay` | `transfer_alipay` | `Cookie` | `tradeNo` |
+| `paypal` | `transfer_paypal` | `Cookie` | `PAYMENT_ID` |
 
 Per-platform session-material types require these headers using the canonical names shown above while still allowing
 additional captured headers. Captured request bodies are session material because they can contain sensitive data and
 are encrypted before being sent to the service.
 
+Identity requests use the same attested upload key and compact JWE plaintext shape as buyer TEE, but with a narrower
+platform/action matrix. The typed helper encrypts captured session material, posts
+`{ platform, actionType, callerAddress, encryptedSessionMaterial, params }` to `POST /identity`, unwraps the service response, and
+returns an `IdentityAttestationOutput`. `verifyIdentityAttestation` checks the EIP-712 signature, trusted signer,
+platform/action binding, expected caller address, expected payee hash, canonical identity `dataHash`, and `validUntil`,
+then returns normalized identity details.
+
+```ts
+const identityPayload = await nitro.requestIdentityAttestation({
+  platform: "wise",
+  actionType: "register_wise",
+  callerAddress: "0x0000000000000000000000000000000000000002",
+  sessionMaterial: {
+    Cookie: "<captured-cookie-header>",
+    "X-Access-Token": "<captured-token>",
+  },
+  params: { PROFILE_ID: "41246868" },
+});
+
+const identity = verifyIdentityAttestation(identityPayload, {
+  trustedSigners,
+  expectedPlatform: "wise",
+  expectedActionType: "register_wise",
+  expectedCallerAddress: "0x0000000000000000000000000000000000000002",
+  expectedPayeeIdHash: hashUtf8("<wise-recipient-id>"),
+});
+// identity: { payeeIdHash, payeeId, username, metadata, ... }
+```
+
+Identity platform matrix:
+
+| Platform | `actionType` | Required encrypted session material | Public params fields |
+|---|---|---|---|
+| `venmo` | `register_venmo` | `url`, `Cookie` | `SENDER_ID` |
+| `paypal` | `register_paypal` | `Cookie` | `{}` |
+| `wise` | `register_wise` | `Cookie`, `X-Access-Token` | `PROFILE_ID` |
+
+For Venmo identity, pass the captured `https://account.venmo.com/api/stories?feedType=me&externalId=...` request URL
+inside encrypted `sessionMaterial.url`; the service validates that `params.SENDER_ID` matches the URL `externalId` and
+that Venmo returns a valid stories response with an explicit `stories` array.
+
+Buyer TEE and identity expose discriminated unions keyed by `platform` and `actionType`, including per-platform
+`params`, so invalid pairings fail during TypeScript compilation. Seller credential upload keeps its existing
+platform narrowing (`wise` derives payee id from the credential; Venmo, Cash App, and PayPal require `payeeId`) but
+does not add exhaustive `sessionMaterial` typing: each seller platform can accept multiple credential sources, such as
+cookie headers or Google OAuth with optional partner OAuth client material, and encoding all combinations would make
+the SDK brittle without improving the wire contract.
+
 ## Cache-Friendly Path
 
 ```ts
@@ -171,6 +233,19 @@ const encryptedSessionMaterial = await nitro.encryptBuyerTeeSessionMaterial({
 });
 ```
 
+For identity flows with a cached attestation:
+
+```ts
+const encryptedSessionMaterial = await nitro.encryptIdentitySessionMaterial({
+  key: verified.attestedSellerUploadKey,
+  platform: "paypal",
+  actionType: "register_paypal",
+  sessionMaterial: {
+    Cookie: "<captured-cookie-header>",
+  },
+});
+```
+
 The attested SPKI is stable within one enclave process. If the enclave restarts, cached keys become stale and upload decrypt will fail; fetch a fresh attestation for a new session.
 
 ## React Native Wiring
@@ -193,12 +268,20 @@ Any conforming `SubtleCrypto` works. The package does not require `Buffer`.
 ```ts
 import {
   createEncryptedBuyerTeeSessionMaterial,
+  createEncryptedIdentitySessionMaterial,
   createEncryptedSellerCredentialUpload,
   encryptBuyerTeeSessionMaterial,
+  encryptIdentitySessionMaterial,
   encryptSellerCredentialUpload,
   fetchAndVerifyAttestation,
+  getUnifiedPaymentVerifierDomainSeparator,
+  hashUtf8,
+  requestIdentityAttestation,
   uploadSellerCredential,
+  verifyBuyerTeePaymentAttestation,
   verifyBuyerTeePayment,
+  verifyIdentityAttestation,
+  verifySellerCredentialBundle,
 } from "@zkp2p/zkp2p-attestation";
 ```
 

package/dist/cli/verify.js

@@ -4672,7 +4672,7 @@ Options:
   --expected-pcr8 <hex>       Strict PCR8 pin
   --expected-signer <addr>    Strict signer pin for --verify-signature
   --expected-verifying-contract <addr>  Strict verifyingContract pin
-  --verify-signature <path>   Optional path to a prior /verify or /seller/verify JSON response
+  --verify-signature <path>   Optional path to a prior buyer or seller verify JSON response
   --help                      Show this help text
 `);
 }