Usage

---

triggerLogin

triggerLogin performs the following actions:

• Opens the login window of the auth provider as a popup
• Listens on the redirected url
• Returns the verifier scoped public private key pair + user info

If your verifier is of normal type, use this method. If you wish to have account linking / multiple verifiers returning same keys (e.g.: passwordless and google logins returning the same key), use triggerAggregateLogin instead.

await torusdirectsdk.triggerLogin(options);

Parameters

options is an object of type SubVerifierDetails with the following parameters

• params - SubVerifierDetails : The login options.

  • typeOfLogin - LOGIN_TYPE : The type of login. Supported Login Types include google | facebook | reddit | discord | twitch | apple | github | linkedin | twitter | weibo | line | email_password | jwt. For passwordless and other types of custom logins use jwt

  • verifier - string: A verifier is a unique identifier for your OAuth registration on the torus network. The public/private keys generated for a user are scoped to a verifier. Register your app here to get your verifier today.

  • clientId: string: clientId obtained from OAuth registration For native logins, please use the one from OAuth registration. For proxy logins, please use the clientId obtained from proxy provider

  • jwtParams? : Auth0ClientOptions(optional): Details below

  • hash?: string(optional): The location hash returned from OAuth login. Useful in case the OAuth redirects to app with hash & query params

  • queryParameters?: TorusGenericObject(optional): Key value pairs of query parameters returned from OAuth login. Useful in case the OAuth redirects to app with hash & query params

  • customState?: TorusGenericObject(optional): Custom OAuth state parameter. Useful for state management post redirect flow.

info

In some cases (electron apps, chrome extensions), your app will be redirected to the redirect url with hash and query params from OAuth provider. To get torus key in such cases, please pass along those parameters into the sdk. Passing these will skip the login and return the torus result directly.

Returns

• Promise<TorusLoginResponse> : Returns a promise which resolves to the TorusLoginResponse object

Reference

export interface SubVerifierDetails {
  typeOfLogin: LOGIN_TYPE;
  verifier: string;
  clientId: string;
  jwtParams?: Auth0ClientOptions;
  hash?: string;
  queryParameters?: TorusGenericObject;
  customState?: TorusGenericObject;
}

export const LOGIN = {
  GOOGLE: "google",
  FACEBOOK: "facebook",
  REDDIT: "reddit",
  DISCORD: "discord",
  TWITCH: "twitch",
  APPLE: "apple",
  GITHUB: "github",
  LINKEDIN: "linkedin",
  TWITTER: "twitter",
  WEIBO: "weibo",
  LINE: "line",
  EMAIL_PASSWORD: "email_password",
  PASSWORDLESS: "passwordless",
  JWT: "jwt",
  WEBAUTHN: "webauthn",
} as const;
export type LOGIN_TYPE = typeof LOGIN[keyof typeof LOGIN];

// REGION: AUTH0 PARAMS
export interface BaseLoginOptions {
  /**
   * - `'page'`: displays the UI with a full page view
   * - `'popup'`: displays the UI with a popup window
   * - `'touch'`: displays the UI in a way that leverages a touch interface
   * - `'wap'`: displays the UI with a "feature phone" type interface
   */
  display?: "page" | "popup" | "touch" | "wap" | string;
  /**
   * - `'none'`: do not prompt user for login or consent on reauthentication
   * - `'login'`: prompt user for reauthentication
   * - `'consent'`: prompt user for consent before processing request
   * - `'select_account'`: prompt user to select an account
   */
  prompt?: "none" | "login" | "consent" | "select_account" | string;
  /**
   * Maximum allowable elasped time (in seconds) since authentication.
   * If the last time the user authenticated is greater than this value,
   * the user must be reauthenticated.
   */
  max_age?: string | number;
  /**
   * The space-separated list of language tags, ordered by preference.
   * For example: `'fr-CA fr en'`.
   */
  ui_locales?: string;
  /**
   * Previously issued ID Token.
   */
  id_token_hint?: string;
  /**
   * The user's email address or other identifier. When your app knows
   * which user is trying to authenticate, you can provide this parameter
   * to pre-fill the email box or select the right session for sign-in.
   *
   * This currently only affects the classic Lock experience.
   */
  login_hint?: string;
  acr_values?: string;
  /**
   * The default scope to be used on authentication requests.
   * The defaultScope defined in the Auth0Client is included
   * along with this scope
   */
  scope?: string;
  /**
   * The default audience to be used for requesting API access.
   */
  audience?: string;
  /**
   * The name of the connection configured for your application.
   * If null, it will redirect to the Auth0 Login Page and show
   * the Login Widget.
   */
  connection?: string;

