@pafi-dev/issuer 0.7.8 → 0.8.0

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   BundlerRejectedError: () => BundlerRejectedError,
   BurnIndexer: () => BurnIndexer,
   ConfigurationError: () => ConfigurationError,
+  DEFAULT_REDEMPTION_POLICY: () => DEFAULT_REDEMPTION_POLICY,
   DefaultPolicyEngine: () => DefaultPolicyEngine,
   FeeManager: () => FeeManager,
   InMemoryCursorStore: () => InMemoryCursorStore,
@@ -37,8 +38,11 @@ __export(index_exports, {
   IssuerStateValidator: () => IssuerStateValidator,
   LockNotFoundError: () => LockNotFoundError,
   MemoryPendingUserOpStore: () => MemoryPendingUserOpStore,
+  MemoryRateLimiter: () => MemoryRateLimiter,
+  MemoryRedemptionHistoryStore: () => MemoryRedemptionHistoryStore,
   MemorySessionStore: () => MemorySessionStore,
   NonceManager: () => NonceManager,
+  NoopRateLimiter: () => NoopRateLimiter,
   PAFI_ISSUER_SDK_VERSION: () => PAFI_ISSUER_SDK_VERSION,
   PAFI_SUBGRAPH_URL: () => import_core15.PAFI_SUBGRAPH_URL,
   PTClaimError: () => PTClaimError,
@@ -53,8 +57,12 @@ __export(index_exports, {
   PerpDepositError: () => PerpDepositError,
   PerpDepositHandler: () => PerpDepositHandler,
   PointIndexer: () => PointIndexer,
+  PolicyProvider: () => PolicyProvider,
+  REDEMPTION_HISTORY_WINDOW_SEC: () => REDEMPTION_HISTORY_WINDOW_SEC,
+  RedemptionService: () => RedemptionService,
   RelayError: () => RelayError,
   RelayService: () => RelayService,
+  SettlementClient: () => SettlementClient,
   ValidationError: () => import_core3.ValidationError,
   authenticateRequest: () => authenticateRequest,
   createIssuerService: () => createIssuerService,
@@ -62,6 +70,8 @@ __export(index_exports, {
   createSdkErrorMapper: () => createSdkErrorMapper,
   createSubgraphNativeUsdtQuoter: () => createSubgraphNativeUsdtQuoter,
   createSubgraphPoolsProvider: () => createSubgraphPoolsProvider,
+  defaultPolicyFor: () => defaultPolicyFor,
+  evaluateRedemption: () => evaluateRedemption,
   handleClaimStatus: () => handleClaimStatus,
   handleDelegateSubmit: () => handleDelegateSubmit,
   handleMobilePrepare: () => handleMobilePrepare,
@@ -161,9 +171,9 @@ var MemorySessionStore = class {
   nonceTtlMs;
   now;
   constructor(opts = {}) {
-    if (process.env.NODE_ENV === "production") {
-      console.error(
-        "[PAFI] MemorySessionStore is not safe for multi-process/K8s deployments. Session revocations are NOT propagated across pods. Use a Redis-backed session store in production."
+    if (process.env.NODE_ENV === "production" && !opts.dangerouslyAllowMemoryStoreInProduction) {
+      throw new Error(
+        "[PAFI] MemorySessionStore refuses to start in production (NODE_ENV=production). Multi-pod K8s deploys do not share Map state, so sessions are not revocable across replicas \u2014 `logout` on pod A leaves the token valid on pod B until expiry. Use a Redis-backed session store (see RedisSessionStoreService in gg56-backend or implement your own ISessionStore). To bypass for a single-pod deploy, pass `dangerouslyAllowMemoryStoreInProduction: true`."
       );
     }
     this.nonceTtlMs = opts.nonceTtlMs ?? DEFAULT_NONCE_TTL_MS;
@@ -290,6 +300,64 @@ var AuthError = class extends import_core.PafiSdkError {
 };
 
 // src/auth/loginVerifier.ts
+function assertJwtSecretStrength(secret) {
+  if (!secret) {
+    throw new Error(
+      "AuthService: jwtSecret is required. Generate via `node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"`"
+    );
+  }
+  if (secret.length < 32) {
+    throw new Error(
+      `AuthService: jwtSecret too short (${secret.length} chars; need \u2265 32). HS256 brute-force becomes feasible below this threshold.`
+    );
+  }
+  const uniqueChars = new Set(secret).size;
+  if (uniqueChars < 16) {
+    throw new Error(
+      `AuthService: jwtSecret has only ${uniqueChars} unique characters; need \u2265 16. A trivially weak secret (e.g. "aaaaa...") will pass length but offer almost no entropy. Use \`crypto.randomBytes(32).toString('hex')\`.`
+    );
+  }
+  const entropy = shannonEntropyBitsPerChar(secret);
+  if (entropy < 3.5) {
+    throw new Error(
+      `AuthService: jwtSecret entropy too low (${entropy.toFixed(2)} bits/char; need \u2265 3.5). Use \`crypto.randomBytes(32).toString('hex')\` (\u2248 4.0 bits/char).`
+    );
+  }
+  for (let period = 1; period <= secret.length / 4; period++) {
+    if (secret.length % period !== 0) continue;
+    const head = secret.slice(0, period);
+    if (secret === head.repeat(secret.length / period)) {
+      throw new Error(
+        `AuthService: jwtSecret is a repeating pattern of period ${period}. Use \`crypto.randomBytes(32).toString('hex')\`.`
+      );
+    }
+  }
+}
+function shannonEntropyBitsPerChar(s) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const c of s) counts.set(c, (counts.get(c) ?? 0) + 1);
+  const len = s.length;
+  let h = 0;
+  for (const n of counts.values()) {
+    const p = n / len;
+    h -= p * Math.log2(p);
+  }
+  return h;
+}
+function decodeExpiredJwtJti(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return {};
+    const payloadB64 = parts[1];
+    if (!payloadB64) return {};
+    const padded = payloadB64.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((payloadB64.length + 3) % 4);
+    const json = Buffer.from(padded, "base64").toString("utf-8");
+    const claims = JSON.parse(json);
+    return typeof claims.jti === "string" ? { jti: claims.jti } : {};
+  } catch {
+    return {};
+  }
+}
 var DEFAULT_EXPIRES_IN = "24h";
 var AuthService = class {
   sessionStore;
@@ -297,17 +365,19 @@ var AuthService = class {
   jwtExpiresIn;
   domain;
   chainId;
+  issuer;
+  audience;
   nonceManager;
   now;
   constructor(config) {
-    if (!config.jwtSecret || config.jwtSecret.length < 32) {
-      throw new Error("AuthService: jwtSecret must be at least 32 characters for HS256 security");
-    }
+    assertJwtSecretStrength(config.jwtSecret);
     this.sessionStore = config.sessionStore;
     this.jwtSecret = new TextEncoder().encode(config.jwtSecret);
     this.jwtExpiresIn = config.jwtExpiresIn ?? DEFAULT_EXPIRES_IN;
     this.domain = config.domain;
     this.chainId = config.chainId;
+    this.issuer = config.issuer;
+    this.audience = config.audience;
     this.nonceManager = new NonceManager(config.sessionStore);
     this.now = config.now ?? (() => /* @__PURE__ */ new Date());
   }
@@ -384,29 +454,59 @@ var AuthService = class {
       expiresAt
     };
     await this.sessionStore.createSession(session);
-    const token = await new import_jose.SignJWT({
+    let signer = new import_jose.SignJWT({
       userAddress,
       chainId: this.chainId
-    }).setProtectedHeader({ alg: "HS256" }).setJti(tokenId).setIssuedAt(Math.floor(issuedAt.getTime() / 1e3)).setExpirationTime(Math.floor(expiresAt.getTime() / 1e3)).sign(this.jwtSecret);
+    }).setProtectedHeader({ alg: "HS256" }).setJti(tokenId).setIssuedAt(Math.floor(issuedAt.getTime() / 1e3)).setExpirationTime(Math.floor(expiresAt.getTime() / 1e3));
+    if (this.issuer) signer = signer.setIssuer(this.issuer);
+    if (this.audience) signer = signer.setAudience(this.audience);
+    const token = await signer.sign(this.jwtSecret);
     return { token, userAddress, tokenId, expiresAt };
   }
   /** Revoke the session backing the given JWT (logout). */
   async logout(token) {
+    let payload;
     try {
-      const { payload } = await (0, import_jose.jwtVerify)(token, this.jwtSecret, {
-        clockTolerance: 60
+      const result = await (0, import_jose.jwtVerify)(token, this.jwtSecret, {
+        clockTolerance: 60,
         // allow logout right after expiry
+        ...this.issuer ? { issuer: this.issuer } : {},
+        ...this.audience ? { audience: this.audience } : {}
       });
-      if (payload.jti) {
-        await this.sessionStore.revokeSession(payload.jti);
-      }
+      payload = result.payload;
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (!msg.includes("not found") && !msg.includes("expired")) {
-        console.error("[PAFI] AuthService logout: session store error", err);
+      if (err instanceof import_jose.errors.JWTExpired) {
+        const decoded = decodeExpiredJwtJti(token);
+        if (decoded.jti) {
+          try {
+            await this.sessionStore.revokeSession(decoded.jti);
+          } catch (storeErr) {
+            this.logSessionStoreError(storeErr);
+          }
+        }
+        return;
+      }
+      if (err instanceof import_jose.errors.JWSSignatureVerificationFailed || err instanceof import_jose.errors.JWSInvalid || err instanceof import_jose.errors.JWTInvalid) {
+        throw new AuthError("TOKEN_INVALID", "JWT verification failed");
+      }
+      throw new AuthError(
+        "TOKEN_INVALID",
+        `JWT verification failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (payload.jti) {
+      try {
+        await this.sessionStore.revokeSession(payload.jti);
+      } catch (storeErr) {
+        this.logSessionStoreError(storeErr);
       }
     }
   }
+  logSessionStoreError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("not found")) return;
+    console.error("[PAFI] AuthService logout: session store error", err);
+  }
   /**
    * Verify a JWT and return the authenticated user context. Throws an
    * `AuthError` if the token is missing, malformed, expired, revoked, or
@@ -415,7 +515,10 @@ var AuthService = class {
   async verifyToken(token) {
     let payload;
     try {
-      const result = await (0, import_jose.jwtVerify)(token, this.jwtSecret);
+      const result = await (0, import_jose.jwtVerify)(token, this.jwtSecret, {
+        ...this.issuer ? { issuer: this.issuer } : {},
+        ...this.audience ? { audience: this.audience } : {}
+      });
       payload = result.payload;
     } catch (err) {
       if (err instanceof import_jose.errors.JWTExpired) {
@@ -481,6 +584,70 @@ async function authenticateRequest(authHeader, authService) {
   return authService.verifyToken(token);
 }
 
+// src/auth/rateLimiter.ts
+var DEFAULT_LIMITS = {
+  auth_nonce: { max: 30, windowMs: 6e4 },
+  // 30 nonces/min ≈ 1 per 2s
+  auth_login: { max: 5, windowMs: 6e4 }
+  // 5 logins/min
+};
+var MemoryRateLimiter = class {
+  buckets = /* @__PURE__ */ new Map();
+  limits;
+  now;
+  constructor(config = {}) {
+    if (process.env.NODE_ENV === "production" && !process.env.PAFI_ALLOW_MEMORY_RATE_LIMITER_IN_PROD) {
+      console.warn(
+        "[PAFI] MemoryRateLimiter not safe for multi-pod K8s deploys \u2014 rate counters are NOT shared across replicas, allowing round-robin bypass. Use a Redis-backed IRateLimiter in production."
+      );
+    }
+    this.limits = {
+      ...DEFAULT_LIMITS,
+      ...config.limits ?? {}
+    };
+    this.now = config.now ?? (() => Date.now());
+  }
+  async consume(key, action) {
+    const limit = this.limits[action];
+    if (!limit) return { allowed: true };
+    const bucketKey = `${action}:${key}`;
+    const now = this.now();
+    const bucket = this.buckets.get(bucketKey);
+    if (!bucket || now - bucket.windowStartedAt >= limit.windowMs) {
+      this.buckets.set(bucketKey, { count: 1, windowStartedAt: now });
+      return { allowed: true };
+    }
+    if (bucket.count < limit.max) {
+      bucket.count += 1;
+      return { allowed: true };
+    }
+    const retryAfterMs = Math.max(
+      0,
+      bucket.windowStartedAt + limit.windowMs - now
+    );
+    return { allowed: false, retryAfterMs };
+  }
+  /**
+   * Test helper — clear all buckets. Not part of `IRateLimiter`; only
+   * exposed on the in-memory impl for unit tests.
+   */
+  reset() {
+    this.buckets.clear();
+  }
+};
+var NoopRateLimiter = class {
+  warned = false;
+  async consume() {
+    if (!this.warned && process.env.NODE_ENV === "production") {
+      console.warn(
+        "[PAFI] NoopRateLimiter active \u2014 `/auth/nonce` and `/auth/login` are NOT throttled. Wire a `MemoryRateLimiter` (dev) or Redis-backed impl (prod) via `IssuerApiHandlersConfig.rateLimiter`."
+      );
+      this.warned = true;
+    }
+    return { allowed: true };
+  }
+};
+
 // src/relay/types.ts
 var RelayError = class extends import_core.PafiSdkError {
   httpStatus = "unprocessable";
@@ -828,6 +995,7 @@ var PointIndexer = class {
   confirmations;
   batchSize;
   pollIntervalMs;
+  onTickError;
   running = false;
   timer;
   constructor(config) {
@@ -843,6 +1011,7 @@ var PointIndexer = class {
     this.confirmations = BigInt(config.confirmations ?? DEFAULT_CONFIRMATIONS);
     this.batchSize = BigInt(config.batchSize ?? Number(DEFAULT_BATCH_SIZE));
     this.pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (config.onTickError) this.onTickError = config.onTickError;
   }
   // -------------------------------------------------------------------------
   // Lifecycle
@@ -851,7 +1020,7 @@ var PointIndexer = class {
   start() {
     if (this.running) return;
     this.running = true;
-    void this.tick();
+    this.tick().catch((err) => this.handleTickError(err));
   }
   /** Stop polling. Safe to call multiple times. */
   stop() {
@@ -883,13 +1052,27 @@ var PointIndexer = class {
       }
       await this.processBlockRange(from, safeHead);
     } catch (err) {
-      console.error("[PAFI] PointIndexer tick error:", err);
+      this.handleTickError(err);
     }
     this.scheduleNext();
   }
+  handleTickError(err) {
+    if (this.onTickError) {
+      try {
+        this.onTickError(err);
+      } catch {
+        console.error("[PAFI] PointIndexer onTickError threw:", err);
+      }
+    } else {
+      console.error("[PAFI] PointIndexer tick error:", err);
+    }
+  }
   scheduleNext() {
     if (!this.running) return;
-    this.timer = setTimeout(() => void this.tick(), this.pollIntervalMs);
+    this.timer = setTimeout(
+      () => this.tick().catch((err) => this.handleTickError(err)),
+      this.pollIntervalMs
+    );
   }
   // -------------------------------------------------------------------------
   // Block scanning
@@ -1009,6 +1192,7 @@ var BurnIndexer = class {
   confirmations;
   batchSize;
   pollIntervalMs;
+  onTickError;
   matchLockId;
   running = false;
   timer;
@@ -1027,6 +1211,7 @@ var BurnIndexer = class {
     );
     this.batchSize = BigInt(config.batchSize ?? Number(DEFAULT_BATCH_SIZE2));
     this.pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS2;
+    if (config.onTickError) this.onTickError = config.onTickError;
     if (!config.matchLockId) {
       throw new Error(
         "BurnIndexer: matchLockId is required. Provide a function that maps a burn event to its pending credit lockId. Without it, no on-chain burns will ever grant off-chain credits."
@@ -1037,7 +1222,7 @@ var BurnIndexer = class {
   start() {
     if (this.running) return;
     this.running = true;
-    void this.tick();
+    this.tick().catch((err) => this.handleTickError(err));
   }
   stop() {
     this.running = false;
@@ -1063,13 +1248,27 @@ var BurnIndexer = class {
       }
       await this.processBlockRange(from, safeHead);
     } catch (err) {
-      console.error("[PAFI] BurnIndexer tick error:", err);
+      this.handleTickError(err);
     }
     this.scheduleNext();
   }
+  handleTickError(err) {
+    if (this.onTickError) {
+      try {
+        this.onTickError(err);
+      } catch {
+        console.error("[PAFI] BurnIndexer onTickError threw:", err);
+      }
+    } else {
+      console.error("[PAFI] BurnIndexer tick error:", err);
+    }
+  }
   scheduleNext() {
     if (!this.running) return;
-    this.timer = setTimeout(() => void this.tick(), this.pollIntervalMs);
+    this.timer = setTimeout(
+      () => this.tick().catch((err) => this.handleTickError(err)),
+      this.pollIntervalMs
+    );
   }
   /**
    * Scan `[from, to]` inclusive for burn events. Callers can drive this
@@ -1162,10 +1361,13 @@ var IssuerApiHandlers = class {
   pafiWebUrl;
   feeManager;
   poolsProvider;
+  redemption;
+  rateLimiter;
   constructor(config) {
     this.authService = config.authService;
     this.ledger = config.ledger;
     this.provider = config.provider;
+    this.rateLimiter = config.rateLimiter ?? new NoopRateLimiter();
     const raw = config.pointTokenAddresses && config.pointTokenAddresses.length > 0 ? config.pointTokenAddresses : config.pointTokenAddress ? [config.pointTokenAddress] : [];
     if (raw.length === 0) {
       throw new Error(
@@ -1179,17 +1381,64 @@ var IssuerApiHandlers = class {
     if (config.pafiWebUrl) this.pafiWebUrl = config.pafiWebUrl;
     if (config.feeManager) this.feeManager = config.feeManager;
     if (config.poolsProvider) this.poolsProvider = config.poolsProvider;
+    if (config.redemption) this.redemption = config.redemption;
   }
   // =========================================================================
   // Public handlers (no auth required)
   // =========================================================================
-  /** `GET /auth/nonce` */
-  async handleGetNonce() {
+  /**
+   * `GET /auth/nonce`
+   *
+   * @param rateLimitKey  Caller-side rate-limit key (typically client IP).
+   *                      The HTTP layer (controller/middleware) extracts
+   *                      this from the request and passes it through.
+   *                      When omitted, no rate limit applies — production
+   *                      callers SHOULD always pass a key.
+   */
+  async handleGetNonce(rateLimitKey) {
+    if (rateLimitKey) {
+      const result = await this.rateLimiter.consume(
+        rateLimitKey,
+        "auth_nonce"
+      );
+      if (!result.allowed) {
+        throw new import_core3.ValidationError(
+          "RATE_LIMIT_EXCEEDED",
+          "handleGetNonce: too many requests",
+          {
+            retryAfterMs: result.retryAfterMs ?? 0,
+            action: "auth_nonce"
+          }
+        );
+      }
+    }
     const nonce = await this.authService.getNonce();
     return { nonce };
   }
-  /** `POST /auth/login` */
-  async handleLogin(body) {
+  /**
+   * `POST /auth/login`
+   *
+   * @param body          Login message + signature.
+   * @param rateLimitKey  Caller-side rate-limit key (typically client IP
+   *                      or `body.userAddress` if known). See `handleGetNonce`.
+   */
+  async handleLogin(body, rateLimitKey) {
+    if (rateLimitKey) {
+      const result2 = await this.rateLimiter.consume(
+        rateLimitKey,
+        "auth_login"
+      );
+      if (!result2.allowed) {
+        throw new import_core3.ValidationError(
+          "RATE_LIMIT_EXCEEDED",
+          "handleLogin: too many requests",
+          {
+            retryAfterMs: result2.retryAfterMs ?? 0,
+            action: "auth_login"
+          }
+        );
+      }
+    }
     if (!body || typeof body.message !== "string" || body.message.length === 0 || typeof body.signature !== "string" || body.signature.length <= 2) {
       throw new import_core3.ValidationError(
         "INVALID_LOGIN_BODY",
@@ -1332,6 +1581,74 @@ var IssuerApiHandlers = class {
   // Note: legacy `handleClaim` (sync sponsored-claim returning calls[]) was
   // removed in 0.5.43 — callers should use `PTClaimHandler` directly or
   // wire `IssuerApiAdapter.claim()` which composes the full flow.
+  /**
+   * `GET /redemption/preview?pointToken=<addr>`
+   *
+   * Returns the headroom currently available to `userAddress` under the
+   * configured RedemptionPolicy. Pure read — does not record anything.
+   * Use this for UI to render "X PT redeemable now / next available at …".
+   */
+  async handleRedemptionPreview(userAddress, request) {
+    if (!this.redemption) {
+      throw new ConfigurationError(
+        "REDEMPTION_NOT_CONFIGURED",
+        "handleRedemptionPreview: redemption is not configured on this issuer"
+      );
+    }
+    const tokenAddress = request.pointTokenAddress ? this.requireSupportedToken((0, import_viem6.getAddress)(request.pointTokenAddress), "handleRedemptionPreview") : void 0;
+    const preview = await this.redemption.preview(
+      (0, import_viem6.getAddress)(userAddress),
+      tokenAddress
+    );
+    return preview;
+  }
+  /**
+   * `POST /redemption/evaluate`
+   *
+   * Pre-flight check before the issuer signs a BurnRequest. Returns
+   * { allowed, denial?, preview }. Caller (the burn-orchestrator) MUST
+   * re-check on the actual initiate path — evaluate is read-only and a
+   * caller could race two requests under the same headroom. The intended
+   * write path is: evaluate → sign BurnRequest → reserve pending credit
+   * → call `service.redemption.recordSuccessfulInitiate()`.
+   */
+  async handleRedemptionEvaluate(userAddress, request) {
+    if (!this.redemption) {
+      throw new ConfigurationError(
+        "REDEMPTION_NOT_CONFIGURED",
+        "handleRedemptionEvaluate: redemption is not configured on this issuer"
+      );
+    }
+    if (request.amountPt <= 0n) {
+      throw new import_core3.ValidationError(
+        "INVALID_AMOUNT",
+        "handleRedemptionEvaluate: amountPt must be positive",
+        { amountPt: request.amountPt.toString() }
+      );
+    }
+    const tokenAddress = request.pointTokenAddress ? this.requireSupportedToken((0, import_viem6.getAddress)(request.pointTokenAddress), "handleRedemptionEvaluate") : void 0;
+    const decision = await this.redemption.evaluate(
+      (0, import_viem6.getAddress)(userAddress),
+      request.amountPt,
+      tokenAddress
+    );
+    const response = {
+      allowed: decision.allowed,
+      preview: decision.preview
+    };
+    if (decision.denial) response.denial = decision.denial;
+    return response;
+  }
+  requireSupportedToken(pointToken, handler) {
+    if (!this.supportedTokens.has(pointToken)) {
+      throw new import_core3.ValidationError(
+        "UNSUPPORTED_POINT_TOKEN",
+        `${handler}: unsupported pointToken ${pointToken}`,
+        { requested: pointToken }
+      );
+    }
+    return pointToken;
+  }
 };
 
 // src/api/handlers/ptRedeemHandler.ts
@@ -1342,9 +1659,13 @@ var DEFAULT_SIG_DEADLINE_SEC = 15 * 60;
 var PTRedeemError = class extends import_core.PafiSdkError {
   httpStatus = "unprocessable";
   code;
-  constructor(code, message) {
+  policyDenialCode;
+  constructor(code, message, options) {
     super(message);
     this.code = code;
+    if (options?.policyDenialCode) {
+      this.policyDenialCode = options.policyDenialCode;
+    }
   }
 };
 var PTRedeemHandler = class {
@@ -1360,6 +1681,7 @@ var PTRedeemHandler = class {
   redeemLockDurationMs;
   signatureDeadlineSeconds;
   now;
+  redemptionService;
   /**
    * Per-user in-flight nonce guard (single-process only).
    *
@@ -1402,6 +1724,9 @@ var PTRedeemHandler = class {
     this.redeemLockDurationMs = config.redeemLockDurationMs ?? DEFAULT_REDEEM_LOCK_MS;
     this.signatureDeadlineSeconds = config.signatureDeadlineSeconds ?? DEFAULT_SIG_DEADLINE_SEC;
     this.now = config.now ?? (() => Date.now());
+    if (config.redemptionService) {
+      this.redemptionService = config.redemptionService;
+    }
   }
   async handle(request) {
     if ((0, import_viem7.getAddress)(request.authenticatedAddress) !== (0, import_viem7.getAddress)(request.userAddress)) {
@@ -1413,6 +1738,21 @@ var PTRedeemHandler = class {
     if (request.amount <= 0n) {
       throw new PTRedeemError("INVALID_AMOUNT", "redeem amount must be positive");
     }
+    if (this.redemptionService) {
+      const decision = await this.redemptionService.evaluate(
+        request.userAddress,
+        request.amount,
+        this.pointTokenAddress
+      );
+      if (!decision.allowed) {
+        const denial = decision.denial;
+        throw new PTRedeemError(
+          "REDEMPTION_POLICY_DENIED",
+          `redemption denied: ${denial.message}`,
+          { policyDenialCode: denial.code }
+        );
+      }
+    }
     let burnNonce;
     try {
       burnNonce = await this.provider.readContract({
@@ -1566,6 +1906,15 @@ var PTRedeemHandler = class {
           netCreditAmount: request.amount
         };
       }
+      if (this.redemptionService) {
+        await this.redemptionService.recordSuccessfulInitiate({
+          user: request.userAddress,
+          amountPt: request.amount,
+          pointTokenAddress: this.pointTokenAddress,
+          reservationId: sponsoredLockId
+        }).catch(() => {
+        });
+      }
       return {
         lockId: sponsoredLockId,
         userOp: sponsoredUserOp,
@@ -3289,6 +3638,7 @@ var BalanceAggregator = class {
 };
 
 // src/pafi-backend/client.ts
+var import_core17 = require("@pafi-dev/core");
 function serializeBigInt(_key, value) {
   return typeof value === "bigint" ? value.toString(10) : value;
 }
@@ -3297,10 +3647,13 @@ function sleep(ms) {
 }
 var PafiBackendClient = class {
   config;
+  baseUrl;
   constructor(config) {
-    if (!config.url) throw new Error("PafiBackendClient: url is required");
+    if (!config.chainId) throw new Error("PafiBackendClient: chainId is required");
     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 = (0, import_core17.getPafiServiceUrls)(config.chainId).sponsorRelayer;
   }
   async requestSponsorship(request) {
     const maxAttempts = this.config.retry?.maxAttempts ?? 1;
@@ -3335,7 +3688,7 @@ var PafiBackendClient = class {
    */
   async getUserOpReceipt(userOpHash) {
     const fetchFn = this.config.fetchImpl ?? fetch;
-    const url = `${this.config.url}/bundler/receipt`;
+    const url = `${this.baseUrl}/bundler/receipt`;
     let response;
     try {
       response = await fetchFn(url, {
@@ -3374,7 +3727,7 @@ var PafiBackendClient = class {
   }
   async relayUserOperation(request) {
     const fetchFn = this.config.fetchImpl ?? fetch;
-    const url = `${this.config.url}/bundler/relay`;
+    const url = `${this.baseUrl}/bundler/relay`;
     let response;
     try {
       response = await fetchFn(url, {
@@ -3408,7 +3761,7 @@ var PafiBackendClient = class {
   }
   async _doRequest(request) {
     const fetchFn = this.config.fetchImpl ?? fetch;
-    const url = `${this.config.url}/paymaster/sponsor`;
+    const url = `${this.baseUrl}/paymaster/sponsor`;
     const body = JSON.stringify(request, serializeBigInt);
     let response;
     try {
@@ -3463,7 +3816,313 @@ var PafiBackendClient = class {
 
 // src/config.ts
 var import_viem14 = require("viem");
-var import_core17 = require("@pafi-dev/core");
+var import_core19 = require("@pafi-dev/core");
+
+// src/redemption/evaluator.ts
+var SECONDS_PER_DAY = 24 * 60 * 60;
+function evaluateRedemption(input) {
+  const { policy, history, amountPt, nowUnixSec, policySource } = input;
+  const dailyRemaining = policy.dailyLimitPt > history.redeemedLast24hPt ? policy.dailyLimitPt - history.redeemedLast24hPt : 0n;
+  const cooldownUntilUnixSec = history.lastRedeemedAtUnixSec !== null ? history.lastRedeemedAtUnixSec + policy.cooldownSec : null;
+  const inCooldown = cooldownUntilUnixSec !== null && cooldownUntilUnixSec > nowUnixSec;
+  const activeBlackout = findActiveBlackout(policy.blackoutWindows, nowUnixSec);
+  const nextBlackoutEnd = nextBlackoutEndAfter(
+    policy.blackoutWindows,
+    nowUnixSec
+  );
+  let availableAmountPt = 0n;
+  if (!inCooldown && !activeBlackout) {
+    const headroom = dailyRemaining < policy.perTxMaxPt ? dailyRemaining : policy.perTxMaxPt;
+    availableAmountPt = headroom >= policy.perTxMinPt ? headroom : 0n;
+  }
+  const preview = {
+    availableAmountPt,
+    dailyRemainingPt: dailyRemaining,
+    cooldownUntilUnixSec: inCooldown ? cooldownUntilUnixSec : null,
+    nextBlackoutEndsAtUnixSec: activeBlackout ? activeBlackout.endUnixSec : nextBlackoutEnd,
+    perTxMinPt: policy.perTxMinPt,
+    perTxMaxPt: policy.perTxMaxPt,
+    policyVersion: policy.version,
+    policySource
+  };
+  if (amountPt <= 0n) {
+    return { allowed: false, preview, denial: rejectAmountBelowMin(policy) };
+  }
+  const denial = firstDenial({
+    amountPt,
+    policy,
+    dailyRemaining,
+    inCooldown,
+    cooldownUntilUnixSec,
+    activeBlackout
+  });
+  if (denial) return { allowed: false, denial, preview };
+  return { allowed: true, preview };
+}
+function firstDenial(args) {
+  const { amountPt, policy, dailyRemaining, inCooldown, cooldownUntilUnixSec, activeBlackout } = args;
+  if (activeBlackout) {
+    return {
+      code: "BLACKOUT_WINDOW",
+      message: `Redemption is blocked until ${new Date(
+        activeBlackout.endUnixSec * 1e3
+      ).toISOString()}${activeBlackout.reason ? ` (${activeBlackout.reason})` : ""}`
+    };
+  }
+  if (inCooldown && cooldownUntilUnixSec !== null) {
+    return {
+      code: "COOLDOWN_ACTIVE",
+      message: `Cooldown active until ${new Date(
+        cooldownUntilUnixSec * 1e3
+      ).toISOString()}`
+    };
+  }
+  if (amountPt < policy.perTxMinPt) {
+    return {
+      code: "AMOUNT_BELOW_MIN",
+      message: `amount ${amountPt} below per-tx minimum ${policy.perTxMinPt}`
+    };
+  }
+  if (amountPt > policy.perTxMaxPt) {
+    return {
+      code: "AMOUNT_ABOVE_MAX",
+      message: `amount ${amountPt} above per-tx maximum ${policy.perTxMaxPt}`
+    };
+  }
+  if (amountPt > dailyRemaining) {
+    return {
+      code: "DAILY_LIMIT_EXCEEDED",
+      message: `amount ${amountPt} exceeds daily remaining ${dailyRemaining}`
+    };
+  }
+  return null;
+}
+function rejectAmountBelowMin(policy) {
+  return {
+    code: "AMOUNT_BELOW_MIN",
+    message: `amount must be >= ${policy.perTxMinPt}`
+  };
+}
+function findActiveBlackout(windows, nowUnixSec) {
+  for (const w of windows) {
+    if (w.startUnixSec <= nowUnixSec && nowUnixSec < w.endUnixSec) return w;
+  }
+  return null;
+}
+function nextBlackoutEndAfter(windows, nowUnixSec) {
+  let earliest = null;
+  for (const w of windows) {
+    if (w.endUnixSec > nowUnixSec) {
+      if (earliest === null || w.endUnixSec < earliest) earliest = w.endUnixSec;
+    }
+  }
+  return earliest;
+}
+var REDEMPTION_HISTORY_WINDOW_SEC = SECONDS_PER_DAY;
+
+// src/redemption/settlementClient.ts
+var import_core18 = require("@pafi-dev/core");
+var DEFAULT_TIMEOUT_MS = 1e3;
+var SettlementClient = class {
+  config;
+  constructor(config) {
+    if (!config.chainId) throw new Error("SettlementClient: chainId is required");
+    if (!config.issuerId) throw new Error("SettlementClient: issuerId is required");
+    if (!config.apiKey) throw new Error("SettlementClient: apiKey is required");
+    this.config = {
+      baseUrl: (0, import_core18.getPafiServiceUrls)(config.chainId).issuerApi.replace(/\/+$/, ""),
+      issuerId: config.issuerId,
+      apiKey: config.apiKey,
+      fetchTimeoutMs: config.fetchTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+      fetchImpl: config.fetchImpl
+    };
+  }
+  async fetchPolicy() {
+    const fetchFn = this.config.fetchImpl ?? fetch;
+    const url = `${this.config.baseUrl}/issuers/${encodeURIComponent(this.config.issuerId)}/redemption-policy`;
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      this.config.fetchTimeoutMs
+    );
+    let response;
+    try {
+      response = await fetchFn(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-Issuer-Id": this.config.issuerId
+        },
+        signal: controller.signal
+      });
+    } catch (err) {
+      const isAbort = err instanceof Error && (err.name === "AbortError" || /aborted|timeout/i.test(err.message ?? ""));
+      return { ok: false, reason: isAbort ? "TIMEOUT" : "NETWORK" };
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status === 404) {
+      return { ok: false, reason: "NOT_FOUND", status: 404 };
+    }
+    if (response.status === 401 || response.status === 403) {
+      return { ok: false, reason: "UNAUTHORIZED", status: response.status };
+    }
+    if (!response.ok) {
+      return { ok: false, reason: "SERVER_ERROR", status: response.status };
+    }
+    let raw;
+    try {
+      raw = await response.json();
+    } catch {
+      return { ok: false, reason: "INVALID_RESPONSE", status: response.status };
+    }
+    const parsed = parsePolicyDto(raw);
+    if (!parsed) {
+      return { ok: false, reason: "INVALID_RESPONSE", status: response.status };
+    }
+    return { ok: true, policy: parsed };
+  }
+};
+function parsePolicyDto(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const dto = raw;
+  if (typeof dto.issuerId !== "string" || typeof dto.dailyLimitPt !== "string" || typeof dto.cooldownSec !== "number" || typeof dto.perTxMinPt !== "string" || typeof dto.perTxMaxPt !== "string" || typeof dto.version !== "string" || !Array.isArray(dto.blackoutWindows)) {
+    return null;
+  }
+  try {
+    return {
+      issuerId: dto.issuerId,
+      dailyLimitPt: BigInt(dto.dailyLimitPt),
+      cooldownSec: dto.cooldownSec,
+      perTxMinPt: BigInt(dto.perTxMinPt),
+      perTxMaxPt: BigInt(dto.perTxMaxPt),
+      blackoutWindows: dto.blackoutWindows.map(normalizeBlackout).filter((b) => b !== null),
+      version: dto.version
+    };
+  } catch {
+    return null;
+  }
+}
+function normalizeBlackout(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const win = raw;
+  if (typeof win.startUnixSec !== "number" || typeof win.endUnixSec !== "number" || win.startUnixSec >= win.endUnixSec) {
+    return null;
+  }
+  return {
+    startUnixSec: win.startUnixSec,
+    endUnixSec: win.endUnixSec,
+    reason: typeof win.reason === "string" ? win.reason : void 0
+  };
+}
+
+// src/redemption/defaults.ts
+var PT_DECIMALS = 10n ** 18n;
+var DEFAULT_REDEMPTION_POLICY = {
+  issuerId: "default",
+  dailyLimitPt: 1000n * PT_DECIMALS,
+  cooldownSec: 60,
+  perTxMinPt: 1n * PT_DECIMALS,
+  perTxMaxPt: 500n * PT_DECIMALS,
+  blackoutWindows: [],
+  version: "default-v1"
+};
+function defaultPolicyFor(issuerId) {
+  return { ...DEFAULT_REDEMPTION_POLICY, issuerId };
+}
+
+// src/redemption/policyProvider.ts
+var DEFAULT_CACHE_TTL_MS3 = 5 * 60 * 1e3;
+var PolicyProvider = class {
+  client;
+  issuerId;
+  cacheTtlMs;
+  now;
+  cache = null;
+  inflight = null;
+  constructor(config) {
+    this.client = new SettlementClient(config);
+    this.issuerId = config.issuerId;
+    this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS3;
+    this.now = config.now ?? (() => Date.now());
+  }
+  async getPolicy() {
+    const fresh = this.readCache();
+    if (fresh) return { policy: fresh, source: "cache" };
+    if (this.inflight) return this.inflight;
+    this.inflight = this.fetchAndStore().finally(() => {
+      this.inflight = null;
+    });
+    return this.inflight;
+  }
+  /** Drop cached policy. Next getPolicy() will refetch. */
+  invalidate() {
+    this.cache = null;
+  }
+  readCache() {
+    if (!this.cache) return null;
+    if (this.cache.expiresAtMs <= this.now()) {
+      this.cache = null;
+      return null;
+    }
+    return this.cache.policy;
+  }
+  async fetchAndStore() {
+    const result = await this.client.fetchPolicy();
+    if (result.ok) {
+      this.cache = {
+        policy: result.policy,
+        expiresAtMs: this.now() + this.cacheTtlMs
+      };
+      return { policy: result.policy, source: "settlement" };
+    }
+    return { policy: defaultPolicyFor(this.issuerId), source: "default" };
+  }
+};
+
+// src/redemption/service.ts
+var RedemptionService = class {
+  policyProvider;
+  historyStore;
+  nowUnixSec;
+  constructor(config) {
+    this.policyProvider = config.policyProvider instanceof PolicyProvider ? config.policyProvider : new PolicyProvider(config.policyProvider);
+    this.historyStore = config.historyStore;
+    this.nowUnixSec = config.nowUnixSec ?? (() => Math.floor(Date.now() / 1e3));
+  }
+  async preview(user, pointTokenAddress) {
+    const decision = await this.evaluate(user, 0n, pointTokenAddress);
+    return decision.preview;
+  }
+  async evaluate(user, amountPt, pointTokenAddress) {
+    const { policy, source } = await this.policyProvider.getPolicy();
+    const now = this.nowUnixSec();
+    const [redeemedLast24hPt, lastRedeemedAtUnixSec] = await Promise.all([
+      this.historyStore.sumRedeemedSince(
+        user,
+        now - REDEMPTION_HISTORY_WINDOW_SEC,
+        pointTokenAddress
+      ),
+      this.historyStore.getLastRedeemedAtUnixSec(user, pointTokenAddress)
+    ]);
+    return evaluateRedemption({
+      policy,
+      policySource: source,
+      history: { redeemedLast24hPt, lastRedeemedAtUnixSec },
+      amountPt,
+      nowUnixSec: now
+    });
+  }
+  async recordSuccessfulInitiate(entry) {
+    await this.historyStore.recordRedemption({
+      ...entry,
+      unixSec: this.nowUnixSec()
+    });
+  }
+};
+
+// src/config.ts
 function createIssuerService(config) {
   if (!config.provider) {
     throw new Error("createIssuerService: provider is required");
@@ -3533,7 +4192,7 @@ function createIssuerService(config) {
     indexers.set(tokenAddress, new PointIndexer(indexerConfig));
   }
   const firstIndexer = indexers.get(tokenAddresses[0]);
-  const chainAddresses = (0, import_core17.getContractAddresses)(config.chainId);
+  const chainAddresses = (0, import_core19.getContractAddresses)(config.chainId);
   const resolvedContracts = {
     batchExecutor: chainAddresses.batchExecutor,
     usdt: chainAddresses.usdt,
@@ -3542,6 +4201,25 @@ function createIssuerService(config) {
     pafiHook: chainAddresses.pafiHook,
     ...config.contracts
   };
+  let redemption;
+  if (config.redemption) {
+    const policyConfig = {
+      chainId: config.chainId,
+      issuerId: config.redemption.issuerId,
+      apiKey: config.redemption.apiKey
+    };
+    if (config.redemption.fetchImpl) policyConfig.fetchImpl = config.redemption.fetchImpl;
+    if (config.redemption.fetchTimeoutMs !== void 0) {
+      policyConfig.fetchTimeoutMs = config.redemption.fetchTimeoutMs;
+    }
+    if (config.redemption.cacheTtlMs !== void 0) {
+      policyConfig.cacheTtlMs = config.redemption.cacheTtlMs;
+    }
+    redemption = new RedemptionService({
+      policyProvider: new PolicyProvider(policyConfig),
+      historyStore: config.redemption.historyStore
+    });
+  }
   const handlersConfig = {
     authService,
     ledger,
@@ -3552,6 +4230,7 @@ function createIssuerService(config) {
   };
   if (feeManager) handlersConfig.feeManager = feeManager;
   if (config.poolsProvider) handlersConfig.poolsProvider = config.poolsProvider;
+  if (redemption) handlersConfig.redemption = redemption;
   const handlers = new IssuerApiHandlers(handlersConfig);
   if (config.indexer?.autoStart) {
     for (const idx of indexers.values()) {
@@ -3567,13 +4246,14 @@ function createIssuerService(config) {
     fee: feeManager,
     indexers,
     indexer: firstIndexer,
-    api: handlers
+    api: handlers,
+    redemption
   };
 }
 
 // src/issuer-state/validator.ts
 var import_viem15 = require("viem");
-var import_core18 = require("@pafi-dev/core");
+var import_core20 = require("@pafi-dev/core");
 var ISSUER_RECORD_TTL_MS = 3e4;
 var IssuerStateValidator = class _IssuerStateValidator {
   constructor(provider, registryAddress) {
@@ -3590,7 +4270,7 @@ var IssuerStateValidator = class _IssuerStateValidator {
    * `CONTRACT_ADDRESSES` map for the given chain.
    */
   static forChain(provider, chainId) {
-    const { issuerRegistry } = (0, import_core18.getContractAddresses)(chainId);
+    const { issuerRegistry } = (0, import_core20.getContractAddresses)(chainId);
     return new _IssuerStateValidator(provider, issuerRegistry);
   }
   /**
@@ -3619,7 +4299,7 @@ var IssuerStateValidator = class _IssuerStateValidator {
     if (cached) return cached;
     const issuer = await this.provider.readContract({
       address: key,
-      abi: import_core18.POINT_TOKEN_V2_ABI,
+      abi: import_core20.POINT_TOKEN_V2_ABI,
       functionName: "issuer"
     });
     this.pointTokenIssuerCache.set(key, (0, import_viem15.getAddress)(issuer));
@@ -3700,13 +4380,13 @@ var IssuerStateValidator = class _IssuerStateValidator {
     const [issuerTuple, totalSupply] = await Promise.all([
       this.provider.readContract({
         address: this.registryAddress,
-        abi: import_core18.issuerRegistryGetIssuerFlatAbi,
+        abi: import_core20.issuerRegistryGetIssuerFlatAbi,
         functionName: "getIssuer",
         args: [issuerAddr]
       }),
       this.provider.readContract({
         address: tokenAddr,
-        abi: import_core18.POINT_TOKEN_V2_ABI,
+        abi: import_core20.POINT_TOKEN_V2_ABI,
         functionName: "totalSupply"
       })
     ]);
@@ -3727,8 +4407,44 @@ var IssuerStateValidator = class _IssuerStateValidator {
   }
 };
 
+// src/redemption/memoryHistoryStore.ts
+var MemoryRedemptionHistoryStore = class {
+  entries = [];
+  async sumRedeemedSince(user, sinceUnixSec, pointTokenAddress) {
+    const userKey = user.toLowerCase();
+    const tokenKey = pointTokenAddress?.toLowerCase() ?? null;
+    let total = 0n;
+    for (const e of this.entries) {
+      if (e.user !== userKey) continue;
+      if (e.unixSec < sinceUnixSec) continue;
+      if (tokenKey !== null && e.pointTokenAddress !== tokenKey) continue;
+      total += e.amountPt;
+    }
+    return total;
+  }
+  async getLastRedeemedAtUnixSec(user, pointTokenAddress) {
+    const userKey = user.toLowerCase();
+    const tokenKey = pointTokenAddress?.toLowerCase() ?? null;
+    let latest = null;
+    for (const e of this.entries) {
+      if (e.user !== userKey) continue;
+      if (tokenKey !== null && e.pointTokenAddress !== tokenKey) continue;
+      if (latest === null || e.unixSec > latest) latest = e.unixSec;
+    }
+    return latest;
+  }
+  async recordRedemption(entry) {
+    this.entries.push({
+      user: entry.user.toLowerCase(),
+      amountPt: entry.amountPt,
+      pointTokenAddress: entry.pointTokenAddress?.toLowerCase() ?? null,
+      unixSec: entry.unixSec
+    });
+  }
+};
+
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.7.8" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.8.0" : "dev";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdapterMisconfiguredError,
@@ -3739,6 +4455,7 @@ var PAFI_ISSUER_SDK_VERSION = true ? "0.7.8" : "dev";
   BundlerRejectedError,
   BurnIndexer,
   ConfigurationError,
+  DEFAULT_REDEMPTION_POLICY,
   DefaultPolicyEngine,
   FeeManager,
   InMemoryCursorStore,
@@ -3748,8 +4465,11 @@ var PAFI_ISSUER_SDK_VERSION = true ? "0.7.8" : "dev";
   IssuerStateValidator,
   LockNotFoundError,
   MemoryPendingUserOpStore,
+  MemoryRateLimiter,
+  MemoryRedemptionHistoryStore,
   MemorySessionStore,
   NonceManager,
+  NoopRateLimiter,
   PAFI_ISSUER_SDK_VERSION,
   PAFI_SUBGRAPH_URL,
   PTClaimError,
@@ -3764,8 +4484,12 @@ var PAFI_ISSUER_SDK_VERSION = true ? "0.7.8" : "dev";
   PerpDepositError,
   PerpDepositHandler,
   PointIndexer,
+  PolicyProvider,
+  REDEMPTION_HISTORY_WINDOW_SEC,
+  RedemptionService,
   RelayError,
   RelayService,
+  SettlementClient,
   ValidationError,
   authenticateRequest,
   createIssuerService,
@@ -3773,6 +4497,8 @@ var PAFI_ISSUER_SDK_VERSION = true ? "0.7.8" : "dev";
   createSdkErrorMapper,
   createSubgraphNativeUsdtQuoter,
   createSubgraphPoolsProvider,
+  defaultPolicyFor,
+  evaluateRedemption,
   handleClaimStatus,
   handleDelegateSubmit,
   handleMobilePrepare,