#21 create audit evidence index for aegis contracts fix

[onakijames-droid]

CLOSE #21 create audit evidence index for aegis contracts fix

Description

Implements the audit evidence index requested in the issue: one canonical
location that organises every security-relevant contract document and test in
this repository, and is honest about what is missing.

What changed (2 created · 3 modified · 2 renamed · 0 contract code touched):

Action	File	Details
🆕 Created	docs/audit-evidence-index.md (314 lines)	The index itself: 11-area readiness table (compliance, admin roles, minting, transfers, asset metadata, storage, events, errors, pause, migration, test coverage) → per-area evidence with source-line anchors → 9-invariant register (I1–I9: enforcement line + verifying test + ✅/⚠ status) → full error string catalogue → test-coverage matrix (9 contract + 106 monitoring tests) → 14-item known-gap register (G-1…G-14) → reproduction commands
🆕 Created	docs/threat-model.md (87 lines)	New threat model (did not exist): assets, actors/trust assumptions, 9 security objectives, 14 threats (T1–T14) each mapped to mitigating code lines, test evidence and residual risk
✏️ Modified	README.md	New Security & Auditing section linking the index + threat model + supporting docs; fixed monitoring path drift (monitoring/ → .github/monitoring/)
✏️ Modified	Makefile	Repointed monitor-install/monitor-test/monitor/monitor-demo/clean from monitoring/ to .github/monitoring/ (actual service location)
✏️ Modified	.gitignore	Added test_snapshots/ (cargo-test generated artifact)
🔀 Renamed	.github/monitoring/src/analytics/Index.js → index.js	Zero content change. Case mismatch broke integration.test.js, onchain-compat.test.js, triggers.test.js on case-sensitive filesystems (3 pre-existing failures)
🔀 Renamed	.github/monitoring/tests/store.tests.js → store.test.js	Zero content change. Plural filename meant node --test tests/ never discovered the file — 14 tests were silently not running

The renames + path fixes were found while validating that the evidence the
index links actually runs; without them the index would have pointed at a
test suite that could not pass in this tree.

Not modified (deliberate): no Rust source (src/lib.rs, src/asset.rs,
src/compliance.rs, src/events.rs, src/test.rs), Cargo.toml,
Cargo.lock, docs/architecture.md, docs/contract-spec.md — the issue is
documentation-only, so contract behaviour, build, and tests are untouched.

Related Issues

Fixes #NN — Create an audit evidence index that organises all security-relevant contract documentation and tests (Files/areas: docs/, README.md, tests/)

Replace #NN with the actual issue number when opening the PR.

Completion Table

Acceptance Criterion	Status	Implementation Evidence	Test Evidence	Documentation Impact
AC 1: Audit evidence index is added	Complete	docs/audit-evidence-index.md created — status table for all 11 issue areas (§1), evidence register (§2–§3), invariant register (§4), gap register (§5), reproduction commands (§6), maintenance rule (§7)	Rendered Markdown verified; automated relative-link audit: 126/126 links resolve, 0 broken (script run over all new/modified docs)	New file docs/audit-evidence-index.md; linked from new "Security & Auditing" section in README.md
AC 2: Compliance enforcement docs are linked	Complete	Index §3.1 links docs/architecture.md (ACL separation), docs/contract-spec.md (revert conditions), src/compliance.rs:L8-L31, enforcement asserts in src/asset.rs:L14-L17,L45-L53, and the WhitelistAdd event def src/events.rs:L43-L51	Linked tests: test_whitelist_emits_compliance_event (src/test.rs:L99), test_mint_to_non_whitelisted_fails (src/test.rs:L273); full suite passes: cargo test 9/9	Index §3.1 (new)
AC 3: Storage and API docs are linked	Complete	Index §3.6 links docs/architecture.md#ledger-state-storage + DataKey enum (src/lib.rs:L13-L18) incl. the rent/TTL honesty note; Index §2 links docs/contract-spec.md (public API spec for all 5 entry points) with per-area links back from §3.2–§3.4	Storage behaviour exercised via replay/persistence suites: store.test.js (14 tests, now discovered after rename), integration.test.js (12); full suites green (115/115 total)	Index §2 + §3.6 (new)
AC 4: Threat model is linked	Complete	Created docs/threat-model.md (assets, actors, 9 objectives, threats T1–T14 w/ mitigations + residual risk); linked from index §2 and README.md Security & Auditing section; index §5 cross-links every ⚠ threat	Threat rows cite the exact tests that back each mitigation (e.g. T3→test_mint_to_non_whitelisted_fails, T8→test_every_state_change_is_observable + onchain-compat.test.js)	New file docs/threat-model.md; README.md updated
AC 5: Relevant tests are linked	Complete	Index §3.11 maps all 9 contract tests (with src/test.rs line anchors L51–L309) and all 8 monitoring suites (106 tests) to audit relevance; §4 invariant register maps each invariant to its verifying test	make test-all → 115/115 passing (9 contract + 106 monitoring); hygiene fixes ensure the linked suites actually run (store.test.js now discovered, 3 previously-broken suites repaired via index.js rename)	Index §3.11 + §4 (new)
AC 6: Known audit gaps are listed	Complete	Index §5: 14 gaps (G-1…G-14) w/ impact + next step — incl. no pause, no migration/upgrade path, no asset metadata/SEP-41, single-admin trust, all tests mock auth, no TTL bumping, string-only errors, no de-whitelist, no external audit; honesty policy stated at index head and per-area "Honest notes" throughout	N/A — this criterion is documentation; validated by review, and flagged goals (pause/migration/metadata) verified absent by code inspection of src/	Index §5 (new)

