@pafi-dev/issuer 0.3.0-beta.9 → 0.5.0

package/dist/index.js

@@ -1,201 +1,3 @@
-// src/ledger/memoryLedger.ts
-import { getAddress } from "viem";
-var MemoryPointLedger = class {
-  balances = /* @__PURE__ */ new Map();
-  locks = /* @__PURE__ */ new Map();
-  nextLockId = 1;
-  now;
-  constructor(opts = {}) {
-    this.now = opts.now ?? (() => Date.now());
-  }
-  // -------------------------------------------------------------------------
-  // Read
-  // -------------------------------------------------------------------------
-  async getBalance(userAddress, tokenAddress) {
-    const user = getAddress(userAddress);
-    const token = normalizeToken(tokenAddress);
-    this.purgeExpired();
-    const total = this.balances.get(balanceKey(user, token)) ?? 0n;
-    const locked = this.lockedTotalFor(user, token);
-    return total - locked;
-  }
-  async getLockedRequests(userAddress, tokenAddress) {
-    const user = getAddress(userAddress);
-    const token = normalizeToken(tokenAddress);
-    this.purgeExpired();
-    const out = [];
-    for (const lock of this.locks.values()) {
-      if (lock.userAddress === user && lock.status === "PENDING" && (lock.tokenAddress ?? DEFAULT_TOKEN_KEY) === token) {
-        out.push({ ...lock });
-      }
-    }
-    return out;
-  }
-  // -------------------------------------------------------------------------
-  // Write
-  // -------------------------------------------------------------------------
-  async creditBalance(userAddress, amount, _reason, tokenAddress) {
-    if (amount <= 0n) {
-      throw new Error("MemoryPointLedger: credit amount must be positive");
-    }
-    const user = getAddress(userAddress);
-    const token = normalizeToken(tokenAddress);
-    const key = balanceKey(user, token);
-    const current = this.balances.get(key) ?? 0n;
-    this.balances.set(key, current + amount);
-  }
-  async lockForMinting(userAddress, amount, lockDurationMs, tokenAddress) {
-    if (amount <= 0n) {
-      throw new Error("MemoryPointLedger: lock amount must be positive");
-    }
-    if (lockDurationMs <= 0) {
-      throw new Error("MemoryPointLedger: lockDurationMs must be positive");
-    }
-    const user = getAddress(userAddress);
-    const token = normalizeToken(tokenAddress);
-    this.purgeExpired();
-    const total = this.balances.get(balanceKey(user, token)) ?? 0n;
-    const alreadyLocked = this.lockedTotalFor(user, token);
-    const available = total - alreadyLocked;
-    if (available < amount) {
-      throw new Error(
-        `MemoryPointLedger: insufficient balance \u2014 available=${available}, requested=${amount}`
-      );
-    }
-    const lockId = `lock-${this.nextLockId++}`;
-    const now = this.now();
-    const lock = {
-      lockId,
-      userAddress: user,
-      amount,
-      status: "PENDING",
-      createdAt: now,
-      expiresAt: now + lockDurationMs
-    };
-    if (tokenAddress !== void 0) {
-      lock.tokenAddress = getAddress(tokenAddress);
-    }
-    this.locks.set(lockId, lock);
-    return lockId;
-  }
-  async releaseLock(lockId) {
-    const lock = this.locks.get(lockId);
-    if (!lock) return;
-    if (lock.status === "PENDING") {
-      this.locks.delete(lockId);
-    }
-  }
-  async deductBalance(userAddress, amount, txHash, tokenAddress) {
-    if (amount <= 0n) {
-      throw new Error("MemoryPointLedger: deduct amount must be positive");
-    }
-    const user = getAddress(userAddress);
-    const token = normalizeToken(tokenAddress);
-    const key = balanceKey(user, token);
-    const current = this.balances.get(key) ?? 0n;
-    if (current < amount) {
-      throw new Error(
-        `MemoryPointLedger: cannot deduct ${amount} from balance ${current}`
-      );
-    }
-    this.balances.set(key, current - amount);
-    for (const lock of this.locks.values()) {
-      if (lock.userAddress === user && lock.status === "PENDING" && lock.amount === amount && (lock.tokenAddress ?? DEFAULT_TOKEN_KEY) === token) {
-        lock.status = "MINTED";
-        lock.txHash = txHash;
-        return;
-      }
-    }
-  }
-  async updateMintStatus(lockId, status, txHash) {
-    const lock = this.locks.get(lockId);
-    if (!lock) {
-      throw new Error(`MemoryPointLedger: unknown lockId ${lockId}`);
-    }
-    lock.status = status;
-    if (txHash) lock.txHash = txHash;
-  }
-  // -------------------------------------------------------------------------
-  // v1.4 — Reverse flow (PT burn → off-chain credit)
-  // -------------------------------------------------------------------------
-  pendingCredits = /* @__PURE__ */ new Map();
-  nextCreditId = 1;
-  async reservePendingCredit(userAddress, amount, durationMs, tokenAddress) {
-    if (amount <= 0n) {
-      throw new Error(
-        "MemoryPointLedger: pending credit amount must be positive"
-      );
-    }
-    if (durationMs <= 0) {
-      throw new Error("MemoryPointLedger: durationMs must be positive");
-    }
-    const user = getAddress(userAddress);
-    const lockId = `credit-${this.nextCreditId++}`;
-    const now = this.now();
-    this.pendingCredits.set(lockId, {
-      lockId,
-      userAddress: user,
-      amount,
-      tokenAddress: tokenAddress !== void 0 ? getAddress(tokenAddress) : void 0,
-      createdAt: now,
-      expiresAt: now + durationMs,
-      status: "PENDING"
-    });
-    return lockId;
-  }
-  async resolveCreditByBurnTx(lockId, txHash) {
-    const credit = this.pendingCredits.get(lockId);
-    if (!credit) {
-      throw new Error(
-        `MemoryPointLedger: unknown pending credit lockId ${lockId}`
-      );
-    }
-    if (credit.status === "RESOLVED") {
-      if (credit.txHash === txHash) return;
-      throw new Error(
-        `MemoryPointLedger: credit ${lockId} already resolved with a different txHash`
-      );
-    }
-    const token = normalizeToken(credit.tokenAddress);
-    const key = balanceKey(credit.userAddress, token);
-    const current = this.balances.get(key) ?? 0n;
-    this.balances.set(key, current + credit.amount);
-    credit.status = "RESOLVED";
-    credit.txHash = txHash;
-  }
-  // -------------------------------------------------------------------------
-  // Internal helpers
-  // -------------------------------------------------------------------------
-  /**
-   * Auto-expire any PENDING lock past its expiry. Called lazily on every
-   * read/write so the in-memory state stays self-cleaning without a timer.
-   */
-  purgeExpired() {
-    const now = this.now();
-    for (const lock of this.locks.values()) {
-      if (lock.status === "PENDING" && lock.expiresAt <= now) {
-        lock.status = "EXPIRED";
-      }
-    }
-  }
-  lockedTotalFor(userAddress, tokenKey) {
-    let total = 0n;
-    for (const lock of this.locks.values()) {
-      if (lock.userAddress === userAddress && lock.status === "PENDING" && (lock.tokenAddress ?? DEFAULT_TOKEN_KEY) === tokenKey) {
-        total += lock.amount;
-      }
-    }
-    return total;
-  }
-};
-var DEFAULT_TOKEN_KEY = "default";
-function normalizeToken(tokenAddress) {
-  return tokenAddress === void 0 ? DEFAULT_TOKEN_KEY : getAddress(tokenAddress);
-}
-function balanceKey(user, tokenKey) {
-  return `${user}|${tokenKey}`;
-}
-
 // src/policy/defaultPolicy.ts
 var DefaultPolicyEngine = class {
   ledger;
@@ -211,6 +13,13 @@ var DefaultPolicyEngine = class {
     }
     if (opts.verifyMintCap) this.verifyMintCap = opts.verifyMintCap;
     if (opts.resolveIssuer) this.resolveIssuer = opts.resolveIssuer;
+    if (!opts.mintingOracleAddress || !opts.provider || !opts.verifyMintCap || !opts.resolveIssuer) {
+      if (process.env.NODE_ENV === "production") {
+        throw new Error(
+          "[PAFI] DefaultPolicyEngine: on-chain MintingOracle cap check is required in production. Configure mintingOracleAddress, provider, verifyMintCap, and resolveIssuer."
+        );
+      }
+    }
   }
   async evaluate(request) {
     if (request.amount <= 0n) {
@@ -247,34 +56,9 @@ var DefaultPolicyEngine = class {
   }
 };
 
-// src/signer/privateKeySigner.ts
-import { createWalletClient, http } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import {
-  signMintRequest
-} from "@pafi-dev/core";
-var PrivateKeySigner = class {
-  account;
-  walletClient;
-  constructor(opts) {
-    this.account = privateKeyToAccount(opts.privateKey);
-    this.walletClient = createWalletClient({
-      account: this.account,
-      chain: opts.chain,
-      transport: http(opts.rpcUrl)
-    });
-  }
-  async signMintRequest(domain, message) {
-    return signMintRequest(this.walletClient, domain, message);
-  }
-  async getAddress() {
-    return this.account.address;
-  }
-};
-
 // src/auth/memorySessionStore.ts
 import { randomBytes } from "crypto";
-import { getAddress as getAddress2 } from "viem";
+import { getAddress } from "viem";
 var DEFAULT_NONCE_TTL_MS = 5 * 60 * 1e3;
 var MemorySessionStore = class {
   nonces = /* @__PURE__ */ new Map();
@@ -284,6 +68,11 @@ 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."
+      );
+    }
     this.nonceTtlMs = opts.nonceTtlMs ?? DEFAULT_NONCE_TTL_MS;
     this.now = opts.now ?? (() => Date.now());
   }