  /**
   * If you need to send custom parameters to the Authorization Server,
   * make sure to use the original parameter name.
   */
  [key: string]: unknown;
}

export interface Auth0ClientOptions extends BaseLoginOptions {
  /**
   * Your Auth0 account domain such as `'example.auth0.com'`,
   * `'example.eu.auth0.com'` or , `'example.mycompany.com'`
   * (when using [custom domains](https://auth0.com/docs/custom-domains))
   */
  domain: string;
  /**
   * The Client ID found on your Application settings page
   */
  client_id?: string;
  /**
   * The default URL where Auth0 will redirect your browser to with
   * the authentication result. It must be whitelisted in
   * the "Allowed Callback URLs" field in your Auth0 Application's
   * settings. If not provided here, it should be provided in the other
   * methods that provide authentication.
   */
  redirect_uri?: string;
  /**
   * The value in seconds used to account for clock skew in JWT expirations.
   * Typically, this value is no more than a minute or two at maximum.
   * Defaults to 60s.
   */
  leeway?: number;

  /**
   * The field in jwt token which maps to verifier id
   */
  verifierIdField?: string;

  /**
   * Whether the verifier id field is case sensitive
   * @default true
   */
  isVerifierIdCaseSensitive?: boolean;
}

export type TorusGenericObject = {
  [key: string]: string;
};

export type TorusLoginResponse = TorusSingleVerifierResponse & TorusKey;

export interface TorusSingleVerifierResponse {
  userInfo: TorusVerifierResponse & LoginWindowResponse;
}

export interface TorusKeyPub {
  pubKey?: {
    pub_key_X: string;
    pub_key_Y: string;
  };
}

export interface TorusKey extends TorusKeyPub {
  publicAddress: string;
  privateKey: string;
  metadataNonce: string;
}

export interface TorusVerifierResponse {
  email: string;
  name: string;
  profileImage: string;
  aggregateVerifier?: string;
  verifier: string;
  verifierId: string;
  typeOfLogin: LOGIN_TYPE;
  ref?: string;
  registerOnly?: boolean;
  extraVerifierParams?: WebAuthnExtraParams;
}

export interface LoginWindowResponse {
  accessToken: string;
  idToken?: string;
  ref?: string;
  extraParams?: string;
  extraParamsPassed?: string;
  state: TorusGenericObject;
}

export type WebAuthnExtraParams = {
  signature?: string;
  clientDataJSON?: string;
  authenticatorData?: string;
  publicKey?: string;
  challenge?: string;
  rpOrigin?: string;
  credId?: string;
};

Examples

Native

/*
 Native logins use this approach
 The following are native logins
 - google
 - facebook
 - reddit
 - discord
 - twitch
 All others are proxy logins
*/

const loginDetails = await torusdirectsdk.triggerLogin({
  typeOfLogin: "google",
  verifier: "YOUR_VERIFIER_HERE", // get your verifier deployed today
  clientId: "YOUR_GOOGLE_CLIENT_ID",
});

const loginDetails = await torusdirectsdk.triggerLogin({
  typeOfLogin: "facebook",
  verifier: "YOUR_VERIFIER_HERE", // get your verifier deployed today
  clientId: "YOUR_FACEBOOK_APP_ID",
});

Proxy

/*
  All logins done via a proxy auth provider use this method
  domain is a mandatory param
*/

const jwtParams = {
  domain: "YOUR_PROXY_VERIFIER_DOMAIN", // eg: "https://torus-test.auth0.com"
};

