diff --git a/.env-example b/.env-example index c134967..ce5c0ca 100644 --- a/.env-example +++ b/.env-example @@ -16,6 +16,9 @@ export LOCAL_RESTURL=http://localhost:5942/v6 # END INFRASTRUCTURE SETUP +# Public base URL for apiDoc HTML (optional; used by Docker entrypoint before `npm run docs`). +#APIDOC_URL=https://api.example.com + # START ACCESS CONTROL diff --git a/README.md b/README.md index e85a7c6..b207cb8 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,21 @@ Protected endpoints return `402 Payment Required` when no valid payment is attac ### 4) x402 + Bearer Bypass -```bash +When `X402_ENABLED=true`, the server also exposes machine-discovery endpoints: + +- `/.well-known/x402` - x402-bch v2 payment discovery manifest +- `/openapi.json` - OpenAPI 3 projection generated from apiDoc annotations +- `/swagger.json` - Swagger 2.0 compatibility projection +- `/llms.txt` - LLM-oriented markdown index of service metadata +- `/.well-known/agent.json` - draft agent manifest describing API actions + +When `X402_ENABLED=false`, these discovery endpoints return `404`. + +#### Combined: x402 + Bearer Token + +You can enable both at the same time: + +``` X402_ENABLED=true USE_BASIC_AUTH=true BASIC_AUTH_TOKEN=my-secret-token @@ -182,6 +196,126 @@ npm test npm run test:integration npm run docs ``` +X402_ENABLED=false +USE_BASIC_AUTH=false +``` + +5. Start the server: + +`npm start` + +The server will start on port `5942` by default (or whatever you set in `PORT`). API documentation is available at `http://localhost:5942/`. + +### Generating API Docs + +The API reference documentation is generated by [apiDoc](https://apidocjs.com/) from inline annotations in the source code. To regenerate: + +`npm run docs` + +The output is written to the `docs/` directory and served by the running server at its root URL. + +To regenerate API docs plus discovery artifacts (`openapi.json`, `swagger.json`, `llms.txt`, and `agent.json` payload source): + +`npm run docs:all` + +This runs apiDoc first, then generates `docs/discovery-artifacts.json` from the same annotation source. + +A live version can be found at [bch.fullstack.cash](https://bch.fullstack.cash/). + +## Production (Docker) + +A Docker setup is provided in the `production/docker/` directory for production deployments. The target OS is Ubuntu Linux. + +1. Install [Docker and Docker Compose](https://docs.docker.com/engine/install/ubuntu/). + +2. Navigate to the Docker directory: + +`cd production/docker` + +3. Create and configure the `.env` file. An example is provided: + +`cp .env-example .env` + +Edit `.env` to match your production infrastructure. Note that inside a Docker container, `localhost` refers to the container itself. Use `172.17.0.1` (the default Docker bridge gateway) to reach services running on the host machine: + +``` +RPC_BASEURL=http://172.17.0.1:8332 +FULCRUM_API=http://172.17.0.1:3001/v1 +SLP_INDEXER_API=http://172.17.0.1:5010 +``` + +Set `APIDOC_URL` to the public base URL for your deployment (for example `https://api.example.com` or your subdomain). The container entrypoint applies this value to `apidoc.json` and the `apidoc` section of `package.json`, then runs `npm run docs` before starting the server so generated HTML matches each instance. The compose file mounts `./.env` to `/home/safeuser/psf-bch-api/.env` so it matches `dotenv.config()` in the app. + +4. Build the Docker image: + +`docker-compose build --no-cache` + +5. Start the container: + +`docker-compose up -d` + +The container maps host port `5942` to container port `5942`. The `.env` file is mounted into the container as a volume, so you can update configuration without rebuilding. + +To view logs: + +`docker logs -f psf-bch-api` + +To stop the container: + +`docker-compose down` + +A helper script `cleanup-images.sh` is provided to remove dangling Docker images after rebuilds. + +## Testing + +The project includes both unit tests and integration tests. Tests use [Mocha](https://mochajs.org/) as the test runner, [Chai](https://www.chaijs.com/) for assertions, and [Sinon](https://sinonjs.org/) for mocking. Code coverage is provided by [c8](https://github.com/bcoe/c8). + +### Unit Tests + +Unit tests are located in `test/unit/` and cover adapters, controllers, and use cases. They do not require any running infrastructure. To run: + +`npm test` + +This will first lint the code with [Standard](https://standardjs.com/), then execute all unit tests with code coverage. + +To generate an HTML coverage report: + +`npm run coverage` + +The report is written to the `coverage/` directory. + +### Integration Tests + +Integration tests are located in `test/integration/` and require the back end infrastructure (full node, Fulcrum, SLP indexer) to be running. To run: + +`npm run test:integration` + +Integration tests have a 25-second timeout per test to accommodate network calls. + +## Configuration Reference + +All configuration values are read from environment variables (via the `.env` file). The complete list: + +- `PORT` - Server listen port. Default: `5942` +- `NODE_ENV` - Environment (`development` or `production`). Default: `development` +- `API_PREFIX` - URL prefix for all REST endpoints. Default: `/v6` +- `LOG_LEVEL` - Winston logging level. Default: `info` +- `RPC_BASEURL` - Full node JSON-RPC URL. Default: `http://127.0.0.1:8332` +- `RPC_USERNAME` - Full node RPC username. +- `RPC_PASSWORD` - Full node RPC password. +- `RPC_TIMEOUT_MS` - Full node RPC request timeout in ms. Default: `15000` +- `FULCRUM_API` - Fulcrum indexer REST API URL. +- `FULCRUM_TIMEOUT_MS` - Fulcrum API request timeout in ms. Default: `15000` +- `SLP_INDEXER_API` - SLP Token Indexer REST API URL. +- `SLP_INDEXER_TIMEOUT_MS` - SLP Indexer API request timeout in ms. Default: `15000` +- `LOCAL_RESTURL` - Internal REST URL for wallet operations. Default: `http://127.0.0.1:5942/v6/` +- `IPFS_GATEWAY` - IPFS gateway hostname. Default: `p2wdb-gateway-678.fullstack.cash` +- `X402_ENABLED` - Enable x402-bch payment middleware. Default: `true` +- `SERVER_BCH_ADDRESS` - BCH address for x402 payments. Default: `bitcoincash:qqsrke9lh257tqen99dkyy2emh4uty0vky9y0z0lsr` +- `FACILITATOR_URL` - x402-bch facilitator service URL. Default: `http://localhost:4345/facilitator` +- `X402_PRICE_SAT` - Satoshis charged per API call via x402. Default: `200` +- `USE_BASIC_AUTH` - Enable Bearer token authentication. Default: `false` +- `BASIC_AUTH_TOKEN` - Expected Bearer token value. ## License diff --git a/bin/server.js b/bin/server.js index 2c652f5..8cc6651 100644 --- a/bin/server.js +++ b/bin/server.js @@ -18,6 +18,7 @@ import Controllers from '../src/controllers/index.js' import wlogger from '../src/adapters/wlogger.js' import { buildX402Routes, getX402Settings, getBasicAuthSettings, createAuthHeader } from '../src/config/x402.js' import { basicAuthMiddleware } from '../src/middleware/basic-auth.js' +import DiscoveryRouter from '../src/controllers/discovery/router.js' // Load environment variables dotenv.config() @@ -228,6 +229,8 @@ class Server { // Attach REST API controllers to the app. this.controllers.attachRESTControllers(app) + const discoveryRouter = new DiscoveryRouter() + discoveryRouter.attach(app) // Initialize any other controller libraries. this.controllers.initControllers() diff --git a/dev-docs/update-logs/2026-04-01.md b/dev-docs/update-logs/2026-04-01.md new file mode 100644 index 0000000..b9f2285 --- /dev/null +++ b/dev-docs/update-logs/2026-04-01.md @@ -0,0 +1,72 @@ +# 2026-04-01 Update Log + +## Summary + +Added x402-gated discovery endpoints for agent/tool self-discovery, built a docs-derived artifact pipeline from apiDoc annotations, and documented the new flow and behavior. + +## Changes Made + +- Added new discovery controller/router: + - `src/controllers/discovery/controller.js` + - `src/controllers/discovery/router.js` +- Added five root-path discovery endpoints: + - `GET /.well-known/x402` + - `GET /openapi.json` + - `GET /swagger.json` + - `GET /llms.txt` + - `GET /.well-known/agent.json` +- Added x402-enabled gating: + - All five endpoints now return `404` when `X402_ENABLED=false`. + - When enabled, payloads are returned with x402-bch v2-oriented metadata. +- Added apiDoc-derived document builder: + - `src/discovery/build-documents.js` + - Parses `@api` annotations and builds OpenAPI, Swagger, llms, and agent documents. + - Uses `docs/discovery-artifacts.json` if present, otherwise builds in-process. +- Added artifact generation script: + - `scripts/build-discovery-artifacts.js` + - Writes `docs/discovery-artifacts.json` +- Updated npm scripts in `package.json`: + - `docs:discovery` + - `docs:all` (runs `docs` then `docs:discovery`) +- Wired discovery routes into server bootstrap: + - `bin/server.js` +- Added tests: + - `test/unit/controllers/discovery-controller-unit.js` + - `test/unit/controllers/discovery-router-unit.js` + - `test/unit/controllers/discovery-documents-unit.js` +- Updated docs/config examples: + - `README.md` (discovery endpoints + docs workflow) + - `.env-example` (x402 gating note for discovery endpoints) + +## Why This Was Changed + +- Endpoint probes for discovery paths are common from API tooling and AI agents. +- Serving structured discovery metadata improves machine interoperability for: + - API clients and SDK tooling (`openapi.json`, `swagger.json`) + - LLM retrieval workflows (`llms.txt`) + - Agent capability discovery (`agent.json`) + - x402 payment discovery (`/.well-known/x402`) +- Gating by `X402_ENABLED` keeps discovery aligned with monetization mode and avoids advertising payment surfaces when x402 is disabled. + +## Validation Notes + +- Lint passed. +- New discovery-focused unit tests passed. +- Full `npm test` run showed one pre-existing timeout failure in `test/unit/use-cases/price-use-cases-unit.js` unrelated to discovery endpoint changes. + +## References + +- Local protocol spec: + - `../x402-bch/specs/x402-bch-specification-v2.2.md` +- OpenAPI Specification: + - https://spec.openapis.org/oas/latest.html +- Swagger / OpenAPI 2.0: + - https://swagger.io/specification/v2/ +- llms.txt proposal: + - https://www.llmstxt.org/index.html +- Agent manifest draft reference: + - https://agentwebprotocol.org/spec +- x402 HTTP 402 background: + - https://docs.x402.org/core-concepts/http-402 +- x402 DNS discovery draft: + - https://www.ietf.org/archive/id/draft-jeftovic-x402-dns-discovery-00.html diff --git a/dev-docs/update-logs/2026-04-02.md b/dev-docs/update-logs/2026-04-02.md new file mode 100644 index 0000000..cd40bd5 --- /dev/null +++ b/dev-docs/update-logs/2026-04-02.md @@ -0,0 +1,19 @@ +# 2026-04-02 Update Log + +## Summary + +Docker deployments now run `npm run docs` at container start via an entrypoint script, and optionally apply `APIDOC_URL` from the environment so apiDoc HTML matches each deployment subdomain or public URL. + +## Changes Made + +- Added `scripts/patch-apidoc-from-env.js` to set `apidoc.json` and `package.json` `apidoc.url` from `APIDOC_URL` (dotenv loads the project `.env`, same path as `bin/server.js`). +- Added `production/docker/entrypoint.sh` to run the patch script, `npm run docs`, then `exec npm start`. +- Updated `production/docker/Dockerfile` to remove build-time `npm run docs`, copy the entrypoint and patch script from the build context, and use `ENTRYPOINT` for the shell script. +- Updated `production/docker/docker-compose.yml` to use build `context: ../..` and `dockerfile: production/docker/Dockerfile` so COPY paths resolve from the repository root. +- Compose mounts `./.env` at `/home/safeuser/psf-bch-api/.env` so the app and entrypoint share one file (not `/home/safeuser/.env`). +- Documented `APIDOC_URL` in `.env-example`, `production/docker/.env-example`, and `README.md` (Production Docker section). + +## Outcome + +- Operators can set `APIDOC_URL` in the mounted `.env` (for example `https://api.example.com`) per instance without rebuilding the image for each subdomain. +- The HTML apiDoc bundle is regenerated on every container start so it stays aligned with the configured URL. diff --git a/package.json b/package.json index f6790e7..300dcf7 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,8 @@ "scripts": { "start": "node bin/server.js", "docs": "./node_modules/.bin/apidoc -i src/ -o docs", + "docs:discovery": "node scripts/build-discovery-artifacts.js", + "docs:all": "npm run docs && npm run docs:discovery", "lint": "standard --env mocha --fix", "test": "npm run lint && TEST=unit c8 mocha 'test/unit/**/*.js' --exit", "test:integration": "mocha --timeout 25000 'test/integration/**/*.js' --exit", diff --git a/production/docker/.env-example b/production/docker/.env-example index 47c099b..8dc176c 100644 --- a/production/docker/.env-example +++ b/production/docker/.env-example @@ -16,6 +16,10 @@ export LOCAL_RESTURL=http://localhost:5942/v6 # END INFRASTRUCTURE SETUP +# Public base URL for apiDoc HTML (set per deployment / subdomain). +# Applied at container start before `npm run docs`. Example: https://api.example.com +#APIDOC_URL=https://api.example.com + # START ACCESS CONTROL diff --git a/production/docker/Dockerfile b/production/docker/Dockerfile index bff319b..53ba857 100644 --- a/production/docker/Dockerfile +++ b/production/docker/Dockerfile @@ -57,13 +57,15 @@ WORKDIR /home/safeuser/psf-bch-api-base RUN npm install #RUN npm install minimal-slp-wallet -# Generate the API docs -RUN npm run docs +# Runtime entrypoint + apidoc URL patch (see production/docker/entrypoint.sh). +# API docs are generated at container start so APIDOC_URL can be set per deployment. +COPY production/docker/entrypoint.sh /home/safeuser/psf-bch-api/entrypoint.sh +COPY scripts/patch-apidoc-from-env.js /home/safeuser/psf-bch-api/scripts/patch-apidoc-from-env.js +RUN chmod +x /home/safeuser/psf-bch-api/entrypoint.sh -COPY .env .env +# Runtime `.env` is provided by docker-compose (mount at psf-bch-api/.env), not baked into the image. - -CMD ["npm", "start"] +ENTRYPOINT ["/home/safeuser/psf-bch-api/entrypoint.sh"] # Used to debug the container. #COPY temp.js temp.js diff --git a/production/docker/docker-compose.yml b/production/docker/docker-compose.yml index 6524137..cbde449 100644 --- a/production/docker/docker-compose.yml +++ b/production/docker/docker-compose.yml @@ -1,9 +1,11 @@ # Start the service with the command 'docker-compose up -d' services: - psf-bch-api-x402-base: - build: . - container_name: psf-bch-api-x402-base + psf-bch-api-base: + build: + context: ../.. + dockerfile: production/docker/Dockerfile + container_name: psf-bch-api-base logging: driver: 'json-file' options: @@ -16,7 +18,7 @@ services: - '6100:6100' # : volumes: #- ./start-rest2nostr.sh:/home/safeuser/REST2NOSTR/start-rest2nostr.sh - - ./.env:/home/safeuser/.env + - ./.env:/home/safeuser/psf-bch-api-base/.env - ../data:/home/safeuser/psf-bch-api-base/production/data - ../data/logs:/home/safeuser/psf-bch-api-base/logs restart: always diff --git a/production/docker/entrypoint.sh b/production/docker/entrypoint.sh new file mode 100644 index 0000000..54a8834 --- /dev/null +++ b/production/docker/entrypoint.sh @@ -0,0 +1,10 @@ +#!/bin/bash +set -euo pipefail + +cd /home/safeuser/psf-bch-api-base + +node scripts/patch-apidoc-from-env.js + +npm run docs + +exec npm start diff --git a/scripts/build-discovery-artifacts.js b/scripts/build-discovery-artifacts.js new file mode 100644 index 0000000..1005186 --- /dev/null +++ b/scripts/build-discovery-artifacts.js @@ -0,0 +1,21 @@ +/* + Build discovery endpoint artifacts from apiDoc source annotations. +*/ + +import { mkdirSync, writeFileSync } from 'fs' +import { dirname, resolve } from 'path' + +import { buildDiscoveryDocuments } from '../src/discovery/build-documents.js' + +function main () { + const outputPath = resolve(process.cwd(), 'docs/discovery-artifacts.json') + const docs = buildDiscoveryDocuments() + + mkdirSync(dirname(outputPath), { recursive: true }) + writeFileSync(outputPath, `${JSON.stringify(docs, null, 2)}\n`) + + // eslint-disable-next-line no-console + console.log(`Wrote discovery artifacts to ${outputPath}`) +} + +main() diff --git a/scripts/patch-apidoc-from-env.js b/scripts/patch-apidoc-from-env.js new file mode 100644 index 0000000..f14c4b2 --- /dev/null +++ b/scripts/patch-apidoc-from-env.js @@ -0,0 +1,41 @@ +/* + Applies APIDOC_URL from the environment to apidoc.json and package.json (apidoc.url). + Loads dotenv from the project root `.env` (same file as `dotenv.config()` in bin/server.js). + Exits without changes when APIDOC_URL is unset or empty. +*/ + +import dotenv from 'dotenv' +import { readFileSync, writeFileSync } from 'fs' +import { dirname, resolve } from 'path' +import { fileURLToPath } from 'url' + +const __dirname = dirname(fileURLToPath(import.meta.url)) +const root = resolve(__dirname, '..') + +dotenv.config({ path: resolve(root, '.env') }) + +const url = process.env.APIDOC_URL +if (url === undefined || url === null || String(url).trim() === '') { + process.exit(0) +} + +const normalized = String(url).trim() + +function patchApidocJson () { + const path = resolve(root, 'apidoc.json') + const data = JSON.parse(readFileSync(path, 'utf8')) + data.url = normalized + data.sampleUrl = normalized + writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`) +} + +function patchPackageJson () { + const path = resolve(root, 'package.json') + const data = JSON.parse(readFileSync(path, 'utf8')) + if (!data.apidoc) data.apidoc = {} + data.apidoc.url = normalized + writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`) +} + +patchApidocJson() +patchPackageJson() diff --git a/src/controllers/discovery/controller.js b/src/controllers/discovery/controller.js new file mode 100644 index 0000000..f5605cf --- /dev/null +++ b/src/controllers/discovery/controller.js @@ -0,0 +1,152 @@ +/* + Controller for discovery and machine-readable metadata endpoints. +*/ + +import config from '../../config/index.js' +import { getX402Settings } from '../../config/x402.js' +import { getDiscoveryDocuments } from '../../discovery/build-documents.js' + +const BCH_MAINNET_CAIP2 = 'bip122:000000000000000000651ef99cb9fcbe' +const BCH_NATIVE_ASSET = '0x0000000000000000000000000000000000000001' +const X402_TIMEOUT_SECONDS = 60 + +class DiscoveryController { + constructor (localConfig = {}) { + this.getX402Settings = localConfig.getX402Settings || getX402Settings + this.getDiscoveryDocuments = localConfig.getDiscoveryDocuments || getDiscoveryDocuments + this.apiPrefix = localConfig.apiPrefix || config.apiPrefix + + this.x402Manifest = this.x402Manifest.bind(this) + this.openapi = this.openapi.bind(this) + this.swagger = this.swagger.bind(this) + this.llmsTxt = this.llmsTxt.bind(this) + this.agentManifest = this.agentManifest.bind(this) + this.respondNotFoundWhenDisabled = this.respondNotFoundWhenDisabled.bind(this) + this.sendText = this.sendText.bind(this) + } + + respondNotFoundWhenDisabled (res) { + const { enabled } = this.getX402Settings() + if (enabled) return false + + res.status(404).json({ + error: 'Not found' + }) + return true + } + + /** + * @api {get} /.well-known/x402 x402-bch resource discovery + * @apiName X402Discovery + * @apiGroup Discovery + * @apiDescription Returns x402-bch v2 resource and payment requirement metadata. + */ + x402Manifest (req, res) { + if (this.respondNotFoundWhenDisabled(res)) return + + const x402 = this.getX402Settings() + const apiPrefix = this.apiPrefix || '/v6' + const prefixWithSlash = apiPrefix.startsWith('/') ? apiPrefix : `/${apiPrefix}` + + const payload = { + x402Version: 2, + network: BCH_MAINNET_CAIP2, + facilitator: { + url: x402.facilitatorUrl + }, + resources: [ + { + resource: `${prefixWithSlash}/*`, + type: 'http', + x402Version: 2, + accepts: [ + { + scheme: 'utxo', + network: BCH_MAINNET_CAIP2, + amount: String(x402.priceSat), + description: `Access to protected psf-bch-api resources (${x402.priceSat} satoshis)`, + mimeType: 'application/json', + payTo: x402.serverAddress, + maxTimeoutSeconds: X402_TIMEOUT_SECONDS, + asset: BCH_NATIVE_ASSET, + extra: {} + } + ] + } + ] + } + + return res.status(200).json(payload) + } + + /** + * @api {get} /openapi.json OpenAPI discovery document + * @apiName OpenApiDiscovery + * @apiGroup Discovery + * @apiDescription Returns an OpenAPI document generated from apiDoc annotations. + */ + openapi (req, res) { + if (this.respondNotFoundWhenDisabled(res)) return + + const docs = this.getDiscoveryDocuments() + return res.status(200).json(docs.openapi) + } + + /** + * @api {get} /swagger.json Swagger discovery document + * @apiName SwaggerDiscovery + * @apiGroup Discovery + * @apiDescription Returns a Swagger 2.0 compatibility document generated from apiDoc annotations. + */ + swagger (req, res) { + if (this.respondNotFoundWhenDisabled(res)) return + + const docs = this.getDiscoveryDocuments() + return res.status(200).json(docs.swagger) + } + + /** + * @api {get} /llms.txt LLM discovery file + * @apiName LlmsDiscovery + * @apiGroup Discovery + * @apiDescription Returns an llms.txt markdown index for AI tooling discovery. + */ + llmsTxt (req, res) { + if (this.respondNotFoundWhenDisabled(res)) return + + const docs = this.getDiscoveryDocuments() + return this.sendText(res, docs.llms) + } + + /** + * @api {get} /.well-known/agent.json Agent manifest + * @apiName AgentManifestDiscovery + * @apiGroup Discovery + * @apiDescription Returns a draft agent manifest describing API capabilities. + */ + agentManifest (req, res) { + if (this.respondNotFoundWhenDisabled(res)) return + + const docs = this.getDiscoveryDocuments() + return res.status(200).json(docs.agent) + } + + sendText (res, text) { + res.status(200) + res.setHeader('Content-Type', 'text/plain; charset=utf-8') + + if (typeof res.send === 'function') { + return res.send(text) + } + + if (typeof res.write === 'function') { + res.write(text) + } + if (typeof res.end === 'function') { + res.end() + } + return res + } +} + +export default DiscoveryController diff --git a/src/controllers/discovery/router.js b/src/controllers/discovery/router.js new file mode 100644 index 0000000..ea7918a --- /dev/null +++ b/src/controllers/discovery/router.js @@ -0,0 +1,30 @@ +/* + Router for discovery and machine-readable metadata endpoints. +*/ + +import express from 'express' +import DiscoveryController from './controller.js' + +class DiscoveryRouter { + constructor (localConfig = {}) { + this.controller = localConfig.controller || new DiscoveryController() + this.router = express.Router() + this.attach = this.attach.bind(this) + } + + attach (app) { + if (!app) { + throw new Error('Must pass app object when attaching DiscoveryRouter.') + } + + this.router.get('/.well-known/x402', this.controller.x402Manifest) + this.router.get('/openapi.json', this.controller.openapi) + this.router.get('/swagger.json', this.controller.swagger) + this.router.get('/llms.txt', this.controller.llmsTxt) + this.router.get('/.well-known/agent.json', this.controller.agentManifest) + + app.use(this.router) + } +} + +export default DiscoveryRouter diff --git a/src/discovery/build-documents.js b/src/discovery/build-documents.js new file mode 100644 index 0000000..7bf5ed0 --- /dev/null +++ b/src/discovery/build-documents.js @@ -0,0 +1,223 @@ +/* + Build and cache discovery documents from apiDoc-style annotations. +*/ + +import { readFileSync, existsSync, readdirSync } from 'fs' +import { resolve } from 'path' + +import config from '../config/index.js' +import { getX402Settings } from '../config/x402.js' + +const BCH_MAINNET_CAIP2 = 'bip122:000000000000000000651ef99cb9fcbe' +const X402_SPEC_VERSION = 2 + +let cachedDocs = null + +function parseApiAnnotations () { + const srcRoot = resolve(process.cwd(), 'src/controllers/rest-api') + const entries = [] + const files = walkJsFiles(srcRoot) + + for (const file of files) { + const text = readFileSync(file, 'utf8') + const blocks = text.match(/\/\*\*[\s\S]*?\*\//g) || [] + + for (const block of blocks) { + const endpoint = parseBlock(block) + if (endpoint) entries.push(endpoint) + } + } + + return entries +} + +function parseBlock (block) { + const methodMatch = block.match(/@api\s+\{([^}]+)\}\s+(\S+)\s+([^\n\r*]+)/) + if (!methodMatch) return null + + const method = methodMatch[1].trim().toUpperCase() + const path = methodMatch[2].trim() + const summary = methodMatch[3].trim() + + const groupMatch = block.match(/@apiGroup\s+([^\n\r*]+)/) + const descriptionMatch = block.match(/@apiDescription\s+([^\n\r*][\s\S]*?)(?=\n\s*\*\s*@api|\n\s*\*\/)/) + const apiNameMatch = block.match(/@apiName\s+([^\n\r*]+)/) + + return { + method, + path, + summary, + group: groupMatch ? groupMatch[1].trim() : 'General', + operationId: apiNameMatch ? apiNameMatch[1].trim() : `${method.toLowerCase()}_${path.replace(/[^\w]/g, '_')}`, + description: descriptionMatch + ? descriptionMatch[1].replace(/\n\s*\*\s?/g, ' ').trim() + : summary + } +} + +function walkJsFiles (dir) { + const output = [] + + for (const item of readdirSync(dir, { withFileTypes: true })) { + const fullPath = resolve(dir, item.name) + if (item.isDirectory()) { + output.push(...walkJsFiles(fullPath)) + continue + } + + if (item.isFile() && fullPath.endsWith('.js')) output.push(fullPath) + } + + return output +} + +function normalizePaths (endpoints) { + const paths = {} + + for (const endpoint of endpoints) { + if (!paths[endpoint.path]) paths[endpoint.path] = {} + + const op = { + tags: [endpoint.group], + summary: endpoint.summary, + description: endpoint.description, + operationId: endpoint.operationId, + responses: { + 200: { + description: 'Successful response' + }, + 402: { + description: 'Payment required when x402 is enabled' + } + }, + 'x-payment-model': 'x402-bch-v2' + } + + paths[endpoint.path][endpoint.method.toLowerCase()] = op + } + + return paths +} + +function buildOpenApi (paths) { + return { + openapi: '3.0.3', + info: { + title: 'psf-bch-api', + version: config.version, + description: 'OpenAPI projection generated from apiDoc annotations' + }, + servers: [ + { + url: '/' + } + ], + paths + } +} + +function buildSwagger (paths) { + return { + swagger: '2.0', + info: { + title: 'psf-bch-api', + version: config.version, + description: 'Swagger projection generated from apiDoc annotations' + }, + basePath: '/', + schemes: ['https', 'http'], + paths + } +} + +function buildLlms (endpoints) { + const lines = [ + '# psf-bch-api', + '', + '> REST API proxy to Bitcoin Cash infrastructure with optional x402-bch monetized access.', + '', + '## Discovery', + '- [OpenAPI document](/openapi.json): OpenAPI 3 projection generated from apiDoc annotations.', + '- [Swagger document](/swagger.json): Swagger 2.0 compatibility projection.', + '- [x402 manifest](/.well-known/x402): x402-bch v2 payment requirement discovery.', + '- [Agent manifest](/.well-known/agent.json): draft agent capability surface.', + '', + '## API Groups' + ] + + const seen = new Set() + for (const endpoint of endpoints) { + if (seen.has(endpoint.group)) continue + seen.add(endpoint.group) + lines.push(`- ${endpoint.group}`) + } + + lines.push('', '## Optional', '- [Human docs](/): apiDoc HTML documentation root.') + return lines.join('\n') +} + +function buildAgent (endpoints) { + const x402 = getX402Settings() + const actions = endpoints.map(endpoint => ({ + id: endpoint.operationId, + description: endpoint.summary, + auth_required: true, + endpoint: endpoint.path, + method: endpoint.method + })) + + return { + awp_version: '0.1', + domain: 'localhost', + intent: 'Programmatic BCH blockchain API access', + capabilities: { + batch_actions: false, + streaming: false + }, + auth: { + type: 'x402-bch-v2', + required_for: actions.map(a => a.id), + pricing: { + amountSat: String(x402.priceSat), + payTo: x402.serverAddress, + network: BCH_MAINNET_CAIP2, + x402Version: X402_SPEC_VERSION + } + }, + actions + } +} + +export function buildDiscoveryDocuments () { + const endpoints = parseApiAnnotations() + const paths = normalizePaths(endpoints) + + return { + openapi: buildOpenApi(paths), + swagger: buildSwagger(paths), + llms: buildLlms(endpoints), + agent: buildAgent(endpoints) + } +} + +export function getDiscoveryDocuments () { + if (cachedDocs) return cachedDocs + + const artifactPath = resolve(process.cwd(), 'docs/discovery-artifacts.json') + if (existsSync(artifactPath)) { + try { + cachedDocs = JSON.parse(readFileSync(artifactPath, 'utf8')) + return cachedDocs + } catch { + cachedDocs = buildDiscoveryDocuments() + return cachedDocs + } + } + + cachedDocs = buildDiscoveryDocuments() + return cachedDocs +} + +export function resetDiscoveryDocumentCache () { + cachedDocs = null +} diff --git a/test/unit/controllers/discovery-controller-unit.js b/test/unit/controllers/discovery-controller-unit.js new file mode 100644 index 0000000..834cec1 --- /dev/null +++ b/test/unit/controllers/discovery-controller-unit.js @@ -0,0 +1,106 @@ +/* + Unit tests for DiscoveryController. +*/ + +import { assert } from 'chai' + +import DiscoveryController from '../../../src/controllers/discovery/controller.js' +import { createMockRequest, createMockResponse } from '../mocks/controller-mocks.js' + +describe('#discovery-controller.js', () => { + const makeController = ({ enabled = true } = {}) => { + return new DiscoveryController({ + apiPrefix: '/v6', + getX402Settings: () => ({ + enabled, + facilitatorUrl: 'http://localhost:4345/facilitator', + serverAddress: 'bitcoincash:qtestaddress', + priceSat: 200 + }), + getDiscoveryDocuments: () => ({ + openapi: { openapi: '3.0.3', paths: { '/v6/price/bchusd': {} } }, + swagger: { swagger: '2.0', paths: { '/v6/price/bchusd': {} } }, + llms: '# psf-bch-api', + agent: { awp_version: '0.1', actions: [] } + }) + }) + } + + describe('x402 disabled gating', () => { + it('should return 404 for all discovery endpoints when x402 disabled', async () => { + const uut = makeController({ enabled: false }) + const req = createMockRequest() + + const handlers = [ + uut.x402Manifest, + uut.openapi, + uut.swagger, + uut.llmsTxt, + uut.agentManifest + ] + + for (const handler of handlers) { + const res = createMockResponse() + await handler(req, res) + assert.equal(res.statusValue, 404) + assert.deepEqual(res.jsonData, { error: 'Not found' }) + } + }) + }) + + describe('x402 enabled responses', () => { + it('should return x402 manifest schema fields', async () => { + const uut = makeController({ enabled: true }) + const req = createMockRequest() + const res = createMockResponse() + + await uut.x402Manifest(req, res) + + assert.equal(res.statusValue, 200) + assert.equal(res.jsonData.x402Version, 2) + assert.isArray(res.jsonData.resources) + assert.equal(res.jsonData.resources[0].accepts[0].scheme, 'utxo') + assert.equal(res.jsonData.resources[0].accepts[0].amount, '200') + }) + + it('should return openapi and swagger docs', async () => { + const uut = makeController({ enabled: true }) + const req = createMockRequest() + + const openapiRes = createMockResponse() + await uut.openapi(req, openapiRes) + assert.equal(openapiRes.statusValue, 200) + assert.equal(openapiRes.jsonData.openapi, '3.0.3') + + const swaggerRes = createMockResponse() + await uut.swagger(req, swaggerRes) + assert.equal(swaggerRes.statusValue, 200) + assert.equal(swaggerRes.jsonData.swagger, '2.0') + }) + + it('should return llms.txt as text/plain', async () => { + const uut = makeController({ enabled: true }) + const req = createMockRequest() + const res = createMockResponse() + + await uut.llmsTxt(req, res) + + assert.equal(res.statusValue, 200) + assert.equal(res.headers['Content-Type'], 'text/plain; charset=utf-8') + assert.equal(res.writeData[0], '# psf-bch-api') + assert.isTrue(res.endCalled) + }) + + it('should return agent manifest json', async () => { + const uut = makeController({ enabled: true }) + const req = createMockRequest() + const res = createMockResponse() + + await uut.agentManifest(req, res) + + assert.equal(res.statusValue, 200) + assert.equal(res.jsonData.awp_version, '0.1') + assert.isArray(res.jsonData.actions) + }) + }) +}) diff --git a/test/unit/controllers/discovery-documents-unit.js b/test/unit/controllers/discovery-documents-unit.js new file mode 100644 index 0000000..4d80a92 --- /dev/null +++ b/test/unit/controllers/discovery-documents-unit.js @@ -0,0 +1,25 @@ +/* + Unit tests for discovery document builder. +*/ + +import { assert } from 'chai' + +import { buildDiscoveryDocuments } from '../../../src/discovery/build-documents.js' + +describe('#discovery-build-documents.js', () => { + it('should build openapi and swagger documents with v6 paths', () => { + const docs = buildDiscoveryDocuments() + + assert.property(docs, 'openapi') + assert.property(docs, 'swagger') + assert.property(docs, 'llms') + assert.property(docs, 'agent') + + assert.isString(docs.openapi.openapi) + assert.equal(docs.swagger.swagger, '2.0') + assert.isAbove(Object.keys(docs.openapi.paths).length, 0) + + const hasV6Path = Object.keys(docs.openapi.paths).some(path => path.startsWith('/v6/')) + assert.isTrue(hasV6Path) + }) +}) diff --git a/test/unit/controllers/discovery-router-unit.js b/test/unit/controllers/discovery-router-unit.js new file mode 100644 index 0000000..b682f7c --- /dev/null +++ b/test/unit/controllers/discovery-router-unit.js @@ -0,0 +1,43 @@ +/* + Unit tests for DiscoveryRouter. +*/ + +import { assert } from 'chai' + +import DiscoveryRouter from '../../../src/controllers/discovery/router.js' + +describe('#discovery-router.js', () => { + it('should require app object in attach()', () => { + const uut = new DiscoveryRouter() + assert.throws(() => uut.attach(), /Must pass app object/) + }) + + it('should register all discovery routes', () => { + const calls = [] + const app = { + use: () => {} + } + + const mockRouter = { + get: (path, handler) => calls.push({ path, handler }) + } + + const mockController = { + x402Manifest: () => {}, + openapi: () => {}, + swagger: () => {}, + llmsTxt: () => {}, + agentManifest: () => {} + } + + const uut = new DiscoveryRouter({ controller: mockController }) + uut.router = mockRouter + uut.attach(app) + + assert.equal(calls.length, 5) + assert.deepEqual( + calls.map(x => x.path), + ['/.well-known/x402', '/openapi.json', '/swagger.json', '/llms.txt', '/.well-known/agent.json'] + ) + }) +})