0
# Authentication
1

2
OAuth-based authentication system supporting multiple providers (Google, Facebook, Discord, etc.) with session management and user profile access.
3

4
## Capabilities
5

6
### User Login
7

8
Authenticate users through OAuth providers and return their Ethereum accounts.
9

10
```typescript { .api }
11
/**
12
 * Initiate user login process through OAuth providers
13
 * @param params - Optional login parameters including verifier and login hint
14
 * @returns Promise resolving to array of user's Ethereum account addresses
15
 * @throws Error if widget not initialized
16
 */
17
login(params?: TorusLoginParams): Promise<string[]>;
18

19
interface TorusLoginParams {
20
  /** OAuth verifier to use for login */
21
  verifier?: string;
22
  /** Login hint (email or username) to pre-fill login form */
23
  login_hint?: string;
24
}
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
// Basic login with default providers
31
const accounts = await torus.login();
32
console.log("User accounts:", accounts);
33

34
// Login with specific verifier
35
const googleAccounts = await torus.login({ 
36
  verifier: "google" 
37
});
38

39
// Login with email hint
40
const accounts = await torus.login({ 
41
  verifier: "google",
42
  login_hint: "user@example.com"
43
});
44
```
45

46
### User Logout
47

48
Log out the current user and clear authentication state.
49

50
```typescript { .api }
51
/**
52
 * Log out the current user and clear authentication state
53
 * @returns Promise that resolves when logout is complete
54
 * @throws Error if user not logged in
55
 */
56
logout(): Promise<void>;
57
```
58

59
**Usage Example:**
60

61
```typescript
62
try {
63
  await torus.logout();
64
  console.log("User logged out successfully");
65
} catch (error) {
66
  console.error("Logout failed:", error.message);
67
}
68
```
69

70
### User Information
71

72
Retrieve detailed user profile information.
73

74
```typescript { .api }
75
/**
76
 * Request user profile information with custom message
77
 * May prompt user for permission
78
 * @param message - Custom message to display in permission request
79
 * @returns Promise resolving to user profile information
80
 */
81
getUserInfo(message: string): Promise<UserInfo>;
82

83
interface UserInfo {
84
  /** User's email address */
85
  email: string;
86
  /** User's full name */
87
  name: string;
88
  /** User's profile image URL */
89
  profileImage: string;
90
  /** OAuth verifier used (google, facebook, etc.) */
91
  verifier: string;
92
  /** Verifier-specific user ID */
93
  verifierId: string;
94
  /** Whether this is a new user */
95
  isNewUser: boolean;
96
  /** Type of login used */
97
  typeOfLogin: LOGIN_TYPE;
98
}
99
```
100

101
**Usage Example:**
102

103
```typescript
104
try {
105
  const userInfo = await torus.getUserInfo("Please allow access to your profile");
106
  console.log("User info:", {
107
    name: userInfo.name,
108
    email: userInfo.email,
109
    provider: userInfo.verifier,
110
    isNew: userInfo.isNewUser
111
  });
112
} catch (error) {
113
  console.error("Failed to get user info:", error);
114
}
115
```
116

117
### Private Key Login
118

119
Authenticate using a private key with associated user information.
120

121
```typescript { .api }
122
/**
123
 * Login using a private key and user information
124
 * Private key must be 32-byte secp256k1 key
125
 * @param loginParams - Private key and user information
126
 * @returns Promise resolving to success status
127
 */
128
loginWithPrivateKey(loginParams: {
129
  privateKey: string;
130
  userInfo: Omit<UserInfo, "isNewUser">;
131
}): Promise<boolean>;
132
```
133

134
**Usage Example:**
135

136
```typescript
137
const success = await torus.loginWithPrivateKey({
138
  privateKey: "0x1234567890abcdef...", // 32-byte hex string
139
  userInfo: {
140
    email: "user@example.com",
141
    name: "John Doe",
142
    profileImage: "https://example.com/avatar.jpg",
143
    verifier: "custom",
144
    verifierId: "custom-user-id",
145
    typeOfLogin: "jwt"
146
  }
147
});
148

149
if (success) {
150
  console.log("Private key login successful");
151
}
152
```
153

154
### Authentication State
155

156
Access current authentication status.
157

158
```typescript { .api }
159
/** Whether user is currently logged in */
160
readonly isLoggedIn: boolean;
161

162
/** Current verifier being used */
163
readonly currentVerifier: string;
164

165
/** Requested verifier for login */
166
readonly requestedVerifier: string;
167
```
168

169
**Usage Example:**
170

171
```typescript
172
if (torus.isLoggedIn) {
173
  console.log("User is logged in with:", torus.currentVerifier);
174
} else {
175
  console.log("User not logged in");
176
}
177
```
178

179
### Login Configuration
180

181
Configure OAuth providers and customize login options.
182