// twitter
const loginDetails = await torusdirectsdk.triggerLogin({
  typeOfLogin: "twitter",
  verifier: "YOUR_TWITTER_VERIFIER",
  // this is obtained at the proxy website (e.g.: auth0 application client id)
  clientId: "YOUR_PROXY_TWITTER_CLIENT_ID",
  jwtParams,
});

// passwordless
const loginDetails = await torusdirectsdk.triggerLogin({
  typeOfLogin: "jwt",
  verifier: "YOUR_PASSWORDLESS_VERIFIER",
  // this is obtained at the proxy website (e.g.: auth0 application client id)
  clientId: "YOUR_PROXY_PASSWORDLESS_CLIENT_ID",
  jwtParams: {
    ...jwtParams,
    // this corresponds to the field inside jwt which must be used to uniquely
    // identify the user
    verifierIdField: "name",
    isVerifierIdCaseSensitive: false,
  },
});

Rehydrate

/*
  In some platforms (electron etc.) or in cases where you wish to perform
  authentication in a different manner other than opening a popup (redirect flow),
  you can pass in hash and queryParameters of redirected url into the method
  to bypass opening of popup window and return the result
*/

var url = new URL(location.href);
const hash = url.hash.substr(1);
const queryParameters = {};
for (let key of url.searchParams.keys()) {
  queryParameters[key] = url.searchParams.get(key);
}

const loginDetails = await torusdirectsdk.triggerLogin({
  typeOfLogin: "google",
  verifier: "YOUR_GOOGLE_VERIFIER",
  clientId: "YOUR_GOOGLE_CLIENT_ID",
  jwtParams: {},
  hash,
  queryParameters,
});

triggerAggregateLogin

triggerAggregateLogin performs the following actions:

• Opens the login window of the auth provider as a popup
• Listens on the redirected url
• Returns the verifier scoped public private key pair + user info

Use this if you wish to have account linking / multiple verifiers returning same keys (e.g.: passwordless and google logins returning the same key or google iOS, web, android clients to return the same key). Currently, only single_id_verifier is supported as aggregate verifier type

await torusdirectsdk.triggerAggregateLogin(options);

Parameters

options is an object of type AggregateLoginParams with the following parameters

• params - AggregateLoginParams : The login options.

  • aggregateVerifierType - AGGREGATE_VERIFIER_TYPE : Currently only single_id_verifier is supported

  • verifierIdentifier - string: A verifierIndentifier is a unique identifier for your OAuth registration on the torus network. The public/private keys generated for a user are scoped to a verifierIdentifier for aggregate login. Register your app here to get your verifier today.

  • subVerifierDetailsArray- SubVerifierDetails[]: SubVerifierDetails is the options parameter for triggerLogin

Returns

• Promise<TorusAggregateLoginResponse> : Returns a promise which resolves to the TorusAggregateLoginResponse object

Reference

export const AGGREGATE_VERIFIER = {
  SINGLE_VERIFIER_ID: "single_id_verifier",
  // AND_AGGREGATE_VERIFIER : "and_aggregate_verifier",
  // OR_AGGREGATE_VERIFIER : "or_aggregate_verifier",
} as const;
export type AGGREGATE_VERIFIER_TYPE = typeof AGGREGATE_VERIFIER[keyof typeof AGGREGATE_VERIFIER];
export interface AggregateLoginParams {
  aggregateVerifierType: AGGREGATE_VERIFIER_TYPE;
  verifierIdentifier: string;
  subVerifierDetailsArray: SubVerifierDetails[];
}

export type TorusAggregateLoginResponse = TorusAggregateVerifierResponse &
  TorusKey;

export interface TorusAggregateVerifierResponse {
  userInfo: (TorusVerifierResponse & LoginWindowResponse)[];
}
// Additional types are present in the triggerLogin documentation

Examples

Native

/*
 If you want google and facebook logins to have the same user account,
 do the following
*/

const subVerifierDetailsGoogle = {
  typeOfLogin: "google",
  verifier: "ANY_UNIQUE_STRING",
  clientId: "YOUR_GOOGLE_CLIENT_ID",
};

