WEB SDK Auth

The auth module provides a minimal login state machine plus in-memory token handling. The concrete MFA completion method in the source is completeLogin(...); conceptually this is the MFA completion step that exchanges the challenge for a TokenPair and stores it in TokenManager.

Login Flow State Machine

State	Entered When	Left When
unauthenticated	Initial state, logout, refresh failure, or login completion failure.	initiateLogin() succeeds.
mfa_pending	initiateLogin() returns an MfaChallenge.	completeLogin() succeeds or fails.
authenticated	completeLogin() or refreshToken() succeeds.	logout() or refresh failure clears tokens.

AuthClient

Constructor	Description
new AuthClient(config: AuthClientConfig)	Requires baseUrl, portalAccessCode, and a shared TokenManager.

Step 1: Initiate Login

initiateLogin(username, password) posts credentials to /login/initiate, stores the challenge internally, sets state to mfa_pending, and returns the challenge payload.

import {
  AuthClient,
  MfaMethod,
  TokenManager,
} from '@slaunchx/web-sdk';

const tokenManager = new TokenManager();

const auth = new AuthClient({
  baseUrl: 'https://api.example.com',
  portalAccessCode: 'portal-web',
  tokenManager,
});

const challenge = await auth.initiateLogin('alice@example.com', 'password');
const method: MfaMethod = challenge.methods[0];

Step 2: Complete MFA

The SDK does not expose a separate completeMfa() method. The second step is completeLogin(sessionId, method, code), which posts the MFA code to /login/complete, receives a TokenPair, stores it through TokenManager, clears MFA state, and transitions to authenticated.

await auth.completeLogin(challenge.sessionId, method, '123456');

console.log(auth.getState()); // authenticated
console.log(tokenManager.getAccessToken()); // bearer token

Refresh And Logout

refreshToken() posts the stored refresh token to /auth/refresh. logout() performs a best-effort /auth/logout call if an access token exists, then clears local auth state.

if (tokenManager.isExpired()) {
  await auth.refreshToken();
}

await auth.logout();

TokenManager

TokenManager is intentionally in-memory only. It does not use localStorage, which keeps the default SDK behavior aligned with XSS-sensitive browser flows.

Responsibility	Details
Storage	Stores accessToken, refreshToken, and calculated expiry time in memory.
Expiry checks	isExpired() returns true when no access token exists or the current time is beyond expiresAt.
Clearing	clear() removes all token state.
Refresh integration	Automatic refresh is performed by AuthClient.refreshToken() or SlaunchxFetch + RetryPolicy, using values from TokenManager.

tokenManager.setTokens({
  accessToken: 'access',
  refreshToken: 'refresh',
  expiresIn: 900,
});

console.log(tokenManager.getAccessToken());
console.log(tokenManager.isExpired());

MfaHandler

AuthClient uses an internal MfaHandler, but the class is also exported for apps that want to manage MFA state outside AuthClient.

Method	Use
setChallenge(challenge)	Store the current MFA challenge.
getAvailableMethods()	Return allowed MfaMethod[].
getSessionId()	Return the MFA challenge session id.
isExpired()	Check the challenge expiry timestamp.
prepareVerification(method, code)	Build { sessionId, method, code } if the method is valid.
clear()	Reset challenge state.

import { MfaHandler } from '@slaunchx/web-sdk';

const handler = new MfaHandler();
handler.setChallenge(challenge);

const verification = handler.prepareVerification(method, '123456');
if (!verification || handler.isExpired()) {
  throw new Error('MFA challenge is no longer valid');
}

await auth.completeLogin(
  verification.sessionId,
  verification.method,
  verification.code,
);

Types Used In Auth

Type	Shape
AuthState	`'unauthenticated'
MfaMethod	`'EMAIL'
MfaChallenge	{ sessionId, methods, expiresAt }
TokenPair	{ accessToken, refreshToken, expiresIn }
LoginResult	Same fields as TokenPair; exported as a semantic alias for login outcomes.