@pafi-dev/issuer 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# @pafi/issuer
+
+Issuer backend boilerplate for the PAFI point token system. Wraps
+`@pafi/core` with everything a partner needs to run the off-chain side
+of the mint-and-cash-out flow: authentication, point ledger, policy
+engine, EIP-712 issuer signing, relay submission, mint event indexing,
+and framework-agnostic HTTP handlers.
+
+## Install
+
+```bash
+pnpm add @pafi/issuer @pafi/core viem
+```
+
+Peer deps: `viem ^2.0`, `@pafi/core` (workspace), `jose ^5` (transitive).
+
+## At a glance
+
+```ts
+import { createIssuerService, PrivateKeySigner } from "@pafi/issuer";
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+
+const provider = createPublicClient({ chain: base, transport: http(RPC_URL) });
+const operatorWallet = createWalletClient({
+  account: privateKeyToAccount(OPERATOR_PK),
+  chain: base,
+  transport: http(RPC_URL),
+});
+
+const service = createIssuerService({
+  chainId: 8453,
+  pointTokenAddress: "0x5F...",
+  relayAddress: "0x92...",
+  contracts: { pointToken, relay, issuerRegistry, usdt },
+  provider,
+  operatorWallet,
+  auth: {
+    jwtSecret: process.env.JWT_SECRET!,
+    domain: "app.example.com",
+  },
+  // ⚠️ NOT for production — replace with a KMS-backed IIssuerSigner
+  signer: new PrivateKeySigner({ privateKey: ISSUER_PK, chain: base }),
+});
+
+// Wire `service.handlers` into Express / Fastify / Hono — see
+// examples/express-issuer/ for a full runnable server.
+```
+
+## What you get
+
+| Component               | Default               | Replace for production?               |
+| ----------------------- | --------------------- | ------------------------------------- |
+| `IPointLedger`          | `MemoryPointLedger`   | ✅ Postgres / Prisma                    |
+| `ISessionStore`         | `MemorySessionStore`  | ✅ Redis                                |
+| `IPolicyEngine`         | `DefaultPolicyEngine` | ➕ extend for KYC / caps / claim budget |
+| `IIssuerSigner`         | `PrivateKeySigner`    | 🚨 **MUST replace** — KMS / HSM / MPC   |
+| `AuthService`           | ✅ built-in            | —                                     |
+| `RelayService`          | ✅ built-in            | —                                     |
+| `FeeManager`            | ✅ built-in (opt-in)   | injection-based — no DEX lock-in      |
+| `MintingGateway`        | ✅ built-in            | —                                     |
+| `PointIndexer`          | ✅ built-in (polling)  | —                                     |
+| `IssuerApiHandlers`     | ✅ built-in            | —                                     |
+
+See [`examples/adapters/`](./examples/adapters) for reference
+implementations of the three interfaces you must replace.
+
+## The minting flow
+
+The SDK's central orchestrator is `MintingGateway.processMintAndCashOut()`,
+which runs the full 11-step flow documented in
+[`docs/PAFI_ISSUER_SDK_SPEC.md`](../../../pafi-backend/docs/PAFI_ISSUER_SDK_SPEC.md):
+
+```
+1. Validate request fields (cheap rejects)
+2. Verify ReceiverConsent signature via @pafi/core
+3. Check off-chain balance via ledger
+4. Check locked requests via ledger
+5. Run policy engine (balance + cap + issuer rules)
+6. Lock the requested amount in the ledger
+7. Sign MintRequest as the issuer (via IIssuerSigner)
+8. Build Relay calldata (MintParams + SwapParams)
+9. Submit via RelayService (simulate → write → receipt)
+10. Return { txHash, lockId, block/gas }
+11. PointIndexer finalizes the ledger on the Mint event (out of band)
+```
+
+**The gateway never deducts the balance directly.** Deduction is
+driven by the `PointIndexer` when it observes the on-chain Mint event.
+That makes the system crash-safe: if the gateway dies between
+broadcast and receipt, the indexer still finalizes the ledger the next
+time it polls.
+
+### Lock release semantics
+
+Every `MintingGatewayError` carries a `safeToRetry: boolean` flag that
+tells the API layer whether the underlying ledger lock was released:
+
+| Error code                  | Lock released? | `safeToRetry` |
+| --------------------------- | -------------- | ------------- |
+| `INVALID_REQUEST`           | never locked   | `true`        |
+| `INVALID_CONSENT_SIGNATURE` | never locked   | `true`        |
+| `CONSENT_EXPIRED`           | never locked   | `true`        |
+| `POLICY_REJECTED`           | never locked   | `true`        |
+| `INSUFFICIENT_BALANCE`      | never locked   | `true`        |
+| `SIGNER_FAILED`             | ✅ released     | `true`        |
+| `RELAY_SIMULATION_FAILED`   | ✅ released     | `true`        |
+| `RELAY_SUBMIT_FAILED`       | ✅ released     | `true`        |
+| `RELAY_REVERTED`            | 🔒 kept         | `false`       |
+| `RELAY_TIMEOUT`             | 🔒 kept         | `false`       |
+
+`RELAY_REVERTED` and `RELAY_TIMEOUT` keep the lock because the tx may
+still be in the mempool or already mined — releasing would enable a
+double-spend on retry. Your API should surface `409 Conflict` in these
+cases and require manual reconciliation.
+
+## Authentication
+
+Wallet-based login uses EIP-4361 (Sign-In with Ethereum):
+
+```
+Frontend                           Issuer backend
+────────                           ──────────────
+1. GET /auth/nonce              →  authService.getNonce()
+                                ←  { nonce }
+2. Build EIP-4361 message with
+   nonce (via PafiSDK or
+   @pafi/core createLoginMessage)
+3. Sign with wallet
+4. POST /auth/login             →  authService.login(message, sig)
+   { message, signature }           → parse → verify → consume nonce
+                                    → create session → issue JWT
+                                ←  { token, userAddress, expiresAt }
+5. Authorization: Bearer <jwt>  →  authenticateRequest()
+                                    → verify JWT + session
+                                    → pass { userAddress, chainId } to handlers
+```
+
+Key property: a failed signature does **not** burn the nonce. Users can
+retry with the correct wallet on the same nonce without hitting the
+backend again.
+
+## HTTP endpoints
+
+The handlers are framework-agnostic — `async` functions that take plain
+inputs and return plain outputs. Wrap them in Express / Fastify / Hono /
+whatever you use. See `examples/express-issuer/server.ts` for the full
+wiring.
+
+| Method | Path             | Auth | Handler              |
+| ------ | ---------------- | ---- | -------------------- |
+| GET    | /auth/nonce      | no   | `handleGetNonce`     |
+| POST   | /auth/login      | no   | `handleLogin`        |
+| GET    | /config          | no   | `handleConfig`       |
+| GET    | /gas-fee         | no   | `handleGasFee`       |
+| POST   | /auth/logout     | yes  | `handleLogout`       |
+| GET    | /pools           | yes  | `handlePools`        |
+| GET    | /user            | yes  | `handleUser`         |
+| POST   | /claim-and-swap  | yes  | `handleClaimAndSwap` |
+
+## Security notes
+
+- 🚨 **Never deploy `PrivateKeySigner` to production.** The private key lives in process memory and is trivially extractable from a compromised host. Use `examples/adapters/kms-signer.ts` as a starting point for a KMS/HSM integration.
+- 🔑 **`jwtSecret` must be at least 16 characters (32+ recommended) and rotated periodically.** Sessions survive a rotation because the JWT lookup cross-checks the session store — but existing tokens signed with the old secret will fail `verifyToken`, forcing users to re-login.
+- 🕐 **The default `MemorySessionStore` does not survive restarts.** Nonces and sessions are both lost. Use `examples/adapters/redis-session-store.ts` for anything past local development.
+- 🔒 **The `MintingGatewayError.safeToRetry` flag is load-bearing.** Do not ignore it in your API layer — surfacing `RELAY_REVERTED` as a retryable 400 will cause double-spend the moment a tx lands after the first response.
+
+## Tests
+
+The package ships with 142 unit tests covering every collaborator + the
+full gateway flow through mocked providers. Run them with:
+
+```bash
+pnpm --filter @pafi/issuer test
+```
+
+No network or on-chain state is required — all tests are hermetic.
+
+## Exports
+
+```ts
+import {
+  // Factory (recommended entry point)
+  createIssuerService,
+  type IssuerService,
+  type IssuerServiceConfig,
+
+  // Ledger
+  MemoryPointLedger,
+  type IPointLedger,
+  type LockedMintRequest,
+  type MintingStatus,
+
+  // Policy
+  DefaultPolicyEngine,
+  type IPolicyEngine,
+  type PolicyDecision,
+  type PolicyEvalRequest,
+
+  // Signer
+  PrivateKeySigner,                  // DEV ONLY
+  type IIssuerSigner,
+
+  // Auth
+  AuthService,
+  AuthError,
+  type AuthErrorCode,
+  type AuthContext,
+  MemorySessionStore,
+  type ISessionStore,
+  type Session,
+  NonceManager,
+  authenticateRequest,
+
+  // Relay + fees
+  RelayService,
+  RelayError,
+  type RelayErrorCode,
+  type SubmitMintAndSwapParams,
+  type RelayResult,
+  type OperatorWalletLike,
+  FeeManager,
+  type FeeManagerConfig,
+
+  // Gateway
+  MintingGateway,
+  MintingGatewayError,
+  type MintingGatewayErrorCode,
+  type MintAndCashOutRequest,
+  type MintAndCashOutResponse,
+  encodeExtData,
+
+  // Indexer
+  PointIndexer,
+  type PointIndexerConfig,
+  type MintEvent,
+  type IIndexerCursorStore,
+  InMemoryCursorStore,
+
+  // API handlers + HTTP contract (source of truth — FE imports these type-only)
+  IssuerApiHandlers,
+  type IssuerApiHandlersConfig,
+  type ApiConfigResponse,
+  type ApiNonceResponse,
+  type ApiLoginRequest,
+  type ApiLoginResponse,
+  type ApiGasFeeResponse,
+  type ApiPoolsRequest,
+  type ApiPoolsResponse,
+  type ApiUserRequest,
+  type ApiUserResponse,
+  type ApiClaimAndSwapRequest,
+  type ApiClaimAndSwapResponse,
+  type PoolsProvider,
+} from "@pafi/issuer";
+```
+
+### HTTP contract ownership
+
+`@pafi/issuer` is the **single source of truth** for the HTTP API contract
+between the issuer backend and any frontend / mobile / SDK consumer. The
+request/response types above are defined once here, then imported
+**type-only** by frontend code so browser bundles never pull in server
+code (`jose`, `node:crypto`, indexer polling loops, etc):
+
+```ts
+// Frontend — type-only import, erased at build time
+import type {
+  ApiLoginRequest,
+  ApiClaimAndSwapRequest,
+  ApiUserResponse,
+} from "@pafi/issuer";
+
+// Build your own fetch call with full type safety
+const res = await fetch(`${API_URL}/claim-and-swap`, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${token}`,
+  },
+  body: JSON.stringify(request satisfies ApiClaimAndSwapRequest),
+});
+const body = (await res.json()) as ApiClaimAndSwapResponse;
+```
+
+**`@pafi/core` deliberately does NOT ship an HTTP client** — it handles
+only cryptography (EIP-712 / EIP-4361), contract reads, and V4 quoting.
+That's what keeps the frontend bundle small and keeps the protocol
+contract in exactly one place.
+
+## License
+
+UNLICENSED — internal use by PAFI issuers.