@gg-software/auth

pnpm add @gg-software/auth

import { decodeJwt, getSession, can } from '@gg-software/auth';
import { AuthProvider, useAuth } from '@gg-software/auth/react'; // optional, needs react

parseBearerToken('Bearer abc123'); // "abc123"
parseBearerToken('Basic abc123'); // null
parseBearerToken(undefined); // null

decodeJwt(token); // { sub: "42", exp: 1767225600, ... }
decodeJwt('not-a-jwt'); // null
decodeJwt<{ sub: string }>(token)?.sub; // typed access

type JwtPayload = {
    iss?: string;
    sub?: string;
    aud?: string | string[];
    exp?: number; // seconds since epoch
    nbf?: number;
    iat?: number;
    jti?: string;
    [claim: string]: unknown;
};

isTokenExpired(freshToken); // false
isTokenExpired(oldToken); // true
isTokenExpired(oldToken, 60); // false within 60s of expiry (clock-skew leeway)
isTokenExpired(null); // true

getTokenExpiry(token); // Date | null

type AuthSession = {
    token?: string;
    user?: AuthUser;
    [key: string]: unknown; // extend freely
};
 
type AuthUser = {
    id?: string | number;
    name?: string;
    email?: string;
    roles?: string[];
    permissions?: string[];
    [key: string]: unknown;
};
 
type SessionOptions = {
    key?: string; // storage key (default "gg-session")
    storage?: Storage; // storage backend (default window.localStorage)
};

const session = getSession();
if (session?.token) fetchWithAuth(session.token);
 
// custom key / sessionStorage
getSession({ key: 'admin-session', storage: sessionStorage });

setSession({ token, user: { id: 42, name: 'Ada', roles: ['admin'] } });

clearSession();

const stop = onSessionChange((session) => {
    if (!session) redirectToLogin();
});
// later
stop();

hasRole(user, 'admin'); // user.roles includes "admin"
hasRole(null, 'admin'); // false

hasAnyRole(user, ['admin', 'editor']); // at least one of them

// user.permissions = ['read:*', 'write:orders']
hasPermission(user, 'read:customers'); // true  (read:*)
hasPermission(user, 'write:orders'); // true  (exact)
hasPermission(user, 'delete:orders'); // false

can(user, 'delete', 'orders'); // checks "delete:orders"

import { AuthProvider } from '@gg-software/auth/react';
 
<AuthProvider>
    <App />
</AuthProvider>;

import { useAuth } from '@gg-software/auth/react';
 
function UserMenu() {
    const { user, isAuthenticated, login, logout } = useAuth();
    if (!isAuthenticated) return <LoginButton onDone={(session) => login(session)} />;
    return <button onClick={logout}>Sign out {user?.name}</button>;
}

import { RequireAuth } from '@gg-software/auth/react';
 
<RequireAuth fallback={<LoginPage />}>
    <AdminArea />
</RequireAuth>;

import { usePermission } from '@gg-software/auth/react';
 
function DeleteButton() {
    const canDelete = usePermission('delete:orders');
    return canDelete ? <Button danger>Delete</Button> : null;
}