TypeScript API / @laikacms/server/oauth2 / OAuthTotpCallbacks

Interface: OAuthTotpCallbacks

OAuth-specific TOTP callbacks for simplified OAuth authentication flow.

Methods

deletePendingTotpSession()

deletePendingTotpSession(sessionId): Promise<void>;

Delete a pending TOTP session.

Required. It is called after a session is consumed AND after every failed verification: without it a single password-authenticated session accepts unlimited guesses at a six-digit code for the session's whole TTL, which a distributed attacker exhausts in well under a second.

Parameters

Parameter	Type
sessionId	string

Returns

Promise<void>

---

getLastTotpStep()?

optional getLastTotpStep(userId): Promise<number | null>;

Return the most recently consumed TOTP time step for the user, or null if none has been recorded. Together with setLastTotpStep this provides RFC 6238 §5.2 replay protection. Optional — omitting disables per-step replay protection.

Parameters

Parameter	Type
userId	string

Returns

Promise<number | null>

---

getPendingTotpSession()

getPendingTotpSession(sessionId): Promise<
  | {
  purpose: PendingTotpSessionPurpose;
  userId: string;
}
| null>;

Get a pending TOTP session. Must return the purpose it was stored with, and must not return sessions whose expiresAt has passed.

Parameters

Parameter	Type
sessionId	string

Returns

Promise< | { purpose: PendingTotpSessionPurpose; userId: string; } | null>

---

getTotpSecret()

getTotpSecret(userId): Promise<string | null>;

Get user's TOTP secret as a string for verification

Parameters

Parameter	Type
userId	string

Returns

Promise<string | null>

---

hasTotp()

hasTotp(userId): Promise<boolean>;

Check if user has TOTP enabled

Parameters

Parameter	Type
userId	string

Returns

Promise<boolean>

---

setLastTotpStep()?

optional setLastTotpStep(userId, step): Promise<void>;

Record the time step of a successfully consumed TOTP code. Optional — omit alongside getLastTotpStep.

Parameters

Parameter	Type
userId	string
step	number

Returns

Promise<void>

---

storePendingTotpSession()

storePendingTotpSession(
   sessionId, 
   userId, 
   expiresAt, 
   purpose
): Promise<void>;

Store a pending TOTP session.

purpose distinguishes the two flows that both produce a short-lived session token, and it MUST be persisted and returned verbatim by OAuthTotpCallbacks.getPendingTotpSession:

• 'login' — password verified, awaiting a TOTP code.
• 'setup' — user is enrolling a new authenticator.

Storing the two in one undifferentiated namespace is an authentication bypass: a login-stage token is visible to anyone who knows the password, and if enrollment accepts it, that password alone re-enrolls the second factor.

Parameters

Parameter	Type
sessionId	string
userId	string
expiresAt	number
purpose	PendingTotpSessionPurpose

Returns

Promise<void>

---

storeTotpSecret()

storeTotpSecret(userId, secret): Promise<void>;

Store TOTP secret for a user

Parameters

Parameter	Type
userId	string
secret	string

Returns

Promise<void>