feat(stellar): publish SEP-1 stellar.toml metadata endpoint.

[Ahbiz]

Summary

Closes #58

Hosts a SEP-1 stellar.toml file at /.well-known/stellar.toml so DeenBridge platform organization metadata, declared accounts, and supported assets (USDC) are discoverable and verifiable across the Stellar ecosystem.

What Was Done

1. Config-Driven TOML Builder (src/services/stellar/stellarTomlService.js):

   • Dynamically builds the TOML document without hardcoded values.
   • Sources active network passphrase, USDC issuer, and platform wallet from stellarService.js.
   • Supports optional env vars (ORG_NAME, ORG_URL, ORG_DESCRIPTION, ORG_LOGO, ORG_TWITTER, ORG_GITHUB, STELLAR_PLATFORM_PUBLIC_KEY, SIGNING_KEY).
   • Degrades gracefully (omits missing fields) when optional env vars are unset.

2. Public Well-Known Endpoint (src/routes/wellKnownRoutes.js & app.js):

   • Exposes GET /.well-known/stellar.toml.
   • Serves Content-Type: text/toml; charset=utf-8 and Access-Control-Allow-Origin: * per SEP-1 requirement.
   • Mounted before /api rate limiter so ecosystem crawlers and wallets can fetch it unthrottled and unauthenticated.

3. Validation & Docs:

   • Added optional variables to src/config/validateEnv.js and .env.example.
   • Updated QUICK_START.md and README.md.

4. Automated Testing (test/stellarToml.test.js):

   • Added @iarna/toml (devDependency) to parse and validate TOML response structure.
   • 11 unit/integration test cases covering status code, content type, CORS headers, TOML validity, network passphrase matching, USDC issuer matching, optional env behavior, auth bypass, and rate limiter bypass.

How to Test

# 1. Run unit tests
npm test

# 2. Curl the endpoint locally
npm run dev
curl -i http://localhost:5000/.well-known/stellar.toml


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

* **New Features**
  * Added a Stellar SEP-1 metadata endpoint at `/.well-known/stellar.toml`.
  * Returns TOML with network, supported currency, and optional organization/platform metadata.
  * Supports optional `SIGNING_KEY` (left blank until SEP-10 is implemented); `STELLAR_PLATFORM_PUBLIC_KEY` controls `[ACCOUNTS]` output.
* **Documentation**
  * Updated `README.md` and `QUICK_START.md` with the new endpoint and configuration variables, including `.env.example`.
* **Bug Fixes**
  * Ensures `/.well-known` requests are not blocked by API authentication or rate limiting.
* **Tests**
  * Added automated coverage for response headers, TOML validity, conditional sections, and concurrent access.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[coderabbitai]

Walkthrough

Adds a configurable SEP-1 stellar.toml generator and public /.well-known/stellar.toml endpoint, with optional Stellar and organization metadata, network-aware currency information, documentation, and endpoint coverage.

Changes

SEP-1 metadata endpoint

Layer / File(s)	Summary
TOML generation and configuration src/services/stellar/stellarTomlService.js, src/config/validateEnv.js, .env.example	Generates network metadata, optional accounts, signing configuration, organization documentation, and USDC currency entries from environment settings.
Public endpoint wiring src/routes/wellKnownRoutes.js, app.js	Serves TOML with CORS, TOML content type, and five-minute caching, mounted before the API rate limiter.
Validation and documentation test/stellarToml.test.js, package.json, QUICK_START.md, README.md	Adds TOML parsing and endpoint tests covering metadata, optional configuration, authentication, concurrency, and rate-limit isolation, plus setup and route documentation. @iarna/toml is added for parsing.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ExpressApp
  participant wellKnownRoutes
  participant stellarTomlService
  Client->>ExpressApp: GET /.well-known/stellar.toml
  ExpressApp->>wellKnownRoutes: Route request
  wellKnownRoutes->>stellarTomlService: buildStellarToml()
  stellarTomlService-->>wellKnownRoutes: TOML document
  wellKnownRoutes-->>Client: 200 TOML response

Loading

Possibly related PRs

• Deen-Bridge/dnb-backend#72: Directly overlaps the SEP-1 route, TOML generation, environment wiring, and tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 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 (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: publishing the SEP-1 stellar.toml metadata endpoint.
Linked Issues check	✅ Passed	The PR adds the SEP-1 endpoint, TOML builder, optional env handling, CORS, and tests that match the requested metadata and access behavior.
Out of Scope Changes check	✅ Passed	The changes stay focused on SEP-1 hosting, docs, config, and tests; no unrelated code paths or features were introduced.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 6

🧹 Nitpick comments (1)

test/stellarToml.test.js (1)

24-38: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Make the network-specific expectations deterministic.

