Skip to content

Auth-Core SDK

Auth-Core SDK enables basic functionality for onboarding users to Web3 apps via social login. It uses the Arcana Keystore APIs to interact with the distributed key generation subsystem in the Arcana Network.

The Arcana Auth product is built using the Auth-Core SDK and the Arcana wallet UI. It ensures that only authenticated users have access to the private keys for signing blockchain transactions. With Arcana Auth, the app developers cannot access the user's private keys.

Web3 apps that choose to integrate directly with the Auth-Core SDK instead of using Arcana Auth must implement some of the functionality related to handling user authentication via social login. In addition, developers must ensure the security and privacy of the user's keys. See the Usage section below for details.

Note that the 'Global Keys' and enhanced wallet security 'MFA' features available via Arcana Auth are not available through the Auth-Core SDK.

Installation

npm

npm install --save @arcana/auth-core

yarn

yarn add @arcana/auth-core

CDN

<script src="https://cdn.jsdelivr.net/npm/@arcana/auth-core"></script>
<script src="https://unpkg.com/@arcana/auth-core"></script>

Usage

Import

const { AuthProvider, SocialLoginType, CURVE } = window.arcana.auth_core;
// or
import { AuthProvider, CURVE } from '@arcana/auth-core';

Initialize AuthProvider

const auth = new AuthProvider({
   curve: CURVE.ED25519, // defaults to CURVE.SECP256K1
   appId: `${appId}`,
   redirectUri: ''    
});

Initiate Social Login

await auth.loginWithSocial(SocialLoginType.google);

Initiate Passwordless Login

const result = await auth.loginWithPasswordlessStart(`${emailAddress}`, PasswordlessOptions);

Get Login Status

const loggedIn = auth.isLoggedIn(); /* boolean response */

Get User Info

After successful login, the user information is saved in memory. Before the page unload event, the user information gets stored in session-storage. After a successful page reload, it is fetched again to memory and removed from the session-storage.

const userInfo = auth.getUserInfo();
/* 
  UserInfo: {
    loginType: 'google',
    userInfo: {
      id: 'abc@example.com',
      name: 'ABC DEF',
      email: '',
      picture: ''
    },
    privateKey: ''
  }
*/

For userInfo type details, see Exported Types.

Get Public Key

const publicKey = await auth.getPublicKey({
  verifier: SocialLoginType.google,
  id: `abc@example.com`,
}); 

For details regarding SocialLoginType, see Exported Enums.

Clear Login Session

await auth.logout();

TypeScript Usage

Exported Enums

enum SocialLoginType {
  google = 'google',
  discord = 'discord',
  twitch = 'twitch',
  github = 'github',
  twitter = 'twitter',
  passwordless = 'passwordless',
}

Exported Types

interface KeystoreInput {
  id: string;
  verifier: LoginType;
}

interface InitParams {
  // arcana app id with network hint, ex xar_dev_xyz - xyz is the appId
  appId: string;
  network?: 'dev' | 'testnet'| 'mainnet'; /* defaults to testnet  */
  /**
   * autoRedirect: is redirected via SDK, instead of `loginWithSocial`
   * output being `{ url }`
  */
  autoRedirect: boolean                   /* defaults to true     */
  /** 
   * shouldVerifyState: state is compared internally, the state is stored
   * to local storage on login init
  */
  shouldVerifyState: boolean              /* defaults to true     */ 
  /**
   * revokeTokenPostLogin: Some tokens need to be revoked to get new tokens
   * on subsequent login or to prevent misuse, SDK does this internally. If
   * set to `false` there is a cleanup function that is output of the func
   * `auth.handleRedirectMode()` which should be called after token is used 
   * for secondary purpose
   */
  revokeTokenPostLogin: boolean           /* defaults to true     */
  debug?: boolean;                        /* defaults to false    */
}

interface GetInfoOutput {
  loginType: SocialLoginType;
  userInfo: UserInfo {
    id: string;
    email?: string;
    name?: string;
    picture?: string;
  };
  privateKey: string;
}

Flow Modes

Redirect

login.js

window.onload = async () => {
  const auth = new AuthProvider({
    appId: `${appId}`,
    redirectUri:'path/to/redirect' 
  });

  googleLoginBtn.addEventListener('click', async () => {
    await auth.loginWithSocial(SocialLoginType.google);
  });
}

redirect.js

window.onload = async () => {
  const auth = new AuthProvider({
    appId: `${appId}`,
    redirectUri:'path/to/redirect' 
  });

  await auth.handleRedirect();

  if(auth.isLoggedIn()) {
    const info = auth.getUserInfo();
  }
}

Variables

  • origin - Base URL of the app.

Last update: November 15, 2023 by shaloo, shalz