[Docpoc] SDP Security

platforms/stellar-disbursement-platform/admin-guide/security.mdx

@@ -0,0 +1,69 @@
+---
+title: Security
+sidebar_position: 60
+---
+
+This manual outlines the security measures implemented in the Stellar Disbursement Platform (SDP) to protect the integrity of the platform and its users. By adhering to these guidelines, you can ensure that your use of the SDP is as secure as possible.
+
+Security is a critical aspect of the SDP. The measures outlined in this document are designed to mitigate risks and enhance the security of the platform. Users are strongly encouraged to follow these guidelines to protect their accounts and operations.
+
+### Implementation of reCAPTCHA
+
+Google's reCAPTCHA has been integrated into the SDP to prevent automated attacks and ensure that interactions are performed by humans, not bots.
+
+ReCAPTCHA is enabled by default and can be disabled by setting the `DISABLE_RECAPTCHA` environment variable to `true`.
+
+Configuration is available at two levels:
+
+1. **Environment default** – Set `DISABLE_RECAPTCHA=true` to apply the setting globally across all tenants.
+2. **Tenant override** – Each organization can enable or disable reCAPTCHA via its own settings (UI or API). When present, the tenant-level choice overrides the environment default.
+
+Use the following environment variables to control how reCAPTCHA behaves:
+
+- `CAPTCHA_TYPE` – `GOOGLE_RECAPTCHA_V2` (default) or `GOOGLE_RECAPTCHA_V3`.
+- `RECAPTCHA_SITE_KEY` – Google site key issued for the chosen CAPTCHA type.
+- `RECAPTCHA_SITE_SECRET_KEY` – Google secret key paired with the site key.
+- `RECAPTCHA_V3_MIN_SCORE` – Minimum allowed score (0.0–1.0, default 0.5) when `CAPTCHA_TYPE=GOOGLE_RECAPTCHA_V3`.
+
+**Note:** Disabling reCAPTCHA in production (pubnet) deployments substantially reduces protection against automated abuse. This configuration should be used only when equivalent compensating controls are in place.
+
+### Enforcement of Multi-Factor Authentication
+
+Multi-Factor Authentication (MFA) provides an additional layer of security to user accounts. It is enforced by default on the SDP and it relies on OTPs sent to the account's email.
+
+MFA is enabled by default and can be disabled in the development environment by setting the `DISABLE_MFA` environment variable to `true`.
+
+**Note:** MFA cannot be disabled in production (pubnet) environments due to security risk.
+
+### Request Rate Limiting and Network Protections
+
+SDP enforces rate limiting at the HTTP layer to curb scripted abuse. Each unique `<IP, endpoint>` pair is limited to 40 requests within 20 seconds (rolling window). Requests that exceed this threshold receive throttled responses until the window resets.
+
+### Role-Based Permissions and Authentication
+
+All authenticated API routes require clients to present either an SDP-issued API key or a JWT derived from the SEP10/SEP24 flows. After authentication, the platform enforces fine-grained authorization through role-based permissions. The primary roles are:
+
+- **Owner** – Full control, including creating users, assigning roles, and editing organization configuration. Owner is the only role that can grant or revoke access for others.
+- **Financial Controller** – Can perform every operational task (wallets, assets, disbursements, statistics) except user management. This role is ideal for finance staff executing payouts.
+- **Developer** – Manages technical configuration such as wallets, assets, and API keys, and can view statistics; it cannot modify users or financial workflows.
+- **Business** – Read-only across business data (disbursements, recipients, statistics) but cannot access user management details.
+- **Initiator** – Creates and saves disbursements but cannot submit them. Mutually exclusive with the Approver role to enforce separation of duties.
+- **Approver** – Reviews and submits disbursements but cannot create new ones; mutually exclusive with Initiator.
+
+Each API endpoint specifies which roles may access it—for example, API key management routes (`/api-keys`) require Owner or Developer, while disbursement creation requires Initiator or Financial Controller and submission requires Approver or Financial Controller. This combination of strong authentication plus least-privilege, role-based authorization ensures that only the appropriate personnel can perform sensitive operations.
+
+To enhance security, disbursement responsibilities should be distributed among multiple financial controller users. A recommended configuration includes:
+
+1. **Approval Flow**: Enable the approval flow on the organization page to require two users for the disbursement process. The owner can do that at _Profile > Organization > ... > Edit details > Approval flow > Confirm_.
+2. **Financial Controller Role**: Create two users with the _Financial Controller_ role on the organization page to enforce separation of duties. The owner can do that at _Settings > Team Members_.
+3. **Owner Account Management**: Use the Owner account solely for user management and organization configuration. Avoid using the Owner account for financial controller tasks to minimize the exposure of that account.
+
+### Best Practices for Wallet Management
+
+The SDP wallet should be used primarily as a hot wallet with a limited amount of funds to minimize potential losses.
+
+#### Hot and Cold Wallets
+
+- A hot wallet is connected to the internet and allows for quick transactions.
+- A cold wallet is offline and used for storing funds securely.
+- Learn more about these concepts at [Investopedia](https://www.investopedia.com/hot-wallet-vs-cold-wallet-7098461).