@travetto/auth 2.2.4 → 3.0.0-rc.1

package/README.md

@@ -63,7 +63,8 @@ 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.
+   * 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,7 +106,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#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
@@ -113,42 +114,16 @@ import * as crypto from 'crypto';
 import * as 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
-   *
-   * @param include Which permissions to include
-   * @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'): PermissionCheckerSet ;
-  /**
-   * 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 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,155 +145,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 "Application phase management, environment config and common utilities for travetto applications.")'s Util class.  
 
-   
-   *  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. 
-
-## Extension - Model
-
-This module also supports the integration between the [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the travetto framework") module and the [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations."). 
-
-The asset module requires an [CRUD](https://github.com/travetto/travetto/tree/main/module/model/src/service/crud.ts#L11) to provide functionality for reading and storing user information. You can use any existing providers to serve as your [CRUD](https://github.com/travetto/travetto/tree/main/module/model/src/service/crud.ts#L11), or you can roll your own.
-
-**Install: provider**
-```bash
-npm install @travetto/model-{provider}
-```
+An example of role checks could be:
 
-Currently, the following are packages that provide [CRUD](https://github.com/travetto/travetto/tree/main/module/model/src/service/crud.ts#L11):
    
-   *  [DynamoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-dynamodb#readme "DynamoDB backing for the travetto model module.") - @travetto/model-dynamodb
-   *  [Elasticsearch Model Source](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch#readme "Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.") @travetto/model-elasticsearch
-   *  [Firestore Model Support](https://github.com/travetto/travetto/tree/main/module/model-firestore#readme "Firestore backing for the travetto model module.") @travetto/model-firestore
-   *  [MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.") @travetto/model-mongo
-   *  [Redis Model Support](https://github.com/travetto/travetto/tree/main/module/model-redis#readme "Redis backing for the travetto model module.") @travetto/model-redis
-   *  [S3 Model Support](https://github.com/travetto/travetto/tree/main/module/model-s3#readme "S3 backing for the travetto model module.") @travetto/model-s3
-   *  [SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.") @travetto/model-sql
-
-The module itself is fairly straightforward, and truly the only integration point for this module to work is defined at the model level.  The contract for authentication is established in code as providing translation to and from a [Registered Principal](https://github.com/travetto/travetto/tree/main/module/auth/src/extension/model.ts#L15)
-
-A registered principal extends the base concept of an principal, by adding in additional fields needed for local registration, specifically password management information.
-
-**Code: Registered Principal**
-```typescript
-export interface RegisteredPrincipal extends Principal {
-  /**
-   * Password hash
-   */
-  hash?: string;
-  /**
-   * Password salt
-   */
-  salt?: string;
-  /**
-   * Temporary Reset Token
-   */
-  resetToken?: string;
-  /**
-   * End date for the reset token
-   */
-  resetExpires?: Date;
-  /**
-   * The actual password, only used on password set/update
-   */
-  password?: string;
-}
-```
-
-**Code: A valid user model**
-```typescript
-import { Model } from '@travetto/model';
-import { RegisteredPrincipal } from '@travetto/auth';
-
-@Model()
-export class User implements RegisteredPrincipal {
-  id: string;
-  source: string;
-  details: Record<string, unknown>;
-  password?: string;
-  salt: string;
-  hash: string;
-  resetToken?: string;
-  resetExpires?: Date;
-  permissions: string[];
-}
-```
-
-## 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 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
-import { InjectableFactory } from '@travetto/di';
-import { ModelAuthService, RegisteredPrincipal } from '@travetto/auth';
-import { ModelCrudSupport } from '@travetto/model';
-
-import { User } from './model';
-
-class AuthConfig {
-  @InjectableFactory()
-  static getModelAuthService(svc: ModelCrudSupport) {
-    return new ModelAuthService(
-      svc,
-      User,
-      (u: User) => ({    // This converts User to a RegisteredPrincipal
-        source: 'model',
-        provider: 'model',
-        id: u.id,
-        permissions: u.permissions,
-        hash: u.hash,
-        salt: u.salt,
-        resetToken: u.resetToken,
-        resetExpires: u.resetExpires,
-        password: u.password,
-        details: u,
-      }),
-      (u: Partial<RegisteredPrincipal>) => User.from(({   // This converts a RegisteredPrincipal to a User
-        id: u.id,
-        permissions: [...(u.permissions || [])],
-        hash: u.hash,
-        salt: u.salt,
-        resetToken: u.resetToken,
-        resetExpires: u.resetExpires,
-      })
-      )
-    );
-  }
-}
-```
-
-**Code: Sample usage**
-```typescript
-import { AppError } from '@travetto/base';
-import { Injectable, Inject } from '@travetto/di';
-import { ModelAuthService } from '@travetto/auth';
+   *  Admin
+   *  !Editor
+   *  Owner+Author
 
-import { User } from './model';
-
-@Injectable()
-class UserService {
-
-  @Inject()
-  private auth: ModelAuthService<User>;
-
-  async authenticate(identity: User) {
-    try {
-      return await this.auth.authenticate(identity);
-    } catch (err) {
-      if (err instanceof AppError && err.category === 'notfound') {
-        return await this.auth.register(identity);
-      } else {
-        throw err;
-      }
-    }
-  }
-}
-```
+The code would check the list in order, which would result in the following logic:
+   
+   *  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/index.ts

