feat: add SEP-1 stellar.toml discovery

.env.example

@@ -1,20 +1,56 @@
-CLOUDINARY_API_KEY=your_cloudinary_api_key
-CLOUDINARY_API_SECRET=your_cloudinary_api_secret
-CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
-CLOUDINARY_URL=your_cloudinary_url
-JWT_SECRET=your_jwt_secret
-MONGO_URI="your_mongodb_uri"
-PORT=5000
+# DeenBridge Backend Environment Variables
+
+# MongoDB connection string
+MONGO_URI=mongodb+srv://user:password@cluster.mongodb.net/dnb-backend?retryWrites=true&w=majority
+
+# JWT secret for authentication (use a strong random string, min 32 characters)
+JWT_SECRET=your_jwt_secret_here
+
+# Node environment (development, production, test)
 NODE_ENV=development
+
+# Server port
+PORT=5000
+
+# Cloudinary configuration for file uploads
+CLOUDINARY_CLOUD_NAME=your_cloud_name
+CLOUDINARY_API_KEY=your_api_key
+CLOUDINARY_API_SECRET=your_api_secret
+CLOUDINARY_URL=cloudinary://api_key:api_secret@cloud_name
+
+# EmailJS configuration for sending emails
 EMAILJS_API_URL=https://api.emailjs.com/api/v1.0/email/send
-EMAILJS_PRIVATE_KEY=your_emailjs_private_key
-EMAILJS_PUBLIC_KEY=your_emailjs_public_key
-EMAILJS_SERVICE_ID=your_emailjs_service_id
-EMAILJS_TEMPLATE_ID=your_emailjs_template_id
+EMAILJS_PRIVATE_KEY=your_private_key
+EMAILJS_PUBLIC_KEY=your_public_key
+EMAILJS_SERVICE_ID=your_service_id
+EMAILJS_TEMPLATE_ID=your_template_id
 EMAILJS_RECEIPT_TEMPLATE_ID=your_emailjs_receipt_template_id
+
+# Stellar blockchain network (testnet or mainnet)
 STELLAR_NETWORK=testnet
+
+# Resilient Horizon Client Configuration (Optional)
+# HORIZON_URLS=https://horizon-testnet.stellar.org,https://horizon-testnet.stellar.org (Comma-separated list of Horizon endpoints)
+# HORIZON_TIMEOUT_MS=10000 (Request timeout in milliseconds)
+# HORIZON_MAX_RETRIES=3 (Maximum number of retries for transient errors)
+# HORIZON_CB_THRESHOLD=5 (Number of consecutive failures before opening the circuit breaker)
+# HORIZON_CB_COOLDOWN_MS=30000 (Time to wait in ms before attempting a half-open probe)
+
+# SEP-1 discovery metadata (optional)
+STELLAR_PLATFORM_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ORG_NAME=DeenBridge
+ORG_URL=https://deenbridge.com
+ORG_DESCRIPTION="A platform for Islamic education and Stellar-based creator payments."
+ORG_LOGO=https://deenbridge.com/logo.png
+ORG_GITHUB=Deen-Bridge
+ORG_TELEGRAM_URL=https://t.me/+nst9lXNj1wc4ZDE0
+# Set these when SEP-10 and SEP-24 are enabled
+SIGNING_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+WEB_AUTH_ENDPOINT=https://api.deenbridge.com/auth
+TRANSFER_SERVER_SEP0024=https://api.deenbridge.com/sep24
 # Stellar donation fund (public key only - the secret key must NEVER be stored here)
 DONATION_WALLET_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
 # Platform fee split on purchases (0-20, 0 disables the split)
 PLATFORM_FEE_PERCENT=0
 PLATFORM_WALLET_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
@@ -28,3 +64,20 @@ JOBS_ENABLED=true
 QUEUE_DRIVER=mongo
 JOBS_DASHBOARD_TOKEN=replace_with_a_long_random_token
 
