chore: audit documentation

docs/operators/CONFIGURATION.md

@@ -1,5 +1,5 @@
 # Kora Configuration Reference
-*Last Updated: 2025-08-25*
+*Last Updated: 2025-10-28*
 
 Your Kora node will be signing transactions for your users, so it is important to configure it to only sign transactions that meet your business requirements. Kora gives you a lot of flexibility in how you configure your node, but it is important to understand the implications of your configuration. `kora.toml` is the control center for your Kora configuration. This document provides a comprehensive reference for configuring your Kora paymaster node through the `kora.toml` configuration file.
 
@@ -128,8 +128,11 @@ account_ttl = 60                    # Account data TTL in seconds (1 minute)
 
 ## Kora Usage Limits (optional)
 
-The `[kora.usage_limit]` section configures per-wallet transaction limiting to prevent abuse and ensure fair usage across your users. This could also be used to create rewards programs to subsidize users' transaction fees up to a certain limit.
-This feature requires Redis when enabled across multiple Kora instances:
+The `[kora.usage_limit]` section configures per-wallet transaction limiting to prevent abuse and ensure fair usage across your users. This could also be used to create rewards programs to subsidize users' transaction fees up to a certain limit. 
+
+**Important**: Currently, the only form of usage limiting supported by Kora is a **permanent limit**. Once a wallet reaches its transaction limit, it cannot be reset and the user will no longer be able to submit any more transactions using that same wallet. This limit persists until manually cleared from Redis or the Redis data is reset.
+
+**Note**: This feature requires Redis when enabled across multiple Kora instances:
 
 ```toml
 [kora.usage_limit]
@@ -266,6 +269,11 @@ blocked_account_extensions = [
 
 > *Note: Blocking extensions helps prevent interactions with tokens that have complex or potentially risky behaviors. For example, blocking `transfer_hook` prevents signing transactions for tokens with custom transfer logic.*
 
+### Security Considerations
+
+**PermanentDelegate Extension** - Tokens with this extension allow the delegate to transfer/burn tokens at any time without owner approval. This creates significant risks for the Kora node operator as payment funds can be seized after payment. 
+- Consider adding "permanent_delegate" to `blocked_mint_extensions` in [validation.token2022] unless explicitly needed for your use case.
+- Avoid using payment tokens with the `permanent_delegate` extension.
 
 ## Fee Payer Policy
 
@@ -293,7 +301,10 @@ allow_approve = false
 | `allow_close_account` | Allow closing token accounts where the Kora node's fee payer is the signer/authority | ✅ | boolean |
 | `allow_approve` | Allow token delegation/approval where the Kora node's fee payer is the signer/authority | ✅ | boolean |
 
-> *Note: For security reasons, it is recommended to set all of these to `false` and only enable as needed.*
+
+### Security Considerations
+
+**SECURITY WARNING:** For security reasons, it is recommended to set all of these to `false` and only enable as needed. This will prevent unwanted behavior such as users draining your fee payer account or burning tokens from your fee payer account.
 
 ## Price Configuration (optional)
 
@@ -321,6 +332,8 @@ margin = 0.1  # 10% margin (0.1 = 10%, 1.0 = 100%)
 
 ### Fixed Pricing
 
+**SECURITY WARNING:** Fixed pricing does **NOT** include fee payer outflow in the charged amount. This can allow users to drain your fee payer account if not properly configured.
+
 Charge a fixed amount in a specific token regardless of network fees:
 
 ```toml
@@ -329,7 +342,7 @@ type = "fixed"
 amount = 1000000  # Amount in token's base units
 token = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"  # USDC mint
 ```
-
+   
 ### Free Transactions
 
 Sponsor all transaction fees (no charge to users):
@@ -339,6 +352,35 @@ Sponsor all transaction fees (no charge to users):
 type = "free"
 ```
 
+#### Security Measures When Using Fixed/Free Pricing
+
+1. **Disable Transfer Operations** - Prevent fee payer from being used as source in transfers:
+   ```toml
+   [validation.fee_payer_policy.system]
+   allow_transfer = false              # Critical: Block SOL transfers
+   allow_create_account = false        # Block account creation
+
+   [validation.fee_payer_policy.spl_token]
+   allow_transfer = false              # Block SPL transfers
+
+   [validation.fee_payer_policy.token_2022]
+   allow_transfer = false              # Block Token2022 transfers
+   ```
+
+2. **Enable Authentication** - Use authentication to prevent abuse:
+   ```toml
+   [kora.auth]
+   api_key = "your-secure-api-key"
+   # or
+   hmac_secret = "your-minimum-32-character-hmac-secret"
+   ```
+
+3. **Set Conservative Limits** - Minimize exposure:
+   ```toml
+   [validation]
+   max_allowed_lamports = 1000000  # 0.001 SOL maximum
+   ```
+
 ## Performance Monitoring (optional)
 
 The `[metrics]` section configures metrics collection and monitoring. This section is optional and by default, metrics are disabled.

docs/operators/FEES.md

@@ -1,12 +1,18 @@
 # Kora Fee Estimation Resource Guide
 
-*Last updated: 2025-09-02*
+*Last updated: 2025-10-28*
 
