psf-bch-api 1.2.0 → 7.1.0

package/.env-local

@@ -1,4 +1,32 @@
+# START INFRASTRUCTURE SETUP
+
 # Full Node Connection
 RPC_BASEURL=http://172.17.0.1:8332
 RPC_USERNAME=bitcoin
 RPC_PASSWORD=password
+
+# Fulcrum Indexer
+FULCRUM_API=http://172.17.0.1:3001/v1
+
+# SLP Indexer
+SLP_INDEXER_API=http://localhost:5010
+
+# REST API URL for wallet operations
+LOCAL_RESTURL=http://localhost:5942/v6
+
+# END INFRASTRUCTURE SETUP
+
+
+# START ACCESS CONTROL
+
+# x402 payments required to access this API?
+X402_ENABLED=true
+SERVER_BCH_ADDRESS=bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d
+FACILITATOR_URL=http://localhost:4345/facilitator
+
+# Basic Authentication required to access this API?
+USE_BASIC_AUTH=true
+BASIC_AUTH_TOKEN=some-random-token
+
+# END ACCESS CONTROL
+

package/bin/server.js

@@ -1,5 +1,5 @@
 /*
-  Express server for REST2NOSTR Proxy API.
+  Express server for psf-bch-api REST API.
   The architecture of the code follows the Clean Architecture pattern.
 */
 
@@ -15,7 +15,8 @@ import { dirname, join } from 'path'
 import config from '../src/config/index.js'
 import Controllers from '../src/controllers/index.js'
 import wlogger from '../src/adapters/wlogger.js'
-import { buildX402Routes, getX402Settings } from '../src/config/x402.js'
+import { buildX402Routes, getX402Settings, getBasicAuthSettings } from '../src/config/x402.js'
+import { basicAuthMiddleware } from '../src/middleware/basic-auth.js'
 
 // Load environment variables
 dotenv.config()
@@ -60,6 +61,7 @@ class Server {
       const app = express()
 
       const x402Settings = getX402Settings()
+      const basicAuthSettings = getBasicAuthSettings()
 
       // MIDDLEWARE START
       app.use(express.json())
@@ -72,22 +74,72 @@ class Server {
         allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With']
       }))
 
