@illustrisinteractive/sentinel-nest 0.0.1

package/src/bin/init.ts

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+import { intro, log, select, SelectOptions } from '@clack/prompts';
+import { exit } from 'process';
+import { Sequelize } from 'sequelize';
+import { Umzug, SequelizeStorage } from 'umzug';
+import fs from 'fs';
+
+export const init = async (
+  modelTable: string,
+  modelKey: string,
+  nxReadFrom?: string,
+  env_file?: string,
+  skip = false,
+  verbose = false,
+) => {
+  intro('Sentinel CLI');
+  log.info('Initialize - Preparing your Nest.js project for Sentinel');
+
+  let nestConfig: { [key: string]: any } | undefined = undefined;
+  const tsconfig = {
+    compilerOptions: {
+      module: 'nodenext',
+      moduleResolution: 'nodenext',
+      resolvePackageJsonExports: true,
+      esModuleInterop: true,
+      isolatedModules: true,
+      declaration: true,
+      removeComments: true,
+      emitDecoratorMetadata: true,
+      experimentalDecorators: true,
+      allowSyntheticDefaultImports: true,
+      target: 'ES2023',
+      sourceMap: true,
+      outDir: '.sentinel/',
+      baseUrl: './',
+      incremental: true,
+      skipLibCheck: true,
+      strictNullChecks: true,
+      forceConsistentCasingInFileNames: true,
+      noImplicitAny: false,
+      strictBindCallApply: false,
+      noFallthroughCasesInSwitch: false,
+      allowJs: true,
+    },
+  };
+
+  if (nxReadFrom) {
+    log.info(
+      '--nx-read-from flag specified. Sentinel CLI will try to detect all Nest projects in the provided path and generate a "nest-cli.json" file.',
+    );
+    const newNestConfig: {
+      projects: {
+        [key: string]: {
+          root: string;
+          sourceRoot: string;
+        };
+      };
+      monorepo: boolean;
+    } = {
+      projects: {},
+      monorepo: true,
+    };
+
+    const nxPath = process.cwd() + '\\' + nxReadFrom;
+
+    if (!fs.existsSync(nxPath)) {
+      log.error(
+        `The path specified in --nx-read-from (${nxPath}) does not exist.`,
+      );
+      exit(-1);
+    }
+
+    const dirs = fs.readdirSync(nxPath);
+
+    dirs.forEach((dir) => {
+      if (fs.existsSync(nxPath + '\\' + dir + '\\project.json')) {
+        log.step(
+          `Project detected in ${nxPath + '\\' + dir}. Assuming as Nest project with name (${dir})`,
+        );
+        newNestConfig.projects[dir] = {
+          root: `${nxReadFrom}/${dir}`,
+          sourceRoot: `${nxReadFrom}/${dir}/src`,
+        };
+      }
+    });
+    fs.writeFileSync(
+      process.cwd() + '/nest-cli.json',
+      JSON.stringify(newNestConfig, null, 2),
+    );
+  }
+
+  try {
+    nestConfig = (
+      await import('file://' + process.cwd() + '\\nest-cli.json', {
+        with: { type: 'json' },
+      })
+    ).default as object;
+  } catch (error) {
+    log.warn(
+      `Your project's "nest-cli.json" file was not found in the current working directory in ${process.cwd()}. Sentinel CLI will now treat your project as an Nx monorepo.`,
+    );
+    exit(-1);
+  }
+
+  if (env_file) {
+    try {
+      process.loadEnvFile(env_file);
+    } catch (error) {
+      log.error(
+        `Sentinel CLI failed to initialize Sentinel during ENV file loading. ${error}`,
+      );
+      exit(-1);
+    }
+  }
+
+  if (skip) {
+    log.warn(
+      "Sentinel CLI will not execute the migrations to create the tables required by Sentinel within your database. Make sure that you're doing this for good reason.",
+    );
+  } else {
+    try {
+      process.env.SENTINEL_MODEL_REFERENCE_TABLE = modelTable;
+      process.env.SENTINEL_MODEL_REFERENCE_KEY = modelKey;
+
+      const opts = {
+        SENTINEL_DB_HOST: process.env.SENTINEL_DB_HOST,
+        SENTINEL_DB_USER: process.env.SENTINEL_DB_USER,
+        SENTINEL_DB_PASS: process.env.SENTINEL_DB_PASS,
+        SENTINEL_DB_PORT: process.env.SENTINEL_DB_PORT as unknown as number,
+        SENTINEL_DB_DATABASE: process.env.SENTINEL_DB_DATABASE,
+      };
+
+      const missingOpts = Object.keys(opts).filter((key) => {
+        return opts[key] === undefined;
+      });
+
+      if (missingOpts.length != 0) {
+        log.error(
+          `Sentinel CLI failed to initialize Sentinel due to missing environment variables: ${missingOpts}.`,
+        );
+        log.message(
+          'If these variables are defined in a file, run \`npx sentinel init --env-from="<path>"\` instead.',
+        );
+        exit(-1);
+      }
+
+      const sequelize = new Sequelize({
+        dialect: 'postgres',
+        host: opts.SENTINEL_DB_HOST,
+        username: opts.SENTINEL_DB_USER,
+        password: opts.SENTINEL_DB_PASS,
+        port: opts.SENTINEL_DB_PORT,
+        database: opts.SENTINEL_DB_DATABASE,
+      });
+
+      try {
+        await sequelize.authenticate();
+      } catch (error) {
+        log.error(
+          'Sentinel CLI cannot connect to your database. Initialization failed.',
+        );
+        exit(-1);
+      }
+
+      log.success('Successfully connected to your database.');
+
+      const umzug = new Umzug({
+        migrations: {
+          glob: ['migrations/*.js', { cwd: __dirname }],
+        },
+        context: sequelize.getQueryInterface(),
+        storage: new SequelizeStorage({ sequelize }),
+        logger: verbose ? console : undefined,
+      });
+
+      await umzug.up();
+    } catch (error) {
+      console.log(error);
+    }
+    log.success('Successfully ran all migrations.');
+  }
+
+  let selectedProject: {
+    name: string;
+    sourceRoot: string;
+    sentinelConfigPath: string;
+  } = {
+    name: 'default',
+    sourceRoot: 'src',
+    sentinelConfigPath: 'src\\sentinel',
+  };
+
+  if (nestConfig.monorepo || nestConfig.projects) {
+    log.info(
+      'Monorepo Nest.js project detected. You will be prompted to select which Application to install Sentinel in.',
+    );
+
+    selectedProject = (await select({
+      message: 'Select which Application to configure Sentinel for:',
+      options: Object.keys(nestConfig.projects).map((app) => ({
+        label: app,
+        value: {
+          name: app,
+          sourceRoot: nestConfig.projects[app].sourceRoot,
+          sentinelConfigPath:
+            nestConfig.projects[app].sourceRoot + '\\sentinel',
+        },
+      })),
+    })) as { name: string; sourceRoot: string; sentinelConfigPath: string };
+  } else {
+    log.info(
+      'Standalone Nest.js project detected. Default Application defined in your "main.ts" file will be used.',
+    );
+  }
+
+  log.info(
+    `Sentinel CLI will configure Sentinel for application "${selectedProject.name}" in (${selectedProject.sourceRoot})`,
+  );
+
+  try {
+    fs.mkdirSync(selectedProject.sentinelConfigPath + '/resources', {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      selectedProject.sentinelConfigPath + '/sentinel.config.json',
+      JSON.stringify(selectedProject, null, 2),
+    );
+    fs.writeFileSync(
+      selectedProject.sentinelConfigPath + '/resources/tsconfig.json',
+      JSON.stringify(tsconfig, null, 2),
+    );
+    log.success(
+      `Sentinel Configuration file has been created in ${selectedProject.sentinelConfigPath + '/sentinel.config.json'}`,
+    );
+  } catch (err) {
+    console.log(err);
+    log.error(err);
+    exit(-1);
+  }
+
+  log.success('Next Steps');
+  log.message(
+    `You may now run${nestConfig.projects ? ` "cd apps/${selectedProject.name}" then ` : ' '}"npx sentinel resource <name>" to create a Secured Resource.`,
+  );
+  log.message(
+    'Afterwards, edit the generated file with your own list of Actions',
+  );
+  log.message(
+    "When you're ready, run `npx sentinel commit` to commit all of your Secured Resources to the database.",
+  );
+};

package/src/bin/migrations/1-create-permission.js

@@ -0,0 +1,32 @@
+'use strict';
+const { Sequelize } = require('sequelize');
+
+async function up({ context: queryInterface }) {
+  await queryInterface.createTable('PermissionKeys', {
+    id: {
+      allowNull: false,
+      primaryKey: true,
+      type: Sequelize.STRING,
+    },
+    resource: {
+      type: Sequelize.STRING,
+    },
+    action: {
+      type: Sequelize.STRING,
+    },
+    createdAt: {
+      allowNull: false,
+      type: Sequelize.DATE,
+    },
+    updatedAt: {
+      allowNull: false,
+      type: Sequelize.DATE,
+    },
+  });
+}
+
+async function down({ context: queryInterface }) {
+  await queryInterface.dropTable('PermissionKeys');
+}
+
+module.exports = { up, down };

package/src/bin/migrations/2-create-role.js

@@ -0,0 +1,29 @@
+'use strict';
+const { Sequelize } = require('sequelize');
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+  async up({ context: queryInterface }) {
+    await queryInterface.createTable('Roles', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER,
+      },
+      name: {
+        type: Sequelize.STRING,
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE,
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE,
+      },
+    });
+  },
+  async down({ context: queryInterface }) {
+    await queryInterface.dropTable('Roles');
+  },
+};

