@pafi-dev/issuer 0.30.0 → 0.32.0

package/dist/index.d.cts

@@ -1551,9 +1551,18 @@ interface SettlementClientConfig {
     /**
      * chainId — used to derive the issuer-api base URL via
      * `getPafiServiceUrls(chainId).issuerApi`. SDK ships with the URL
-     * per chainId; bump SDK version to retarget.
+     * per chainId; bump SDK version to retarget — OR pass `baseUrl`
+     * to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the issuer-api base URL. Audit PACI5-17 —
+     * production issuer backends should set this from an env var
+     * (e.g. `PAFI_ISSUER_API_URL`) so the deployed binary doesn't
+     * depend on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
     issuerId: string;
     /** Raw API key sent as `Authorization: Bearer <apiKey>`. */
@@ -1566,6 +1575,34 @@ interface SettlementClientConfig {
 interface PolicyProviderConfig extends SettlementClientConfig {
     /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
     cacheTtlMs?: number;
+    /**
+     * Behavior khi settlement-api fetch fail (network blip, 5xx, timeout).
+     *
+     * Audit PACI5-17 — the pre-flight redeem limit is the SOLE gate
+     * before the issuer signer mints a BurnRequest. Silently degrading
+     * to a permissive default during settlement outages let users
+     * exceed their configured limit until the outage cleared.
+     *
+     *  - `'fail-closed'` (DEFAULT, recommended): throw
+     *    `PolicyProviderUnavailableError`. Caller maps to HTTP 503 so
+     *    the FE can retry; redemptions are blocked until policy fetch
+     *    succeeds.
+     *
+     *  - `'permissive-default'`: return `defaultPolicyFor(issuerId)` and
+     *    fire `onWarning`. Pre-fix behavior. Operators who genuinely
+     *    prefer availability over enforcement (e.g. test issuers, low-
+     *    risk PT) MUST opt in explicitly AND wire `onWarning` to a
+     *    pager / Slack / Sentry alert. Silent permissive fallback is no
+     *    longer the default.
+     */
+    onFetchFailure?: "fail-closed" | "permissive-default";
+    /**
+     * Observability hook for non-fatal events: permissive-default
+     * fallbacks (when explicitly opted in). Wire to your logger /
+     * Sentry / Datadog so the `policy_provider_fallback` event reaches
+     * the on-call dashboard.
+     */
+    onWarning?: (msg: string, ctx: Record<string, unknown>) => void;
     /**
      * Optional clock for testability. Returns unix milliseconds.
      * Defaults to () => Date.now().
@@ -1596,6 +1633,8 @@ declare class PolicyProvider {
     private readonly client;
     private readonly issuerId;
     private readonly cacheTtlMs;
+    private readonly onFetchFailure;
+    private readonly onWarning?;
     private readonly now;
     private cache;
     private inflight;
@@ -1889,17 +1928,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.
@@ -1998,7 +2026,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" | "UNSUPPORTED_POINT_TOKEN";
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "REDEMPTION_POLICY_UNAVAILABLE" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTRedeemError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTRedeemErrorCode;
@@ -2050,9 +2078,18 @@ interface PafiBackendConfig {
     /**
      * chainId — used to derive the sponsor-relayer base URL via
      * `getPafiServiceUrls(chainId).sponsorRelayer`. SDK ships with the
-     * URL per chainId; bump SDK version to retarget.
+     * URL per chainId; bump SDK version to retarget — OR pass
+     * `baseUrl` to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the sponsor-relayer base URL. Audit
+     * PACI5-17 — production issuer backends should set this from an env
+     * var (e.g. `PAFI_SPONSOR_RELAYER_URL`) so the binary doesn't depend
+     * on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     issuerId: string;
     apiKey: string;
     fetchImpl?: typeof fetch;
@@ -2295,6 +2332,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 +2569,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 +2697,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 +2857,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
@@ -3159,6 +3233,30 @@ interface IssuerServiceConfig {
         issuerId: string;
         apiKey: string;
         historyStore: IRedemptionHistoryStore;
+        /**
+         * Optional override for the PAFI issuer-api base URL. Audit
+         * PACI5-17 — production issuer backends should set this from an
+         * env var (e.g. `PAFI_ISSUER_API_URL`) so policy fetch hits the
+         * canonical environment for the deploy. Undefined → SDK
+         * ship-default per chainId.
+         */
+        baseUrl?: string;
+        /**
+         * Behavior khi settlement-api fetch fail. Default `'fail-closed'`
+         * (audit PACI5-17 — pre-flight redeem limit is the sole gate; do
+         * not silently degrade to a permissive default).
+         *
+         * Opt in to `'permissive-default'` ONLY when paired with an alert
+         * on the `policy_provider_fallback` event surfaced via
+         * `onPolicyWarning`.
+         */
+        onFetchFailure?: "fail-closed" | "permissive-default";
+        /**
+         * Observability hook for `policy_provider_fallback` events. Wire
+         * to your logger / Sentry / Datadog so the on-call dashboard sees
+         * settlement-api degradation.
+         */
+        onPolicyWarning?: (msg: string, ctx: Record<string, unknown>) => void;
         /** Override fetch (testing). */
         fetchImpl?: typeof fetch;
         /** Per-fetch timeout in ms. Default 1000. */
@@ -3324,6 +3422,12 @@ 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`).
+     */
+    lockIdFallback?: string;
 }
 interface MobileSubmitDto {
     userOpHash: Hex;

package/dist/index.d.ts

@@ -1551,9 +1551,18 @@ interface SettlementClientConfig {
     /**
      * chainId — used to derive the issuer-api base URL via
      * `getPafiServiceUrls(chainId).issuerApi`. SDK ships with the URL
-     * per chainId; bump SDK version to retarget.
+     * per chainId; bump SDK version to retarget — OR pass `baseUrl`
+     * to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the issuer-api base URL. Audit PACI5-17 —
+     * production issuer backends should set this from an env var
+     * (e.g. `PAFI_ISSUER_API_URL`) so the deployed binary doesn't
+     * depend on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
     issuerId: string;
     /** Raw API key sent as `Authorization: Bearer <apiKey>`. */
@@ -1566,6 +1575,34 @@ interface SettlementClientConfig {
 interface PolicyProviderConfig extends SettlementClientConfig {
     /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
     cacheTtlMs?: number;
+    /**
+     * Behavior khi settlement-api fetch fail (network blip, 5xx, timeout).
+     *
+     * Audit PACI5-17 — the pre-flight redeem limit is the SOLE gate
+     * before the issuer signer mints a BurnRequest. Silently degrading
+     * to a permissive default during settlement outages let users
+     * exceed their configured limit until the outage cleared.
+     *
+     *  - `'fail-closed'` (DEFAULT, recommended): throw
+     *    `PolicyProviderUnavailableError`. Caller maps to HTTP 503 so
+     *    the FE can retry; redemptions are blocked until policy fetch
+     *    succeeds.
+     *
+     *  - `'permissive-default'`: return `defaultPolicyFor(issuerId)` and
+     *    fire `onWarning`. Pre-fix behavior. Operators who genuinely
+     *    prefer availability over enforcement (e.g. test issuers, low-
+     *    risk PT) MUST opt in explicitly AND wire `onWarning` to a
+     *    pager / Slack / Sentry alert. Silent permissive fallback is no
+     *    longer the default.
+     */
+    onFetchFailure?: "fail-closed" | "permissive-default";
+    /**
+     * Observability hook for non-fatal events: permissive-default
+     * fallbacks (when explicitly opted in). Wire to your logger /
+     * Sentry / Datadog so the `policy_provider_fallback` event reaches
+     * the on-call dashboard.
+     */
+    onWarning?: (msg: string, ctx: Record<string, unknown>) => void;
     /**
      * Optional clock for testability. Returns unix milliseconds.
      * Defaults to () => Date.now().
@@ -1596,6 +1633,8 @@ declare class PolicyProvider {
     private readonly client;
     private readonly issuerId;
     private readonly cacheTtlMs;
+    private readonly onFetchFailure;
+    private readonly onWarning?;
     private readonly now;
     private cache;
     private inflight;
@@ -1889,17 +1928,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.
@@ -1998,7 +2026,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" | "UNSUPPORTED_POINT_TOKEN";
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "REDEMPTION_POLICY_UNAVAILABLE" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTRedeemError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTRedeemErrorCode;
@@ -2050,9 +2078,18 @@ interface PafiBackendConfig {
     /**
      * chainId — used to derive the sponsor-relayer base URL via
      * `getPafiServiceUrls(chainId).sponsorRelayer`. SDK ships with the
-     * URL per chainId; bump SDK version to retarget.
+     * URL per chainId; bump SDK version to retarget — OR pass
+     * `baseUrl` to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the sponsor-relayer base URL. Audit
+     * PACI5-17 — production issuer backends should set this from an env
+     * var (e.g. `PAFI_SPONSOR_RELAYER_URL`) so the binary doesn't depend
+     * on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     issuerId: string;
     apiKey: string;
     fetchImpl?: typeof fetch;
@@ -2295,6 +2332,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 +2569,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 +2697,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 +2857,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
@@ -3159,6 +3233,30 @@ interface IssuerServiceConfig {
         issuerId: string;
         apiKey: string;
         historyStore: IRedemptionHistoryStore;
+        /**
+         * Optional override for the PAFI issuer-api base URL. Audit
+         * PACI5-17 — production issuer backends should set this from an
+         * env var (e.g. `PAFI_ISSUER_API_URL`) so policy fetch hits the
+         * canonical environment for the deploy. Undefined → SDK
+         * ship-default per chainId.
+         */
+        baseUrl?: string;
+        /**
+         * Behavior khi settlement-api fetch fail. Default `'fail-closed'`
+         * (audit PACI5-17 — pre-flight redeem limit is the sole gate; do
+         * not silently degrade to a permissive default).
+         *
+         * Opt in to `'permissive-default'` ONLY when paired with an alert
+         * on the `policy_provider_fallback` event surfaced via
+         * `onPolicyWarning`.
+         */
+        onFetchFailure?: "fail-closed" | "permissive-default";
+        /**
+         * Observability hook for `policy_provider_fallback` events. Wire
+         * to your logger / Sentry / Datadog so the on-call dashboard sees
+         * settlement-api degradation.
+         */
+        onPolicyWarning?: (msg: string, ctx: Record<string, unknown>) => void;
         /** Override fetch (testing). */
         fetchImpl?: typeof fetch;
         /** Per-fetch timeout in ms. Default 1000. */
@@ -3324,6 +3422,12 @@ 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`).
+     */
+    lockIdFallback?: string;
 }
 interface MobileSubmitDto {
     userOpHash: Hex;

package/dist/index.js

@@ -2190,11 +2190,23 @@ var PTRedeemHandler = class {
       );
     }
     if (this.redemptionService) {
-      const decision = await this.redemptionService.evaluate(
-        request.userAddress,
-        request.amount,
-        pointTokenAddress
-      );
+      let decision;
+      try {
+        decision = await this.redemptionService.evaluate(
+          request.userAddress,
+          request.amount,
+          pointTokenAddress
+        );
+      } catch (err) {
+        const code = err && typeof err === "object" && "code" in err ? err.code : void 0;
+        if (code === "POLICY_PROVIDER_UNAVAILABLE") {
+          throw new PTRedeemError(
+            "REDEMPTION_POLICY_UNAVAILABLE",
+            "Redemption policy temporarily unavailable \u2014 please try again shortly."
+          );
+        }
+        throw err;
+      }
       if (!decision.allowed) {
         const denial = decision.denial;
         throw new PTRedeemError(
@@ -2685,7 +2697,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 +2893,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 +2922,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 +3693,12 @@ var IssuerApiAdapter = class {
       "burn",
       pointTokenAddress,
       redeemResponse.expiresInSeconds,
-      input.eip7702Auth
+      input.eip7702Auth,
+      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 +3829,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,
@@ -4252,7 +4272,9 @@ var PafiBackendClient = class {
     if (!config.issuerId) throw new Error("PafiBackendClient: issuerId is required");
     if (!config.apiKey) throw new Error("PafiBackendClient: apiKey is required");
     this.config = config;
-    this.baseUrl = getPafiServiceUrls(config.chainId).sponsorRelayer;
+    this.baseUrl = getPafiServiceUrls(config.chainId, {
+      sponsorRelayer: config.baseUrl
+    }).sponsorRelayer;
   }
   async requestSponsorship(request) {
     const maxAttempts = this.config.retry?.maxAttempts ?? 1;
@@ -4517,6 +4539,9 @@ function nextBlackoutEndAfter(windows, nowUnixSec) {
 }
 var REDEMPTION_HISTORY_WINDOW_SEC = SECONDS_PER_DAY;
 
+// src/redemption/policyProvider.ts
+import { PafiSdkError as PafiSdkError2 } from "@pafi-dev/core";
+
 // src/redemption/settlementClient.ts
 import {
   getPafiServiceUrls as getPafiServiceUrls2
@@ -4529,7 +4554,12 @@ var SettlementClient = class {
     if (!config.issuerId) throw new Error("SettlementClient: issuerId is required");
     if (!config.apiKey) throw new Error("SettlementClient: apiKey is required");
     this.config = {
-      baseUrl: getPafiServiceUrls2(config.chainId).issuerApi.replace(/\/+$/, ""),
+      // Audit PACI5-17 — honor optional baseUrl override wired from
+      // an env var (e.g. PAFI_ISSUER_API_URL). Empty / undefined →
+      // ship-default for chainId.
+      baseUrl: getPafiServiceUrls2(config.chainId, {
+        issuerApi: config.baseUrl
+      }).issuerApi.replace(/\/+$/, ""),
       issuerId: config.issuerId,
       apiKey: config.apiKey,
       fetchTimeoutMs: config.fetchTimeoutMs ?? DEFAULT_TIMEOUT_MS,
@@ -4633,10 +4663,23 @@ function defaultPolicyFor(issuerId) {
 
 // src/redemption/policyProvider.ts
 var DEFAULT_CACHE_TTL_MS3 = 5 * 60 * 1e3;
+var PolicyProviderUnavailableError = class extends PafiSdkError2 {
+  code = "POLICY_PROVIDER_UNAVAILABLE";
+  httpStatus = "service_unavailable";
+  details;
+  constructor(issuerId, reason) {
+    super(
+      `Redemption policy provider unavailable for issuer ${issuerId}: ${reason}. Pre-flight redeem limit cannot be enforced \u2014 refusing to sign BurnRequest. Mobile FE: surface "try again shortly" and retry with backoff.`
+    );
+    this.details = { issuerId, reason };
+  }
+};
 var PolicyProvider = class {
   client;
   issuerId;
   cacheTtlMs;
+  onFetchFailure;
+  onWarning;
   now;
   cache = null;
   inflight = null;
@@ -4644,6 +4687,8 @@ var PolicyProvider = class {
     this.client = new SettlementClient(config);
     this.issuerId = config.issuerId;
     this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS3;
+    this.onFetchFailure = config.onFetchFailure ?? "fail-closed";
+    this.onWarning = config.onWarning;
     this.now = config.now ?? (() => Date.now());
   }
   async getPolicy() {
@@ -4676,7 +4721,19 @@ var PolicyProvider = class {
       };
       return { policy: result.policy, source: "settlement" };
     }
-    return { policy: defaultPolicyFor(this.issuerId), source: "default" };
+    const reason = "reason" in result && typeof result.reason === "string" ? result.reason : "unknown";
+    if (this.onFetchFailure === "permissive-default") {
+      this.onWarning?.(
+        "PolicyProvider: settlement-api unreachable, falling back to permissive default. Pre-flight redeem limit is DEGRADED until settlement-api recovers.",
+        {
+          event: "policy_provider_fallback",
+          issuerId: this.issuerId,
+          reason
+        }
+      );
+      return { policy: defaultPolicyFor(this.issuerId), source: "default" };
+    }
+    throw new PolicyProviderUnavailableError(this.issuerId, reason);
   }
 };
 
@@ -4823,6 +4880,15 @@ async function createIssuerService(config) {
       issuerId: config.redemption.issuerId,
       apiKey: config.redemption.apiKey
     };
+    if (config.redemption.baseUrl) {
+      policyConfig.baseUrl = config.redemption.baseUrl;
+    }
+    if (config.redemption.onFetchFailure) {
+      policyConfig.onFetchFailure = config.redemption.onFetchFailure;
+    }
+    if (config.redemption.onPolicyWarning) {
+      policyConfig.onWarning = config.redemption.onPolicyWarning;
+    }
     if (config.redemption.fetchImpl) policyConfig.fetchImpl = config.redemption.fetchImpl;
     if (config.redemption.fetchTimeoutMs !== void 0) {
       policyConfig.fetchTimeoutMs = config.redemption.fetchTimeoutMs;
@@ -5087,7 +5153,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.30.0" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.32.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,