docs: verify #451 FACTORY_ADDRESS guard docs and regression harness #996

Merged

PlasticDigits merged 2 commits from qa/451-verify-factory-address-docs into main

2026-07-01 00:30:33 +00:00

PlasticDigits commented

2026-06-30 22:21:07 +00:00

(Migrated from gitlab.com)

Summary

Aligns operator secrets, launch checklist Phase 0, deployment guide, indexer/QA invariants, and pair_discovery.rs comment with the merged ConfigError::EmptyFactoryAddress startup guard (MR !983 / commit 6ae40413).
Adds make verify-issue-451, make check-factory-address-docs, agent skill skills/AGENTS_FACTORY_ADDRESS_GUARD.md, and invariant Q5 in docs/qa-invariants.md.

Acceptance checklist

Item	Command / evidence	Result
Indexer startup rejects empty `FACTORY_ADDRESS` in every `RUN_MODE`	`make verify-issue-451` → step `empty_factory_address_rejected_in_dev`; manual: `FACTORY_ADDRESS=' ' … ./target/debug/cl8y-dex-indexer` → `Configuration error: FACTORY_ADDRESS must be non-empty…` exit 1	PASS
Post-deploy verification asserts `FACTORY_ADDRESS` non-empty	`grep 'FACTORY_ADDRESS not found' scripts/qa/verify-deploy.sh`; `make qa-verify-deploy` pre-flight (Q1)	PASS
Launch-checklist Phase 0 names non-empty `FACTORY_ADDRESS` precondition	`grep SEC-I02 docs/runbooks/launch-checklist.md`; `make check-factory-address-docs`	PASS
Staging/CI confirms guard before indexer runs	`.gitlab-ci.yml` `test-indexer-lib` runs `cargo test --lib` (includes `empty_factory_address_rejected_in_dev`); `make start-qa` runs `qa-verify-deploy` after deploy	PASS

Full regression: make verify-issue-451 (8/8 PASS).

Follow-ups

Consider adding verify-issue-451 to the Cloud Agent help one-liner in AGENTS.md if agents routinely verify SEC-I02 issues.

## Summary - Aligns operator secrets, launch checklist Phase 0, deployment guide, indexer/QA invariants, and `pair_discovery.rs` comment with the merged `ConfigError::EmptyFactoryAddress` startup guard (MR !983 / commit `6ae40413`). - Adds `make verify-issue-451`, `make check-factory-address-docs`, agent skill `skills/AGENTS_FACTORY_ADDRESS_GUARD.md`, and invariant **Q5** in `docs/qa-invariants.md`. ## Acceptance checklist | Item | Command / evidence | Result | |------|-------------------|--------| | Indexer startup rejects empty `FACTORY_ADDRESS` in every `RUN_MODE` | `make verify-issue-451` → step `empty_factory_address_rejected_in_dev`; manual: `FACTORY_ADDRESS=' ' … ./target/debug/cl8y-dex-indexer` → `Configuration error: FACTORY_ADDRESS must be non-empty…` exit 1 | **PASS** | | Post-deploy verification asserts `FACTORY_ADDRESS` non-empty | `grep 'FACTORY_ADDRESS not found' scripts/qa/verify-deploy.sh`; `make qa-verify-deploy` pre-flight (Q1) | **PASS** | | Launch-checklist Phase 0 names non-empty `FACTORY_ADDRESS` precondition | `grep SEC-I02 docs/runbooks/launch-checklist.md`; `make check-factory-address-docs` | **PASS** | | Staging/CI confirms guard before indexer runs | `.gitlab-ci.yml` `test-indexer-lib` runs `cargo test --lib` (includes `empty_factory_address_rejected_in_dev`); `make start-qa` runs `qa-verify-deploy` after deploy | **PASS** | Full regression: **`make verify-issue-451`** (8/8 PASS). ## Follow-ups - Consider adding `verify-issue-451` to the Cloud Agent help one-liner in `AGENTS.md` if agents routinely verify SEC-I02 issues.

PlasticDigits commented

2026-06-30 22:22:32 +00:00

