TocToc Auth

1.1.9 verified Sat May 09 auth: no javascript

TocToc Auth (v1.1.9) is a React authentication library with JWT access/refresh token lifecycle, encrypted local storage (AES-256-CBC, PBKDF2, HMAC), browser fingerprinting, and automatic token refresh with exponential backoff. Built for React 19, it ships TypeScript types and integrates via context providers and hooks. Differentiators include refresh deduplication, environment-aware logging, input sanitization, and open redirect protection. Released under active development.

Common errors

error Cannot read properties of undefined (reading 'signInWithCredentialsAsync') ↓

cause Component not wrapped in TocTocAuthProvider, or useTocTocAuth called outside provider.

fix

Wrap the component tree with <TocTocAuthProvider config={...}> at the root.

error TypeError: (0 , toctoc_auth.useTocTocAuth) is not a function ↓

cause Default import instead of named import.

fix

Use import { useTocTocAuth } from 'toctoc-auth' instead of import useTocTocAuth from 'toctoc-auth'.

Warnings

gotcha Peer dependencies require React 19 and react-router-dom 7. Using older versions may cause runtime errors. ↓

fix Ensure package.json includes react@^19.0.0, react-dom@^19.0.0, react-router-dom@^7.0.0.

gotcha Encryption key must be exactly 32 characters for AES-256. Using a different length silently degrades encryption. ↓

fix Set encryptionKey to a 32-character string in authConfig.

gotcha When signInAfterSignUp is true, the sign-in endpoint must accept the same request body as sign-up. Mismatched fields cause auth failures. ↓

fix Align sign-in API to accept the same payload as sign-up, or set signInAfterSignUp to false.

Install

npm install toctoc-auth

yarn add toctoc-auth

pnpm add toctoc-auth

Imports

TocTocAuthProvider

wrong

import TocTocAuthProvider from 'toctoc-auth'

correct

import { TocTocAuthProvider } from 'toctoc-auth'

Named export, not default. Since v1.0.

useTocTocAuth
```
import { useTocTocAuth } from 'toctoc-auth'
```
Hook must be used inside a TocTocAuthProvider context. Named export.

isTokenExpired

wrong

import { isTokenExpired } from 'toctoc-auth/utils'

correct

import { isTokenExpired } from 'toctoc-auth'

Utility function exported from main package. Not a subpath.

Quickstart

Minimal setup: wrap app with TocTocAuthProvider, then use useTocTocAuth hook for credentials-based sign-in.

import { TocTocAuthProvider, useTocTocAuth } from 'toctoc-auth';
import { BrowserRouter } from 'react-router-dom';

const authConfig = {
  apiBaseUrl: process.env.AUTH_API_URL ?? 'http://localhost:4000',
  encryptionKey: process.env.ENCRYPTION_KEY ?? 'default-dev-key-32chars!!',
  providers: {
    credentials: {
      signUpApiRoute: '/auth/register',
      signInApiRoute: '/auth/login',
      refreshTokenApiRoute: '/auth/refresh',
      signInAfterSignUp: false,
      redirectClientRoutes: {
        afterSignUp: '/dashboard',
        afterSignIn: '/dashboard',
        afterSignOut: '/login'
      },
      signInJsonResponseAccessTokenLocation: ['accessToken'],
      signInJsonResponseRefreshTokenLocation: ['refreshToken'],
      signInJsonResponseUser: {
        location: ['user'],
        roleLocation: ['role']
      }
    }
  }
};

function App() {
  return (
    <BrowserRouter>
      <TocTocAuthProvider config={authConfig}>
        <YourApp />
      </TocTocAuthProvider>
    </BrowserRouter>
  );
}

function LoginForm() {
  const { signInWithCredentialsAsync, isAuthenticating, user } = useTocTocAuth();
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    const res = await signInWithCredentialsAsync({ email: 'a@b.com', password: 'secret' });
    if (res.isSuccess) console.log('Logged in');
    else console.error(res.responseBody);
  };
  return (
    <form onSubmit={handleSubmit}>
      <button disabled={isAuthenticating}>Sign In</button>
    </form>
  );
}