@cyber-eco/auth¶

Authentication, single sign-on, permissions, JWT management, rate limiting, and error recovery for the CyberEco ecosystem. This package provides dual entry points to separate client-safe code from server-only dependencies.

Installation¶

npmPeer Dependencies

npm install @cyber-eco/auth

Peer	Version	Required
`firebase`	`>=11.0.0`	Yes
`react`	`>=18.0.0`	Optional -- only for hooks/components
`jsonwebtoken`	`>=9.0.0`	Optional -- only for server entry point

Runtime Dependencies

This package depends on @cyber-eco/types for interfaces and zod for runtime validation schemas.

Dual Entry Points¶

This package exposes two separate entry points to prevent server-only code from leaking into client bundles.

Client (@cyber-eco/auth)Server (@cyber-eco/auth/server)

import { useAuth, useHubAuth, AuthProvider, SessionSync } from '@cyber-eco/auth';

Safe for browsers, React components, and client-side code. No Node.js dependencies.

import { jwtService, sessionService, twoFactorService } from '@cyber-eco/auth/server';

Requires Node.js. Uses jsonwebtoken and other server-only modules. Never import this in client code.

Do Not Mix Entry Points

Importing @cyber-eco/auth/server in client-side code will crash the browser due to Node.js-only dependencies (jsonwebtoken, crypto). Always use the bare @cyber-eco/auth import for client code.

Client Features¶

Authentication Context and Hooks¶

AuthProvider and useAuth¶

The core authentication context and hook for managing Firebase Auth state in React applications.

import { AuthProvider, useAuth } from '@cyber-eco/auth';
import type { AuthConfig } from '@cyber-eco/auth';

const config: AuthConfig = {
  // ... Firebase and auth configuration
};

function App() {
  return (
    <AuthProvider config={config}>
      <MyComponent />
    </AuthProvider>
  );
}

function MyComponent() {
  const { user, loading, signIn, signOut } = useAuth();

  if (loading) return <p>Loading...</p>;
  if (!user) return <button onClick={() => signIn('email', 'pass')}>Sign In</button>;

  return <p>Welcome, {user.email}</p>;
}

useHubAuth¶

Hub-specific auth hook with extended user profile and app permissions.

import { useHubAuth } from '@cyber-eco/auth';
import type { HubUser, HubAuthState } from '@cyber-eco/auth';

function DashboardPage() {
  const { user, isAuthenticated, permissions } = useHubAuth();
  // user: HubUser | null
  // isAuthenticated: boolean
  // permissions: user's app-level permissions
}

Permission Hooks¶

import { usePermissions, withPermissions } from '@cyber-eco/auth';
import type { PermissionCheck, AppPermission } from '@cyber-eco/auth';

function AdminPanel() {
  const { hasPermission, hasMinimumRole } = usePermissions();

  if (!hasMinimumRole('admin')) {
    return <p>Access denied</p>;
  }

  return <div>Admin content</div>;
}

// Or use the HOC
const ProtectedAdminPanel = withPermissions(AdminPanel, {
  requiredRole: 'admin',
});

Session Synchronization¶

SessionSync¶

Synchronizes authentication state across tabs using BroadcastChannel.

import { SessionSync, useSessionSync, useSharedAuthState, clearSharedAuthState } from '@cyber-eco/auth';

function App() {
  return (
    <SessionSync>
      <MyApp />
    </SessionSync>
  );
}

function MyComponent() {
  const { isShared, sharedState } = useSharedAuthState();
  // Auth state is now synced across all open tabs
}

CrossOriginAuth¶

Enables authentication sharing across CyberEco subdomains.

import {
  CrossOriginAuth,
  useCrossOriginAuth,
  getCrossOriginAuthState,
  clearCrossOriginAuthState,
  waitForSharedAuth,
} from '@cyber-eco/auth';

function App() {
  return (
    <CrossOriginAuth>
      <MyApp />
    </CrossOriginAuth>
  );
}

Error Recovery¶

Comprehensive error handling with retry logic, circuit breakers, and offline support.

import {
  ErrorRecoveryBoundary,
  DefaultErrorFallback,
  RecoveryStrategy,
  retryWithBackoff,
  CircuitBreaker,
  useErrorBoundary,
  useOfflineRecovery,
  useAutoSave,
  handleFirebaseError,
} from '@cyber-eco/auth';

