@sasjs/api 0.7.2 → 0.9.0

package/build/cjs/corpus/records.js

@@ -404,7 +404,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: RESTRICTED,
             params: { username: 'user2' },
-            body: { password: 'wrong' }
+            body: { password: 'wrong123' }
         },
         expect: { status: 401, error: 'Invalid password.' }
     },
@@ -702,6 +702,70 @@ exports.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: exports.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: exports.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: exports.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',
@@ -713,55 +777,24 @@ exports.RECORD_CORPUS = [
             body: [
                 {
                     uid: 'rule-routes',
-                    path: '/SASjsApi/info',
+                    path: '/SASjsApi/drive/file',
                     type: 'Route',
                     setting: 'Grant',
-                    group: {
-                        uid: 'group-data-controller',
-                        name: 'DCGroup',
-                        description: 'Data Controller users',
-                        isActive: true,
-                        users: [
-                            {
-                                uid: RESTRICTED_UID,
-                                username: 'user2',
-                                displayName: 'Demo User',
-                                isAdmin: false
-                            }
-                        ]
-                    }
+                    group: 'group-data-controller'
                 },
                 {
                     uid: 'rule-execute',
                     path: '/SASjsApi/stp/execute',
                     type: 'Route',
                     setting: 'Grant',
-                    group: {
-                        uid: 'group-data-controller',
-                        name: 'DCGroup',
-                        description: 'Data Controller users',
-                        isActive: true,
-                        users: [
-                            {
-                                uid: RESTRICTED_UID,
-                                username: 'user2',
-                                displayName: 'Demo User',
-                                isAdmin: false
-                            }
-                        ]
-                    }
+                    group: 'group-data-controller'
                 },
                 {
                     uid: 'rule-code',
                     path: '/SASjsApi/code/execute',
                     type: 'Route',
                     setting: 'Deny',
-                    user: {
-                        uid: RESTRICTED_UID,
-                        username: 'user2',
-                        displayName: 'Demo User',
-                        isAdmin: false
-                    }
+                    user: RESTRICTED_UID
                 }
             ]
         }
@@ -777,55 +810,24 @@ exports.RECORD_CORPUS = [
             body: [
                 {
                     uid: 'rule-routes',
-                    path: '/SASjsApi/info',
+                    path: '/SASjsApi/drive/file',
                     type: 'Route',
                     setting: 'Grant',
-                    group: {
-                        uid: 'group-data-controller',
-                        name: 'DCGroup',
-                        description: 'Data Controller users',
-                        isActive: true,
-                        users: [
-                            {
-                                uid: RESTRICTED_UID,
-                                username: 'user2',
-                                displayName: 'Demo User',
-                                isAdmin: false
-                            }
-                        ]
-                    }
+                    group: 'group-data-controller'
                 },
                 {
                     uid: 'rule-execute',
                     path: '/SASjsApi/stp/execute',
                     type: 'Route',
                     setting: 'Grant',
-                    group: {
-                        uid: 'group-data-controller',
-                        name: 'DCGroup',
-                        description: 'Data Controller users',
-                        isActive: true,
-                        users: [
-                            {
-                                uid: RESTRICTED_UID,
-                                username: 'user2',
-                                displayName: 'Demo User',
-                                isAdmin: false
-                            }
-                        ]
-                    }
+                    group: 'group-data-controller'
                 },
                 {
                     uid: 'rule-code',
                     path: '/SASjsApi/code/execute',
                     type: 'Route',
                     setting: 'Deny',
-                    user: {
-                        uid: RESTRICTED_UID,
-                        username: 'user2',
-                        displayName: 'Demo User',
-                        isAdmin: false
-                    }
+                    user: RESTRICTED_UID
                 }
             ]
         }
