@transmit-security/rbac 1.0.0-beta

package/README.md

@@ -0,0 +1,18 @@
+# @transmit-security/rbac
+
+RBAC impl of Transmt sec
+
+### Usage
+
+```js
+import { Permission, Action, AppResourceDefinition } from '@transmit-security/rbac';
+
+const userPermission = new Permission(Action.read, AppResourceDefinition);
+
+if (userPermission.allows([Action.write, AppResourceDefinition.type])) {
+  // perform the operation
+} else {
+  // return error
+}
+
+```

package/dist/src/definitions/action.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Action = void 0;
+var Action;
+(function (Action) {
+    /** Create a resource. */
+    Action["create"] = "create";
+    /** Read a single resource. This should not allow searching or listing similar resources, only reading a specific one.
+     for example, this can be used for the `/users/:id` endpoint, but not for `/users` (at least not without additional actions).
+     */
+    Action["read"] = "read";
+    /** Edit a single resource. This should not allow deleting that resource or creating similar resources. */
+    Action["edit"] = "edit";
+    /** Delete resources. This can be used for bulk-delete as well. */
+    Action["delete"] = "delete";
+    /** List resources. This should be used for list and search endpoints, where resource IDs or resource details are returned without
+     * their IDs being known to the caller. for example, if the `/users` endpoint returns a list of all user IDs, this can be used to
+     * guard it. but this should not be used for `/users/:id`.
+     *
+     * If an endpoint returns not just resource IDs but also some details (e.g search users which returns name and email), then the
+     * endpoint should be guarded by the `read` permission as well as `list`.
+     */
+    Action["list"] = "list";
+    /** Execute a resource. Currently the only resources we can execute are FlexId journeys, but perhaps in the future we'll extend
+     * this capability to users who complain too much.
+     */
+    Action["execute"] = "execute";
+    /** All actions. This grants the ability to perform any of the other actions. */
+    Action["all"] = "*";
+})(Action || (exports.Action = Action = {}));
+//# sourceMappingURL=action.js.map

package/dist/src/definitions/resources/administration-resources.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdministrationResourceDefinition = void 0;
+exports.AdministrationResourceDefinition = {
+    type: 'simple',
+    id: 'administration',
+    children: {
+        adminUsers: { type: 'collection', id: 'admin-users', key: 'adminId' },
+        adminRoles: { type: 'collection', id: 'admin-roles', key: 'roleId' },
+    },
+};
+//# sourceMappingURL=administration-resources.js.map

