Abstract Class: BaseAuthElevationRoute<U, S, A>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:81

Issues an elevated access token (see TokenUtils.createAccessToken's elevated argument, and the @RequiresElevation decorator in @rapidrest/service-core) once the caller — who must already hold a valid, non-elevated access token — has freshly re-proven their identity. Only an elevated token carries the caller's trusted roles — a normal, non-elevated token never does — so this route is what turns a plain "I'm logged in" session into "I've recently confirmed I'm still me" for the specific request(s) that need it.

This is deliberately a lightweight, single-factor "prove you're still you" check, NOT a full re-authentication: the caller already proved their identity once to obtain their current access token (see @Auth(["jwt"]) below), so this route only asks for one additional method:

• A caller who has enrolled at least one secondary method (OTP/TOTP/FIDO2) must complete exactly one of them — GET lists the caller's own available methods, and POST both begins and completes a challenge for a selected one (mirroring BaseAuthMFARoute's phase 2/3, but scoped to the caller's own uid throughout since identity is already established via the JWT, never taken from the request body).
• A caller with no secondary method enrolled (most commonly a freshly bootstrapped default admin account, which typically only has a password) elevates by resubmitting their password instead. Without this, such an account could never satisfy @RequiresElevation-gated actions at all, since it has no second factor to prove — a permanent lockout, not a security improvement. Password resubmission is only accepted when zero secondary methods are enrolled — once a real second factor exists, it must be used, since re-supplying the same password used to obtain the current token proves nothing new.

Extended by

• BaseAuthElevationRouteMongo
• BaseAuthElevationRouteSQL

Type Parameters

U

U extends User

S

S extends Secret

A

A extends Alias

Constructors

Constructor

new BaseAuthElevationRoute<U, S, A>(): BaseAuthElevationRoute<U, S, A>

Returns

BaseAuthElevationRoute<U, S, A>

Properties

aliasClass

abstract protected aliasClass: any

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:82

---

aliasRepo?

protected optional aliasRepo?: RepoUtils<A>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:89

---

auditLogUtils?

protected optional auditLogUtils?: AuditLogUtils

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:92

---

defaultScopes

protected defaultScopes: string[] = []

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:95

---

fido2Config

protected fido2Config: PasskeyConfig

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:103

The relying party configuration to use for the FIDO2 elevation method. See BaseAuthFIDO2Route/BaseSecretRoute.fido2Config for the primary-auth/registration counterparts of this configuration.

---

logger

protected logger: any

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:110

---

messagingUtils?

protected optional messagingUtils?: MessagingUtils

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:113

---

passwordConfig

protected passwordConfig: PasswordConfig

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:116

---

rateLimiter?

protected optional rateLimiter?: RateLimiter

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:119

---

secretClass

abstract protected secretClass: any

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:83

---

secretRepo?

protected optional secretRepo?: RepoUtils<S>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:121

---

template

protected template: string = "login-otp"

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:124

The name of the messaging template to use for sending notifications.

---

tokenUtils?

protected optional tokenUtils?: TokenUtils

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:134

---

totpConfig

protected totpConfig: TOTPConfig

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:131

Only encryption_key is read here — the rest of TOTPConfig (digits/period/algorithm/etc.) is captured onto each TOTPSecret at registration time by BaseSecretRoute, not re-read on elevation.

---

trustedProxies

protected trustedProxies: string[] = []

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:137

---

userClass

abstract protected userClass: any

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:84

---

userRepo?

protected optional userRepo?: RepoUtils<U>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:139

---

userUtils?

protected optional userUtils?: UserUtils<U, A>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:141

Methods

beginChallenge()

protected beginChallenge(methodId, user, req): Promise<any>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:304

Begins a challenge for one of the caller's own elevation methods. Scoped to user.uid throughout via getMethod() — the same authorization boundary BaseAuthMFARoute relies on — so a methodId belonging to another user can never be used here.

Parameters

methodId

string

user

JWTUser

req

HttpRequest

Returns

Promise<any>

---

convertAliasToMethod()

protected convertAliasToMethod(alias, obfuscate?): MFAMethod | undefined

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:445

Parameters

alias

Alias

obfuscate?

boolean

Returns

MFAMethod | undefined

---

convertAliasToWhatsAppMethod()

protected convertAliasToWhatsAppMethod(alias, obfuscate?): MFAMethod | undefined

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:490

Converts a verified phone alias into its WhatsApp MFAMethod, delivering the code over WhatsApp instead of SMS. Its id is derived from the alias's uid (see toWhatsAppMethodId()) so it is selectable and resolvable independently of the same alias's SMS method, whose id is the plain alias uid. The caller is responsible for only using this while WhatsApp is configured (see isWhatsAppConfigured()).

Parameters

alias

Alias

The alias to convert.

obfuscate?

boolean

Set to true to obfuscate the contact, as for convertAliasToMethod().

Returns

MFAMethod | undefined

The method, or undefined if alias isn't a verified phone.

---

convertSecretToMethod()

protected convertSecretToMethod(secret): MFAMethod | undefined

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:511

Parameters

secret

S

Returns

MFAMethod | undefined

---

elevate()

elevate(obj, user, req, res): Promise<any>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:219

Re-verifies the caller's identity using exactly one additional method beyond their existing access token, and on success returns a fresh elevated access token (and refresh token) for them to use with the specific request(s) that require it. Accepts, in the request body:

• { methodId } — begins a challenge for one of the caller's own methods (from listMethods()). For FIDO2 this returns a WebAuthn assertion challenge; for OTP this sends a code to the associated contact; for TOTP this returns an empty body (the caller's authenticator app already has the current code).
• { token } (OTP/TOTP) or a WebAuthn assertion response (FIDO2) — completes the challenge begun above.
• { password } — only accepted when the caller has zero secondary methods enrolled.