-      if (x402Settings.enabled) {
+      // Apply basic auth middleware if enabled
+      // This must run before x402 middleware to set req.locals.basicAuthValid
+      if (basicAuthSettings.enabled) {
+        wlogger.info('Basic auth middleware enabled')
+        app.use(basicAuthMiddleware)
+      }
+
+      // Apply x402 middleware based on configuration
+      // Logic:
+      // - If X402_ENABLED=false OR USE_BASIC_AUTH=false: Don't apply x402 (no rate limits)
+      // - If X402_ENABLED=true AND USE_BASIC_AUTH=true: Apply x402 conditionally (bypass if basic auth valid)
+
+      // Apply access control middleware based on configuration
+      if (x402Settings.enabled && basicAuthSettings.enabled) {
+        // X402_ENABLED=true AND USE_BASIC_AUTH=true: Apply x402 conditionally
         const routes = buildX402Routes(this.config.apiPrefix)
         const facilitatorOptions = x402Settings.facilitatorUrl
           ? { url: x402Settings.facilitatorUrl }
           : undefined
 
-        wlogger.info(`x402 middleware enabled; enforcing ${x402Settings.priceSat} satoshis per request`)
-        app.use(
-          x402PaymentMiddleware(
+        wlogger.info(`x402 middleware enabled with basic auth bypass; enforcing ${x402Settings.priceSat} satoshis per request (unless basic auth provided)`)
+
+        // Create conditional x402 middleware that bypasses if basic auth is valid
+        const conditionalX402Middleware = (req, res, next) => {
+          // If basic auth is valid, bypass x402
+          if (req.locals?.basicAuthValid === true) {
+            return next()
+          }
+
+          // Otherwise, apply x402 middleware
+          return x402PaymentMiddleware(
             x402Settings.serverAddress,
             routes,
             facilitatorOptions
-          )
-        )
+          )(req, res, next)
+        }
+
+        app.use(conditionalX402Middleware)
+      } else if (basicAuthSettings.enabled && !x402Settings.enabled) {
+        // USE_BASIC_AUTH=true AND X402_ENABLED=false: Require basic auth, reject unauthenticated requests
+        wlogger.info('Basic auth enforcement enabled (x402 disabled)')
+
+        // Middleware that rejects requests without valid basic auth
+        const requireBasicAuthMiddleware = (req, res, next) => {
+          // Skip auth check for health endpoint and root
+          if (req.path === '/health' || req.path === '/') {
+            return next()
+          }
+
+          // If basic auth is valid, allow the request
+          if (req.locals?.basicAuthValid === true) {
+            return next()
+          }
+
+          // Reject unauthenticated requests
+          wlogger.warn(`Unauthenticated request rejected: ${req.method} ${req.path}`)
+          return res.status(401).json({
+            error: 'Unauthorized',
+            message: 'Valid Bearer token required in Authorization header'
+          })
+        }
+
+        app.use(requireBasicAuthMiddleware)
       } else {
-        wlogger.info('x402 middleware disabled via configuration')
+        // X402_ENABLED=false AND USE_BASIC_AUTH=false: No access control middleware
+        wlogger.info('No access control middleware enabled')
       }
 
       // Endpoint logging middleware

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "psf-bch-api",
-  "version": "1.2.0",
-  "main": "index.js",
+  "version": "7.1.0",
+  "main": "psf-bch-api.js",
   "type": "module",
   "scripts": {
     "start": "node bin/server.js",
@@ -15,10 +15,14 @@
   "license": "MIT",
   "description": "REST API proxy to Bitcoin Cash infrastructure",
   "dependencies": {
+    "@psf/bch-js": "6.8.3",
     "axios": "1.7.7",
     "cors": "2.8.5",
     "dotenv": "16.3.1",
     "express": "5.1.0",
+    "minimal-slp-wallet": "5.13.3",
+    "psffpp": "1.2.0",
+    "slp-token-media": "1.2.10",
     "winston": "3.11.0",
     "winston-daily-rotate-file": "4.7.1",
     "x402-bch-express": "1.1.1"

package/src/adapters/fulcrum-api.js

@@ -0,0 +1,124 @@
+/*
+  Adapter library for interacting with Fulcrum API service over HTTP.
+*/
+
+import axios from 'axios'
+import wlogger from './wlogger.js'
+import config from '../config/index.js'
+
+class FulcrumAPIAdapter {
+  constructor (localConfig = {}) {
+    this.config = localConfig.config || config
+
+    // Allow missing config for testing environments
+    if (!this.config.fulcrumApi || !this.config.fulcrumApi.baseUrl) {
+      if (process.env.NODE_ENV === 'test' || process.env.TEST) {
+        // In test environment, create a mock baseURL
+        this.config.fulcrumApi = {
+          baseUrl: 'http://localhost:50001',
+          timeoutMs: 15000
+        }
+      } else {
+        throw new Error('FULCRUM_API env var not set. Can not connect to Fulcrum indexer.')
+      }
+    }
+
+    const {
+      baseUrl,
+      timeoutMs = 15000
+    } = this.config.fulcrumApi
+
+    this.http = axios.create({
+      baseURL: baseUrl,
+      timeout: timeoutMs
+    })
+  }
+
+  async get (path) {
+    try {
+      const response = await this.http.get(path)
+      return response.data
+    } catch (err) {
+      throw this._handleError(err)
+    }
+  }
+
+  async post (path, data) {
+    try {
+      const response = await this.http.post(path, data)
+      return response.data
+    } catch (err) {
+      throw this._handleError(err)
+    }
+  }
+
+  _handleError (err) {
+    const { status, message } = this.decodeError(err)
+    const error = new Error(message)
+    error.status = status
+    error.originalError = err
+    return error
+  }
+
+  decodeError (err) {
+    try {
+      // Attempt to extract error message from response data
+      if (err.response && err.response.data) {
+        const data = err.response.data
+        // Handle structured error responses
+        if (data.error) {
+          return this._formatError(data.error, err.response.status || 400)
+        }
+        // Handle string error messages
+        if (typeof data === 'string') {
+          return this._formatError(data, err.response.status || 400)
+        }
+        // Handle object responses that might contain error info
+        if (typeof data === 'object' && data.message) {
+          return this._formatError(data.message, err.response.status || 400)
+        }
+        // Fallback to returning the status
+        return this._formatError('Fulcrum API error', err.response.status || 500)
+      }
+
+      // Network errors
+      if (err.message) {
+        if (err.message.includes('ENOTFOUND') || err.message.includes('ENETUNREACH') || err.message.includes('EAI_AGAIN')) {
+          return this._formatError(
+            'Network error: Could not communicate with Fulcrum API service.',
+            503
+          )
+        }
+      }
+
+      if (err.code && (err.code === 'ECONNABORTED' || err.code === 'ECONNREFUSED')) {
+        return this._formatError(
+          'Network error: Could not communicate with Fulcrum API service.',
+          503
+        )
+      }
+
+      if (err.error && typeof err.error === 'string' && err.error.includes('429')) {
+        return this._formatError('429 Too Many Requests', 429)
+      }
+
+      if (err.message) {
+        return this._formatError(err.message, err.status || 422)
+      }
+
+      return this._formatError('Unhandled Fulcrum API error', 500)
+    } catch (decodeError) {
+      wlogger.error('Unhandled error in FulcrumAPIAdapter.decodeError()', decodeError)
+      return this._formatError('Internal server error', 500)
+    }
+  }
+
+  _formatError (message, status = 500) {
+    return {
+      message: message || 'Internal server error',
+      status: status || 500
+    }
+  }
+}
+
+export default FulcrumAPIAdapter

package/src/adapters/full-node-rpc.js

@@ -113,12 +113,8 @@ class FullNodeRPCAdapter {
     }
   }
 
-  validateArraySize (length, options = {}) {
-    const { isProUser = false } = options
-    const freemiumLimit = Number(this.config.fullNode?.freemiumArrayLimit || 20)
-    const proLimit = Number(this.config.fullNode?.proArrayLimit || freemiumLimit)
-
-    const limit = isProUser ? proLimit : freemiumLimit
+  validateArraySize (length) {
+    const limit = 20
     return length <= limit
   }
 

package/src/adapters/index.js

@@ -7,6 +7,8 @@
 // Load individual adapter libraries.
 // import NostrRelayAdapter from './nostr-relay.js'
 import FullNodeRPCAdapter from './full-node-rpc.js'
+import FulcrumAPIAdapter from './fulcrum-api.js'
+import SlpIndexerAPIAdapter from './slp-indexer-api.js'
 import config from '../config/index.js'
 
 class Adapters {
@@ -33,6 +35,8 @@ class Adapters {
     // this.nostrRelay = this.nostrRelays[0]
 
     this.fullNode = new FullNodeRPCAdapter({ config: this.config })
+    this.fulcrum = new FulcrumAPIAdapter({ config: this.config })
+    this.slpIndexer = new SlpIndexerAPIAdapter({ config: this.config })
   }
 
   async start () {

package/src/adapters/slp-indexer-api.js

@@ -0,0 +1,124 @@
+/*
+  Adapter library for interacting with SLP Indexer API service over HTTP.
+*/
+
+import axios from 'axios'
+import wlogger from './wlogger.js'
+import config from '../config/index.js'
+
+class SlpIndexerAPIAdapter {
+  constructor (localConfig = {}) {
+    this.config = localConfig.config || config
+
+    // Allow missing config for testing environments
+    if (!this.config.slpIndexerApi || !this.config.slpIndexerApi.baseUrl) {
+      if (process.env.NODE_ENV === 'test' || process.env.TEST) {
+        // In test environment, create a mock baseURL
+        this.config.slpIndexerApi = {
+          baseUrl: 'http://localhost:5021',
+          timeoutMs: 15000
+        }
+      } else {
+        throw new Error('SLP_INDEXER_API env var not set. Can not connect to PSF SLP indexer.')
+      }
+    }
+
+    const {
+      baseUrl,
+      timeoutMs = 15000
+    } = this.config.slpIndexerApi
+
+    this.http = axios.create({
+      baseURL: baseUrl,
+      timeout: timeoutMs
+    })
+  }
+
+  async get (path) {
+    try {
+      const response = await this.http.get(path)
+      return response.data
+    } catch (err) {
+      throw this._handleError(err)
+    }
+  }
+
+  async post (path, data) {
+    try {
+      const response = await this.http.post(path, data)
+      return response.data
+    } catch (err) {
+      throw this._handleError(err)
+    }
+  }
+
+  _handleError (err) {
+    const { status, message } = this.decodeError(err)
+    const error = new Error(message)
+    error.status = status
+    error.originalError = err
+    return error
+  }
+
+  decodeError (err) {
+    try {
+      // Attempt to extract error message from response data
+      if (err.response && err.response.data) {
+        const data = err.response.data
+        // Handle structured error responses
+        if (data.error) {
+          return this._formatError(data.error, err.response.status || 400)
+        }
+        // Handle string error messages
+        if (typeof data === 'string') {
+          return this._formatError(data, err.response.status || 400)
+        }
+        // Handle object responses that might contain error info
+        if (typeof data === 'object' && data.message) {
+          return this._formatError(data.message, err.response.status || 400)
+        }
+        // Fallback to returning the status
+        return this._formatError('SLP Indexer API error', err.response.status || 500)
+      }
+
+      // Network errors
+      if (err.message) {
+        if (err.message.includes('ENOTFOUND') || err.message.includes('ENETUNREACH') || err.message.includes('EAI_AGAIN')) {
+          return this._formatError(
+            'Network error: Could not communicate with SLP Indexer API service.',
+            503
+          )
+        }
+      }
+
+      if (err.code && (err.code === 'ECONNABORTED' || err.code === 'ECONNREFUSED')) {
+        return this._formatError(
+          'Network error: Could not communicate with SLP Indexer API service.',
+          503
+        )
+      }
+
+      if (err.error && typeof err.error === 'string' && err.error.includes('429')) {
+        return this._formatError('429 Too Many Requests', 429)
+      }
+
+      if (err.message) {
+        return this._formatError(err.message, err.status || 422)
+      }
+
+      return this._formatError('Unhandled SLP Indexer API error', 500)
+    } catch (decodeError) {
+      wlogger.error('Unhandled error in SlpIndexerAPIAdapter.decodeError()', decodeError)
+      return this._formatError('Internal server error', 500)
+    }
+  }
+
+  _formatError (message, status = 500) {
+    return {
+      message: message || 'Internal server error',
+      status: status || 500
+    }
+  }
+}
+
+export default SlpIndexerAPIAdapter

package/src/config/env/common.js

@@ -16,6 +16,7 @@ const pkgInfo = JSON.parse(readFileSync(`${__dirname.toString()}/../../../packag
 
 const version = pkgInfo.version
 
+// This function is used to convert the string input of an environment variable to a boolean value.
 const normalizeBoolean = (value, defaultValue) => {
   if (value === undefined || value === null || value === '') return defaultValue
 
@@ -25,16 +26,23 @@ const normalizeBoolean = (value, defaultValue) => {
   return defaultValue
 }
 
+// By default, the price per API call is 2000 satoshis.
+// But the user can override this value by setting the X402_PRICE_SAT environment variable.
 const parsedPriceSat = Number(process.env.X402_PRICE_SAT)
 const priceSat = Number.isFinite(parsedPriceSat) && parsedPriceSat > 0 ? parsedPriceSat : 2000
 
 const x402Defaults = {
   enabled: normalizeBoolean(process.env.X402_ENABLED, true),
   facilitatorUrl: process.env.FACILITATOR_URL || 'http://localhost:4345/facilitator',
-  serverAddress: process.env.SERVER_BCH_ADDRESS || 'bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d',
+  serverAddress: process.env.SERVER_BCH_ADDRESS || 'bitcoincash:qqsrke9lh257tqen99dkyy2emh4uty0vky9y0z0lsr',
   priceSat
 }
 
+const basicAuthDefaults = {
+  enabled: normalizeBoolean(process.env.USE_BASIC_AUTH, false),
+  token: process.env.BASIC_AUTH_TOKEN || ''
+}
+
 export default {
   // Server port
   port: process.env.PORT || 5942,
@@ -48,30 +56,6 @@ export default {
   // Logging level
   logLevel: process.env.LOG_LEVEL || 'info',
 
-  // Nostr relay configuration (array of relay URLs)
-  nostrRelayUrls: (() => {
-    // Support NOSTR_RELAY_URLS (plural) as comma-separated string or JSON array
-    if (process.env.NOSTR_RELAY_URLS) {
-      try {
-        // Try parsing as JSON array first
-        const parsed = JSON.parse(process.env.NOSTR_RELAY_URLS)
-        if (Array.isArray(parsed)) {
-          return parsed.filter(url => url && typeof url === 'string')
-        }
-      } catch (e) {
-        // Not JSON, treat as comma-separated string
-        return process.env.NOSTR_RELAY_URLS.split(',').map(url => url.trim()).filter(url => url.length > 0)
-      }
-    }
-    // Backward compatibility: support NOSTR_RELAY_URL (singular)
-    if (process.env.NOSTR_RELAY_URL) {
-      return [process.env.NOSTR_RELAY_URL]
-    }
-
-    // Default
-    return ['wss://nostr-relay.psfoundation.info', 'wss://relay.damus.io']
-  })(),
-
   // Full node RPC configuration
   fullNode: {
     rpcBaseUrl: process.env.RPC_BASEURL || 'http://127.0.0.1:8332',
@@ -81,8 +65,28 @@ export default {
     rpcRequestIdPrefix: process.env.RPC_REQUEST_ID_PREFIX || 'psf-bch-api'
   },
 
+  // Fulcrum API configuration
+  fulcrumApi: {
+    baseUrl: process.env.FULCRUM_API || '',
+    timeoutMs: Number(process.env.FULCRUM_TIMEOUT_MS || 15000)
+  },
+
+  // SLP Indexer API configuration
+  slpIndexerApi: {
+    baseUrl: process.env.SLP_INDEXER_API || '',
+    timeoutMs: Number(process.env.SLP_INDEXER_TIMEOUT_MS || 15000)
+  },
+
+  // REST API URL for wallet operations
+  restURL: process.env.REST_URL || process.env.LOCAL_RESTURL || 'http://127.0.0.1:5942/v6/',
+
+  // IPFS Gateway URL
+  ipfsGateway: process.env.IPFS_GATEWAY || 'p2wdb-gateway-678.fullstack.cash',
+
   x402: x402Defaults,
 
+  basicAuth: basicAuthDefaults,
+
   // Version
   version
 }

package/src/config/x402.js

@@ -41,3 +41,10 @@ export function getX402Settings () {
     priceSat: config.x402?.priceSat
   }
 }
+
+export function getBasicAuthSettings () {
+  return {
+    enabled: Boolean(config.basicAuth?.enabled),
+    token: config.basicAuth?.token || ''
+  }
+}