@xeplr/base-apis 2.0.6 → 3.0.0

package/README.md

@@ -67,7 +67,8 @@ createApp(3000, 'myapp', {
 | `remoteAuth(config)` | the default gate, as middleware |
 | `gateRequiredEnv` | `['AUTH_URL']` |
 | `checkEnv(names, options)` | missing-variable check |
-| `uploadRoute(options)` | a standalone "receive a file, return its path" router |
+| `uploadRoute(options)` | a standalone "receive a file, return its path" router — into the requester's own `uploads/` unless told otherwise |
+| `sendTenantFile(res, name, { download? })` | serve a stored file back, only from the requesting tenant's own folder (404 another company's name, 400 a path out, 400 no tenant) |
 | `sse` | `{ handler, createHandler, publish, defaultAuthorizeTopics }` |
 | `runCluster(options)`, `broadcast(msg)`, `isPrimary()`, `isWorker()` | Node cluster helpers |
 | `createHttpServer` | `{ init(port, appName, handler) }` — a plain `http.Server` |
@@ -116,24 +117,27 @@ Why on by default: a service that forgot to configure auth used to boot clean, p
 
 `remoteAuth` sends the caller's `Authorization: Bearer …` **and the request it is serving** (`x-verify-method`, `x-verify-path`) to `url + endpoint` (`/auth/api/verify`). Auth answers who the caller is and whether they may call that API, so **every request is checked for access, not only for a signed-in token**; the answer's `user` and `access` go on `req.user` / `req.access`. See `@xeplr/auth`'s "Every request is checked".
 
+**And whether the caller belongs to the company and workspace the request names.** When the app registered tenancy (`@xeplr/db`'s `registerMTs`) and the request carries those headers, the gate sends them as `x-verify-tenant` (`{"l1":"<company>","l2":"<workspace>"}`), and auth refuses a caller without a membership for each (`403 NOT_A_MEMBER`, Super Admin excepted) — before the app sees the request. So `mtMiddleware`'s tenant, which every query and every file path (`@xeplr/db`'s `dataDir`) reads, can be trusted on every request of every app, and no route has to add `mtMembershipMiddleware` itself. An auth that does not answer `tenant: 'checked'` (older than `@xeplr/auth` 1.4) is refused (503), never taken as a member.
+
 | situation | response |
 |---|---|
 | path starts with a `publicPaths` entry | skipped |
 | no `Bearer` token | 401 `No token provided` |
-| auth answers `403` with `code` `DISABLED`, `HIDDEN` or `UNLICENSED` | 403 with that `code`: signed in, but not allowed this API (`UNLICENSED`: its module is not in the caller's licence) |
+| auth answers `403` with `code` `DISABLED`, `HIDDEN`, `UNLICENSED` or `NOT_A_MEMBER` | 403 with that `code`: signed in, but not allowed this API (`UNLICENSED`: its module is not in the caller's licence; `NOT_A_MEMBER`: not in the company or workspace the request names) |
+| the request names a company, and auth answers without `tenant: 'checked'` | **503**: an auth that ignored the question is not an answer |
 | auth answers 401 / other 403 | same status, `Invalid or expired token` |
 | auth answers 200 **without** `state: 'enabled'` (an older auth, or an `endpoint` such as `/me` that only says who the caller is) | **503**: "did not say no" is not "said yes" |
 | auth unreachable, times out (`timeoutMs`, 5000), answers anything else, or answers non-JSON | **503 `Authentication service unavailable` — never let through** |
 
 - **Validated over HTTP, not in-process** — so a service needs no `@xeplr/auth` dependency (it would be a cycle), no JWT secret and no Redis. The cost is a hop per request.
 - **A burst makes one call.** Requests with the same token, method and path that arrive while a check is on its way share its answer: ten at once, one call to auth. This holds with `cacheSeconds: 0` too.
-- **`cacheSeconds` (default 5)** caches each answer (allowed or refused) per token, method and path, per process; a revoked token or a changed mapping takes that long to reach here. `0` checks every request.
+- **`cacheSeconds` (default 5)** caches each answer (allowed or refused) per token, method, path **and company named**, per process — another company with the same token is asked about afresh; a revoked token or a changed mapping takes that long to reach here. `0` checks every request.
 - **`X-New-Token` is forwarded** (with `Access-Control-Expose-Headers`) when the auth service slides a token, to every request in the burst that shared the check, so none is rejected because the token changed. That answer is **not cached** — otherwise the next requests would be answered from memory without telling the client to switch, and it would be logged out when the window closed.
 
 ### Uploads
 
 ```js
-createApp(port, 'myapp', { upload: { destination: './uploads', allowedTypes: ['image/*'], maxSize: 2e6 } })
+createApp(port, 'myapp', { upload: { allowedTypes: ['image/*'], maxSize: 2e6 } })
 ```
 
 | option | default |
@@ -141,15 +145,19 @@ createApp(port, 'myapp', { upload: { destination: './uploads', allowedTypes: ['i
 | `route` | `/internal/upload` — `POST`, multipart, behind the gate |
 | `fieldName` | `file` |
 | `maxFiles` | `10` |
-| `destination` | `UPLOAD_DIR`, else `./uploads` |
+| `destination` | **the requester's own `uploads/`** under `XEPLR_DATA_DIR` (`@xeplr/db`'s `dataDir`), asked per upload — never one folder for every company. A request with no tenant is refused. A folder named here is the app's own, and the app serves it |
 | `allowedTypes` | `['*']` |
 | `maxSize` | `5242880` (5 MB) |
-| `serveRoute` | `/uploads` — static, **before the gate** |
+| `serveRoute` | `/uploads` — `GET /uploads/:name`, **behind the gate**, from the requester's own `uploads/` (`sendTenantFile`). It used to be `express.static` over the whole folder before the gate: every company's files to anyone with a name. Only with the default `destination` |
 | `auth` | a function passed to `@xeplr/utils`' `FileUploader` |
 
 Returns `{ filename, originalName, size, mimetype }`, or an array of them for several files; 400 when none arrived. Files are stored under a generated id plus the original extension.
 
-`uploadRoute({ destination, maxSize, allowedTypes, fieldName, auth })` is the same as a router of its own: `POST /` (single file) → `{ filePath, fileName, originalName, size, mimetype }`.
+`uploadRoute({ destination, maxSize, allowedTypes, fieldName, auth })` is the same as a router of its own: `POST /` (single file) → `{ filePath, fileName, originalName, size, mimetype }`. With no `destination`, into the requester's own `uploads/`.
+
+**Serving a stored file back:** `sendTenantFile(res, 'uploads/' + name)` — the one way. It reads only the requesting tenant's own folder: another company's name is 404, a path out (`../`, a link, a full path elsewhere) is 400, a request with no tenant is 400. Never `express.static` over a shared folder.
+
+**From 2.x (3.0.0):** an upload with no folder named goes into the requester's own folder (it was `UPLOAD_DIR` / `./uploads`, shared), and `createApp`'s uploads are no longer served before the gate. Set `XEPLR_DATA_DIR` (`@xeplr/db`'s `dataRequiredEnv`) and register the application (`registerApplication`).
 
 ## genericRoute
 
@@ -266,7 +274,7 @@ broadcast({ type: 'cache-clear' })   // from a worker: relayed to every other wo
 | variable | |
 |---|---|
 | `AUTH_URL` | the auth service base URL — **required** for the default gate |
-| `UPLOAD_DIR` | upload destination when `upload.destination` is not given |
+| `XEPLR_DATA_DIR` | the root of every tenant's files: an upload with no folder named goes in the requester's `uploads/` under it (`@xeplr/db` `dataRequiredEnv`) |
 | `NODE_ENV` | anything but `production` puts the logger in dev mode |
 
 ## Tests
@@ -275,7 +283,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.
+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.
 
 ## License
 

package/express.js

@@ -37,12 +37,12 @@ var logs = require('@xeplr/logs');
  * @param {object}        [options.log.emailService]           - Email service instance
  * @param {object}        [options.upload]        - File upload config
  * @param {string}        [options.upload.route='/internal/upload'] - Upload endpoint path
- * @param {string}        [options.upload.destination='./uploads']  - Storage directory
+ * @param {string}        [options.upload.destination]              - A folder of the app's own; default: the requester's own uploads/ under XEPLR_DATA_DIR
  * @param {string[]}      [options.upload.allowedTypes=['*']]       - MIME types
  * @param {number}        [options.upload.maxSize=5242880]          - Max file size in bytes
  * @param {string}        [options.upload.fieldName='file']         - Form field name
  * @param {number}        [options.upload.maxFiles=10]              - Max files per request
- * @param {string}        [options.upload.serveRoute='/uploads']    - Static serve path for uploaded files
+ * @param {string}        [options.upload.serveRoute='/uploads']    - Where an upload is fetched back, signed in, from the requester's own uploads/ (default destination only)
  * @returns {{ app: Express, server: http.Server }}
  */
 function createApp(port, appName, options) {
@@ -86,13 +86,6 @@ function createApp(port, appName, options) {
     app.use(express.static(options.staticDir));
   }
 
-  // ── File upload (static serve before auth, upload route after auth) ──
-  if (options.upload) {
-    var serveRoute = options.upload.serveRoute || '/uploads';
-    var destination = path.resolve(options.upload.destination || process.env.UPLOAD_DIR || './uploads');
-    app.use(serveRoute, express.static(destination));
-  }
-
   // ── Auth gate ──
   //
   // ON BY DEFAULT. A service that forgets to configure auth must not answer
@@ -146,7 +139,10 @@ function createApp(port, appName, options) {
   if (options.upload) {
     var FileUploader = require('@xeplr/utils').FileUploader;
     var uploadCfg = options.upload;
-    var destination = path.resolve(uploadCfg.destination || process.env.UPLOAD_DIR || './uploads');
+    // Named: that folder. Not named: the requesting tenant's own uploads/
+    // under XEPLR_DATA_DIR, asked per upload — never one folder for every
+    // company (lib/uploadRoute.js tenantUploads).
+    var destination = uploadCfg.destination ? path.resolve(uploadCfg.destination) : require('./lib/uploadRoute').tenantUploads;
     var uploader = new FileUploader({
       auth: uploadCfg.auth || null,
       allowedTypes: uploadCfg.allowedTypes || ['*'],
@@ -158,6 +154,17 @@ function createApp(port, appName, options) {
     var fieldName = uploadCfg.fieldName || 'file';
     var maxFiles = uploadCfg.maxFiles || 10;
 
+    // SERVED BACK SIGNED IN, from the requester's own uploads/ only. This was
+    // express.static over the whole folder, BEFORE the gate: every company's
+    // files to anyone who had a name. Now behind the gate (which checks the
+    // caller belongs to the company named) and read in that company's folder.
+    // With a folder of the app's own (`destination`), the app serves it.
+    if (!uploadCfg.destination) {
+      var serveRoute = uploadCfg.serveRoute || '/uploads';
+      var sendTenantFile = require('./lib/sendTenantFile');
+      app.get(serveRoute + '/:name', function(req, res) { sendTenantFile(res, 'uploads/' + req.params.name); });
+    }
+
     app.post(uploadRoute, uploader.array(fieldName, maxFiles), function(req, res) {
       if (!req.files || req.files.length === 0) {
         return res.status(400).json({ error: 'No files uploaded' });

package/index.js

@@ -15,6 +15,8 @@ module.exports = {
   remoteAuth: require('./lib/remoteAuth'),
   genericController: require('./lib/genericController'),
   uploadRoute: require('./lib/uploadRoute'),
+  // Serve a stored file back, only from the requesting tenant's own folder.
+  sendTenantFile: require('./lib/sendTenantFile'),
   runCluster: require('./lib/cluster').runCluster,
   broadcast: require('./lib/cluster').broadcast,
   isPrimary: require('./lib/cluster').isPrimary,

package/lib/remoteAuth.js

@@ -37,7 +37,33 @@ var DEFAULT_TIMEOUT_MS = 5000;
 // The 403 codes auth gives for a signed-in caller this API is refused to. Any
 // other 403 is a token problem. UNLICENSED: the API's module is not in the
 // caller's licence (@xeplr/auth's licence.use).
-var REFUSALS = ['DISABLED', 'HIDDEN', 'UNLICENSED'];
+// NOT_A_MEMBER: the request names a company or workspace the caller does not
+// belong to (see tenantOf).
+var REFUSALS = ['DISABLED', 'HIDDEN', 'UNLICENSED', 'NOT_A_MEMBER'];
+var LEVELS = ['l1', 'l2', 'l3', 'l4'];
+
+/**
+ * THE COMPANY AND WORKSPACE THIS REQUEST NAMES, for auth to check membership
+ * of — in this gate, so it is checked for every request of every app built on
+ * createApp, and no route can forget it (@xeplr/db's mtMiddleware would
+ * otherwise trust whatever the header says). By level, as auth keeps
+ * memberships: '{"l1":"<company>","l2":"<workspace>"}', or null when the app
+ * registered no tenancy or the request names none. Read from the app's own
+ * registerMTs(), per request.
+ */
+function tenantOf(req) {
+  var mt;
+  try { mt = require('@xeplr/db').getMtConfig(); } catch (e) { return null; }
+  if (!mt || !mt.enabled) return null;
+  var named = {};
+  var any = false;
+  LEVELS.forEach(function (level) {
+    var slot = mt.slots && mt.slots[level];
+    var value = slot && req.headers[slot.header];
+    if (value) { named[level] = String(value); any = true; }
+  });
+  return any ? JSON.stringify(named) : null;
+}
 
 /**
  * @param {object} config
@@ -99,11 +125,13 @@ function remoteAuth(config) {
   }
 
   // One call to auth → an outcome every waiter can apply.
-  async function ask(header, method, path) {
+  async function ask(header, method, path, tenant) {
     var response;
+    var headers = { authorization: header, 'x-verify-method': method, 'x-verify-path': path };
+    if (tenant) headers['x-verify-tenant'] = tenant;
     try {
       response = await fetch(url + endpoint, {
-        headers: { authorization: header, 'x-verify-method': method, 'x-verify-path': path },
+        headers: headers,
         signal: AbortSignal.timeout(timeoutMs)
       });
     } catch (err) {
@@ -153,6 +181,12 @@ function remoteAuth(config) {
     if (!body || body.state !== 'enabled') {
       return { kind: 'unavailable', why: 'auth answered without an access state; update @xeplr/auth' };
     }
+    // Asked about a company and not told it was checked: an older auth that
+    // ignored the question. Refused for the same reason — "did not say no" is
+    // not "is a member".
+    if (tenant && body.tenant !== 'checked') {
+      return { kind: 'unavailable', why: 'auth did not check membership of the company named; update @xeplr/auth to 1.4 or later' };
+    }
 
     return { kind: 'ok', newToken: newToken, user: body.user, access: body.access };
   }
@@ -188,7 +222,10 @@ function remoteAuth(config) {
     var token = header.slice('Bearer '.length);
     var method = req.method;
     var path = (req.baseUrl || '') + req.path;
-    var key = token + '\n' + method + ' ' + path;
+    var tenant = tenantOf(req);
+    // The answer is about this token, this request AND this company: another
+    // company named with the same token is asked about afresh.
+    var key = token + '\n' + method + ' ' + path + '\n' + (tenant || '');
 
     if (cacheSeconds > 0) {
       var hit = cache.get(key);
@@ -197,7 +234,7 @@ function remoteAuth(config) {
 
     var inFlight = pending.get(key);
     if (!inFlight) {
-      inFlight = ask(header, method, path);
+      inFlight = ask(header, method, path, tenant);
       pending.set(key, inFlight);
       inFlight.then(function (outcome) {
         pending.delete(key);
@@ -220,3 +257,4 @@ function remoteAuth(config) {
 }
 
 module.exports = remoteAuth;
+module.exports.tenantOf = tenantOf;

package/lib/sendTenantFile.js

@@ -0,0 +1,35 @@
+// SEND A FILE BACK — only from the requesting tenant's own folder.
+//
+// The one way an app serves a stored file: the name is resolved inside the
+// tenant's folder under XEPLR_DATA_DIR (@xeplr/db's dataDir), so another
+// company's name finds nothing here, and a path that climbs out (../, a link,
+// an absolute path elsewhere) is refused before anything is opened. The
+// tenant is the request's, checked by the gate (createApp asks auth whether
+// the caller belongs to it) — never what the client names.
+//
+//   router.get('/files/:name', function(req, res) { sendTenantFile(res, 'uploads/' + req.params.name); });
+//
+// 404 when there is nothing there; 400 when the name is not one in the
+// tenant's folder. Never express.static over a shared folder.
+var fs = require('fs');
+
+/**
+ * @param res      the Express response
+ * @param name     a name in the tenant's folder, e.g. 'report-assets/logo.png'
+ * @param options  { download: true | '<file name>' } to send as an attachment
+ */
+function sendTenantFile(res, name, options) {
+  options = options || {};
+  var file;
+  try {
+    file = require('@xeplr/db').dataDir.resolve(String(name || ''), 'The file');
+  } catch (err) {
+    var status = err.code === 'DATA_DIR_UNSET' ? 500 : 400;
+    return res.status(status).json({ error: status === 500 ? 'Files are not set up on this server' : err.message, code: err.code });
+  }
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return res.status(404).json({ error: 'No such file' });
+  if (options.download) return res.download(file, options.download === true ? undefined : options.download);
+  return res.sendFile(file);
+}
+
+module.exports = sendTenantFile;

package/lib/uploadRoute.js

@@ -18,7 +18,10 @@ var FileUploader = require('@xeplr/utils/lib/fileUploader');
  *     → { filePath, fileName, originalName, size, mimetype }
  *
  * @param {object} [options]
- * @param {string} [options.destination='./uploads'] - disk directory to store uploaded files
+ * @param {string|Function} [options.destination] - where to keep the file: a
+ *   folder, or (req) => folder. DEFAULT: the requesting tenant's own
+ *   `uploads/` folder under XEPLR_DATA_DIR (@xeplr/db's dataDir) — never one
+ *   folder for every company. A request with no tenant is refused.
  * @param {number} [options.maxSize=5MB]
  * @param {string[]} [options.allowedTypes=['*']]
  * @param {string} [options.fieldName='file']
@@ -31,7 +34,7 @@ function uploadRoute(options) {
   var fieldName = options.fieldName || 'file';
 
   var uploader = new FileUploader({
-    destination: options.destination,
+    destination: options.destination || tenantUploads,
     maxSize: options.maxSize,
     allowedTypes: options.allowedTypes
   });
@@ -53,4 +56,10 @@ function uploadRoute(options) {
   return router;
 }
 
+/** The requesting tenant's uploads/ — asked per upload, inside its context. */
+function tenantUploads() {
+  return require('@xeplr/db').dataDir.resolve('uploads', 'The uploads folder');
+}
+
 module.exports = uploadRoute;
+module.exports.tenantUploads = tenantUploads;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/base-apis",
-  "version": "2.0.6",
+  "version": "3.0.0",
   "description": "Base API bootstrapper — Express and plain HTTP server factories with middleware injection",
   "main": "index.js",
   "bin": {
@@ -31,23 +31,31 @@
     "access": "public"
   },
   "dependencies": {
+    "@xeplr/logs": "^1.0.0",
+    "@xeplr/utils": "^1.1.0",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.6",
     "debug": "^4.4.3",
-    "http-errors": "^2.0.1",
-    "@xeplr/logs": "^1.0.0",
-    "@xeplr/utils": "^1.0.0"
+    "http-errors": "^2.0.1"
   },
   "peerDependencies": {
+    "@xeplr/db": "^1.1.0",
     "express": "^4.0.0 || ^5.0.0",
     "multer": "^2.3.0"
   },
   "peerDependenciesMeta": {
     "multer": {
       "optional": true
+    },
+    "@xeplr/db": {
+      "optional": true
     }
   },
   "scripts": {
     "test": "node --test test/*.test.js"
+  },
+  "devDependencies": {
+    "@xeplr/db": "^1.1.0",
+    "multer": "^2.5.0"
   }
 }