(Migrated from gitlab.com)

Security review — MR !996

Commit reviewed: 0529634a84940d314e8599c9f0a3b0330c32b058
Scope: Documentation alignment for SEC-I02 / #451 (FACTORY_ADDRESS non-empty startup guard), regression harness (make verify-issue-451, make check-factory-address-docs), agent skill, Makefile wiring, and a comment/format-only touch in indexer/src/indexer/pair_discovery.rs.

Outcome: FINDINGS: 0 medium+

Summary: This MR does not change indexer runtime behavior beyond a doc comment and rustfmt-style formatting in pair_discovery.rs. The security control under test (ConfigError::EmptyFactoryAddress at config load in indexer/src/config.rs, merged in !983) is documented and regression-tested, not weakened.

Reviewed attack paths (none exploitable from this diff):

Spoofed pair indexing via empty FACTORY_ADDRESS: Still blocked at startup by factory_address.trim().is_empty() → EmptyFactoryAddress before the indexer serves traffic. The warn-and-skip branch in verify_factory_provenance remains defensive dead code on normal startup paths; this MR only documents that.
Injection / path traversal in new scripts: verify-issue-451.sh and check_factory_address_docs.py use fixed repo-relative paths and hardcoded env values; no attacker-controlled sinks.
Secret leakage / SSRF / XSS / authz: No new network surfaces, user input handlers, or credential handling in the diff.

Inline threads: None (no medium+ findings).

Security review: no medium+ findings on this diff.

## Security review — MR !996 **Commit reviewed:** `0529634a84940d314e8599c9f0a3b0330c32b058` **Scope:** Documentation alignment for SEC-I02 / #451 (`FACTORY_ADDRESS` non-empty startup guard), regression harness (`make verify-issue-451`, `make check-factory-address-docs`), agent skill, Makefile wiring, and a comment/format-only touch in `indexer/src/indexer/pair_discovery.rs`. **Outcome:** `FINDINGS: 0` medium+ **Summary:** This MR does not change indexer runtime behavior beyond a doc comment and rustfmt-style formatting in `pair_discovery.rs`. The security control under test (`ConfigError::EmptyFactoryAddress` at config load in `indexer/src/config.rs`, merged in !983) is documented and regression-tested, not weakened. **Reviewed attack paths (none exploitable from this diff):** - **Spoofed pair indexing via empty `FACTORY_ADDRESS`:** Still blocked at startup by `factory_address.trim().is_empty()` → `EmptyFactoryAddress` before the indexer serves traffic. The warn-and-skip branch in `verify_factory_provenance` remains defensive dead code on normal startup paths; this MR only documents that. - **Injection / path traversal in new scripts:** `verify-issue-451.sh` and `check_factory_address_docs.py` use fixed repo-relative paths and hardcoded env values; no attacker-controlled sinks. - **Secret leakage / SSRF / XSS / authz:** No new network surfaces, user input handlers, or credential handling in the diff. **Inline threads:** None (no medium+ findings). Security review: no medium+ findings on this diff.

PlasticDigits commented

2026-07-01 00:10:47 +00:00

(Migrated from gitlab.com)

added 9 commits

0529634a...4621116e - 8 commits from branch main
b5752c20 - Merge branch 'main' into qa/451-verify-factory-address-docs

Compare with previous version

added 9 commits <ul><li>0529634a...4621116e - 8 commits from branch <code>main</code></li><li>b5752c20 - Merge branch 'main' into qa/451-verify-factory-address-docs</li></ul> [Compare with previous version](/PlasticDigits/cl8y-dex-terraclassic/-/merge_requests/278/diffs?diff_id=1879512484&start_sha=0529634a84940d314e8599c9f0a3b0330c32b058)

PlasticDigits commented

2026-07-01 00:10:48 +00:00

(Migrated from gitlab.com)

Resolved merge conflicts with main (1 file: docs/operator-secrets.md).

Kept the #451 all-mode FACTORY_ADDRESS guard section and prod wording that references it instead of duplicating the requirement; incorporated main's #458 note that the non-loopback dual-zero startup guard does not apply in prod because rate limits are clamped to safe minimums.

