@travetto/auth 5.0.16 → 6.0.0-rc.0

package/README.md

@@ -17,20 +17,23 @@ This module provides the high-level backdrop for managing security principals.
    *  Standard Types
    *  Authentication Contract
    *  Authorization Contract
-   *  Common security-related utilities for
-      *  Checking permissions
-      *  Generating passwords
+   *  Authorization Services
+   *  Authorization Context
 
 ## Standard Types
-The module's goal is to be as flexible as possible.  To that end, the primary contract that this module defines, is that of the [Principal Structure](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L8).
+The module's goal is to be as flexible as possible.  To that end, the primary contract that this module defines, is that of the [Principal Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L8).
 
-**Code: Principal Structure**
+**Code: Principal Contract**
 ```typescript
 export interface Principal<D = AnyMap> {
   /**
    * Primary identifier for a user
    */
-  id: string;
+  readonly id: string;
+  /**
+   * Unique identifier for the principal's lifecycle
+   */
+  readonly sessionId?: string;
   /**
    * Date of expiration
    */
@@ -39,37 +42,32 @@ export interface Principal<D = AnyMap> {
    * Date of issuance
    */
   issuedAt?: Date;
-  /**
-   * Max age in seconds a principal is valid
-   */
-  maxAge?: number;
   /**
    * The source of the issuance
    */
-  issuer?: string;
+  readonly issuer?: string;
   /**
    * Supplemental details
    */
-  details: D;
+  readonly details: D;
   /**
    * List of all provided permissions
    */
-  permissions?: string[];
+  readonly permissions?: string[];
 }
 ```
 
