Arcana Auth-Core SDK

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({
  email: 'abc@example.com'
});

On Redirect page

await auth.handleRedirect();

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 {
  /**
   * appId: arcana app id without network hint, 
   * example: for clientId `xar_dev_xyz` - `xyz` is the appId.
   */
  appId: string;
  network?: 'dev' | 'testnet'| 'mainnet'; /* defaults to testnet  */
  /**
   * autoRedirect: is redirected via SDK internally,
   * instead of `loginWithSocial` output being `{ url }`.
  */
  autoRedirect: boolean                   /* defaults to true     */
  /** 
   * shouldVerifyState: by default state is compared internally, 
   * the state is stored to local storage on login init.
   * Set to false if you want to compare it yourself.
  */
  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 outputted from
   * `auth.handleRedirect()` 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.

💡 Support

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

ℹ️ License

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