@travetto/auth 2.1.5 → 2.2.0

package/README.md

@@ -55,7 +55,7 @@ export interface Principal<D = { [key: string]: any }> {
 }
 ```
 
-As referenced above, a [Principal Structure](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L8) is defined as a user with respect to a security context. This can be information the application knows about the user (authorized) or what a separate service may know about a user (3rd-party authenticatino).
+As referenced above, a [Principal Structure](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L8) is defined as a user with respect to a security context. This can be information the application knows about the user (authorized) or what a separate service may know about a user (3rd-party authentication).
 
 ## Authentication
 
@@ -72,7 +72,7 @@ export interface Authenticator<T = unknown, P extends Principal = Principal, C =
 }
 ```
 
-The [Authenticator](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L8) only requires one method to be defined, and that is `authenticate`. This method receives a generic payload, and a supplemental context as an input. The interface is respon for converting that to an authenticated principal.
+The [Authenticator](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L8) only requires one method to be defined, and that is `authenticate`. This method receives a generic payload, and a supplemental context as an input. The interface is responsible for converting that to an authenticated principal.
 
 ### Example
 The [JWT](https://github.com/travetto/travetto/tree/main/module/jwt#readme "JSON Web Token implementation") module is a good example of an authenticator. This is a common use case for simple internal auth.
@@ -105,7 +105,7 @@ 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#L18) provides the following functionality:
+The [AuthUtil](https://github.com/travetto/travetto/tree/main/module/auth/src/util.ts#L24) provides the following functionality:
 
 **Code: Auth util structure**
 ```typescript
@@ -118,6 +118,11 @@ 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
  */
@@ -135,7 +140,7 @@ export class AuthUtil {
    * @param exclude Which permissions to exclude
    * @param matchAll Whether not all permissions should be matched
    */
-  static permissionChecker(include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any') ;
+  static permissionChecker(include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any'): PermissionCheckerSet ;
   /**
    * Build a permission checker off of an include, and exclude set
    *
@@ -143,7 +148,7 @@ export class AuthUtil {
    * @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') ;
+  static checkPermissions(permissions: Iterable<string>, include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any'): void ;
   /**
    * Generate a hash for a given value
    *
@@ -153,7 +158,7 @@ export class AuthUtil {
    * @param keylen Length of hash
    * @param digest Digest method
    */
-  static generateHash(value: string, salt: string, iterations = 25000, keylen = 256, digest = 'sha256') ;
+  static generateHash(value: string, salt: string, iterations = 25000, keylen = 256, digest = 'sha256'): Promise<string> ;
   /**
    * Generate a salted password, with the ability to validate the password
    *
@@ -161,7 +166,7 @@ export class AuthUtil {
    * @param salt Salt value, or if a number, length of salt
    * @param validator Optional function to validate your password
    */
-  static async generatePassword(password: string, salt: number | string = 32) ;
+  static async generatePassword(password: string, salt: number | string = 32): Promise<{ salt: string, hash: string }> ;
 }
 ```
 
@@ -248,7 +253,7 @@ export class User implements RegisteredPrincipal {
 
 ## Configuration
 
-Additionally, there exists a common practice of mapping various external security principals into a local contract. These external identities, as provided from countless authentication schemes, need to be homogeonized for use.  This has been handled in other frameworks by using external configuration, and creating a mapping between the two set of fields.  Within this module, the mappings are defined as functions in which you can translate to the model from an identity or to an identity from a model.
+Additionally, there exists a common practice of mapping various external security principals into a local contract. These external identities, as provided from countless authentication schemes, need to be homogenized for use.  This has been handled in other frameworks by using external configuration, and creating a mapping between the two set of fields.  Within this module, the mappings are defined as functions in which you can translate to the model from an identity or to an identity from a model.
 
 **Code: Principal Source configuration**
 ```typescript

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@travetto/auth",
   "displayName": "Authentication",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "description": "Authentication scaffolding for the travetto framework",
   "keywords": [
     "authentication",
@@ -25,10 +25,10 @@
     "directory": "module/auth"
   },
   "dependencies": {
-    "@travetto/base": "^2.1.3"
+    "@travetto/base": "^2.2.0"
   },
   "optionalPeerDependencies": {
-    "@travetto/model": "^2.1.5"
+    "@travetto/model": "^2.2.0"
   },
   "private": false,
   "publishConfig": {

package/src/extension/model.ts

@@ -67,7 +67,7 @@ export class ModelAuthService<T extends ModelType> implements
    * Retrieve user by id
    * @param userId The user id to retrieve
    */
-  async #retrieve(userId: string) {
+  async #retrieve(userId: string): Promise<T> {
     return await this.#modelService.get<T>(this.#cls, userId);
   }
 
@@ -75,7 +75,7 @@ export class ModelAuthService<T extends ModelType> implements
    * Convert identity to a principal
    * @param ident The registered identity to resolve
    */
-  async #resolvePrincipal(ident: RegisteredPrincipal) {
+  async #resolvePrincipal(ident: RegisteredPrincipal): Promise<RegisteredPrincipal> {
     const user = await this.#retrieve(ident.id);
     return this.toPrincipal(user);
   }
@@ -85,7 +85,7 @@ export class ModelAuthService<T extends ModelType> implements
    * @param userId The user id to authenticate against
    * @param password The password to authenticate against
    */
-  async #authenticate(userId: string, password: string) {
+  async #authenticate(userId: string, password: string): Promise<RegisteredPrincipal> {
     const ident = await this.#resolvePrincipal({ id: userId, details: {} });
 
     const hash = await AuthUtil.generateHash(password, ident.salt!);
@@ -97,7 +97,7 @@ export class ModelAuthService<T extends ModelType> implements
     }
   }
 
-  async postConstruct() {
+  async postConstruct(): Promise<void> {
     if (isStorageSupported(this.#modelService) && EnvUtil.isDynamic()) {
       await this.#modelService.createModel?.(this.#cls);
     }
@@ -107,7 +107,8 @@ export class ModelAuthService<T extends ModelType> implements
    * Register a user
    * @param user The user to register
    */
-  async register(user: OptionalId<T>) {
+  async register(user: OptionalId<T>): Promise<T> {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const ident = this.toPrincipal(user as T);
 
     try {
@@ -115,9 +116,9 @@ export class ModelAuthService<T extends ModelType> implements
         await this.#retrieve(ident.id);
         throw new AppError('That id is already taken.', 'data');
       }
-    } catch (e) {
-      if (!(e instanceof NotFoundError)) {
-        throw e;
+    } catch (err) {
+      if (!(err instanceof NotFoundError)) {
+        throw err;
       }
     }
 
@@ -133,11 +134,11 @@ export class ModelAuthService<T extends ModelType> implements
 
   /**
    * Change a password
-   * @param userId The user id to affet
+   * @param userId The user id to affect
    * @param password The new password
    * @param oldPassword The old password
    */
-  async changePassword(userId: string, password: string, oldPassword?: string) {
+  async changePassword(userId: string, password: string, oldPassword?: string): Promise<T> {
     const user = await this.#retrieve(userId);
     const ident = this.toPrincipal(user);
 
@@ -182,7 +183,7 @@ export class ModelAuthService<T extends ModelType> implements
    * @param principal
    * @returns Authorized principal
    */
-  authorize(principal: RegisteredPrincipal) {
+  authorize(principal: RegisteredPrincipal): Promise<RegisteredPrincipal> {
     return this.#resolvePrincipal(principal);
   }
 
@@ -191,7 +192,7 @@ export class ModelAuthService<T extends ModelType> implements
    * @param payload
    * @returns Authenticated principal
    */
-  authenticate(payload: T) {
+  authenticate(payload: T): Promise<RegisteredPrincipal> {
     const { id, password } = this.toPrincipal(payload);
     return this.#authenticate(id, password!);
   }

package/src/util.ts

@@ -12,6 +12,12 @@ type PermissionChecker = {
   any: (perms: PermSet) => boolean;
 };
 
+type PermissionCheckerSet = {
+  includes: (perms: PermSet) => boolean;
+  excludes: (perms: PermSet) => boolean;
+  check: (value: PermSet) => boolean;
+};
+
 /**
  * Standard auth utilities
  */
@@ -28,11 +34,11 @@ export class AuthUtil {
    */
   static #buildChecker(perms: Iterable<string>, defaultIfEmpty: boolean): PermissionChecker {
     const permArr = [...perms].map(x => x.toLowerCase());
-    let all = (_: PermSet) => defaultIfEmpty;
-    let any = (_: PermSet) => defaultIfEmpty;
+    let all = (_: PermSet): boolean => defaultIfEmpty;
+    let any = (_: PermSet): boolean => defaultIfEmpty;
     if (permArr.length) {
-      all = (uPerms: PermSet) => permArr.every(x => uPerms.has(x));
-      any = (uPerms: PermSet) => permArr.some(x => uPerms.has(x));
+      all = (uPerms: PermSet): boolean => permArr.every(x => uPerms.has(x));
+      any = (uPerms: PermSet): boolean => permArr.some(x => uPerms.has(x));
     }
     return { all, any };
   }
@@ -44,7 +50,7 @@ export class AuthUtil {
    * @param exclude Which permissions to exclude
    * @param matchAll Whether not all permissions should be matched
    */
-  static permissionChecker(include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any') {
+  static permissionChecker(include: Iterable<string>, exclude: Iterable<string>, mode: 'all' | 'any' = 'any'): PermissionCheckerSet {
     const incKey = [...include].sort().join(',');
     const excKey = [...exclude].sort().join(',');
 
@@ -70,7 +76,7 @@ export class AuthUtil {
    * @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') {
+  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');
@@ -87,7 +93,7 @@ export class AuthUtil {
    * @param keylen Length of hash
    * @param digest Digest method
    */
-  static generateHash(value: string, salt: string, iterations = 25000, keylen = 256, digest = 'sha256') {
+  static generateHash(value: string, salt: string, iterations = 25000, keylen = 256, digest = 'sha256'): Promise<string> {
     const half = Math.trunc(Math.ceil(keylen / 2));
     return pbkdf2(value, salt, iterations, half, digest).then(x => x.toString('hex').substring(0, keylen));
   }
@@ -99,7 +105,7 @@ export class AuthUtil {
    * @param salt Salt value, or if a number, length of salt
    * @param validator Optional function to validate your password
    */
-  static async generatePassword(password: string, salt: number | string = 32) {
+  static async generatePassword(password: string, salt: number | string = 32): Promise<{ salt: string, hash: string }> {
     if (!password) {
       throw new AppError('Password is required', 'data');
     }

package/test-support/model.ts

@@ -26,7 +26,7 @@ class User implements RegisteredPrincipal {
 
 class TestConfig {
   @InjectableFactory()
-  static getauthService(@Inject(TestModelSvcⲐ) svc: ModelCrudSupport): ModelAuthService<User> {
+  static getAuthService(@Inject(TestModelSvcⲐ) svc: ModelCrudSupport): ModelAuthService<User> {
     const src = new ModelAuthService<User>(
       svc,
       User,