@gg-software/auth

Auth toolkit for JavaScript/TypeScript apps — JWT parsing, persisted session management, and role/permission (RBAC) helpers, with optional React bindings.

Installation

pnpm add @gg-software/auth
# or: npm install @gg-software/auth

The core is framework-agnostic with no required dependencies. react is an optional peer dependency, needed only if you use the @gg-software/auth/react entry point.

Core usage

The main entry point (@gg-software/auth) is pure logic — no React required.

import {
  parseBearerToken,
  decodeJwt,
  isTokenExpired,
  getSession,
  setSession,
  clearSession,
  hasRole,
  hasPermission,
  can,
} from "@gg-software/auth";

// Tokens
const token = parseBearerToken("Bearer eyJhbGci...");   // -> "eyJhbGci..."
const payload = decodeJwt(token);                        // typed JwtPayload
if (isTokenExpired(token)) redirectToLogin();

// Session (persisted to storage)
setSession({ user: { id: "1", roles: ["admin"] }, token });
const session = getSession();
clearSession();

// RBAC
hasRole(user, "admin");            // boolean
hasPermission(user, "delete:orders"); // wildcards supported, e.g. "delete:*"
can(user, "edit", "post");

React bindings

Import from @gg-software/auth/react for context, hooks, and gate components.

import {
  AuthProvider,
  useAuth,
  RequireAuth,
  usePermission,
} from "@gg-software/auth/react";

function App() {
  return (
    <AuthProvider>
      <Dashboard />
    </AuthProvider>
  );
}

function Dashboard() {
  const { user, isAuthenticated, login, logout } = useAuth();
  const canDelete = usePermission("delete:orders");

  return (
    <RequireAuth fallback={<LoginScreen />}>
      <p>Welcome, {user?.name}</p>
      {canDelete && <button>Delete</button>}
      <button onClick={logout}>Sign out</button>
    </RequireAuth>
  );
}

AuthProvider reads the persisted session after mount (SSR-safe) and stays in sync with setSession/clearSession calls anywhere in the app — including across browser tabs.

API

• Tokens — parseBearerToken, decodeJwt, isTokenExpired, getTokenExpiry
• Session — getSession, setSession, clearSession, onSessionChange (types: AuthSession, AuthUser, SessionOptions)
• RBAC — hasRole, hasAnyRole, hasPermission, can (type: RbacUser)
• React (/react) — AuthProvider, useAuth, RequireAuth, usePermission

License

MIT © GG Software