@pafi-dev/issuer 0.29.0 → 0.31.0

package/dist/index.d.cts

@@ -1884,6 +1884,16 @@ interface PTRedeemHandlerConfig {
      * provisioning time. Typically HSM/KMS-backed in prod.
      */
     burnerSignerWallet: WalletClient;
+    /**
+     * Issuer's allow-listed PointToken contracts (checksummed EIP-55).
+     * Every `handle()` call validates the request's `pointTokenAddress`
+     * against this set BEFORE any chain read, signer call, or pending
+     * credit reservation.
+     * Pass the SAME set used to construct `IssuerApiHandlers` and
+     * `PTClaimHandler` so the read, claim, and redeem paths agree on
+     * what this issuer is willing to sign for.
+     */
+    supportedTokens: ReadonlySet<Address>;
     /**
      * Optional — when wired, used to estimate the PT gas-reimbursement
      * fee. The handler self-computes `feeAmount` + `feeRecipient` so the
@@ -1977,7 +1987,7 @@ interface PTRedeemResponse {
     /** The BurnRequest deadline (unix seconds) — FE uses this to surface a countdown. */
     signatureDeadline: bigint;
 }
-type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED";
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTRedeemError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTRedeemErrorCode;
@@ -1995,6 +2005,7 @@ declare class PTRedeemHandler {
     private readonly chainId;
     private readonly domainResolver;
     private readonly burnerSignerWallet;
+    private readonly supportedTokens;
     private readonly redeemLockDurationMs;
     private readonly signatureDeadlineSeconds;
     private readonly now;
@@ -2273,6 +2284,23 @@ interface PendingUserOpEntry {
         verificationGasLimit: string;
         preVerificationGas: string;
         userOpHash: Hex;
+        /**
+         * Lock id (PendingCredit on redeem, LockedMint on claim) reserved
+         * for the FALLBACK path — distinct from the outer entry's
+         * sponsored lock because the on-chain amount the user burns/mints
+         * differs between variants.
+         *
+         * Audit PACI5-21 — pre-fix `handleMobileSubmit.bindUserOpHash`
+         * always bound the submitted userOpHash to the SPONSORED lockId,
+         * even when the user submitted the fallback variant. The
+         * bundler-receipt fallback in `handleRedeemStatus` then resolved
+         * the sponsored credit (`amount - fee`) against the on-chain
+         * burn of the FULL `amount` — every fee-bearing fallback redeem
+         * permanently under-credited the user by exactly the fee. Surface
+         * the fallback lockId here so submit can route the bind to the
+         * correct ledger row.
+         */
+        lockId?: string;
     };
     /**
      * EIP-7702 authorization tuple — present only on the `delegate`
@@ -2493,6 +2521,21 @@ interface PrepareMobileUserOpParams {
         maxFeePerGas?: bigint;
         maxPriorityFeePerGas?: bigint;
     };
+    /**
+     * Optional separate lock id for the FALLBACK path — required when
+     * the upstream handler reserves a DIFFERENT ledger row for the
+     * fallback variant (PTRedeemHandler reserves
+     * `amount` for fallback vs `amount - fee` for sponsored).
+     *
+     * Audit PACI5-21 — when omitted, `handleMobileSubmit` binds the
+     * fallback userOpHash to the outer sponsored `lockId`, which made
+     * `handleRedeemStatus`'s bundler-receipt fallback resolve the
+     * SMALLER sponsored credit against the on-chain burn of the FULL
+     * amount. Every fee-bearing fallback redeem permanently
+     * under-credited the user by exactly the fee. Pass the fallback
+     * lockId here so submit can route the bind to the correct row.
+     */
+    lockIdFallback?: string;
     /** Paymaster sponsorship response, or `undefined` if PAFI declined. */
     paymasterFields?: {
         paymaster: Address;
@@ -2606,6 +2649,13 @@ interface HandleMobilePrepareParams {
     partialUserOp: PartialUserOperation;
     /** Optional fee-stripped fallback variant. */
     partialUserOpFallback?: PartialUserOperation;
+    /**
+     * Optional separate lock id for the fallback path. Required when the
+     * upstream handler (e.g. PTRedeemHandler) reserves a DIFFERENT
+     * ledger row for the fallback variant. See audit PACI5-21 +
+     * `prepareMobileUserOp` for the full rationale.
+     */
+    lockIdFallback?: string;
     /**
      * Scenario tag — passed to `requestSponsorship` so the relayer can
      * apply per-scenario L1 enforcement (`mint`, `burn`, etc.).
@@ -2732,7 +2782,7 @@ interface IssuerStateValidatorLike {
  * own composer — gg56 uses a timestamp-key 2D nonce). Caller layers
  * paymaster sponsorship + sponsorAuth on top of the returned UserOps.
  */
-type PTClaimErrorCode = "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT";
+type PTClaimErrorCode = "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTClaimError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTClaimErrorCode;
@@ -2754,6 +2804,23 @@ interface PTClaimHandlerConfig {
      * `chainId` + `pointTokenAddress` respectively.
      */
     domainResolver: PointTokenDomainResolver;
+    /**
+     * Issuer's allow-listed PointToken contracts (checksummed EIP-55).
+     * Every `handle()` call validates the request's `pointTokenAddress`
+     * against this set BEFORE any chain read or signer call.
+     *
+     * write surface (claim/redeem) previously skipped it. The asymmetry
+     * meant an issuer signer whitelisted as minter on PointTokens
+     * outside the configured indexer set could be coerced into signing
+     * a valid `MintForRequest` for an off-set token — the on-chain
+     * mint would succeed, but no PointIndexer was watching to debit the
+     * off-chain ledger. Silent supply-invariant violation.
+     *
+     * Pass the SAME set used to construct `IssuerApiHandlers` so the
+     * read and write paths agree on what this issuer is willing to
+     * sign for.
+     */
+    supportedTokens: ReadonlySet<Address>;
     /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
     feeService?: FeeManager;
     /** Optional — pre-validates issuer status + cap before locking balance. */
@@ -3283,6 +3350,18 @@ interface MobilePrepareDto {
 interface RedeemPrepareDto extends MobilePrepareDto {
     netCreditAmount: string;
     netCreditAmountFallback?: string;
+    /**
+     * Lock id reserved for the FALLBACK redeem path (= full `amount`).
+     * Mobile FE polls `/redeem/status/:lockIdFallback` when it submits
+     * the fallback variant (`variant: 'fallback'` on `/redeem/submit`).
+     *
+     * Audit PACI5-21 — pre-fix the adapter exposed only the sponsored
+     * `lockId` (= `amount - fee`), so the bundler-receipt fallback in
+     * `handleRedeemStatus` resolved the smaller credit against the
+     * on-chain burn of the full amount → user under-credited by exactly
+     * the fee on every fallback redeem.
+     */
+    lockIdFallback?: string;
 }
 interface MobileSubmitDto {
     userOpHash: Hex;

package/dist/index.d.ts

@@ -1884,6 +1884,16 @@ interface PTRedeemHandlerConfig {
      * provisioning time. Typically HSM/KMS-backed in prod.
      */
     burnerSignerWallet: WalletClient;
+    /**
+     * Issuer's allow-listed PointToken contracts (checksummed EIP-55).
+     * Every `handle()` call validates the request's `pointTokenAddress`
+     * against this set BEFORE any chain read, signer call, or pending
+     * credit reservation.
+     * Pass the SAME set used to construct `IssuerApiHandlers` and
+     * `PTClaimHandler` so the read, claim, and redeem paths agree on
+     * what this issuer is willing to sign for.
+     */
+    supportedTokens: ReadonlySet<Address>;
     /**
      * Optional — when wired, used to estimate the PT gas-reimbursement
      * fee. The handler self-computes `feeAmount` + `feeRecipient` so the
@@ -1977,7 +1987,7 @@ interface PTRedeemResponse {
     /** The BurnRequest deadline (unix seconds) — FE uses this to surface a countdown. */
     signatureDeadline: bigint;
 }
-type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED";
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTRedeemError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTRedeemErrorCode;
@@ -1995,6 +2005,7 @@ declare class PTRedeemHandler {
     private readonly chainId;
     private readonly domainResolver;
     private readonly burnerSignerWallet;
+    private readonly supportedTokens;
     private readonly redeemLockDurationMs;
     private readonly signatureDeadlineSeconds;
     private readonly now;
@@ -2273,6 +2284,23 @@ interface PendingUserOpEntry {
         verificationGasLimit: string;
         preVerificationGas: string;
         userOpHash: Hex;
+        /**
+         * Lock id (PendingCredit on redeem, LockedMint on claim) reserved
+         * for the FALLBACK path — distinct from the outer entry's
+         * sponsored lock because the on-chain amount the user burns/mints
+         * differs between variants.
+         *
+         * Audit PACI5-21 — pre-fix `handleMobileSubmit.bindUserOpHash`
+         * always bound the submitted userOpHash to the SPONSORED lockId,
+         * even when the user submitted the fallback variant. The
+         * bundler-receipt fallback in `handleRedeemStatus` then resolved
+         * the sponsored credit (`amount - fee`) against the on-chain
+         * burn of the FULL `amount` — every fee-bearing fallback redeem
+         * permanently under-credited the user by exactly the fee. Surface
+         * the fallback lockId here so submit can route the bind to the
+         * correct ledger row.
+         */
+        lockId?: string;
     };
     /**
      * EIP-7702 authorization tuple — present only on the `delegate`
@@ -2493,6 +2521,21 @@ interface PrepareMobileUserOpParams {
         maxFeePerGas?: bigint;
         maxPriorityFeePerGas?: bigint;
     };
+    /**
+     * Optional separate lock id for the FALLBACK path — required when
+     * the upstream handler reserves a DIFFERENT ledger row for the
+     * fallback variant (PTRedeemHandler reserves
+     * `amount` for fallback vs `amount - fee` for sponsored).
+     *
+     * Audit PACI5-21 — when omitted, `handleMobileSubmit` binds the
+     * fallback userOpHash to the outer sponsored `lockId`, which made
+     * `handleRedeemStatus`'s bundler-receipt fallback resolve the
+     * SMALLER sponsored credit against the on-chain burn of the FULL
+     * amount. Every fee-bearing fallback redeem permanently
+     * under-credited the user by exactly the fee. Pass the fallback
+     * lockId here so submit can route the bind to the correct row.
+     */
+    lockIdFallback?: string;
     /** Paymaster sponsorship response, or `undefined` if PAFI declined. */
     paymasterFields?: {
         paymaster: Address;
@@ -2606,6 +2649,13 @@ interface HandleMobilePrepareParams {
     partialUserOp: PartialUserOperation;
     /** Optional fee-stripped fallback variant. */
     partialUserOpFallback?: PartialUserOperation;
+    /**
+     * Optional separate lock id for the fallback path. Required when the
+     * upstream handler (e.g. PTRedeemHandler) reserves a DIFFERENT
+     * ledger row for the fallback variant. See audit PACI5-21 +
+     * `prepareMobileUserOp` for the full rationale.
+     */
+    lockIdFallback?: string;
     /**
      * Scenario tag — passed to `requestSponsorship` so the relayer can
      * apply per-scenario L1 enforcement (`mint`, `burn`, etc.).
@@ -2732,7 +2782,7 @@ interface IssuerStateValidatorLike {
  * own composer — gg56 uses a timestamp-key 2D nonce). Caller layers
  * paymaster sponsorship + sponsorAuth on top of the returned UserOps.
  */
-type PTClaimErrorCode = "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT";
+type PTClaimErrorCode = "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTClaimError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTClaimErrorCode;
@@ -2754,6 +2804,23 @@ interface PTClaimHandlerConfig {
      * `chainId` + `pointTokenAddress` respectively.
      */
     domainResolver: PointTokenDomainResolver;
+    /**
+     * Issuer's allow-listed PointToken contracts (checksummed EIP-55).
+     * Every `handle()` call validates the request's `pointTokenAddress`
+     * against this set BEFORE any chain read or signer call.
+     *
+     * write surface (claim/redeem) previously skipped it. The asymmetry
+     * meant an issuer signer whitelisted as minter on PointTokens
+     * outside the configured indexer set could be coerced into signing
+     * a valid `MintForRequest` for an off-set token — the on-chain
+     * mint would succeed, but no PointIndexer was watching to debit the
+     * off-chain ledger. Silent supply-invariant violation.
+     *
+     * Pass the SAME set used to construct `IssuerApiHandlers` so the
+     * read and write paths agree on what this issuer is willing to
+     * sign for.
+     */
+    supportedTokens: ReadonlySet<Address>;
     /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
     feeService?: FeeManager;
     /** Optional — pre-validates issuer status + cap before locking balance. */
@@ -3283,6 +3350,18 @@ interface MobilePrepareDto {
 interface RedeemPrepareDto extends MobilePrepareDto {
     netCreditAmount: string;
     netCreditAmountFallback?: string;
+    /**
+     * Lock id reserved for the FALLBACK redeem path (= full `amount`).
+     * Mobile FE polls `/redeem/status/:lockIdFallback` when it submits
+     * the fallback variant (`variant: 'fallback'` on `/redeem/submit`).
+     *
+     * Audit PACI5-21 — pre-fix the adapter exposed only the sponsored
+     * `lockId` (= `amount - fee`), so the bundler-receipt fallback in
+     * `handleRedeemStatus` resolved the smaller credit against the
+     * on-chain burn of the full amount → user under-credited by exactly
+     * the fee on every fallback redeem.
+     */
+    lockIdFallback?: string;
 }
 interface MobileSubmitDto {
     userOpHash: Hex;

package/dist/index.js

@@ -2108,6 +2108,7 @@ var PTRedeemHandler = class {
   chainId;
   domainResolver;
   burnerSignerWallet;
+  supportedTokens;
   redeemLockDurationMs;
   signatureDeadlineSeconds;
   now;
@@ -2147,6 +2148,13 @@ var PTRedeemHandler = class {
     this.chainId = config.chainId;
     this.domainResolver = config.domainResolver;
     this.burnerSignerWallet = config.burnerSignerWallet;
+    if (!config.supportedTokens) {
+      throw new PTRedeemError(
+        "UNSUPPORTED_POINT_TOKEN",
+        "PTRedeemHandler requires `supportedTokens` (issuer's allow-listed PointToken contracts). See audit PACI5-18."
+      );
+    }
+    this.supportedTokens = config.supportedTokens;
     if (this.burnerSignerWallet?.account?.type === "local") {
       console.warn("[PAFI] PTRedeemHandler: burnerSignerWallet uses a local (private key) account. Use a KMS-backed signer in production.");
     }
@@ -2175,6 +2183,12 @@ var PTRedeemHandler = class {
       throw new PTRedeemError("INVALID_AMOUNT", "redeem amount must be positive");
     }
     const pointTokenAddress = getAddress7(request.pointTokenAddress);
+    if (!this.supportedTokens.has(pointTokenAddress)) {
+      throw new PTRedeemError(
+        "UNSUPPORTED_POINT_TOKEN",
+        `redeem: pointTokenAddress ${pointTokenAddress} is not in the issuer's supported-token allowlist. Check IssuerApiHandlers.supportedTokens and PTRedeemHandler.config.supportedTokens point at the same set.`
+      );
+    }
     if (this.redemptionService) {
       const decision = await this.redemptionService.evaluate(
         request.userAddress,
@@ -2671,7 +2685,10 @@ async function prepareMobileUserOp(params) {
       callGasLimit: fallback.userOp.callGasLimit.toString(),
       verificationGasLimit: fallback.userOp.verificationGasLimit.toString(),
       preVerificationGas: fallback.userOp.preVerificationGas.toString(),
-      userOpHash: fallback.userOpHash
+      userOpHash: fallback.userOpHash,
+      // Audit PACI5-21 — carry the fallback-specific lockId so submit
+      // can bind the fallback userOpHash to the correct ledger row.
+      lockId: params.lockIdFallback
     };
   }
   const entry = {
@@ -2864,6 +2881,7 @@ async function handleMobilePrepare(params) {
     lockId: params.lockId,
     partialUserOp: sponsoredOp,
     partialUserOpFallback: params.partialUserOpFallback,
+    lockIdFallback: params.lockIdFallback,
     paymasterFields,
     chainId: params.chainId,
     store: params.store,
@@ -2892,7 +2910,8 @@ async function handleMobileSubmit(params) {
     entryPoint: params.entryPoint ?? ENTRY_POINT_V08,
     eip7702Auth: entry.eip7702Auth
   });
-  await params.bindUserOpHash(params.lockId, result.userOpHash);
+  const targetLockId = variant === "fallback" && entry.fallback?.lockId ? entry.fallback.lockId : params.lockId;
+  await params.bindUserOpHash(targetLockId, result.userOpHash);
   await params.store.delete(params.lockId);
   return { userOpHash: result.userOpHash };
 }
@@ -2942,6 +2961,12 @@ var PTClaimHandler = class {
   cfg;
   inFlightNonces = /* @__PURE__ */ new Map();
   constructor(config) {
+    if (!config.supportedTokens) {
+      throw new PTClaimError(
+        "UNSUPPORTED_POINT_TOKEN",
+        "PTClaimHandler requires `supportedTokens` (issuer's allow-listed PointToken contracts). See audit PACI5-18."
+      );
+    }
     const lockDurationMs = config.lockDurationMs ?? DEFAULT_LOCK_MS;
     const signatureDeadlineSeconds = config.signatureDeadlineSeconds ?? DEFAULT_SIG_DEADLINE_SEC2;
     const maxAllowedSignatureMs = lockDurationMs - M11_SAFETY_MARGIN_MS2;
@@ -2973,6 +2998,14 @@ var PTClaimHandler = class {
     if (request.amount <= 0n) {
       throw new PTClaimError("INVALID_AMOUNT", "claim amount must be positive");
     }
+    const pointTokenAddress = getAddress9(request.pointTokenAddress);
+    if (!this.cfg.supportedTokens.has(pointTokenAddress)) {
+      throw new PTClaimError(
+        "UNSUPPORTED_POINT_TOKEN",
+        `claim: pointTokenAddress ${pointTokenAddress} is not in the issuer's supported-token allowlist. Check IssuerApiHandlers.supportedTokens and PTClaimHandler.config.supportedTokens point at the same set.`,
+        { requested: pointTokenAddress }
+      );
+    }
     if (this.cfg.issuerStateValidator) {
       try {
         await this.cfg.issuerStateValidator.preValidateMint(
@@ -3648,10 +3681,16 @@ var IssuerApiAdapter = class {
       "burn",
       pointTokenAddress,
       redeemResponse.expiresInSeconds,
-      input.eip7702Auth
+      input.eip7702Auth,
+      // Audit PACI5-21 — fallback path reserves a separate
+      // PendingCredit row for the full `amount`. Surface its lockId so
+      // mobile FE can poll the correct row + `handleMobileSubmit`
+      // routes the userOpHash bind to it on fallback submit.
+      redeemResponse.fallback?.lockId
     );
     return {
       lockId: redeemResponse.lockId,
+      lockIdFallback: redeemResponse.fallback?.lockId,
       userOpHash: prepared.sponsored.userOpHash,
       typedData: prepared.sponsored.typedData,
       userOpHashFallback: prepared.fallback?.userOpHash,
@@ -3782,13 +3821,14 @@ var IssuerApiAdapter = class {
       issuerSignerWallet: this.cfg.issuerSignerWallet
     });
   }
-  async runMobilePrepare(authenticatedAddress, chainId, lockId, partialUserOp, partialUserOpFallback, scenario, pointTokenAddress, ttlSeconds, eip7702Auth) {
+  async runMobilePrepare(authenticatedAddress, chainId, lockId, partialUserOp, partialUserOpFallback, scenario, pointTokenAddress, ttlSeconds, eip7702Auth, lockIdFallback) {
     return await handleMobilePrepare({
       userAddress: authenticatedAddress,
       chainId,
       lockId,
       partialUserOp,
       partialUserOpFallback,
+      lockIdFallback,
       scenario,
       pointTokenAddress,
       ttlSeconds,
@@ -5059,7 +5099,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.28.1" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.31.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,