@sasjs/api 0.6.0 → 0.7.0

package/build/cjs/identity/records.js

@@ -0,0 +1,398 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRecordService = exports.sanitiseDisplayName = void 0;
+/**
+ * Users, groups, permission rules and clients: the administration routes'
+ * decisions, over the same store the sign-in flow uses.
+ *
+ * The server answers these from four controllers and two middlewares - the
+ * statuses, the messages and the order of the checks are copied from there, so a
+ * mock and a server refuse a request the same way. What stays with the host is
+ * the *transport* (a session or a bearer token, a CSRF token) and the things a
+ * host owns: a new user's home folder, a directory bind, an audit trail.
+ *
+ * The admin gate is here rather than in a caller because `dispatch` has no
+ * middleware: `requireAdmin` is `verifyAdmin`, and `requireSelfOrAdmin` is
+ * `verifyAdminIfNeeded`. Both answer `401 Admin account required`, which is what
+ * the server sends.
+ */
+const types_js_1 = require("../types.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. */
+const PUBLIC_GROUP = 'public';
+const unauthorized = () => new types_js_1.ApiError(401, 'Unauthorized');
+/**
+ * The caller, while the account behind it may still act.
+ *
+ * Every administration route reads the caller through this: the server
+ * re-reads the user on every request and refuses a deactivated account, so a
+ * token or session that outlived the account must not administer anything.
+ */
+const requireCaller = async (store, caller) => {
+    if (!caller)
+        throw unauthorized();
+    const user = await store.userById(caller.userId);
+    if (!user || !user.isActive)
+        throw unauthorized();
+    return user;
+};
+/** `verifyAdmin`: the caller is an administrator, or the route refuses. */
+const requireAdmin = async (store, caller) => {
+    const user = await requireCaller(store, caller);
+    if (!user.isAdmin)
+        throw new types_js_1.ApiError(401, 'Admin account required');
+    return user;
+};
+/**
+ * `verifyAdminIfNeeded`: an administrator, or the account being acted on.
+ *
+ * The server compares `req.params.uid` / `.username` with the caller's own
+ * identifier, which is why the target is passed in rather than read from the
+ * body - a restful route names its subject in the path.
+ */
+const requireSelfOrAdmin = async (store, caller, target) => {
+    const user = await requireCaller(store, caller);
+    if (!user.isAdmin && user.uid !== target?.uid)
+        throw new types_js_1.ApiError(401, 'Admin account required');
+    return user;
+};
+/**
+ * A display name, as the server stores one: control characters out, trimmed and
+ * bounded.
+ *
+ * The value reaches generated stored-program source and webout headers, so the
+ * server sanitises on the way in; a host that stored it verbatim would hold a
+ * different value from the server for the same request.
+ */
+const MAX_DISPLAY_NAME_LENGTH = 100;
+const sanitiseDisplayName = (value) => String(value ?? '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u001F\u007F]/g, '')
+    .trim()
+    .slice(0, MAX_DISPLAY_NAME_LENGTH);
+exports.sanitiseDisplayName = sanitiseDisplayName;
+const asUser = (user) => ({
+    uid: user.uid,
+    username: user.username,
+    displayName: user.displayName,
+    isAdmin: user.isAdmin
+});
+const asGroup = (group) => ({
+    uid: group.uid,
+    name: group.name,
+    description: group.description
+});
+const createRecordService = (store) => {
+    const groupDetails = async (group) => {
+        const members = [];
+        for (const uid of group.users) {
+            const user = await store.userById(uid);
+            if (user)
+                members.push(asUser(user));
+        }
+        return { ...asGroup(group), isActive: group.isActive, users: members };
+    };
+    const userDetails = async (user, withAutoExec) => {
+        const groups = [];
+        for (const uid of user.groups) {
+            const group = await store.groupById(uid);
+            if (group)
+                groups.push(asGroup(group));
+        }
+        const details = {
+            ...asUser(user),
+            isActive: user.isActive,
+            needsToUpdatePassword: user.needsToUpdatePassword,
+            groups
+        };
+        if (withAutoExec)
+            details.autoExec = user.autoExec ?? '';
+        return details;
+    };
+    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;
+    };
+    return {
+        async listUsers(caller) {
+            await requireCaller(store, caller);
+            const users = await store.users();
+            return users.map(asUser);
+        },
+        async getUser(caller, by) {
+            const reader = await requireCaller(store, caller);
+            const user = await findBy(by);
+            if (!user)
+                throw new types_js_1.ApiError(404, 'User is not found.');
+            // the server hands the auto-exec code to an administrator or to the user
+            // themselves and omits it for anyone else
+            const withAutoExec = reader.isAdmin || reader.uid === user.uid;
+            return userDetails(user, withAutoExec);
+        },
+        async createUser(caller, body) {
+            await requireAdmin(store, caller);
+            if (await store.userByName(body.username))
+                throw new types_js_1.ApiError(409, 'Username already exists.');
+            const created = await store.createUser({
+                username: body.username,
+                displayName: (0, exports.sanitiseDisplayName)(body.displayName),
+                isAdmin: body.isAdmin === true,
+                isActive: body.isActive !== false,
+                autoExec: body.autoExec
+            });
+            await store.setPassword(created.uid, body.password);
+            // the server adds every new account to the all-users group when the host
+            // has one, so a group-based grant reaches it without an explicit add
+            const allUsers = await store.groupByName(ALL_USERS_GROUP);
+            if (allUsers)
+                await store.addToGroup(allUsers.uid, created.uid);
+            const stored = await store.userById(created.uid);
+            return userDetails(stored ?? created, true);
+        },
+        async updateUser(caller, by, body) {
+            const current = await findBy(by);
+            await requireSelfOrAdmin(store, caller, current);
+            const change = {};
+            const displayName = (0, exports.sanitiseDisplayName)(body.displayName);
+            // the provider checks come before the uniqueness check and before the
+            // update, in the server's order: a provider-managed account cannot have
+            // its identity fields changed, and saying so does not depend on the new
+            // value being free
+            if (body.username &&
+                body.username !== current?.username &&
+                current?.authProvider)
+                throw new types_js_1.ApiError(405, 'Can not update username of user that is created by an external auth provider.');
+            if (displayName &&
+                displayName !== current?.displayName &&
+                current?.authProvider)
+                throw new types_js_1.ApiError(405, 'Can not update display name of user that is created by an external auth provider.');
+            if (body.username) {
+                const holder = await store.userByName(body.username);
+                if (holder && holder.uid !== current?.uid)
+                    throw new types_js_1.ApiError(409, 'Username already exists.');
+                change.username = body.username;
+            }
+            if (displayName)
+                change.displayName = displayName;
+            if (body.isAdmin !== undefined)
+                change.isAdmin = body.isAdmin;
+            if (body.isActive !== undefined)
+                change.isActive = body.isActive;
+            if (body.autoExec !== undefined)
+                change.autoExec = body.autoExec;
+            const updated = current
+                ? await store.updateUser(current.uid, change)
+                : undefined;
+            if (!updated)
+                throw new types_js_1.ApiError(404, `Unable to find user with ${by.uid || by.username}`);
+            if (body.password)
+                await store.setPassword(updated.uid, body.password);
+            const stored = await store.userById(updated.uid);
+            return userDetails(stored ?? updated, true);
+        },
+        async deleteUser(caller, by, body) {
+            const current = await findBy(by);
+            const actor = await requireSelfOrAdmin(store, caller, current);
+            if (!current)
+                throw new types_js_1.ApiError(404, 'User is not found.');
+            // an administrator deletes without proving the password; anyone else
+            // deleting their own account proves it. The caller's admin flag is the
+            // server's `@Hidden() isAdmin` query parameter, resolved here from the
+            // caller's own record rather than trusted from the request.
+            if (!actor.isAdmin) {
+                if (!(await store.passwordMatches(current, body.password ?? '')))
+                    throw new types_js_1.ApiError(401, 'Invalid password.');
+            }
+            await store.deleteUser(current.uid);
+        },
+        async listGroups(caller) {
+            await requireCaller(store, caller);
+            const groups = await store.groups();
+            return groups.map(asGroup);
+        },
+        async getGroup(caller, by) {
+            await requireCaller(store, caller);
+            const group = by.uid !== undefined
+                ? await store.groupById(by.uid)
+                : await store.groupByName(by.name ?? '');
+            if (!group)
+                throw new types_js_1.ApiError(404, 'Group not found.');
+            return groupDetails(group);
+        },
+        async createGroup(caller, body) {
+            await requireAdmin(store, caller);
+            if (await store.groupByName(body.name))
+                throw new types_js_1.ApiError(409, 'Group name already exists.');
+            const created = await store.createGroup({
+                name: body.name,
+                description: body.description,
+                isActive: body.isActive !== false
+            });
+            return groupDetails(created);
+        },
+        async deleteGroup(caller, uid) {
+            await requireAdmin(store, caller);
+            if (!(await store.groupById(uid)))
+                throw new types_js_1.ApiError(404, 'Group not found.');
+            await store.deleteGroup(uid);
+        },
+        async addUserToGroup(caller, groupUid, userUid) {
+            await requireAdmin(store, caller);
+            const group = await store.groupById(groupUid);
+            if (!group)
+                throw new types_js_1.ApiError(404, 'Group not found.');
+            if (group.name === PUBLIC_GROUP)
+                throw new types_js_1.ApiError(400, `Can't add/remove user to '${PUBLIC_GROUP}' group.`);
+            if (group.authProvider)
+                throw new types_js_1.ApiError(405, "Can't add/remove user to group created by external auth provider.");
+            const user = await store.userById(userUid);
+            if (!user)
+                throw new types_js_1.ApiError(404, 'User not found.');
+            if (user.authProvider)
+                throw new types_js_1.ApiError(405, "Can't add/remove user to group created by external auth provider.");
+            const updated = await store.addToGroup(groupUid, userUid);
+            if (!updated)
+                throw new types_js_1.ApiError(400, 'Unable to update group.');
+            return groupDetails(updated);
+        },
+        async removeUserFromGroup(caller, groupUid, userUid) {
+            await requireAdmin(store, caller);
+            const group = await store.groupById(groupUid);
+            if (!group)
+                throw new types_js_1.ApiError(404, 'Group not found.');
+            if (group.name === PUBLIC_GROUP)
+                throw new types_js_1.ApiError(400, `Can't add/remove user to '${PUBLIC_GROUP}' group.`);
+            if (group.authProvider)
+                throw new types_js_1.ApiError(405, "Can't add/remove user to group created by external auth provider.");
+            const user = await store.userById(userUid);
+            if (!user)
+                throw new types_js_1.ApiError(404, 'User not found.');
+            if (user.authProvider)
+                throw new types_js_1.ApiError(405, "Can't add/remove user to group created by external auth provider.");
+            const updated = await store.removeFromGroup(groupUid, userUid);
+            if (!updated)
+                throw new types_js_1.ApiError(400, 'Unable to update group.');
+            return groupDetails(updated);
+        },
+        async listPermissions(caller) {
+            const reader = await requireCaller(store, caller);
+            const rules = await store.permissions();
+            // an administrator sees every rule; anyone else sees the rules assigned to
+            // them and to the groups they belong to, which is what an app renders its
+            // menus from
+            const visible = reader.isAdmin
+                ? rules
+                : rules.filter((rule) => rule.user === reader.uid ||
+                    (rule.group !== undefined && reader.groups.includes(rule.group)));
+            const out = [];
+            for (const rule of visible)
+                out.push(await permissionDetails(rule));
+            return out;
+        },
+        async createPermission(caller, body) {
+            await requireAdmin(store, caller);
+            if (body.principalType === 'user') {
+                const user = await store.userById(body.principalId);
+                if (!user)
+                    throw new types_js_1.ApiError(404, 'User not found.');
+                if (user.isAdmin)
+                    throw new types_js_1.ApiError(400, 'Can not add permission for admin user.');
+                const exists = (await store.permissions()).some((rule) => rule.path === body.path &&
+                    rule.type === body.type &&
+                    rule.user === body.principalId);
+                if (exists)
+                    throw new types_js_1.ApiError(409, 'Permission already exists with provided Path, Type and User.');
+                const created = await store.createPermission({
+                    path: body.path,
+                    type: body.type,
+                    setting: body.setting,
+                    user: body.principalId
+                });
+                return permissionDetails(created);
+            }
+            if (body.principalType === 'group') {
+                const group = await store.groupById(body.principalId);
+                if (!group)
+                    throw new types_js_1.ApiError(404, 'Group not found.');
+                const exists = (await store.permissions()).some((rule) => rule.path === body.path &&
+                    rule.type === body.type &&
+                    rule.group === body.principalId);
+                if (exists)
+                    throw new types_js_1.ApiError(409, 'Permission already exists with provided Path, Type and Group.');
+                const created = await store.createPermission({
+                    path: body.path,
+                    type: body.type,
+                    setting: body.setting,
+                    group: body.principalId
+                });
+                return permissionDetails(created);
+            }
+            throw new types_js_1.ApiError(400, 'Invalid principal type. Valid types are user or group.');
+        },
+        async updatePermission(caller, uid, body) {
+            await requireAdmin(store, caller);
+            const updated = await store.setPermissionSetting(uid, body.setting);
+            if (!updated)
+                throw new types_js_1.ApiError(404, 'Permission not found.');
+            return permissionDetails(updated);
+        },
+        async deletePermission(caller, uid) {
+            await requireAdmin(store, caller);
+            if (!(await store.permissionById(uid)))
+                throw new types_js_1.ApiError(404, 'Permission not found.');
+            await store.deletePermission(uid);
+        },
+        async listClients(caller) {
+            await requireAdmin(store, caller);
+            return store.clients();
+        },
+        async createClient(caller, body) {
+            await requireAdmin(store, caller);
+            // the server answers `res.status(403).send(err.toString())`, so the body a
+            // client receives carries the Error prefix
+            if (await store.client(body.clientId))
+                throw new types_js_1.ApiError(403, 'Error: Client ID already exists.');
+            return store.createClient({
+                clientId: body.clientId,
+                clientSecret: body.clientSecret,
+                accessTokenExpiration: body.accessTokenExpiration,
+                refreshTokenExpiration: body.refreshTokenExpiration
+            });
+        },
+        async updatePassword(caller, body) {
+            // requireCaller answers 401 for a caller that is absent or deactivated, so
+            // the document's 404 (a caller whose record has gone) cannot be reached
+            // here - the overlay records that as a host-only status.
+            const reader = await requireCaller(store, caller);
+            if (reader.authProvider)
+                throw new types_js_1.ApiError(405, 'Can not update password of user that is created by an external auth provider.');
+            if (!(await store.passwordMatches(reader, body.currentPassword)))
+                throw new types_js_1.ApiError(403, 'Invalid current password!');
+            await store.setPassword(reader.uid, body.newPassword);
+            // the flag is what makes the web interface ask, and the server clears it in
+            // the same write: it has to go through the store, or a host keeps refusing
+            // every call the caller makes after the change
+            await store.updateUser(reader.uid, { needsToUpdatePassword: false });
+        }
+    };
+};
+exports.createRecordService = createRecordService;

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.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = 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.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.
  *
@@ -62,6 +62,9 @@ Object.defineProperty(exports, "dispatch", { enumerable: true, get: function ()
 Object.defineProperty(exports, "HANDLED_ROUTES", { enumerable: true, get: function () { return dispatch_js_1.HANDLED_ROUTES; } });
 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 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");
@@ -72,6 +75,10 @@ var drive_js_1 = require("./corpus/drive.js");
 Object.defineProperty(exports, "DRIVE_CORPUS", { enumerable: true, get: function () { return drive_js_1.DRIVE_CORPUS; } });
 var identity_js_1 = require("./corpus/identity.js");
 Object.defineProperty(exports, "IDENTITY_CORPUS", { enumerable: true, get: function () { return identity_js_1.IDENTITY_CORPUS; } });
+var records_js_2 = require("./corpus/records.js");
+Object.defineProperty(exports, "RECORD_CORPUS", { enumerable: true, get: function () { return records_js_2.RECORD_CORPUS; } });
+Object.defineProperty(exports, "ADMIN_SIGNED_IN", { enumerable: true, get: function () { return records_js_2.ADMIN_SIGNED_IN; } });
+Object.defineProperty(exports, "PROVIDER_MANAGED", { enumerable: true, get: function () { return records_js_2.PROVIDER_MANAGED; } });
 var runner_js_1 = require("./corpus/runner.js");
 Object.defineProperty(exports, "runCase", { enumerable: true, get: function () { return runner_js_1.runCase; } });
 Object.defineProperty(exports, "servicesFor", { enumerable: true, get: function () { return runner_js_1.servicesFor; } });