@@ -1,7 +1,4 @@
 export * from './src/util';
 export * from './src/types/authenticator';
 export * from './src/types/authorizer';
-export * from './src/types/principal';
-
-// Named export needed for proxying
-export { ModelAuthService, RegisteredPrincipal } from './src/extension/model';
+export * from './src/types/principal';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@travetto/auth",
   "displayName": "Authentication",
-  "version": "2.2.4",
+  "version": "3.0.0-rc.1",
   "description": "Authentication scaffolding for the travetto framework",
   "keywords": [
     "authentication",
@@ -16,8 +16,7 @@
   },
   "files": [
     "index.ts",
-    "src",
-    "test-support"
+    "src"
   ],
   "main": "index.ts",
   "repository": {
@@ -25,10 +24,7 @@
     "directory": "module/auth"
   },
   "dependencies": {
-    "@travetto/base": "^2.2.4"
-  },
-  "optionalPeerDependencies": {
-    "@travetto/model": "^2.2.4"
+    "@travetto/base": "^3.0.0-rc.1"
   },
   "private": false,
   "publishConfig": {

package/src/internal/types.ts

@@ -1,6 +1,3 @@
-import { Schema } from '@travetto/schema'; // @line-if @travetto/schema
-
-@Schema() // @line-if @travetto/schema
 export class PrincipalTarget {
   id: string;
   expiresAt?: Date;

package/src/types/authenticator.ts

@@ -7,7 +7,8 @@ import { Principal } from './principal';
  */
 export interface Authenticator<T = unknown, P extends Principal = Principal, C = unknown> {
   /**
-   * Verify the payload, verifying the payload is correctly identified.
+   * 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` // @line-if @travetto/rest
+ * @augments `@trv:rest/Context`
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface Principal<D = { [key: string]: any }> {

package/src/util.ts

@@ -5,85 +5,32 @@ 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
    *

package/src/extension/model.ts

@@ -1,199 +0,0 @@
-// @file-if @travetto/model
-import { AppError, Util, Class } from '@travetto/base';
-import { ModelCrudSupport, ModelType, NotFoundError, OptionalId } from '@travetto/model';
-import { EnvUtil } from '@travetto/boot';
-import { isStorageSupported } from '@travetto/model/src/internal/service/common';
-
-import { Principal } from '../types/principal';
-import { Authenticator } from '../types/authenticator';
-import { Authorizer } from '../types/authorizer';
-import { AuthUtil } from '../util';
-
-/**
- * A set of registration data
- */
-export interface RegisteredPrincipal extends Principal {
-  /**
-   * Password hash
-   */
-  hash?: string;
-  /**
-   * Password salt
-   */
-  salt?: string;
-  /**
-   * Temporary Reset Token
-   */
-  resetToken?: string;
-  /**
-   * End date for the reset token
-   */
-  resetExpires?: Date;
-  /**
-   * The actual password, only used on password set/update
-   */
-  password?: string;
-}
-
-/**
- * A model-based auth service
- */
-export class ModelAuthService<T extends ModelType> implements
-  Authenticator<T, RegisteredPrincipal>,
-  Authorizer<RegisteredPrincipal>
-{
-
-  #modelService: ModelCrudSupport;
-  #cls: Class<T>;
-
-  /**
-   * Build a Model Principal Source
-   *
-   * @param cls Model class for the principal
-   * @param toPrincipal Convert a model to an principal
-   * @param fromPrincipal Convert an identity to the model
-   */
-  constructor(
-    modelService: ModelCrudSupport,
-    cls: Class<T>,
-    public toPrincipal: (t: T) => RegisteredPrincipal,
-    public fromPrincipal: (t: Partial<RegisteredPrincipal>) => Partial<T>,
-  ) {
-    this.#modelService = modelService;
-    this.#cls = cls;
-  }
-
-  /**
-   * Retrieve user by id
-   * @param userId The user id to retrieve
-   */
-  async #retrieve(userId: string): Promise<T> {
-    return await this.#modelService.get<T>(this.#cls, userId);
-  }
-
-  /**
-   * Convert identity to a principal
-   * @param ident The registered identity to resolve
-   */
-  async #resolvePrincipal(ident: RegisteredPrincipal): Promise<RegisteredPrincipal> {
-    const user = await this.#retrieve(ident.id);
-    return this.toPrincipal(user);
-  }
-
-  /**
-   * Authenticate password for model id
-   * @param userId The user id to authenticate against
-   * @param password The password to authenticate against
-   */
-  async #authenticate(userId: string, password: string): Promise<RegisteredPrincipal> {
-    const ident = await this.#resolvePrincipal({ id: userId, details: {} });
-
-    const hash = await AuthUtil.generateHash(password, ident.salt!);
-    if (hash !== ident.hash) {
-      throw new AppError('Invalid password', 'authentication');
-    } else {
-      delete ident.password;
-      return ident;
-    }
-  }
-
-  async postConstruct(): Promise<void> {
-    if (isStorageSupported(this.#modelService) && EnvUtil.isDynamic()) {
-      await this.#modelService.createModel?.(this.#cls);
-    }
-  }
-
-  /**
-   * Register a user
-   * @param user The user to register
-   */
-  async register(user: OptionalId<T>): Promise<T> {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const ident = this.toPrincipal(user as T);
-
-    try {
-      if (ident.id) {
-        await this.#retrieve(ident.id);
-        throw new AppError('That id is already taken.', 'data');
-      }
-    } catch (err) {
-      if (!(err instanceof NotFoundError)) {
-        throw err;
-      }
-    }
-
-    const fields = await AuthUtil.generatePassword(ident.password!);
-
-    ident.password = undefined; // Clear it out on set
-
-    Object.assign(user, this.fromPrincipal(fields));
-
-    const res: T = await this.#modelService.create(this.#cls, user);
-    return res;
-  }
-
-  /**
-   * Change a password
-   * @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): Promise<T> {
-    const user = await this.#retrieve(userId);
-    const ident = this.toPrincipal(user);
-
-    if (oldPassword === ident.resetToken) {
-      if (ident.resetExpires && ident.resetExpires.getTime() < Date.now()) {
-        throw new AppError('Reset token has expired', 'data');
-      }
-    } else if (oldPassword !== undefined) {
-      const pw = await AuthUtil.generateHash(oldPassword, ident.salt!);
-      if (pw !== ident.hash) {
-        throw new AppError('Old password is required to change', 'authentication');
-      }
-    }
-
-    const fields = await AuthUtil.generatePassword(password);
-    Object.assign(user, this.fromPrincipal(fields));
-
-    return await this.#modelService.update(this.#cls, user);
-  }
-
-  /**
-   * Generate a reset token
-   * @param userId The user to reset for
-   */
-  async generateResetToken(userId: string): Promise<RegisteredPrincipal> {
-    const user = await this.#retrieve(userId);
-    const ident = this.toPrincipal(user);
-    const salt = await Util.uuid();
-
-    ident.resetToken = await AuthUtil.generateHash(Util.uuid(), salt, 25000, 32);
-    ident.resetExpires = Util.timeFromNow('1h');
-
-    Object.assign(user, this.fromPrincipal(ident));
-
-    await this.#modelService.update(this.#cls, user);
-
-    return ident;
-  }
-
-  /**
-   * Authorize principal into known user
-   * @param principal
-   * @returns Authorized principal
-   */
-  authorize(principal: RegisteredPrincipal): Promise<RegisteredPrincipal> {
-    return this.#resolvePrincipal(principal);
-  }
-
-  /**
-   * Authenticate entity into a principal
-   * @param payload
-   * @returns Authenticated principal
-   */
-  authenticate(payload: T): Promise<RegisteredPrincipal> {
-    const { id, password } = this.toPrincipal(payload);
-    return this.#authenticate(id, password!);
-  }
-}

package/test-support/model.ts

@@ -1,89 +0,0 @@
-// @file-if @travetto/model
-import * as assert from 'assert';
-
-import { AppError, Class } from '@travetto/base';
-import { Suite, Test } from '@travetto/test';
-import { Inject, InjectableFactory } from '@travetto/di';
-import { ModelCrudSupport, Model } from '@travetto/model';
-import { InjectableSuite } from '@travetto/di/test-support/suite';
-import { ModelSuite } from '@travetto/model/test-support/suite';
-
-import { ModelAuthService, RegisteredPrincipal } from '..';
-
-export const TestModelSvcⲐ = Symbol.for('@trv:auth/test-model-svc');
-
-@Model({ autoCreate: false })
-class User implements RegisteredPrincipal {
-  id: string;
-  password?: string;
-  salt?: string;
-  hash?: string;
-  resetToken?: string;
-  resetExpires?: Date;
-  permissions?: string[];
-  details: Record<string, unknown>;
-}
-
-class TestConfig {
-  @InjectableFactory()
-  static getAuthService(@Inject(TestModelSvcⲐ) svc: ModelCrudSupport): ModelAuthService<User> {
-    const src = new ModelAuthService<User>(
-      svc,
-      User,
-      u => ({ ...u, details: u, source: 'model' }),
-      reg => User.from({ ...reg })
-    );
-    return src;
-  }
-}
-
-@Suite()
-@ModelSuite()
-@InjectableSuite()
-export abstract class AuthModelServiceSuite {
-
-  serviceClass: Class;
-  configClass: Class;
-
-  @Inject()
-  authService: ModelAuthService<User>;
-
-  @Inject(TestModelSvcⲐ)
-  svc: ModelCrudSupport;
-
-  @Test()
-  async register() {
-    const pre = User.from({
-      password: 'bob',
-      details: {}
-    });
-
-    const user = await this.authService.register(pre);
-    assert.ok(user.hash);
-    assert.ok(user.id);
-  }
-
-  @Test()
-  async authenticate() {
-    const pre = User.from({
-      id: this.svc.uuid(),
-      password: 'bob',
-      details: {}
-    });
-
-    try {
-      await this.authService.authenticate(pre);
-      assert.fail('Should not have gotten here');
-    } catch (err) {
-      if (err instanceof AppError && err.category === 'notfound') {
-        const user = await this.authService.register(pre);
-        assert.ok(user.hash);
-        assert.ok(user.id);
-      } else {
-        throw err;
-      }
-    }
-
-    await assert.doesNotReject(() => this.authService.authenticate(pre));
-  }
-}