npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ic-use-siws-identity

v0.0.1

Published

React hook and context provider for easy frontend integration with SIWS (Sign in with Solana) enabled Internet Computer canisters.

Downloads

18

Readme

Sign in with Solana for the Internet Computer

ic-use-siws-identity is a React hook and context provider for easy frontend integration with SIWS enabled Internet Computer canisters.

ic-use-siws-identity is part of the ic-siws project that enables Solana wallet-based authentication for applications on the Internet Computer (ICP) platform. The goal of the project is to enhance the interoperability between Solana and the Internet Computer platform, enabling developers to build applications that leverage the strengths of both platforms.

A SIWS enabled canister is a canister that integrates the ic_siws library and exposes the SIWS login interface. The ic_siws library provides a set of functions for managing Internet Computer delegate identities created using Solana signatures.

version downloads

Features

  • Cached Identity: The identity is cached in local storage and restored on page load. This allows the user to stay logged in even if the page is refreshed.
  • Login progress: State varibles are provided to indicate whether the user is logged in, logging in, or logged out.
  • Works with ic-use-actor: Plays nicely with ic-use-actor for hassle free frontend integration.
  • Works with ic_siws_provider: An easy alternative to integrating with ic_siws directly is using the prebuilt ic_siws_provider canister. The provider canister can be added to your project as a dependency and used as a login provider for you project.

Table of Contents

Installation

In addition to ic-use-siws-identity, these peer dependencies are required:

  • @dfinity/agent
  • @dfinity/candid
  • @dfinity/identity
  • @solana/wallet-adapter-base
  • @solana/wallet-adapter-react
npm install ic-use-siws-identity @dfinity/agent @dfinity/candid @dfinity/identity @solana/wallet-adapter-base @solana/wallet-adapter-react

Usage

[!TIP] For a complete example, see the ic-siws-react-demo-rust demo project.

To use ic-use-siws-identity in your React application, follow these steps:

1. Add an Solana wallet provider

Before interacting with the useSiwsIdentity hook, you need to add an Solana wallet provider to your application. The wallet provider is responsible for connecting to the Solana wallet and handling the signing of messages. It an detect most Solana wallets on the market.

[!TIP] See the Solana wallet adapter documentation for the most up-to-date setup instructions.

// SolanaProviders.tsx

import "@solana/wallet-adapter-react-ui/styles.css";

import {
  ConnectionProvider,
  WalletProvider,
} from "@solana/wallet-adapter-react";
import React, { useMemo } from "react";

import { WalletAdapterNetwork } from "@solana/wallet-adapter-base";
import { WalletModalProvider } from "@solana/wallet-adapter-react-ui";
import { clusterApiUrl } from "@solana/web3.js";

export default function SolanaProviders({
  children,
}: {
  children: React.ReactNode;
}) {
  const network = WalletAdapterNetwork.Devnet;
  const endpoint = useMemo(() => clusterApiUrl(network), [network]);

  return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider autoConnect wallets={[]}>
        <WalletModalProvider>{children}</WalletModalProvider> // The rest of your app
      </WalletProvider>
    </ConnectionProvider>
  );
}

2. Setup the SiwsIdentityProvider component

Wrap your application's root component with SiwsIdentityProvider to provide all child components access to the SIWS identity context. Provide the component with the _SERVICE type argument, where _SERVICE represents the canister service definition of a canister that implements the SIWS login interface. This could be a canister that you have created yourself, using the ic_siws library, or the prebuilt ic_siws_provider canister. Adding the pre-built provider canister to your project as a dependency is the easiest way to get started.

// App.tsx

import { SiwsIdentityProvider } from 'ic-use-siws-identity';
import { _SERVICE } from "[DECLARATIONS PATH]/declarations/ic_siws_provider/ic_siws_provider.did";
import {
  canisterId,
  idlFactory,
} from "[DECLARATIONS PATH]/declarations/ic_siws_provider/index";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <SolanaProviders>
      <SiwsIdentityProvider<_SERVICE>
        canisterId={canisterId}
        idlFactory={idlFactory}
      >
        <Actors>
          <AuthGuard>
            <App />
          </AuthGuard>
        </Actors>
      </SiwsIdentityProvider>
    </SolanaProviders>
  </React.StrictMode>
);

3. Prepare the login

This is an optional step, as the login process will automatically call prepareLogin if it has not been called manually. However, calling prepareLogin before initiating the login process improves the user experience by reducing the time it takes to complete the login. The prepareLogin function requests a SIWS message from the backend. This is an update call that usually takes two to three seconds to complete.

The prepareLoginStatus state variable can be used to indicate the status of the prepare login process. Errors that occur during the prepare login process are stored in the prepareLoginError state variable.

