@_linked/server 2.20.0 → 2.21.0

package/lib/esm/shapes/LinkedServer.js

@@ -26,6 +26,7 @@ import { JSONWriter } from '@_linked/server-utils/utils/JSONWriter';
 import { Server } from '@_linked/server-utils/utils/Server';
 import { ServerCallError } from '@_linked/server-utils/utils/ServerCallError';
 import { ShapeProvider } from '@_linked/server-utils/utils/ShapeProvider';
+import { getCallContext, httpCallContext, runAsSystem, runInHttpContext, runWithCallContext, } from '@_linked/server-utils/utils/CallContext';
 import { Shape } from '@_linked/core/shapes/Shape';
 import { LinkedErrorLogging } from '@_linked/core/utils/LinkedErrorLogging';
 import { FileStorePurposes, LinkedFileStorage, } from '@_linked/core/utils/LinkedFileStorage';
@@ -114,6 +115,7 @@ import { indexShapesIntoMemory } from '../utils/Shapes.js';
 import { materializeShapes } from '../utils/syncShapes.js';
 import { installSpaFallback, repinSpaFallback, } from '../utils/spaFallback.js';
 import { LincdAPI } from './LincdAPI.js';
+import { getRpcExposureMode, isGenericRpcDisabled, logSafe, resolveCallable, setRpcExposureMode, warnUndeclaredCall, } from '../utils/rpcExposure.js';
 //prevent errors in node.js when (s)css files are imported in js
 const isProduction = process.env.NODE_ENV === 'production';
 const isDevelopment = process.env.NODE_ENV === 'development';
@@ -148,6 +150,48 @@ events.EventEmitter.prototype.setMaxListeners(500);
 // global['document'] = document;
 global['reactStaticRenderer'] = renderToStaticMarkup;
 autoLoadOntologyData(true);
+/**
+ * How RPC arguments treat a `{__sc}` (live Shape class) marker. No call takes a
+ * Shape class from the client: logged in 'warn', refused (400) in 'enforce'.
+ */
+function rpcShapeClassRevival() {
+    return getRpcExposureMode() === 'enforce' ? 'reject' : 'warn';
+}
+/**
+ * Serve the local upload folder at `/uploads` (where `LocalFileStore` files are
+ * reachable), with the headers for untrusted files.
+ */
+export function mountUploads(app, folder = './data/uploads', maxAge = 1000 * 60 * 60 * 24 * 365) {
+    app.use('/uploads', express.static(folder, {
+        maxAge, // cache for a long time
+        immutable: true, // Suggest that the content won't change
+        // uploaded files are user content: never sniffed, never run as a page
+        setHeaders: setUntrustedFileHeaders,
+    }));
+}
+/**
+ * Express middleware: run the rest of the chain in the request's http context.
+ * `LinkedServer.start` installs it first, and again right after the JSON body
+ * parser (whose stream callbacks do not carry the context).
+ */
+export function enterRequestContext(req, res, next) {
+    runInHttpContext(req, res, next);
+}
+/**
+ * Headers for files users uploaded (`/uploads`, resized copies): the browser
+ * must not guess a type from the bytes, and a document served from them runs
+ * sandboxed (no scripts, an opaque origin), so an uploaded HTML or SVG file
+ * cannot act on the app's origin.
+ */
+export function setUntrustedFileHeaders(res) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Content-Security-Policy', 'sandbox');
+}
+/** Whether the current HTTP call carries a session. */
+function hasSession(request) {
+    var _a;
+    return !!((_a = request === null || request === void 0 ? void 0 : request.linkedAuth) === null || _a === void 0 ? void 0 : _a.userAccount);
+}
 // Named explicitly: tsc emits `let X = class X`, and any later esbuild pass over that JS (Vite's
 // SSR `define` replacement runs one on every file mentioning a defined `process.env.*`) renames
 // the inner binding to `X2`, which would otherwise become this shape's IRI.
