@xeplr/base-apis 3.0.0 → 3.0.2

package/README.md

@@ -80,8 +80,10 @@ createApp(3000, 'myapp', {
 | option | |
 |---|---|
 | `requiredEnv` | variable names; any missing → message and `process.exit(1)` before anything starts |
+| `host` | the address to listen on, e.g. `'127.0.0.1'` for a service that only nginx on the same machine may reach. Default: every address |
 | `auth` | the gate — see below. **On when omitted** |
 | `middleware` | array, mounted after the gate |
+| `rawBodyPaths` | path prefixes whose body is also kept byte for byte as `req.rawBody` (a `Buffer`) — see below |
 | `routes` | `{ '/path': router }` |
 | `log` | `@xeplr/logs` settings (`logDir` `'./logs'`, `fatalThreshold`, `emailThreshold`, `emailTo`, `emailService`), or `false` |
 | `corsOptions` | passed to `cors` (default: allow all) |
@@ -94,7 +96,7 @@ createApp(3000, 'myapp', {
 ### Order of the middleware
 
 1. request logger (`@xeplr/logs` — sets `req.log`), unless `log: false`
-2. view engine, `cors`, `express.json`, `express.urlencoded`, `cookie-parser`
+2. view engine, `cors`, `express.json`, `express.urlencoded` (and the raw body, for `rawBodyPaths`), `cookie-parser`
 3. `staticDir`
 4. uploaded files served at `upload.serveRoute` — **before the gate, so public**
 5. **the auth gate**
@@ -104,6 +106,23 @@ createApp(3000, 'myapp', {
 9. `options.routes`
 10. 404, then the error handler
 
+### Webhooks: the raw body
+
+A payment provider (Stripe, Razorpay…) signs **the bytes it sent**, and `req.body` is those bytes parsed. `JSON.stringify(req.body)` is not them — spacing, key order and `1.50` vs `1.5` all change — so a signature checked against it fails, or worse, gets "fixed" by skipping the check. Name the webhook paths and they also get the bytes:
+
+```js
+createApp(3000, 'myapp', {
+  auth: { publicPaths: ['/billing/webhook/'] },   // a provider cannot sign in
+  rawBodyPaths: ['/billing/webhook/'],           // so it must be checked by signature, over these
+  routes
+})
+// in the route: hmac(secret).update(req.rawBody) === req.headers['x-signature']
+```
+
+- JSON and form bodies are still parsed into `req.body`; any other type (`text/plain`, `application/octet-stream`) is read only into `req.rawBody`.
+- Only the paths named: every other request keeps just its parsed body, not a second copy.
+- A prefix, matched like `publicPaths`.
+
 ### The auth gate
 
 | `auth` | result |
@@ -283,7 +302,7 @@ broadcast({ type: 'cache-clear' })   // from a worker: relayed to every other wo
 npm test
 ```
 
-The auth gate against a stand-in auth service (refusal to boot, 401 / 503, public paths, caching, `X-New-Token`), SSE publish and subscribe, and ticket-authorised SSE. `tenant-gate.test.js`: the gate naming the company and workspace, refusing a non-member before the app sees the request, refusing an auth that did not check, caching per company; a real multipart upload landing in the company's own `uploads/` and served back only to it; `createApp`'s uploads no longer public; `sendTenantFile` refusing another company's name, a path out and no tenant.
+The auth gate against a stand-in auth service (refusal to boot, 401 / 503, public paths, caching, `X-New-Token`), SSE publish and subscribe, and ticket-authorised SSE. `tenant-gate.test.js`: the gate naming the company and workspace, refusing a non-member before the app sees the request, refusing an auth that did not check, caching per company; a real multipart upload landing in the company's own `uploads/` and served back only to it; `createApp`'s uploads no longer public; `sendTenantFile` refusing another company's name, a path out and no tenant. `raw-body.test.js`: a `rawBodyPaths` route gets the exact bytes a provider signed (JSON, form and other types), and every other path does not.
 
 ## License
 

package/express.js

@@ -14,6 +14,8 @@ var logs = require('@xeplr/logs');
  * @param {string}        appName    - Service name (used for debug namespace and console logs)
  * @param {object}        [options]  - Configuration options
  * @param {string[]}      [options.requiredEnv]   - Mandatory env var names; missing ones abort startup
+ * @param {string}        [options.host]          - The address to listen on, e.g. '127.0.0.1' for a service only a
+ *   proxy on the same machine may reach. Default: every address (Node's own default).
  * @param {object}        [options.routes]        - Route map: { '/path': router }
  * @param {object|false}  [options.auth]          - THE GATE, ON BY DEFAULT.
  *   Omit it and every route requires a valid token, validated by asking the
@@ -25,6 +27,9 @@ var logs = require('@xeplr/logs');
  *     { middleware }     supply your own gate instead of the HTTP one
  *     false              this service is public ON PURPOSE
  * @param {Function[]}    [options.middleware]     - Middleware to apply before routes (runs AFTER the auth gate)
+ * @param {string[]}      [options.rawBodyPaths]  - Path prefixes whose body is also kept, byte for byte, as
+ *   req.rawBody (a Buffer) — what a webhook's signature is computed over. JSON and form
+ *   bodies are still parsed into req.body; any other type is read only as req.rawBody.
  * @param {object}        [options.views]         - { engine: 'pug', dir: '/abs/path' }
  * @param {string}        [options.staticDir]     - Path to static files directory
  * @param {string}        [options.corsOptions]   - Custom CORS options (default: allow all)
@@ -77,8 +82,32 @@ function createApp(port, appName, options) {
 
   // ── Standard middleware ──
   app.use(cors(options.corsOptions));
-  app.use(express.json());
-  app.use(express.urlencoded({ extended: false }));
+  // A webhook signs the bytes it sent, and req.body is those bytes parsed:
+  // JSON.stringify(req.body) is not them (spacing, key order, number
+  // formatting). So a rawBodyPaths route also gets the bytes, as req.rawBody.
+  // Only for the paths named — every other request keeps just its parsed body.
+  var rawBodyPaths = options.rawBodyPaths || [];
+  function keepsRaw(req) {
+    for (var i = 0; i < rawBodyPaths.length; i++) {
+      if (req.path === rawBodyPaths[i] || req.path.indexOf(rawBodyPaths[i]) === 0) return true;
+    }
+    return false;
+  }
+  function keepRaw(req, res, buf) { if (keepsRaw(req)) req.rawBody = buf; }
+  var verify = rawBodyPaths.length ? keepRaw : undefined;
+  app.use(express.json({ verify: verify }));
+  app.use(express.urlencoded({ extended: false, verify: verify }));
+  if (rawBodyPaths.length) {
+    // A type neither parser reads (text/plain, application/octet-stream…).
+    var rawParser = express.raw({ type: function () { return true; } });
+    app.use(function (req, res, next) {
+      if (req.rawBody || !keepsRaw(req)) return next();
+      rawParser(req, res, function (err) {
+        if (!err && Buffer.isBuffer(req.body)) req.rawBody = req.body;
+        next(err);
+      });
+    });
+  }
   app.use(cookieParser());
 
   // ── Static files ──
@@ -224,7 +253,7 @@ function createApp(port, appName, options) {
 
   // ── Start HTTP server ──
   app.set('port', port);
-  var server = createServer(app, port, appName);
+  var server = createServer(app, port, appName, options.host);
 
   return { app: app, server: server };
 }

package/lib/server.js

@@ -7,12 +7,14 @@ function normalizePort(val) {
   return false;
 }
 
-function createServer(handler, port, name) {
+function createServer(handler, port, name, host) {
   const dbg = require('debug')('architects:' + name);
   const normalizedPort = normalizePort(port);
 
   const server = http.createServer(handler);
-  server.listen(normalizedPort);
+  // A host only for a port: a named pipe has none.
+  if (host && typeof normalizedPort === 'number') server.listen(normalizedPort, host);
+  else server.listen(normalizedPort);
 
   server.on('error', function onError(error) {
     if (error.syscall !== 'listen') throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/base-apis",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Base API bootstrapper — Express and plain HTTP server factories with middleware injection",
   "main": "index.js",
   "bin": {