@sasjs/api 0.8.0 → 0.10.0

package/build/cjs/identity/records.js

@@ -17,6 +17,7 @@ exports.createRecordService = exports.sanitiseDisplayName = void 0;
  * the server sends.
  */
 const types_js_1 = require("../types.js");
+const routeAccess_js_1 = require("./routeAccess.js");
 /** The name the server gives the group every account is added to on creation. */
 const ALL_USERS_GROUP = 'all-users';
 /** The group whose membership the API refuses to change. */
@@ -83,7 +84,8 @@ const asGroup = (group) => ({
     name: group.name,
     description: group.description
 });
-const createRecordService = (store) => {
+const createRecordService = (store, options = {}) => {
+    const grantableRoutes = options.grantableRoutes || routeAccess_js_1.DEFAULT_GRANTABLE_ROUTES;
     const groupDetails = async (group) => {
         const members = [];
         for (const uid of group.users) {
@@ -285,6 +287,41 @@ const createRecordService = (store) => {
                 throw new types_js_1.ApiError(400, 'Unable to update group.');
             return groupDetails(updated);
         },
+        async listAuthorizedRoutes(caller) {
+            // an identity is required because the route is about a caller's access,
+            // even though what it returns is the whole inventory
+            await requireCaller(store, caller);
+            return { paths: [...grantableRoutes] };
+        },
+        async myAuthorizedRoutes(caller) {
+            const reader = await requireCaller(store, caller);
+            // an administrator holds every route, and the always-visible ones are
+            // visible whatever the rules say
+            if (reader.isAdmin)
+                return { paths: [...grantableRoutes] };
+            const rules = await store.permissions();
+            const mine = {
+                user: rules
+                    .filter((rule) => rule.user === reader.uid)
+                    .map((rule) => ({ path: rule.path, setting: rule.setting })),
+                group: rules
+                    .filter((rule) => rule.group !== undefined && reader.groups.includes(rule.group))
+                    .map((rule) => ({ path: rule.path, setting: rule.setting }))
+            };
+            // a grant on the reserved public group admits any caller, and it is
+            // checked before the rules so no user or group rule can take it away
+            const publicGroup = (await store.groups()).find((group) => group.name === 'public');
+            const publicGrants = publicGroup
+                ? rules
+                    .filter((rule) => rule.group === publicGroup.uid && rule.setting === 'Grant')
+                    .map((rule) => rule.path)
+                : [];
+            return {
+                paths: grantableRoutes.filter((path) => routeAccess_js_1.ALWAYS_VISIBLE_ROUTES.includes(path) ||
+                    publicGrants.includes(path) ||
+                    (0, routeAccess_js_1.isRouteGranted)(mine, path, (0, routeAccess_js_1.topLevelRouteFor)(path)))
+            };
+        },
         async listPermissions(caller) {
             const reader = await requireCaller(store, caller);
             const rules = await store.permissions();

package/build/cjs/identity/routeAccess.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Which routes a caller may use, from the permission rules alone.
+ *
+ * This is the answer `GET /SASjsApi/info/myAuthorizedRoutes` gives, and it is the
+ * same decision the gate makes when the route is actually requested - a
+ * web interface that offers a route the gate then refuses is the bug this exists
+ * to prevent, so the two must not be two implementations. A host that gates its
+ * own middleware should call `isRouteGranted` rather than re-derive it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRouteGranted = exports.topLevelRouteFor = exports.DEFAULT_GRANTABLE_ROUTES = exports.STATIC_AUTHORIZED_ROUTES = exports.ALWAYS_VISIBLE_ROUTES = exports.TOP_LEVEL_ROUTES = void 0;
+/** The two top-level routes, which a rule can address to cover everything below. */
+exports.TOP_LEVEL_ROUTES = ['/AppStream', '/SASjsApi'];
+/**
+ * Routes any authenticated caller may use whatever the rules say. `/AppStream` is
+ * the navigation page whose job is to list the apps the caller may open, so
+ * gating it on a grant that lists them would hide the page that leads to them.
+ */
+exports.ALWAYS_VISIBLE_ROUTES = ['/AppStream'];
+/**
+ * The routes that accept a rule, before a host adds its own. A host with
+ * streamed applications extends this with `/AppStream/<app>` for each one, which
+ * is why the inventory is passed in rather than derived from a fixed list here.
+ */
+exports.STATIC_AUTHORIZED_ROUTES = [
+    '/SASjsApi/code/execute',
+    '/SASjsApi/stp/execute',
+    '/SASjsApi/drive/deploy',
+    '/SASjsApi/drive/deploy/upload',
+    '/SASjsApi/drive/file',
+    '/SASjsApi/drive/folder',
+    '/SASjsApi/drive/fileTree',
+    '/SASjsApi/drive/rename'
+];
+/** The route inventory when the host states no additions of its own. */
+exports.DEFAULT_GRANTABLE_ROUTES = [
+    ...exports.TOP_LEVEL_ROUTES,
+    ...exports.STATIC_AUTHORIZED_ROUTES
+];
+/**
+ * The top-level route that governs a request: `/SASjsApi/code/execute` is
+ * governed by `/SASjsApi`, and a rule on the top-level route applies to
+ * everything beneath it.
+ */
+const topLevelRouteFor = (routePath) => exports.TOP_LEVEL_ROUTES.find((route) => routePath.toLowerCase().startsWith(route.toLowerCase())) ?? routePath;
+exports.topLevelRouteFor = topLevelRouteFor;
+const settingOn = (rules, path) => rules.find((rule) => rule.path === path)?.setting;
+const GRANT = 'Grant';
+const DENY = 'Deny';
+/**
+ * Whether these rules grant access to `path`.
+ *
+ * The order is the documented one and the only implementation of it:
+ *
+ *   1. a rule addressed to the user on the path itself decides either way;
+ *   2. otherwise a rule addressed to the user on the top-level route decides;
+ *   3. otherwise a group grant on the path allows, and a group deny on the path
+ *      blocks the top-level check - but a grant from another group still allows;
+ *   4. otherwise a group grant on the top-level route allows;
+ *   5. otherwise denied.
+ *
+ * A grant beats a deny at the same level, which is why step 3 looks at every
+ * group rule rather than stopping at the first deny.
+ */
+const isRouteGranted = (rules, path, topLevelRoute = (0, exports.topLevelRouteFor)(path)) => {
+    const userSetting = settingOn(rules.user, path) ?? settingOn(rules.user, topLevelRoute);
+    if (userSetting)
+        return userSetting === GRANT;
+    const onPath = rules.group.filter((rule) => rule.path === path);
+    if (onPath.some((rule) => rule.setting === GRANT))
+        return true;
+    if (onPath.some((rule) => rule.setting === DENY))
+        return false;
+    return rules.group.some((rule) => rule.path === topLevelRoute && rule.setting === GRANT);
+};
+exports.isRouteGranted = isRouteGranted;

package/build/cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.servicesFor = exports.runCase = exports.PROVIDER_MANAGED = exports.ADMIN_SIGNED_IN = exports.RECORD_CORPUS = exports.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = exports.sanitiseDisplayName = exports.createRecordService = exports.createIdentityService = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.measureDeployTree = exports.isDeployTree = exports.deployTree = exports.decodeBase64 = exports.checkDeployTree = exports.DEPLOY_SUCCESS = exports.DEPLOY_PAYLOAD_BYTES = exports.DEPLOY_LIMITS = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
+exports.servicesFor = exports.runCase = exports.PROVIDER_MANAGED = exports.ADMIN_SIGNED_IN = exports.RECORD_CORPUS = exports.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = exports.CODE_CORPUS = exports.sanitiseDisplayName = exports.createRecordService = exports.createIdentityService = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.measureDeployTree = exports.isDeployTree = exports.deployTree = exports.decodeBase64 = exports.checkDeployTree = exports.DEPLOY_SUCCESS = exports.DEPLOY_PAYLOAD_BYTES = exports.DEPLOY_LIMITS = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
 /**
  * `@sasjs/api` - the SASjs Server API described once.
  *
@@ -60,11 +60,15 @@ Object.defineProperty(exports, "TAG_CAPABILITIES", { enumerable: true, get: func
 var dispatch_js_1 = require("./host/dispatch.js");
 Object.defineProperty(exports, "dispatch", { enumerable: true, get: function () { return dispatch_js_1.dispatch; } });
 Object.defineProperty(exports, "HANDLED_ROUTES", { enumerable: true, get: function () { return dispatch_js_1.HANDLED_ROUTES; } });
+// a host gating its own middleware reads the same decision the inventory reports
+__exportStar(require("./identity/routeAccess.js"), exports);
 var service_js_2 = require("./identity/service.js");
 Object.defineProperty(exports, "createIdentityService", { enumerable: true, get: function () { return service_js_2.createIdentityService; } });
 var records_js_1 = require("./identity/records.js");
 Object.defineProperty(exports, "createRecordService", { enumerable: true, get: function () { return records_js_1.createRecordService; } });
 Object.defineProperty(exports, "sanitiseDisplayName", { enumerable: true, get: function () { return records_js_1.sanitiseDisplayName; } });
+var code_js_1 = require("./corpus/code.js");
+Object.defineProperty(exports, "CODE_CORPUS", { enumerable: true, get: function () { return code_js_1.CODE_CORPUS; } });
 var memory_store_js_2 = require("./identity/memory-store.js");
 Object.defineProperty(exports, "MemoryIdentityStore", { enumerable: true, get: function () { return memory_store_js_2.MemoryIdentityStore; } });
 var fixture_js_1 = require("./identity/fixture.js");

package/build/cjs/routes/overlay.js

@@ -26,11 +26,9 @@ exports.TAG_CAPABILITIES = {
  * thing thirty times.
  */
 const DIRECTORY = 'Synchronising with an external auth provider needs a directory port, which this package does not have: a host decides which directory it holds accounts in, and answers this itself.';
-const EDITOR = 'Linting and formatting come from @sasjs/lint, which this package does not depend on. They land with the code routes so an editor has one wiring.';
 const RUNTIME = 'Starting a program needs a runtime port, which this package does not have: a host decides which languages it holds, and answers this itself until then.';
 const SESSION_RECORD = "A triggered session's record, log, output and state belong to the runtime that ran the program, and this package has no runtime port.";
 const HOST_CONFIG = "The body is the host's own configuration - ports, run times and providers - which a mock states for itself and this package cannot know.";
-const PERMISSIONS = "The route inventory is the host's permission model, which this package does not hold.";
 const HOST_OWNED = "The host owns this report: it describes the host's own process and files, which a browser build has no equivalent of.";
 const WEB_BUNDLE = 'The host serves its own web bundle; there is no API decision here for this package to answer.';
 const ARCHIVE = "Expanding the uploaded archive is the host's transport work - multer and a zip library on the server, `DecompressionStream` in a worker - and the host hands this package the tree it produces, which is the same tree `POST /SASjsApi/drive/deploy` takes.";
@@ -97,8 +95,14 @@ exports.OVERLAY = {
     // Code - the editor's three calls, and the runtime one
     'POST /SASjsApi/code/execute': { implemented: false, reason: RUNTIME },
     'POST /SASjsApi/code/trigger': { implemented: false, reason: RUNTIME },
-    'POST /SASjsApi/code/lint': { implemented: false, reason: EDITOR },
-    'POST /SASjsApi/code/format': { implemented: false, reason: EDITOR },
+    'POST /SASjsApi/code/lint': {
+        implemented: true,
+        capabilities: ['identity']
+    },
+    'POST /SASjsApi/code/format': {
+        implemented: true,
+        capabilities: ['identity']
+    },
     // Drive - the file and folder rules, and the three deploy routes
     // The body is the file itself, so there is nothing to annotate
     'GET /SASjsApi/drive/file': { implemented: true },
@@ -177,16 +181,12 @@ exports.OVERLAY = {
     // Info - what the host is, and what this caller may use
     'GET /SASjsApi/info': { implemented: false, reason: HOST_CONFIG },
     'GET /SASjsApi/info/authorizedRoutes': {
-        implemented: false,
-        // the route inventory reports what the CALLER may use, so it needs an
-        // identity even though the rest of the Info tag needs nothing
-        capabilities: ['identity'],
-        reason: PERMISSIONS
+        implemented: true,
+        capabilities: ['identity']
     },
     'GET /SASjsApi/info/myAuthorizedRoutes': {
-        implemented: false,
-        capabilities: ['identity'],
-        reason: PERMISSIONS
+        implemented: true,
+        capabilities: ['identity']
     },
     // Permission - the rules the inventory above is derived from
     'GET /SASjsApi/permission': {

package/build/esm/code/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The code service, on its own entry point.
+ *
+ * `@sasjs/lint` reads the filesystem (its config resolution walks up for a
+ * `.sasjslint`), so it cannot be bundled for a service worker: the package root
+ * stays free of it and a host that wants these routes imports `@sasjs/api/code`.
+ */
+export { createCodeService } from './service.js';
+export type { CodeRequest, CodeService, CodeServiceOptions } from './service.js';
+//# sourceMappingURL=index.d.ts.map

package/build/esm/code/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/code/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA"}

package/build/esm/code/index.js

@@ -0,0 +1,8 @@
+/**
+ * The code service, on its own entry point.
+ *
+ * `@sasjs/lint` reads the filesystem (its config resolution walks up for a
+ * `.sasjslint`), so it cannot be bundled for a service worker: the package root
+ * stays free of it and a host that wants these routes imports `@sasjs/api/code`.
+ */
+export { createCodeService } from './service.js';

package/build/esm/code/service.d.ts

@@ -0,0 +1,40 @@
+import type { Diagnostic, LintConfig } from '@sasjs/lint';
+import type { Subject } from '../identity/types.js';
+/** What both code routes take: a buffer, and where it came from when it has a file. */
+export interface CodeRequest {
+    code: string;
+    /** The drive path the code belongs to, so a host can pick that folder's rules. */
+    filePath?: string;
+}
+export interface CodeServiceOptions {
+    /**
+     * The lint configuration that applies to a file.
+     *
+     * A host resolves the nearest `.sasjslint` at or above `filePath`, so each
+     * folder can carry its own rules; without one the linter's defaults apply,
+     * which is what an untitled buffer lints against.
+     */
+    lintConfig?: (filePath?: string) => LintConfig | undefined;
+}
+export interface CodeService {
+    /** The diagnostics for a buffer. Nothing is written and nothing is executed. */
+    lint(caller: Subject | undefined, body: CodeRequest): Promise<Diagnostic[]>;
+    /** The formatted buffer. */
+    format(caller: Subject | undefined, body: CodeRequest): Promise<string>;
+}
+/**
+ * The two editor routes, over `@sasjs/lint`.
+ *
+ * The linter is a dependency because it is the same everywhere, and it is
+ * deliberately NOT reachable from the package root: `@sasjs/lint` resolves its
+ * configuration by walking the filesystem, so it cannot be bundled into the
+ * service worker the browser entry produces. A host that wants these routes
+ * imports `@sasjs/api/code`, which is Node-only, exactly like the linter.
+ *
+ * The *rules* are the host's: which `.sasjslint` applies to a path is a fact
+ * about a drive, so `lintConfig` is asked for it.
+ * Neither route touches the drive or runs anything; they answer about the text
+ * in the request, which is what lets an editor check unsaved changes.
+ */
+export declare const createCodeService: (options?: CodeServiceOptions) => CodeService;
+//# sourceMappingURL=service.d.ts.map

package/build/esm/code/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/code/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAEnD,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAA;CAC3D;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAC3E,4BAA4B;IAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACxE;AAmBD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAS,kBAAuB,KAC/B,WAqBF,CAAA"}

package/build/esm/code/service.js

@@ -0,0 +1,53 @@
+import { formatText, lintText } from '@sasjs/lint';
+import { ApiError } from '../types.js';
+/**
+ * `code`, refused the way the server's schema refuses it.
+ *
+ * Coercing with `String(...)` defeated the refusal: `{"code": 123}` was linted as
+ * the text "123" and `{"code": ""}` answered "required" where the server says it
+ * is empty. The three messages are Joi's, because they are the ones a client
+ * written against the document already handles.
+ */
+const codeOf = (body) => {
+    const value = body.code;
+    if (value === undefined)
+        throw new ApiError(400, '"code" is required');
+    if (typeof value !== 'string')
+        throw new ApiError(400, '"code" must be a string');
+    if (value === '')
+        throw new ApiError(400, '"code" is not allowed to be empty');
+    return value;
+};
+/**
+ * The two editor routes, over `@sasjs/lint`.
+ *
+ * The linter is a dependency because it is the same everywhere, and it is
+ * deliberately NOT reachable from the package root: `@sasjs/lint` resolves its
+ * configuration by walking the filesystem, so it cannot be bundled into the
+ * service worker the browser entry produces. A host that wants these routes
+ * imports `@sasjs/api/code`, which is Node-only, exactly like the linter.
+ *
+ * The *rules* are the host's: which `.sasjslint` applies to a path is a fact
+ * about a drive, so `lintConfig` is asked for it.
+ * Neither route touches the drive or runs anything; they answer about the text
+ * in the request, which is what lets an editor check unsaved changes.
+ */
+export const createCodeService = (options = {}) => {
+    const requireCaller = (caller) => {
+        // both routes are permissioned at the gate, so a caller that reached the
+        // service without one is a host that skipped it rather than a public route
+        if (!caller)
+            throw new ApiError(401, 'Unauthorized');
+    };
+    const configFor = (filePath) => options.lintConfig ? options.lintConfig(filePath) : undefined;
+    return {
+        async lint(caller, body) {
+            requireCaller(caller);
+            return lintText(codeOf(body), configFor(body.filePath));
+        },
+        async format(caller, body) {
+            requireCaller(caller);
+            return formatText(codeOf(body), configFor(body.filePath));
+        }
+    };
+};

package/build/esm/corpus/code.d.ts

@@ -0,0 +1,17 @@
+import type { CorpusCase } from './drive.js';
+/**
+ * The editor's corpus: the two routes that answer about a buffer rather than a
+ * file.
+ *
+ * Both expectations are the linter's own output for the same input, measured
+ * against `@sasjs/lint` with no configuration - the defaults an untitled buffer
+ * lints against. A host that supplies a `.sasjslint` changes the rules for its
+ * own drive, which is why the case names no `filePath`.
+ *
+ *     lintText('data _null_;\n  x = 1;\nrun;\n')
+ *       -> [{ message: 'File missing Doxygen header', lineNumber: 1, ... }]
+ *     formatText(...)
+ *       -> the header block, then the program with its spacing normalised
+ */
+export declare const CODE_CORPUS: CorpusCase[];
+//# sourceMappingURL=code.d.ts.map

package/build/esm/corpus/code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code.d.ts","sourceRoot":"","sources":["../../../src/corpus/code.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,EAAE,UAAU,EA6CnC,CAAA"}

package/build/esm/corpus/code.js

@@ -0,0 +1,59 @@
+/**
+ * The editor's corpus: the two routes that answer about a buffer rather than a
+ * file.
+ *
+ * Both expectations are the linter's own output for the same input, measured
+ * against `@sasjs/lint` with no configuration - the defaults an untitled buffer
+ * lints against. A host that supplies a `.sasjslint` changes the rules for its
+ * own drive, which is why the case names no `filePath`.
+ *
+ *     lintText('data _null_;\n  x = 1;\nrun;\n')
+ *       -> [{ message: 'File missing Doxygen header', lineNumber: 1, ... }]
+ *     formatText(...)
+ *       -> the header block, then the program with its spacing normalised
+ */
+export const CODE_CORPUS = [
+    {
+        id: 'code-lint-missing-header',
+        route: 'POST /SASjsApi/code/lint',
+        description: 'answers the diagnostics for a buffer, without touching a file',
+        request: {
+            // the routes are permissioned; the runner resolves the fixture's admin
+            subject: { userId: 'user-admin', clientId: 'web_app' },
+            body: { code: 'data _null_;\n  x = 1;\nrun;\n' }
+        },
+        expect: {
+            status: 200,
+            body: [
+                {
+                    message: 'File missing Doxygen header',
+                    lineNumber: 1,
+                    startColumnNumber: 1,
+                    endColumnNumber: 1,
+                    severity: 1
+                }
+            ]
+        }
+    },
+    // Two refusals are deliberately not pinned here yet: a `code` that is not a
+    // string, and one that is empty. The package answers 400 `"code" must be a
+    // string` / `"code" is not allowed to be empty` - the messages the server's
+    // schema produces - but sasjs/server's code controller carries no
+    // `@Response(400)` for these routes, so the document states 200 alone and the
+    // parity gate refuses a case answering anything else. The cases land when the
+    // decorators do.
+    {
+        id: 'code-format-adds-the-header',
+        route: 'POST /SASjsApi/code/format',
+        description: 'answers the formatted buffer, header block included',
+        request: {
+            // the routes are permissioned; the runner resolves the fixture's admin
+            subject: { userId: 'user-admin', clientId: 'web_app' },
+            body: { code: 'data _null_;\n  x = 1;\nrun;\n' }
+        },
+        expect: {
+            status: 200,
+            body: '/**\n  @file\n  @brief <Your brief here>\n\n  <h4> SAS Macros </h4>\n\n**/\ndata _null_;\n  x = 1;\nrun;\n'
+        }
+    }
+];

package/build/esm/corpus/drive.d.ts

@@ -47,6 +47,15 @@ export interface CorpusCase {
          * minted token is not a value a case can state.
          */
         keys?: string[];
+        /**
+         * How the body travels, where a string could be either. `json` is a JSON
+         * string on the wire - what tsoa emits for `Promise<string>` and what the
+         * server's `res.json` sends; `text` is a body the route sends itself, which
+         * the document carries in the `description` with no content. A case that
+         * names neither is read as `text` when the document declares no content and
+         * as `json` when it does.
+         */
+        encoding?: 'json' | 'text';
     };
 }
 export declare const DRIVE_CORPUS: CorpusCase[];

package/build/esm/corpus/drive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/corpus/drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAA;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,EAAE,UAAU,CAAA;IACnB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;QAC9B,yDAAyD;QACzD,KAAK,CAAC,EAAE,MAAM,CAAA;QACd;;;;WAIG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC;;;WAGG;QACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAChB,CAAA;CACF;AAmBD,eAAO,MAAM,YAAY,EAAE,UAAU,EAqapC,CAAA"}
+{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/corpus/drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAA;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,EAAE,UAAU,CAAA;IACnB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;QAC9B,yDAAyD;QACzD,KAAK,CAAC,EAAE,MAAM,CAAA;QACd;;;;WAIG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC;;;WAGG;QACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;QACf;;;;;;;WAOG;QACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAC3B,CAAA;CACF;AAmBD,eAAO,MAAM,YAAY,EAAE,UAAU,EAqapC,CAAA"}

package/build/esm/corpus/records.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../../src/corpus/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAA;AAkB/B,qFAAqF;AACrF,eAAO,MAAM,eAAe,EAAE,eAG7B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA0C9B,CAAA;AAOD,eAAO,MAAM,aAAa,EAAE,UAAU,EA4kCrC,CAAA"}
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../../src/corpus/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAA;AAkB/B,qFAAqF;AACrF,eAAO,MAAM,eAAe,EAAE,eAG7B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA0C9B,CAAA;AAOD,eAAO,MAAM,aAAa,EAAE,UAAU,EA4oCrC,CAAA"}

package/build/esm/corpus/records.js

@@ -699,6 +699,70 @@ export const RECORD_CORPUS = [
         expect: { status: 404, error: 'Group not found.' }
     },
     // ------------------------------------------------------------ permissions
+    {
+        id: 'authorized-routes',
+        route: 'GET /SASjsApi/info/authorizedRoutes',
+        description: 'answers the routes that accept a rule, to any caller',
+        identity: ADMIN_SIGNED_IN,
+        request: { token: RESTRICTED },
+        expect: {
+            status: 200,
+            body: {
+                paths: [
+                    '/AppStream',
+                    '/SASjsApi',
+                    '/SASjsApi/code/execute',
+                    '/SASjsApi/stp/execute',
+                    '/SASjsApi/drive/deploy',
+                    '/SASjsApi/drive/deploy/upload',
+                    '/SASjsApi/drive/file',
+                    '/SASjsApi/drive/folder',
+                    '/SASjsApi/drive/fileTree',
+                    '/SASjsApi/drive/rename'
+                ]
+            }
+        }
+    },
+    {
+        id: 'my-authorized-routes-as-admin',
+        route: 'GET /SASjsApi/info/myAuthorizedRoutes',
+        description: 'answers every route to an administrator',
+        identity: ADMIN_SIGNED_IN,
+        request: { token: ADMIN },
+        expect: {
+            status: 200,
+            body: {
+                paths: [
+                    '/AppStream',
+                    '/SASjsApi',
+                    '/SASjsApi/code/execute',
+                    '/SASjsApi/stp/execute',
+                    '/SASjsApi/drive/deploy',
+                    '/SASjsApi/drive/deploy/upload',
+                    '/SASjsApi/drive/file',
+                    '/SASjsApi/drive/folder',
+                    '/SASjsApi/drive/fileTree',
+                    '/SASjsApi/drive/rename'
+                ]
+            }
+        }
+    },
+    {
+        id: 'my-authorized-routes-as-user',
+        route: 'GET /SASjsApi/info/myAuthorizedRoutes',
+        description: 'answers a caller only the routes its rules grant',
+        identity: ADMIN_SIGNED_IN,
+        request: { token: RESTRICTED },
+        expect: {
+            status: 200,
+            // /AppStream is visible whatever the rules say; the two grants come from
+            // DCGroup; /SASjsApi/code/execute is denied to this user by a user rule,
+            // and nothing grants the rest
+            body: {
+                paths: ['/AppStream', '/SASjsApi/stp/execute', '/SASjsApi/drive/file']
+            }
+        }
+    },
     {
         id: 'list-permissions-as-admin',
         route: 'GET /SASjsApi/permission',

package/build/esm/host/dispatch.d.ts

@@ -1,6 +1,7 @@
 import type { DriveService } from '../drive/service.js';
 import type { IdentityService } from '../identity/service.js';
 import type { RecordService } from '../identity/records.js';
+import type { CodeService } from '../code/service.js';
 import type { Subject } from '../identity/types.js';
 export interface ApiRequest {
     query?: Record<string, string | undefined>;
@@ -33,6 +34,8 @@ export interface ApiResponse {
     contents?: string | Uint8Array;
 }
 export interface Services {
+    /** The editor routes, where the host supplies a linter. */
+    code?: CodeService;
     drive: DriveService;
     /**
      * Users, clients and tokens. A host without one answers 501 for the identity

package/build/esm/host/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/host/dispatch.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAOnD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,oFAAoF;IACpF,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;IACtD;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,YAAY,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B,yFAAyF;IACzF,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB;AAsCD,eAAO,MAAM,QAAQ,GACnB,UAAU,QAAQ,EAClB,SAAS,MAAM,EACf,UAAS,UAAe,KACvB,OAAO,CAAC,WAAW,CAqWrB,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,EAwClC,CAAA"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/host/dispatch.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAOnD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,oFAAoF;IACpF,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;IACtD;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,KAAK,EAAE,YAAY,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B,yFAAyF;IACzF,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB;AA2CD,eAAO,MAAM,QAAQ,GACnB,UAAU,QAAQ,EAClB,SAAS,MAAM,EACf,UAAS,UAAe,KACvB,OAAO,CAAC,WAAW,CA2YrB,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,EA4ClC,CAAA"}

package/build/esm/host/dispatch.js

@@ -21,8 +21,13 @@ const validate = (route, request) => {
         const given = param.in === 'query'
             ? request.query?.[param.name]
             : request.body?.[param.name];
-        if (given === undefined || given === '')
+        // missing and empty are two refusals, the way the schema has them: a
+        // client that sent the field an empty value has a different bug from one
+        // that omitted it
+        if (given === undefined)
             throw new ApiError(400, `"${param.name}" is required`);
+        if (given === '')
+            throw new ApiError(400, `"${param.name}" is not allowed to be empty`);
     }
 };
 /** The drive path a write names: the query parameter wins over the form field. */
@@ -41,7 +46,7 @@ export const dispatch = async (services, routeId, request = {}) => {
     const route = routeById(routeId);
     if (!route)
         throw new ApiError(404, `No such operation: ${routeId}`);
-    const { drive, identity, records } = services;
+    const { drive, identity, records, code } = services;
     // The server authenticates before its payload schema runs, so an anonymous
     // request with an incomplete body is a 401 there rather than a 400. The order
     // is only observable on the route groups that gate on a caller: the sign-in
@@ -89,7 +94,7 @@ export const dispatch = async (services, routeId, request = {}) => {
                     status: 200,
                     body: await identity.token({
                         clientId: String(body.clientId ?? ''),
-                        code: String(body.code ?? '')
+                        code: body.code
                     })
                 };
             case 'POST /SASjsApi/auth/refresh':
@@ -216,6 +221,36 @@ export const dispatch = async (services, routeId, request = {}) => {
                 status: 200,
                 body: await required().deleteUser(await caller(), { username: String(params.username ?? '') }, { password: body.password })
             };
+        case 'POST /SASjsApi/code/lint':
+            if (!code)
+                throw new ApiError(501, `This host has no code service, so it cannot answer ${routeId}.`);
+            return {
+                status: 200,
+                body: await code.lint(await caller(), {
+                    code: body.code,
+                    filePath: body.filePath
+                })
+            };
+        case 'POST /SASjsApi/code/format':
+            if (!code)
+                throw new ApiError(501, `This host has no code service, so it cannot answer ${routeId}.`);
+            return {
+                status: 200,
+                body: await code.format(await caller(), {
+                    code: body.code,
+                    filePath: body.filePath
+                })
+            };
+        case 'GET /SASjsApi/info/authorizedRoutes':
+            return {
+                status: 200,
+                body: await required().listAuthorizedRoutes(await caller())
+            };
+        case 'GET /SASjsApi/info/myAuthorizedRoutes':
+            return {
+                status: 200,
+                body: await required().myAuthorizedRoutes(await caller())
+            };
         case 'GET /SASjsApi/group':
             return { status: 200, body: await required().listGroups(await caller()) };
         case 'GET /SASjsApi/group/{uid}':
@@ -318,6 +353,10 @@ export const dispatch = async (services, routeId, request = {}) => {
 };
 /** Whether a route is one `dispatch` can answer today. */
 export const HANDLED_ROUTES = [
+    'POST /SASjsApi/code/lint',
+    'POST /SASjsApi/code/format',
+    'GET /SASjsApi/info/authorizedRoutes',
+    'GET /SASjsApi/info/myAuthorizedRoutes',
     'GET /SASjsApi/drive/file',
     'POST /SASjsApi/drive/file',
     'PATCH /SASjsApi/drive/file',