@@ -846,7 +848,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: ADMIN,
             body: {
-                path: '/SASjsApi/code/lint',
+                path: '/SASjsApi/drive/folder',
                 type: 'Route',
                 setting: 'Grant',
                 principalType: 'user',
@@ -855,7 +857,7 @@ exports.RECORD_CORPUS = [
         },
         expect: {
             status: 200,
-            partial: { path: '/SASjsApi/code/lint', setting: 'Grant' }
+            partial: { path: '/SASjsApi/drive/folder', setting: 'Grant' }
         }
     },
     {
@@ -866,7 +868,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: ADMIN,
             body: {
-                path: '/SASjsApi/code/lint',
+                path: '/SASjsApi/drive/rename',
                 type: 'Route',
                 setting: 'Grant',
                 principalType: 'group',
@@ -876,9 +878,9 @@ exports.RECORD_CORPUS = [
         expect: {
             status: 200,
             partial: {
-                path: '/SASjsApi/code/lint',
+                path: '/SASjsApi/drive/rename',
                 setting: 'Grant',
-                group: { uid: 'group-data-controller', name: 'DCGroup' }
+                group: 'group-data-controller'
             }
         }
     },
@@ -890,7 +892,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: ADMIN,
             body: {
-                path: '/SASjsApi/code/lint',
+                path: '/SASjsApi/drive/deploy',
                 type: 'Route',
                 setting: 'Grant',
                 principalType: 'role',
@@ -910,7 +912,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: ADMIN,
             body: {
-                path: '/SASjsApi/code/lint',
+                path: '/SASjsApi/drive/folder',
                 type: 'Route',
                 setting: 'Grant',
                 principalType: 'user',
@@ -930,7 +932,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: RESTRICTED,
             body: {
-                path: '/SASjsApi/code/lint',
+                path: '/SASjsApi/drive/folder',
                 type: 'Route',
                 setting: 'Grant',
                 principalType: 'user',
@@ -947,7 +949,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: ADMIN,
             body: {
-                path: '/SASjsApi/code/lint',
+                path: '/SASjsApi/drive/rename',
                 type: 'Route',
                 setting: 'Grant',
                 principalType: 'group',
@@ -964,7 +966,7 @@ exports.RECORD_CORPUS = [
         request: {
             token: ADMIN,
             body: {
-                path: '/SASjsApi/info',
+                path: '/SASjsApi/drive/file',
                 type: 'Route',
                 setting: 'Grant',
                 principalType: 'group',

package/build/cjs/host/dispatch.js

@@ -219,6 +219,16 @@ const dispatch = async (services, routeId, request = {}) => {
                 status: 200,
                 body: await required().deleteUser(await caller(), { username: String(params.username ?? '') }, { password: body.password })
             };
+        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}':
@@ -322,6 +332,8 @@ const dispatch = async (services, routeId, request = {}) => {
 exports.dispatch = dispatch;
 /** Whether a route is one `dispatch` can answer today. */
 exports.HANDLED_ROUTES = [
+    'GET /SASjsApi/info/authorizedRoutes',
+    'GET /SASjsApi/info/myAuthorizedRoutes',
     'GET /SASjsApi/drive/file',
     'POST /SASjsApi/drive/file',
     'PATCH /SASjsApi/drive/file',

package/build/cjs/identity/fixture.js

@@ -57,7 +57,7 @@ exports.DEFAULT_IDENTITY = {
     permissions: [
         {
             uid: 'rule-routes',
-            path: '/SASjsApi/info',
+            path: '/SASjsApi/drive/file',
             type: 'Route',
             setting: 'Grant',
             group: 'group-data-controller'

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) {
@@ -113,25 +115,14 @@ const createRecordService = (store) => {
     const findBy = async (by) => by.uid !== undefined
         ? store.userById(by.uid)
         : store.userByName(by.username ?? '');
-    const permissionDetails = async (permission) => {
-        const response = {
-            uid: permission.uid,
-            path: permission.path,
-            type: permission.type,
-            setting: permission.setting
-        };
-        if (permission.user) {
-            const user = await store.userById(permission.user);
-            if (user)
-                response.user = asUser(user);
-        }
-        if (permission.group) {
-            const group = await store.groupById(permission.group);
-            if (group)
-                response.group = await groupDetails(group);
-        }
-        return response;
-    };
+    const permissionDetails = async (permission) => ({
+        uid: permission.uid,
+        path: permission.path,
+        type: permission.type,
+        setting: permission.setting,
+        ...(permission.user ? { user: permission.user } : {}),
+        ...(permission.group ? { group: permission.group } : {})
+    });
     return {
         async listUsers(caller) {
             await requireCaller(store, caller);
@@ -296,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

@@ -60,6 +60,8 @@ 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");

package/build/cjs/routes/overlay.js

@@ -30,7 +30,6 @@ const EDITOR = 'Linting and formatting come from @sasjs/lint, which this package
 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.";
@@ -177,16 +176,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/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,EA0oCrC,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"}