@pafi-dev/issuer 0.30.0 → 0.31.0

package/dist/index.d.cts

@@ -1889,17 +1889,6 @@ interface PTRedeemHandlerConfig {
      * Every `handle()` call validates the request's `pointTokenAddress`
      * against this set BEFORE any chain read, signer call, or pending
      * credit reservation.
-     *
-     * Audit PACI5-18 (redeem twin of the claim-side finding) — the read
-     * surface (`IssuerApiHandlers.handleUser` / `handleRedemptionEvaluate`)
-     * enforces this allowlist, but the write surface previously skipped
-     * it. The asymmetry meant an issuer burner signer whitelisted on
-     * multiple PointTokens could be coerced into signing a valid
-     * `BurnRequest` for an off-allowlist token where no BurnIndexer is
-     * running — the on-chain burn would succeed but the off-chain
-     * pending credit would stay PENDING forever (or worse, resolve via
-     * the bundler-receipt fallback against an unbacked credit balance).
-     *
      * 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.
@@ -2295,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`
@@ -2515,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;
@@ -2628,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.).
@@ -2781,8 +2809,6 @@ interface PTClaimHandlerConfig {
      * Every `handle()` call validates the request's `pointTokenAddress`
      * against this set BEFORE any chain read or signer call.
      *
-     * Audit PACI5-18 — the read surface (`IssuerApiHandlers.handleUser`,
-     * `handleRedemptionEvaluate`) enforces this allowlist, but the
      * 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
@@ -3324,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

@@ -1889,17 +1889,6 @@ interface PTRedeemHandlerConfig {
      * Every `handle()` call validates the request's `pointTokenAddress`
      * against this set BEFORE any chain read, signer call, or pending
      * credit reservation.
-     *
-     * Audit PACI5-18 (redeem twin of the claim-side finding) — the read
-     * surface (`IssuerApiHandlers.handleUser` / `handleRedemptionEvaluate`)
-     * enforces this allowlist, but the write surface previously skipped
-     * it. The asymmetry meant an issuer burner signer whitelisted on
-     * multiple PointTokens could be coerced into signing a valid
-     * `BurnRequest` for an off-allowlist token where no BurnIndexer is
-     * running — the on-chain burn would succeed but the off-chain
-     * pending credit would stay PENDING forever (or worse, resolve via
-     * the bundler-receipt fallback against an unbacked credit balance).
-     *
      * 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.
@@ -2295,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`
@@ -2515,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;
@@ -2628,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.).
@@ -2781,8 +2809,6 @@ interface PTClaimHandlerConfig {
      * Every `handle()` call validates the request's `pointTokenAddress`
      * against this set BEFORE any chain read or signer call.
      *
-     * Audit PACI5-18 — the read surface (`IssuerApiHandlers.handleUser`,
-     * `handleRedemptionEvaluate`) enforces this allowlist, but the
      * 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
@@ -3324,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

@@ -2685,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 = {
@@ -2878,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,
@@ -2906,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 };
 }
@@ -3676,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,
@@ -3810,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,
@@ -5087,7 +5099,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.30.0" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.31.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,