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

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@bitblit/ratchet-warden-server",
-  "version": "6.0.146-alpha",
+  "version": "6.0.147-alpha",
   "description": "Typescript library to simplify using simplewebauthn and secondary auth methods over GraphQL",
   "sideEffects": false,
   "type": "module",
   "files": [
+    "src/**",
     "lib/**",
     "bin/**"
   ],
@@ -48,10 +49,10 @@
   "dependencies": {
     "@aws-sdk/client-s3": "3.922.0",
     "@aws-sdk/client-ses": "3.922.0",
-    "@bitblit/ratchet-aws": "6.0.146-alpha",
-    "@bitblit/ratchet-common": "6.0.146-alpha",
-    "@bitblit/ratchet-node-only": "6.0.146-alpha",
-    "@bitblit/ratchet-warden-common": "6.0.146-alpha",
+    "@bitblit/ratchet-aws": "6.0.147-alpha",
+    "@bitblit/ratchet-common": "6.0.147-alpha",
+    "@bitblit/ratchet-node-only": "6.0.147-alpha",
+    "@bitblit/ratchet-warden-common": "6.0.147-alpha",
     "@simplewebauthn/browser": "13.2.2",
     "@simplewebauthn/server": "13.2.2",
     "jsonwebtoken": "9.0.2"
@@ -59,9 +60,9 @@
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.922.0",
     "@aws-sdk/client-ses": "^3.922.0",
-    "@bitblit/ratchet-aws": "6.0.146-alpha",
-    "@bitblit/ratchet-common": "6.0.146-alpha",
-    "@bitblit/ratchet-warden-common": "6.0.146-alpha",
+    "@bitblit/ratchet-aws": "6.0.147-alpha",
+    "@bitblit/ratchet-common": "6.0.147-alpha",
+    "@bitblit/ratchet-warden-common": "6.0.147-alpha",
     "@simplewebauthn/browser": "^13.2.2",
     "@simplewebauthn/server": "^13.2.2",
     "jsonwebtoken": "^9.0.2"

package/src/build/ratchet-warden-server-info.ts

@@ -0,0 +1,19 @@
+import { BuildInformation } from '@bitblit/ratchet-common/build/build-information';
+
+export class RatchetWardenServerInfo {
+  // Empty constructor prevents instantiation
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  public static buildInformation(): BuildInformation {
+    const val: BuildInformation = {
+      version: 'LOCAL-SNAPSHOT',
+      hash: 'LOCAL-HASH',
+      branch: 'LOCAL-BRANCH',
+      tag: 'LOCAL-TAG',
+      timeBuiltISO: 'LOCAL-TIME-ISO',
+      notes: 'LOCAL-NOTES',
+    };
+    return val;
+  }
+}

package/src/server/provider/warden-default-send-magic-link-command-validator.ts

@@ -0,0 +1,21 @@
+/**
+ * The user details gets jammed into the JWT token upon login.  If one is not provided,
+ * the default only puts the WardenEntrySummary in there
+ */
+import { WardenEntry } from '@bitblit/ratchet-warden-common/common/model/warden-entry';
+import { SendMagicLink } from '@bitblit/ratchet-warden-common/common/command/send-magic-link';
+import { WardenSendMagicLinkCommandValidator } from './warden-send-magic-link-command-validator.js';
+
+export class WardenDefaultSendMagicLinkCommandValidator implements WardenSendMagicLinkCommandValidator {
+  public async allowMagicLinkCommand(cmd: SendMagicLink, _origin: string, _loggedInUser: WardenEntry): Promise<void> {
+    if (!cmd) {
+      throw new Error('Cannot process null magic link');
+    }
+    if (cmd.ttlSeconds && cmd.ttlSeconds > 3600) {
+      throw new Error('TTL may not exceed 3600 seconds');
+    }
+    if (cmd.overrideDestinationContact) {
+      throw new Error('You may not specify an overrideDestinationContact');
+    }
+  }
+}

package/src/server/provider/warden-default-user-decoration-provider.ts

@@ -0,0 +1,23 @@
+/**
+ * The user details gets jammed into the JWT token upon login.  If one is not provided,
+ * the default only puts the WardenEntrySummary in there
+ */
+import { WardenEntrySummary } from '@bitblit/ratchet-warden-common/common/model/warden-entry-summary';
+import { WardenEntry } from '@bitblit/ratchet-warden-common/common/model/warden-entry';
+import { WardenUtils } from '@bitblit/ratchet-warden-common/common/util/warden-utils';
+import { WardenUserDecoration } from '@bitblit/ratchet-warden-common/common/model/warden-user-decoration';
+import { WardenUserDecorationProvider } from './warden-user-decoration-provider.js';
+
+export class WardenDefaultUserDecorationProvider implements WardenUserDecorationProvider<WardenEntrySummary> {
+  public async fetchDecoration(wardenUser: WardenEntry): Promise<WardenUserDecoration<WardenEntrySummary>> {
+    // Default to 1 hour
+    const rval: WardenUserDecoration<WardenEntrySummary> = {
+      userTokenData: WardenUtils.stripWardenEntryToSummary(wardenUser),
+      proxyUserTokenData: null,
+      userTokenExpirationSeconds: 3600,
+      globalRoleIds: [],
+      teamRoleMappings: [],
+    };
+    return rval;
+  }
+}

package/src/server/provider/warden-dynamo-storage-provider-options.ts

@@ -0,0 +1,8 @@
+import { WardenTeamRoleMapping } from "@bitblit/ratchet-warden-common/common/model/warden-team-role-mapping";
+
+export class WardenDynamoStorageProviderOptions<T> {
+  tableName: string;
+  defaultTeamRoleMappings: WardenTeamRoleMapping[];
+  defaultTokenExpirationSeconds: number;
+  defaultDecoration?: T
+}

package/src/server/provider/warden-dynamo-storage-provider.ts

@@ -0,0 +1,278 @@
+import { DynamoRatchet } from '@bitblit/ratchet-aws/dynamodb/dynamo-ratchet';
+import { WardenDynamoStorageProviderOptions } from './warden-dynamo-storage-provider-options.js';
+import { WardenContact } from '@bitblit/ratchet-warden-common/common/model/warden-contact';
+import { WardenEntry } from '@bitblit/ratchet-warden-common/common/model/warden-entry';
+import { WardenEntrySummary } from '@bitblit/ratchet-warden-common/common/model/warden-entry-summary';
+import { DeleteCommandOutput, PutCommandOutput,ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import { Logger } from '@bitblit/ratchet-common/logger/logger';
+import { ErrorRatchet } from '@bitblit/ratchet-common/lang/error-ratchet';
+import { WardenUtils } from '@bitblit/ratchet-warden-common/common/util/warden-utils';
+import { ExpiringCodeProvider } from '@bitblit/ratchet-aws/expiring-code/expiring-code-provider';
+import { ExpiringCode } from '@bitblit/ratchet-aws/expiring-code/expiring-code';
+import { WardenStorageProvider } from "./warden-storage-provider.js";
+import { WardenUserDecorationProvider } from "./warden-user-decoration-provider.js";
+import { WardenUserDecoration } from "@bitblit/ratchet-warden-common/common/model/warden-user-decoration";
+import { WardenTeamRoleMapping } from "@bitblit/ratchet-warden-common/common/model/warden-team-role-mapping";
+
+
+// Create a ddb table with a hashkey of userId type string
+export class WardenDynamoStorageProvider<T> implements WardenStorageProvider, ExpiringCodeProvider, WardenUserDecorationProvider<T> {
+
+  private static readonly EXPIRING_CODE_PROVIDER_KEY: string = '__EXPIRING_CODE_DATA';
+
+  constructor(
+    private ddb: DynamoRatchet,
+    private options: WardenDynamoStorageProviderOptions<T>
+  ) {
+  }
+
+  public createDecoration(decoration: T): WardenUserDecoration<T> {
+    return {
+      globalRoleIds: [],
+      teamRoleMappings: this.options.defaultTeamRoleMappings,
+      userTokenExpirationSeconds: this.options.defaultTokenExpirationSeconds,
+      userTokenData: decoration,
+      proxyUserTokenData: null
+    };
+  }
+
+  public async updateRoles(userId: string, roles: WardenTeamRoleMapping[]): Promise<WardenUserDecoration<T>> {
+    const rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(userId);
+    if (rval) {
+      rval.decoration ??= this.createDecoration(null);
+      rval.decoration.teamRoleMappings = roles;
+      await this.updateInternal(rval);
+    } else {
+      throw ErrorRatchet.fErr('Cannot update roles - no entry found for %s', userId);
+    }
+
+    return this.fetchDecorationById(userId);
+  }
+
+  public async updateTokenExpirationSeconds(userId: string, newValue: number): Promise<WardenUserDecoration<T>> {
+    const rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(userId);
+    if (rval) {
+      rval.decoration ??= this.createDecoration(null);
+      rval.decoration.userTokenExpirationSeconds = newValue;
+      await this.updateInternal(rval);
+    } else {
+      throw ErrorRatchet.fErr('Cannot update roles - no entry found for %s', userId);
+    }
+
+    return this.fetchDecorationById(userId);
+  }
+
+  public async updateDecoration(userId: string, decoration:T): Promise<WardenUserDecoration<T>> {
+    const rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(userId);
+    if (rval) {
+      rval.decoration ??= this.createDecoration(null);
+      rval.decoration.userTokenData = decoration;
+      await this.updateInternal(rval);
+    } else {
+      throw ErrorRatchet.fErr('Cannot update roles - no entry found for %s', userId);
+    }
+
+    return this.fetchDecorationById(userId);
+  }
+
+  public async fetchDecoration(wardenUser: WardenEntry): Promise<WardenUserDecoration<T>> {
+    return this.fetchDecorationById(wardenUser.userId);
+  }
+
+  public async fetchDecorationById(userId: string): Promise<WardenUserDecoration<T>> {
+    const rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(userId);
+    return rval?.decoration;
+  }
+
+  // Sure, this is hackish... but DDB doesn't care, and it allows you to wrap up all the
+  // warden data in a single item
+  private async fetchExpiringCodes(): Promise<ExpiringCodeHolder> {
+    let rval: ExpiringCodeHolder = await this.ddb.simpleGet<ExpiringCodeHolder>(this.options.tableName, {
+      userId: WardenDynamoStorageProvider.EXPIRING_CODE_PROVIDER_KEY
+    });
+
+    if (!rval) {
+      rval = {
+        userId: WardenDynamoStorageProvider.EXPIRING_CODE_PROVIDER_KEY,
+        values: []
+      };
+      await this.updateInternal(rval as unknown as WardenDynamoStorageDataWrapper);  // Hack to piggyback
+    }
+
+    return rval;
+  }
+
+  private async updateInternal(val: WardenDynamoStorageDataWrapper): Promise<PutCommandOutput> {
+    return this.ddb.simplePut(this.options.tableName, val);
+  }
+
+  public async checkCode(code: string, context: string, deleteOnMatch?: boolean): Promise<boolean> {
+    const codes: ExpiringCodeHolder = await this.fetchExpiringCodes();
+    const rval: ExpiringCode = codes.values.find((c) => c.code === code && c.context === context);
+    if (rval) {
+      if (deleteOnMatch) {
+        codes.values = codes.values.filter((c) => c.code !== code || c.context !== context);
+        await this.updateInternal(codes as unknown as WardenDynamoStorageDataWrapper);  // Hack to piggyback
+      }
+      return true;
+    } else {
+      return !!rval;
+    }
+  }
+
+  public async storeCode(code: ExpiringCode): Promise<boolean> {
+    const codes: ExpiringCodeHolder = await this.fetchExpiringCodes();
+    codes.values.push(code);
+    const now: number = Date.now();
+    codes.values=codes.values.filter(c=>c.expiresEpochMS>now); // Always remove expired ones on storage
+    const stored: PutCommandOutput = await this.updateInternal(codes as unknown as WardenDynamoStorageDataWrapper);  // Hack to piggyback
+
+    return stored ? true : false;
+  }
+
+  private static contactToSearchString(contact: WardenContact): string {
+    const toFind: string = `${contact.type}:${contact.value}`;
+    return toFind;
+  }
+
+  private static thirdPartyToSearchString(thirdParty: string, thirdPartyId: string): string {
+    const toFind: string = `${thirdParty}:${thirdPartyId}`;
+    return toFind;
+  }
+
+  private async fetchInternalByUserId(userId: string): Promise<WardenDynamoStorageDataWrapper> {
+    return this.ddb.simpleGet<WardenDynamoStorageDataWrapper>(this.options.tableName, {userId: userId});
+  }
+
+  public async fetchCurrentUserChallenge(userId: string, relyingPartyId: string): Promise<string> {
+    const rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(userId);
+    const cuc: string = rval ? rval.currentUserChallenges.find((c) => c.startsWith(relyingPartyId)) : null;
+    return cuc ? cuc.substring(relyingPartyId.length+1) : null;
+  }
+
+
+
+  public async findEntryByThirdPartyId(thirdParty: string, thirdPartyId: string): Promise<WardenEntry> {
+    const toFind: string = WardenDynamoStorageProvider.thirdPartyToSearchString(thirdParty, thirdPartyId);
+    const scan: ScanCommandInput = {
+      TableName: this.options.tableName,
+      FilterExpression: 'contains(#thirdPartySearchString,:thirdPartySearchString)',
+      ExpressionAttributeNames: {
+        '#thirdPartySearchString': 'thirdPartySearchString',
+      },
+      ExpressionAttributeValues: {
+        ':thirdPartySearchString': toFind
+      }
+    };
+
+    const results: WardenDynamoStorageDataWrapper[] = await this.ddb.fullyExecuteScan<WardenDynamoStorageDataWrapper>(scan);
+    if (results && results.length > 0) {
+      const rval: WardenDynamoStorageDataWrapper = results[0];
+      return rval.entry;
+    } else {
+      Logger.info('No results found for %s', toFind);
+      return null;
+    }
+
+  }
+
+  public async findEntryByContact(contact: WardenContact): Promise<WardenEntry> {
+    const toFind: string = WardenDynamoStorageProvider.contactToSearchString(contact);
+    const scan: ScanCommandInput = {
+      TableName: this.options.tableName,
+      FilterExpression: 'contains(#contactSearchString,:contactSearchString)',
+      ExpressionAttributeNames: {
+        '#contactSearchString': 'contactSearchString',
+      },
+      ExpressionAttributeValues: {
+        ':contactSearchString': toFind
+      }
+    };
+
+    const results: WardenDynamoStorageDataWrapper[] = await this.ddb.fullyExecuteScan<WardenDynamoStorageDataWrapper>(scan);
+    if (results && results.length > 0) {
+      const rval: WardenDynamoStorageDataWrapper = results[0];
+      return rval.entry;
+    } else {
+      Logger.info('No results found for %s', toFind);
+      return null;
+    }
+
+  }
+
+  public async findEntryById(userId: string): Promise<WardenEntry> {
+    const rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(userId);
+    return rval ? rval.entry : null;
+  }
+
+  public async listUserSummaries(): Promise<WardenEntrySummary[]> {
+    // TODO: This is way too slow long term
+    const scan: ScanCommandInput = {
+      TableName: this.options.tableName,
+    };
+
+    const results: WardenDynamoStorageDataWrapper[] = await this.ddb.fullyExecuteScan<WardenDynamoStorageDataWrapper>(scan);
+    const rval: WardenEntrySummary[] = results.map(wd=>{
+      return WardenUtils.stripWardenEntryToSummary(wd.entry);
+    })
+    return rval;
+  }
+
+  public async removeEntry(userId: string): Promise<boolean> {
+    const tmp: DeleteCommandOutput = await this.ddb.simpleDelete(this.options.tableName, {userId: userId});
+    return tmp.Attributes ? true : false;
+  }
+
+  public async saveEntry(entry: WardenEntry): Promise<WardenEntry> {
+    let rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(entry.userId);
+    if (!rval) {
+      rval = {
+        userId: entry.userId,
+        entry: entry,
+        currentUserChallenges: [],
+        decoration: this.createDecoration(null),
+        contactSearchString: 'ContactSearch:  '+(entry.contactMethods || []).map((cm) => WardenDynamoStorageProvider.contactToSearchString(cm)).join(' '),
+        thirdPartySearchString: '3rdPartySearch:  '+(entry.thirdPartyAuthenticators || []).map((item) => WardenDynamoStorageProvider.thirdPartyToSearchString(item.thirdParty, item.thirdPartyId)).join(' '),
+      };
+    }
+    rval.entry = entry;
+    const now: number = Date.now();
+    rval.entry.updatedEpochMS = now;
+    rval.entry.createdEpochMS = rval.entry.createdEpochMS || now;
+    const saved: PutCommandOutput = await this.updateInternal(rval);
+    Logger.silly('Saved %j', saved);
+
+    const postSaveLookup: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(entry.userId);
+    return postSaveLookup.entry;
+  }
+
+  public async updateUserChallenge(userId: string, relyingPartyId: string, challenge: string): Promise<boolean> {
+    const rval: WardenDynamoStorageDataWrapper = await this.fetchInternalByUserId(userId);
+    if (!rval) {
+      throw ErrorRatchet.fErr('Cannot update user challenge - no entry found for %s', userId);
+    }
+    rval.currentUserChallenges = (rval.currentUserChallenges || []).filter((c) => !c.startsWith(relyingPartyId));
+    const cuc: string = relyingPartyId + ':' + challenge;
+    rval.currentUserChallenges.push(cuc);
+
+    const saved: PutCommandOutput = await this.updateInternal(rval);
+    Logger.silly('Saved %j', saved);
+    return saved.Attributes ? true : false;
+  }
+
+
+}
+
+export interface WardenDynamoStorageDataWrapper {
+  userId: string;
+  entry: WardenEntry;
+  decoration: WardenUserDecoration<any>;
+  currentUserChallenges: string[];
+  contactSearchString: string;
+  thirdPartySearchString: string;
+}
+
+export interface ExpiringCodeHolder {
+  userId: string;
+  values: ExpiringCode[];
+}

package/src/server/provider/warden-event-processing-provider.ts

@@ -0,0 +1,10 @@
+import { WardenEntry } from '@bitblit/ratchet-warden-common/common/model/warden-entry';
+
+/**
+ * Notifies the containing system when significant events happen
+ */
+
+export interface WardenEventProcessingProvider {
+  userCreated(entry: WardenEntry): Promise<void>;
+  userRemoved(entry: WardenEntry): Promise<void>;
+}

package/src/server/provider/warden-mailer-and-expiring-code-ratchet-single-use-code-provider.ts

@@ -0,0 +1,155 @@
+import { WardenSingleUseCodeProvider } from './warden-single-use-code-provider.js';
+import { Logger } from '@bitblit/ratchet-common/logger/logger';
+import { ErrorRatchet } from '@bitblit/ratchet-common/lang/error-ratchet';
+import { StringRatchet } from '@bitblit/ratchet-common/lang/string-ratchet';
+import { Base64Ratchet } from '@bitblit/ratchet-common/lang/base64-ratchet';
+import { WardenMailerAndExpiringCodeRatchetSingleUseCodeProviderOptions } from './warden-mailer-and-expiring-code-ratchet-single-user-provider-options.js';
+import { ExpiringCodeRatchet } from '@bitblit/ratchet-aws/expiring-code/expiring-code-ratchet';
+import { ExpiringCode } from '@bitblit/ratchet-aws/expiring-code/expiring-code';
+import { Mailer } from '@bitblit/ratchet-common/mail/mailer';
+import { ReadyToSendEmail } from '@bitblit/ratchet-common/mail/ready-to-send-email';
+import { SendEmailResult } from '@bitblit/ratchet-common/mail/send-email-result';
+import { WardenContactType } from '@bitblit/ratchet-warden-common/common/model/warden-contact-type';
+import { WardenContact } from '@bitblit/ratchet-warden-common/common/model/warden-contact';
+import { WardenCustomerMessageType } from '@bitblit/ratchet-warden-common/common/model/warden-customer-message-type';
+import { WardenCustomTemplateDescriptor } from '@bitblit/ratchet-warden-common/common/command/warden-custom-template-descriptor';
+
+/**
+ * Classes implementing WardenSingleUseCodeProvider are able to
+ * generate single-use codes for a user, and to validate a code
+ * provided by the user
+ **/
+export class WardenMailerAndExpiringCodeRatchetSingleUseCodeProvider implements WardenSingleUseCodeProvider {
+  private static defaultOptions(): WardenMailerAndExpiringCodeRatchetSingleUseCodeProviderOptions {
+    const rval: WardenMailerAndExpiringCodeRatchetSingleUseCodeProviderOptions = {
+      emailBaseLayoutName: undefined,
+      expiringTokenHtmlTemplateName: 'expiring-token-request-email',
+      expiringTokenTxtTemplateName: undefined,
+      magicLinkHtmlTemplateName: 'magic-token-request-email',
+      magicLinkTxtTemplateName: undefined,
+    };
+    return rval;
+  }
+
+  constructor(
+    private mailer: Mailer<any, any>,
+    private expiringCodeRatchet: ExpiringCodeRatchet,
+    private mailerOptions: WardenMailerAndExpiringCodeRatchetSingleUseCodeProviderOptions = WardenMailerAndExpiringCodeRatchetSingleUseCodeProvider.defaultOptions(),
+  ) {}
+  public handlesContactType(type: WardenContactType): boolean {
+    return type === WardenContactType.EmailAddress;
+  }
+
+  public async createAndSendNewCode(contact: WardenContact, relyingPartyName: string, origin: string): Promise<boolean> {
+    let rval: boolean = null;
+    const token: ExpiringCode = await this.expiringCodeRatchet.createNewCode({
+      context: contact.value,
+      length: 6,
+      alphabet: '0123456789',
+      timeToLiveSeconds: 300,
+      tags: ['Login'],
+    });
+    const msg: any = await this.formatMessage(contact, WardenCustomerMessageType.ExpiringCode, {
+      requestor: contact.value,
+      requestorB64: Base64Ratchet.encodeStringToBase64String(contact.value),
+      code: token.code,
+      relyingPartyName: relyingPartyName,
+      origin: origin
+    });
+    rval = await this.sendMessage(msg);
+    return rval;
+  }
+  public async checkCode(contactValue: string, code: string): Promise<boolean> {
+    const rval: boolean = await this.expiringCodeRatchet.checkCode(code, contactValue);
+    return rval;
+  }
+  public async createCodeAndSendMagicLink?(
+    loginContact: WardenContact,
+    relyingPartyName: string,
+    landingUrl: string,
+    metaIn?: Record<string, string>,
+    ttlSeconds?: number,
+    destinationContact?: WardenContact,
+    customTemplate?: WardenCustomTemplateDescriptor,
+  ): Promise<boolean> {
+    let rval: boolean = null;
+    const token: ExpiringCode = await this.expiringCodeRatchet.createNewCode({
+      context: loginContact.value,
+      length: 36,
+      alphabet: StringRatchet.UPPER_CASE_LATIN,
+      timeToLiveSeconds: ttlSeconds,
+      tags: ['MagicLink'],
+    });
+
+    const meta: Record<string, any> = Object.assign({}, metaIn || {}, { contact: loginContact });
+    const encodedMeta: string = Base64Ratchet.safeObjectToBase64JSON(meta || {});
+
+    const landingUrlFilled: string = StringRatchet.simpleTemplateFill(landingUrl, { CODE: token.code, META: encodedMeta }, true, '{', '}');
+
+    const context: Record<string, string> = Object.assign({}, meta || {}, {
+      landingUrl: landingUrlFilled,
+      code: token.code,
+      relyingPartyName: relyingPartyName,
+    });
+
+    const msgType: WardenCustomerMessageType = customTemplate ? WardenCustomerMessageType.Custom : WardenCustomerMessageType.MagicLink;
+    const msg: ReadyToSendEmail = await this.formatMessage(loginContact, msgType, context, destinationContact, customTemplate);
+    rval = await this.sendMessage(msg);
+    return rval;
+  }
+
+  public async formatMessage(
+    contact: WardenContact,
+    messageType: WardenCustomerMessageType,
+    context: Record<string, any>,
+    destinationContact?: WardenContact,
+    customTemplate?: WardenCustomTemplateDescriptor,
+  ): Promise<ReadyToSendEmail> {
+    const rts: ReadyToSendEmail = {
+      destinationAddresses: [destinationContact?.value || contact.value],
+      subject: customTemplate?.subjectLine || this.mailerOptions.magicLinkSubjectLine || 'Login token for '+contact.value,
+    };
+
+    Logger.info('Formatting Message for magic link, rts: %j, messageType: %s, context: %j', rts, messageType, context);
+
+    if (messageType === WardenCustomerMessageType.ExpiringCode) {
+      await this.mailer.fillEmailBody(
+        rts,
+        context,
+        this.mailerOptions.expiringTokenHtmlTemplateName,
+        this.mailerOptions.expiringTokenTxtTemplateName,
+        this.mailerOptions.emailBaseLayoutName,
+      );
+    } else if (messageType === WardenCustomerMessageType.MagicLink) {
+      await this.mailer.fillEmailBody(
+        rts,
+        context,
+        this.mailerOptions.magicLinkHtmlTemplateName,
+        this.mailerOptions.magicLinkTxtTemplateName,
+        this.mailerOptions.emailBaseLayoutName,
+      );
+    } else if (messageType === WardenCustomerMessageType.Custom) {
+      if (!customTemplate) {
+        throw ErrorRatchet.fErr('Cannot send custom message if customTemplate not set');
+      }
+      Logger.info('Sending custom template : %j', customTemplate);
+      await this.mailer.fillEmailBody(
+        rts,
+        context,
+        customTemplate.htmlVersion,
+        customTemplate.textVersion,
+        customTemplate.baseLayout === 'DEFAULT' ? this.mailerOptions.emailBaseLayoutName : customTemplate.baseLayout,
+      );
+    } else {
+      throw ErrorRatchet.fErr('No such message type : %s', messageType);
+    }
+
+    return rts;
+  }
+
+  public async sendMessage(message: ReadyToSendEmail): Promise<boolean> {
+    const rval: SendEmailResult<any, any> = await this.mailer.sendEmail(message);
+    Logger.debug('SendRawEmailResponse was : %j', rval);
+    return !!rval;
+  }
+}

package/src/server/provider/warden-mailer-and-expiring-code-ratchet-single-user-provider-options.ts

@@ -0,0 +1,10 @@
+//    Service for interacting with positions for a given user
+
+export interface WardenMailerAndExpiringCodeRatchetSingleUseCodeProviderOptions {
+  emailBaseLayoutName?: string;
+  expiringTokenHtmlTemplateName: string;
+  expiringTokenTxtTemplateName?: string;
+  magicLinkHtmlTemplateName: string;
+  magicLinkTxtTemplateName?: string;
+  magicLinkSubjectLine?: string;
+}

package/src/server/provider/warden-message-sending-provider.ts

@@ -0,0 +1,14 @@
+import { WardenContactType } from '@bitblit/ratchet-warden-common/common/model/warden-contact-type';
+import { WardenContact } from '@bitblit/ratchet-warden-common/common/model/warden-contact';
+import { WardenCustomerMessageType } from '@bitblit/ratchet-warden-common/common/model/warden-customer-message-type';
+
+/**
+ * Classes implementing WardenMessageSendingProvider are able to
+ * send expiring, single
+ */
+
+export interface WardenMessageSendingProvider<T> {
+  handlesContactType(type: WardenContactType): boolean;
+  sendMessage(contact: WardenContact, message: T): Promise<boolean>;
+  formatMessage(contact: WardenContact, messageType: WardenCustomerMessageType, context: Record<string, any>): Promise<T>;
+}

package/src/server/provider/warden-no-op-event-processing-provider.ts

@@ -0,0 +1,12 @@
+/**
+ * Default implementation of the event processing provider - does nothing
+ */
+import { WardenEntry } from '@bitblit/ratchet-warden-common/common/model/warden-entry';
+import { WardenEventProcessingProvider } from './warden-event-processing-provider.js';
+
+export class WardenNoOpEventProcessingProvider implements WardenEventProcessingProvider {
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  public async userCreated(_entry: WardenEntry): Promise<void> {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  public async userRemoved(_entry: WardenEntry): Promise<void> {}
+}

package/src/server/provider/warden-s3-single-file-storage-provider-options.ts

@@ -0,0 +1,6 @@
+//    Service for interacting with positions for a given user
+
+export interface WardenS3SingleFileStorageProviderOptions {
+  bucket: string;
+  dataFileKey: string;
+}