-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).
+As referenced above, a [Principal Contract](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
+## Authentication Contract
 
-**Code: Authenticator**
+**Code: Authenticator Contract**
 ```typescript
-export interface Authenticator<T = unknown, P extends Principal = Principal, C = unknown> {
+export interface Authenticator<T = unknown, C = unknown, P extends Principal = Principal> {
   /**
-   * Allows for the authenticator to be initialized if needed
-   * @param ctx
+   * Retrieve the authenticator state for the given request
    */
-  initialize?(ctx: C): Promise<void>;
+  getState?(context?: C): Promise<AuthenticatorState | undefined> | AuthenticatorState | undefined;
 
   /**
    * Verify the payload, ensuring the payload is correctly identified.
@@ -78,32 +76,31 @@ export interface Authenticator<T = unknown, P extends Principal = Principal, C =
    * @returns undefined if authentication is valid, but incomplete (multi-step)
    * @throws AppError if authentication fails
    */
-  authenticate(payload: T, ctx?: C): Promise<P | undefined> | P | undefined;
+  authenticate(payload: T, context?: C): Promise<P | undefined> | P | undefined;
 }
 ```
 
-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.
+The [Authenticator Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L14) 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.
 
-## Authorization
+## Authorization Contract
 
-**Code: Authorizer**
+**Code: Authorizer Contract**
 ```typescript
 export interface Authorizer<P extends Principal = Principal> {
   /**
    * Authorize inbound principal, verifying it's permission to access the system.
-   * @param principal
    * @returns New principal that conforms to the required principal shape
    */
-  authorize(principal: Principal): Promise<P> | P;
+  authorize(principal: P): Promise<P> | P;
 }
 ```
 
 Authorizers are generally seen as a secondary step post-authentication. Authentication acts as a very basic form of authorization, assuming the principal store is owned by the application. 
 
-The [Authorizer](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authorizer.ts#L8) only requires one method to be defined, and that is `authorizer`. This method receives an authenticated principal as an input, and is responsible for converting that to an authorized principal.
+The [Authorizer Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authorizer.ts#L8) only requires one method to be defined, and that is `authorizer`. This method receives an authenticated principal as an input, and is responsible for converting that to an authorized principal.
 
 ### Example
 The [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") extension is a good example of an authenticator. This is a common use case for simple internal auth. 
@@ -113,48 +110,84 @@ Overall, the structure is simple, but drives home the primary use cases of the f
    *  To have a reference to a user's set of permissions
    *  To have access to the principal
 
-## Common Utilities
-The [AuthUtil](https://github.com/travetto/travetto/tree/main/module/auth/src/util.ts#L11) provides the following functionality:
+## Authorization Services
 
-**Code: Auth util structure**
+**Code: Authorization Service**
 ```typescript
-import crypto from 'node:crypto';
-import util from 'node:util';
-import { AppError, Util } from '@travetto/runtime';
-const pbkdf2 = util.promisify(crypto.pbkdf2);
-/**
- * Standard auth utilities
- */
-export class AuthUtil {
-  /**
-   * Generate a hash for a given value
-   *
-   * @param value Value to hash
-   * @param salt The salt value
-   * @param iterations Number of iterations on hashing
-   * @param keylen Length of hash
-   * @param digest Digest method
+export class AuthService {
+  @Inject()
+  /**
+   * Get authenticators by keys
    */
-  static generateHash(value: string, salt: string, iterations = 25000, keylen = 256, digest = 'sha256'): Promise<string>;
+  async getAuthenticators<T = unknown, C = unknown>(keys: symbol[]): Promise<Authenticator<T, C>[]>;
   /**
-   * Generate a salted password, with the ability to validate the password
-   *
-   * @param password
-   * @param salt Salt value, or if a number, length of salt
-   * @param validator Optional function to validate your password
+   * Authenticate. Supports multi-step login.
+   * @param ctx The authenticator context
+   * @param authenticators List of valid authentication sources
+   */
+  async authenticate<T, C>(payload: T, context: C, authenticators: symbol[]): Promise<Principal | undefined>;
+  /**
+   * Manage expiry state, renewing if allowed
    */
-  static async generatePassword(password: string, salt: number | string = 32): Promise<{ salt: string, hash: string }>;
+  manageExpiry(p?: Principal): void;
+  /**
+   * Enforce expiry, invalidating the principal if expired
+   */
+  enforceExpiry(p?: Principal): Principal | undefined;
 }
 ```
 
-`roleMatcher` is probably the only functionality that needs to be explained.  The function extends the core allow/deny matcher functionality from [Runtime](https://github.com/travetto/travetto/tree/main/module/runtime#readme "Runtime 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:
-   *  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
+The [AuthService](https://github.com/travetto/travetto/tree/main/module/auth/src/service.ts#L14) operates as the owner of the current auth state for a given "request".  "Request" here implies a set of operations over a period of time, with the http request/response model being an easy point of reference.  This could also tie to a CLI operation, or any other invocation that requires some concept of authentication and authorization. 
+
+The service allows for storing and retrieving the active [Principal Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L8), and/or the actively persisted auth token.  This is extremely useful for other parts of the framework that may request authenticated information (if available).  [Rest Auth](https://github.com/travetto/travetto/tree/main/module/auth-rest#readme "Rest authentication integration support for the Travetto framework") makes heavy use of this state for enforcing routes when authentication is required. 
+
+### Login
+"Logging in" can be thought of going through the action of finding a single source that can authenticate the identity for the request credentials.  Some times there may be more than one valid source of authentication that you want to leverage, and the first one to authenticate wins. The [AuthService](https://github.com/travetto/travetto/tree/main/module/auth/src/service.ts#L14) operates in this fashion, in which a set of credentials and potential [Authenticator Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L14)s are submitted, and the service will attempt to authenticate.  
+
+Upon successful authentication, an optional [Authorizer Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authorizer.ts#L8) may be invoked to authorize the authenticated user.  The [Authenticator Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L14) is assumed to be only one within the system, and should be tied to the specific product you are building for.  The [Authorizer Contract](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authorizer.ts#L8) should be assumed to have multiple sources, and are generally specific to external third parties.  All of these values are collected via the [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support.") module and will be auto-registered on startup. 
+
+If this process is too cumbersome or restrictive, manually authenticating and authorizing is still more than permissible, and setting the principal within the service is a logical equivalent to login.
+
+## Authorization Context
+When working with framework's authentication, the authenticated information is exposed via the [AuthContext](https://github.com/travetto/travetto/tree/main/module/auth/src/context.ts#L16), object. 
+
+**Code: Auth Context Outline**
+```typescript
+type AuthContextShape = {
+  principal?: Principal;
+  authToken?: AuthToken;
+  authenticatorState?: AuthenticatorState;
+};
+@Injectable()
+export class AuthContext {
+  @Inject()
+  /**
+   * Get the principal, if set
+   */
+  get principal(): Principal | undefined;
+  /**
+   * Set principal
+   */
+  set principal(p: Principal | undefined);
+  /**
+   * Get the authentication token, if it exists
+   */
+  get authToken(): AuthToken | undefined;
+  /**
+   * Set/overwrite the user's authentication token
+   */
+  set authToken(token: AuthToken | undefined);
+  /**
+   * Get the authenticator state, if it exists
+   */
+  get authenticatorState(): AuthenticatorState | undefined;
+  /**
+   * Set/overwrite the authenticator state
+   */
+  set authenticatorState(state: AuthenticatorState | undefined);
+  /**
+   * Clear context
+   */
+  async clear(): Promise<void>;
+}
+```

package/__index__.ts

@@ -1,5 +1,8 @@
-export * from './src/util';
+export * from './src/service';
+export * from './src/context';
+export * from './src/config';
 export * from './src/types/authenticator';
 export * from './src/types/authorizer';
 export * from './src/types/principal';
-export * from './src/types/error';
+export * from './src/types/error';
+export * from './src/types/token';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/auth",
-  "version": "5.0.16",
+  "version": "6.0.0-rc.0",
   "description": "Authentication scaffolding for the Travetto framework",
   "keywords": [
     "authentication",
@@ -23,7 +23,7 @@
     "directory": "module/auth"
   },
   "dependencies": {
-    "@travetto/runtime": "^5.0.16"
+    "@travetto/context": "^6.0.0-rc.0"
   },
   "travetto": {
     "displayName": "Authentication"

package/src/config.ts

@@ -0,0 +1,17 @@
+import { Config } from '@travetto/config';
+import { TimeSpan, TimeUtil } from '@travetto/runtime';
+import { Ignore } from '@travetto/schema';
+
+@Config('auth')
+export class AuthConfig {
+
+  maxAge: TimeSpan | number = '1h';
+  rollingRenew: boolean = true;
+
+  @Ignore()
+  maxAgeMs: number;
+
+  postConstruct(): void {
+    this.maxAgeMs = TimeUtil.asMillis(this.maxAge);
+  }
+}

package/src/context.ts

@@ -0,0 +1,80 @@
+
+import { Inject, Injectable } from '@travetto/di';
+import { AsyncContext, AsyncContextValue } from '@travetto/context';
+
+import { AuthToken } from './types/token';
+import { Principal } from './types/principal';
+import { AuthenticatorState } from './types/authenticator';
+
+type AuthContextShape = {
+  principal?: Principal;
+  authToken?: AuthToken;
+  authenticatorState?: AuthenticatorState;
+};
+
+@Injectable()
+export class AuthContext {
+
+  #value = new AsyncContextValue<AuthContextShape>(this);
+
+  @Inject()
+  context: AsyncContext;
+
+  /**
+   * Initialize context
+   * @private
+   */
+  init(): void {
+    this.#value.set({});
+  }
+
+  /**
+   * Get the principal, if set
+   */
+  get principal(): Principal | undefined {
+    return this.#value.get()?.principal;
+  }
+
+  /**
+   * Set principal
+   */
+  set principal(p: Principal | undefined) {
+    this.#value.get()!.principal = p;
+  }
+
+  /**
+   * Get the authentication token, if it exists
+   */
+  get authToken(): AuthToken | undefined {
+    return this.#value.get()?.authToken;
+  }
+
+  /**
+   * Set/overwrite the user's authentication token
+   */
+  set authToken(token: AuthToken | undefined) {
+    this.#value.get()!.authToken = token;
+  }
+
+  /**
+   * Get the authenticator state, if it exists
+   */
+  get authenticatorState(): AuthenticatorState | undefined {
+    return this.#value.get()?.authenticatorState;
+  }
+
+  /**
+   * Set/overwrite the authenticator state
+   */
+  set authenticatorState(state: AuthenticatorState | undefined) {
+    this.#value.get()!.authenticatorState = state;
+  }
+
+  /**
+   * Clear context
+   * @private
+   */
+  async clear(): Promise<void> {
+    this.#value.set(undefined);
+  }
+}

package/src/internal/types.ts

@@ -9,4 +9,3 @@ export class PrincipalTarget {
 }
 export class AuthorizerTarget { }
 export class AuthenticatorTarget { }
-export class PrincipalSerializerTarget { }

package/src/service.ts

@@ -0,0 +1,114 @@
+
+import { DependencyRegistry, Inject, Injectable } from '@travetto/di';
+import { TimeUtil } from '@travetto/runtime';
+
+import { AuthenticatorTarget } from './internal/types';
+import { Principal } from './types/principal';
+import { Authenticator } from './types/authenticator';
+import { Authorizer } from './types/authorizer';
+import { AuthenticationError } from './types/error';
+import { AuthContext } from './context';
+import { AuthConfig } from './config';
+
+@Injectable()
+export class AuthService {
+
+  @Inject()
+  authContext: AuthContext;
+
+  @Inject()
+  config: AuthConfig;
+
+  #authenticators = new Map<symbol, Promise<Authenticator>>();
+
+  @Inject()
+  authorizer?: Authorizer;
+
+  async postConstruct(): Promise<void> {
+    // Find all authenticators
+    for (const source of DependencyRegistry.getCandidateTypes(AuthenticatorTarget)) {
+      const dep = DependencyRegistry.getInstance<Authenticator>(AuthenticatorTarget, source.qualifier);
+      this.#authenticators.set(source.qualifier, dep);
+    }
+  }
+
+  /**
+   * Get authenticators by keys
+   */
+  async getAuthenticators<T = unknown, C = unknown>(keys: symbol[]): Promise<Authenticator<T, C>[]> {
+    return await Promise.all(keys.map(key => this.#authenticators.get(key)!));
+  }
+
+  /**
+   * Authenticate. Supports multi-step login.
+   * @param ctx The authenticator context
+   * @param authenticators List of valid authentication sources
+   */
+  async authenticate<T, C>(payload: T, context: C, authenticators: symbol[]): Promise<Principal | undefined> {
+    let lastError: Error | undefined;
+
+    /**
+     * Attempt to authenticate, checking with multiple authentication sources
+     */
+    for (const idp of await this.getAuthenticators<T, C>(authenticators)) {
+      try {
+        const principal = await idp.authenticate(payload, context);
+
+        if (idp.getState) {
+          this.authContext.authenticatorState = await idp.getState(context);
+        }
+
+        if (!principal) { // Multi-step login process
+          return;
+        }
+        return this.authContext.principal = (await this.authorizer?.authorize(principal)) ?? principal;
+      } catch (err) {
+        if (!(err instanceof Error)) {
+          throw err;
+        }
+        lastError = err;
+      }
+    }
+
+    if (lastError) {
+      console.warn('Failed to authenticate', { error: lastError, sources: authenticators.map(x => x.toString()) });
+    }
+
+    // Take the last error and return
+    throw new AuthenticationError('Unable to authenticate', { cause: lastError });
+  }
+
+  /**
+   * Manage expiry state, renewing if allowed
+   */
+  manageExpiry(p?: Principal): void {
+    if (!p) {
+      return;
+    }
+
+    if (this.config.maxAgeMs) {
+      p.expiresAt ??= TimeUtil.fromNow(this.config.maxAgeMs);
+    }
+
+    p.issuedAt ??= new Date();
+
+    if (p.expiresAt && this.config.maxAgeMs && this.config.rollingRenew) { // Session behavior
+      const end = p.expiresAt.getTime();
+      const midPoint = end - this.config.maxAgeMs / 2;
+      if (Date.now() > midPoint) { // If we are past the half way mark, renew the token
+        p.issuedAt = new Date();
+        p.expiresAt = TimeUtil.fromNow(this.config.maxAgeMs); // This will trigger a re-send
+      }
+    }
+  }
+
+  /**
+   * Enforce expiry, invalidating the principal if expired
+   */
+  enforceExpiry(p?: Principal): Principal | undefined {
+    if (p && p.expiresAt && p.expiresAt.getTime() < Date.now()) {
+      return undefined;
+    }
+    return p;
+  }
+}

package/src/types/authenticator.ts

@@ -1,16 +1,21 @@
+import { AnyMap } from '@travetto/runtime';
 import { Principal } from './principal';
 
+/**
+ * Represents the general shape of additional login context, usually across multiple calls
+ */
+export interface AuthenticatorState extends AnyMap { }
+
 /**
  * Supports validation payload of type T into an authenticated principal
  *
  * @concrete ../internal/types#AuthenticatorTarget
  */
-export interface Authenticator<T = unknown, P extends Principal = Principal, C = unknown> {
+export interface Authenticator<T = unknown, C = unknown, P extends Principal = Principal> {
   /**
-   * Allows for the authenticator to be initialized if needed
-   * @param ctx
+   * Retrieve the authenticator state for the given request
    */
-  initialize?(ctx: C): Promise<void>;
+  getState?(context?: C): Promise<AuthenticatorState | undefined> | AuthenticatorState | undefined;
 
   /**
    * Verify the payload, ensuring the payload is correctly identified.
@@ -19,5 +24,5 @@ export interface Authenticator<T = unknown, P extends Principal = Principal, C =
    * @returns undefined if authentication is valid, but incomplete (multi-step)
    * @throws AppError if authentication fails
    */
-  authenticate(payload: T, ctx?: C): Promise<P | undefined> | P | undefined;
+  authenticate(payload: T, context?: C): Promise<P | undefined> | P | undefined;
 }

package/src/types/authorizer.ts

@@ -8,8 +8,7 @@ import { Principal } from './principal';
 export interface Authorizer<P extends Principal = Principal> {
   /**
    * Authorize inbound principal, verifying it's permission to access the system.
-   * @param principal
    * @returns New principal that conforms to the required principal shape
    */
-  authorize(principal: Principal): Promise<P> | P;
+  authorize(principal: P): Promise<P> | P;
 }

package/src/types/principal.ts

@@ -2,14 +2,18 @@ import { AnyMap } from '@travetto/runtime';
 
 /**
  * A user principal, including permissions and details
- * @concrete ../internal/types#PrincipalTarget
  * @augments `@travetto/rest:Context`
+ * @concrete ../internal/types#PrincipalTarget
  */
 export interface Principal<D = AnyMap> {
   /**
    * Primary identifier for a user
    */
-  id: string;
+  readonly id: string;
+  /**
+   * Unique identifier for the principal's lifecycle
+   */
+  readonly sessionId?: string;
   /**
    * Date of expiration
    */
@@ -18,20 +22,16 @@ export interface Principal<D = AnyMap> {
    * Date of issuance
    */
   issuedAt?: Date;
-  /**
-   * Max age in seconds a principal is valid
-   */
-  maxAge?: number;
   /**
    * The source of the issuance
    */
-  issuer?: string;
+  readonly issuer?: string;
   /**
    * Supplemental details
    */
-  details: D;
+  readonly details: D;
   /**
    * List of all provided permissions
    */
-  permissions?: string[];
+  readonly permissions?: string[];
 }

package/src/types/token.ts

@@ -0,0 +1 @@
+export type AuthToken = { value: string, type: string };

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2020 ArcSine Technologies
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/src/util.ts

@@ -1,44 +0,0 @@
-import crypto from 'node:crypto';
-import util from 'node:util';
-
-import { AppError, Util } from '@travetto/runtime';
-
-const pbkdf2 = util.promisify(crypto.pbkdf2);
-
-/**
- * Standard auth utilities
- */
-export class AuthUtil {
-
-  /**
-   * Generate a hash for a given value
-   *
-   * @param value Value to hash
-   * @param salt The salt value
-   * @param iterations Number of iterations on hashing
-   * @param keylen Length of hash
-   * @param digest Digest method
-   */
-  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));
-  }
-
-  /**
-   * Generate a salted password, with the ability to validate the password
-   *
-   * @param password
-   * @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): Promise<{ salt: string, hash: string }> {
-    if (!password) {
-      throw new AppError('Password is required', { category: 'data' });
-    }
-
-    salt = typeof salt === 'number' ? Util.uuid(salt) : salt;
-    const hash = await this.generateHash(password, salt);
-
-    return { salt, hash };
-  }
-}