-Kora estimates transaction fees when performing `estimate_transaction_fee`, `sign_transaction` and `sign_and_send_transaction` RPC methods. To estimate fees, Kora calculates the total cost for executing transactions on Solana, including network fees, account creation costs, and optional payment processing fees. This guide breaks down each component of the fee calculation.
+Kora estimates transaction fees when performing `estimate_transaction_fee` and `sign_transaction` RPC methods. To estimate fees, Kora calculates the total cost for executing transactions on Solana, including network fees, account creation costs, and optional payment processing fees. This guide breaks down each component of the fee calculation.
 
 ## Fee Calculation Formula
 
-The main entry point for fee estimation is `FeeConfigUtil::estimate_kora_fee()` in [`crates/lib/src/fee/fee.rs`](/crates/lib/src/fee/fee.rs). It uses the following generalized formula:
+The fee is determined by the pricing model configured in `kora.toml`: 
+
+- `PriceModel::Free` - Sponsors all transaction fees (total fee = 0)
+- `PriceModel::Fixed` - Charges a fixed amount in a specific token (regardless of network fees)
+- `PriceModel::Margin` - Adds a percentage margin to total fees.
+
+The main entry point for total fee estimation used in `PriceModel::Margin` is `FeeConfigUtil::estimate_kora_fee()` in [`crates/lib/src/fee/fee.rs`](/crates/lib/src/fee/fee.rs). It uses the following generalized formula:
 
 ```
 Total Fee = Base Fee 
@@ -15,7 +21,7 @@ Total Fee = Base Fee
           + Fee Payer Outflow 
           + Payment Instruction Fee 
           + Transfer Fee Amount
-          + Price Adjustment (if configured)
+          + Margin Adjustment
 ```
 
 ## Fee Components
@@ -28,4 +34,67 @@ Total Fee = Base Fee
 | **Fee Payer Outflow** | Total SOL the fee payer sends out in the transaction (transfers, account creations, etc.) | Sum of: System transfers from fee payer, CreateAccount funded by fee payer, Nonce withdrawals from fee payer | When fee payer performs System Program operations |
 | **Payment Instruction Fee** | Estimated cost of priority fees to add a payment instruction for gasless transactions | Fixed estimate: 50 lamports (`ESTIMATED_LAMPORTS_FOR_PAYMENT_INSTRUCTION`) | When payment is required but not included in transaction |
 | **Transfer Fee** | Token2022 transfer fees configured on the mint (e.g., 1% of transfer amount) | `Token2022Mint.calculate_transfer_fee(amount, epoch)` - Based on mint's transfer fee configuration | Only for Token2022 transfers to Kora payment address |
-| **Price Adjustment** | Kora's pricing model markup/adjustment | Configured price model in `validation.price` - Can add markup or fixed fee amount | When `[validation.price]` is provided in kora.toml (optional) |
+| **Margin Adjustment** | Kora's pricing model markup/adjustment | Configured margin in `validation.price` - Can add markup as a % of the total fee | When `[validation.price]` is provided in kora.toml |
+
+## Pricing Models & Fee Payer Outflow
+
+Kora supports three pricing models that determine how users are charged for transactions:
+
+### Margin Pricing (Default)
+- **Formula:** `Total Fee = (Base + Outflow + Other Components) × (1 + margin)`
+- **Includes Fee Payer Outflow:** Yes
+- **Best For:** Production deployments where fees should reflect actual costs with an added operating margin
+
+### Fixed Pricing
+- **Formula:** `Total Fee = Fixed Amount (in specified token)`
+- **Includes Fee Payer Outflow:** No
+- **Best For:** Simplified UX with predictable pricing in controlled environments
+
+### Free Pricing
+- **Formula:** `Total Fee = 0`
+- **Includes Fee Payer Outflow:** No (operator absorbs all costs)
+- **Best For:** Promotional campaigns, testing, or fully sponsored applications
+
+---
+
+## ⚠️ Security Warning: Fixed/Free Pricing Models
+
+**CRITICAL:** The fixed/free pricing models do **NOT** include fee payer outflow in the charged amount. This creates a significant security risk if not properly configured: If your fee payer policy allows transfers or other outflow operations, attackers can exploit this to drain your fee payer account:
+
+### Required Security Controls
+
+When using fixed/free pricing, you **MUST** configure restrictive fee payer policies:
+
+```toml
+[validation.fee_payer_policy.system]
+allow_transfer = false              # Block SOL transfers
+allow_create_account = false        # Block account creation with lamports
+
+[validation.fee_payer_policy.spl_token]
+allow_transfer = false              # Block SPL token transfers
+
+[validation.fee_payer_policy.token_2022]
+allow_transfer = false              # Block Token2022 transfers
+```
+
+### Additional Protections
+
+1. **Enable Authentication:** Always require API key or HMAC authentication with fixed pricing
+2. **Set Low Limits:** Use conservative `max_allowed_lamports` values
+3. **Monitor Usage:** Track unusual patterns of high-outflow transactions
+4. **Consider Margin Pricing:** Margin pricing automatically includes outflow costs
+
+### Validation Warnings
+
+Kora's config validator will warn you about dangerous configurations:
+
+```bash
+kora --config kora.toml config validate
+```
+
+Expected warnings for vulnerable configs:
+```
+⚠️  SECURITY: Fixed pricing with allow_transfer=true for System instructions.
+    Users can make the fee payer transfer arbitrary SOL amounts at fixed cost.
+    This can drain your fee payer account.
+```