Skip to content

Latest commit

 

History

History
404 lines (322 loc) · 15.2 KB

auths.md

File metadata and controls

404 lines (322 loc) · 15.2 KB
Raw

Auths

Sismo Connect can be used to authenticate a user from multiple sources, either from web2 or web3.

Type definitions

The AuthRequest is an object with the following properties:

  • AuthType (required): defines the type of authentication required. The following authType are currently supported:
    • VAULT: Sismo Connect returns the user's vaultId for the application that requested it. It is a deterministic anonymous identifier (hash(userVaultSecret, AppId, ..))
      See more information about Vault Identifiers here.
    • GITHUB: Sismo Connect returns the user's GitHub account id.
    • TWITTER Sismo Connect returns the user's Twitter account id.
    • EVM_ACCOUNT: Sismo Connect returns the user's Ethereum address.
    • TELEGRAM : Sismo Connect returns the user's Telegram account id.
  • userId (optional): requests the user to have a predefined account.
  • isOptional(optional): by default set to false. Allows the user to optionally authenticate with this AuthType.
// Types (typescript version)
enum AuthType {
    VAULT = 0,
    GITHUB = 1,
    TWITTER = 2,
    EVM_ACCOUNT = 3,
    TELEGRAM = 4,
}

type AuthRequest = {
    authType: AuthType;
    userId?: string;
    isOptional?: boolean;
};

Integrations

Authentication requests are made in the front end using either the sismo-connect-react package or the sismo-connect-client package. Requests are then verified either in a back end using the sismo-connect-server package or in a smart contract using the sismo-connect-solidity package.

Making an AuthRequest - Front-end integration

{% hint style="info" %} Making an AuthRequest is only possible in the front end as the request redirects users to the Sismo Data Vault app, where users can generate a zero-knowledge proof. {% endhint %}

{% tabs %} {% tab title="React Component" %} The SismoConnectButton React component is available from the sismo-connect-react package. It is a wrapper of the sismo-connect-client package.

  • AuthRequests are passed as props of the SismoConnectButton either through:
    1. the auth props for one authentication request: AuthRequest or,
    2. the auths props for several authentication requests: AuthRequest[]
  • Responses are received through either:
    1. the onResponse: (response: SismoConnectResponse) => void callback for offchain verification or,
    2. the onResponseBytes (response: string) => void callback for onchain verification.

One AuthRequest - code example

{% code title="app.tsx" overflow="wrap" %}

import { SismoConnectButton, AuthType, SismoConnectClientConfig, SismoConnectResponse } from "@sismo-core/sismo-connect-react";

<SismoConnectButton 
    // the client config created
    config={config}
    // request a proof of account ownership 
    // (here Vault ownership)
    auth={{authType: AuthType.VAULT}}
    onResponse={async (response: SismoConnectResponse) => {
	//Send the response to your server to verify it
	//thanks to the @sismo-core/sismo-connect-server package
    }}
    onResponseBytes={async (bytes: string) => {
        //Send the response to your contract to verify it
        //thanks to the @sismo-core/sismo-connect-solidity package
    }}
/>

{% endcode %}

Multiple AuthRequests - code example

{% code title="app.tsx" overflow="wrap" %}

// You can also create several auth requests 
// in the same button
import { SismoConnectButton, AuthType, SismoConnectClientConfig, SismoConnectResponse } from "@sismo-core/sismo-connect-react";

<SismoConnectButton 
    config={config}
    // request multiple proofs of account ownership 
    // (here Vault ownership and Twitter account ownership)
    auths={[
        {authType: AuthType.VAULT},
        {authType: AuthType.TWITTER},
    ]}
    onResponse={async (response: SismoConnectResponse) => {
	//Send the response to your server to verify it
	//thanks to the @sismo-core/sismo-connect-server package
    }}
    onResponseBytes={async (bytes: string) => {
        //Send the response to your contract to verify it
        //thanks to the @sismo-core/sismo-connect-solidity package
    }}
/>

{% endcode %} {% endtab %}