package/src/bin/migrations/3-create-rolepermissions.js

@@ -0,0 +1,46 @@
+'use strict';
+const { Sequelize } = require('sequelize');
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+  async up({ context: queryInterface }) {
+    await queryInterface.createTable('RoleHasPermissions', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER,
+      },
+      role: {
+        type: Sequelize.INTEGER,
+        references: {
+          model: {
+            tableName: 'Roles',
+          },
+          key: 'id',
+        },
+        allowNull: false,
+      },
+      permission: {
+        type: Sequelize.STRING,
+        references: {
+          model: {
+            tableName: 'PermissionKeys',
+          },
+          key: 'id',
+        },
+        allowNull: false,
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE,
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE,
+      },
+    });
+  },
+  async down({ context: queryInterface }) {
+    await queryInterface.dropTable('RoleHasPermissions');
+  },
+};

package/src/bin/migrations/4-create-model-roles.js

@@ -0,0 +1,46 @@
+'use strict';
+const { Sequelize } = require('sequelize');
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+  async up({ context: queryInterface }) {
+    await queryInterface.createTable('ModelHasRoles', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER,
+      },
+      role: {
+        type: Sequelize.INTEGER,
+        references: {
+          model: {
+            tableName: 'Roles',
+          },
+          key: 'id',
+        },
+        allowNull: false,
+      },
+      model: {
+        type: Sequelize.INTEGER,
+        references: {
+          model: {
+            tableName: process.env.SENTINEL_MODEL_REFERENCE_TABLE || 'Roles',
+          },
+          key: process.env.SENTINEL_MODEL_REFERENCE_KEY || 'id',
+        },
+        allowNull: false,
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE,
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE,
+      },
+    });
+  },
+  async down({ context: queryInterface }) {
+    await queryInterface.dropTable('ModelHasRoles');
+  },
+};