// Wrap components in error boundary with automatic recovery
function App() {
  return (
    <ErrorRecoveryBoundary fallback={DefaultErrorFallback}>
      <MyApp />
    </ErrorRecoveryBoundary>
  );
}

// Retry operations with exponential backoff
const result = await retryWithBackoff(
  () => fetchData(),
  { maxRetries: 3, baseDelay: 1000 }
);

// Circuit breaker for flaky services
const breaker = new CircuitBreaker({ threshold: 5, resetTimeout: 30000 });
const data = await breaker.execute(() => externalApiCall());

Validation Schemas¶

Zod schemas for validating auth-related data at runtime.

import { /* validation utilities */ } from '@cyber-eco/auth';

// Validation schemas are used internally and available for
// custom validation in your application code

Rate Limiting¶

Client-side rate limiting for auth operations.

import {
  RateLimiter,
  InMemoryRateLimitStore,
  authRateLimiter,
  apiRateLimiter,
  exportRateLimiter,
} from '@cyber-eco/auth';
import type { RateLimitConfig, RateLimitStore, RateLimitResult } from '@cyber-eco/auth';

// Pre-configured rate limiters
const result = await authRateLimiter.check('user-123');
if (!result.allowed) {
  console.log(`Rate limited. Retry after ${result.retryAfter}ms`);
}

// Custom rate limiter
const limiter = new RateLimiter({
  maxRequests: 10,
  windowMs: 60_000,  // 10 requests per minute
  store: new InMemoryRateLimitStore(),
});

Additional Client Utilities¶

// Logging
import { /* logger utilities */ } from '@cyber-eco/auth';

// Performance monitoring
import { /* performance utilities */ } from '@cyber-eco/auth';

// Auth token management
import { /* authTokenService */ } from '@cyber-eco/auth';

// Cache service
import { /* cacheService */ } from '@cyber-eco/auth';

// SSO (client-side)
import { /* ssoService */ } from '@cyber-eco/auth';

// Shared auth state management
import { /* shared-auth-state */ } from '@cyber-eco/auth';

// Permission middleware (for route protection)
import { /* middleware utilities */ } from '@cyber-eco/auth';

Server Features¶

Server-Only

All exports from @cyber-eco/auth/server require Node.js and must not be imported in client-side code.

JWT Service¶

import { jwtService } from '@cyber-eco/auth/server';
import type { TokenPayload, DecodedToken, TokenPair } from '@cyber-eco/auth/server';

// Generate a token pair (access + refresh)
const tokens: TokenPair = jwtService.generateTokenPair({
  userId: 'user-123',
  email: 'user@example.com',
  roles: ['admin'],
});

// Verify and decode a token
const decoded: DecodedToken = jwtService.verifyToken(tokens.accessToken);

// Refresh an expired access token
const newTokens = jwtService.refreshTokenPair(tokens.refreshToken);

Session Service¶

import { sessionService, SessionService } from '@cyber-eco/auth/server';
import type { DeviceInfo, GeolocationData, Session, SessionStore } from '@cyber-eco/auth/server';

// Create a new session
const session = await sessionService.createSession({
  userId: 'user-123',
  deviceInfo: {
    userAgent: req.headers['user-agent'],
    ip: req.ip,
  },
});

// Validate an existing session
const isValid = await sessionService.validateSession(sessionId);

// List active sessions for a user
const sessions = await sessionService.getUserSessions('user-123');

// Revoke a session
await sessionService.revokeSession(sessionId);

Two-Factor Authentication¶

import { twoFactorService } from '@cyber-eco/auth/server';
import type { TwoFactorSecret, TwoFactorProvider } from '@cyber-eco/auth/server';

// Generate a 2FA secret
const secret: TwoFactorSecret = twoFactorService.generateSecret('user@example.com');

// Verify a TOTP code
const isValid = twoFactorService.verifyCode(secret, '123456');

import { gdprService, GDPRService, ConsentType } from '@cyber-eco/auth/server';
import type { ConsentRecord, PrivacyPreferences, DataProcessingActivity, GDPRStore } from '@cyber-eco/auth/server';

