code/cl8y-dex-terraclassic

Fork 0

Security: no user-facing incident explanation for pause/blacklist/rate-limit states and missing link from security docs [SEC-A03] #390

New issue

Closed

opened 2026-06-18 15:08:58 +00:00 by totdking · 9 comments

totdking commented

2026-06-18 15:08:58 +00:00

(Migrated from gitlab.com)

No description provided.

totdking commented

2026-06-18 15:12:17 +00:00

(Migrated from gitlab.com)

Checklist Item

SEC-A03: Add a "what happens during an incident" explanation: pause/blacklist/rate-limit actions, expected user impact, and how funds/LP positions are handled. Verify: runbook or FAQ reviewed by developer and linked from security docs.

Summary

All incident-related documentation in the repo is either admin-facing, integration-reference, or terse technical invariants. There is no single user-facing document explaining what pause, blacklist, and rate-limit mean for a regular user, how their funds and LP positions are handled during each state, or what to do when the restriction is lifted. Nothing matching this description is linked from the security docs.

What Was Checked

docs/security-model.md -- technical governance/admin doc, not user-facing
docs/contracts-security-audit.md -- invariant L6 documents pause mechanics for developers, not users
docs/adr/0003-governance-trading-blacklist.md -- ADR explaining blacklist design, admin-focused
docs/limit-orders.md -- pause section covers limit order freeze mechanics for integrators
docs/templates/incident-dex-indexer.md -- internal incident command template for admin triage
docs/integrators.md -- integration reference, not user communication
docs/runbooks/ -- all runbooks are admin operational guides
Entire repo searched for FAQ files: none found
docs/security-model.md checked for links to any user-facing runbook or FAQ: none found

Expected (per checklist)

A runbook or FAQ must exist that explains in plain user-facing language: what pause, blacklist, and rate-limit do; what the user will see and cannot do during each state; that funds, LP positions, and limit order escrow are safe and recoverable; and what to do when the restriction is lifted. This document must be linked from docs/security-model.md or equivalent security entry point.

Actual

No such document exists. The closest content is:

frontend-dapp/src/services/terraclassic/blacklist.ts lines 39-53: inline UI strings ("Swaps, liquidity, and limit orders are disabled until governance removes the restriction") -- not a standalone doc
frontend-dapp/src/components/trade/TradeOrderTicket.tsx lines 674-675: pause banner copy referencing invariant L6 and a GitLab issue number -- not user-readable
docs/contracts-security-audit.md: invariant L6 states "parked expired escrow stays in EXPIRED_LIMIT_CLAIMS until unpause" -- technical invariant, not user guidance

None of these are linked from security docs or surfaced as a user-readable FAQ.

Evidence

docs/security-model.md: no link to incident FAQ or user-facing runbook
docs/runbooks/launch-checklist.md: admin deploy checklist only, no user impact section
docs/templates/incident-dex-indexer.md: internal triage template, no user communication section
Entire docs/ directory: no file named faq.md, incident-user-guide.md, or equivalent
frontend-dapp/src/: no modal, page, or help component explaining incident impact to users beyond inline button/banner copy

Suggested Fix

Create a user-facing incident FAQ or runbook section (could be a new docs/user-incident-faq.md or a section added to docs/security-model.md) covering:

What happens to swaps during a pair pause (blocked, retry after unpause)
What happens to LP positions during a pair pause (cannot withdraw, funds held safely in contract)
What happens to limit orders during a pair pause (cannot place, cancel, or claim parked expired orders; escrow held safely until unpause)
What happens when a wallet is blacklisted (all actions blocked, funds recoverable when restriction lifted)
What happens when a token or pair is blacklisted (affected trading paths blocked, unaffected pairs remain open)
What to do when rate-limited (wait and retry, no funds at risk)
What the recovery path looks like after each restriction is lifted

Link this document from docs/security-model.md and from LegalFooterNotice.tsx (or the security posture page once Issue 1 is resolved).

Verification Checklist

Steps to confirm the fix is complete and the checklist item can be marked done.

A user-facing incident explanation document exists in docs/
Document covers pair pause impact on swaps, LP positions, and limit orders
Document covers wallet blacklist impact and fund recovery path
Document covers token and pair blacklist impact
Document covers rate-limit behavior and retry guidance
Document is linked from docs/security-model.md
Developer has reviewed the document (noted in MR or issue comment)

Labels

~security , pre-launch

Cc: @PlasticDigits