package/src/bin/resource.ts

@@ -0,0 +1,107 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+import { intro, log } from '@clack/prompts';
+import { SentinelConfig } from '@models/SentinelConfig';
+import { SecuredResource } from '@models/SecuredResource';
+import { Project } from 'ts-morph';
+import fs from 'fs';
+import { exit } from 'process';
+
+export const resource = async (name: string, manage: boolean) => {
+  intro('Sentinel CLI');
+  log.info('Resource - Create a new Secured Resource');
+
+  let sentinelConfig: SentinelConfig = {
+    name: '',
+    sourceRoot: '',
+    sentinelConfigPath: '',
+  };
+  if (!fs.existsSync(process.cwd() + '\\src\\sentinel\\sentinel.config.json')) {
+    log.error(
+      `"sentinel.config.json" was not found in (${process.cwd() + '\\src\\sentinel'}). Have you initialized Sentinel using "npx sentinel init"?`,
+    );
+  }
+  try {
+    sentinelConfig = (
+      await import(
+        'file://' + process.cwd() + '\\src\\sentinel\\sentinel.config.json',
+        {
+          with: { type: 'json' },
+        }
+      )
+    ).default as SentinelConfig;
+  } catch (error) {
+    console.log(error);
+    exit(-1);
+  }
+
+  const project = new Project();
+  const resourceFile = project.createSourceFile(
+    process.cwd() + '\\src\\sentinel\\resources\\' + name + '.ts',
+    `export class ${name} {}`,
+  );
+  resourceFile.addImportDeclaration({
+    moduleSpecifier: '@luminotion/sentinel',
+    namedImports: [
+      { name: 'SecuredResource' },
+      { name: 'SecuredResourceAction' },
+    ],
+  });
+  resourceFile.getClass(name)?.setExtends('SecuredResource');
+  resourceFile.getClass(name)?.addProperties([
+    { name: 'static name', initializer: `"${name}"` },
+    {
+      name: 'static actions: Record<string, SecuredResourceAction>',
+      initializer: (writer) => {
+        if (manage) {
+          writer.block(() => {
+            writer.writeLine(`"manage": `).block(() => {
+              writer.writeLine(
+                'description: "Allows all Actions in this Secured Resource"',
+              );
+            });
+          });
+        } else writer.writeLine('{}');
+      },
+    },
+  ]);
+  resourceFile.getClass(name)?.addStaticBlock({
+    statements: [
+      `Object.keys(${name}.actions).forEach((key) => {
+      ${name}.actions[key].source = '${name}';
+    });`,
+    ],
+  });
+  resourceFile.saveSync();
+
+  const newResource: SecuredResource = {
+    name,
+    actions: manage
+      ? {
+          manage: {
+            description: 'Allows all Actions in this Secured Resource.',
+          },
+        }
+      : {},
+  };
+  if (sentinelConfig.resources) {
+    const matchIdx = sentinelConfig.resources.findIndex(
+      (res) => res.name == name,
+    );
+    if (matchIdx != -1) {
+      sentinelConfig.resources[matchIdx] = newResource;
+    } else sentinelConfig.resources.push(newResource);
+  } else sentinelConfig.resources = [newResource];
+
+  log.success(
+    `New Secured Resource created in ${sentinelConfig.sentinelConfigPath}\\${name}`,
+  );
+
+  fs.writeFileSync(
+    process.cwd() + '\\src\\sentinel\\sentinel.config.json',
+    JSON.stringify(sentinelConfig, null, 2),
+  );
+
+  log.success(
+    `${name} is ready to be committed. Edit the file with your Actions, then run "npx sentinel commit" to refresh all Secured Resource definitions.`,
+  );
+};

