@bitblit/ratchet-warden-common 6.0.146-alpha → 6.0.147-alpha

package/src/common/error/warden-error.ts

@@ -0,0 +1,122 @@
+import { StringRatchet } from "@bitblit/ratchet-common/lang/string-ratchet";
+import { WardenErrorCode } from "./warden-error-codes";
+
+/**
+ * This is the superclass for errors that can be thrown in the Warden system -
+ * most aren't user-recoverable but some are or hold more data.
+ * 
+ * Big users of ratchet will notice similarities to WardenError which
+ * are not accidental
+ */
+export class WardenError<T = void> extends Error {
+  private static readonly WARDEN_ERROR_FLAG_KEY: string = '__wardenErrorFlag';
+  private _errorCode: number;
+  private _internalMessage: string;
+  private _publicMessage: string;
+  private _details: T;
+  private _wrappedError: Error;
+
+  constructor(code: number, internalMessage?: string, publicMessage?: string, wrapped?: Error, details?: T) {
+    super(StringRatchet.trimToNull(internalMessage)??'Warden Security Error');
+    this._errorCode = code;
+    this._internalMessage = StringRatchet.trimToNull(internalMessage)??'Warden Security Error'
+    this._publicMessage = StringRatchet.trimToNull(publicMessage) ?? this._internalMessage;
+    this._details = details;
+    this._wrappedError = wrapped;
+    this[WardenError.WARDEN_ERROR_FLAG_KEY] = true; // Just used to tell if one has been wrapped
+  }
+
+  public withFormattedInternalErrorMessage(format: string, ...input: any[]): WardenError<T> {
+    this.setFormattedInternalErrorMessage(format, ...input);
+    return this;
+  }
+
+  public setFormattedInternalErrorMessage(format: string, ...input: any[]): void {
+    const msg: string = StringRatchet.format(format, ...input);
+    this._internalMessage = msg;
+  }
+  
+  public withFormattedPublicErrorMessage(format: string, ...input: any[]): WardenError<T> {
+    this.setFormattedPublicErrorMessage(format, ...input);
+    return this;
+  }
+
+  public setFormattedPublicErrorMessage(format: string, ...input: any[]): void {
+    const msg: string = StringRatchet.format(format, ...input);
+    this._publicMessage = msg;
+  }
+
+  public withErrorCode(code: number): WardenError<T> {
+    this.errorCode = code; // Call setter
+    return this;
+  }
+
+  public withDetails(details: T): WardenError<T> {
+    this._details = details; // Call setter
+    return this;
+  }
+
+  public withWrappedError(err: Error): WardenError<T> {
+    this._wrappedError = err; // Call setter
+    return this;
+  }
+
+  public isWrappedError(): boolean {
+    return !!this._wrappedError;
+  }
+
+  public static wrapError<T = void>(err: Error): WardenError<T> {
+    let rval: WardenError<T> = null;
+    if (WardenError.objectIsWardenError(err)) {
+      rval = err as WardenError<T>;
+    } else {
+      rval = new WardenError<T>(WardenErrorCode.Unspecified).withWrappedError(err);
+    }
+    return rval;
+  }
+
+  public static objectIsWardenError(obj: any): boolean {
+    return obj && obj[WardenError.WARDEN_ERROR_FLAG_KEY] === true;
+  }
+
+  get errorCode(): number {
+    return this._errorCode;
+  }
+
+  set errorCode(value: number) {
+    this._errorCode = value;
+  }
+
+  get publicMessage(): string {
+    return this._publicMessage;
+  }
+
+  set publicMessage(value: string) {
+    this._publicMessage = value;
+  }
+
+  get internalMessage(): string {
+    return this._internalMessage;
+  }
+
+  set internalMessage(value: string) {
+    this._internalMessage = value;
+  }
+
+  get details(): T {
+    return this._details;
+  }
+
+  set details(value: T) {
+    this._details = value;
+  }
+
+  get wrappedError(): Error {
+    return this._wrappedError;
+  }
+
+  set wrappedError(value: Error) {
+    this._wrappedError = value;
+  }
+
+}

package/src/common/model/warden-contact-type.ts

