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

package/src/server/warden-service.ts

@@ -0,0 +1,815 @@
+import {
+  AuthenticationResponseJSON,
+  AuthenticatorTransportFuture,
+  generateAuthenticationOptions,
+  GenerateAuthenticationOptionsOpts,
+  generateRegistrationOptions,
+  PublicKeyCredentialCreationOptionsJSON,
+  PublicKeyCredentialRequestOptionsJSON,
+  RegistrationResponseJSON,
+  VerifiedAuthenticationResponse,
+  VerifiedRegistrationResponse,
+  verifyAuthenticationResponse,
+  VerifyAuthenticationResponseOpts,
+  verifyRegistrationResponse,
+  VerifyRegistrationResponseOpts
+} from "@simplewebauthn/server";
+import { WardenServiceOptions } from "./warden-service-options.js";
+import { WardenContact } from "@bitblit/ratchet-warden-common/common/model/warden-contact";
+import {
+  WardenCustomTemplateDescriptor
+} from "@bitblit/ratchet-warden-common/common/command/warden-custom-template-descriptor";
+import { WardenEntry } from "@bitblit/ratchet-warden-common/common/model/warden-entry";
+import { WardenUtils } from "@bitblit/ratchet-warden-common/common/util/warden-utils";
+import { WardenLoginRequest } from "@bitblit/ratchet-warden-common/common/model/warden-login-request";
+import { WardenCommand } from "@bitblit/ratchet-warden-common/common/command/warden-command";
+import { WardenCommandResponse } from "@bitblit/ratchet-warden-common/common/command/warden-command-response";
+import { WardenLoginResults } from "@bitblit/ratchet-warden-common/common/model/warden-login-results";
+import {
+  WardenStoreRegistrationResponse
+} from "@bitblit/ratchet-warden-common/common/model/warden-store-registration-response";
+import { WardenUserDecoration } from "@bitblit/ratchet-warden-common/common/model/warden-user-decoration";
+import { WardenJwtToken } from "@bitblit/ratchet-warden-common/common/model/warden-jwt-token";
+import {
+  WardenStoreRegistrationResponseType
+} from "@bitblit/ratchet-warden-common/common/model/warden-store-registration-response-type";
+import { WardenWebAuthnEntry } from "@bitblit/ratchet-warden-common/common/model/warden-web-authn-entry";
+
+import { RequireRatchet } from "@bitblit/ratchet-common/lang/require-ratchet";
+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 { ExpiredJwtHandling } from "@bitblit/ratchet-common/jwt/expired-jwt-handling";
+
+import { WardenDefaultUserDecorationProvider } from "./provider/warden-default-user-decoration-provider.js";
+import { WardenNoOpEventProcessingProvider } from "./provider/warden-no-op-event-processing-provider.js";
+import { WardenSingleUseCodeProvider } from "./provider/warden-single-use-code-provider.js";
+import {
+  WardenDefaultSendMagicLinkCommandValidator
+} from "./provider/warden-default-send-magic-link-command-validator.js";
+import { WardenLoginRequestType } from "@bitblit/ratchet-warden-common/common/model/warden-login-request-type";
+import {
+  WardenThirdPartyAuthentication
+} from "@bitblit/ratchet-warden-common/common/model/warden-third-party-authentication";
+import { WardenThirdPartyAuthenticationProvider } from "./provider/warden-third-party-authentication-provider.js";
+import { WardenEntryBuilder } from "./warden-entry-builder.js";
+import { WardenAuthorizer } from "./warden-authorizer.ts";
+import { WardenWebAuthnExportToken } from "./warden-web-authn-export-token.ts";
+
+export class WardenService {
+  private opts: WardenServiceOptions;
+  private cacheAuthorizer: WardenAuthorizer;
+
+  constructor(private inOptions: WardenServiceOptions) {
+    RequireRatchet.notNullOrUndefined(inOptions, "options");
+    RequireRatchet.notNullOrUndefined(inOptions.relyingPartyName, "options.relyingPartyName");
+    RequireRatchet.notNullUndefinedOrEmptyArray(inOptions.allowedOrigins, "options.allowedOrigins");
+    RequireRatchet.notNullOrUndefined(inOptions.storageProvider, "options.storageProvider");
+    RequireRatchet.notNullOrUndefined(inOptions.jwtRatchet, "options.jwtRatchet");
+    RequireRatchet.notNullUndefinedOrEmptyArray(inOptions.singleUseCodeProviders, "options.singleUseCodeProviders");
+
+    this.opts = Object.assign(
+      {
+        userTokenDataProvider: new WardenDefaultUserDecorationProvider(),
+        eventProcessor: new WardenNoOpEventProcessingProvider(),
+        sendMagicLinkCommandValidator: new WardenDefaultSendMagicLinkCommandValidator()
+      },
+      inOptions
+    );
+    this.cacheAuthorizer = new WardenAuthorizer(inOptions);
+  }
+
+  public get authorizer(): WardenAuthorizer {
+    return this.cacheAuthorizer;
+  }
+
+  public get options(): WardenServiceOptions {
+    return Object.assign({}, this.opts); // Don't allow a reader to change
+  }
+
+  // Passthru for very common use case
+  public findEntryByContact(contact: WardenContact): Promise<WardenEntry> {
+    return this.opts.storageProvider.findEntryByContact(contact);
+  }
+
+  // Passthru for very common use case
+  public findEntryById(userId: string): Promise<WardenEntry> {
+    return this.opts.storageProvider.findEntryById(userId);
+  }
+
+  // A helper function for bridging across GraphQL as an embedded JSON command
+  public async processCommandStringToString(cmdString: string, origin: string, loggedInUserId: string): Promise<string> {
+    let rval: string = null;
+    try {
+      const cmd: WardenCommand = JSON.parse(cmdString);
+      const resp: WardenCommandResponse = await this.processCommandToResponse(cmd, origin, loggedInUserId);
+      if (resp === null) {
+        Logger.warn("Response was null for %s %s %s", cmdString, origin, loggedInUserId);
+      } else {
+        rval = JSON.stringify(resp);
+      }
+    } catch (err) {
+      // Just cast it directly
+      const errString: string = ErrorRatchet.safeStringifyErr(err);
+      Logger.error("Failed %s : %j", errString, cmdString, err);
+      rval = JSON.stringify({ error: errString } as WardenCommandResponse);
+    }
+    return rval;
+  }
+
+  // A helper function for bridging across GraphQL as an embedded JSON command
+  public async processCommandToResponse(cmd: WardenCommand, origin: string, loggedInUserId: string): Promise<WardenCommandResponse> {
+    let rval: WardenCommandResponse = null;
+    if (cmd) {
+      Logger.info("Processing command : UserID: %s  Origin: %s Command: %j", loggedInUserId, origin, cmd);
+
+      if (cmd.sendExpiringValidationToken) {
+        rval = { sendExpiringValidationToken: await this.sendExpiringValidationToken(cmd.sendExpiringValidationToken, origin) };
+      } else if (cmd.generateWebAuthnAuthenticationChallengeForUserId) {
+        const tmp: PublicKeyCredentialRequestOptionsJSON = await this.generateWebAuthnAuthenticationChallengeForUserId(
+          cmd.generateWebAuthnAuthenticationChallengeForUserId,
+          origin
+        );
+        rval = { generateWebAuthnAuthenticationChallengeForUserId: { dataAsJson: JSON.stringify(tmp) } };
+      } else if (cmd.createAccount) {
+        const newEntry: WardenEntry = await this.createAccount(
+          cmd.createAccount.contact,
+          origin,
+          cmd.createAccount.sendCode,
+          cmd.createAccount.label,
+          cmd.createAccount.tags
+        );
+        rval = {
+          createAccount: newEntry.userId
+        };
+      } else if (cmd.sendMagicLink) {
+        if (cmd?.sendMagicLink?.contactLookup && cmd?.sendMagicLink?.contact) {
+          throw ErrorRatchet.fErr("You may not specify both contact and contactLookup");
+        }
+        if (!cmd?.sendMagicLink?.contactLookup && !cmd?.sendMagicLink?.contact) {
+          throw ErrorRatchet.fErr("You must not specify either contact and contactLookup");
+        }
+        if (cmd.sendMagicLink.contactLookup) {
+          const entry: WardenEntry = await this.findEntryById(cmd.sendMagicLink.contactLookup.userId);
+          if (entry) {
+            if (cmd.sendMagicLink.contactLookup.contactType) {
+              // Use the one specified, otherwise just first one
+              cmd.sendMagicLink.contact = (entry.contactMethods || []).find(
+                (cm) => cm.type === cmd.sendMagicLink.contactLookup.contactType
+              );
+            } else {
+              cmd.sendMagicLink.contact = (entry.contactMethods || []).length > 0 ? entry.contactMethods[0] : null;
+            }
+          }
+          cmd.sendMagicLink.contactLookup = null;
+        }
+
+        if (!cmd.sendMagicLink.contact) {
+          throw ErrorRatchet.fErr("Could not find contract entry either directly or by lookup");
+        }
+        // Now run all allowance checks on the link
+        const loggedInUser: WardenEntry = StringRatchet.trimToNull(loggedInUserId)
+          ? await this.opts.storageProvider.findEntryById(loggedInUserId)
+          : null;
+
+        await this.opts.sendMagicLinkCommandValidator.allowMagicLinkCommand(cmd.sendMagicLink, origin, loggedInUser);
+
+        const ttlSeconds: number = cmd?.sendMagicLink?.ttlSeconds || 300;
+
+        rval = {
+          sendMagicLink: await this.sendMagicLink(
+            cmd.sendMagicLink.contact,
+            cmd.sendMagicLink.overrideDestinationContact,
+            this.opts.relyingPartyName,
+            cmd.sendMagicLink.landingUrl,
+            cmd.sendMagicLink.meta,
+            ttlSeconds,
+            cmd.sendMagicLink.customTemplate
+          )
+        };
+      } else if (cmd.generateWebAuthnRegistrationChallengeForLoggedInUser) {
+        if (!StringRatchet.trimToNull(loggedInUserId)) {
+          ErrorRatchet.throwFormattedErr("This requires a logged in user");
+        }
+        const tmp: PublicKeyCredentialCreationOptionsJSON = await this.generateWebAuthnRegistrationChallengeForLoggedInUser(
+          loggedInUserId,
+          origin
+        );
+        rval = { generateWebAuthnRegistrationChallengeForLoggedInUser: { dataAsJson: JSON.stringify(tmp) } };
+      } else if (cmd.addContactToLoggedInUser) {
+        if (!WardenUtils.validContact(cmd.addContactToLoggedInUser)) {
+          ErrorRatchet.throwFormattedErr("Cannot add, invalid contact %j", cmd.addContactToLoggedInUser);
+        } else {
+          const out: boolean = await this.addContactMethodToUser(loggedInUserId, cmd.addContactToLoggedInUser);
+          rval = { addContactToLoggedInUser: out };
+        }
+      } else if (cmd.addWebAuthnRegistrationToLoggedInUser) {
+        if (!StringRatchet.trimToNull(loggedInUserId)) {
+          ErrorRatchet.throwFormattedErr("This requires a logged in user");
+        }
+        const data: RegistrationResponseJSON = JSON.parse(cmd.addWebAuthnRegistrationToLoggedInUser.webAuthn.dataAsJson);
+        const out: WardenStoreRegistrationResponse = await this.storeAuthnRegistration(
+          loggedInUserId,
+          origin,
+          cmd.addWebAuthnRegistrationToLoggedInUser.applicationName,
+          cmd.addWebAuthnRegistrationToLoggedInUser.deviceLabel,
+          data
+        );
+        if (out.updatedEntry) {
+          rval = { addWebAuthnRegistrationToLoggedInUser: WardenUtils.stripWardenEntryToSummary(out.updatedEntry) };
+        } else if (out.error) {
+          rval = { error: out.error };
+        } else {
+          rval = { error: "Cannot happen - neither user nor error set" };
+        }
+      } else if (cmd.removeWebAuthnRegistration) {
+        const modified: WardenEntry = await this.removeSingleWebAuthnRegistration(
+          cmd.removeWebAuthnRegistration.userId,
+          cmd.removeWebAuthnRegistration.credentialId
+        );
+        rval = {
+          removeWebAuthnRegistration: WardenUtils.stripWardenEntryToSummary(modified)
+        };
+      } else if (cmd.removeWebAuthnRegistrationFromLoggedInUser) {
+        const modified: WardenEntry = await this.removeSingleWebAuthnRegistration(
+          loggedInUserId,
+          cmd.removeWebAuthnRegistrationFromLoggedInUser
+        );
+        rval = {
+          removeWebAuthnRegistrationFromLoggedInUser: WardenUtils.stripWardenEntryToSummary(modified)
+        };
+      } else if (cmd.removeContactFromLoggedInUser) {
+        const output: WardenEntry = await this.removeContactMethodFromUser(loggedInUserId, cmd.removeContactFromLoggedInUser);
+        // wardencontact
+        rval = {
+          removeContactFromLoggedInUser: WardenUtils.stripWardenEntryToSummary(output)
+        };
+        // return WardenEntrySummary
+      } else if (cmd.performLogin) {
+        const loginData: WardenLoginRequest = cmd.performLogin;
+        const user: WardenEntry = await this.processLogin(loginData, origin);
+        if (user) {
+          const decoration: WardenUserDecoration<any> = await this.opts.userDecorationProvider.fetchDecoration(user);
+          const wardenToken: WardenJwtToken<any> = {
+            wardenData: WardenUtils.stripWardenEntryToSummary(user),
+            user: decoration.userTokenData,
+            proxy: decoration.proxyUserTokenData,
+            globalRoleIds: decoration.globalRoleIds,
+            teamRoleMappings: decoration.teamRoleMappings
+          };
+          const jwtToken: string = await this.opts.jwtRatchet.createTokenString(wardenToken, decoration.userTokenExpirationSeconds);
+          const output: WardenLoginResults = {
+            request: loginData,
+            userId: user.userId,
+            jwtToken: jwtToken
+          };
+          rval = { performLogin: output };
+        } else {
+          rval = { error: "Login failed" };
+        }
+      } else if (cmd.refreshJwtToken) {
+        const parsed: WardenJwtToken<any> = await this.opts.jwtRatchet.decodeToken(cmd.refreshJwtToken, ExpiredJwtHandling.THROW_EXCEPTION);
+        const user: WardenEntry = await this.opts.storageProvider.findEntryById(parsed.wardenData.userId);
+        const decoration: WardenUserDecoration<any> = await this.opts.userDecorationProvider.fetchDecoration(user);
+        const wardenToken: WardenJwtToken<any> = {
+          wardenData: WardenUtils.stripWardenEntryToSummary(user),
+          user: decoration.userTokenData,
+          proxy: decoration.proxyUserTokenData,
+          globalRoleIds: decoration.globalRoleIds,
+          teamRoleMappings: decoration.teamRoleMappings
+        };
+
+        const newToken: string = await this.opts.jwtRatchet.createTokenString(wardenToken, decoration.userTokenExpirationSeconds);
+        // CAW : We do not use refresh token because we want any user changes to show up in the new token
+        //const newToken: string = await this.opts.jwtRatchet.refreshJWTString(cmd.refreshJwtToken, false, expirationSeconds);
+        rval = {
+          refreshJwtToken: newToken
+        };
+      } else if (cmd.exportWebAuthnRegistrationEntryForLoggedInUser) {
+        rval = {
+          exportWebAuthnRegistrationEntryForLoggedInUser: await this.exportWebAuthnRegistrationEntry(cmd.exportWebAuthnRegistrationEntryForLoggedInUser, loggedInUserId)
+        };
+      } else if (cmd.importWebAuthnRegistrationEntryForLoggedInUser) {
+        rval = {
+          importWebAuthnRegistrationEntryForLoggedInUser: await this.importWebAuthnRegistrationEntry(cmd.importWebAuthnRegistrationEntryForLoggedInUser, loggedInUserId)
+        };
+      }
+    } else {
+      rval = { error: "No command sent" };
+    }
+    return rval;
+  }
+
+  public async exportWebAuthnRegistrationEntry(origin: string, userId: string): Promise<string> {
+    const ent: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+    let rval: string = null;
+    if (ent) {
+      const webAuth: WardenWebAuthnEntry = ent.webAuthnAuthenticators.find(w => w.origin === origin);
+      if (webAuth) {
+        const oUrl: URL = new URL(origin);
+        const rpId: string = oUrl.hostname;
+        Logger.debug('Finding challenge for origin %s  / RPID %s', origin, rpId);
+        const expectedChallenge: string = await this.opts.storageProvider.fetchCurrentUserChallenge(userId, rpId);
+        const token: WardenWebAuthnExportToken = {
+          entry: webAuth,
+          challenge: expectedChallenge
+        };
+
+        const s1: string = JSON.stringify(token);
+        rval = Base64Ratchet.encodeStringToBase64String(s1);
+      } else {
+        Logger.warn("Could not export webauthn - no such origin");
+      }
+    } else {
+      Logger.warn("Could not export webauthn - no such user id");
+    }
+
+    return rval;
+  }
+
+  public async importWebAuthnRegistrationEntry(token: string, userId: string): Promise<boolean> {
+    const ent: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+    let rval: boolean = false;
+    if (ent) {
+      const s1: string = Base64Ratchet.base64StringToString(token);
+      const newEntry: WardenWebAuthnExportToken = JSON.parse(s1);
+      const old: WardenWebAuthnEntry = ent.webAuthnAuthenticators.find(w => w.origin === newEntry.entry.origin);
+      if (old) {
+        Logger.warn("Removing existing entry %j", old);
+        ent.webAuthnAuthenticators = ent.webAuthnAuthenticators.filter(w => w.origin !== newEntry.entry.origin);
+      }
+      ent.webAuthnAuthenticators.push(newEntry.entry);
+      await this.opts.storageProvider.saveEntry(ent);
+      if (newEntry.challenge) {
+        await this.opts.storageProvider.updateUserChallenge(userId, newEntry.entry.origin, newEntry.challenge);
+      }
+      Logger.info("Wrote ok");
+      rval = true;
+    } else {
+      Logger.warn("Could not export webauthn - no such user id");
+    }
+    return rval;
+  }
+
+  public urlIsOnAllowedOrigin(url: string): boolean {
+    let rval: boolean = false;
+    if (url) {
+      const u: URL = new URL(url);
+      for (let i = 0; i < this.opts.allowedOrigins.length && !rval; i++) {
+        const test: URL = new URL(this.opts.allowedOrigins[i]);
+        rval = test.origin === u.origin && test.protocol === u.protocol && test.port === u.port;
+      }
+    }
+    return rval;
+  }
+
+  public singleUseCodeProvider(
+    contact: WardenContact,
+    requireMagicLinkSupport: boolean,
+    returnNullIfNoProviders?: boolean
+  ): WardenSingleUseCodeProvider {
+    const rval: WardenSingleUseCodeProvider = this.opts.singleUseCodeProviders.find(
+      (s) => s.handlesContactType(contact.type) && (!requireMagicLinkSupport || s.createCodeAndSendMagicLink)
+    );
+    if (!rval && !returnNullIfNoProviders) {
+      throw ErrorRatchet.fErr("Cannot find a single use code provider for contact type : %s", contact.type);
+    }
+    return rval;
+  }
+
+  public async sendMagicLink(
+    contact: WardenContact,
+    overrideDestinationContact: WardenContact,
+    relyingPartyName: string,
+    landingUrl: string,
+    metaIn?: Record<string, string>,
+    ttlSeconds?: number,
+    customTemplate?: WardenCustomTemplateDescriptor
+  ): Promise<boolean> {
+    let rval: boolean = false;
+    RequireRatchet.notNullOrUndefined(contact, "contact");
+    RequireRatchet.notNullUndefinedOrOnlyWhitespaceString(landingUrl, "landingUrl");
+    RequireRatchet.true(this.urlIsOnAllowedOrigin(landingUrl), "landingUrl is not on an allowed origin for redirect");
+
+    if (contact?.type && StringRatchet.trimToNull(contact?.value)) {
+      const prov: WardenSingleUseCodeProvider = this.singleUseCodeProvider(contact, true);
+      rval = await prov.createCodeAndSendMagicLink(
+        contact,
+        relyingPartyName,
+        landingUrl,
+        metaIn,
+        ttlSeconds,
+        overrideDestinationContact,
+        customTemplate
+      );
+    } else {
+      ErrorRatchet.throwFormattedErr("Cannot send - invalid contact %j", contact);
+    }
+    return rval;
+  }
+
+  public async createAccountByThirdParty(thirdParty: WardenThirdPartyAuthentication, origin: string, inLabel?: string): Promise<WardenEntry> {
+    let rval: WardenEntry = null;
+    RequireRatchet.notNullOrUndefined(thirdParty, "thirdParty");
+    RequireRatchet.notNullUndefinedOrOnlyWhitespaceString(thirdParty.thirdParty, "thirdParty");
+    RequireRatchet.notNullUndefinedOrOnlyWhitespaceString(thirdParty.thirdPartyId, "thirdPartyId");
+
+    const old: WardenEntry = await this.opts.storageProvider.findEntryByThirdPartyId(thirdParty.thirdParty, thirdParty.thirdPartyId);
+    if (old) {
+      ErrorRatchet.throwFormattedErr("Cannot create - account already exists for %j", thirdParty);
+    }
+
+    const label: string = inLabel || thirdParty.thirdParty + " " + thirdParty.thirdPartyId;
+    const newUser: WardenEntry = new WardenEntryBuilder(label).withThirdPartyAuthentication([thirdParty]).entry;
+    rval = await this.opts.storageProvider.saveEntry(newUser);
+
+    return rval;
+  }
+
+  // Creates a new account, returns the userId for that account upon success
+  public async createAccount(contact: WardenContact, origin: string, sendCode?: boolean, label?: string, tags?: string[]): Promise<WardenEntry> {
+    let rval: WardenEntry = null;
+    if (WardenUtils.validContact(contact)) {
+      const old: WardenEntry = await this.opts.storageProvider.findEntryByContact(contact);
+      if (old) {
+        ErrorRatchet.throwFormattedErr("Cannot create - account already exists for %j", contact);
+      }
+
+      // Defaults to email if nothing provided, usually full name
+      const newUser: WardenEntry = new WardenEntryBuilder(label || contact.value).withContacts([contact]).withTags(tags).entry;
+      rval = await this.opts.storageProvider.saveEntry(newUser);
+
+      if (sendCode) {
+        Logger.info("New user %j created and send requested - sending", rval);
+        await this.sendExpiringValidationToken(contact, origin);
+      }
+    } else {
+      ErrorRatchet.throwFormattedErr("Cannot create - invalid contact (missing or invalid fields)");
+    }
+    return rval;
+  }
+
+
+  public async saveNewUser(newUser: WardenEntry): Promise<WardenEntry> {
+    const next: WardenEntry = await this.opts.storageProvider.saveEntry(newUser);
+    if (this?.opts?.eventProcessor) {
+      await this.opts.eventProcessor.userCreated(next);
+    }
+    return next;
+  }
+
+  // For an existing user, add another contact method
+  // A given contact (eg, email address, phone number) can only associated with a single
+  // userId at a time
+  public async addContactMethodToUser(userId: string, contact: WardenContact): Promise<boolean> {
+    let rval: boolean = false;
+    if (StringRatchet.trimToNull(userId) && WardenUtils.validContact(contact)) {
+      const otherUser: WardenEntry = await this.opts.storageProvider.findEntryByContact(contact);
+      if (otherUser && otherUser.userId !== userId) {
+        ErrorRatchet.throwFormattedErr("Cannot add contact to this user, another user already has that contact");
+      }
+      const curUser: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+      if (!curUser) {
+        ErrorRatchet.throwFormattedErr("Cannot add contact to this user, user does not exist");
+      }
+      curUser.contactMethods.push(contact);
+      await this.opts.storageProvider.saveEntry(curUser);
+      rval = true;
+    } else {
+      ErrorRatchet.throwFormattedErr("Cannot add - invalid config : %s %j", userId, contact);
+    }
+    return rval;
+  }
+
+  // For an existing user, remove a contact method
+  public async removeContactMethodFromUser(userId: string, contact: WardenContact): Promise<WardenEntry> {
+    let rval: WardenEntry = null;
+    if (StringRatchet.trimToNull(userId) && WardenUtils.validContact(contact)) {
+      const curUser: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+      if (!curUser) {
+        ErrorRatchet.throwFormattedErr("Cannot remove contact from this user, user does not exist");
+      }
+      curUser.contactMethods = (curUser.contactMethods || []).filter((s) => s.type !== contact.type || s.value !== contact.value);
+      if (curUser.contactMethods.length === 0) {
+        ErrorRatchet.throwFormattedErr("Cannot remove the last contact method from a user");
+      }
+      await this.opts.storageProvider.saveEntry(curUser);
+      rval = await this.opts.storageProvider.findEntryById(userId);
+    } else {
+      ErrorRatchet.throwFormattedErr("Cannot add - invalid config : %s %j", userId, contact);
+    }
+    return rval;
+  }
+
+  // Used as the first step of adding a new WebAuthn device to an existing (logged in) user
+  // Server creates a challenge that the device will sign
+  public async generateWebAuthnRegistrationChallengeForLoggedInUser(
+    userId: string,
+    origin: string
+  ): Promise<PublicKeyCredentialCreationOptionsJSON> {
+    if (!origin || !this.opts.allowedOrigins.includes(origin)) {
+      throw new Error("Invalid origin : " + origin);
+    }
+    const asUrl: URL = new URL(origin);
+    const rpID: string = asUrl.hostname;
+
+    const entry: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+    if (!entry) {
+      throw ErrorRatchet.fErr("Cannot generateWebAuthnRegistrationChallengeForLoggedInUser - no user %s / %s", userId, origin);
+    }
+    if (!entry?.webAuthnAuthenticators?.length) {
+      Logger.info("Entry has no webAuthnAuthenticators");
+      entry.webAuthnAuthenticators = []; // Just in case
+    }
+    const options = await generateRegistrationOptions({
+      rpName: this.opts.relyingPartyName,
+      rpID: rpID,
+      userID: StringRatchet.stringToUint8Array(entry.userId),
+      userName: entry.userLabel,
+      // Don't prompt users for additional information about the authenticator
+      // (Recommended for smoother UX)
+      attestationType: "none",
+      // Prevent users from re-registering existing authenticators
+      excludeCredentials: entry.webAuthnAuthenticators.map((authenticator) => ({
+        id: authenticator.credentialPublicKeyBase64,
+        //type: 'public-key',
+        // Optional
+        transports: authenticator.transports as unknown as AuthenticatorTransportFuture[]
+      }))
+    });
+
+    await this.opts.storageProvider.updateUserChallenge(entry.userId, rpID, options.challenge);
+
+    return options;
+  }
+
+  // Given a new device's registration, add it to the specified user account as a valid login method
+  public async storeAuthnRegistration(
+    userId: string,
+    origin: string,
+    applicationName: string,
+    deviceLabel: string,
+    data: RegistrationResponseJSON
+  ): Promise<WardenStoreRegistrationResponse> {
+    Logger.info("Store authn data : %j", data);
+    let rval: WardenStoreRegistrationResponse = null;
+    try {
+      if (!origin || !this.opts.allowedOrigins.includes(origin)) {
+        throw new Error("Invalid origin : " + origin);
+      }
+      const asUrl: URL = new URL(origin);
+      const rpID: string = asUrl.hostname;
+
+      const user: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+      if (!user) {
+        throw ErrorRatchet.fErr("Cannot storeAuthnRegistration - no user %s / %s", userId, origin);
+      }
+
+      // (Pseudocode) Get `options.challenge` that was saved above
+      const expectedChallenge: string = await this.opts.storageProvider.fetchCurrentUserChallenge(user.userId, rpID);
+
+      const vrOpts: VerifyRegistrationResponseOpts = {
+        response: data,
+        expectedChallenge: expectedChallenge,
+        expectedOrigin: origin,
+        expectedRPID: rpID
+      };
+
+      Logger.info("Calling verifyRegistrationResponse: %j", vrOpts);
+
+      const verification: VerifiedRegistrationResponse = await verifyRegistrationResponse(vrOpts);
+      Logger.info("verifyRegistrationResponse Result : %j", verification);
+
+      rval = {
+        updatedEntry: null,
+        registrationResponseId: data.id,
+        result: verification.verified ? WardenStoreRegistrationResponseType.Verified : WardenStoreRegistrationResponseType.Failed
+      };
+
+      if (rval.result === WardenStoreRegistrationResponseType.Verified) {
+        Logger.info("Storing registration");
+        const newAuth: WardenWebAuthnEntry = {
+          origin: origin,
+          applicationName: applicationName || "Unknown Application",
+          deviceLabel: deviceLabel || "Unknown Device",
+          counter: verification.registrationInfo.credential.counter,
+          credentialBackedUp: verification.registrationInfo.credentialBackedUp,
+          credentialDeviceType: verification.registrationInfo.credentialDeviceType,
+          credentialIdBase64: verification.registrationInfo.credential.id,
+          credentialPublicKeyBase64: Base64Ratchet.uint8ArrayToBase64UrlString(verification.registrationInfo.credential.publicKey)
+          //transports: TBD
+        };
+
+        // (Pseudocode) Save the authenticator info so that we can
+        // get it by user ID later
+        user.webAuthnAuthenticators = (user.webAuthnAuthenticators || []).filter(
+          (wa) => wa.credentialIdBase64 !== newAuth.credentialIdBase64
+        );
+        user.webAuthnAuthenticators.push(newAuth);
+        const storedUser: WardenEntry = await this.opts.storageProvider.saveEntry(user);
+        rval.updatedEntry = storedUser;
+        Logger.info("Stored auth : %j", storedUser);
+      }
+    } catch (err) {
+      rval = {
+        registrationResponseId: data.id,
+        result: WardenStoreRegistrationResponseType.Error,
+        error: ErrorRatchet.safeStringifyErr(err)
+      };
+    }
+
+    return rval;
+  }
+
+  public async generateWebAuthnAuthenticationChallengeForUserId(
+    userId: string,
+    origin: string
+  ): Promise<PublicKeyCredentialRequestOptionsJSON> {
+    const user: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+    const rval: PublicKeyCredentialRequestOptionsJSON = await this.generateWebAuthnAuthenticationChallenge(user, origin);
+    return rval;
+  }
+
+  // Part of the login process - for a given user, generate the challenge that the device will have to answer
+  public async generateWebAuthnAuthenticationChallenge(user: WardenEntry, origin: string): Promise<PublicKeyCredentialRequestOptionsJSON> {
+    // (Pseudocode) Retrieve any of the user's previously-registered authenticators
+    const userAuthenticators: WardenWebAuthnEntry[] = user.webAuthnAuthenticators;
+    if (!origin || !this.opts.allowedOrigins.includes(origin)) {
+      throw new Error("Invalid origin : " + origin);
+    }
+    const asUrl: URL = new URL(origin);
+    const rpID: string = asUrl.hostname;
+
+    const out: any[] = userAuthenticators.map((authenticator) => {
+      const next: any = {
+        id: authenticator.credentialIdBase64, // Type is Base64URLString
+        //type: 'public-key',
+        // Optional
+        transports: authenticator.transports
+      };
+      return next;
+    });
+
+    const opts: GenerateAuthenticationOptionsOpts = {
+      // Require users to use a previously-registered authenticator
+      rpID: rpID,
+      allowCredentials: out,
+      userVerification: "preferred"
+    };
+
+    const options: PublicKeyCredentialRequestOptionsJSON = await generateAuthenticationOptions(opts);
+
+    // (Pseudocode) Remember this challenge for this user
+    await this.opts.storageProvider.updateUserChallenge(user.userId, rpID, options.challenge);
+
+    return options;
+  }
+
+  // Send a single use token to this contact
+  public async sendExpiringValidationToken(request: WardenContact, origin: string): Promise<boolean> {
+    let rval: boolean = false;
+    if (request?.type && StringRatchet.trimToNull(request?.value)) {
+      const prov: WardenSingleUseCodeProvider = this.singleUseCodeProvider(request, false);
+      rval = await prov.createAndSendNewCode(request, this.opts.relyingPartyName, origin);
+    } else {
+      ErrorRatchet.throwFormattedErr("Cannot send - invalid request %j", request);
+    }
+    return rval;
+  }
+
+  // Perform a login using one of several methods
+  // Delegates to functions that handle the specific methods
+  // Should return a valid WardenEntry if successful, or null if not
+  // If createUserIfMissing=true, will create a new user if one does not exist
+  public async processLogin(request: WardenLoginRequest, origin: string): Promise<WardenEntry | null> {
+    Logger.info("Processing login : %s : %j", origin, request);
+    let rval: WardenEntry = null;
+    const requestErrors: string[] = WardenUtils.loginRequestErrors(request);
+    if (requestErrors.length > 0) {
+      throw ErrorRatchet.fErr("Invalid login request : %j", requestErrors);
+    }
+    if (request.type === WardenLoginRequestType.ThirdParty) {
+      // ThirdParty is a bit different since token lookup typically gives us the info we'll use
+      // to lookup the user
+      const provider: WardenThirdPartyAuthenticationProvider = (this.options.thirdPartyAuthenticationProviders ?? [])
+        .find(s => s.handlesThirdParty(request.thirdPartyToken.thirdParty));
+      if (provider) {
+        const auth: WardenThirdPartyAuthentication = await provider.validateTokenAndReturnThirdPartyUserId(request.thirdPartyToken, origin);
+        if (auth) {
+          rval = await this.opts.storageProvider.findEntryByThirdPartyId(auth.thirdParty, auth.thirdPartyId);
+          if (!rval && request.createUserIfMissing) {
+            Logger.info("Found no existing user for %j, creating", auth);
+            let label: string = auth.thirdParty + " " + auth.thirdPartyId;
+            if (provider.extractUserLabelFromAuthentication) {
+              label = await provider.extractUserLabelFromAuthentication(auth);
+            }
+            rval = await this.createAccountByThirdParty(auth, origin, label);
+            Logger.info("Finished create, new id is %s", rval.userId);
+          }
+        } else {
+          Logger.warn("Authentication failed for %j", request.thirdPartyToken, request.createUserIfMissing);
+        }
+      } else {
+        Logger.warn("Could not find any provider to handle third party token %j", request.thirdPartyToken);
+      }
+    } else {
+      let user: WardenEntry = StringRatchet.trimToNull(request?.userId)
+        ? await this.opts.storageProvider.findEntryById(request?.userId)
+        : await this.opts.storageProvider.findEntryByContact(request.contact);
+      if (!user) {
+        Logger.info("User not found, and createUserIfMissing=%s / %j", request.createUserIfMissing, request.contact);
+        if (request.createUserIfMissing && request.contact) {
+          user = await this.createAccount(request.contact, origin);
+          Logger.info("Finished create, new id is %s", user.userId);
+        }
+        // If STILL no user...
+        if (!user) {
+          ErrorRatchet.throwFormattedErr("No user found for %j / %s", request?.contact, request?.userId);
+        }
+      }
+
+      let loginSuccess: boolean = false;
+      if (request.webAuthn) {
+        loginSuccess = await this.loginWithWebAuthnRequest(user, origin, request.webAuthn);
+      } else if (StringRatchet.trimToNull(request.expiringToken)) {
+        const prov: WardenSingleUseCodeProvider = this.singleUseCodeProvider(request.contact, false);
+        loginSuccess = await prov.checkCode(request.contact.value, request.expiringToken);
+        if (!loginSuccess) {
+          ErrorRatchet.throwFormattedErr("Cannot login - token is invalid for this user");
+        }
+      }
+      rval = loginSuccess ? user : null;
+    }
+
+    return rval;
+  }
+
+  // Perform a login using webAuthn
+  public async loginWithWebAuthnRequest(user: WardenEntry, origin: string, data: AuthenticationResponseJSON): Promise<boolean> {
+    let rval: boolean = false;
+    const asUrl: URL = new URL(origin);
+    const rpID: string = asUrl.hostname;
+    const expectedChallenge: string = await this.opts.storageProvider.fetchCurrentUserChallenge(user.userId, rpID);
+
+    // (Pseudocode} Retrieve an authenticator from the DB that
+    // should match the `id` in the returned credential
+    //const b64id: string = Base64Ratchet.base64UrlStringToString(data.id);
+    const auth: WardenWebAuthnEntry = (user.webAuthnAuthenticators || []).find((s) => s.credentialIdBase64 === data.id);
+
+    if (!auth) {
+      const allIds: string[] = (user.webAuthnAuthenticators || []).map((s) => s.credentialIdBase64);
+      throw ErrorRatchet.fErr("Could not find authenticator %s (%s) for user %s (avail were : %j)", data.id, data.id, user.userId, allIds);
+    }
+
+    const vrOpts: VerifyAuthenticationResponseOpts = {
+      response: data,
+      expectedChallenge,
+      expectedOrigin: origin,
+      expectedRPID: rpID,
+      credential: {
+        counter: auth.counter,
+        id: auth.credentialIdBase64,
+        publicKey: Base64Ratchet.base64UrlStringToBytes(auth.credentialPublicKeyBase64)
+      }
+    };
+
+    const verification: VerifiedAuthenticationResponse = await verifyAuthenticationResponse(vrOpts);
+
+    if (verification.verified) {
+      rval = true;
+    }
+    return rval;
+  }
+
+  // Unregisters a device from a given user account
+  public async removeSingleWebAuthnRegistration(userId: string, key: string): Promise<WardenEntry> {
+    let ent: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+    if (ent) {
+      ent.webAuthnAuthenticators = (ent.webAuthnAuthenticators || []).filter((s) => s.credentialIdBase64 !== key);
+      ent = await this.opts.storageProvider.saveEntry(ent);
+    } else {
+      Logger.info("Not removing - no such user as %s", userId);
+    }
+    return ent;
+  }
+
+  // Admin function - pass thru to the storage layer
+  public async removeUser(userId: string): Promise<boolean> {
+    let rval: boolean = false;
+    if (StringRatchet.trimToNull(userId)) {
+      const oldUser: WardenEntry = await this.opts.storageProvider.findEntryById(userId);
+      if (oldUser) {
+        await this.opts.storageProvider.removeEntry(userId);
+        if (this?.opts?.eventProcessor) {
+          await this.opts.eventProcessor.userRemoved(oldUser);
+        }
+        rval = true;
+      } else {
+        Logger.warn("Cannot remove non-existent user : %s", userId);
+      }
+    }
+
+    return rval;
+  }
+}