identity-react

Reclaim Identity for React

Reclaim Identity is a React-based authentication module that provides an easy-to-use interface for authenticating users with the Reclaim Protocol. It manages the OAuth 2.0 flow, handling user sign-in, token management, and user data retrieval within your React application.

Features

• React-friendly authentication flow
• OAuth 2.0 authentication with popup window
• Automatic token management
• User data retrieval and caching
• Event-based auth state changes
• TypeScript support

Installation

You can install the Reclaim Identity package using npm:

npm i identity-react

Or using yarn:

yarn add identity-react

Usage

Initializing ReclaimAuth

In your React application, typically in a context provider or a top-level component:

import React from 'react';
import { getReclaimAuth } from 'identity-react';

const clientId = 'your-client-id';
const redirectUri = 'your-redirect-uri';
const auth = getReclaimAuth(clientId, redirectUri);

function App() {
  // Your app code
}

Using ReclaimAuth in a Component

import React, { useState, useEffect } from 'react';
import { getReclaimAuth } from 'identity-react';

const clientId = 'your-client-id';
const redirectUri = 'your-redirect-uri';

function AuthComponent() {
  const [user, setUser] = useState(null);
  const auth = getReclaimAuth(clientId, redirectUri);

  useEffect(() => {
    const unsubscribe = auth.onAuthStateChanged((newUser) => {
      setUser(newUser);
    });

    return () => unsubscribe();
  }, []);

  const handleSignIn = async () => {
    try {
      await auth.signIn();
    } catch (error) {
      console.error('Sign in failed:', error);
    }
  };

  const handleSignOut = async () => {
    try {
      await auth.signOut();
    } catch (error) {
      console.error('Sign out failed:', error);
    }
  };

  return (
    <div>
      {user ? (
        <>
          <p>Welcome, {user.id}</p>
          <button onClick={handleSignOut}>Sign Out</button>
        </>
      ) : (
        <button onClick={handleSignIn}>Sign In</button>
      )}
    </div>
  );
}

Creating a Custom Hook

You can create a custom hook to simplify the use of ReclaimAuth across your React components:

import { useState, useEffect } from 'react';
import { getReclaimAuth } from 'identity-react';

const clientId = 'your-client-id';
const redirectUri = 'your-redirect-uri';

export function useReclaimAuth() {
  const [user, setUser] = useState(null);
  const auth = getReclaimAuth(clientId, redirectUri);


  useEffect(() => {
    const unsubscribe = auth.onAuthStateChanged(setUser);
    return () => unsubscribe();
  }, []);

  return {
    user,
    signIn: auth.signIn,
    signOut: auth.signOut,
    getCurrentUser: auth.getCurrentUser,
  };
}

Then use it in your components:

function AuthComponent() {
  const { user, signIn, signOut } = useReclaimAuth();

  // Rest of your component code
}

API Reference

getReclaimAuth(clientId?: string, redirectUri?: string): ReclaimAuth

Returns the singleton instance of ReclaimAuth. clientId and redirectUri are only required on the first call.

signIn(): Promise<ReclaimUser>

Initiates the sign-in process, opening a popup for authentication. Returns a Promise that resolves with the user data.

getCurrentUser(): ReclaimUser | null

Returns the current signed-in user, or null if no user is signed in.

onAuthStateChanged(callback: (user: ReclaimUser | null) => void): () => void

Sets up a listener for changes in authentication state. Returns a function to unsubscribe from the events.

signOut(): Promise<void>

Signs out the current user.

Types

ReclaimUser

interface ReclaimUser {
    id: string;
    data: Map<string, string>;
}

Configuration

The ReclaimAuth module uses the following configuration options:

• clientId: Your Reclaim Protocol client ID.
• redirectUri: The URI to redirect to after authentication.

These should be provided when first calling getReclaimAuth().

Environment Variables

The module uses the following environment variables:

• NODE_ENV: Set to 'production' for production environment.

Browser Compatibility

ReclaimAuth is compatible with modern browsers that support ES6+ features. For older browser support, consider using appropriate polyfills.

Security Considerations

• The module uses secure practices like CSRF protection and secure cookie handling.
• Always use HTTPS in production environments.

Troubleshooting

If you encounter issues:

1. Ensure you're using the latest version of the package.
2. Check that your clientId and redirectUri are correct.
3. Verify that you're calling getReclaimAuth() with the required parameters on first use.
4. For network-related issues, check your browser's console for more details.