These assertions hard-code testnet values, so a mainnet-configured run fails even when the network-aware implementation is correct. Pin STELLAR_NETWORK=testnet before importing app.js, or parameterize expectations for both networks.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/stellarToml.test.js` around lines 24 - 38, Make the tests in the
NETWORK_PASSPHRASE and USDC CURRENCIES cases deterministic by setting
STELLAR_NETWORK to testnet before app.js is imported, or derive expectations
from the configured network. Preserve the existing testnet assertions when
running in testnet mode and ensure app.js reads the intended network
configuration.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@QUICK_START.md`:
- Line 73: Update the optional TOML environment-variable list in QUICK_START.md
to remove SIGNING_KEY or clearly mark it as a blank placeholder that must remain
unset until SEP-10 (`#25`). Ensure the documentation does not suggest storing or
publishing a private signing key through this endpoint.

In `@src/services/stellar/stellarTomlService.js`:
- Around line 63-64: Update the TOML generation loop in stellarTomlService
around setDocFields so every interpolated value is serialized or escaped as a
TOML string before being appended to lines. Handle quotes, backslashes, and
newlines for all environment-derived ORG_* values while preserving the generated
key/value structure and ensuring valid machine-readable TOML.
- Around line 39-43: Update the SIGNING_KEY handling in the stellar.toml
generation flow to never emit process.env.SIGNING_KEY verbatim. Validate that
the value is a public Stellar account key beginning with G and emit it only when
valid; otherwise keep the existing commented placeholder, ensuring secret seeds
or other invalid values are not published.
- Around line 4-5: Update the stellar.toml generation logic in
stellarTomlService to use only STELLAR_PLATFORM_PUBLIC_KEY for the published
account, removing the PLATFORM_WALLET_PUBLIC_KEY fallback; when
STELLAR_PLATFORM_PUBLIC_KEY is blank or unset, omit ACCOUNTS entirely.

In `@test/stellarToml.test.js`:
- Around line 40-47: Update the environment-mutating tests around the ORG_* and
STELLAR_PLATFORM_PUBLIC_KEY overrides to save each variable’s exact prior value
and restore it in a finally block, ensuring cleanup runs after failed
assertions. Restore empty-string values as empty strings, and delete a variable
only when its saved value was originally undefined.
- Around line 83-90: Update the test case “omits ACCOUNTS gracefully when no
platform key is available” to parse res.text as a Stellar TOML document and
assert doc.ACCOUNTS is undefined, not just that the response is successful. Also
disable or override the service’s PLATFORM_WALLET_PUBLIC_KEY fallback during the
test so the omission is genuinely exercised, while preserving environment
restoration afterward.

---

Nitpick comments:
In `@test/stellarToml.test.js`:
- Around line 24-38: Make the tests in the NETWORK_PASSPHRASE and USDC
CURRENCIES cases deterministic by setting STELLAR_NETWORK to testnet before
app.js is imported, or derive expectations from the configured network. Preserve
the existing testnet assertions when running in testnet mode and ensure app.js
reads the intended network configuration.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ac51c7d1-8b45-401e-a80e-04e6d48cf9cf

📥 Commits

Reviewing files that changed from the base of the PR and between 2138e57 and af64f16.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (9)

• .env.example
• QUICK_START.md
• README.md
• app.js
• package.json
• src/config/validateEnv.js
• src/routes/wellKnownRoutes.js
• src/services/stellar/stellarTomlService.js
• test/stellarToml.test.js

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

test/stellarToml.test.js (1)

147-154: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Exercise the limiter threshold in this test
Ten requests never hit the current apiLimiter cap (100), so this doesn’t prove the /.well-known route stays exempt under load. Send at least 101 requests, or swap in a deliberately low test limiter, so a future global limiter regression fails here.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/stellarToml.test.js` around lines 147 - 154, Update the “is not affected
by /api rate limiter” test to issue at least 101 concurrent requests, exceeding
the current apiLimiter threshold while continuing to request
/.well-known/stellar.toml and assert every response remains successful.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@test/stellarToml.test.js`:
- Around line 147-154: Update the “is not affected by /api rate limiter” test to
issue at least 101 concurrent requests, exceeding the current apiLimiter
threshold while continuing to request /.well-known/stellar.toml and assert every
response remains successful.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0ef91c15-5bb6-45aa-bba3-e2bd86598b68

📥 Commits

Reviewing files that changed from the base of the PR and between af64f16 and c0811db.

📒 Files selected for processing (3)

• QUICK_START.md
• src/services/stellar/stellarTomlService.js
• test/stellarToml.test.js

🚧 Files skipped from review as they are similar to previous changes (2)

• QUICK_START.md
• src/services/stellar/stellarTomlService.js