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 } = window.arcana.auth_core;
// or
import { AuthProvider } from '@arcana/auth-core';

Initialize AuthProvider

Auth-Core SDK AuthProvider can be initialized for a UI flow that uses a pop-up modal within the current app context or redirects to a different app page after login.

const auth = await AuthProvider.init({
   appId: `${appId}`,
   flow: 'redirect', /* can be 'popup' or 'redirect' */
   redirectUri:''    /* can be ignored for redirect flow if same as login page */
});

Initiate Social Login

await auth.loginWithSocial(SocialLoginType.google);

Initiate Passwordless Login

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

PasswordlessOptions:

• { withUI: true } - the user is redirected to email-sent or error page
• { withUI: false } - the Social / Passwordless login API returns a json response back with no redirection
• defaults to { withUI: true }

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: '[email protected]',
      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: `${email}`,
}, PublickeyOutput); 

For details regarding SocialLoginType and PublickeyOutput, see Exported Enums.

Clear Login Session

await auth.logout();

TypeScript Usage

Exported Enums

enum PublicKeyOutput {
  point = 'point',
  compressed = 'compressed',
  uncompressed = 'uncompressed',
}

Regarding PublicKeyOutput:

- value can be 'point', 'compressed' or 'uncompressed'
- `point` output will be an object with `{ x: string, y: string }`
- `compressed` output will be a `string` like `0x03...`
- `uncompressed` output will be a `string` like `0x04...`
- defaults to `uncompressed`

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

Exported Types

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

interface InitParams {
  appId: string;
  network?: 'dev' | 'testnet'; /* defaults to testnet  */
  flow?: 'popup' | 'redirect'; /* defaults to redirect */
  debug?: boolean;             /* defaults to false    */
}

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

interface PasswordlessOptions {
  withUI?: boolean;
}

Flow Modes

Redirect

login.js

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

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

redirect.js

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

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

• Skip redirectUri in params if the value is the same as the login page. For example:

  index.js

  window.onload = async () => {
    const auth = await AuthProvider.init({
      appId: `${appId}`,
      flow: 'redirect',
    });
  
    if(auth.isLoggedIn()) {
      /* already logged in, get user info and use */
      const info = auth.getUserInfo();
    } else {
      /* add handler to handle login function */
      googleLoginBtn.addEventListener('click', async () => {
        await auth.loginWithSocial(SocialLoginType.google);
      });
    }
  }

Popup

login.js

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

  googleLoginBtn.addEventListener('click', async () => {
    await auth.loginWithSocial(SocialLoginType.google);
    if(auth.isLoggedIn()) {
      const info = auth.getUserInfo();
      // Store info and redirect accordingly
    }
  });
}

redirect.js

window.onload = async () => {
  AuthProvider.handleRedirectPage(<origin>);
};

Variables

• origin - Base URL of the app.

💡 Support

For any support or integration-related queries, contact the Arcana support team.

ℹ️ License

Arcana Auth SDK is distributed under the MIT License. For details see Arcana License.