@@ -0,0 +1,4 @@
+export enum WardenContactType {
+  TextCapablePhoneNumber = 'TextCapablePhoneNumber',
+  EmailAddress = 'EmailAddress',
+}

package/src/common/model/warden-contact.ts

@@ -0,0 +1,6 @@
+import { WardenContactType } from './warden-contact-type.js';
+
+export interface WardenContact {
+  value: string;
+  type: WardenContactType;
+}

package/src/common/model/warden-customer-message-type.ts

@@ -0,0 +1,5 @@
+export enum WardenCustomerMessageType {
+  ExpiringCode = 'ExpiringCode',
+  MagicLink = 'MagicLink',
+  Custom = 'Custom',
+}

package/src/common/model/warden-entry-summary.ts

@@ -0,0 +1,9 @@
+import { WardenContact } from './warden-contact.js';
+import { WardenWebAuthnEntrySummary } from './warden-web-authn-entry-summary.js';
+
+export interface WardenEntrySummary {
+  userId: string;
+  userLabel: string; // Usually full name, could be something else
+  contactMethods: WardenContact[];
+  webAuthnAuthenticatorSummaries: WardenWebAuthnEntrySummary[];
+}

package/src/common/model/warden-entry.ts

@@ -0,0 +1,14 @@
+import { WardenWebAuthnEntry } from './warden-web-authn-entry.js';
+import { WardenContact } from './warden-contact.js';
+import { WardenThirdPartyAuthentication } from "./warden-third-party-authentication.js";
+
+export interface WardenEntry {
+  userId: string;
+  userLabel: string; // Usually full name, could be something else
+  contactMethods: WardenContact[];
+  tags: string[];
+  webAuthnAuthenticators: WardenWebAuthnEntry[];
+  thirdPartyAuthenticators: WardenThirdPartyAuthentication[];
+  createdEpochMS: number;
+  updatedEpochMS: number;
+}

package/src/common/model/warden-jwt-token.ts

@@ -0,0 +1,15 @@
+import { CommonJwtToken } from '@bitblit/ratchet-common/jwt/common-jwt-token';
+import { WardenEntrySummary } from './warden-entry-summary.js';
+import { WardenTeamRoleMapping } from "./warden-team-role-mapping.ts";
+
+export interface WardenJwtToken<T> extends CommonJwtToken<T> {
+  wardenData: WardenEntrySummary;
+
+  // This is built using a combo of the user data that warden tracks, and that the decorator tracks
+  // Decorator output goes into the user and proxy fields from commonJwtToken, plus the
+  // fields below
+
+  globalRoleIds: string[];
+  teamRoleMappings: WardenTeamRoleMapping[];
+
+}

package/src/common/model/warden-login-request-type.ts

@@ -0,0 +1,6 @@
+export enum WardenLoginRequestType {
+  WebAuthn='WebAuthn',
+  ExpiringToken='ExpiringToken',
+  JwtTokenToRefresh='JwtTokenToRefresh',
+  ThirdParty='ThirdParty',
+}

package/src/common/model/warden-login-request.ts

@@ -0,0 +1,15 @@
+import { WardenContact } from './warden-contact.js';
+import { AuthenticationResponseJSON } from '@simplewebauthn/browser';
+import { WardenLoginRequestType } from "./warden-login-request-type.js";
+import { WardenLoginThirdPartyToken } from "./warden-login-third-party-token";
+
+export interface WardenLoginRequest {
+  type: WardenLoginRequestType;
+  userId?: string;
+  contact?: WardenContact;
+  webAuthn?: AuthenticationResponseJSON;
+  thirdPartyToken?: WardenLoginThirdPartyToken;
+  expiringToken?: string;
+  jwtTokenToRefresh?: string;
+  createUserIfMissing?: boolean;
+}

package/src/common/model/warden-login-results.ts

@@ -0,0 +1,8 @@
+import { WardenLoginRequest } from './warden-login-request.js';
+
+export interface WardenLoginResults {
+  request: WardenLoginRequest;
+  userId?: string;
+  jwtToken?: string;
+  error?: string;
+}

package/src/common/model/warden-login-third-party-token.ts

