You... shall not... PAAASS!

… thundered Gandalf (the movie bloke, the book bloke on the other hand said "cannot" instead of "shall not") as he restricted the Balrog to cross the Bridge of Khazad-dûm in the Lord of The Rings - The Fellow of the Ring.

While that was fantasy, in the real world, restricting access or rather authentication and authorisation is a critical component of web based applications that provide features based on which user is logged in. With web2 applications that maintain user sessions, there's usually a sign up / sign in feature where users register themselves with the application and subsequently identify themselves to gain access to various sections of the application, which they could not otherwise access.

With web3 applications, we can replace the traditional username / email based login and instead go for what is most valuable and must have utility - their crypto wallet. Instead of providing their username or email during sign up and reusing it during sign in, web3 application users instead can connect their "wallet" - which like its web2 counterpart, uniquely identifies the user.

Just like with web2 applications, it can get really cumbersome to repeat the same code over and over again each time you create a new application - specifically for common tasks such as signing up and signing in users.

This is where Subter's Wallet Guard module comes into picture. Currently available as a reactjs module, Wallet Guard provides you instantly with features to read the backend contract, interact with the user's wallet and to connect (sign in) and disconnect (sign out) their wallets. You no longer have to code it all by yourself and in a few minutes you will instantly have a full fledged web3 auth management integrated into your app.

How to use the Wallet Guard

After installing the module, you start off by wrapping all your components (the ones that need info about the user) in a context provider:

<ProvideAuth
  network="hangzhounet"
  contractAddress={process.env.REACT_APP_BACKEND_CONTRACT_ADDRESS}
  beaconWalletOptions={{
    name: "Subter Development",
    disableDefaultEvents: true,
    eventHandlers={{
      [BeaconEvent.LOCAL_RATE_LIMIT_REACHED]: {
        handler: data => console.log("Local rate limit reached")
      }
    }}
  }}
>
  {/** React Router components used here, but you can wrap any component of your liking */}
  <BrowserRouter>
    <Routes>
      <Route path="/" element={<App />} />
      <Route path="/dashboard" element={<Dashboard />} />
    </Routes>
  </BrowserRouter>
</ProvideAuth>

The <ProvideAuth /> component used is a React Context Provider. You need to specify the network you need to connect to and your backend tezos contract's address. Internally, it uses Beacon to manage the user's wallet.

What this provides is a hook - useAuth(). This hook returns:

- your contract (you shared the address with the Context Provider earlier) through contract

- the currently active user's wallet, through wallet. Separately, you get the details about the user's wallet address (userAddress) and the wallet balance (userBalance).

- the storage on the contract, through storage

- utility functions to connect and disconnect with the user's wallet, through connectWallet and disconnectWallet respectively.

Voila! No further coding necessary. Right of the bat, you get all the control needed to guard your application and interact with the contract.

How to enhance the Wallet Guard to create a "Route Guard"

You can even enhance this by creating a "route guard" - allowing only users that have connected their wallets to access certain routes of your application:

/**
 * <PrivateRoute /> here overrides the <Route /> component offered by React Router
 */
function PrivateRoute({ children, ...rest }) {
  const { publicToken, userAddress, userBalance } =  useAuth();

  return (
    <Route
      {...rest}
      render={({ location }) => {
        if (publicToken  && (!userAddress  ||  isNaN(userBalance))) {
          // This implies the user is still connecting their wallet
          return <Loading />; // Render a loading indicator
        } else  if (userAddress  &&  !isNaN(userBalance)) {
          // User has connected their wallet
          return children; // Render the private route
        }

        // User has not connected their wallet. DO NOT show the private route and instead
        // redirect to the Connect Wallet page
        return (
          <Redirect
            to={{
              pathname: "/login",
            }}
          />
        );
      }}
    />
  );
}

Now, only those users that have connected their wallets with your application can access the private route declared. The Wallet Guard module is thus quite useful when you build web3 based tezos applications.

All of this would not be possible without the awesome taquito library. It provides the TezosToolkit and the BeaconWallet modules that the Wallet Guard builds upon.