package/src/bin/sentinel.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import { intro } from '@clack/prompts';
+import { Command, Option } from 'commander';
+import { init } from './init';
+import { resource } from './resource';
+import { commit } from './commit';
+
+const program = new Command();
+
+program
+  .name('Sentinel CLI')
+  .description('RBAC implementation for Nest.js powered by CASL and Postgres')
+  .version('0.0.1');
+
+program
+  .command('init')
+  .description(
+    'Prepares your Nest.js project for Sentinel. Run this command where your `nest-cli.json` file is located.',
+  )
+  .requiredOption(
+    '--model-table <model>',
+    'Determines which table to reference when logging which Roles a Model has been given with. This will often be your Users or Clients table.',
+  )
+  .option(
+    '--nx-read-from <path>',
+    'Determines the path to read Nest projects from in an Nx monorepo. (Ie. apps/backend)',
+  )
+  .option(
+    '--model-key <key>',
+    'The primary key of your Model Table. Defaults to "id".',
+    'id',
+  )
+  .option(
+    '--env-from <path>',
+    'Optionally configure the CLI to load required ENV values from a file.',
+  )
+  .option(
+    '--skip-migration',
+    'Configures the CLI to skip running the migration files required by Sentinel',
+  )
+  .option('--verbose', 'If true, Sequelize logs are printed to the console.')
+  .action((opts) => {
+    init(
+      opts.modelTable,
+      opts.modelKey,
+      opts.nxReadFrom,
+      opts.envFrom,
+      opts.skipMigration,
+      opts.verbose,
+    );
+  });
+
+program
+  .command('resource')
+  .description(
+    'Creates a new Secured Resource without pushing it to your database. Afterwards, you can add Actions by editing the generated file, then run `npx sentinel commit` to save them to your database.',
+  )
+  .argument('<resource>', 'Name of the Secured Resource')
+  .option(
+    '--no-manage',
+    'Skips generating the "manage" Action in the new Secured Resource',
+  )
+  .action((name, opts) => {
+    resource(name, opts.manage);
+  });
+
+program
+  .command('commit')
+  .description(
+    'Commits all new and modified Secured Resources to your database.',
+  )
+  .option(
+    '--env-from <path>',
+    'Optionally configure the CLI to load required ENV values from a file.',
+  )
+  .option(
+    '--review',
+    'Generate a list of all detected Secured Resources and their Actions.',
+  )
+  .option(
+    '--refresh',
+    'Refreshes the local Secured Resource definitions in the "sentinel.config.json" without committing to the database.',
+  )
+  .option(
+    '--skip-prompts',
+    'Skips all confirmation prompts and directly performs operations.',
+  )
+  .action((opts) => {
+    commit(opts.envFrom);
+  });
+
+program
+  .command('clean')
+  .description(
+    'Add flags to remove configurations and/or drop tables related to Sentinel. Does not modify any of your Nest.js code.',
+  )
+  .option(
+    '--migration',
+    'Resets the internal SequelizeMeta table to allow migrations to re-run again.',
+  )
+  .option(
+    '--tables',
+    'Drops all tables related to Sentinel (Roles, RoleHasPermissions, PermissionKeys)',
+  )
+  .option(
+    '--role-permissions <name>',
+    'Removes all Permissions assigned to a certain Role.',
+  )
+  .option('--role <name>', 'Deletes a Role completely.')
+  .option(
+    '--all',
+    'Removes all Roles, PermissionKeys, and role assignments (RoleHasPermissions)',
+  );
+
+program.parse();

package/src/bin/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "resolvePackageJsonExports": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2023",
+    "sourceMap": true,
+    "outDir": "../../dist/",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "noImplicitAny": false,
+    "strictBindCallApply": false,
+    "noFallthroughCasesInSwitch": false,
+    "allowJs": true,
+    "paths": {
+      "@models/*": ["../models/*"],
+      "@models/sequelize/*": ["../models/sequelize/*"]
+    }
+  }
+}

package/src/can.decorator.ts

@@ -0,0 +1,4 @@
+import { SecuredResourceAction } from './main';
+import { Reflector } from '@nestjs/core';
+
+export const Can = Reflector.createDecorator<SecuredResourceAction[]>();