@@ -0,0 +1,5 @@
+
+export interface WardenLoginThirdPartyToken {
+  thirdParty: string;
+  token: string;
+}

package/src/common/model/warden-permission.ts

@@ -0,0 +1,4 @@
+export interface WardenPermission {
+  actions: string[];
+  resourceSuffixes: string[];
+}

package/src/common/model/warden-role.ts

@@ -0,0 +1,8 @@
+import { WardenPermission } from "./warden-permission.ts";
+
+export interface WardenRole {
+  roleId: string;
+  label: string;
+  description?: string;
+  permissions: WardenPermission[];
+}

package/src/common/model/warden-store-registration-response-type.ts

@@ -0,0 +1,5 @@
+export enum WardenStoreRegistrationResponseType {
+  Verified = 'Verified',
+  Failed = 'Failed',
+  Error = 'Error',
+}

package/src/common/model/warden-store-registration-response.ts

@@ -0,0 +1,9 @@
+import { WardenStoreRegistrationResponseType } from './warden-store-registration-response-type.js';
+import { WardenEntry } from './warden-entry.js';
+
+export interface WardenStoreRegistrationResponse {
+  updatedEntry?: WardenEntry;
+  registrationResponseId: string;
+  result: WardenStoreRegistrationResponseType;
+  error?: string;
+}

package/src/common/model/warden-team-role-mapping.ts

@@ -0,0 +1,4 @@
+export interface WardenTeamRoleMapping {
+  teamId: string;
+  roleId: string;
+}

package/src/common/model/warden-team.ts

@@ -0,0 +1,5 @@
+export interface WardenTeam {
+  teamId: string;
+  label: string;
+  description?: string;
+}

package/src/common/model/warden-third-party-authentication.ts

@@ -0,0 +1,6 @@
+
+export interface WardenThirdPartyAuthentication{
+  thirdParty: string;
+  thirdPartyId: string;
+  meta?: Record<string,string>;
+}

package/src/common/model/warden-user-decoration.ts

@@ -0,0 +1,10 @@
+import { WardenTeamRoleMapping } from './warden-team-role-mapping.ts';
+
+export interface WardenUserDecoration<T> {
+  userTokenData: T;
+  proxyUserTokenData: T;
+  userTokenExpirationSeconds: number;
+
+  globalRoleIds: string[];
+  teamRoleMappings: WardenTeamRoleMapping[];
+}

package/src/common/model/warden-web-authn-entry-summary.ts

@@ -0,0 +1,6 @@
+export interface WardenWebAuthnEntrySummary {
+  origin: string;
+  applicationName: string;
+  deviceLabel: string;
+  credentialIdBase64: string;
+}

package/src/common/model/warden-web-authn-entry.ts

@@ -0,0 +1,14 @@
+import { WardenWebAuthnTransportFutureType } from './warden-web-authn-transport-future-type.js';
+
+export interface WardenWebAuthnEntry {
+  origin: string;
+  applicationName: string;
+  deviceLabel: string;
+
+  credentialIdBase64: string;
+  credentialPublicKeyBase64: string;
+  counter: number;
+  credentialBackedUp: boolean;
+  credentialDeviceType: string;
+  transports?: WardenWebAuthnTransportFutureType[];
+}

package/src/common/model/warden-web-authn-transport-future-type.ts

@@ -0,0 +1,8 @@
+export enum WardenWebAuthnTransportFutureType {
+  ble = 'ble',
+  internal = 'internal',
+  nfc = 'nfc',
+  usb = 'usb',
+  cable = 'cable',
+  hybrid = 'hybrid',
+}

package/src/common/util/warden-utils.spec.ts

@@ -0,0 +1,15 @@
+import { WardenContactType } from '../model/warden-contact-type.js';
+import { WardenContact } from '../model/warden-contact.js';
+import { WardenUtils } from './warden-utils.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#WardenUtils', () => {
+  //beforeEach(() => {});
+
+  test('Should convert a string to a contact type', async () => {
+    const output: WardenContact = WardenUtils.stringToWardenContact('test@test.com');
+    expect(output).not.toBeNull();
+    expect(output.value).toEqual('test@test.com');
+    expect(output.type).toEqual(WardenContactType.EmailAddress);
+  });
+});

