feat(validators): add comprehensive deadline, amount, address, and signature validation suites

[terngunan]

What this fixes

• Implement deadline validation #1064 (Implement deadline validation): Deadlines were previously accepted without strict validation against past timestamps, invalid formats, non-finite values, or millisecond/second discrepancies, leading to potential on-chain contract panics or immediately expired invoices.
• Add amount validation #1063 (Add amount validation): Token and payment amounts lacked a unified validator to verify reasonable bounds (Stellar INT64_MAX limit), enforce Stellar's 7-decimal precision constraints, reject scientific notation, and prevent negative/zero values.
• Implement address validation #1062 (Implement address validation): Public key and contract address inputs lacked comprehensive validation for RFC 4648 Base32 formatting, exact lengths, version prefixes (G, C, M), CRC16-XModem checksums, and explicit rejection of secret keys (S...).
• Add signature validation #1061 (Add signature validation): Cryptographic signature checks lacked a unified validation layer to verify Ed25519 signature authenticity and format, evaluate multi-signature threshold sets across weighted signers, and validate webhook HMAC signatures with timing-safe comparison and replay protection.

What changed

• Deadline Validator (src/validators/deadlineValidator.ts):
  • Implemented validateDeadline, validateDeadlineOrThrow, isFutureDeadline, and parseDeadline.
  • Added support for bigint, number, Date, and ISO-8601/numeric date strings.
  • Added millisecond timestamp detection and normalization to Unix seconds.
  • Added configurable future constraints: referenceTime, minLeadSeconds, and maxFutureSeconds.
  • Added DeadlineValidator class for reusable configurations.
• Amount Validator (src/validators/amountValidator.ts):
  • Implemented validateAmount, validateAmountOrThrow, isValidAmount, and parseToStroops.
  • Enforced Stellar protocol range bounds (1n to 9_223_372_036_854_775_807n / INT64_MAX) and boundary tests.
  • Enforced 7-decimal precision limit (STELLAR_MAX_DECIMALS = 7) and rejected scientific notation.
  • Added configurable range bounds (min, max, allowZero, allowNegative, maxDecimals, unit).
  • Added AmountValidator class for reusable configurations.
• Address Validator (src/validators/addressValidator.ts):
  • Implemented validateAddress, validateAddressOrThrow, isStellarAddress, detectAddressType, and verifyAddressChecksum.
  • Enforced exact lengths (56 for G/C, 69 for M) and RFC 4648 Base32 character set ([A-Z2-7]).
  • Implemented CRC16-XModem checksum verification via StrKey.
  • Added explicit security protection rejecting private keys (S...).
  • Added AddressValidator class with allowedTypes filtering.
• Signature Validator (src/validators/signatureValidator.ts):
  • Implemented validateEd25519Signature, validateEd25519SignatureOrThrow, validateMultiSig, validateMultiSigOrThrow, and validateWebhookSignature.
  • Implemented cryptographic Ed25519 signature verification against public keys (G... or 32-byte buffers).
  • Implemented multi-signature threshold evaluation, deduplicating signers and accumulating authorized weights.
  • Implemented timing-safe webhook HMAC verification with timestamp freshness checking.
  • Added SignatureValidator class and format normalization helpers.
• Errors & Exports (src/errors.ts, src/validators/index.ts, src/index.ts):
  • Added typed error classes: DeadlineValidationError, AmountValidationError, AddressValidationError, and SignatureValidationError (all extending ValidationError).
  • Added type guards: isDeadlineValidationError, isAmountValidationError, isAddressValidationError, and isSignatureValidationError.
  • Exported all validator functions, classes, constants, and types via @stellar-split/sdk and src/validators/index.ts.

Testing

• Added 4 dedicated unit test suites covering format, boundary conditions, edge cases, and error handling:
  • test/deadlineValidator.test.ts: 26 tests (all passed)
  • test/amountValidator.test.ts: 24 tests (all passed)
  • test/addressValidator.test.ts: 19 tests (all passed)
  • test/signatureValidator.test.ts: 25 tests (all passed)
  • test/sdkExports.test.ts: 4 tests (all passed)
• Executed npm test verifying 110 baseline tests pass with zero regressions.

Issues

closes #1064
closes #1063
closes #1062
closes #1061

[drips-wave]

@terngunan Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits