@pcg/auth 1.0.0-alpha.0

package/tests/permissions/__snapshots__/helpers.test.ts.snap

@@ -0,0 +1,43 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Helpers > must merge resolved permissions 1`] = `
+[
+  {
+    "id": "js:core:episodes:create",
+    "scopes": [
+      "org#hci",
+      "user#xxx",
+      [
+        "org#hci",
+        "review",
+      ],
+    ],
+  },
+  {
+    "id": "js:core:videos:create",
+    "scopes": [],
+  },
+  {
+    "id": "js:core:seasons:create",
+    "scopes": [
+      "org#hci",
+    ],
+  },
+  {
+    "id": "js:core:subtitles:list",
+    "scopes": [
+      [
+        "org#hci",
+        "published",
+      ],
+    ],
+  },
+  {
+    "id": "js:core:episodes:update",
+    "scopes": [
+      "org#hci",
+      "user#yyy",
+    ],
+  },
+]
+`;

package/tests/permissions/action-scopes.test.ts

@@ -0,0 +1,111 @@
+import {
+  describe,
+  expect,
+  test,
+} from 'vitest';
+
+import { ActionScopes } from '../../src/index.js';
+
+describe('ActionScopes', () => {
+  describe('set', () => {
+    test(`must add 'OR' scope`, () => {
+      const scopes = new ActionScopes().set('foo');
+
+      expect(scopes.array).toContain('foo');
+    });
+
+    test(`must add 'AND' scope as array`, () => {
+      const scopes = new ActionScopes().set('foo+bar');
+
+      expect(Array.from(scopes.array)).toContainEqual(['foo', 'bar']);
+    });
+
+    test(`must memorize ids`, () => {
+      const scopes = new ActionScopes()
+        .set('org', 'jsorg:hci')
+        .set('org+published');
+
+      expect(Array.from(scopes.array)).toMatchObject([
+        'org#jsorg:hci',
+        ['org#jsorg:hci', 'published'],
+      ]);
+    });
+  });
+
+  describe(`canBeExecutedInScopes with 'OR' scopes`, () => {
+    test(`must return true if at least one required 'OR' scope is present`, () => {
+      const scopes = new ActionScopes()
+        .set('foo')
+        .set('bar');
+
+      expect(scopes.canBeExecutedInScopes(['foo'])).toBeTruthy();
+      expect(scopes.canBeExecutedInScopes(['foo', 'bar'])).toBeTruthy();
+      expect(scopes.canBeExecutedInScopes(['foo', 'extra'])).toBeTruthy();
+    });
+
+    test(`must return false if required 'OR' scope is missed`, () => {
+      const scopes = new ActionScopes()
+        .set('foo')
+        .set('bar');
+
+      expect(scopes.canBeExecutedInScopes(['baz'])).toBeFalsy();
+    });
+  });
+
+  describe(`canBeExecutedInScopes with 'AND' scopes`, () => {
+    test(`must return true if all required 'AND' scopes are present`, () => {
+      const scopes = new ActionScopes().set('foo+bar');
+
+      expect(scopes.canBeExecutedInScopes([['foo', 'bar']])).toBeTruthy();
+      expect(
+        scopes.canBeExecutedInScopes([['foo', 'bar'], 'extra']),
+      ).toBeTruthy();
+    });
+
+    test(`must return false if required 'AND' scope is missed`, () => {
+      const scopes = new ActionScopes().set('foo+bar+baz');
+
+      expect(scopes.canBeExecutedInScopes([])).toBeTruthy();
+      expect(scopes.canBeExecutedInScopes([['foo', 'beez']])).toBeFalsy();
+    });
+  });
+
+  describe(`canBeExecutedInScopes with mixed scopes`, () => {
+    test(`must return true if all required 'AND' or one of 'OR' scopes are present`, () => {
+      const scopes = new ActionScopes()
+        .set('foo+bar')
+        .set('baz');
+
+      expect(scopes.canBeExecutedInScopes([['foo', 'bar']])).toBeTruthy();
+      expect(
+        scopes.canBeExecutedInScopes([['foo', 'bar'], 'extra']),
+      ).toBeTruthy();
+      expect(scopes.canBeExecutedInScopes(['baz'])).toBeTruthy();
+      expect(scopes.canBeExecutedInScopes(['baz', 'extra'])).toBeTruthy();
+    });
+
+    test(`must return true if main scope is matched`, () => {
+      const scopes = new ActionScopes().set('foo+bar');
+
+      expect(scopes.canBeExecutedInScopes(['foo'])).toBeTruthy();
+    });
+
+    test(`must return true if subscopes is matched`, () => {
+      const scopes = new ActionScopes().set('foo+bar+baz');
+
+      expect(scopes.canBeExecutedInScopes([['foo', 'bar']])).toBeTruthy();
+    });
+
+    test(`must return false if no one scopes is matched`, () => {
+      const scopes = new ActionScopes().set('bar+baz');
+
+      expect(scopes.canBeExecutedInScopes([['foo']])).toBeFalsy();
+    });
+
+    test(`must return false if no one subscopes is matched`, () => {
+      const scopes = new ActionScopes().set('foo+bar+baz');
+
+      expect(scopes.canBeExecutedInScopes([['foo+beez']])).toBeFalsy();
+    });
+  });
+});

package/tests/permissions/helpers.test.ts

@@ -0,0 +1,169 @@
+import {
+  describe,
+  expect,
+  test,
+} from 'vitest';
+
+import {
+  encodeScopes,
+  injectScopesIntoPermission,
+  mergeResolvedPermissions,
+  replaceScope,
+  resolvePermissionGroups,
+  resolvePermissions,
+} from '../../src/index.js';
+
+describe('Helpers', () => {
+  test.each([
+    [['org#xxx'], '[org#xxx]'],
+    [['org#xxx', 'user#xxx'], '[org#xxx,user#xxx]'],
+    [[['org#xxx', 'published']], '[org#xxx+published]'],
+    [[['org#xxx', 'published'], 'user#xxx'], '[org#xxx+published,user#xxx]'],
+  ])('must encode scopes', (scopes, encodedScopes) => {
+    expect(encodeScopes(scopes)).toBe(encodedScopes);
+  });
+
+  test('must inject scopes into permission', async () => {
+    expect(injectScopesIntoPermission('js:core:episodes:create', [])).toBe(
+      'js:core:episodes:create',
+    );
+
+    expect(injectScopesIntoPermission('js:core:episodes:create', ['org'])).toBe(
+      'js:core:episodes[org]:create',
+    );
+
+    expect(
+      injectScopesIntoPermission('js:core:episodes[org]:create', ['shared']),
+    ).toBe('js:core:episodes[org,shared]:create');
+  });
+
+  test('must resolve permissions with scopes', async () => {
+    const permissions = [
+      'js:*:*:*',
+      'foo:*:*[org]:*',
+      'js:core:*:*',
+      'foo:bar:*[org]:*',
+      'js:core:episodes:*',
+      'js:core:episodes:create',
+      'js:core:episodes[published]:create',
+      'js:core:episodes[action#approve]:create',
+      'js:core:episodes[published,org]:create',
+      'js:core:episodes[published+my]:create',
+      'js:core:episodes[my]:create',
+      'js:core:articles[published]:create',
+    ];
+    const resolvedPermissions = resolvePermissions(permissions);
+    const expectedPermissions = [
+      {
+        id: 'js:*:*:*',
+        scopes: [],
+      },
+      {
+        id: 'foo:*:*:*',
+        scopes: ['org'],
+      },
+      {
+        id: 'js:core:*:*',
+        scopes: [],
+      },
+      {
+        id: 'foo:bar:*:*',
+        scopes: ['org'],
+      },
+      {
+        id: 'js:core:episodes:*',
+        scopes: [],
+      },
+      {
+        id: 'js:core:episodes:create',
+        scopes: [
+          'published',
+          'action#approve',
+          'org',
+          ['published', 'my'],
+          'my',
+        ],
+      },
+      {
+        id: 'js:core:articles:create',
+        scopes: ['published'],
+      },
+    ];
+
+    expect(resolvedPermissions).toEqual(expectedPermissions);
+  });
+
+  test('must resolve permission groups with scopes', async () => {
+    const permissionGroups = [
+      'g:js:mam:brands:read',
+      'g:js:mam:episodes[org,shared]:read',
+    ];
+
+    expect(resolvePermissionGroups(permissionGroups)).toEqual([
+      {
+        id: 'g:js:mam:brands:read',
+        scopes: [],
+      },
+      {
+        id: 'g:js:mam:episodes:read',
+        scopes: ['org', 'shared'],
+      },
+    ]);
+  });
+
+  test('must merge resolved permissions', () => {
+    expect(
+      mergeResolvedPermissions(
+        [
+          {
+            id: 'js:core:episodes:create',
+            scopes: ['org#hci'],
+          },
+          {
+            id: 'js:core:videos:create',
+            scopes: ['org#hci'],
+          },
+          {
+            id: 'js:core:seasons:create',
+            scopes: ['org#hci'],
+          },
+          {
+            id: 'js:core:subtitles:list',
+            scopes: [['org#hci', 'published']],
+          },
+        ],
+        [
+          {
+            id: 'js:core:episodes:create',
+            scopes: ['user#xxx', ['org#hci', 'review']],
+          },
+          {
+            id: 'js:core:episodes:update',
+            scopes: ['org#hci', 'user#yyy'],
+          },
+          {
+            id: 'js:core:videos:create',
+            scopes: [],
+          },
+          {
+            id: 'js:core:subtitles:list',
+            scopes: [['org#hci', 'published']],
+          },
+        ],
+      ),
+    ).toMatchSnapshot();
+  });
+
+  test.each([
+    [['assigned'], 'assigned', 'brand#xxx', ['brand#xxx']],
+    [['shared'], 'shared', [['brand#xxx', 'stage#publication']], [['brand#xxx', 'stage#publication']]],
+    [
+      [['assigned', 'social']],
+      'assigned',
+      'brand#xxx',
+      [['brand#xxx', 'social']],
+    ],
+  ])('must replace scopes', (scopes, from, to, result) => {
+    expect(replaceScope(scopes, from, to)).toMatchObject(result);
+  });
+});

package/tests/permissions/helpers.ts

@@ -0,0 +1,10 @@
+import { IUser } from '../../src/types/user.js';
+
+export const createMockUser = (input?: Partial<IUser>): IUser => {
+  return {
+    id: 'hcu:xxx',
+    permissions: [],
+    resolvedPermissions: [],
+    ...input,
+  };
+};

package/tests/permissions/permissions.test.ts

@@ -0,0 +1,218 @@
+import {
+  describe,
+  expect,
+  test,
+} from 'vitest';
+
+import {
+  ActionScopes, isGranted, resolvePermissions,
+} from '../../src/index.js';
+import { createMockUser } from './helpers.js';
+
+describe('Permissions', () => {
+  describe.each([
+    [
+      'js:core:roles:create',
+      ['js:core:roles:create'],
+      [],
+    ],
+    [
+      'js:core:roles:update',
+      ['js:core:roles:*'],
+      [],
+    ],
+    [
+      'js:core:roles:create',
+      ['js:core:*:*'],
+      [],
+    ],
+    [
+      'js:mam:episodes:create',
+      ['js:*:*[org]:*'],
+      ['org'],
+    ],
+    [
+      'js:mam:episodes:create',
+      ['*:mam:episodes:create'],
+      [],
+    ],
+    [
+      'js:mam:episodes:create',
+      ['js:mam:*[org]:*'],
+      ['org'],
+    ],
+    [
+      'js:core:users:update',
+      ['js:*:*:*'],
+      [],
+    ],
+    [
+      'js:core:episodes:get',
+      ['js:core:episodes[group]:get'],
+      ['group'],
+    ],
+    [
+      'js:core:episodes:get',
+      ['js:core:episodes[group,published]:get'],
+      ['group', 'published'],
+    ],
+    [
+      'js:core:episodes:get',
+      ['js:core:episodes[published,group]:get'],
+      ['group'],
+    ],
+    [
+      'js:core:episodes:get',
+      ['js:core:episodes[published+org]:get'],
+      [['published', 'org']],
+    ],
+    [
+      'js:core:episodes:get',
+      ['js:core:episodes[published,group+org]:get'],
+      ['group', ['group', 'org']],
+    ],
+    [
+      'js:core:episodes:get',
+      ['js:core:episodes[group#published]:get'],
+      ['group#published'],
+    ],
+  ])(
+    'Access to action \'%s\' with permissions \'%s\' (%j)',
+    (operation, permissions, scopes) => {
+      const user = createMockUser({
+        resolvedPermissions: resolvePermissions(permissions),
+      });
+
+      const userWithoutPermissions = createMockUser({
+        resolvedPermissions: [],
+      });
+
+      describe('Success', () => {
+        test('must allow operation with permission', async () => {
+          expect(isGranted(user, operation, scopes)).toBeTruthy();
+        });
+      });
+
+      describe('Fail', () => {
+        test('must deny operation without permission', async () => {
+          expect(isGranted(userWithoutPermissions, operation, scopes)).toBeFalsy();
+        });
+      });
+    },
+  );
+});
+
+describe('Other Cases', () => {
+  test('must be granted with any scope', async () => {
+    const user = createMockUser({
+      resolvedPermissions: resolvePermissions(['js:core:episodes[acc]:list']),
+    });
+
+    expect(
+      isGranted(user, 'js:core:episodes:list', ['*']),
+    ).toBeTruthy();
+  });
+
+  test('must be granted with any order of scopes grouped with "and" logic', async () => {
+    const user = createMockUser({
+      resolvedPermissions: resolvePermissions(['js:core:episodes[foo+bar+baz]:list']),
+    });
+
+    expect(
+      isGranted(user, 'js:core:episodes:list', [['baz', 'foo', 'bar']]),
+    ).toBeTruthy();
+  });
+});
+
+describe('Permission Denied', () => {
+  test('must not be granted if org is not specified in auth context', async () => {
+    const user = createMockUser({
+      resolvedPermissions: [
+        {
+          id: 'js:core:roles:assign-org',
+          scopes: ['org#jsorg:test-org'],
+        },
+        {
+          id: 'js:core:roles:assign-system',
+          scopes: ['org#jsorg:test-org'],
+        },
+      ],
+    });
+
+    const scopes = new ActionScopes();
+
+    expect(isGranted(user, 'js:core:roles:assign-system', scopes)).toBeFalsy();
+    expect(isGranted(user, 'js:core:roles:assign-org', scopes)).toBeFalsy();
+  });
+
+  test('must not be granted if another org specified in auth context', async () => {
+    const user = createMockUser({
+      resolvedPermissions: [
+        {
+          id: 'js:core:roles:assign-org',
+          scopes: ['org#jsorg:test-org-1'],
+        },
+        {
+          id: 'js:core:roles:assign-system',
+          scopes: ['org#jsorg:test-org-1'],
+        },
+      ],
+    });
+
+    const scopes = new ActionScopes();
+    scopes.set('org#jsorg:test-org-2');
+
+    expect(isGranted(user, 'js:core:roles:assign-system', scopes)).toBeFalsy();
+    expect(isGranted(user, 'js:core:roles:assign-org', scopes)).toBeFalsy();
+  });
+});
+
+describe('Organization Group Admin', () => {
+  test('must be granted update entity from organization group', async () => {
+    const user = createMockUser({
+      resolvedPermissions: [
+        {
+          id: '*:*:*:*',
+          scopes: ['org#mygroup'],
+        },
+      ],
+    });
+
+    const scopes = new ActionScopes();
+    scopes.set('org#mygroup');
+
+    expect(isGranted(user, 'js:core:brands:update', scopes)).toBeTruthy();
+  });
+
+  test('must be granted update organization in orggroup in any product', async () => {
+    const user = createMockUser({
+      resolvedPermissions: [
+        {
+          id: '*:core:organizations:update',
+          scopes: ['orggroup#hcgrp:ZT9mt8j9lSR'],
+        },
+      ],
+    });
+
+    const scopes = new ActionScopes();
+    scopes.set('orggroup#hcgrp:ZT9mt8j9lSR');
+
+    expect(isGranted(user, 'bo:core:organizations:update', scopes)).toBeTruthy();
+  });
+
+  test('must not be granted update entity from another organization group', async () => {
+    const user = createMockUser({
+      resolvedPermissions: [
+        {
+          id: '*:*:*:*',
+          scopes: ['org#mygroup'],
+        },
+      ],
+    });
+
+    const scopes = new ActionScopes();
+    scopes.set('org#notmygroup');
+
+    expect(isGranted(user, 'js:core:brands[org]:update', scopes)).toBeFalsy();
+  });
+});

package/tests/permissions/scopes-bulder.test.ts

@@ -0,0 +1,80 @@
+import {
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from 'vitest';
+
+import { ScopesBulder } from '../../src/permissions/scopes-bulder.js';
+
+describe('ScopesBulder', () => {
+  let scopes: ScopesBulder;
+
+  beforeEach(() => {
+    scopes = new ScopesBulder();
+  });
+
+  it('should add a single scope', () => {
+    scopes.append('org#hci');
+    expect(scopes.build()).toEqual(['org#hci']);
+  });
+
+  it('should add an array of scopes', () => {
+    scopes.extend(['org#hci', 'org#dv']);
+    expect(scopes.build()).toEqual(['org#hci', 'org#dv']);
+  });
+
+  it('should add another ScopesBulder', () => {
+    const otherScopes = new ScopesBulder(['org#hcc', 'org#dv']);
+    scopes.extend(otherScopes);
+    expect(scopes.build()).toEqual(['org#hcc', 'org#dv']);
+  });
+
+  it('should clone the ScopesBulder', () => {
+    scopes.append('org#hcc');
+    const clone = scopes.clone();
+    expect(clone.build()).toEqual(scopes.build());
+    expect(clone).not.toBe(scopes);
+  });
+
+  it('should join simple org scope', () => {
+    scopes.extend(['published', 'draft']);
+    scopes.join('org#hcc', 'before');
+    expect(scopes.build()).toEqual([
+      ['org#hcc', 'published'],
+      ['org#hcc', 'draft'],
+    ]);
+  });
+
+  it('should join lang scopes', () => {
+    scopes.append('season#xxx');
+    scopes.join(['lang#en', 'lang#de']);
+    expect(scopes.build()).toEqual([
+      ['season#xxx', 'lang#en'],
+      ['season#xxx', 'lang#de'],
+    ]);
+  });
+
+  it('should join lang scopes to complex scopes', () => {
+    scopes.append(['org#hci', 'season#xxx']);
+    scopes.join(['lang#en', 'lang#de']);
+    expect(scopes.build()).toEqual([
+      ['org#hci', 'season#xxx', 'lang#en'],
+      ['org#hci', 'season#xxx', 'lang#de'],
+    ]);
+  });
+
+  it('should keep scopes when joining empty scopes', () => {
+    scopes.append(['org#hci', 'season#xxx']);
+    scopes.join([]);
+    expect(scopes.build()).toEqual([
+      ['org#hci', 'season#xxx'],
+    ]);
+  });
+
+  it('should replace prefix in all scopes', () => {
+    scopes.extend(['org#hcorg:hci', 'org#hcorg:dv']);
+    scopes.replacePrefix('org', 'id');
+    expect(scopes.build()).toEqual(['id#hcorg:hci', 'id#hcorg:dv']);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "moduleResolution": "bundler",
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist"],
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  tsconfig: '../../tsconfig.build.json',
+  outDir: 'dist',
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  format: 'esm',
+});

package/vitest.config.ts

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    exclude: ['tests/tools/**'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov', 'clover'],
+      reportsDirectory: './dev/coverage',
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});