feat: dashboard config validation guardrails (#8)

[Justine-Ifedozie]

Description

Implements the admin compliance management dashboard for issue #4: a section on the existing /admin page (admin-role-only route) where an admin can search, add, remove, and audit KYC-whitelisted investor addresses, with a review-before-signing step and Freighter integration.

Related Issue: Closes #4

Type of Change:

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (changes to documentation only)
• Refactor (code restructuring with no functional changes)
• CI/CD (changes to build process or automation)

---

Evidence Checklist

1. Issue Reference

• This PR references a tracked issue (e.g., Closes #123)
• Issue Link: Implement admin compliance management dashboard #4

2. Implementation Summary

• A clear summary of what was changed and why is provided above
• Files Changed:
  • src/lib/whitelist.ts — new: address validation, search, and no-op-action guard logic
  • src/lib/__fixtures__/whitelist.ts — new: sample whitelist data for mock mode
  • src/lib/sdk/IAegisProvider.ts — added listWhitelist, addToWhitelist, removeFromWhitelist to the provider contract
  • src/lib/sdk/MockAegisProvider.ts — implements the three methods against in-memory fixture state
  • src/lib/aegis/client.ts / src/lib/sdk/LiveAegisProvider.ts — stub implementations for the live path, marked TODO(@aegis/sdk)
  • src/hooks/useAegis.ts — wraps the three calls with loading state and records each add/remove to transaction history as a compliance_update
  • src/features/compliance/components/WhitelistManager.tsx — new: the dashboard (search, add form, table, loading/empty/error states)
  • src/features/compliance/components/WhitelistActionModal.tsx — new: review → sign → receipt flow, reusing the existing TransactionReview/TransactionProgress/TransactionReceipt components
  • src/pages/admin.tsx — wires WhitelistManager into the existing admin-only route
  • docs/admin-whitelist-management.md — new: workflow documentation
  • src/lib/whitelist.test.ts — new: 17 tests for the pure logic module
  • src/__tests__/sdk/provider.test.ts — 9 new tests for the mock provider's whitelist methods

3. Testing

• Tests have been added or updated to cover the changes
• All existing tests pass locally

Test Commands Run:

npm run lint
npm run typecheck
npm test
npm run build

Test Output (summary):

• npm run lint — no errors (2 pre-existing warnings in unrelated files, not introduced by this PR)
• npm run typecheck — clean, no errors
• npm test — 449/449 tests passing across 32 test files, including the 26 new tests added in this PR
• npm run build — production build succeeds; /admin route compiles at 5.73 kB

Note: this full suite was verified in a clean environment against Node 20.19+. Running locally on Node 20.11.x will hit an unrelated vitest/rolldown startup error (styleText not exported from node:util) — this is a local tooling/Node-version issue, not something introduced by this change. Recommend confirming green on CI's Node version.

4. Commands Run

• The following commands were executed locally to validate the change:

npm install
npm run dev
npm run lint
npm run typecheck
npm test
npm run build

5. CI Status

• All CI checks pass on this PR
• No new warnings or errors were introduced
• CI Pipeline Link:

6. Acceptance Criteria Coverage

• All acceptance criteria from the linked issue have been satisfied

Acceptance Criterion	Evidence
Compliance management page is implemented	WhitelistManager added to the existing /admin page (admin-role-restricted via RouteGuard)
Whitelist status can be searched and displayed	searchWhitelistEntries + TableSearch filter the table by address or note; status shown as a badge (Whitelisted / Revoked)
Admin update flow includes review before signing	WhitelistActionModal shows full details via TransactionReview before any signature is requested
Freighter signing integration is handled safely	Signing flows entirely through the existing useAegis → getAegisProvider() path already used by mint/transfer — no new wallet-interaction code was added
Loading, empty, success, and error states are included	Loading spinner text, EmptyState (no-data vs unavailable variants) for empty/error, TransactionReceipt for success/failure/pending/unknown
Documentation explains admin compliance workflow	docs/admin-whitelist-management.md

7. Self-Assessment

• The Contributor Self-Assessment Form has been completed and attached to this PR
• Form Location:

---

Screenshots / Recordings

Before	After
(no whitelist management UI existed)	(add screenshot here)

---

Reviewer Notes

The whitelist admin section was added to the existing /admin page rather than a new route, since /admin is already restricted to the admin role and the prior AdminPanel had a stubbed "Whitelist User" button (// TODO: replace with a real contract.whitelist(address) call) that this PR effectively completes. Happy to move it to its own route if maintainers prefer that separation.

LiveAegisProvider's whitelist methods currently delegate to mock-latency stubs in client.ts, consistent with every other SDK method in this repo pending the real @aegis/sdk package.