Handling incomplete criteria: all six criteria Complete. Remaining
incompleteness is in the product (pause, migration, metadata, etc.), which
AC 6 explicitly required to be documented — it is, in the gap register.

Detailed Traceability Mapping

Acceptance Criteria	Implementation	Storage & State Changes	Events Emitted	Test Coverage	Security/Safety Controls
AC 1: Index added	docs/audit-evidence-index.md	None — documentation-only; src/ untouched (verified via status/diff)	None	Link audit script (126 links OK); make test-all 115/115 regression	Single-source-of-truth index; honesty policy: ✅ requires linked evidence to exist & pass today
AC 2: Compliance docs linked	Index §3.1	None	None	cargo test 9/9 (compliance gate tests green)	Evidence rows only claim enforcement where asserts exist (compliance.rs, asset.rs anchors)
AC 3: Storage & API docs linked	Index §2, §3.6	None — but documents the existing layout (DataKey, instance vs persistent) and the TTL gap	None	Store/replay suites green after fixes	TTL/archival risk flagged (G-6/T9) instead of implied handled
AC 4: Threat model linked	docs/threat-model.md; index §2; README	None	None (documents existing 5-event surface)	Threat→test citations verified (126-link audit)	Residual risks (T1 admin trust, T7 init front-run, T9 TTL, T14 mocked auth) rated honestly ⚠, not marked resolved
AC 5: Tests linked	Index §3.11, §4	None	None	9 contract tests + 106 monitoring tests enumerated with anchors; all pass	Repair of hidden-test defects: undiscovered store.tests.js and case-broken analytics/Index.js fixed so evidence is reproducible
AC 6: Gaps listed	Index §5 (G-1…G-14)	None	None	N/A	Gap register double-checked against code (no pause/upgrade/metadata fns exist); monitoring hygiene fixes disclosed as completed G-13

Summary for the mapping section: 0 storage changes, 0 event changes,
0 contract-code changes. The only security-relevant behavioural effects are
in the off-chain test harness (two renames) which increase executed coverage
(55→106 discovered tests).

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Chore (refactoring, build tools, etc.) — tree hygiene renames + Makefile/README path corrections found while validating the docs

PR Evidence Checklist

1. Issue Reference

