feat(audit-guard): add RelayerTxScanner for unauthorized TX detection (closes #25)

[gbengaeben]

Summary

Resolves #25 by adding a RelayerTxScanner alongside the existing LogicErrorDetector (issue #16). The new scanner authorizes transactions before the relayer submits them to the Stellar network, with:

• 11-pattern library covering signer auth, denylist precedence, multi-sig, replay, malformed inputs, opt-in trusted-source + per-op fee checks.
• Tri-state AuthorizationStatus (AUTHORIZED / REQUIRES_REVIEW / UNAUTHORIZED) with severity-driven rollup.
• Additive CLI command scan-tx keyed on TX_DATA_FILE + VERO_RELAYER_* env vars. Exit codes mirror detect-logic (0 = AUTHORIZED/REQUIRES_REVIEW, 1 = UNAUTHORIZED) so wire-up parity is trivial.
• Coarse Rego mirror (policies/relayer_authz.rego) for orgs that centralise policy in OPA.

What ships

• src/audit-guard/src/relayer-scanner.ts — types + RelayerTxScanner orchestrator + generateReport(). Pure (no I/O, no global state), mirrors the LogicErrorDetector shape exactly.
• src/audit-guard/src/relayer-patterns.ts — frozen Object.freeze library of 11 pure check patterns, each with id/title/description/severity/optional references. RELAYER_PATTERNS and RELAYER_PATTERN_IDS exported.
• src/audit-guard/policies/relayer_authz.rego — OPA mirror under package relayer.authz. INVALID_HASH_FORMAT is intentionally delegated to the TS engine (see inline comment) because OPA regex support varies by version.
• src/audit-guard/src/cli.ts — additive scan-tx command, grouped with the other async handlers above printHelp; every existing command preserved.
• src/audit-guard/src/index.ts — additive exports; all existing LogicErrorDetector exports intact; RelayerContext re-exported from the correct module.
• src/audit-guard/README.md — new ## Relayer Tx Scan (Issue #25) section as a peer of ## Logic Error Detection (Issue #16).

Pattern library

Pattern ID	Default Severity	Trigger
DENYLISTED_SIGNER	CRITICAL	Signer on the denylist (denylist trumps allowlist overlap).
UNKNOWN_SIGNER	HIGH	Signer not on the allowlist.
MISSING_SIGNATURES	CRITICAL	Envelope has zero signatures — refuse to relay.
INSUFFICIENT_SIGNATURES	HIGH / CRITICAL	Unique signer count below multiSigThreshold (CRITICAL when zero).
DUPLICATE_SIGNATURE	LOW	Same signer appears more than once (fee waste, observability).
MALFORMED_SIGNATURE_ENTRY	HIGH	A signature object is missing signerKey or signatureValue.
INVALID_HASH_FORMAT	MEDIUM	Hash does not match 64-char lower-case hex shape.
REPLAY_DETECTED	CRITICAL	Hash appears in caller-supplied knownHashes set.
UNTRUSTED_SOURCE_ACCOUNT	HIGH	sourceAccount not in trustedSourceAccounts (opt-in).
UNSUPPORTED_OPERATION	HIGH	An op type is not in allowedOperationTypes (opt-in).
FEE_OVER_LIMIT	MEDIUM	fee / opCount exceeds maxFeePerOp (opt-in).

Note on pre-existing TS errors

tsc --build for the full audit-guard package is RED on issues outside this PR scope and unrelated to the RelayerTxScanner:

• missing --jsx flag + react package (src/ui/BountyForm.tsx, src/ui/BreakerButton.tsx)
• missing node-fetch types (src/webhook.ts)
• unused start variable (src/policy-engine.ts)

These are pre-existing on main and not regressions introduced by this PR. The new code paths typecheck cleanly when tsc --noEmit is scoped to the changed files; 77/77 jest tests pass in the relayer-scanner + logic-detector suites. A separate follow-up issue should address them.

Test plan

cd src/audit-guard
npm test -- --testPathPattern=relayer-scanner
# or: npx jest --testPathPattern=relayer-scanner

Mirrors and intent

PR #69 from gbengaeben addresses the same issue but REPLACES the existing LogicErrorDetector exports and the detect-logic CLI command, which would regress our current ## Logic Error Detection (Issue #16) surface. This PR is strictly additive:

• Removes zero existing functionality.
• Exits semantics mirror detect-logic.
• Can merge independently of PR feat(audit-guard): add RelayerTxScanner for unauthorized TX detection (closes #25) #69 without conflict in either direction.

Reviewers familiar with the existing LogicErrorDetector will recognize the orchestrator shape (RelayerTxScanner <- LogicErrorDetector), the frozen pattern library (RELAYER_PATTERNS <- LOGIC_PATTERNS), the severity-sorted findings, and the markdown report.

---

Followups needed before this can merge

The OPA Policy Compliance and Anomaly Detector Tests CI jobs fail because of pre-existing TS/dependency issues in src/audit-guard that are not caused by this PR. A separate upstream PR (see search for fix/audit-guard-build-ci) addresses them; once that merges, the CI matrix for this PR will go green.

Until then, treat the OPA Policy Compliance and Anomaly Detector Tests (TypeScript) failures as expected noise — they are not regressions from this PR.

[N-thnI]

please resolve conflicts