V2-BE-108 — Protect Evidence Fetching Against SSRF

[dDevAhmed]

Overview

Protect Evidence Fetching Against SSRF as an independently reviewable V2 backend work item. This task strengthens authentication, authorization, and abuse resistance without granting the backend protocol authority.

Problem Context

TruthBounty treats deployed Optimism/EVM contracts and canonical chain events as protocol authority. The API is a deterministic indexing, projection, authentication, and delivery layer; it must never invent, mutate, or override protocol truth. This boundary must remain explicit under failures, retries, reorgs, migrations, and degraded dependencies.

Technical Scope

• Define the production design, interfaces, invariants, and failure modes for this task.
• Implement the smallest cohesive backend change needed to satisfy the design.
• Keep chain-derived state reproducible from canonical events and versioned deployment artifacts.
• Add observable, actionable failure reporting with no silent fallback to fabricated state.
• Update operator and developer documentation where behavior or recovery procedures change.

Security and Architecture Requirements

• Optimism/EVM only; do not add Stellar, Soroban, Freighter, or alternate-chain runtime paths.
• Smart contracts and finalized canonical events remain authoritative for protocol state.
• Do not introduce backend-authoritative settlement, rewards, treasury, governance, claim, or dispute mutation.
• Preserve the TypeORM-only persistence boundary; do not add Prisma or a second ORM.
• Fail closed on identity, chain, finality, signature, authorization, configuration, and integrity uncertainty.
• Never commit secrets, live credentials, placeholder production values, or production mocks.

Required Tests

• Unit tests for success, invalid input, boundary conditions, and each documented failure mode.
• Integration tests using PostgreSQL/Redis/RPC dependencies appropriate to the change.
• Reorg, retry, duplicate-delivery, stale-data, and degraded-dependency coverage where applicable.
• Regression tests proving canonical protocol compatibility and no unauthorized mutation path.
• CI evidence for lint, typecheck/build, tests, security scanning, migration checks, and artifact drift.

Acceptance Criteria

• The implementation matches the canonical V2 protocol and repository architecture.
• Behavior is deterministic, observable, and fail-closed where correctness or security is uncertain.
• Required tests execute in CI and pass without skips that conceal required coverage.
• Migrations, schemas, generated artifacts, and documentation are synchronized.
• No unrelated issue is closed and no unrelated refactor is bundled.
• An independent human maintainer approves the exact head SHA when the change is security-sensitive.

Dependencies

V2-BE-107; any referenced contract ABI/address artifact must already be canonical.

Non-Goals

• Changing smart-contract protocol rules.
• Adding alternative-chain runtime support.
• Replacing TypeORM or creating a second persistence architecture.
• Activating this task for contributor assignment before maintainers apply Stellar Wave.

Complexity and Review

• Complexity: low
• Points: 100
• Review: backend maintainer; security/architecture maintainer approval required for sensitive paths.

---

🏷 Labels

• backend
• complexity-low
• wave-candidate

[IgweHub1]

@IgweHub1 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @IgweHub1 to this issue.

[drips-wave]

Congratulations, @IgweHub1! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @IgweHub1: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @IgweHub1 as part of the Stellar Wave Program's 9th Wave 🥳

😎 @IgweHub1: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.