+# Redis Configuration (optional - app works without Redis but with reduced performance)
+# Option 1: Use REDIS_URL for full connection string (recommended for cloud services)
+# REDIS_URL=redis://username:password@host:port
+
+# Option 2: Use separate credentials
+REDIS_HOST=localhost
+REDIS_PORT=6379
+# REDIS_USERNAME=default
+# REDIS_PASSWORD=your_password
+
+# Jitsi configuration for video calls (optional)
+# JITSI_MEET_DOMAIN=your_jitsi_domain
+# JITSI_APP_ID=your_app_id
+# JITSI_PRIVATE_KEY=your_private_key
+# JITSI_PUBLIC_KEY_ID=your_public_key_id
+# JITSI_KID=your_kid
+# JITSI_TENANT=your_tenant

QUICK_START.md

@@ -19,6 +19,21 @@ NODE_ENV=development
 PORT=5000
 ```
 
+Optional Stellar discovery settings:
+
+```env
+STELLAR_NETWORK=testnet
+STELLAR_PLATFORM_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ORG_URL=https://deenbridge.com
+ORG_LOGO=https://deenbridge.com/logo.png
+SIGNING_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+WEB_AUTH_ENDPOINT=https://api.deenbridge.com/auth
+TRANSFER_SERVER_SEP0024=https://api.deenbridge.com/sep24
+```
+
+Unset optional values are left out of `GET /.well-known/stellar.toml`. The
+endpoint remains available and returns the configured network and USDC metadata.
+
 ### **3. Start Server**
 
 ```bash

app.js

@@ -45,6 +45,7 @@ import stellarPaymentRoutes from "./src/routes/stellar/paymentRoutes.js";
 import stellarDonationRoutes from "./src/routes/stellar/donationRoutes.js";
 import payoutRoutes from "./src/routes/payoutRoutes.js";
 import jobsRoutes from "./src/routes/jobsRoutes.js";
+import { getStellarToml } from "./src/routes/wellKnownRoutes.js";
 
 handleUncaughtException();
 validateEnv();
@@ -105,6 +106,9 @@ app.get("/metrics", metricsMiddleware);
 app.use(helmetMiddleware);
 app.use(customSecurityHeaders);
 