package/dist/src/definitions/resources/app-resources.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppResourceDefinition = void 0;
+exports.AppResourceDefinition = {
+    type: 'collection',
+    id: 'apps',
+    key: 'appId',
+    children: {
+        config: {
+            type: 'simple',
+            id: 'config',
+            children: {
+                idv: {
+                    type: 'simple',
+                    id: 'idv',
+                    children: {
+                        identityExperienceManagement: {
+                            type: 'simple',
+                            id: 'identity-experience-management',
+                            children: {
+                                settings: { type: 'simple', id: 'settings' },
+                                consent: { type: 'simple', id: 'consent' },
+                                branding: { type: 'simple', id: 'branding' },
+                            },
+                        },
+                        identityRestrictionCriteria: {
+                            type: 'simple',
+                            id: 'identity-restriction-criteria',
+                        },
+                    },
+                },
+                drs: {
+                    type: 'simple',
+                    id: 'drs',
+                    children: {
+                        privateIdentifier: { type: 'simple', id: 'private-identifier' },
+                    },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=app-resources.js.map

package/dist/src/definitions/resources/drs-resources.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.drsResourceDefinition = void 0;
+exports.drsResourceDefinition = {
+    type: 'simple',
+    id: 'drs',
+    children: {
+        recommendations: {
+            type: 'simple',
+            id: 'recommendations',
+            children: {
+                export: { type: 'simple', id: 'export' },
+            },
+        },
+        list: {
+            type: 'collection',
+            id: 'list',
+            key: 'listId',
+            children: {
+                items: { type: 'collection', id: 'items', key: 'itemId' },
+            },
+        },
+        label: {
+            type: 'simple',
+            id: 'label',
+            children: {
+                bulk: { type: 'simple', id: 'bulk' },
+            },
+        },
+        customActionType: { type: 'simple', id: 'custom-action-type' },
+        detectionSensitivityConfiguration: {
+            type: 'simple',
+            id: 'detection-sensitivity-configuration',
+            children: {
+                preview: { type: 'simple', id: 'preview' },
+                production: { type: 'simple', id: 'production' },
+            },
+        },
+        rule: {
+            type: 'collection',
+            id: 'rule',
+            key: 'ruleId',
+            children: {
+                preview: { type: 'simple', id: 'preview' },
+                production: { type: 'simple', id: 'production' },
+            },
+        },
+        preview: { type: 'simple', id: 'preview' },
+        securityInsights: { type: 'simple', id: 'security-insights' },
+        automatedWorkflows: { type: 'simple', id: 'automated-workflows' },
+    },
+};
+//# sourceMappingURL=drs-resources.js.map

package/dist/src/definitions/resources/events-resources.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsResourceDefinition = void 0;
+exports.EventsResourceDefinition = {
+    type: 'simple',
+    id: 'events',
+    children: {
+        userActivities: {
+            type: 'collection',
+            id: 'user-activities',
+            key: 'userActivityId',
+        },
+        adminActivities: {
+            type: 'collection',
+            id: 'admin-activities',
+            key: 'adminActivityId',
+        },
+    },
+};
+//# sourceMappingURL=events-resources.js.map

package/dist/src/definitions/resources/idv-resources.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.idvResourceDefinition = void 0;
+exports.idvResourceDefinition = {
+    type: 'simple',
+    id: 'idv',
+    children: {
+        identityVerifications: {
+            type: 'collection',
+            id: 'identity-verifications',
+            key: 'verificationId',
+            children: {
+                status: { type: 'simple', id: 'status' },
+                images: { type: 'collection', id: 'images', key: 'imageId' },
+                result: { type: 'simple', id: 'result' },
+                labels: { type: 'simple', id: 'labels' },
+            },
+        },
+        blocklist: {
+            type: 'simple',
+            id: 'blocklist',
+            children: {
+                faces: { type: 'collection', id: 'faces', key: 'entryId' },
+            },
+        },
+        analytics: {
+            type: 'simple',
+            id: 'analytics',
+        },
+    },
+};
+//# sourceMappingURL=idv-resources.js.map

package/dist/src/definitions/resources/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oidcResources = exports.serviceProviders = exports.orc = exports.drs = exports.events = exports.idv = exports.users = exports.organization = exports.administration = exports.apps = void 0;
+const resource_class_builder_1 = require("../../infra/resource-class-builder");
+const administration_resources_1 = require("./administration-resources");
+const app_resources_1 = require("./app-resources");
+const organization_resources_1 = require("./organization-resources");
+const user_resources_1 = require("./user-resources");
+const idv_resources_1 = require("./idv-resources");
+const events_resources_1 = require("./events-resources");
+const drs_resources_1 = require("./drs-resources");
+const service_provider_resources_1 = require("./service-provider-resources");
+const oidc_resource_resources_1 = require("./oidc-resource-resources");
+const orc_resources_1 = require("./orc-resources");
+/*
+Resources definition are split into files for better change isolation. as
+this project matures, we can consider merging all definitions into a single
+file for ease of use.
+*/
+exports.apps = (0, resource_class_builder_1.buildResourceClass)(app_resources_1.AppResourceDefinition);
+exports.administration = (0, resource_class_builder_1.buildResourceClass)(administration_resources_1.AdministrationResourceDefinition);
+exports.organization = (0, resource_class_builder_1.buildResourceClass)(organization_resources_1.organizationsResourceDefinition);
+exports.users = (0, resource_class_builder_1.buildResourceClass)(user_resources_1.userResourceDefinition);
+exports.idv = (0, resource_class_builder_1.buildResourceClass)(idv_resources_1.idvResourceDefinition);
+exports.events = (0, resource_class_builder_1.buildResourceClass)(events_resources_1.EventsResourceDefinition);
+exports.drs = (0, resource_class_builder_1.buildResourceClass)(drs_resources_1.drsResourceDefinition);
+exports.orc = (0, resource_class_builder_1.buildResourceClass)(orc_resources_1.orcResourceDefinitions);
+exports.serviceProviders = (0, resource_class_builder_1.buildResourceClass)(service_provider_resources_1.serviceProviderResourceDefinition);
+exports.oidcResources = (0, resource_class_builder_1.buildResourceClass)(oidc_resource_resources_1.oidcResourceResourceDefinition);
+//# sourceMappingURL=index.js.map

package/dist/src/definitions/resources/oidc-resource-resources.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oidcResourceResourceDefinition = void 0;
+exports.oidcResourceResourceDefinition = {
+    type: 'collection',
+    id: 'resources',
+    key: 'resourceId',
+};
+//# sourceMappingURL=oidc-resource-resources.js.map

package/dist/src/definitions/resources/orc-resources.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orcResourceDefinitions = void 0;
+exports.orcResourceDefinitions = {
+    type: 'simple',
+    id: 'orc',
+    children: {
+        journeys: {
+            type: 'simple',
+            id: 'journeys',
+        },
+        connections: {
+            type: 'simple',
+            id: 'connections',
+        },
+        lists: {
+            type: 'simple',
+            id: 'lists',
+        },
+        identities: {
+            type: 'simple',
+            id: 'identities',
+        },
+    },
+};
+//# sourceMappingURL=orc-resources.js.map

package/dist/src/definitions/resources/organization-resources.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.organizationsResourceDefinition = void 0;
+exports.organizationsResourceDefinition = {
+    type: 'simple',
+    id: 'organizations',
+    children: {
+        orgs: { type: 'simple', id: 'orgs' },
+        roles: { type: 'simple', id: 'roles' },
+    },
+};
+//# sourceMappingURL=organization-resources.js.map

package/dist/src/definitions/resources/service-provider-resources.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceProviderResourceDefinition = void 0;
+exports.serviceProviderResourceDefinition = {
+    type: 'collection',
+    id: 'service-providers',
+    key: 'serviceProviderId',
+};
+//# sourceMappingURL=service-provider-resources.js.map

package/dist/src/definitions/resources/user-resources.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userResourceDefinition = void 0;
+exports.userResourceDefinition = {
+    type: 'collection',
+    id: 'users',
+    key: 'userId',
+};
+//# sourceMappingURL=user-resources.js.map

package/dist/src/index.js

@@ -0,0 +1,53 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wildcardPrimitive = exports.wildcard = exports.resourceClassRegistry = exports.build = exports.Resource = exports.placeholder = exports.Permission = exports.Action = exports.permissions = exports.resources = void 0;
+const resources = __importStar(require("./definitions/resources"));
+exports.resources = resources;
+const permission_selector_builder_1 = require("./infra/permission-selector-builder");
+/** A reference to all the actions and resources in the RBAC system. You can
+ *  use this instead of creating permissions and resource instances
+ * manually.
+ *
+ * example:
+ * ```
+ * permissions.create.Users()
+ * ```*/
+exports.permissions = (0, permission_selector_builder_1.buildPermissionSelector)(resources);
+var action_1 = require("./definitions/action");
+Object.defineProperty(exports, "Action", { enumerable: true, get: function () { return action_1.Action; } });
+var permission_1 = require("./infra/permission");
+Object.defineProperty(exports, "Permission", { enumerable: true, get: function () { return permission_1.Permission; } });
+var placeHolders_1 = require("./infra/placeHolders");
+Object.defineProperty(exports, "placeholder", { enumerable: true, get: function () { return placeHolders_1.placeholder; } });
+var resource_1 = require("./infra/resource");
+Object.defineProperty(exports, "Resource", { enumerable: true, get: function () { return resource_1.Resource; } });
+exports.build = __importStar(require("./infra/resource-class-builder"));
+var resource_registry_1 = require("./infra/resource-registry");
+Object.defineProperty(exports, "resourceClassRegistry", { enumerable: true, get: function () { return resource_registry_1.resourceClassRegistry; } });
+var wildcard_1 = require("./infra/wildcard");
+Object.defineProperty(exports, "wildcard", { enumerable: true, get: function () { return wildcard_1.wildcard; } });
+Object.defineProperty(exports, "wildcardPrimitive", { enumerable: true, get: function () { return wildcard_1.wildcardPrimitive; } });
+//# sourceMappingURL=index.js.map

package/dist/src/infra/permission-selector-builder.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPermissionSelector = void 0;
+const action_1 = require("../definitions/action");
+const permission_1 = require("./permission");
+const placeHolders_1 = require("./placeHolders");
+const wildcard_1 = require("./wildcard");
+function buildPermissionTree(resourceClass, action, parentKeys, keyValues) {
+    const result = {};
+    let childKeys = { ...parentKeys };
+    let entityKeys = { ...parentKeys };
+    if (resourceClass.definition.type === 'collection') {
+        let keyValue = keyValues
+            ? keyValues[resourceClass.definition.key]
+            : undefined;
+        if (keyValue === placeHolders_1.placeholder) {
+            keyValue = (0, placeHolders_1.getPlaceHolderString)(resourceClass.definition.key);
+        }
+        childKeys[resourceClass.definition.key] = keyValue || wildcard_1.wildcard;
+        entityKeys[resourceClass.definition.key] = keyValue || undefined;
+    }
+    Object.getOwnPropertyNames(resourceClass).forEach((propName) => {
+        const value = resourceClass[propName];
+        if (typeof value === 'function') {
+            if ('definition' in value) {
+                result[propName] = buildPermissionTree(value, action, childKeys, keyValues);
+            }
+        }
+    });
+    childKeys['childPermission'] = resourceClass.definition.id;
+    const selectable = {
+        permission: new permission_1.Permission(action, new resourceClass(entityKeys)),
+        childPermission: new permission_1.Permission(action, new resourceClass(childKeys)),
+    };
+    Object.assign(result, selectable);
+    return result;
+}
+function buildPermissionSelector(resourceTree, keyValues) {
+    return Object.entries(action_1.Action).reduce((selector, [actionName, actionValue]) => {
+        const resources = Object.entries(resourceTree).reduce((acc, [key, value]) => {
+            const tree = buildPermissionTree(value, actionValue, {}, keyValues);
+            acc[key] = tree;
+            return acc;
+        }, {});
+        selector[actionName] = resources;
+        return selector;
+    }, {});
+}
+exports.buildPermissionSelector = buildPermissionSelector;
+//# sourceMappingURL=permission-selector-builder.js.map

package/dist/src/infra/permission.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Permission = void 0;
+const action_1 = require("../definitions/action");
+const is_valid_enum_value_1 = require("../utils/is-valid-enum-value");
+const resource_1 = require("./resource");
+class Permission {
+    constructor(action, resource) {
+        this.action = action;
+        this.resource = resource;
+    }
+    static parse(permissionString) {
+        const segments = permissionString.split(':');
+        if (segments.length !== 2 || segments.some((s) => s.length === 0))
+            return {
+                success: false,
+                error: `Invalid format - should be 'action:resource'`,
+            };
+        const action = segments[0];
+        if (!(0, is_valid_enum_value_1.isValidEnumValue)(action_1.Action, action))
+            return { success: false, error: `Invalid action: '${segments[0]}'` };
+        const parseRes = resource_1.Resource.parse(segments[1]);
+        if (!parseRes.success)
+            return {
+                success: false,
+                error: `Cannot parse resource: ${parseRes.error}`,
+            };
+        const { resource } = parseRes;
+        return {
+            success: true,
+            permission: new Permission(action, resource),
+        };
+    }
+    /** Checks if this permission is granted by any of the provided permissions.
+     *
+     * When permission validation fails, it's recommended to log the required and provided permissions for easy debugging.
+     *
+     * note: by default, invalid permissions are ignored. you can adjust this behavior using the options parameter, or
+     * parse and check the permissions yourself using `Permission.parse`.
+     */
+    isAllowedBy(providedPermissions, options) {
+        for (const permission of providedPermissions) {
+            if (typeof permission === 'string') {
+                const parseRes = Permission.parse(permission);
+                if (!parseRes.success) {
+                    if (options.onParsingError === 'throw') {
+                        throw new Error(parseRes.error);
+                    }
+                }
+                else if (parseRes.permission.allows(this)) {
+                    return true;
+                }
+            }
+            else if (permission.allows(this)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Checks if this permission allows the operation described by the other permission.
+     *
+     * example:
+     * ```
+     * if (tokenPermission.allows(requiredPermission)) {
+     *   // perform the operation
+     * } else {
+     *   // return error
+     * }
+     * ```
+     */
+    allows(other) {
+        if (this.action !== action_1.Action.all && this.action !== other.action)
+            return false;
+        if (!this.resource.owns(other.resource))
+            return false;
+        return true;
+    }
+    toString() {
+        return `${this.action}:${this.resource.toString()}`;
+    }
+}
+exports.Permission = Permission;
+//# sourceMappingURL=permission.js.map

package/dist/src/infra/placeHolders.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPlaceHolderString = exports.placeholder = void 0;
+exports.placeholder = 'PLACEHOLDER';
+const getPlaceHolderString = (key) => `[${key}]`;
+exports.getPlaceHolderString = getPlaceHolderString;
+//# sourceMappingURL=placeHolders.js.map

package/dist/src/infra/resource-class-builder.js

@@ -0,0 +1,277 @@
+"use strict";
+/*
+
+The purpose of this file is to provide a way to build resource classes, from a
+data structure that's as simple as possible.
+
+## General idea
+
+recommended reading:
+https://cloud.google.com/apis/design/resource_names
+
+Resource classes are typescript classes which represent a specific type of resources,
+and are used to create instances of those resources for things like permission checks
+or data access. At the lowest level a resource is just a string, but we want to provide
+a move convenient mechanism to work with them.
+
+Resource classes have several requirements:
+
+1. provide a string that represents the resource
+2. ensure all placeholder values are filled in when creating an instance
+  e.g if the resource is `apps/$appId/users/$userId`, then when creating an instance,
+  both `appId` and `userId` must be provided.
+3. provide a way to reference a resource class (not instance) via a string
+  i.e if a client tells a server "I want to access the `users` resource", the server
+  should be able to understand which resource class that is.
+4. provide a convenient way to create child resources from a parent resource
+
+
+The end result is a bunch of classes that look kinda like this:
+```
+class Apps {
+  constructor(public appId: string) { }
+  toString() { return `apps/${this.appId}` }
+
+  users(userId: string) { return new AppUsers(this.appId, userId); }
+}
+
+class AppUsers {
+  constructor(public appId: string, public userId: string) { }
+  toString() { return `apps/${this.appId}/users/${this.userId}` }
+}
+```
+
+the ONLY thing that matters is that end result. the implementation of the
+builder is free to change and evolve - we can even generate the classes
+at build time using a code generator, or even remove automatic generation
+entirely and just write the classes manually.
+
+## Implementation
+
+The implementation is based on a recursive function that builds the classes
+from a data structure that represents the resource.
+
+Due to all the type manipulation, the implementation is a bit complex -
+we have the types which facilitate the type manipulation, and the actual code
+that builds the classes. That's 2 parallel flows of data. We try to use them
+together as much as possible to get type safety, but in some cases it's
+technically impossible to get type info, so we resort to `any` and make sure
+that area covered by tests.
+
+The entry point for the type definitions is the `ResourceClassFromDef` type,
+which takes in a `ResourceDefNode` type and builds a class from it, with the
+the collections keys and child resource if any. see the jsdoc on the type
+itself for details.
+
+The entry point for the actual code is the `buildResourceClass` function,
+which takes in a `ResourceDefNode` instance and returns a class built from it,
+also with the correct collection keys and child resources. here too, see the
+jsdoc for details.
+
+## Some future ideas
+
+### non-class references
+
+there's no real reason that `Apps.Users` (for example) has to be the users
+class - all we need from it is the template, since we can build an instance
+using `new Apps().users()`. Populating those props with something that holds
+a template string and child objects, instead of a class, will make them easier
+to explore since they won't have the other methods that functions have.
+
+### inherently type-checked collection keys
+
+when building the type of an anon object (`{a:"str"}`), typescript sets the
+type of primitive properties to their full type even when a fixed value is
+provided. so the example's type would be `{a: string}` and not `{a:"str"}`.
+for this reason, users of the builder have to add `as const` to their
+definitions - without it, collection keys would be just any string and not
+specifically the provided key.
+we could instead change the api to get collection keys as object keys, not as
+strings: `{key: {userId: string}}` instead of `{key: "userId"}`. with this,
+there's no need to `as const` since string fields are not used for type
+inference.
+
+
+### id-based resource types
+
+instead of simple and collection resource definitions, we can use ids like
+`apps` and `apps/$appId` and automatically determine if it's a collection.
+see https://www.typescriptlang.org/play/?#code/C4TwDgpgBAyglgWzAGwgSQCZQLxQM7ABOcAdgOYBQokUAwgPbKoDGwc9JmAPAHICGCaBAAewCCQx58RUmQA0UANIQQ-QVBFiJUgsXIA+HFAAGAEgDeaiAF8A9KYvLVAm8YruAZgFcSrdiSgyCGAuABUNUXFJOkYWNg5uPhIQBSSQQwAfWEQUdAx9AAoKKBLpQgAuKFCKAEpK8M0oqQYmCD8EjC5SDwhCKCsFbt6lFStDYtKAfihzaghKgCJmWLb4kgWFEhdKgagAa1HtkedBaygJksrzKDnFvBzUDagtwXqzinMLqEJgr0IA8xnPhSNIUazuCjLEgEfAPaC4ILAAoLLx4Xp4BY1Ci2WylPEAPUmkI4MOWrXaAQRwWRqPR9lphEwmOxuIJRIhQA
+this will make the definitions a lot simpler, but is also a bit less discoverable -
+the type system won't tell you that you can create a collection that way.
+can consider this when there are more resources to use as reference.
+
+### fluent builder
+
+instead of passing an object to the constructor, we can use a fluent builder.
+this will allow greater flexibility in the future, and will avoid the need for `as const`.
+downside is that it can get pretty verbose, and will require a lot of boilerplate.
+
+
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidKeyForCollection = exports.MissingKeyForCollection = exports.buildResourceClass = void 0;
+const resource_1 = require("./resource");
+const resource_registry_1 = require("./resource-registry");
+const wildcard_1 = require("./wildcard");
+function getTemplatePath(res) {
+    return res.type === 'simple' ? [res.id] : [res.id, `$${res.key}`];
+}
+function buildResourceClassCommon(source, parentDefinitions) {
+    const parentPath = parentDefinitions.map(getTemplatePath).flat();
+    const fullPath = [...parentPath, ...getTemplatePath(source)];
+    return {
+        template: fullPath,
+        templateStr: fullPath.join(resource_1.Resource.separator),
+        definition: source,
+    };
+}
+function buildResourceConstructor(source, parents) {
+    switch (source.type) {
+        case 'simple':
+            return class SimpleResource extends resource_1.Resource {
+                constructor(input) {
+                    super(buildResourcePath([...parents, source], input));
+                }
+            };
+        case 'collection':
+            return class CollectionResource extends resource_1.Resource {
+                constructor(input) {
+                    super(buildResourcePath([...parents, source], input));
+                }
+            };
+    }
+}
+/** Builds the properties that provide the child resource.
+ *
+ * e.g with `new Apps.Users({appId:"123", userId:"456"})` - this function
+ * had built the `Users` static property on the `Apps` class.
+ *
+ * The returned object should be merged with the parent class.
+ */
+function buildChildResourceStaticProperties(childClasses) {
+    const propMap = {};
+    for (const [key, childClass] of Object.entries(childClasses)) {
+        propMap[key] = { get: () => childClass };
+    }
+    return propMap;
+}
+/** Builds the methods that create child resource from a parent resource.
+ *
+ * e.g with `new Apps("someAppId").users("someUserId")` - this function
+ * had built the `users` method on the `Apps` class.
+ *
+ * The returned object should be merged with the parent class prototype.
+ */
+function buildChildResourceInstanceMethods(childClasses, definitions) {
+    const propMap = {};
+    for (const [key, childClass] of Object.entries(childClasses)) {
+        const childDefinition = childClass.definition;
+        propMap[key] = {
+            get() {
+                let input = gatherInput(this, definitions);
+                return childDefinition.type == 'simple'
+                    ? (childResource) => new childClass({ ...input, childResource })
+                    : (id, childResource) => new childClass({
+                        ...input,
+                        [childDefinition.key]: id,
+                        childResource,
+                    });
+            },
+        };
+    }
+    return propMap;
+}
+function build(source, parentDefinitions) {
+    /*
+    we're gonna do dynamic stuff here, so to maintain type safety as much as possible,
+    we'll create the components of a resource class separately, and then combine them.
+     */
+    const resourceClass = buildResourceConstructor(source, parentDefinitions);
+    Object.assign(resourceClass, buildResourceClassCommon(source, parentDefinitions));
+    if (source.children) {
+        const childParents = [...parentDefinitions, source];
+        const childClassesRecord = Object.entries(source.children).reduce((acc, [key, childDefinition]) => {
+            acc[key] = build(childDefinition, childParents);
+            return acc;
+        }, {});
+        Object.defineProperties(resourceClass, buildChildResourceStaticProperties(childClassesRecord));
+        Object.defineProperties(resourceClass.prototype, buildChildResourceInstanceMethods(childClassesRecord, childParents));
+    }
+    resource_registry_1.resourceClassRegistry.register(resourceClass.templateStr);
+    return resourceClass;
+}
+/** returns an object with the inputs used to build it and each parent.
+ * simple (non-collection) resources are not included in the output since they don't have inputs.
+ *
+ * example -
+ * for resource `apps/123/users/456` (assuming template `apps/$appId/users/$userId`),
+ * this will return `{appId: "123", userId: "456"}`
+ */
+function gatherInput(source, definitions) {
+    const remainingPath = [...source.path];
+    return definitions.reduce((acc, def) => {
+        remainingPath.shift();
+        if (def.type === 'collection') {
+            const key = remainingPath.shift();
+            if (key === wildcard_1.wildcardPrimitive) {
+                acc[def.key] = wildcard_1.wildcard;
+            }
+            else {
+                acc[def.key] = key;
+            }
+        }
+        return acc;
+    }, {});
+}
+function buildResourcePath(resources, input = {}) {
+    const lastResource = resources[resources.length - 1];
+    return resources.reduce((acc, res) => {
+        if (res.type === 'simple') {
+            if (input.childPermission === res.id ||
+                (res.id === lastResource.id && input.childResource)) {
+                return [...acc, res.id, wildcard_1.wildcardPrimitive];
+            }
+            return [...acc, res.id];
+        }
+        else {
+            if (!(res.key in input))
+                return [...acc, res.id];
+            const key = input[res.key];
+            if (key == '' || key == null)
+                return [...acc, res.id];
+            if (key === wildcard_1.wildcard)
+                return [...acc, res.id, wildcard_1.wildcardPrimitive];
+            const isValid = (0, resource_1.validateResourceSegment)(key);
+            if (!isValid)
+                throw new InvalidKeyForCollection(res.key, key);
+            if ((res.id === lastResource.id && input.childResource) ||
+                input.childPermission === res.id) {
+                return [...acc, res.id, key, wildcard_1.wildcardPrimitive];
+            }
+            return [...acc, res.id, key];
+        }
+    }, []);
+}
+/** Build a resource class from a definition.
+ *
+ * - remember to add `as const` to the input object, to get accurate auto-complete.
+ * - for resource names, use valid javascript identifiers - i.e adminUsers and not 'admin-users'. those identifies are mapped to properties, so non-standard names would make them harder to access.
+ */
+function buildResourceClass(resourceDef) {
+    return build(resourceDef, []);
+}
+exports.buildResourceClass = buildResourceClass;
+class MissingKeyForCollection extends Error {
+    constructor(keyName) {
+        super(`No key for collection; keyName: '${String(keyName)}'`);
+    }
+}
+exports.MissingKeyForCollection = MissingKeyForCollection;
+class InvalidKeyForCollection extends Error {
+    constructor(keyName, keyValue) {
+        super(`Invalid key for collection; keyName: '${String(keyName)}', value: '${keyValue}'`);
+    }
+}
+exports.InvalidKeyForCollection = InvalidKeyForCollection;
+//# sourceMappingURL=resource-class-builder.js.map

package/dist/src/infra/resource-registry.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceClassRegistry = void 0;
+class ResourceClassRegistry {
+    constructor() {
+        this.templates = [];
+    }
+    register(name) {
+        this.templates.push(name);
+    }
+    getTemplates() {
+        return [...this.templates];
+    }
+}
+/* not very DI-like but for this specific use case (library, registry of fixed
+values) it's fine.
+
+if we do want to play nice with DI, we'll need to have the registry provided
+to the resource creation externally, and have  the DI provide it.
+*/
+exports.resourceClassRegistry = new ResourceClassRegistry();
+//# sourceMappingURL=resource-registry.js.map

package/dist/src/infra/resource.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Resource = exports.validateResourceSegment = exports.segmentMatcher = void 0;
+const wildcard_1 = require("./wildcard");
+exports.segmentMatcher = /^[a-zA-Z0-9_-]+$/;
+function validateResourceSegment(segment, options) {
+    if ((options === null || options === void 0 ? void 0 : options.allowWildcard) && segment === wildcard_1.wildcardPrimitive)
+        return true;
+    if (segment === undefined)
+        return true;
+    if (segment.startsWith('[') && segment.endsWith(']')) {
+        segment = segment.slice(1, -1); // remove template brackets
+    }
+    return exports.segmentMatcher.test(segment);
+}
+exports.validateResourceSegment = validateResourceSegment;
+class Resource {
+    constructor(path) {
+        this.path = path;
+    }
+    static parse(str) {
+        const path = str.split(Resource.separator);
+        if (path.length === 0) {
+            return { success: false, error: 'Resource path is empty' };
+        }
+        const emptySegments = path.filter((segment) => segment === '');
+        if (emptySegments.length > 0) {
+            return { success: false, error: `Resource path contains empty segments` };
+        }
+        const invalidSegments = path.filter((segment) => !validateResourceSegment(segment, { allowWildcard: true }));
+        if (invalidSegments.length > 0) {
+            return {
+                success: false,
+                error: 'Resource path contains invalid segments',
+                invalidSegments,
+                validationRegex: exports.segmentMatcher,
+            };
+        }
+        return {
+            success: true,
+            resource: new Resource(path),
+        };
+    }
+    /** checks if this resource owns `other`. i.e if `other` is a subset of this resource.
+     *
+     * examples:
+     * - `apps/123/users` does not own `apps/123/users/456`
+     * - `apps/123/users/*` owns `apps/123/users/456`
+     * - `apps/123/users` does not own `apps/123`
+     * - `apps/123/users` owns `apps/123/users` (itself)
+     *
+     * it's like `israel/tel-aviv/*` owns `israel/tel-aviv/alenby`, but not the other way around.
+     * and `israel/tel-aviv` does not own `israel/tel-aviv/alenby`, it owns only itself.
+     */
+    owns(other) {
+        const maxPathLength = Math.max(this.path.length, other.path.length);
+        // safeguard against unintentional global permission. should be explicit `*`
+        if (other.path.length === 0 || other.path[0] === '')
+            return false;
+        for (let i = 0; i < maxPathLength; i++) {
+            const thisSegment = this.path[i];
+            const otherSegment = other.path[i];
+            // e.g this is `apps/123` does not own `apps/123/users`.
+            // but 'apps/123/*' owns 'apps/123/users/567' , 'apps/*' owns 'apps/123/users/567' or 'apps/*/users' etc.
+            if (!thisSegment) {
+                if (this.path[i - 1] === wildcard_1.wildcardPrimitive) {
+                    return true;
+                }
+                return false;
+            }
+            // if `other` ended, but `this` didn't, then `this` doesn't contain `other`.
+            if (!otherSegment)
+                return false;
+            // if this segment is wildcard, no need for additional checks - it's a match.
+            // we only check further if it's not.
+            if (thisSegment !== wildcard_1.wildcardPrimitive) {
+                // if this segment isn't wildcard, but other is, then this can't possibly contain other.
+                if (otherSegment === wildcard_1.wildcardPrimitive)
+                    return false;
+                // if the segments don't match, we can stop checking.
+                if (thisSegment !== otherSegment)
+                    return false;
+            }
+        }
+        return true;
+    }
+    toString() {
+        return this.path.join(Resource.separator);
+    }
+}
+exports.Resource = Resource;
+Resource.separator = '/';
+//# sourceMappingURL=resource.js.map

package/dist/src/infra/wildcard.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wildcard = exports.wildcardPrimitive = void 0;
+exports.wildcardPrimitive = '*';
+exports.wildcard = Symbol('*');
+//# sourceMappingURL=wildcard.js.map

package/dist/src/utils/is-valid-enum-value.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidEnumValue = void 0;
+function isValidEnumValue(enumType, value) {
+    return Object.values(enumType).includes(value);
+}
+exports.isValidEnumValue = isValidEnumValue;
+//# sourceMappingURL=is-valid-enum-value.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@transmit-security/rbac",
+  "private": false,
+  "description": "RBAC impl of Transmt sec",
+  "version": "1.0.0-beta",
+  "main": "dist/ui.es.js",
+  "module": "dist/ui.es.js",
+  "author": "htrs-sec",
+  "repository": "https://www.github.com/htrs-sec/@transmit-security/rbac",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "husky": "9.1.4",
+    "lint-staged": "13.1.4",
+    "typescript": "^5.6.2"
+  },
+  "husky": {
+    "hooks": {
+      "commit-msg": "commitlint .commitlintrc.js -E HUSKY_GIT_PARAMS",
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*": [
+      "eden lint format",
+      "git add"
+    ]
+  }
+}