In scope — please report these:

• Smart contract vulnerabilities (reentrancy, fund loss, logic errors in vault/rebalance/offramp)
• Authentication or authorization bypass
• Data exposure (user PII, private keys, JWT secrets)
• Injection attacks (SQL, command, XSS with financial impact)
• Privilege escalation in the API or admin endpoints
• Cryptographic weaknesses

Out of scope — do not report these as security issues:

• Feature requests or general usability bugs
• UI/styling issues with no security impact
• Rate-limiting on non-sensitive endpoints
• Issues requiring physical access to a user's device
• Self-XSS or social engineering attacks

Do NOT open a public GitHub issue for security vulnerabilities. Doing so exposes users before a fix is available.

Instead, use one of the following:

1. GitHub Private Vulnerability Reporting (preferred) — click "Report a vulnerability" under the Security tab of this repository.
2. Email — send a report to security@nester.dev with the subject line [SECURITY] <brief description>.

• Affected component (smart contract name, API endpoint, service)
• Description of the vulnerability and its potential impact
• Step-by-step reproduction instructions
• Any proof-of-concept code or screenshots (if safe to share)
• Your severity assessment (Critical / High / Medium / Low)

Every Nester contract shares one role model (nester_access_control::Role) rather than a single admin key:

The Guardian asymmetry is the load-bearing guarantee. A Guardian key can always make a vault safer — pause it, halt new deposits, trip the circuit breaker into FullHalt — and can never make it riskier: it cannot unpause, cannot upgrade, cannot withdraw, and cannot even loosen the breaker thresholds that constrain it. Reversing anything a Guardian does always requires a higher role (Admin/Upgrader) to run the staged, cooled-down recovery path (recover_next_stage). Practically, this means a Guardian key can be held more widely and reacted with faster than an Admin key: a compromised Guardian can at worst halt the protocol — annoying and fully recoverable — never drain it.

Every role transfer is two-step (transfer_role / accept_role, cancellable via cancel_role_transfer) so a mistyped or uncontrolled successor address can never take over in one move. Operational roles can be time-bounded with grant_role_until so a forgotten grant to a rotated-away key stops authorising on its own. The full role state is inspectable on-chain via has_role, get_role_members (bounded), and role_expires_at.

On-chain roles vs application roles: the RBAC above lives entirely in the Soroban contracts. The user_roles tables in the API's Postgres migrations are a separate, application-level authorization layer (who can see what in the dashboard) and do not confer any on-chain authority — do not conflate the two when reasoning about contract security.

The vault trips itself automatically rather than waiting for an operator to notice a problem. Four independently-configurable conditions escalate a graded severity (Normal → Throttled → DepositsHalted → FullHalt):

• Share-price move — an implausible change in share price within a rolling window halts new deposits.
• Yield sanity — a single report_yield call larger than a configured fraction of total assets is rejected (not applied) rather than accepted, and halts new deposits.
• Withdrawal velocity — cumulative withdrawal value (not transaction count) within a rolling window throttles the vault. A configurable margin above the raw threshold prevents a dust withdrawal from griefing the vault into a halt for free.
• Source failure — consecutive yield-adapter failures halt new deposits.

The emergency withdrawal queue is never gated by severity — it works identically at every level, including FullHalt, because a breaker that stops users from leaving is a trap, not a safety device. Recovery only ever moves one severity stage at a time, only after a configurable cooldown, and only for callers holding Admin/Upgrader — never Guardian.

Nester uses envelope encryption with key versioning and rotation for all sensitive user data stored at rest. The scheme is implemented in apps/api/internal/crypto/account_cipher.go and reused across all domains.

Master Key (never stored in the application)
    └── Key-Encryption Keys (KEKs) — versioned, configured via env vars
        └── AES-256-GCM Data Key (derived per cipher instance)
            └── Ciphertext stored in `*_encrypted` columns, tagged with `key_version`

Key configuration (environment variables):

Fields that need exact-match lookup (deduplication, find-by-identifier) use a blind index: a keyed HMAC-SHA256 of the normalized plaintext stored in a separate column. The HMAC key is independent of the encryption keys — either the v1 KEK or the explicit ACCOUNT_CIPHER_FINGERPRINT_KEY — so the index cannot be used to attack the ciphertext even if both the index and ciphertext are leaked in the same breach.

Limitations:

• Exact-match only: No prefix, range or fuzzy search on blind indexes.
• Collision resistant: HMAC-SHA256 produces a 256-bit digest; collisions are not a practical concern.

The cmd/rotate_keys command re-encrypts stored ciphertext under the active key version. It processes all encrypted domains (bank accounts, KYC documents) in a single run. The rotator is:

• Idempotent: Rows already on the active version are skipped.
• Resumable: Each row is committed independently; an interrupted run picks up where it left off.
• Safe: Only row IDs and key versions are logged — never plaintext, ciphertext, or keys.