Sanity: make check-factory-address-docs PASS.

Resolved merge conflicts with `main` (1 file: `docs/operator-secrets.md`). Kept the #451 all-mode `FACTORY_ADDRESS` guard section and prod wording that references it instead of duplicating the requirement; incorporated `main`'s #458 note that the non-loopback dual-zero startup guard does not apply in prod because rate limits are clamped to safe minimums. Sanity: `make check-factory-address-docs` PASS.

PlasticDigits commented

2026-07-01 00:12:35 +00:00

(Migrated from gitlab.com)

Security review — MR !996 (re-run)

Commit reviewed: b5752c20c50b8a03699921d32dcff5d0c797ae34
Scope: Documentation alignment for SEC-I02 / #451 (FACTORY_ADDRESS non-empty startup guard), regression harness (make verify-issue-451, make check-factory-address-docs), agent skill, Makefile wiring, comment/rustfmt in indexer/src/indexer/pair_discovery.rs, and rustfmt-only touch in smartcontracts/contracts/factory/src/contract.rs test module. Includes post-main merge conflict resolution in docs/operator-secrets.md.

Outcome: FINDINGS: 0 medium+

Delta since prior review (0529634a): Merge commit b5752c20 rebased onto current main; no new runtime code paths or weakened controls. Operator-secrets merge kept the all-mode FACTORY_ADDRESS guard section and incorporated main's #458 prod rate-limit note without removing SEC-I02 enforcement.

Reviewed attack paths (none exploitable from this diff):

Spoofed pair indexing via empty FACTORY_ADDRESS: Still blocked at startup by factory_address.trim().is_empty() → ConfigError::EmptyFactoryAddress in indexer/src/config.rs (merged !983). This MR documents and regression-tests that guard; the warn-and-skip branch in verify_factory_provenance remains unreachable defensive dead code.
Injection / path traversal in new scripts: verify-issue-451.sh and check_factory_address_docs.py use fixed repo-relative paths and hardcoded env values; no attacker-controlled sinks.
Secret leakage / SSRF / XSS / authz: No new network surfaces, user input handlers, or credential handling in the diff.

Inline threads: None (no medium+ findings).

Security review: no medium+ findings on this diff.

## Security review — MR !996 (re-run) **Commit reviewed:** `b5752c20c50b8a03699921d32dcff5d0c797ae34` **Scope:** Documentation alignment for SEC-I02 / #451 (`FACTORY_ADDRESS` non-empty startup guard), regression harness (`make verify-issue-451`, `make check-factory-address-docs`), agent skill, Makefile wiring, comment/rustfmt in `indexer/src/indexer/pair_discovery.rs`, and rustfmt-only touch in `smartcontracts/contracts/factory/src/contract.rs` test module. Includes post-`main` merge conflict resolution in `docs/operator-secrets.md`. **Outcome:** `FINDINGS: 0` medium+ **Delta since prior review (`0529634a`):** Merge commit `b5752c20` rebased onto current `main`; no new runtime code paths or weakened controls. Operator-secrets merge kept the all-mode `FACTORY_ADDRESS` guard section and incorporated `main`'s #458 prod rate-limit note without removing SEC-I02 enforcement. **Reviewed attack paths (none exploitable from this diff):** - **Spoofed pair indexing via empty `FACTORY_ADDRESS`:** Still blocked at startup by `factory_address.trim().is_empty()` → `ConfigError::EmptyFactoryAddress` in `indexer/src/config.rs` (merged !983). This MR documents and regression-tests that guard; the warn-and-skip branch in `verify_factory_provenance` remains unreachable defensive dead code. - **Injection / path traversal in new scripts:** `verify-issue-451.sh` and `check_factory_address_docs.py` use fixed repo-relative paths and hardcoded env values; no attacker-controlled sinks. - **Secret leakage / SSRF / XSS / authz:** No new network surfaces, user input handlers, or credential handling in the diff. **Inline threads:** None (no medium+ findings). Security review: no medium+ findings on this diff.