• The PR description links to the issue being addressed (see Related Issues; drop in the real number for #NN).

2. Implementation Summary

• A concise summary of what was implemented, changed, or fixed is provided above in the Description section.
• Key files modified are listed with brief descriptions of each change (Description table).
• New public functions, events, error codes, or roles are documented — N/A, none added (no contract code changed; the index instead catalogues the existing 5 public functions, 5 events, 8 error strings, 1 role).

3. Tests Added or Justification

• New or updated tests cover the change — No-Test Justification: the change adds Markdown documentation, two zero-content file renames, and Makefile/gitignore path text. There is no executable contract or JS logic to unit-test. Validation is by execution of the existing suites plus a scripted audit of every relative link in the new docs.
• Test names and locations are listed — exhaustively, in docs/audit-evidence-index.md §3.11 (contract tests at src/test.rs:L51,L79,L99,L126,L154,L184,L209,L273,L287,L309; monitoring suites under .github/monitoring/tests/).
• OR a No-Test Justification is provided and explicitly approved — provided above; requesting explicit reviewer approval.

4. Commands Run

• make verify passes locally — N/A: this repo defines no make verify target. Ran its closest equivalents instead; all pass (output in Additional Context):
  make build ✅ · make test ✅ · make monitor-test ✅ · make test-all ✅ · cargo fmt --all --check ✅ · cargo clippy --all-targets ✅

5. CI Status

• All GitHub Actions checks pass (green) on the PR branch — N/A to claim here: this repo has no build/test CI workflow; only automation dispatchers (auto-trigger.yml, trigger-auto-assign.yml) exist. Local validation stands in (below).
• If CI is failing, a clear explanation and link to the follow-up issue is provided — N/A, nothing failing; recommend a follow-up issue proposing a test CI workflow (also precursor to G-11).

6. Acceptance Criteria Coverage

• Every acceptance criterion from the issue is addressed in the Completion Table above (6/6, all Complete).
• Documentation impact is recorded for every criterion, including an explicit N/A with a reason when no documentation changes are needed.
• Incomplete criteria include a rationale and, where applicable, a link to a follow-up issue — none incomplete; product-level gaps the issue asked to list live in index §5 with suggested next steps.

Policy & Standards

• [~] I have read the Contributor Evaluation Policy and understand that merge does not guarantee payment — cannot check literally: docs/contributor-evaluation-policy.md does not exist in this repo (also absent: docs/pr-evidence-checklist.md, docs/testing-standards.md, docs/reviewer-checklist.md, docs/legal-boundary-disclaimer.md, docs/traceability-mapping.md, referenced by this template). The acknowledgement of the payment policy is accepted as written here.
• I have read the CONTRIBUTING.md guidelines (branch prefixes, mandatory tests for new logic, cargo fmt/cargo clippy gates).
• My code follows the Rust and Soroban formatting standards (ran cargo fmt --all --check → clean; no Rust code changed regardless).
• My changes generate no new warnings (ran cargo clippy --all-targets → 0 warnings, 0 errors).
• I have added/updated tests for the new logic, and all tests pass (ran cargo test → 9/9) — no new logic existed to test; see No-Test Justification; additionally node --test suites now execute 106/106 (up from 52/55) after repairing the case-mismatch and undiscovered-filename defects.
• Traceability Mapping: I have filled out the detailed mapping table above (explicitly recording 0 storage / 0 event / 0 code changes).
• [~] Reviewer Guidance: self-reviewed against the checklist's intent (evidence links, honesty about gaps, reproducible commands); the referenced docs/reviewer-checklist.md file is absent from this repo.
• Compliance & Legal Check: verified — the new docs deliberately describe only smart-contract enforcement. docs/threat-model.md §5 declares legal/regulatory KYC out of scope; gaps G-4/G-8 state the whitelist is not regulatory completeness (no removal/freeze, single admin). Nothing implies compliance guarantees beyond on-chain enforcement.

Additional Context

Validation output (run on this PR tree)

$ make build
   Finished `release` profile [optimized] target(s)
Build successful. WASM located at target/wasm32v1-none/release/aegis_contracts.wasm
   (15,470 bytes, 0 warnings)

$ make test                       # cargo test
test result: ok. 9 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out
   (dump_event_xdr remains #[ignore]d — fixture generator, run via `make dump-events`)

$ make monitor-test               # node --test tests/
# tests 106
# pass 106
# fail 0

$ make test-all                   # both suites end-to-end
test result: ok. 9 passed; ...      # contract
# pass 106                          # monitoring
   → 115/115 total

$ cargo fmt --all --check          → clean
$ cargo clippy --all-targets       → 0 warnings, 0 errors

$ link audit (all new/modified docs) → 126/126 relative links + anchors resolve, 0 broken

Before/after: monitoring test discoverability (why the renames matter)

Suite	Before this PR	After
node --test tests/ discovered runs	55 (52 pass / 3 fail)	106 (106 pass / 0 fail)
store persistence/replay tests	never executed (filename store.tests.js unmatched)	executed (14 tests)
integration, onchain-compat, triggers	failed: ERR_MODULE_NOT_FOUND ../src/analytics/index.js (file was Index.js)	pass

Honesty notes for reviewers

• All gaps in index §5 were re-verified by direct code inspection: no
  pause/upgrade/metadata entry points exist in src/; no
  extend_ttl/bump call exists; every contract test uses mock_all_auths().
• Environment used: Rust stable via rustup + wasm32v1-none, Node 20,
  soroban-sdk 26.0.0 (locked in Cargo.lock).
• test_snapshots/ (new .gitignore entry) is cargo-test output, not source.
• This file (PR_DESCRIPTION.md) is the PR body source — do not commit it to
  main; paste into the PR form and delete.

[El-swaggerito]

\nThis PR is currently blocked by merge conflicts.\n\nPlease update the branch with the latest main branch and resolve the conflicts before it can be merged.

[El-swaggerito]

\nGitHub has not finished calculating whether this PR can be merged cleanly.\n\nThe auto-merge automation will skip this PR for now. Re-run the automation later.