A complete data-classification inventory is maintained at apps/api/internal/crypto/DATA_CLASSIFICATION.md. Every column holding user data is classified as HIGH (sensitive, encrypted), MEDIUM (indirect PII), or LOW (non-sensitive).

When encryption is extended to a new domain, existing plaintext rows are backfilled using a dedicated command (e.g. cmd/backfill_kyc_encryption). The migration pattern follows:

1. Add encrypted columns alongside existing plaintext columns (rollback-safe).
2. Run a batched, resumable backfill job to populate encrypted values.
3. Verify the backfill is complete.
4. Drop plaintext columns in a separate, later migration after confidence is established.

Plaintext is never dropped in the same step that introduces ciphertext.

We maintain a list of known vulnerabilities in our dependency chain that we have assessed and accepted based on their risk profile:

Mitigation strategy: Our CI/CD pipeline (govulncheck step in .github/workflows/security.yml) explicitly allows known accepted vulnerabilities and only fails on new or unreviewed vulnerabilities.

To report a vulnerability not listed here, see Reporting a Vulnerability above.

Nester commits to not pursuing legal action against security researchers who:

• Report vulnerabilities through this policy in good faith
• Avoid accessing, modifying, or deleting user data beyond what is necessary to demonstrate the issue
• Do not disrupt production services or degrade user experience during testing
• Give us reasonable time to resolve the issue before public disclosure

We maintain a Hall of Fame for researchers who responsibly disclose valid security issues. Credit will be given in the relevant release notes and security advisory unless you prefer to remain anonymous.

We do not currently operate a paid bug bounty program, but we appreciate and publicly recognize all valid reports.

Nester maintains a cryptographically hash-chained audit log for all security-relevant actions (admin operations, role changes, fund movements, configuration changes, authentication events). The goal is to make silent modification or deletion of log entries detectable even by a compromised database or malicious insider.

Each audit log entry includes four chain fields in addition to the standard event payload:

Hash input canonical form — deterministic JSON serialization (sorted keys):

SHA256( JSON({sequence, prev_hash, actor, action, target, detail, timestamp}) )

Entries are written inside a SERIALIZABLE isolation-level transaction and guarded by an in-process sync.Mutex. This ensures:

1. No two goroutines can race on the sequence counter.
2. The database rejects non-serial concurrent writes.
3. Every new entry's prev_hash exactly matches the entry_hash of the previous entry.

The AuditService.VerifyChain(ctx, fromSeq, toSeq) method:

1. Fetches entries in sequence order from fromSeq to toSeq.
2. Detects sequence gaps (a gap means an entry was deleted).
3. Recomputes each entry_hash from the raw fields and compares it to the stored value. A mismatch means the entry was modified.
4. Checks prev_hash linkage across entries.

Returns (ok bool, brokenAtSeq int64, err error) — when ok=false, brokenAtSeq is the sequence number where the first break was detected.

scheduler.AuditChainVerifier runs on a configurable interval (default: 30 minutes). On each tick it calls VerifyChain over the entire table. If a break is found, it calls ChainBreakAlerter.AlertChainBreak — in production this should page on-call.

Environment variables:

AUDIT_VERIFIER_ENABLED=true
AUDIT_VERIFIER_INTERVAL_MINUTES=30

Administrators can trigger a one-shot integrity check via:

GET /api/v1/admin/audit/verify
Authorization: Bearer <admin JWT>

Response (intact chain):

{ "chain_ok": true, "broken_at_sequence": 0 }

Response (break detected):

{ "chain_ok": false, "broken_at_sequence": 7, "error": "entry_hash mismatch at sequence 7" }

Sensitive fields (e.g. plaintext tokens inadvertently logged) can be redacted via AuditService.RedactEntry. Redaction:

• Replaces the targeted field value with "[REDACTED]" in detail.
• Sets redacted = true on the entry.
• Appends a new REDACTION audit entry (which is itself chained), so the redaction event is itself tamper-evident.
• The original entry_hash is preserved so historical chains that reference this entry remain verifiable.

The latest entry's hash can be anchored outside the database via AuditService.AnchorLatestEntry:

• MVP: Written to an append-only local file (AUDIT_ANCHOR_FILE_PATH).
• Production target: Published to a Stellar ledger transaction via apps/api/internal/stellar/invoker.go.

Once anchored, the anchored = true and anchor_tx_hash are set. Any later modification of the anchored entry can be proved fraudulent by comparing against the external anchor.

Note: The hash-chained model provides tamper evidence, not full tamper prevention. A sufficiently privileged attacker who can also rewrite the anchor store could still forge entries. Full prevention requires HSM-backed signing, which is tracked as a future enhancement.