@@ -366,8 +410,10 @@ let LinkedServer = class LinkedServer extends Shape {
         setTimeout(() => process.exit(1), 1000).unref();
     }
     async startBoot() {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f;
         this.initPackage();
+        // 'warn' (default) or 'enforce'; see utils/rpcExposure.
+        setRpcExposureMode((_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.server) === null || _b === void 0 ? void 0 : _b.rpcExposure);
         // Static assets should come from the static store URL (versioned path),
         // not the upload store URL. An explicit STATIC_ACCESS_URL still wins;
         // otherwise the release manifest `linked build-app` wrote next to the
@@ -396,7 +442,7 @@ let LinkedServer = class LinkedServer extends Shape {
         // one left on disk by an earlier `vite build` would otherwise swap in
         // stale built CSS while Vite serves the live styles.
         const servingMode = resolveViteServingMode({
-            viteConfig: (_a = this.config.server) === null || _a === void 0 ? void 0 : _a.vite,
+            viteConfig: (_c = this.config.server) === null || _c === void 0 ? void 0 : _c.vite,
             nodeEnv: process.env.NODE_ENV,
             readManifest: () => {
                 try {
@@ -422,7 +468,7 @@ let LinkedServer = class LinkedServer extends Shape {
                 this.assets['main.js'] = staticAsset(`/bundles/${mainEntry.file}`);
                 this.mainEntryIsModule = true;
             }
-            if ((_b = mainEntry === null || mainEntry === void 0 ? void 0 : mainEntry.css) === null || _b === void 0 ? void 0 : _b[0]) {
+            if ((_d = mainEntry === null || mainEntry === void 0 ? void 0 : mainEntry.css) === null || _d === void 0 ? void 0 : _d[0]) {
                 this.assets['main.css'] = staticAsset(`/bundles/${mainEntry.css[0]}`);
             }
         }
@@ -461,8 +507,15 @@ let LinkedServer = class LinkedServer extends Shape {
         //   origin: ['http://localhost:4001', 'https://www.mynd.site'],
         //   optionsSuccessStatus: 200, // some legacy browsers (IE11, various SmartTVs) choke on 204
         // };
+        // Every request runs in its own http call context, from the first layer
+        // on: no handler (middleware, routers, error handlers) ever runs without
+        // one. The context is kept on the request, so a layer that resumes from a
+        // callback that lost it (a body parser's stream events) re-enters the same
+        // one below.
+        this.server.use(enterRequestContext);
         //accept JSON bodies
         this.server.use(createJsonBodyParser());
+        this.server.use(enterRequestContext);
         // this.server.use(cors(corsOptions));
         //
         // //compress server output with gzip,
@@ -473,7 +526,7 @@ let LinkedServer = class LinkedServer extends Shape {
         // (`linked start --vite`), the orchestrator passes the Vite handle
         // through config.server.viteMiddleware. We mount it and skip the
         // entire webpack-dev-middleware setup below.
-        const viteMiddleware = (_c = this.config.server) === null || _c === void 0 ? void 0 : _c.viteMiddleware;
+        const viteMiddleware = (_e = this.config.server) === null || _e === void 0 ? void 0 : _e.viteMiddleware;
         if (viteMiddleware) {
             this.server.use(viteMiddleware);
         }
@@ -490,10 +543,7 @@ let LinkedServer = class LinkedServer extends Shape {
             maxAge: oneYear, // Tell browser to cache for 1 year
             immutable: true, // Suggest that the content won't change
         }));
-        this.server.use('/uploads', express.static('./data/uploads', {
-            maxAge: oneYear, // Tell browser to cache for 1 year
-            immutable: true, // Suggest that the content won't change
-        }));
+        mountUploads(this.server, './data/uploads', oneYear);
         this.server.use('/', express.static('./public/root'));
         this.server.use('/favicon.ico', express.static('./public/favicon.ico', {
             maxAge: oneMonth, // Tell browser to cache for 1 year
@@ -504,25 +554,7 @@ let LinkedServer = class LinkedServer extends Shape {
         this.server.get('/resized/*', async (req, res) => {
             this.resizeImage(req, res);
         });
-        // Scoped-package variants (@scope/pkg). Register BEFORE the unscoped
-        // routes — Express `:pkg` won't consume slashes, so a call to
-        // `/call/@_linked/auth/signinDev` would otherwise fall through to the
-        // 3-segment `:pkg/:shape/:method` route and be misinterpreted as a
-        // shape-method call (pkg=`@_linked`, shape=`auth`). These handlers
-        // recognise the `@scope/pkg` prefix and rebuild the full package name
-        // before dispatching to the same handler used for unscoped packages.
-        this.server.post('/call/@:scope/:pkg/:method', this.handleErrorsJson(async (req, res) => {
-            req.params.pkg = `@${req.params.scope}/${req.params.pkg}`;
-            return this.processBackendMethodCall(req, res);
-        }));
-        this.server.post('/call/@:scope/:pkg/:shape/:method', this.handleErrorsJson(async (req, res) => {
-            req.params.pkg = `@${req.params.scope}/${req.params.pkg}`;
-            return this.processShapeMethodCall(req, res);
-        }));
-        this.server.post('/call/:pkg/:method', this.handleErrorsJson(async (req, res) => this.processBackendMethodCall(req, res)));
-        this.server.post('/call/:pkg/:shape/:method', this.handleErrorsJson(async (req, res) => this.processShapeMethodCall(req, res)));
-        this.server.post('/api/:method/:action?', this.handleErrorsJson(async (req, res) => this.processAPICall(req, res, 'post')));
-        this.server.get('/api/:method/:action?', this.handleErrorsJson(async (req, res) => this.processAPICall(req, res, 'get')));
+        registerCallRoutes(this.server, this);
         // this.server.post(
         //   '/api/query/:method',
         //   this.handleErrorsJson(async (req, res) => this.processQuery(req, res)),
@@ -580,7 +612,7 @@ let LinkedServer = class LinkedServer extends Shape {
         // answering them with the client shell at status 200.
         // An API-only backend (`linked start --api-only`) has no app to render:
         // without the catch-all, page requests get express's plain 404.
-        if (!((_d = this.config.server) === null || _d === void 0 ? void 0 : _d.apiOnly)) {
+        if (!((_f = this.config.server) === null || _f === void 0 ? void 0 : _f.apiOnly)) {
             this.installSpaFallback();
         }
         //remove http(s):// and remove port :[port]
@@ -806,7 +838,9 @@ let LinkedServer = class LinkedServer extends Shape {
         }
         let indexing = this.providerIndexing.get(pkg);
         if (!indexing) {
-            indexing = this.indexPackageBackendProviders(pkg, warnIfNotFound).then(() => undefined);
+            // Loading a package's providers runs their constructors and setup hooks.
+            // That is system work, even when the first call to the package triggers it.
+            indexing = runAsSystem(() => this.indexPackageBackendProviders(pkg, warnIfNotFound), 'loading backend providers of ' + pkg).then(() => undefined);
             this.providerIndexing.set(pkg, indexing);
         }
         try {
@@ -1098,6 +1132,7 @@ let LinkedServer = class LinkedServer extends Shape {
         catch (err) {
             console.warn('Could not cache resized image at ' + resizedKey + ': ' + err);
         }
+        setUntrustedFileHeaders(res);
         res.type(extension || 'bin').send(resized);
     }
     async indexLincdPackage(pkg, warnIfNotFound = false) {
@@ -1142,14 +1177,14 @@ let LinkedServer = class LinkedServer extends Shape {
             if (providerNotFound) {
                 // console.warn('Error loading ' + providerPath + ': ' + e.stack);
                 if (warnIfNotFound) {
-                    console.warn(paint('magenta', `Could not load package ${pkg}`, typeof module !== 'undefined' && typeof exports !== 'undefined'
+                    console.warn(paint('magenta', `Could not load package ${logSafe(pkg)}`, typeof module !== 'undefined' && typeof exports !== 'undefined'
                         ? //@ts-ignore
                             ' at ' + (await import.meta.resolve(pkg))
                         : ''));
                 }
             }
             else {
-                console.warn(paint('red', `Error loading '${pkg}' ${typeof module !== 'undefined' && typeof exports !== 'undefined'
+                console.warn(paint('red', `Error loading '${logSafe(pkg)}' ${typeof module !== 'undefined' && typeof exports !== 'undefined'
                     ? //@ts-ignore
                         ' at ' + (await import.meta.resolve(pkg))
                     : ''}: ${e.message}\n`), e.stack);
@@ -1239,7 +1274,7 @@ let LinkedServer = class LinkedServer extends Shape {
         }
         if (!load) {
             if (warnIfNotFound) {
-                console.warn(paint('magenta', `Could not find backend file of package ${pkg}. 
+                console.warn(paint('magenta', `Could not find backend file of package ${logSafe(pkg)}. 
         Check:\n
           - Make sure backend.ts exists and is included in tsconfig.json\n
           - Make sure the package name in src/package.ts matches the package name in package.json`));
@@ -1267,12 +1302,12 @@ let LinkedServer = class LinkedServer extends Shape {
                     if (isShapeProvider(provider)) {
                         shapeProviders.push(provider);
                         if (!Object.getOwnPropertyNames(provider).includes('shape')) {
-                            console.warn(paint('red', `${Object.getPrototypeOf(provider).constructor.name} in package ${pkg}
+                            console.warn(paint('red', `${Object.getPrototypeOf(provider).constructor.name} in package ${logSafe(pkg)}
                is not properly linked to a shape. Use public shape = SomeShape.`));
                         }
                     }
                     else if (genericBackendProvider) {
-                        console.warn(`Package ${pkg} exports two generic backend providers. Only one will work`);
+                        console.warn(`Package ${logSafe(pkg)} exports two generic backend providers. Only one will work`);
                     }
                     else {
                         genericBackendProvider = provider;
@@ -1365,23 +1400,29 @@ let LinkedServer = class LinkedServer extends Shape {
         repinSpaFallback(this.server);
     }
     async processBackendMethodCall(request, response) {
-        this.noCache(response);
-        await this.initRequest(request, response);
-        let { pkg, method } = request.params;
-        let { args } = JSONParser.parseObject(request.body);
-        return this.callBackendMethod(pkg, method, args, request, response).then((result) => {
-            //some methods of backend providers may choose to work with request/response directly and will not return anything
-            //so only if a result is returned
-            if (typeof result !== 'undefined') {
-                //do we convert it to JSON and send it to the frontend
-                this.sendJson(response, result);
-            }
-            else {
-                //in other cases, we still need to close the request and send an empty response
-                if (!response.headersSent) {
-                    this.sendJson(response, null);
+        // The whole call runs in its own context: `this.request` in a provider is
+        // this request, however many calls are in flight.
+        return runWithCallContext(httpCallContext(request, response), async () => {
+            this.noCache(response);
+            await this.initRequest(request, response);
+            let { pkg, method } = request.params;
+            let { args } = JSONParser.parseObject(request.body, {
+                shapeClasses: rpcShapeClassRevival(),
+            });
+            return this.callBackendMethod(pkg, method, args, request, response).then((result) => {
+                //some methods of backend providers may choose to work with request/response directly and will not return anything
+                //so only if a result is returned
+                if (typeof result !== 'undefined') {
+                    //do we convert it to JSON and send it to the frontend
+                    this.sendJson(response, result);
                 }
-            }
+                else {
+                    //in other cases, we still need to close the request and send an empty response
+                    if (!response.headersSent) {
+                        this.sendJson(response, null);
+                    }
+                }
+            });
         });
     }
     noCache(response) {
@@ -1390,15 +1431,16 @@ let LinkedServer = class LinkedServer extends Shape {
         response.setHeader('Expires', '0');
     }
     async processAPICall(request, response, method) {
-        this.noCache(response);
-        const result = await this.api.process(request, response, method);
+        return runWithCallContext(httpCallContext(request, response), async () => {
+            this.noCache(response);
+            await this.api.process(request, response, method);
+        });
     }
     // async processQuery(request, response) {
     //
     //   this.api.process(request, response);
     // }
     async processShapeMethodCall(request, response) {
-        var _a, _b;
         this.noCache(response);
         // console.log('process shape call');
         // response.on('finish', function() {
@@ -1417,30 +1459,37 @@ let LinkedServer = class LinkedServer extends Shape {
         //   console.log('header');
         //   console.log(response.statusCode);
         // });
-        await this.initRequest(request, response);
-        let { pkg, shape, method } = request.params;
-        let { shapeURI, instanceNode, args } = JSONParser.parseObject(request.body);
-        if (!shapeURI) {
-            if ((_a = request.query) === null || _a === void 0 ? void 0 : _a.shapeURI) {
-                shapeURI = (_b = request.query) === null || _b === void 0 ? void 0 : _b.shapeURI;
-            }
-            else {
-                response.status(500).send({
-                    error: 'Invalid server call request: ' + request.originalUrl,
-                });
-                console.warn(paint('red', 'Invalid server call request: ' + request.originalUrl));
-                return;
-            }
-        }
-        return this.callShapeMethod(pkg, method, shapeURI, instanceNode, args, request, response).then((result) => {
-            //we return json if something was returned or, if nothing was returned, we still close the request if the method has not accessed response itself already to send things over
-            if (typeof result !== 'undefined' || !response.headersSent) {
-                this.sendJson(response, result);
+        return runWithCallContext(httpCallContext(request, response), async () => {
+            var _a, _b;
+            await this.initRequest(request, response);
+            let { pkg, shape, method } = request.params;
+            let { shapeURI, instanceNode, args } = JSONParser.parseObject(request.body, { shapeClasses: rpcShapeClassRevival() });
+            if (!shapeURI) {
+                if ((_a = request.query) === null || _a === void 0 ? void 0 : _a.shapeURI) {
+                    shapeURI = (_b = request.query) === null || _b === void 0 ? void 0 : _b.shapeURI;
+                }
+                else {
+                    response.status(500).send({
+                        error: 'Invalid server call request: ' + request.originalUrl,
+                    });
+                    console.warn(paint('red', 'Invalid server call request: ' + request.originalUrl));
+                    return;
+                }
             }
+            return this.callShapeMethod(pkg, method, shapeURI, instanceNode, args, request, response).then((result) => {
+                //we return json if something was returned or, if nothing was returned, we still close the request if the method has not accessed response itself already to send things over
+                if (typeof result !== 'undefined' || !response.headersSent) {
+                    this.sendJson(response, result);
+                }
+            });
         });
     }
     async callShapeMethod(pkg, method, shapeURI, instanceNode, args, request, response) {
         var _a;
+        // see callBackendMethod: outside any request a local call runs as system
+        if (!request && !getCallContext()) {
+            return runAsSystem(() => this.callShapeMethod(pkg, method, shapeURI, instanceNode, args, request, response));
+        }
         //- index module providers if not done yet
         if (!this.shapeProviders.has(pkg)) {
             await this.ensurePackageBackendProviders(pkg, true);
@@ -1478,20 +1527,27 @@ let LinkedServer = class LinkedServer extends Shape {
             // misconfiguration. Answer 501 (via handleErrorsJson) rather than an empty
             // 200; direct backend callers get a rejected ServerCallError.
             if (!shapeProvider) {
-                console.warn(`[LinkedServer] callShapeMethod: no provider for '${shapeURI}' ` +
-                    `(pkg '${pkg}', method '${method}').`);
-                throw new ServerCallError(501, `No provider for ${pkg}/${method}`);
+                console.warn(`[LinkedServer] callShapeMethod: no provider for '${logSafe(shapeURI)}' ` +
+                    `(pkg '${logSafe(pkg)}', method '${logSafe(method)}').`);
+                throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
             }
             if (shapeProvider) {
+                const resolution = resolveCallable(shapeProvider, method);
+                if (resolution.status !== 'missing') {
+                    this.assertDispatchAllowed(pkg, method, shapeProvider, resolution, request, 'shape');
+                }
                 //NOTE: if this is a direct call from backend to backend, we won't know the request & response here because those don't get passed to the Server utility
                 //if this is an issue, we need to see how we can get those back
                 if (request && response) {
                     //give the provider a chance to prepare for this request
                     //wrap the call in a promise and wait for it, because providers MAY return a promise
                     await Promise.resolve(shapeProvider.initRequest(request, response));
+                    if (resolution.status !== 'missing') {
+                        this.assertSessionForLevel(pkg, method, resolution, request);
+                    }
                 }
                 //see if the shapeProvider implements the called method
-                if (shapeProvider[method]) {
+                if (resolution.status !== 'missing') {
                     //prepare the first argument
                     //we want to convert the instance node into an instance of the shape that this shapeProvider provides for
                     //let's find the shape class
@@ -1511,7 +1567,7 @@ let LinkedServer = class LinkedServer extends Shape {
                             return result;
                         }
                         catch (e) {
-                            console.warn(`Error whilst calling ${Object.getPrototypeOf(shapeProvider).constructor.name}.${method}(): `, e);
+                            console.warn(`Error whilst calling ${Object.getPrototypeOf(shapeProvider).constructor.name}.${logSafe(method)}(): `, e);
                             // Rethrow so the HTTP route answers with an error status (via
                             // handleErrorsJson) instead of `200 null`, and direct backend
                             // callers get a rejected promise.
@@ -1524,19 +1580,61 @@ let LinkedServer = class LinkedServer extends Shape {
                     }
                 }
                 else {
-                    console.warn(`${Object.getPrototypeOf(shapeProvider).constructor.name} does not have a method called ${method}`);
-                    throw new ServerCallError(501, `No provider for ${pkg}/${method}`);
+                    console.warn(`${Object.getPrototypeOf(shapeProvider).constructor.name} does not have a method called ${logSafe(method)}`);
+                    throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
                 }
             }
         }
         catch (err) {
             if (!providerMethodFailed && !ServerCallError.is(err)) {
-                console.warn(`Error whilst trying to access provider of ${pkg}: `, err);
+                console.warn(`Error whilst trying to access provider of ${logSafe(pkg)}: `, err);
             }
             throw err;
         }
         return null;
     }
+    /**
+     * Refuse a dispatch the exposure rules do not allow (see utils/rpcExposure).
+     * Throws a 501 `ServerCallError`, the same answer as for a missing method.
+     *
+     * - reserved names: always, for HTTP and backend-to-backend calls alike;
+     * - HTTP only: an internal method (in every mode), a generic call to a provider whose class sets
+     *   `static rpc = false`, and an undeclared method in 'enforce' mode
+     *   (in 'warn' mode it is logged once and runs).
+     */
+    assertDispatchAllowed(pkg, method, provider, resolution, request, route) {
+        var _a, _b;
+        const className = (_b = (_a = Object.getPrototypeOf(provider)) === null || _a === void 0 ? void 0 : _a.constructor) === null || _b === void 0 ? void 0 : _b.name;
+        if (resolution.status === 'reserved') {
+            console.warn(`[linked] refused call to reserved method ${logSafe(pkg)} ${className}.${logSafe(method)}` +
+                (request ? '' : ' (backend-to-backend)'));
+            throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
+        }
+        if (!request)
+            return;
+        if (resolution.status === 'internal') {
+            console.warn(`[linked] refused call to internal method ${logSafe(pkg)} ${className}.${logSafe(method)}`);
+            throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
+        }
+        if (route === 'generic' && isGenericRpcDisabled(provider)) {
+            throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
+        }
+        if (resolution.status === 'undeclared') {
+            if (getRpcExposureMode() === 'enforce') {
+                console.warn(`[linked] refused undeclared RPC ${logSafe(pkg)} ${className}.${logSafe(method)}`);
+                throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
+            }
+            warnUndeclaredCall(pkg, resolution.owner, method, hasSession(request));
+        }
+    }
+    /** A declared `'user'` method needs a session: 401 without one, in every mode. */
+    assertSessionForLevel(pkg, method, resolution, request) {
+        if (resolution.status === 'callable' &&
+            resolution.level === 'user' &&
+            !hasSession(request)) {
+            throw new ServerCallError(401, 'Authentication required');
+        }
+    }
     handleErrors(fn) {
         return async function (req, res, next) {
             try {
@@ -1641,6 +1739,11 @@ let LinkedServer = class LinkedServer extends Shape {
         return cssChunks.join('\n');
     }
     async render(req, res) {
+        // Server-side rendering runs as the requesting user: a Server.call made
+        // while rendering inherits this context rather than escalating to system.
+        return runWithCallContext(httpCallContext(req, res), () => this.renderPage(req, res));
+    }
+    async renderPage(req, res) {
         var _a, _b, _c, _d, _e, _f;
         res.socket.on('error', (error) => {
             console.error('Fatal socket error', error);
@@ -1929,6 +2032,11 @@ let LinkedServer = class LinkedServer extends Shape {
         return { requestLD, requestObject };
     }
     async callBackendMethod(pkg, method, args, request, response) {
+        // A backend-to-backend call outside any request runs as system. Inside a
+        // request (SSR, a provider calling another) it inherits that request.
+        if (!request && !getCallContext()) {
+            return runAsSystem(() => this.callBackendMethod(pkg, method, args, request, response));
+        }
         if (!this.genericProviders.has(pkg)) {
             await this.ensurePackageBackendProviders(pkg, true);
         }
@@ -1937,13 +2045,15 @@ let LinkedServer = class LinkedServer extends Shape {
         let result;
         if (!genericBackendProvider) {
             console.warn(`${paint('magenta', pkg)} does not have a generic backend provider. If you can edit this package, make sure 'backend.ts' is included in 'tsconfig.json' and that it exports a provider.`);
-            throw new ServerCallError(501, `No provider for ${pkg}/${method}`);
+            throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
         }
-        //test if there is a matching method in the backend provider
-        if (!genericBackendProvider[method]) {
-            console.warn(`Generic provider '${Object.getPrototypeOf(genericBackendProvider).constructor.name}' of ${pkg} does not have a method called ${method}`);
-            throw new ServerCallError(501, `No provider for ${pkg}/${method}`);
+        //test if there is a matching method in the backend provider, and whether it may be called
+        const resolution = resolveCallable(genericBackendProvider, method);
+        if (resolution.status === 'missing') {
+            console.warn(`Generic provider '${Object.getPrototypeOf(genericBackendProvider).constructor.name}' of ${logSafe(pkg)} does not have a method called ${logSafe(method)}`);
+            throw new ServerCallError(501, `No provider for ${logSafe(pkg)}/${logSafe(method)}`);
         }
+        this.assertDispatchAllowed(pkg, method, genericBackendProvider, resolution, request, 'generic');
         try {
             //TODO: remove init request.
             //TODO: refactor this.request and this.response to a request parameter
@@ -1953,6 +2063,7 @@ let LinkedServer = class LinkedServer extends Shape {
                 //initialise the request for this specific provider
                 //wrap the call in a promise and wait for it, because providers MAY return a promise
                 await Promise.resolve(genericBackendProvider.initRequest(request, response));
+                this.assertSessionForLevel(pkg, method, resolution, request);
             }
             // args.push(request);
             // args.push(response);
@@ -1960,7 +2071,9 @@ let LinkedServer = class LinkedServer extends Shape {
             result = await Promise.resolve(genericBackendProvider[method].apply(genericBackendProvider, args));
         }
         catch (e) {
-            console.warn(`Error whilst calling ${method}() in provider ${Object.getPrototypeOf(genericBackendProvider).constructor.name} of package ${pkg}:\n`, e);
+            if (ServerCallError.is(e) && e.status === 401)
+                throw e;
+            console.warn(`Error whilst calling ${logSafe(method)}() in provider ${Object.getPrototypeOf(genericBackendProvider).constructor.name} of package ${logSafe(pkg)}:\n`, e);
             // error logging
             LinkedErrorLogging.log(e);
             // Rethrow so the HTTP route answers with an error status instead of `200 null`.
@@ -1978,4 +2091,33 @@ LinkedServer = __decorate([
     __metadata("design:paramtypes", [Object])
 ], LinkedServer);
 export { LinkedServer };
+/**
+ * Register the RPC routes (`/call/...`) and the `LincdAPI` routes (`/api/...`)
+ * of `linkedServer` on an express app.
+ *
+ * `LinkedServer.start()` calls this; tests call it on a bare express app so they
+ * drive exactly the routes a running server has.
+ */
+export function registerCallRoutes(app, linkedServer) {
+    const server = linkedServer;
+    // Scoped-package variants (@scope/pkg). Register BEFORE the unscoped
+    // routes — Express `:pkg` won't consume slashes, so a call to
+    // `/call/@_linked/auth/signinDev` would otherwise fall through to the
+    // 3-segment `:pkg/:shape/:method` route and be misinterpreted as a
+    // shape-method call (pkg=`@_linked`, shape=`auth`). These handlers
+    // recognise the `@scope/pkg` prefix and rebuild the full package name
+    // before dispatching to the same handler used for unscoped packages.
+    app.post('/call/@:scope/:pkg/:method', server.handleErrorsJson(async (req, res) => {
+        req.params.pkg = `@${req.params.scope}/${req.params.pkg}`;
+        return server.processBackendMethodCall(req, res);
+    }));
+    app.post('/call/@:scope/:pkg/:shape/:method', server.handleErrorsJson(async (req, res) => {
+        req.params.pkg = `@${req.params.scope}/${req.params.pkg}`;
+        return server.processShapeMethodCall(req, res);
+    }));
+    app.post('/call/:pkg/:method', server.handleErrorsJson(async (req, res) => server.processBackendMethodCall(req, res)));
+    app.post('/call/:pkg/:shape/:method', server.handleErrorsJson(async (req, res) => server.processShapeMethodCall(req, res)));
+    app.post('/api/:method/:action?', server.handleErrorsJson(async (req, res) => server.processAPICall(req, res, 'post')));
+    app.get('/api/:method/:action?', server.handleErrorsJson(async (req, res) => server.processAPICall(req, res, 'get')));
+}
 //# sourceMappingURL=LinkedServer.js.map