const subVerifierDetailsFacebook = {
  typeOfLogin: "facebook",
  verifier: "ANY_UNIQUE_STRING",
  clientId: "YOUR_FACEBOOK_APP_ID",
};

// The deployed verifier identifier links both google and facebook
const commonVerifierIdentifier = "YOUR_VERIFIER_IDENTIFIER_HERE";

// when user clicks google button, use this
const loginDetails = await torusdirectsdk.triggerAggregateLogin({
  aggregateVerifierType: "single_id_verifier",
  // get your verifier identifier deployed today
  verifierIdentifier: commonVerifierIdentifier,
  subVerifierDetailsArray: [subVerifierDetailsGoogle],
});

// when user clicks facebook button, use this
const loginDetails = await torusdirectsdk.triggerAggregateLogin({
  aggregateVerifierType: "single_id_verifier",
  // get your verifier identifier deployed today
  verifierIdentifier: commonVerifierIdentifier,
  subVerifierDetailsArray: [subVerifierDetailsFacebook],
});

Proxy

/*
 If you want google and passwordless logins to have the same user account,
 do the following
*/

const jwtParams = {
  domain: "YOUR_PROXY_VERIFIER_DOMAIN", // eg: "https://torus-test.auth0.com"
};

const subVerifierDetailsGoogle = {
  typeOfLogin: "google",
  verifier: "ANY_UNIQUE_STRING",
  clientId: "YOUR_GOOGLE_CLIENT_ID",
};

const subVerifierDetailsPasswordless = {
  typeOfLogin: "jwt",
  verifier: "ANY_UNIQUE_STRING",
  // this is obtained at the proxy website (e.g.: auth0 application client id)
  clientId: "YOUR_PROXY_PASSWORDLESS_CLIENT_ID",
  jwtParams: {
    ...jwtParams,
    // this corresponds to the field inside jwt which must be used to uniquely
    // identify the user. This is mapped b/w google and passwordless logins
    verifierIdField: "name",
    isVerifierIdCaseSensitive: false,
  },
};

// The deployed verifier identifier links both google and passwordless
const commonVerifierIdentifier = "YOUR_VERIFIER_IDENTIFIER_HERE";

// when user clicks google button, use this
const loginDetails = await torusdirectsdk.triggerAggregateLogin({
  aggregateVerifierType: "single_id_verifier",
  // get your verifier identifier deployed today
  verifierIdentifier: commonVerifierIdentifier,
  subVerifierDetailsArray: [subVerifierDetailsGoogle],
});

// when user clicks passwordless button, use this
const loginDetails = await torusdirectsdk.triggerAggregateLogin({
  aggregateVerifierType: "single_id_verifier",
  // get your verifier identifier deployed today
  verifierIdentifier: commonVerifierIdentifier,
  subVerifierDetailsArray: [subVerifierDetailsPasswordless],
});

Rehydrate

/*
  In some platforms (electron etc.) or in cases where you wish to perform
  authentication in a different manner other than opening a popup (redirect flow),
  you can pass in hash and queryParameters of redirected url into the method
  to bypass opening of popup window and return the result
*/

var url = new URL(location.href);
const hash = url.hash.substr(1);
const queryParameters = {};
for (let key of url.searchParams.keys()) {
  queryParameters[key] = url.searchParams.get(key);
}

const subVerifierDetailsGoogle = {
  typeOfLogin: "google",
  verifier: "ANY_UNIQUE_STRING",
  clientId: "YOUR_GOOGLE_CLIENT_ID",
  jwtParams: {},
  hash,
  queryParameters,
};

// The deployed verifier identifier links both google and other login type
const commonVerifierIdentifier = "YOUR_VERIFIER_IDENTIFIER_HERE";

// when user clicks passwordless button, use this
const loginDetails = await torusdirectsdk.triggerAggregateLogin({
  aggregateVerifierType: "single_id_verifier",
  // get your verifier identifier deployed today
  verifierIdentifier: commonVerifierIdentifier,
  subVerifierDetailsArray: [subVerifierDetailsGoogle],
});