package/src/common/util/warden-utils.ts

@@ -0,0 +1,284 @@
+import { WardenContact } from "../model/warden-contact.js";
+import { WardenContactType } from "../model/warden-contact-type.js";
+
+import { Logger } from "@bitblit/ratchet-common/logger/logger";
+import { StringRatchet } from "@bitblit/ratchet-common/lang/string-ratchet";
+import { WardenEntrySummary } from "../model/warden-entry-summary.js";
+import { WardenEntry } from "../model/warden-entry.js";
+import { WardenLoginRequest } from "../model/warden-login-request.js";
+import { WardenTeamRoleMapping } from "../model/warden-team-role-mapping.ts";
+import { WardenWebAuthnEntry } from "../model/warden-web-authn-entry.js";
+import { WardenWebAuthnEntrySummary } from "../model/warden-web-authn-entry-summary.js";
+import { WardenLoggedInUserWrapper } from "../../client/provider/warden-logged-in-user-wrapper.js";
+import { WardenLoginRequestType } from "../model/warden-login-request-type.ts";
+import { WardenUserDecoration } from "../model/warden-user-decoration.ts";
+import { BooleanRatchet } from "@bitblit/ratchet-common/lang/boolean-ratchet";
+import { WardenJwtToken } from "../model/warden-jwt-token.ts";
+
+export class WardenUtils {
+  // Prevent instantiation
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+  constructor() {
+    // Empty
+  }
+
+  public static extractContactsOfType(req: WardenEntry | WardenEntrySummary, type: WardenContactType): string[] {
+    let rval: string[] = null;
+    if (req?.contactMethods) {
+      rval = req.contactMethods.filter((s) => s.type === type).map((s) => s.value);
+    }
+    return rval;
+  }
+
+  public static loginRequestErrors(req: WardenLoginRequest): string[] {
+    const rval: string[] = [];
+
+    if (req) {
+      if (req.type) {
+        switch(req.type) {
+          case WardenLoginRequestType.ExpiringToken:
+            if (!req.userId && !WardenUtils.validContact(req.contact)) {
+              rval.push('User ID or contact is required');
+            }
+            if (!req.expiringToken) {
+              rval.push('Expiring token is required');
+            }
+            break;
+          case WardenLoginRequestType.ThirdParty:
+            if (req.thirdPartyToken) {
+              if (!req.thirdPartyToken.thirdParty) {
+                rval.push('Third party is required');
+              }
+              if (!req.thirdPartyToken.token) {
+                rval.push('Third party token is required');
+              }
+            } else {
+              rval.push('Third party auth is required');
+            }
+            break;
+          case WardenLoginRequestType.WebAuthn:
+            if (!req.userId && !WardenUtils.validContact(req.contact)) {
+              rval.push('User ID or contact is required');
+            }
+            if (!req.webAuthn) {
+              rval.push('Web authn is required');
+            }
+            break;
+          case WardenLoginRequestType.JwtTokenToRefresh:
+            if (!req.jwtTokenToRefresh) {
+              rval.push('JwtToken is required');
+            }
+          break;
+          default: rval.push('Unknown request type');
+        }
+      } else {
+        rval.push('Request type is null');
+      }
+    } else {
+      rval.push('Request is null');
+    }
+    return rval;
+  }
+
+
+  public static validLoginRequest(req: WardenLoginRequest): boolean {
+    return WardenUtils.loginRequestErrors(req).length === 0;
+  }
+
+  public static stringToWardenContact(input: string): WardenContact {
+    let rval: WardenContact = null;
+    const type: WardenContactType = WardenUtils.stringToContactType(input);
+    if (type) {
+      rval = {
+        type: type,
+        value: input,
+      };
+    } else {
+      Logger.error('Failed to convert a string to a contact type', input);
+    }
+    return rval;
+  }
+
+  public static teamRolesToRoles(teamRoles: WardenTeamRoleMapping[]): string[] {
+    const rval: string[] = teamRoles?.length ? teamRoles.map((t) => WardenUtils.teamRoleToRoleString(t)) : [];
+    return rval;
+  }
+
+  public static roleStringsToTeamRoles(roles: string[]): WardenTeamRoleMapping[] {
+    const rval: WardenTeamRoleMapping[] = roles?.length ? roles.map((t) => WardenUtils.roleStringToTeamRole(t)) : [];
+    return rval;
+  }
+
+  public static roleStringToTeamRole(role: string): WardenTeamRoleMapping {
+    let rval: WardenTeamRoleMapping = null;
+    if (role && role.indexOf('_/_') >= 0) {
+      const sp: string[] = role.split('_/_');
+      rval = {
+        teamId: sp[0],
+        roleId: sp[1],
+      };
+    }
+    return rval;
+  }
+
+  public static teamRoleToRoleString(tr: WardenTeamRoleMapping): string {
+    let rval: string = null;
+    if (tr?.roleId && tr?.teamId) {
+      rval = tr.teamId + '_/_' + tr.roleId;
+    }
+    return rval;
+  }
+
+  public static stringToContactType(input: string): WardenContactType {
+    let rval: WardenContactType = null;
+    if (StringRatchet.trimToNull(input)) {
+      rval = WardenUtils.stringIsEmailAddress(input) ? WardenContactType.EmailAddress : null;
+      rval = !rval && WardenUtils.stringIsPhoneNumber(input) ? WardenContactType.TextCapablePhoneNumber : rval;
+    }
+    return rval;
+  }
+
+  public static validContact(contact: WardenContact): boolean {
+    let rval: boolean = false;
+    if (contact?.type && StringRatchet.trimToNull(contact?.value)) {
+      switch (contact.type) {
+        case WardenContactType.EmailAddress:
+          rval = WardenUtils.stringIsEmailAddress(contact.value);
+          break;
+        case WardenContactType.TextCapablePhoneNumber:
+          rval = WardenUtils.stringIsPhoneNumber(contact.value);
+          break;
+        default:
+          rval = false;
+      }
+    }
+
+    return rval;
+  }
+
+  public static stringIsEmailAddress(value: string): boolean {
+    return !!value.match(/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$/);
+  }
+
+  public static stringIsPhoneNumber(value: string): boolean {
+    return !!value.match(/^[\\+]?[(]?[0-9]{3}[)]?[-\\s\\.]?[0-9]{3}[-\\s\\.]?[0-9]{4,6}$/im);
+  }
+
+  public static stripWardenEntryToSummary(we: WardenEntry): WardenEntrySummary {
+    const rval: WardenEntrySummary = we
+      ? {
+          userId: we.userId,
+          userLabel: we.userLabel,
+          contactMethods: we.contactMethods,
+          webAuthnAuthenticatorSummaries: (we?.webAuthnAuthenticators || []).map((s) => WardenUtils.stripWardenWebAuthnEntryToSummary(s)),
+        }
+      : null;
+    return rval;
+  }
+
+  public static stripWardenWebAuthnEntryToSummary(we: WardenWebAuthnEntry): WardenWebAuthnEntrySummary {
+    const rval: WardenWebAuthnEntrySummary = we
+      ? {
+          origin: we.origin,
+          applicationName: we.applicationName,
+          deviceLabel: we.deviceLabel,
+          credentialIdBase64: we.credentialIdBase64,
+        }
+      : null;
+    return rval;
+  }
+
+  public static wrapperIsExpired(value: WardenLoggedInUserWrapper<any>): boolean {
+    const rval: boolean = value?.userObject?.exp && value.expirationEpochSeconds < Date.now() / 1000;
+    return rval;
+  }
+
+  public static userHasGlobalRole(user: WardenUserDecoration<any>, roleId: string): boolean {
+    return WardenUtils.userHasGlobalRoles(user, [roleId], true);
+  }
+
+  public static userHasRoleOnTeam(user: WardenUserDecoration<any>,teamId: string, roleId: string): boolean {
+    return WardenUtils.userHasRolesOnTeam(user, teamId, [roleId], true);
+  }
+
+  public static userHasAtLeastOneGlobalRole(user: WardenUserDecoration<any>, roleIds: string[]): boolean {
+    return WardenUtils.userHasGlobalRoles(user, roleIds, false);
+  }
+
+  public static userHasAtLeastOneRoleOnTeam(user: WardenUserDecoration<any>, teamId: string, roleIds: string[]): boolean {
+    return WardenUtils.userHasRolesOnTeam(user, teamId, roleIds, false);
+  }
+
+
+  public static userHasAllGlobalRoles(user: WardenUserDecoration<any>, roleIds: string[]): boolean {
+    return WardenUtils.userHasGlobalRoles(user, roleIds, true);
+  }
+
+  public static userHasAllRolesOnTeam(user: WardenUserDecoration<any>, teamId: string, roleIds: string[]): boolean {
+    return WardenUtils.userHasRolesOnTeam(user, teamId, roleIds, true);
+  }
+
+
+  public static userHasGlobalRoles(user: WardenUserDecoration<any>, inRoleIds: string[], combineWithAnd: boolean): boolean {
+    let rval: boolean = false;
+    const roleIds: string[] = inRoleIds ? inRoleIds.map(r=>StringRatchet.trimToNull(r)?.toLowerCase()) : null
+    if (user && roleIds && roleIds.length > 0) {
+      const hasMap: boolean[] = user ? roleIds.map(r=>!!user.globalRoleIds.find(gr=>StringRatchet.trimToEmpty(gr).toLowerCase()===r)) : [false];
+      rval = combineWithAnd ? BooleanRatchet.allTrue(hasMap) : BooleanRatchet.anyTrue(hasMap);
+    }
+    return rval;
+  }
+
+  public static userHasRolesOnTeam(user: WardenUserDecoration<any>, inTeamId: string, inRoleIds: string[], combineWithAnd: boolean): boolean {
+    let rval: boolean = false;
+    const teamId: string = StringRatchet.trimToNull(inTeamId)?.toLowerCase();
+    const roleIds: string[] = inRoleIds ? inRoleIds.map(r=>StringRatchet.trimToNull(r)?.toLowerCase()) : null
+    if (user && teamId && roleIds && roleIds.length > 0) {
+      const hasMap: boolean[] = user ? roleIds.map(r=>!!(user?.teamRoleMappings?.find(s=>StringRatchet.trimToEmpty(s.teamId).toLowerCase()===teamId && StringRatchet.trimToEmpty(s.roleId).toLowerCase()===r))) : [false];
+      rval = combineWithAnd ? BooleanRatchet.allTrue(hasMap) : BooleanRatchet.anyTrue(hasMap);
+    }
+
+    return rval;
+  }
+
+  // Just a synonym since that is how some people think
+  public static userIsTeamMember(user: WardenUserDecoration<any>, inTeamId: string): boolean {
+    return WardenUtils.userHasAnyRoleOnTeam(user, inTeamId);
+  }
+
+  public static userHasAnyRoleOnTeam(user: WardenUserDecoration<any>, inTeamId: string): boolean {
+    let rval: boolean = false;
+    const teamId: string = StringRatchet.trimToNull(inTeamId)?.toLowerCase();
+    if (user && teamId) {
+      rval = !!user.teamRoleMappings.find(s=>StringRatchet.trimToNull(s.teamId).toLowerCase()===teamId);
+    }
+
+    return rval;
+  }
+
+  public static usersTeamMemberships(user: WardenUserDecoration<any>): string[] {
+    let rval: string[] = [];
+    if (user) {
+      const s = new Set<string>(user.teamRoleMappings.map(s=>StringRatchet.trimToNull(s.teamId).toLowerCase()));
+      rval = Array.from(s);
+    }
+    return rval;
+  }
+
+  public static wardenUserDecorationFromToken<T>(jwt: WardenJwtToken<T>): WardenUserDecoration<T> {
+    let rval: WardenUserDecoration<any> = null;
+    if (jwt) {
+      rval = {
+        userTokenData: jwt.user,
+        proxyUserTokenData: jwt.proxy,
+        userTokenExpirationSeconds: null,
+
+        globalRoleIds: jwt.globalRoleIds,
+        teamRoleMappings: jwt.teamRoleMappings
+      }
+    }
+    return rval;
+  }
+
+
+}