+// SEP-1 discovery must allow requests from wallets on any origin.
+app.get("/.well-known/stellar.toml", getStellarToml);
+
 const corsOptions = {
   origin: function (origin, callback) {
     const allowedOrigins = [

package.json

@@ -49,6 +49,7 @@
     "xss-clean": "^0.1.4"
   },
   "devDependencies": {
+    "@iarna/toml": "^2.2.5",
     "concurrently": "^9.1.2",
     "jest": "^29.7.0",
     "mongodb-memory-server": "^11.2.0",

src/config/validateEnv.js

@@ -17,6 +17,16 @@ const optionalEnvVars = [
   "JITSI_KID",
   "JITSI_TENANT",
   "STELLAR_NETWORK",
+  "STELLAR_PLATFORM_PUBLIC_KEY",
+  "ORG_NAME",
+  "ORG_URL",
+  "ORG_DESCRIPTION",
+  "ORG_LOGO",
+  "ORG_GITHUB",
+  "ORG_TELEGRAM_URL",
+  "SIGNING_KEY",
+  "WEB_AUTH_ENDPOINT",
+  "TRANSFER_SERVER_SEP0024",
   "DONATION_WALLET_PUBLIC_KEY",
   "PLATFORM_FEE_PERCENT",
   "PLATFORM_WALLET_PUBLIC_KEY",
@@ -28,13 +38,37 @@ const optionalEnvVars = [
   "JOBS_ENABLED",
   "JOBS_DASHBOARD_TOKEN",
   "EMAILJS_RECEIPT_TEMPLATE_ID",
+  // Redis configuration (optional - app works without Redis)
+  "REDIS_URL",
+  "REDIS_HOST",
+  "REDIS_PORT",
+  "REDIS_USERNAME",
+  "REDIS_PASSWORD",
+  "HORIZON_URLS",
+  "HORIZON_TIMEOUT_MS",
+  "HORIZON_MAX_RETRIES",
+  "HORIZON_CB_THRESHOLD",
+  "HORIZON_CB_COOLDOWN_MS",
 ];
 
 export const validateEnv = () => {
   // Default values for TTLs if not provided
   process.env.ACCESS_TOKEN_TTL = process.env.ACCESS_TOKEN_TTL || "15m";
   process.env.REFRESH_TOKEN_TTL = process.env.REFRESH_TOKEN_TTL || "30d";
 
+  // Default values for Horizon resilient client if not provided
+  const network = process.env.STELLAR_NETWORK || "testnet";
+  if (!process.env.HORIZON_URLS) {
+    process.env.HORIZON_URLS =
+      network === "mainnet"
+        ? "https://horizon.stellar.org"
+        : "https://horizon-testnet.stellar.org";
+  }
+  process.env.HORIZON_TIMEOUT_MS = process.env.HORIZON_TIMEOUT_MS || "10000";
+  process.env.HORIZON_MAX_RETRIES = process.env.HORIZON_MAX_RETRIES || "3";
+  process.env.HORIZON_CB_THRESHOLD = process.env.HORIZON_CB_THRESHOLD || "5";
+  process.env.HORIZON_CB_COOLDOWN_MS = process.env.HORIZON_CB_COOLDOWN_MS || "30000";
+
   const missing = [];
 
   requiredEnvVars.forEach((envVar) => {

src/config/validateEnv.test.js

@@ -0,0 +1,57 @@
+import { jest } from "@jest/globals";
+import { validateEnv } from "./validateEnv.js";
+
+describe("validateEnv", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = {
+      ...originalEnv,
+      MONGO_URI: "mongodb://localhost:27017/test",
+      JWT_SECRET: "test-secret-key-for-ci-minimum-32-chars",
+      NODE_ENV: "test",
+      PORT: "5000",
+    };
+    // Ensure new vars are unset
+    delete process.env.HORIZON_URLS;
+    delete process.env.HORIZON_TIMEOUT_MS;
+    delete process.env.HORIZON_MAX_RETRIES;
+    delete process.env.HORIZON_CB_THRESHOLD;
+    delete process.env.HORIZON_CB_COOLDOWN_MS;
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it("should derive testnet default endpoint when STELLAR_NETWORK is unset or testnet", () => {
+    delete process.env.STELLAR_NETWORK;
+    validateEnv();
+    expect(process.env.HORIZON_URLS).toBe("https://horizon-testnet.stellar.org");
+    expect(process.env.HORIZON_TIMEOUT_MS).toBe("10000");
+    expect(process.env.HORIZON_MAX_RETRIES).toBe("3");
+    expect(process.env.HORIZON_CB_THRESHOLD).toBe("5");
+    expect(process.env.HORIZON_CB_COOLDOWN_MS).toBe("30000");
+  });
+
+  it("should derive mainnet default endpoint when STELLAR_NETWORK is mainnet", () => {
+    process.env.STELLAR_NETWORK = "mainnet";
+    validateEnv();
+    expect(process.env.HORIZON_URLS).toBe("https://horizon.stellar.org");
+  });
+
+  it("should preserve explicitly set Horizon values", () => {
+    process.env.HORIZON_URLS = "https://custom.stellar.org";
+    process.env.HORIZON_TIMEOUT_MS = "5000";
+    process.env.HORIZON_MAX_RETRIES = "1";
+    process.env.HORIZON_CB_THRESHOLD = "10";
+    process.env.HORIZON_CB_COOLDOWN_MS = "10000";
+    validateEnv();
+    expect(process.env.HORIZON_URLS).toBe("https://custom.stellar.org");
+    expect(process.env.HORIZON_TIMEOUT_MS).toBe("5000");
+    expect(process.env.HORIZON_MAX_RETRIES).toBe("1");
+    expect(process.env.HORIZON_CB_THRESHOLD).toBe("10");
+    expect(process.env.HORIZON_CB_COOLDOWN_MS).toBe("10000");
+  });
+});

src/middlewares/errorHandler.js

@@ -79,6 +79,12 @@ export const errorHandler = (err, req, res, next) => {
   err.status = err.status || "error";
 
   if (process.env.NODE_ENV === "development") {
+    if (err.name === "AllEndpointsOpenError") {
+      return res.status(503).json({
+        error: "Stellar network currently unreachable. Please try again later.",
+        code: "NETWORK_UNAVAILABLE"
+      });
+    }
     sendErrorDev(err, req, res);
   } else {
     let error = { ...err };
@@ -89,6 +95,13 @@ export const errorHandler = (err, req, res, next) => {
     if (err.name === "ValidationError") error = handleValidationErrorDB(err);
     if (err.name === "JsonWebTokenError") error = handleJWTError();
     if (err.name === "TokenExpiredError") error = handleJWTExpiredError();
+
+    if (err.name === "AllEndpointsOpenError") {
+      return res.status(503).json({
+        error: "Stellar network currently unreachable. Please try again later.",
+        code: "NETWORK_UNAVAILABLE"
+      });
+    }
 
     sendErrorProd(error, req, res);
   }

src/routes/books/bookRoutes.js

@@ -17,43 +17,76 @@ import {
   removeBookBookmark,
 } from "../../controllers/books/bookmarkBookController.js";
 import { protect } from "../../middlewares/authMiddleware.js";
+import {
+  cacheMiddleware,
+  invalidateCacheMiddleware,
+} from "../../middlewares/cache.js";
+import { CACHE_TTL, CACHE_KEYS } from "../../utils/cache.js";
 
 const router = express.Router();
 
-// creating book
+// Cache key generators
+const booksListCacheKey = () => `${CACHE_KEYS.BOOKS}list`;
+const bookDetailCacheKey = (req) => `${CACHE_KEYS.BOOK}${req.params.id}`;
+const booksByAuthorCacheKey = (req) =>
+  `${CACHE_KEYS.BOOKS}author:${req.params.authorId}`;
 
+// creating book - invalidates books list cache
 router.post(
   "/",
   protect,
   upload.fields([
     { name: "thumbnail", maxCount: 1 },
     { name: "file", maxCount: 1 },
   ]),
+  invalidateCacheMiddleware([`${CACHE_KEYS.BOOKS}*`]),
   createBook
 );
-// getting all books
-router.get("/", getBooks);
 
-// get recommended books for user
-router.get("/recom", fetchRecommendedBooks);
+// getting all books - cached for 15 minutes
+router.get("/", cacheMiddleware(CACHE_TTL.BOOKS, booksListCacheKey), getBooks);
+
+// get recommended books for user - cached for 5 minutes
+router.get(
+  "/recom",
+  cacheMiddleware(CACHE_TTL.SHORT, () => `${CACHE_KEYS.BOOKS}recommended`),
+  fetchRecommendedBooks
+);
 
 // Bookmarks (must come before dynamic :id routes)
 router.get("/bookmarks", protect, getBookmarkedBooks);
 router.post("/:bookId/bookmark", protect, toggleBookBookmark);
 router.get("/:bookId/bookmark/check", protect, checkIfBookBookmarked);
 router.delete("/:bookId/bookmark", protect, removeBookBookmark);
 
-//get books  created by the author
-router.get("/by-author/:authorId", getBooksByAuthor);
+// get books created by the author - cached for 15 minutes
+router.get(
+  "/by-author/:authorId",
+  cacheMiddleware(CACHE_TTL.BOOKS, booksByAuthorCacheKey),
+  getBooksByAuthor
+);
 
-//get a spefic book
+// get a specific book - cached for 15 minutes
 router.get("/:id/preview", protect, streamBookPreview);
-router.get("/:id", getBook);
+router.get(
+  "/:id",
+  cacheMiddleware(CACHE_TTL.BOOKS, bookDetailCacheKey),
+  getBook
+);
 
-// delete a book
-router.delete("/:id", deleteBook);
+// delete a book - invalidates book caches
+router.delete(
+  "/:id",
+  invalidateCacheMiddleware([`${CACHE_KEYS.BOOKS}*`, `${CACHE_KEYS.BOOK}*`]),
+  deleteBook
+);
 
-//review a book
-router.post("/:id/reviews", protect, addBookReview);
+// review a book - invalidates specific book cache
+router.post(
+  "/:id/reviews",
+  protect,
+  invalidateCacheMiddleware([`${CACHE_KEYS.BOOK}*`]),
+  addBookReview
+);
 
 export default router;