getRedirectResult

getRedirectResult gets the TorusKey result post redirect flow. This method should only be called at the end of the redirect flow.

await torusdirectsdk.getRedirectResult(options);

Parameters options is an object of type RedirectResultParams with the following parameters

• options - RedirectResultParams : The redirect result options.
  • replaceUrl? - boolean (optional) : Whether to clean the url of hash/query params

Returns

• Promise<RedirectResult> : Returns a promise which resolves to the RedirectResult object

Reference

export const TORUS_METHOD = {
  TRIGGER_LOGIN: "triggerLogin",
  TRIGGER_AGGREGATE_LOGIN: "triggerAggregateLogin",
  TRIGGER_AGGREGATE_HYBRID_LOGIN: "triggerHybridAggregateLogin",
} as const;

export type TORUS_METHOD_TYPE = typeof TORUS_METHOD[keyof typeof TORUS_METHOD];

export interface RedirectResult {
  method: TORUS_METHOD_TYPE;
  result: TorusLoginResponse | TorusAggregateLoginResponse | unknown;
  error?: string;
  state: Record<string, unknown>;
}
// types are present in the above documentation

Examples

const torusRedirectResult = await torusdirectsdk.getRedirectResult();

getTorusKey

getTorusKey is a helper method which by passes the login flow and communicates directly with the torus nodes to return you the user's key. Use this if you have a custom login flow and wish to get just the user's key

await torusdirectsdk.getTorusKey(verifier: string,
    verifierId: string,
    verifierParams: { verifier_id: string },
    idToken: string,
    additionalParams?: extraParams);

Parameters

• verifier - string : A verifier is a unique identifier for your OAuth registration on the torus network. The public/private keys generated for a user are scoped to a verifier. Register your app here to get your verifier today

• verifierId - string: verifierId is the unique identifier to publicly represent a user on a verifier. e.g: email, sub etc. other fields can be classified as verifierId

• verifierParams- object: As stated in the signature. Can contain other fields which can be useful for aggregate logins

• idToken- string: idToken or accessToken received from the OAuth provider

• additionalParams- extraParams: Any additional parameters you wish to send to the torus nodes. useful for WebAuthn logins

Returns

• Promise<TorusKey> : Returns a promise which resolves to the TorusKey object

Reference

export interface extraParams {
  [key: string]: unknown;
}
// additional types are present in the triggerLogin documentation

Examples

// google
const torusKey = await torusdirectsdk.getTorusKey(
  "YOUR_GOOGLE_VERIFIER",
  "USER_EMAIL",
  { verifier_id: "USER_EMAIL" },
  "USER_GOOGLE_ID_TOKEN"
);

getAggregateTorusKey

getAggregateTorusKey is a helper method which by passes the login flow and communicates directly with the torus nodes to return you the user's key. Use this if you have a custom aggregate login flow and wish to get just the user's key

await torusdirectsdk.getAggregateTorusKey(
  (verifier: string),
  (verifierId: string),
  (subVerifierInfoArray: TorusSubVerifierInfo[])
);

Parameters

• verifier - string : A verifier is a unique identifier for your OAuth registration on the torus network. The public/private keys generated for a user are scoped to a verifier. Register your app here to get your verifier today

• verifierId - string: verifierId is the unique identifier to publicly represent a user on a verifier. e.g: email, sub etc. other fields can be classified as verifierId

• subVerifierInfoArray- TorusSubVerifierInfo[]: Refer below.

Returns

• Promise<TorusKey> : Returns a promise which resolves to the TorusKey object

Reference

export interface TorusSubVerifierInfo {
  verifier: string;
  idToken: string;
  extraVerifierParams?: WebAuthnExtraParams;
}
// types are present in the triggerLogin documentation

Examples

// google
const torusKey = await torusdirectsdk.getAggregateTorusKey(
  "YOUR_AGGREGATE_VERIFIER",
  "USER_EMAIL",
  [
    {
      idToken: "OAUTH_ID_TOKEN",
      verifier: "SUB_VERIFIER",
    },
  ]
);