[!IMPORTANT] Be sure to call prepareLogin again on wallet change, as the SIWS message is unique to the Solana address of the user. If the user changes their wallet, the SIWS message will be invalid and a new one must be requested.

  const { publicKey } = useWallet(); // Solana wallet hook
  const { prepareLogin, isPrepareLoginIdle, prepareLoginError, loginError } =
    useSiwsIdentity();

/**
 * Preload a Siws message on every address change.
 */
  useEffect(() => {
    if (!isPrepareLoginIdle || !publicKey) return;
    prepareLogin();
  }, [publicKey, prepareLogin, isPrepareLoginIdle]);

4. Initiate the login process

The login process is initiated by calling the login function. This function requests a SIWS message from the backend if it has not already been loaded. The user is asked to sign the message using their Solana wallet and the signed message is sent to the backend for authentication. Once the authentication is complete, the user's identity is stored in local storage and the identity state variable is updated with the new identity.

The loginStatus state variable can be used to indicate the status of the login process. Errors that occur during the login process are stored in the loginError state variable.

import { useSiwsIdentity } from "ic-use-siws-identity";
import { useWallet } from "@solana/wallet-adapter-react";

export default function LoginButton() {
  const { connected } = useWallet();
  const { login, isLoggingIn, isPreparingLogin } = useSiwsIdentity();

  const text = () => {
    if (isLoggingIn) {
      return "Signing in";
    }
    if (isPreparingLogin) {
      return "Preparing";
    }
    return "Sign in";
  };

  const disabled = isLoggingIn || !connected || isPreparingLogin;

  return (
    <button
      disabled={disabled}
      onClick={() => {
        login();
      }}
    >
      {text()}
    </button>
  );
}

SiwsIdentityProvider props

{
  /** Configuration options for the HTTP agent used to communicate with the Internet Computer network. */
  httpAgentOptions?: HttpAgentOptions;

  /** Configuration options for the actor. These options are passed to the actor upon its creation. */
  actorOptions?: ActorConfig;

  /** The Interface Description Language (IDL) factory for the canister. This factory is used to create an actor interface for the canister. */
  idlFactory: IDL.InterfaceFactory;

  /** The unique identifier of the canister on the Internet Computer network. This ID is used to establish a connection to the canister. */
  canisterId: string;

  /** The child components that the SiwsIdentityProvider will wrap. This allows any child component to access the authentication context provided by the SiwsIdentityProvider. */
  children: ReactNode;
}

useSiwsIdentity interface

export type SiwsIdentityContextType = {
  /** Is set to `true` on mount until a stored identity is loaded from local storage or
   * none is found. */
  isInitializing: boolean;

  /** Load a SIWS message from the provider canister, to be used for login. Calling prepareLogin
   * is optional, as it will be called automatically on login if not called manually. */
  prepareLogin: () => void;

  /** Reflects the current status of the prepareLogin process. */
  prepareLoginStatus: PrepareLoginStatus;

  /** `prepareLoginStatus === "loading"` */
  isPreparingLogin: boolean;

  /** `prepareLoginStatus === "error"` */
  isPrepareLoginError: boolean;

  /** `prepareLoginStatus === "success"` */
  isPrepareLoginSuccess: boolean;

  /** `prepareLoginStatus === "idle"` */
  isPrepareLoginIdle: boolean;

  /** Error that occurred during the prepareLogin process. */
  prepareLoginError?: Error;

  /** Initiates the login process by requesting a SIWS message from the backend. */
  login: () => Promise<DelegationIdentity | undefined>;

  /** Reflects the current status of the login process. */
  loginStatus: LoginStatus;

  /** `loginStatus === "logging-in"` */
  isLoggingIn: boolean;

  /** `loginStatus === "error"` */
  isLoginError: boolean;

  /** `loginStatus === "success"` */
  isLoginSuccess: boolean;

  /** `loginStatus === "idle"` */
  isLoginIdle: boolean;

  /** Error that occurred during the login process. */
  loginError?: Error;

  /** The delegation chain is available after successfully loading the identity from local
   * storage or completing the login process. */
  delegationChain?: DelegationChain;

  /** The identity is available after successfully loading the identity from local storage
   * or completing the login process. */
  identity?: DelegationIdentity;

  /** The Ethereum address associated with current identity. This address is not necessarily
   * the same as the address of the currently connected wallet - on wallet change, the addresses
   * will differ. */
  identityAddress?: PublicKey;

  /** Clears the identity from the state and local storage. Effectively "logs the user out". */
  clear: () => void;
};

Contributing

Contributions are welcome. Please submit your pull requests or open issues to propose changes or report bugs.

Author

License

This project is licensed under the MIT License. See the LICENSE file for more details.