{% tab title="React Hook" %} The useSismoConnect hook is available from the sismo-connect-react package. It is a wrapper of the sismo-connect-client package. The useSismoConnect hook exposes the sismoConnect variable.

  • One or multiple AuthRequests can be made using the sismoConnect.request() method available on the sismoConnect variable.
  • The response could be received through either:
    1. the sismoConnect.getResponse() method for offchain verification or,
    2. the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

{% code title="App.tsx" overflow="wrap" %}

import { useSismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-react";

const { sismoConnect } = useSismoConnect({ config });

// Making the request a proof of account ownership 
// (here Vault ownership)
function onClick(){
  sismoConnect.request({
      auth: {authType: AuthType.VAULT}
    });
}

// Proofs are available in two differents types depending on usage (offchain or onchaon verification)
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

{% endcode %}

Multiple AuthRequests - code example

{% code title="App.tsx" overflow="wrap" %}

import { useSismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-react";

const { sismoConnect } = useSismoConnect({ config });

// Making the request for multiple proofs of account ownership 
// (here Vault ownership and Twitter account ownership)
function onClick(){
  sismoConnect.request({
      auths: [
      {authType: AuthType.VAULT},
      {authType: AuthType.TWITTER},
      ]   
    });
}

// Proofs are available in two differents types depending on usage (offchain or onchaon verification)
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

{% endcode %} {% endtab %}

{% tab title="TypeScript" %} The sismo-connect-client package exposes a SismoConnect variable.

  • One or multiple AuthRequests can be made using the sismoConnect.request() method available on a SismoConnect instance.
  • The response could be received through either:
    1. the sismoConnect.getResponse() method for offchain verification or,
    2. the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

{% code title="app.ts" overflow="wrap" %}

import { SismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-client";

const sismoConnect = SismoConnect({config});

// Making the request a proof of account ownership 
// (here Vault ownership)
function onClick(){
  sismoConnect.request({
      auth: {authType: AuthType.VAULT}
    });
}

// Receive the proofs in two different formats
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

{% endcode %}

Multiple AuthRequests - code example

{% code title="app.ts" overflow="wrap" %}

import { SismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-client";

const sismoConnect = SismoConnect({config});

// Making the request for multiple proofs of account ownership 
// (here Vault ownership and Twitter account ownership)
function onClick(){
  sismoConnect.request({
      auths: [
      {authType: AuthType.VAULT},
      {authType: AuthType.TWITTER},
      ]   
    });
}

// Receive the proofs in two different formats
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

{% endcode %} {% endtab %} {% endtabs %}

Verifying an AuthRequest

Once a user has generated a ZKP on the Data Vault app, your application must verify it. This can be achieved in onchain smart contracts or offchain back ends.

{% tabs %} {% tab title="offchain verification - Node.js" %} The sismo-connect-server package exposes a SismoConnect variable.

One or multiple AuthRequests can be verified offchain on a backend server using the sismoConnect.verify() method available on a SismoConnect instance.

  • If the proof is valid sismoConnect.verify() returns a result of type SismoConnectVerifiedResult else it will throw an error,
  • the result.getUserId() can be called as shown below to get the userId of the corresponding type.

One AuthRequest - code example

{% code overflow="wrap" %}

import { SismoConnect, SismoConnectVerifiedResult, AuthType } from "@sismo-core/sismo-connect-server";

const sismoConnect = SismoConnect({config});

async function verifyResponse(sismoConnectResponse: SismoConnectResponse) {
  // verifies the proofs contained in the sismoConnectResponse
  // with respect to the different auths
  // i.e. user prove they own a Vault
  const result: SismoConnectVerifiedResult = await sismoConnect.verify(
    sismoConnectResponse,
    {
      // proofs in the sismoConnectResponse should be valid
      // with respect to a Vault ownership
      auth: { authType: AuthType.VAULT },
    }
  )

  // vaultId = hash(userVaultSecret, appId).
  // the vaultId is an app-specific, anonymous identifier of a vault
  const vaultId = result.getUserId(AuthType.VAULT)
}

{% endcode %}

{% hint style="success" %} If you are using Nextjs, you will need to add this config in the next.config.js file to be able to verify the proof. You can find more information here.

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ["@sismo-core/sismo-connect-server"],
  },
}

module.exports = nextConfig

{% endhint %}

Multiple AuthRequests - code example

{% code overflow="wrap" %}

import { SismoConnect, SismoConnectVerifiedResult, AuthType } from "@sismo-core/sismo-connect-server";

const sismoConnect = SismoConnect({config});

async function verifyResponse(sismoConnectResponse: SismoConnectResponse) {
  // verifies the proofs contained in the sismoConnectResponse
  // with respect to the different auths
  // i.e. user prove they own a Vault, a Twitter account
  const result: SismoConnectVerifiedResult = await sismoConnect.verify(
    sismoConnectResponse,
    {
      // proofs in the sismoConnectResponse should be valid
      // with respect to a Vault and Twitter account ownership
      auths: [
        { authType: AuthType.VAULT }, 
        { authType: AuthType.TWITTER }
      ],
    }
  )

  // vaultId = hash(userVaultSecret, appId).
  // the vaultId is an app-specific, anonymous identifier of a vault
  const vaultId = result.getUserId(AuthType.VAULT)
  // you can also get the twitterId of the user
  const twitterId = result.getUserId(AuthType.TWITTER)
}

{% endcode %} {% endtab %}

{% tab title="onchain verification - Solidity" %} The sismo-connect-solidity package exposes a Sismo Connect Library, which can be inherited by your contract either using Foundry or Hardhat.

The Sismo Connect Library exposes:

  • a verify() function, which allows you to verify a proof generated by the Sismo Vault app with respect to some requests directly in your contract. The verify() function takes an object containing:
    1. a responseBytes send from the front end,
    2. an auth or auths corresponding to the authentification request made in the front end.
  • a buildAuth() helper to recreate the AuthRequest made in the front-end
  • a SismoConnectHelper.getUserId() helper to retrieve the userId of the corresponding type once the proof has been verified.

One AuthRequest - code example

contract MyContract is SismoConnect { // inherits from Sismo Connect library
 
// call SismoConnect constructor with your appId
constructor(bytes16 appId) SismoConnect(buildConfig(appId)) {}

    function doSomethingUsingSismoConnect(bytes memory sismoConnectResponse) public {    
        SismoConnectVerifiedResult memory result = verify({
            responseBytes: sismoConnectResponse,
            // we want users to prove that they own a Sismo Vault
            // we are recreating the auth request made in the frontend to be sure that 
            // the proof provided in the response is valid with respect to this auth request
            auth: buildAuth({authType: AuthType.VAULT}),       
        });
    
        // if the proofs is valid, we can take the userId from the verified result
        // in this case the userId is the vaultId (since we used AuthType.VAULT in the auth request) 
        // it is the anonymous identifier of a user's vault for a specific app 
        // --> vaultId = hash(userVaultSecret, appId)
        uint256 vaultId = SismoConnectHelper.getUserId(result, AuthType.VAULT);
        
        // do something with this vaultId for example
    }
}

Multiple AuthRequests - code example

contract MyContract is SismoConnect { // inherits from Sismo Connect library
 
// call SismoConnect constructor with your appId
constructor(bytes16 appId) SismoConnect(buildConfig(appId)) {}

    function doSomethingUsingSismoConnect(bytes memory sismoConnectResponse) public {    
        // we want users to prove that they own a Sismo Vault and a Twitter Id
        // we are recreating the auth request made in the frontend to be sure that 
        // the proof provided in the response is valid with respect to this auth request
        
        AuthRequest[] memory auths = new AuthRequest[](2);
        auths[0] = buildAuth({authType: AuthType.VAULT})
        auths[1] = buildAuth({authType: AuthType.TWITTER})
        
        SismoConnectVerifiedResult memory result = verify({
            responseBytes: sismoConnectResponse,
            auths: auths,       
        });
        
        // --> vaultId = hash(userVaultSecret, appId)
        uint256 vaultId = SismoConnectHelper.getUserId(result, AuthType.VAULT);
        uint256 twitterId = SismoConnectHelper.getUserId(result, AuthType.TWITTER);     
        
        // do something with this vaultId and the twitterID
    }
}

{% endtab %} {% endtabs %}