### Checklist Item SEC-A03: Add a "what happens during an incident" explanation: pause/blacklist/rate-limit actions, expected user impact, and how funds/LP positions are handled. Verify: runbook or FAQ reviewed by developer and linked from security docs. --- ### Summary All incident-related documentation in the repo is either admin-facing, integration-reference, or terse technical invariants. There is no single user-facing document explaining what pause, blacklist, and rate-limit mean for a regular user, how their funds and LP positions are handled during each state, or what to do when the restriction is lifted. Nothing matching this description is linked from the security docs. --- ### What Was Checked - `docs/security-model.md` -- technical governance/admin doc, not user-facing - `docs/contracts-security-audit.md` -- invariant L6 documents pause mechanics for developers, not users - `docs/adr/0003-governance-trading-blacklist.md` -- ADR explaining blacklist design, admin-focused - `docs/limit-orders.md` -- pause section covers limit order freeze mechanics for integrators - `docs/templates/incident-dex-indexer.md` -- internal incident command template for admin triage - `docs/integrators.md` -- integration reference, not user communication - `docs/runbooks/` -- all runbooks are admin operational guides - Entire repo searched for FAQ files: none found - `docs/security-model.md` checked for links to any user-facing runbook or FAQ: none found --- ### Expected (per checklist) A runbook or FAQ must exist that explains in plain user-facing language: what pause, blacklist, and rate-limit do; what the user will see and cannot do during each state; that funds, LP positions, and limit order escrow are safe and recoverable; and what to do when the restriction is lifted. This document must be linked from `docs/security-model.md` or equivalent security entry point. --- ### Actual No such document exists. The closest content is: - `frontend-dapp/src/services/terraclassic/blacklist.ts` lines 39-53: inline UI strings ("Swaps, liquidity, and limit orders are disabled until governance removes the restriction") -- not a standalone doc - `frontend-dapp/src/components/trade/TradeOrderTicket.tsx` lines 674-675: pause banner copy referencing invariant L6 and a GitLab issue number -- not user-readable - `docs/contracts-security-audit.md`: invariant L6 states "parked expired escrow stays in EXPIRED_LIMIT_CLAIMS until unpause" -- technical invariant, not user guidance None of these are linked from security docs or surfaced as a user-readable FAQ. --- ### Evidence - `docs/security-model.md`: no link to incident FAQ or user-facing runbook - `docs/runbooks/launch-checklist.md`: admin deploy checklist only, no user impact section - `docs/templates/incident-dex-indexer.md`: internal triage template, no user communication section - Entire `docs/` directory: no file named faq.md, incident-user-guide.md, or equivalent - `frontend-dapp/src/`: no modal, page, or help component explaining incident impact to users beyond inline button/banner copy --- ### Suggested Fix Create a user-facing incident FAQ or runbook section (could be a new `docs/user-incident-faq.md` or a section added to `docs/security-model.md`) covering: - What happens to swaps during a pair pause (blocked, retry after unpause) - What happens to LP positions during a pair pause (cannot withdraw, funds held safely in contract) - What happens to limit orders during a pair pause (cannot place, cancel, or claim parked expired orders; escrow held safely until unpause) - What happens when a wallet is blacklisted (all actions blocked, funds recoverable when restriction lifted) - What happens when a token or pair is blacklisted (affected trading paths blocked, unaffected pairs remain open) - What to do when rate-limited (wait and retry, no funds at risk) - What the recovery path looks like after each restriction is lifted Link this document from `docs/security-model.md` and from `LegalFooterNotice.tsx` (or the security posture page once Issue 1 is resolved). --- ### Verification Checklist Steps to confirm the fix is complete and the checklist item can be marked done. - [ ] A user-facing incident explanation document exists in `docs/` - [ ] Document covers pair pause impact on swaps, LP positions, and limit orders - [ ] Document covers wallet blacklist impact and fund recovery path - [ ] Document covers token and pair blacklist impact - [ ] Document covers rate-limit behavior and retry guidance - [ ] Document is linked from `docs/security-model.md` - [ ] Developer has reviewed the document (noted in MR or issue comment) --- ### Labels <span dir=""> </span> ~security <span dir="">, `pre-launch`</span> Cc: @PlasticDigits

totdking commented

2026-06-18 15:38:05 +00:00

(Migrated from gitlab.com)

mentioned in issue #381

PlasticDigits commented

2026-06-19 01:40:56 +00:00

(Migrated from gitlab.com)

mentioned in commit 1227fe94bd

mentioned in commit 1227fe94bddc38506fc367dbbffdc37e8fb9e530

PlasticDigits commented

2026-06-19 01:41:14 +00:00

(Migrated from gitlab.com)

mentioned in merge request !919

PlasticDigits commented

2026-06-19 06:07:11 +00:00

(Migrated from gitlab.com)

mentioned in commit a43de8c75d

mentioned in commit a43de8c75db2db9789eccdd159bd4408e00bdcbb

PlasticDigits commented

2026-06-19 06:09:35 +00:00