@@ -310,7 +99,7 @@ var MemorySessionStore = class {
     this.purgeExpiredSessions();
     const normalized = {
       ...session,
-      userAddress: getAddress2(session.userAddress)
+      userAddress: getAddress(session.userAddress)
     };
     this.sessions.set(session.tokenId, normalized);
   }
@@ -328,7 +117,7 @@ var MemorySessionStore = class {
     this.sessions.delete(tokenId);
   }
   async revokeAllSessions(userAddress) {
-    const key = getAddress2(userAddress);
+    const key = getAddress(userAddress);
     for (const [tokenId, session] of this.sessions.entries()) {
       if (session.userAddress === key) {
         this.sessions.delete(tokenId);
@@ -374,7 +163,7 @@ var NonceManager = class {
 // src/auth/loginVerifier.ts
 import { randomBytes as randomBytes2 } from "crypto";
 import { SignJWT, jwtVerify, errors as joseErrors } from "jose";
-import { getAddress as getAddress3 } from "viem";
+import { getAddress as getAddress2 } from "viem";
 import { parseLoginMessage, verifyLoginMessage } from "@pafi-dev/core";
 
 // src/auth/errors.ts
@@ -398,8 +187,8 @@ var AuthService = class {
   nonceManager;
   now;
   constructor(config) {
-    if (!config.jwtSecret || config.jwtSecret.length < 16) {
-      throw new Error("AuthService: jwtSecret must be at least 16 chars");
+    if (!config.jwtSecret || config.jwtSecret.length < 32) {
+      throw new Error("AuthService: jwtSecret must be at least 32 characters for HS256 security");
     }
     this.sessionStore = config.sessionStore;
     this.jwtSecret = new TextEncoder().encode(config.jwtSecret);
@@ -428,6 +217,12 @@ var AuthService = class {
       const msg = err instanceof Error ? err.message : String(err);
       throw new AuthError("INVALID_MESSAGE", `Could not parse login message: ${msg}`);
     }
+    if (parsed.expirationTime == null) {
+      throw new AuthError(
+        "INVALID_MESSAGE",
+        "login message must include expirationTime"
+      );
+    }
     if (parsed.domain !== this.domain) {
       throw new AuthError(
         "DOMAIN_MISMATCH",
@@ -464,7 +259,7 @@ var AuthService = class {
         "Nonce is unknown, expired, or already used"
       );
     }
-    const userAddress = getAddress3(verifyResult.address);
+    const userAddress = getAddress2(verifyResult.address);
     const tokenId = randomBytes2(16).toString("hex");
     const issuedAt = now;
     const expiresAt = parseExpiry(issuedAt, this.jwtExpiresIn);
@@ -492,7 +287,11 @@ var AuthService = class {
       if (payload.jti) {
         await this.sessionStore.revokeSession(payload.jti);
       }
-    } catch {
+    } 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);
+      }
     }
   }
   /**
@@ -531,7 +330,7 @@ var AuthService = class {
       throw new AuthError("TOKEN_INVALID", "JWT payload is malformed");
     }
     return {
-      userAddress: getAddress3(userAddress),
+      userAddress: getAddress2(userAddress),
       chainId,
       tokenId
     };
@@ -589,7 +388,7 @@ import {
 import {
   POINT_TOKEN_V2_ABI,
   buildPartialUserOperation,
-  signMintRequest as signMintRequest2
+  signMintRequest
 } from "@pafi-dev/core";
 var RelayService = class {
   /**
@@ -624,9 +423,20 @@ var RelayService = class {
     if (params.deadline <= 0n) {
       throw new RelayError("ENCODE_FAILED", "prepareMint: deadline must be positive");
     }
+    const nowSecs = BigInt(Math.floor(Date.now() / 1e3));
+    if (params.deadline <= nowSecs) {
+      throw new RelayError("ENCODE_FAILED", "prepareMint: deadline is in the past");
+    }
+    const MAX_DEADLINE_WINDOW = 3600n;
+    if (params.deadline > nowSecs + MAX_DEADLINE_WINDOW) {
+      throw new RelayError(
+        "ENCODE_FAILED",
+        "prepareMint: deadline exceeds maximum allowed window (1 hour)"
+      );
+    }
     let minterSig;
     try {
-      const sig = await signMintRequest2(
+      const sig = await signMintRequest(
         params.issuerSignerWallet,
         params.domain,
         {
@@ -672,6 +482,12 @@ var RelayService = class {
           "prepareMint: feeRecipient required when feeAmount > 0"
         );
       }
+      if (params.feeRecipient === "0x0000000000000000000000000000000000000000") {
+        throw new RelayError(
+          "ENCODE_FAILED",
+          "prepareMint: feeRecipient must not be zero address"
+        );
+      }
       operations.push({
         target: params.pointTokenAddress,
         value: 0n,
@@ -770,11 +586,14 @@ function errorMessage(err) {
 // src/relay/feeManager.ts
 var DEFAULT_GAS_UNITS = 500000n;
 var DEFAULT_PREMIUM_BPS = 12e3;
-var FeeManager = class {
+var FeeManager = class _FeeManager {
   provider;
   gasUnits;
   gasPremiumBps;
   quoteNativeToFee;
+  cachedFee = null;
+  cacheExpiresAt = 0;
+  static CACHE_TTL_MS = 1e4;
   constructor(config) {
     if (!config.provider) throw new Error("FeeManager: provider required");
     if (!config.quoteNativeToFee)
@@ -797,10 +616,17 @@ var FeeManager = class {
    * currency depends on how the caller wired `quoteNativeToFee`.
    */
   async estimateGasFee() {
+    const now = Date.now();
+    if (this.cachedFee !== null && now < this.cacheExpiresAt) {
+      return this.cachedFee;
+    }
     const gasPrice = await this.provider.getGasPrice();
     const nativeCost = gasPrice * this.gasUnits;
     const withPremium = nativeCost * BigInt(this.gasPremiumBps) / 10000n;
-    return this.quoteNativeToFee(withPremium);
+    const fee = await this.quoteNativeToFee(withPremium);
+    this.cachedFee = fee;
+    this.cacheExpiresAt = now + _FeeManager.CACHE_TTL_MS;
+    return fee;
   }
 };
 
@@ -816,7 +642,7 @@ var InMemoryCursorStore = class {
 };
 
 // src/indexer/pointIndexer.ts
-import { getAddress as getAddress4, parseAbiItem } from "viem";
+import { getAddress as getAddress3, parseAbiItem } from "viem";
 var TRANSFER_EVENT = parseAbiItem(
   "event Transfer(address indexed from, address indexed to, uint256 value)"
 );
@@ -887,7 +713,8 @@ var PointIndexer = class {
         return;
       }
       await this.processBlockRange(from, safeHead);
-    } catch {
+    } catch (err) {
+      console.error("[PAFI] PointIndexer tick error:", err);
     }
     this.scheduleNext();
   }
@@ -937,10 +764,10 @@ var PointIndexer = class {
     for (const log of logs) {
       const args = log.args;
       if (!args.from || !args.to || args.value === void 0) continue;
-      if (getAddress4(args.from) !== ZERO_ADDRESS) continue;
+      if (getAddress3(args.from) !== ZERO_ADDRESS) continue;
       if (log.blockNumber === null || log.transactionHash === null) continue;
       out.push({
-        to: getAddress4(args.to),
+        to: getAddress3(args.to),
         amount: args.value,
         blockNumber: log.blockNumber,
         txHash: log.transactionHash,
@@ -996,7 +823,7 @@ function pickMatchingLock(locks, amount) {
 }
 
 // src/indexer/burnIndexer.ts
-import { getAddress as getAddress5, parseAbiItem as parseAbiItem2 } from "viem";
+import { getAddress as getAddress4, parseAbiItem as parseAbiItem2 } from "viem";
 var TRANSFER_EVENT2 = parseAbiItem2(
   "event Transfer(address indexed from, address indexed to, uint256 value)"
 );
@@ -1013,18 +840,7 @@ var BurnIndexer = class {
   confirmations;
   batchSize;
   pollIntervalMs;
-  /**
-   * Caller-supplied matcher. Return the lockId to resolve for a given
-   * burn event, or `undefined` to skip. Runs synchronously via the
-   * ledger's query path.
-   *
-   * Default: try `ledger.resolveCreditByBurnTx` keyed on a synthetic
-   * lock id `burn-${from}-${amount}` — the in-memory ledger assigns
-   * incrementing IDs so callers with the memory ledger must provide a
-   * custom matcher. Real DB-backed ledgers override this to JOIN on
-   * their `pending_credits` table.
-   */
-  matchLockId = async () => void 0;
+  matchLockId;
   running = false;
   timer;
   constructor(config) {
@@ -1042,6 +858,12 @@ var BurnIndexer = class {
     );
     this.batchSize = BigInt(config.batchSize ?? Number(DEFAULT_BATCH_SIZE2));
     this.pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS2;
+    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."
+      );
+    }
+    this.matchLockId = config.matchLockId;
   }
   start() {
     if (this.running) return;
@@ -1071,7 +893,8 @@ var BurnIndexer = class {
         return;
       }
       await this.processBlockRange(from, safeHead);
-    } catch {
+    } catch (err) {
+      console.error("[PAFI] BurnIndexer tick error:", err);
     }
     this.scheduleNext();
   }
@@ -1116,10 +939,10 @@ var BurnIndexer = class {
     for (const log of logs) {
       const args = log.args;
       if (!args.from || !args.to || args.value === void 0) continue;
-      if (getAddress5(args.to) !== ZERO_ADDRESS2) continue;
+      if (getAddress4(args.to) !== ZERO_ADDRESS2) continue;
       if (log.blockNumber === null || log.transactionHash === null) continue;
       out.push({
-        from: getAddress5(args.from),
+        from: getAddress4(args.from),
         amount: args.value,
         blockNumber: log.blockNumber,
         txHash: log.transactionHash,
@@ -1134,20 +957,27 @@ var BurnIndexer = class {
    * log + skip.
    */
   async finalize(evt) {
+    const txHash = evt.txHash;
     const lockId = await this.matchLockId(evt);
-    if (!lockId) return;
+    if (lockId === void 0) {
+      console.warn(
+        "[PAFI] BurnIndexer: matchLockId returned undefined for burn tx " + txHash + ". This burn will NOT be credited. Implement matchLockId to map burn events to lock IDs."
+      );
+      return;
+    }
     if (!this.ledger.resolveCreditByBurnTx) {
       return;
     }
     try {
       await this.ledger.resolveCreditByBurnTx(lockId, evt.txHash);
-    } catch {
+    } catch (err) {
+      console.error("[PAFI] BurnIndexer finalize error \u2014 credit may be lost:", err);
     }
   }
 };
 
 // src/api/handlers.ts
-import { getAddress as getAddress6 } from "viem";
+import { getAddress as getAddress5 } from "viem";
 import {
   getMintRequestNonce,
   getPointTokenBalance,
@@ -1165,15 +995,12 @@ var IssuerApiHandlers = class {
    * validate the request's `pointTokenAddress` against this set.
    */
   supportedTokens;
-  /** First supported token — used as default when a handler doesn't
-   * receive a `pointTokenAddress` in the request (shouldn't happen in
-   * practice, but keeps type-narrowing happy). */
-  defaultToken;
   chainId;
   contracts;
   pafiWebUrl;
   feeManager;
   poolsProvider;
+  claim;
   constructor(config) {
     this.authService = config.authService;
     this.ledger = config.ledger;
@@ -1184,14 +1011,14 @@ var IssuerApiHandlers = class {
         "IssuerApiHandlers: pointTokenAddress or pointTokenAddresses required"
       );
     }
-    const normalized = raw.map((a) => getAddress6(a));
+    const normalized = raw.map((a) => getAddress5(a));
     this.supportedTokens = new Set(normalized);
-    this.defaultToken = normalized[0];
     this.chainId = config.chainId;
     this.contracts = config.contracts;
     if (config.pafiWebUrl) this.pafiWebUrl = config.pafiWebUrl;
     if (config.feeManager) this.feeManager = config.feeManager;
     if (config.poolsProvider) this.poolsProvider = config.poolsProvider;
+    if (config.claim) this.claim = config.claim;
   }
   // =========================================================================
   // Public handlers (no auth required)
@@ -1206,6 +1033,12 @@ var IssuerApiHandlers = class {
     if (!body || typeof body.message !== "string" || body.message.length === 0 || typeof body.signature !== "string" || body.signature.length <= 2) {
       throw new Error("handleLogin: message and signature are required");
     }
+    if (body.message.length > 4096) {
+      throw new Error("message too long");
+    }
+    if (body.signature.length > 260) {
+      throw new Error("signature too long");
+    }
     const result = await this.authService.login(body.message, body.signature);
     return {
       token: result.token,
@@ -1220,9 +1053,12 @@ var IssuerApiHandlers = class {
    * needs to build EIP-712 messages and interact with on-chain.
    */
   async handleConfig(chainId) {
+    if (!Number.isInteger(chainId) || chainId <= 0) {
+      throw new Error("invalid chainId");
+    }
     if (chainId !== this.chainId) {
       throw new Error(
-        `handleConfig: unsupported chainId ${chainId}, issuer is configured for ${this.chainId}`
+        `handleConfig: unsupported chainId ${chainId}`
       );
     }
     const contracts = {
@@ -1285,14 +1121,14 @@ var IssuerApiHandlers = class {
         `handleUser: unsupported chainId ${request.chainId}`
       );
     }
-    const normalizedAuthed = getAddress6(userAddress);
-    const normalizedRequest = getAddress6(request.userAddress);
+    const normalizedAuthed = getAddress5(userAddress);
+    const normalizedRequest = getAddress5(request.userAddress);
     if (normalizedAuthed !== normalizedRequest) {
       throw new Error(
         "handleUser: request userAddress must match authenticated user"
       );
     }
-    const pointToken = getAddress6(request.pointTokenAddress);
+    const pointToken = getAddress5(request.pointTokenAddress);
     if (!this.supportedTokens.has(pointToken)) {
       throw new Error(
         `handleUser: unsupported pointToken ${pointToken}`
@@ -1335,19 +1171,32 @@ var IssuerApiHandlers = class {
         `handleBuildConsentTypedData: unsupported chainId ${request.chainId}`
       );
     }
-    const pointToken = getAddress6(request.pointTokenAddress);
+    const pointToken = getAddress5(request.pointTokenAddress);
     if (!this.supportedTokens.has(pointToken)) {
       throw new Error(
         `handleBuildConsentTypedData: unsupported pointToken ${pointToken}`
       );
     }
+    const consent = request.receiverConsent;
+    if (getAddress5(consent.originalReceiver) !== getAddress5(userAddress)) {
+      throw new Error(
+        "handleBuildConsentTypedData: receiverConsent.originalReceiver must match authenticated user"
+      );
+    }
+    if (consent.amount <= 0n) {
+      throw new Error("handleBuildConsentTypedData: amount must be positive");
+    }
+    const nowSecs = BigInt(Math.floor(Date.now() / 1e3));
+    if (consent.deadline <= nowSecs) {
+      throw new Error("handleBuildConsentTypedData: deadline is in the past");
+    }
     const name = await getTokenName(this.provider, pointToken);
     const domain = {
       name,
       verifyingContract: pointToken,
       chainId: this.chainId
     };
-    const typedData = buildReceiverConsentTypedData(domain, request.receiverConsent);
+    const typedData = buildReceiverConsentTypedData(domain, consent);
     return {
       typedData: {
         domain: typedData.domain,
@@ -1357,11 +1206,96 @@ var IssuerApiHandlers = class {
       }
     };
   }
+  /**
+   * `POST /claim`
+   *
+   * Policy gate + ledger lock + MintRequest signing in a single atomic
+   * step. Returns an unsigned UserOp the frontend attaches paymaster data
+   * to and submits via EIP-7702 + Bundler.
+   *
+   * Order of operations:
+   *   1. Validate request fields.
+   *   2. policy.evaluate() — throws if denied; cannot be bypassed.
+   *   3. ledger.lockForMinting() — reserves the balance.
+   *   4. Read on-chain mintRequestNonce + token name in parallel.
+   *   5. relayService.prepareMint() — sign MintRequest + encode UserOp.
+   *   6. On any error after step 3, release the lock before re-throwing.
+   */
+  async handleClaim(userAddress, request) {
+    if (!this.claim) {
+      throw new Error("handleClaim: claim is not configured on this issuer");
+    }
+    if (request.chainId !== this.chainId) {
+      throw new Error(`handleClaim: unsupported chainId ${request.chainId}`);
+    }
+    const pointToken = getAddress5(request.pointTokenAddress);
+    if (!this.supportedTokens.has(pointToken)) {
+      throw new Error(`handleClaim: unsupported pointToken ${pointToken}`);
+    }
+    if (request.amount <= 0n) {
+      throw new Error("handleClaim: amount must be positive");
+    }
+    const nowSecs = BigInt(Math.floor(Date.now() / 1e3));
+    if (request.deadline <= nowSecs) {
+      throw new Error("handleClaim: deadline is in the past");
+    }
+    const { policy, relayService, issuerSignerWallet, batchExecutorAddress } = this.claim;
+    const lockDurationMs = this.claim.lockDurationMs ?? 15 * 60 * 1e3;
+    const normalizedUser = getAddress5(userAddress);
+    const decision = await policy.evaluate({
+      userAddress: normalizedUser,
+      amount: request.amount,
+      pointTokenAddress: pointToken,
+      chainId: this.chainId
+    });
+    if (!decision.approved) {
+      throw new Error(`handleClaim: policy denied \u2014 ${decision.reason ?? "no reason given"}`);
+    }
+    const lockId = await this.ledger.lockForMinting(
+      normalizedUser,
+      request.amount,
+      lockDurationMs,
+      pointToken
+    );
+    try {
+      const [mintRequestNonce, tokenName] = await Promise.all([
+        getMintRequestNonce(this.provider, pointToken, normalizedUser),
+        getTokenName(this.provider, pointToken)
+      ]);
+      const domain = {
+        name: tokenName,
+        verifyingContract: pointToken,
+        chainId: this.chainId
+      };
+      const userOp = await relayService.prepareMint({
+        userAddress: normalizedUser,
+        aaNonce: request.aaNonce,
+        batchExecutorAddress,
+        pointTokenAddress: pointToken,
+        amount: request.amount,
+        issuerSignerWallet,
+        domain,
+        mintRequestNonce,
+        deadline: request.deadline,
+        feeAmount: request.feeAmount,
+        feeRecipient: request.feeRecipient
+      });
+      return {
+        lockId,
+        userOp,
+        expiresInSeconds: Math.floor(lockDurationMs / 1e3)
+      };
+    } catch (err) {
+      await this.ledger.releaseLock(lockId).catch(() => {
+      });
+      throw err;
+    }
+  }
 };
 
 // src/api/handlers/ptRedeemHandler.ts
-import { getAddress as getAddress7 } from "viem";
-import { signBurnRequest, POINT_TOKEN_V2_ABI as POINT_TOKEN_V2_ABI2 } from "@pafi-dev/core";
+import { getAddress as getAddress6 } from "viem";
+import { signBurnRequest, POINT_TOKEN_V2_ABI as POINT_TOKEN_V2_ABI2, getPointTokenBalance as getPointTokenBalance2 } from "@pafi-dev/core";
 var DEFAULT_REDEEM_LOCK_MS = 15 * 60 * 1e3;
 var DEFAULT_SIG_DEADLINE_SEC = 15 * 60;
 var PTRedeemError = class extends Error {
@@ -1400,16 +1334,25 @@ var PTRedeemHandler = class {
     this.ledger = config.ledger;
     this.relayService = config.relayService;
     this.provider = config.provider;
-    this.pointTokenAddress = getAddress7(config.pointTokenAddress);
-    this.batchExecutorAddress = getAddress7(config.batchExecutorAddress);
+    this.pointTokenAddress = getAddress6(config.pointTokenAddress);
+    this.batchExecutorAddress = getAddress6(config.batchExecutorAddress);
     this.chainId = config.chainId;
     this.domain = config.domain;
     this.burnerSignerWallet = config.burnerSignerWallet;
+    if (this.burnerSignerWallet?.account?.type === "local") {
+      console.warn("[PAFI] PTRedeemHandler: burnerSignerWallet uses a local (private key) account. Use a KMS-backed signer in production.");
+    }
     this.redeemLockDurationMs = config.redeemLockDurationMs ?? DEFAULT_REDEEM_LOCK_MS;
     this.signatureDeadlineSeconds = config.signatureDeadlineSeconds ?? DEFAULT_SIG_DEADLINE_SEC;
     this.now = config.now ?? (() => Date.now());
   }
   async handle(request) {
+    if (getAddress6(request.authenticatedAddress) !== getAddress6(request.userAddress)) {
+      throw new PTRedeemError(
+        "UNAUTHORIZED",
+        `userAddress (${request.userAddress}) does not match authenticated session (${request.authenticatedAddress})`
+      );
+    }
     if (request.amount <= 0n) {
       throw new PTRedeemError("INVALID_AMOUNT", "redeem amount must be positive");
     }
@@ -1427,6 +1370,17 @@ var PTRedeemHandler = class {
         `failed to read burnRequestNonces(${request.userAddress}): ${err instanceof Error ? err.message : String(err)}`
       );
     }
+    const onChainBalance = await getPointTokenBalance2(
+      this.provider,
+      this.pointTokenAddress,
+      request.userAddress
+    );
+    if (onChainBalance < request.amount) {
+      throw new PTRedeemError(
+        "INVALID_AMOUNT",
+        `insufficient on-chain PT balance: have ${onChainBalance}, need ${request.amount}`
+      );
+    }
     const deadline = BigInt(
       Math.floor(this.now() / 1e3) + this.signatureDeadlineSeconds
     );
@@ -1480,8 +1434,8 @@ var PTRedeemHandler = class {
 };
 
 // src/api/handlers/topUpRedemptionHandler.ts
-import { getAddress as getAddress8 } from "viem";
-import { getPointTokenBalance as getPointTokenBalance2 } from "@pafi-dev/core";
+import { getAddress as getAddress7 } from "viem";
+import { getPointTokenBalance as getPointTokenBalance3 } from "@pafi-dev/core";
 var TopUpRedemptionError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -1499,9 +1453,15 @@ var TopUpRedemptionHandler = class {
     this.ledger = config.ledger;
     this.ptRedeemHandler = config.ptRedeemHandler;
     this.provider = config.provider;
-    this.pointTokenAddress = getAddress8(config.pointTokenAddress);
+    this.pointTokenAddress = getAddress7(config.pointTokenAddress);
   }
   async handle(request) {
+    if (getAddress7(request.authenticatedAddress) !== getAddress7(request.userAddress)) {
+      throw new TopUpRedemptionError(
+        "UNAUTHORIZED",
+        `userAddress (${request.userAddress}) does not match authenticated session (${request.authenticatedAddress})`
+      );
+    }
     const offChainBalance = await this.ledger.getBalance(
       request.userAddress,
       this.pointTokenAddress
@@ -1510,7 +1470,7 @@ var TopUpRedemptionHandler = class {
       return { action: "NO_TOP_UP_NEEDED", offChainBalance };
     }
     const shortfall = request.requiredAmount - offChainBalance;
-    const onChainBalance = await getPointTokenBalance2(
+    const onChainBalance = await getPointTokenBalance3(
       this.provider,
       this.pointTokenAddress,
       request.userAddress
@@ -1524,6 +1484,7 @@ var TopUpRedemptionHandler = class {
       };
     }
     const redeem = await this.ptRedeemHandler.handle({
+      authenticatedAddress: request.authenticatedAddress,
       userAddress: request.userAddress,
       amount: shortfall,
       aaNonce: request.aaNonce
@@ -1537,6 +1498,7 @@ var TopUpRedemptionHandler = class {
 };
 
 // src/pools/subgraphPoolsProvider.ts
+import { isAddress } from "viem";
 var DEFAULT_CACHE_TTL_MS = 3e4;
 var POOL_QUERY = `
   query GetPoolForPointToken($id: ID!) {
@@ -1559,6 +1521,19 @@ function createSubgraphPoolsProvider(config) {
       "createSubgraphPoolsProvider: subgraphUrl is required"
     );
   }
+  try {
+    const parsed = new URL(config.subgraphUrl);
+    if (process.env.NODE_ENV === "production" && parsed.protocol !== "https:") {
+      throw new Error("subgraphUrl must use HTTPS in production");
+    }
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new Error(
+        `subgraphPoolsProvider: invalid subgraphUrl: ${config.subgraphUrl}`
+      );
+    }
+    throw err;
+  }
   const cacheTtl = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
   const fetchImpl = config.fetchImpl ?? globalThis.fetch;
   const now = config.now ?? (() => Date.now());
@@ -1627,6 +1602,26 @@ async function fetchPoolsFromSubgraph(fetchImpl, subgraphUrl, pointTokenAddress)
     return [];
   }
   const { pool } = token;
+  if (!isAddress(pool.hooks)) {
+    console.error(
+      "[PAFI] SubgraphPoolsProvider: invalid hooks address in response:",
+      pool.hooks,
+      "\u2014 skipping pool"
+    );
+    return [];
+  }
+  if (!isAddress(pool.token0.id) || !isAddress(pool.token1.id)) {
+    console.error(
+      "[PAFI] SubgraphPoolsProvider: invalid token address in response \u2014 skipping pool"
+    );
+    return [];
+  }
+  if (!Number.isFinite(Number(pool.feeTier)) || !Number.isFinite(Number(pool.tickSpacing))) {
+    console.error(
+      "[PAFI] SubgraphPoolsProvider: invalid feeTier/tickSpacing \u2014 skipping pool"
+    );
+    return [];
+  }
   const [currency0, currency1] = sortCurrencies(
     pool.token0.id,
     pool.token1.id
@@ -1662,6 +1657,19 @@ function createSubgraphNativeUsdtQuoter(config) {
       "createSubgraphNativeUsdtQuoter: subgraphUrl is required"
     );
   }
+  try {
+    const parsed = new URL(config.subgraphUrl);
+    if (process.env.NODE_ENV === "production" && parsed.protocol !== "https:") {
+      throw new Error("subgraphUrl must use HTTPS in production");
+    }
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new Error(
+        `subgraphPoolsProvider: invalid subgraphUrl: ${config.subgraphUrl}`
+      );
+    }
+    throw err;
+  }
   const usdtDecimals = config.usdtDecimals ?? DEFAULT_USDT_DECIMALS;
   const nativeDecimals = config.nativeDecimals ?? DEFAULT_NATIVE_DECIMALS;
   const cacheTtl = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS2;
@@ -1738,6 +1746,14 @@ async function fetchEthPriceFromSubgraph(fetchImpl, subgraphUrl) {
     );
     return null;
   }
+  const MIN_REASONABLE_ETH_PRICE = 100;
+  const MAX_REASONABLE_ETH_PRICE = 1e5;
+  if (parsed < MIN_REASONABLE_ETH_PRICE || parsed > MAX_REASONABLE_ETH_PRICE) {
+    console.warn(
+      `[PAFI] SubgraphNativeUsdtQuoter: ETH/USD price ${parsed} is outside reasonable range. Using fallback.`
+    );
+    return null;
+  }
   return parsed;
 }
 function toUsdtPerNative(priceFloat, usdtDecimals) {
@@ -1748,7 +1764,7 @@ function toUsdtPerNative(priceFloat, usdtDecimals) {
 }
 
 // src/balance/balanceAggregator.ts
-import { getPointTokenBalance as getPointTokenBalance3 } from "@pafi-dev/core";
+import { getPointTokenBalance as getPointTokenBalance4 } from "@pafi-dev/core";
 var BalanceAggregator = class {
   provider;
   ledger;
@@ -1769,7 +1785,7 @@ var BalanceAggregator = class {
   async getCombinedBalance(user, pointToken) {
     const [offChain, onChain] = await Promise.all([
       this.ledger.getBalance(user, pointToken),
-      getPointTokenBalance3(this.provider, pointToken, user)
+      getPointTokenBalance4(this.provider, pointToken, user)
     ]);
     return {
       offChain,
@@ -1828,12 +1844,104 @@ var PafiBackendError = class extends Error {
   }
 };
 
+// src/pafi-backend/client.ts
+function serializeBigInt(_key, value) {
+  return typeof value === "bigint" ? value.toString(10) : value;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var PafiBackendClient = class {
+  config;
+  constructor(config) {
+    if (!config.url) throw new Error("PafiBackendClient: url is required");
+    if (!config.issuerId) throw new Error("PafiBackendClient: issuerId is required");
+    this.config = config;
+  }
+  async requestSponsorship(request) {
+    const maxAttempts = this.config.retry?.maxAttempts ?? 1;
+    const initialDelayMs = this.config.retry?.initialDelayMs ?? 100;
+    const maxDelayMs = this.config.retry?.maxDelayMs ?? 1e4;
+    const maxRetryAfterMs = this.config.retry?.maxRetryAfterMs;
+    let lastError;
+    let delay = initialDelayMs;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await this._doRequest(request);
+      } catch (err) {
+        if (!(err instanceof PafiBackendError)) throw err;
+        lastError = err;
+        if (attempt >= maxAttempts) break;
+        if (!err.safeToRetry) break;
+        const retryAfterMs = err.retryAfter !== void 0 ? err.retryAfter * 1e3 : void 0;
+        if (maxRetryAfterMs !== void 0 && retryAfterMs !== void 0 && retryAfterMs > maxRetryAfterMs) {
+          break;
+        }
+        await sleep(retryAfterMs ?? delay);
+        delay = Math.min(delay * 2, maxDelayMs);
+      }
+    }
+    throw lastError;
+  }
+  async _doRequest(request) {
+    const fetchFn = this.config.fetchImpl ?? fetch;
+    const url = `${this.config.url}/paymaster/sponsor`;
+    const body = JSON.stringify(request, serializeBigInt);
+    let response;
+    try {
+      response = await fetchFn(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-Issuer-Id": this.config.issuerId
+        },
+        body
+      });
+    } catch (err) {
+      throw new PafiBackendError(
+        "NETWORK_ERROR",
+        `Network error: ${err instanceof Error ? err.message : String(err)}`,
+        0
+      );
+    }
+    const text = await response.text();
+    let json = {};
+    try {
+      json = JSON.parse(text);
+    } catch {
+    }
+    if (!response.ok) {
+      const code = json.code ?? "INTERNAL_ERROR";
+      const message = json.message ?? `HTTP ${response.status}`;
+      const retryAfter = typeof json.retryAfter === "number" ? json.retryAfter : void 0;
+      const safeToRetry = typeof json.safeToRetry === "boolean" ? json.safeToRetry : void 0;
+      throw new PafiBackendError(code, message, response.status, json, {
+        retryAfter,
+        safeToRetry
+      });
+    }
+    return {
+      paymaster: json.paymaster,
+      paymasterData: json.paymasterData,
+      paymasterVerificationGasLimit: BigInt(
+        json.paymasterVerificationGasLimit
+      ),
+      paymasterPostOpGasLimit: BigInt(json.paymasterPostOpGasLimit),
+      expiresAt: json.expiresAt
+    };
+  }
+};
+
 // src/config.ts
-import { getAddress as getAddress9 } from "viem";
+import { getAddress as getAddress8 } from "viem";
 function createIssuerService(config) {
   if (!config.provider) {
     throw new Error("createIssuerService: provider is required");
   }
+  if (!config.ledger) {
+    throw new Error("createIssuerService: ledger is required");
+  }
   if (!config.auth?.jwtSecret) {
     throw new Error("createIssuerService: auth.jwtSecret is required");
   }
@@ -1846,8 +1954,8 @@ function createIssuerService(config) {
       "createIssuerService: at least one of pointTokenAddress / pointTokenAddresses is required"
     );
   }
-  const tokenAddresses = rawAddresses.map((a) => getAddress9(a));
-  const ledger = config.ledger ?? new MemoryPointLedger();
+  const tokenAddresses = rawAddresses.map((a) => getAddress8(a));
+  const ledger = config.ledger;
   const sessionStore = config.sessionStore ?? new MemorySessionStore();
   const policy = config.policy ?? new DefaultPolicyEngine({ ledger });
   const authServiceConfig = {
@@ -1903,6 +2011,15 @@ function createIssuerService(config) {
   };
   if (feeManager) handlersConfig.feeManager = feeManager;
   if (config.poolsProvider) handlersConfig.poolsProvider = config.poolsProvider;
+  if (config.claim) {
+    handlersConfig.claim = {
+      policy,
+      relayService,
+      issuerSignerWallet: config.claim.issuerSignerWallet,
+      batchExecutorAddress: config.claim.batchExecutorAddress,
+      lockDurationMs: config.claim.lockDurationMs
+    };
+  }
   const handlers = new IssuerApiHandlers(handlersConfig);
   if (config.indexer?.autoStart) {
     for (const idx of indexers.values()) {
@@ -1910,20 +2027,20 @@ function createIssuerService(config) {
     }
   }
   return {
-    authService,
-    sessionStore,
+    auth: authService,
+    session: sessionStore,
     ledger,
     policy,
-    relayService,
-    feeManager,
+    relay: relayService,
+    fee: feeManager,
     indexers,
     indexer: firstIndexer,
-    handlers
+    api: handlers
   };
 }
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = "0.1.0";
+var PAFI_ISSUER_SDK_VERSION = "0.4.0";
 export {
   AuthError,
   AuthService,
@@ -1933,15 +2050,14 @@ export {
   FeeManager,
   InMemoryCursorStore,
   IssuerApiHandlers,
-  MemoryPointLedger,
   MemorySessionStore,
   NonceManager,
   PAFI_ISSUER_SDK_VERSION,
   PTRedeemError,
   PTRedeemHandler,
+  PafiBackendClient,
   PafiBackendError,
   PointIndexer,
-  PrivateKeySigner,
   RelayError,
   RelayService,
   TopUpRedemptionError,