@travetto/auth 3.0.0-rc.0 → 3.0.0-rc.10

package/README.md

@@ -1,5 +1,5 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify https://github.com/travetto/travetto/tree/main/module/auth/doc.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/auth/DOC.ts and execute "npx trv doc" to rebuild -->
 # Authentication
 ## Authentication scaffolding for the travetto framework
 
@@ -63,7 +63,14 @@ As referenced above, a [Principal Structure](https://github.com/travetto/travett
 ```typescript
 export interface Authenticator<T = unknown, P extends Principal = Principal, C = unknown> {
   /**
-   * Verify the payload, verifying the payload is correctly identified.
+   * Allows for the authenticator to be initialized if needed
+   * @param ctx
+   */
+  initialize?(ctx: C): Promise<void>;
+
+  /**
+   * Verify the payload, ensuring the payload is correctly identified.
+   *
    * @returns Valid principal if authenticated
    * @returns undefined if authentication is valid, but incomplete (multi-step)
    * @throws AppError if authentication fails
@@ -105,50 +112,24 @@ Overall, the structure is simple, but drives home the primary use cases of the f
    *  To have access to the principal
 
 ## Common Utilities
-The [AuthUtil](https://github.com/travetto/travetto/tree/main/module/auth/src/util.ts#L24) provides the following functionality:
+The [AuthUtil](https://github.com/travetto/travetto/tree/main/module/auth/src/util.ts#L11) provides the following functionality:
 
 **Code: Auth util structure**
 ```typescript
-import * as crypto from 'crypto';
-import * as util from 'util';
+import crypto from 'crypto';
+import util from 'util';
 import { AppError, Util } from '@travetto/base';
 const pbkdf2 = util.promisify(crypto.pbkdf2);
-type PermSet = Set<string> | ReadonlySet<string>;
-type PermissionChecker = {
-  all: (perms: PermSet) => boolean;
-  any: (perms: PermSet) => boolean;
-};
-type PermissionCheckerSet = {
-  includes: (perms: PermSet) => boolean;
-  excludes: (perms: PermSet) => boolean;
-  check: (value: PermSet) => boolean;
-};
 /**
  * Standard auth utilities
  */
 export class AuthUtil {
   /**
-   * Build a permission checker against the provided permissions
-   *
-   * @param perms Set of permissions to check
-   * @param defaultIfEmpty If no perms passed, default to empty
-   */
-  /**
-   * Build a permission checker off of an include, and exclude set
+   * Build matcher for role permissions in allow/deny fashion
    *
-   * @param include Which permissions to include
-   * @param exclude Which permissions to exclude
-   * @param matchAll Whether not all permissions should be matched
+   * @param roles Roles to build matcher for
    */
-  static permissionChecker(include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any'): PermissionCheckerSet ;
-  /**
-   * Build a permission checker off of an include, and exclude set
-   *
-   * @param include Which permissions to include
-   * @param exclude Which permissions to exclude
-   * @param matchAll Whether not all permissions should be matched
-   */
-  static checkPermissions(permissions: Iterable<string>, include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any'): void ;
+  static roleMatcher(roles: string[]): (perms: Set<string>) => boolean ;
   /**
    * Generate a hash for a given value
    *
@@ -170,13 +151,18 @@ export class AuthUtil {
 }
 ```
 
-`permissionSetChecker` is probably the only functionality that needs to be explained.The function operates in a `DENY` / `ALLOW` mode.  This means that a permission check will succeed only if:
+`roleMatcher` is probably the only functionality that needs to be explained.  The function extends the core allow/deny matcher functionality from [Base](https://github.com/travetto/travetto/tree/main/module/base#readme "Environment config and common utilities for travetto applications.")'s Util class.  
+
+An example of role checks could be:
+
+   
+   *  Admin
+   *  !Editor
+   *  Owner+Author
 
+The code would check the list in order, which would result in the following logic:
    
-   *  The user is logged in     
-      *  If `matchAll` is false:    
-         *  The user does not have any permissions in the exclusion list
-         *  The include list is empty, or the user has at least one permission in the include list.
-      *  Else    
-         *  The user does not have all permissions in the exclusion list
-         *  The include list is empty, or the user has all permissions in the include list.
+   *  If the user is an admin, always allow
+   *  If the user has the editor role, deny
+   *  If the user is both an owner and an author allow
+   *  By default, deny due to the presence of positive checks

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@travetto/auth",
-  "displayName": "Authentication",
-  "version": "3.0.0-rc.0",
+  "version": "3.0.0-rc.10",
   "description": "Authentication scaffolding for the travetto framework",
   "keywords": [
     "authentication",
@@ -15,16 +14,19 @@
     "name": "Travetto Framework"
   },
   "files": [
-    "index.ts",
+    "__index__.ts",
     "src"
   ],
-  "main": "index.ts",
+  "main": "__index__.ts",
   "repository": {
     "url": "https://github.com/travetto/travetto.git",
     "directory": "module/auth"
   },
   "dependencies": {
-    "@travetto/base": "^3.0.0-rc.0"
+    "@travetto/base": "^3.0.0-rc.10"
+  },
+  "travetto": {
+    "displayName": "Authentication"
   },
   "private": false,
   "publishConfig": {

package/src/types/authenticator.ts

@@ -7,7 +7,14 @@ import { Principal } from './principal';
  */
 export interface Authenticator<T = unknown, P extends Principal = Principal, C = unknown> {
   /**
-   * Verify the payload, verifying the payload is correctly identified.
+   * Allows for the authenticator to be initialized if needed
+   * @param ctx
+   */
+  initialize?(ctx: C): Promise<void>;
+
+  /**
+   * Verify the payload, ensuring the payload is correctly identified.
+   *
    * @returns Valid principal if authenticated
    * @returns undefined if authentication is valid, but incomplete (multi-step)
    * @throws AppError if authentication fails

package/src/types/principal.ts

@@ -2,7 +2,7 @@
  * A user principal, including permissions and details
  *
  * @concrete ../internal/types:PrincipalTarget
- * @augments `@trv:rest/Context`
+ * @augments `@travetto/rest:Context`
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface Principal<D = { [key: string]: any }> {

package/src/util.ts

@@ -1,89 +1,36 @@
-import * as crypto from 'crypto';
-import * as util from 'util';
+import crypto from 'crypto';
+import util from 'util';
 
 import { AppError, Util } from '@travetto/base';
 
 const pbkdf2 = util.promisify(crypto.pbkdf2);
 
-type PermSet = Set<string> | ReadonlySet<string>;
-
-type PermissionChecker = {
-  all: (perms: PermSet) => boolean;
-  any: (perms: PermSet) => boolean;
-};
-
-type PermissionCheckerSet = {
-  includes: (perms: PermSet) => boolean;
-  excludes: (perms: PermSet) => boolean;
-  check: (value: PermSet) => boolean;
-};
-
 /**
  * Standard auth utilities
  */
 export class AuthUtil {
 
-  static #checkExcCache = new Map<string, PermissionChecker>();
-  static #checkIncCache = new Map<string, PermissionChecker>();
-
-  /**
-   * Build a permission checker against the provided permissions
-   *
-   * @param perms Set of permissions to check
-   * @param defaultIfEmpty If no perms passed, default to empty
-   */
-  static #buildChecker(perms: Iterable<string>, defaultIfEmpty: boolean): PermissionChecker {
-    const permArr = [...perms].map(x => x.toLowerCase());
-    let all = (_: PermSet): boolean => defaultIfEmpty;
-    let any = (_: PermSet): boolean => defaultIfEmpty;
-    if (permArr.length) {
-      all = (uPerms: PermSet): boolean => permArr.every(x => uPerms.has(x));
-      any = (uPerms: PermSet): boolean => permArr.some(x => uPerms.has(x));
+  static #matchPermissionSet(rule: string[], perms: Set<string>): boolean {
+    for (const el of rule) {
+      if (!perms.has(el)) {
+        return false;
+      }
     }
-    return { all, any };
+    return true;
   }
 
   /**
-   * Build a permission checker off of an include, and exclude set
+   * Build matcher for role permissions in allow/deny fashion
    *
-   * @param include Which permissions to include
-   * @param exclude Which permissions to exclude
-   * @param matchAll Whether not all permissions should be matched
+   * @param roles Roles to build matcher for
    */
-  static permissionChecker(include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any'): PermissionCheckerSet {
-    const incKey = [...include].sort().join(',');
-    const excKey = [...exclude].sort().join(',');
-
-    if (!this.#checkIncCache.has(incKey)) {
-      this.#checkIncCache.set(incKey, this.#buildChecker(include, true));
-    }
-    if (!this.#checkExcCache.has(excKey)) {
-      this.#checkExcCache.set(excKey, this.#buildChecker(exclude, false));
-    }
-
-    const includes = this.#checkIncCache.get(incKey)![mode];
-    const excludes = this.#checkExcCache.get(excKey)![mode];
-
-    return {
-      includes, excludes, check: (perms: PermSet) => includes(perms) && !excludes(perms)
-    };
+  static roleMatcher(roles: string[]): (perms: Set<string>) => boolean {
+    return Util.allowDenyMatcher<string[], [Set<string>]>(roles,
+      x => x.split('|'),
+      this.#matchPermissionSet.bind(this),
+    );
   }
 
-  /**
-   * Build a permission checker off of an include, and exclude set
-   *
-   * @param include Which permissions to include
-   * @param exclude Which permissions to exclude
-   * @param matchAll Whether not all permissions should be matched
-   */
-  static checkPermissions(permissions: Iterable<string>, include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any'): void {
-    const { check } = this.permissionChecker(include, exclude, mode);
-    if (!check(!(permissions instanceof Set) ? new Set(permissions) : permissions)) {
-      throw new AppError('Insufficient permissions', 'permissions');
-    }
-  }
-
-
   /**
    * Generate a hash for a given value
    *