Parameters

obj

any

user

JWTUser

req

HttpRequest

res

HttpResponse

Returns

Promise<any>

---

getCredentialById()

protected getCredentialById(credentialId): Promise<StoredPasskeyCredential | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:535

Retrieves a previously-registered FIDO2 credential by its ID, for verifying a FIDO2 elevation challenge response.

Parameters

credentialId

string

The unique id of the FIDO2 credential to retrieve.

Returns

Promise<StoredPasskeyCredential | undefined>

---

getMethod()

protected getMethod(id, userUid): Promise<MFAMethod | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:559

Retrieves the user's elevation method for a given id. Only returns a method that actually belongs to uid — this is what stops one user's elevation challenge from being triggered/consumed using another user's authentication method.

Parameters

id

string

The unique id of the elevation method to retrieve.

userUid

string

The unique id of the user the method must belong to.

Returns

Promise<MFAMethod | undefined>

---

getMethods()

protected getMethods(uid): Promise<MFAMethod[]>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:607

Retrieves the list of elevation methods for the user with the given id. This list is sent to the user and so should be obfuscated where reasonable so as to limit discovery when a password has been compromised.

Parameters

uid

string

The unique identifier of the user.

Returns

Promise<MFAMethod[]>

---

getUser()

protected getUser(uid): Promise<JWTUser | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:665

Retrieves the user with the given unique id.

Parameters

uid

string

The unique id of the user to retrieve.

Returns

Promise<JWTUser | undefined>

The user if found, otherwise undefined.

---

initialize()

protected initialize(): Promise<void>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:147

Called on server startup to initialize the route with any defaults.

Returns

Promise<void>

---

listMethods()

listMethods(user): Promise<MFAMethod[]>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:193

Returns the authenticated caller's own available secondary methods for elevating — see elevate(). An empty list means the caller has none enrolled and must elevate via password instead.

Parameters

user

JWTUser

Returns

Promise<MFAMethod[]>

---

notifyContact()

protected notifyContact(contact, totp): Promise<void>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:672

Parameters

contact

OTPContact

totp

string

Returns

Promise<void>

---

obfuscateAlias()

protected obfuscateAlias(alias, type): string

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:702

Obfuscates the given alias and returns the obfuscated value.

Parameters

alias

string

type

AliasType

Returns

string

---

updateCredentialCounter()

protected updateCredentialCounter(credentialId, newCounter): Promise<void>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:726

Persists the updated signature counter for the given FIDO2 credential after a successful elevation challenge. Called on every successful FIDO2 elevation to guard against cloned authenticators.

Parameters

credentialId

string

The unique id of the credential to update.

newCounter

number

The new signature counter value to persist.

Returns

Promise<void>

---

updateSecretTimeStep()

protected updateSecretTimeStep(uid, timeStep): Promise<void>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:764

Persists the given time step as the last one successfully used for the identified TOTP secret, so a captured/replayed token can't be reused within its validity window.

Closes a TOCTOU race between two concurrent elevation requests both holding the same valid code: each independently verifies the submitted token before either one reaches this method, so verification alone can't tell them apart. Re-checking lastTimeStep against a fresh read here - combined with RepoUtils.update()'s existing optimistic-locking version check, which still protects the case where both readers see the same pre-update state - means at most one of the two ever succeeds in claiming this time step; the loser throws instead of silently letting a second session elevate on an already-used code.

Parameters

uid

string

The unique id of the stored secret that was verified.

timeStep

number

The RFC 6238 time step at which the token was verified.

Returns

Promise<void>

---

verify()

protected verify(name, password): Promise<JWTUser | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:792

Parameters

name

string

password

string

Returns

Promise<JWTUser | undefined>

---

verifyFIDOChallenge()

protected verifyFIDOChallenge(payload, req): Promise<JWTUser | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:388

Parameters

payload

any

req

HttpRequest

Returns

Promise<JWTUser | undefined>

---

verifyOTPChallenge()

protected verifyOTPChallenge(payload, req): Promise<JWTUser | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:344

Parameters

payload

any

req

HttpRequest

Returns

Promise<JWTUser | undefined>

---

verifyPasswordOnly()

protected verifyPasswordOnly(user, password): Promise<JWTUser | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:428

Verifies the caller's password as their sole proof of elevation. Only valid when the caller has no secondary method enrolled — once a real second factor exists it must be used instead, since resubmitting the same password used to obtain the current access token proves nothing new.

Parameters

user

JWTUser

password

string

Returns

Promise<JWTUser | undefined>

---

verifyTOTPChallenge()

protected verifyTOTPChallenge(payload, req): Promise<JWTUser | undefined>

Defined in: auth/src/routes/BaseAuthElevationRoute.ts:361

Parameters

payload

any

req

HttpRequest

Returns

Promise<JWTUser | undefined>