(Migrated from gitlab.com)

mentioned in merge request !915

PlasticDigits commented

2026-06-19 08:21:52 +00:00

(Migrated from gitlab.com)

Verification complete — SEC-A03 (#390)

Verified on main at 13900236 (merged via !919). No additional repo changes required.

Acceptance checklist

Criterion	How verified	Result
User-facing incident doc exists in `docs/`	`test -f docs/user-incident-faq.md`	PASS
Covers pair pause (swaps, LP, limits)	Doc § Pair pause; `grep 'Withdraw liquidity\|Limit order escrow'`	PASS
Covers wallet blacklist + recovery	Doc § Wallet blacklist; `grep UnblacklistWallet`	PASS
Covers token blacklist	Doc § Token blacklist	PASS
Covers pair blacklist	Doc § Pair blacklist	PASS
Covers rate-limit behavior + retry	Doc § Rate limits (HTTP 429, wrap-mapper, factory)	PASS
Linked from `docs/security-model.md`	`grep user-incident-faq docs/security-model.md` (2 links)	PASS
Developer reviewed document	MR !919 description + security review comment (2026-06-19, FINDINGS: 0 medium+)	PASS

Automated checks

make check-user-incident-faq-docs
→ OK: docs/user-incident-faq.md covers SEC-A03 topics and is linked from security docs + footer

npm run test:unit -- src/components/legal/__tests__/LegalFooterNotice.test.tsx
→ 3 passed (footer FAQ link href/label/target/rel)

npm run test:unit -- src/pages/TradePage.test.tsx -t "pause banner"
→ 1 passed (pause banner + disabled limit actions; FAQ href via USER_INCIDENT_FAQ_HREF)

Cross-links confirmed

docs/security-model.md → user-incident-faq.md (entry-point section + blacklist recovery)
frontend-dapp/src/components/legal/legalCopy.ts → USER_INCIDENT_FAQ_HREF
LegalFooterNotice.tsx, TradeOrderTicket.tsx, LimitOrdersPage.tsx → FAQ link with noopener noreferrer
Drift guard: scripts/check_user_incident_faq_docs.py (wired in make lint)
Agent playbook: skills/AGENTS_USER_INCIDENT_FAQ.md

Closing as complete.

## Verification complete — SEC-A03 (#390) Verified on `main` at `13900236` (merged via [!919](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/merge_requests/201)). No additional repo changes required. ### Acceptance checklist | Criterion | How verified | Result | |-----------|--------------|--------| | User-facing incident doc exists in `docs/` | `test -f docs/user-incident-faq.md` | **PASS** | | Covers pair pause (swaps, LP, limits) | Doc § Pair pause; `grep 'Withdraw liquidity\|Limit order escrow'` | **PASS** | | Covers wallet blacklist + recovery | Doc § Wallet blacklist; `grep UnblacklistWallet` | **PASS** | | Covers token blacklist | Doc § Token blacklist | **PASS** | | Covers pair blacklist | Doc § Pair blacklist | **PASS** | | Covers rate-limit behavior + retry | Doc § Rate limits (HTTP 429, wrap-mapper, factory) | **PASS** | | Linked from `docs/security-model.md` | `grep user-incident-faq docs/security-model.md` (2 links) | **PASS** | | Developer reviewed document | MR !919 description + security review comment (2026-06-19, FINDINGS: 0 medium+) | **PASS** | ### Automated checks ```text make check-user-incident-faq-docs → OK: docs/user-incident-faq.md covers SEC-A03 topics and is linked from security docs + footer npm run test:unit -- src/components/legal/__tests__/LegalFooterNotice.test.tsx → 3 passed (footer FAQ link href/label/target/rel) npm run test:unit -- src/pages/TradePage.test.tsx -t "pause banner" → 1 passed (pause banner + disabled limit actions; FAQ href via USER_INCIDENT_FAQ_HREF) ``` ### Cross-links confirmed - `docs/security-model.md` → `user-incident-faq.md` (entry-point section + blacklist recovery) - `frontend-dapp/src/components/legal/legalCopy.ts` → `USER_INCIDENT_FAQ_HREF` - `LegalFooterNotice.tsx`, `TradeOrderTicket.tsx`, `LimitOrdersPage.tsx` → FAQ link with `noopener noreferrer` - Drift guard: `scripts/check_user_incident_faq_docs.py` (wired in `make lint`) - Agent playbook: `skills/AGENTS_USER_INCIDENT_FAQ.md` Closing as complete.

PlasticDigits (Migrated from gitlab.com) closed this issue

2026-06-19 08:21:56 +00:00

PlasticDigits commented

2026-06-19 08:24:08 +00:00

(Migrated from gitlab.com)

mentioned in issue #387