feat: Validate auth entry signature expiration ledger

[zeljkoX]

This PR adds validation for the auth entry signature expiration ledger value.

Requests with auth entries whose expiration is too close to the current ledger will be rejected. The minimum signature ledger buffer is 2, ensuring there is enough time to process the transaction.

Summary by CodeRabbit

• New Features

  • Added configurable sequence number caching settings.
  • Added signature expiration validation with configurable ledger buffer margin.

• Documentation

  • Expanded error codes reference with new categories for request validation, pool operations, simulation, authentication, and management scenarios.
  • Updated configuration documentation for sequence number cache and signature expiration handling.

[coderabbitai]

Walkthrough

This PR adds signature expiration validation for Soroban authorization entries by introducing a configurable minimum ledger buffer parameter. Configuration is extended to load and pass minSignatureExpirationLedgerBuffer through the pipeline, and validation logic rejects auth entries with expirations too close to the current ledger. Comprehensive tests and documentation updates accompany the feature.

Changes

Cohort / File(s)	Summary
Documentation README.md	Adds sequence number cache configuration documentation and expands error codes taxonomy with new categories (validation, pool, simulation, assembly, submission, management, KV schema) including expiry-related errors like AUTH_EXPIRY_TOO_SHORT.
Configuration src/plugin/config.ts, src/plugin/constants.ts	Introduces minSignatureExpirationLedgerBuffer field to ChannelAccountsConfig, adds parser parseMinAuthExpiryLedgerBuffer() with validation, and defines DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER constant (value: 2) in both CONFIG and SIMULATION objects.
Core Logic src/plugin/handler.ts, src/plugin/simulation.ts	Refactors PipelineContext to use config object instead of sequenceNumberCacheMaxAgeMs field; updates handler to pass config through ctx; extends buildWithChannel signature with minSignatureExpirationLedgerBuffer parameter and adds validateAuthExpiry helper to reject overly-tight signature expirations (note: validateAuthExpiry defined twice in simulation.ts).
Tests test/config.test.ts, test/read-only.test.ts	Adds test coverage for MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER environment variable parsing with validation; introduces auth expiry margin tests for both simulateTransaction and buildWithChannel flows verifying rejection of tight expirations and acceptance when margin requirements are met.

Sequence Diagram(s)

sequenceDiagram
    participant Handler as Handler (func-auth)
    participant Config as Config<br/>(loadConfig)
    participant Simulation as buildWithChannel
    participant Validator as validateAuthExpiry
    participant Ledger as Soroban Network

    Handler->>Config: loadConfig()
    Config-->>Handler: ChannelAccountsConfig<br/>(with minSignatureExpirationLedgerBuffer)
    
    Handler->>Simulation: buildWithChannel(<br/>..., minBuffer)
    
    Simulation->>Ledger: Get latestLedger<br/>(from simResult)
    Ledger-->>Simulation: latestLedger number
    
    Simulation->>Validator: validateAuthExpiry(<br/>authEntries,<br/>latestLedger,<br/>minBuffer)
    
    alt Expiry Too Close
        Validator-->>Simulation: Throw AUTH_EXPIRY_TOO_SHORT<br/>(with margin details)
    else Expiry Valid
        Validator-->>Simulation: OK, continue
    end
    
    Simulation-->>Handler: Transaction or Error

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: Enforce soroban auth simulation & Improve inner failure details #78: Modifies src/plugin/simulation.ts and auth-related error handling (SIGNED_AUTH_VALIDATION_FAILED) for Soroban authorization validation during simulation.
• feat: Introduce sequence number cache #77: Implements the KV-backed sequence number cache logic (getSequence/commitSequence) that this PR wires into the plugin config via sequenceNumberCacheMaxAgeMs movement to ChannelAccountsConfig.
• feat: Support unsigned XDR by extracting func+auth automatically #57: Modifies handler.ts func-auth submission path and buildWithChannel flow; this PR's addition of minSignatureExpirationLedgerBuffer parameter directly affects that routing path.

Suggested reviewers

• tirumerla
• NicoMolinaOZ

Poem

🐰 A hop through configs so precise,
Auth entries checked not once, but twice!
Ledger buffers keep us safe and sound,
No expiries sneaking past around!
Thanks to validation, tight and clean—
The freshest auth we've ever seen! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: adding validation for auth entry signature expiration ledger values.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch signature-expiration-ledger

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

test/config.test.ts (1)

146-165: Add a test for value 1 to enforce the minimum buffer.

If the minimum buffer is truly “>= 2,” adding a case for MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER=1 will prevent regressions once the parser is tightened.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@test/config.test.ts` around lines 146 - 165, Add a test case in
test/config.test.ts to cover MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER='1' so the
minimum buffer requirement is enforced: when
process.env.MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER = '1' assert that
loadConfig().minSignatureExpirationLedgerBuffer === 2 (same fallback as other
invalid/too-small values), locating this near the existing "min auth expiry
ledger buffer" test that references loadConfig and
minSignatureExpirationLedgerBuffer.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/plugin/config.ts`:
- Around line 111-116: The parseMinAuthExpiryLedgerBuffer function currently
accepts any positive number allowing 1, but must enforce a minimum of
CONFIG.DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER (>=2); update
parseMinAuthExpiryLedgerBuffer to parse the env var into n, clamp it so the
returned value is Math.floor(n) only when Number.isFinite(n) and Math.floor(n)
>= CONFIG.DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER, otherwise return
CONFIG.DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER; reference the function
name parseMinAuthExpiryLedgerBuffer and the constant
CONFIG.DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER when making the change.

---

Nitpick comments:
In `@test/config.test.ts`:
- Around line 146-165: Add a test case in test/config.test.ts to cover
MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER='1' so the minimum buffer requirement is
enforced: when process.env.MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER = '1' assert
that loadConfig().minSignatureExpirationLedgerBuffer === 2 (same fallback as
other invalid/too-small values), locating this near the existing "min auth
expiry ledger buffer" test that references loadConfig and
minSignatureExpirationLedgerBuffer.

[Copilot]

Pull request overview

Adds a “fail fast” validation layer to reject Soroban auth entries whose signatureExpirationLedger is too close to the simulation’s latestLedger, with configuration and documentation support.

Changes:

• Add auth expiry margin validation in buildWithChannel, throwing AUTH_EXPIRY_TOO_SHORT when the margin is below a configurable buffer (default 2).
• Expose MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER via config/env and plumb it through the request handler.
• Add tests + README updates to document the new config and error code.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/plugin/simulation.ts	Validates auth expiry margin before assembling transactions; introduces AUTH_EXPIRY_TOO_SHORT.
src/plugin/handler.ts	Threads config through pipeline and passes minSignatureExpirationLedgerBuffer into buildWithChannel.
src/plugin/config.ts	Adds parsing + config field for MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER.
src/plugin/constants.ts	Introduces defaults/constants for the new buffer.
test/read-only.test.ts	Adds coverage for rejection/acceptance based on expiry margin + buffer.
test/config.test.ts	Adds coverage for parsing MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER.
README.md	Documents env var and error code categorization additions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tirumerla]

lgtm