Links
Comment on page

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

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.
React Component
React Hook
TypeScript
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. 1.
      the auth props for one authentication request: AuthRequest or,
    2. 2.
      the auths props for several authentication requests: AuthRequest[]
  • Responses are received through either:
    1. 1.
      the onResponse: (response: SismoConnectResponse) => void callback for offchain verification or,
    2. 2.
      the onResponseBytes (response: string) => void callback for onchain verification.

One AuthRequest - code example

app.tsx
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
}}
/>

Multiple AuthRequests - code example

app.tsx
// 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
}}
/>
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. 1.
      the sismoConnect.getResponse() method for offchain verification or,
    2. 2.
      the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

App.tsx
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.
}

Multiple AuthRequests - code example

App.tsx
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.
}
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. 1.
      the sismoConnect.getResponse() method for offchain verification or,
    2. 2.
      the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

app.ts
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.
}

Multiple AuthRequests - code example

app.ts
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.
}

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.
offchain verification - Node.js
onchain verification - Solidity
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

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)
}
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

Multiple AuthRequests - code example

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)
}
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. 1.
      a responseBytes send from the front end,
    2. 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
}
}