183
```typescript { .api }
184
interface LoginConfig {
185
  /** OAuth provider configurations */
186
  [verifier: string]: LoginConfigItem;
187
}
188

189
interface LoginConfigItem {
190
  /** Display name for the login option */
191
  name: string;
192
  /** Type of OAuth provider */
193
  typeOfLogin: LOGIN_TYPE;
194
  /** Description for login button */
195
  description?: string;
196
  /** Custom OAuth client ID */
197
  clientId?: string;
198
  /** Logo URL for hover state */
199
  logoHover?: string;
200
  /** Logo URL for light theme */
201
  logoLight?: string;
202
  /** Logo URL for dark theme */
203
  logoDark?: string;
204
  /** Show login button in modal */
205
  showOnModal?: boolean;
206
  /** Show login button on mobile */
207
  showOnMobile?: boolean;
208
  /** JWT parameters for Auth0 integration */
209
  jwtParameters?: JwtParameters;
210
  /** Show as main login option */
211
  mainOption?: boolean;
212
  /** Show login button on desktop */
213
  showOnDesktop?: boolean;
214
  /** Button display priority (1 = highest) */
215
  priority?: number;
216
}
217

218
interface JwtParameters extends BaseLoginOptions {
219
  /** Auth0 domain */
220
  domain: string;
221
  /** OAuth client ID */
222
  client_id?: string;
223
  /** Callback URL */
224
  redirect_uri?: string;
225
  /** Clock skew allowance in seconds */
226
  leeway?: number;
227
  /** JWT field mapping to verifier ID */
228
  verifierIdField?: string;
229
  /** Whether verifier ID field is case sensitive */
230
  isVerifierIdCaseSensitive?: boolean;
231
}
232

233
interface BaseLoginOptions {
234
  /** Additional OAuth parameters */
235
  [key: string]: unknown;
236
  /** UI display mode */
237
  display?: "page" | "popup" | "touch" | "wap";
238
  /** Authentication prompt behavior */
239
  prompt?: "none" | "login" | "consent" | "select_account";
240
  /** Maximum authentication age in seconds */
241
  max_age?: string | number;
242
  /** Language preferences */
243
  ui_locales?: string;
244
  /** Previously issued ID token */
245
  id_token_hint?: string;
246
  /** Login hint (email/username) */
247
  login_hint?: string;
248
  /** ACR values */
249
  acr_values?: string;
250
  /** OAuth scope */
251
  scope?: string;
252
  /** OAuth audience */
253
  audience?: string;
254
  /** OAuth connection */
255
  connection?: string;
256
}
257
```
258

259
### Supported OAuth Providers
260

261
```typescript { .api }
262
type LOGIN_TYPE = 
263
  | "google"         // Google OAuth
264
  | "facebook"       // Facebook OAuth  
265
  | "reddit"         // Reddit OAuth
266
  | "discord"        // Discord OAuth
267
  | "twitch"         // Twitch OAuth
268
  | "apple"          // Apple Sign In
269
  | "github"         // GitHub OAuth
270
  | "linkedin"       // LinkedIn OAuth
271
  | "twitter"        // Twitter OAuth
272
  | "weibo"          // Weibo OAuth
273
  | "line"           // LINE OAuth
274
  | "jwt"            // Custom JWT
275
  | "email_password" // Email/password
276
  | "passwordless"   // Passwordless email
277
  | "wechat"         // WeChat OAuth
278
  | "kakao";         // Kakao OAuth
279

280
// Predefined verifier identifiers
281
const WALLET_VERIFIERS = {
282
  GOOGLE: "google",
283
  FACEBOOK: "facebook", 
284
  TWITCH: "twitch",
285
  REDDIT: "reddit",
286
  DISCORD: "discord",
287
  EMAIL_PASSWORDLESS: "torus-auth0-email-passwordless"
288
} as const;
289
```
290

291
**Usage Example for Custom Login Config:**
292

293
```typescript
294
await torus.init({
295
  loginConfig: {
296
    "custom-google": {
297
      name: "Custom Google",
298
      typeOfLogin: "google",
299
      description: "Login with your Google account",
300
      clientId: "your-google-client-id",
301
      logoLight: "https://example.com/google-logo.png",
302
      showOnModal: true,
303
      mainOption: true,
304
      priority: 1
305
    },
306
    "custom-auth0": {
307
      name: "Enterprise Login",
308
      typeOfLogin: "jwt",
309
      description: "Login with enterprise account",
310
      jwtParameters: {
311
        domain: "your-company.auth0.com",
312
        client_id: "your-auth0-client-id",
313
        verifierIdField: "email",
314
        isVerifierIdCaseSensitive: false
315
      },
316
      showOnModal: true,
317
      priority: 2
318
    }
319
  }
320
});
321
```