// Record user consent
await gdprService.recordConsent({
  userId: 'user-123',
  type: ConsentType.DataProcessing,
  granted: true,
});

// Get user's privacy preferences
const prefs = await gdprService.getPrivacyPreferences('user-123');

// Export user data (GDPR right of access)
const userData = await gdprService.exportUserData('user-123');

SSO Service (Server)¶

import { ssoService } from '@cyber-eco/auth/server';
import type { SSOToken, SSOClaims, SSOSessionInfo } from '@cyber-eco/auth/server';

// Generate SSO token for cross-app authentication
const ssoToken = ssoService.generateToken({
  userId: 'user-123',
  sourceApp: 'hub',
  targetApp: 'justsplit',
});

// Validate an SSO token
const claims = ssoService.validateToken(ssoToken);

Full Example: Hub Auth Integration¶

Here is how the Hub app wires up authentication:

// apps/hub/src/lib/firebase.ts
import { initializeFirebase, getHubFirestore } from '@cyber-eco/firebase';

initializeFirebase({
  hubConfig: {
    apiKey: import.meta.env.PUBLIC_FIREBASE_API_KEY,
    authDomain: import.meta.env.PUBLIC_FIREBASE_AUTH_DOMAIN,
    projectId: import.meta.env.PUBLIC_FIREBASE_PROJECT_ID,
    storageBucket: import.meta.env.PUBLIC_FIREBASE_STORAGE_BUCKET,
    messagingSenderId: import.meta.env.PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
    appId: import.meta.env.PUBLIC_FIREBASE_APP_ID,
  },
  useEmulators: import.meta.env.DEV,
  emulatorPorts: { auth: 9099, firestore: 8080 },
});

// apps/hub/src/providers/HubAuthContext.tsx
import { useAuth } from '@cyber-eco/auth';

export function HubAuthProvider({ children }) {
  return (
    <AuthProvider config={config}>
      <SessionSync>
        {children}
      </SessionSync>
    </AuthProvider>
  );
}

// apps/hub/src/pages/api/auth/generate-token.ts (API route)
import { jwtService } from '@cyber-eco/auth/server';

export async function POST({ request }) {
  const { uid, email } = await request.json();
  const tokens = jwtService.generateTokenPair({ userId: uid, email });
  return new Response(JSON.stringify(tokens));
}

Exports Summary¶

Client Entry Point (`@cyber-eco/auth`)¶

Category	Exports
Context	`AuthContext`, `AuthProvider`, `useAuth`, `createAuthContext`, `sanitizeForFirestore`
Hooks	`useHubAuth`, `usePermissions`, `withPermissions`
Session	`SessionSync`, `useSessionSync`, `useSharedAuthState`, `clearSharedAuthState`
Cross-origin	`CrossOriginAuth`, `useCrossOriginAuth`, `getCrossOriginAuthState`, `clearCrossOriginAuthState`, `waitForSharedAuth`
Error recovery	`ErrorRecoveryBoundary`, `DefaultErrorFallback`, `RecoveryStrategy`, `retryWithBackoff`, `CircuitBreaker`, `useErrorBoundary`, `useOfflineRecovery`, `useAutoSave`, `handleFirebaseError`
Rate limiting	`RateLimiter`, `InMemoryRateLimitStore`, `authRateLimiter`, `apiRateLimiter`, `exportRateLimiter`
Utils	Logger, errors, validation, performance, auth token service, cache service, SSO service
Permissions	Role hierarchy, conditional permissions, middleware

Server Entry Point (`@cyber-eco/auth/server`)¶

Category	Exports
JWT	`jwtService`, `TokenPayload`, `DecodedToken`, `TokenPair`
Sessions	`sessionService`, `SessionService`, `DeviceInfo`, `GeolocationData`, `Session`, `SessionStore`
2FA	`twoFactorService`, `TwoFactorSecret`, `TwoFactorProvider`
GDPR	`gdprService`, `GDPRService`, `ConsentType`, `ConsentRecord`, `PrivacyPreferences`, `DataProcessingActivity`, `GDPRStore`
SSO	`ssoService`, `SSOToken`, `SSOClaims`, `SSOSessionInfo`