@startsimpli/auth 0.1.0

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @startsimpli/auth - Shared authentication package
+ *
+ * Provides JWT-based authentication for Next.js apps with Django backend
+ *
+ * NOTE: Server-only utilities (using next/headers) are available via '@startsimpli/auth/server'
+ * NOTE: Functional auth API (signInWithCredentials, authFetch, etc.) is available via '@startsimpli/auth/client'
+ */
+
+// Re-export client-safe code only
+export * from './types';
+export * from './utils';
+// Export client without AuthUser to avoid duplicate with types/AuthUser.
+// Consumers needing the functional AuthUser should import from '@startsimpli/auth/client'.
+export {
+  AuthClient,
+  AuthProvider,
+  useAuthContext,
+  useAuth,
+  usePermissions,
+  resolveAuthUrl,
+  getAccessToken,
+  setAccessToken,
+  signInWithCredentials,
+  registerAccount,
+  requestPasswordReset,
+  resetPassword,
+  verifyEmail,
+  resendVerification,
+  initiateGoogleOAuth,
+  completeGoogleOAuth,
+  refreshAccessToken,
+  getMe,
+  signOut,
+  authFetch,
+  hasPermission,
+  hasGroup,
+} from './client';
+export type { UseAuthReturn, UsePermissionsReturn } from './client';
+
+// DO NOT export './server' here - it uses next/headers and must be imported explicitly via '@startsimpli/auth/server'

package/src/server/guards.ts

@@ -0,0 +1,113 @@
+/**
+ * Auth guards for API routes
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import type { CompanyRole } from '../types';
+import { hasRolePermission } from '../types';
+import { getRequestToken } from './middleware';
+
+/**
+ * Auth guard result
+ */
+export interface GuardResult {
+  authorized: boolean;
+  response?: NextResponse;
+  token?: string;
+}
+
+/**
+ * Require authentication for API route
+ */
+export async function requireAuthGuard(
+  request: NextRequest
+): Promise<GuardResult> {
+  const token = getRequestToken(request);
+
+  if (!token) {
+    return {
+      authorized: false,
+      response: NextResponse.json(
+        { error: 'Unauthorized' },
+        { status: 401 }
+      ),
+    };
+  }
+
+  return {
+    authorized: true,
+    token,
+  };
+}
+
+/**
+ * Require specific role for API route
+ */
+export async function requireRoleGuard(
+  request: NextRequest,
+  requiredRole: CompanyRole,
+  getUserRole: () => Promise<CompanyRole | null>
+): Promise<GuardResult> {
+  const authResult = await requireAuthGuard(request);
+
+  if (!authResult.authorized) {
+    return authResult;
+  }
+
+  const userRole = await getUserRole();
+
+  if (!userRole || !hasRolePermission(userRole, requiredRole)) {
+    return {
+      authorized: false,
+      response: NextResponse.json(
+        { error: 'Forbidden' },
+        { status: 403 }
+      ),
+    };
+  }
+
+  return {
+    authorized: true,
+    token: authResult.token,
+  };
+}
+
+/**
+ * Higher-order function to wrap API route with auth guard
+ */
+export function withAuth<T = any>(
+  handler: (request: NextRequest, token: string) => Promise<NextResponse<T>>
+) {
+  return async (request: NextRequest): Promise<NextResponse> => {
+    const guardResult = await requireAuthGuard(request);
+
+    if (!guardResult.authorized) {
+      return guardResult.response!;
+    }
+
+    return handler(request, guardResult.token!);
+  };
+}
+
+/**
+ * Higher-order function to wrap API route with role guard
+ */
+export function withRole<T = any>(
+  requiredRole: CompanyRole,
+  getUserRole: () => Promise<CompanyRole | null>,
+  handler: (request: NextRequest, token: string) => Promise<NextResponse<T>>
+) {
+  return async (request: NextRequest): Promise<NextResponse> => {
+    const guardResult = await requireRoleGuard(
+      request,
+      requiredRole,
+      getUserRole
+    );
+
+    if (!guardResult.authorized) {
+      return guardResult.response!;
+    }
+
+    return handler(request, guardResult.token!);
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,20 @@
+export {
+  getServerSession,
+  validateSession,
+  requireAuth,
+  refreshServerToken,
+} from './session';
+export {
+  createAuthMiddleware,
+  hasValidToken,
+  getRequestToken,
+  getTokenFromRequest,
+  type AuthMiddlewareConfig,
+} from './middleware';
+export {
+  requireAuthGuard,
+  requireRoleGuard,
+  withAuth,
+  withRole,
+  type GuardResult,
+} from './guards';

package/src/server/middleware.ts

@@ -0,0 +1,106 @@
+/**
+ * Next.js middleware helpers for authentication
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { isTokenExpired } from '../utils';
+
+export interface AuthMiddlewareConfig {
+  apiBaseUrl: string;
+  publicPaths?: string[];
+  loginPath?: string;
+}
+
+/**
+ * Create auth middleware for Next.js
+ */
+export function createAuthMiddleware(config: AuthMiddlewareConfig) {
+  const {
+    apiBaseUrl,
+    publicPaths = ['/login', '/register', '/forgot-password'],
+    loginPath = '/login',
+  } = config;
+
+  return async function authMiddleware(request: NextRequest) {
+    const { pathname } = request.nextUrl;
+
+    const isPublicPath = publicPaths.some((path) =>
+      pathname.startsWith(path)
+    );
+
+    if (isPublicPath) {
+      return NextResponse.next();
+    }
+
+    const accessToken = request.cookies.get('access_token')?.value;
+
+    if (!accessToken || isTokenExpired(accessToken)) {
+      const url = request.nextUrl.clone();
+      url.pathname = loginPath;
+      url.searchParams.set('from', pathname);
+      return NextResponse.redirect(url);
+    }
+
+    return NextResponse.next();
+  };
+}
+
+/**
+ * Check if request has valid auth token
+ */
+export function hasValidToken(request: NextRequest): boolean {
+  const accessToken = request.cookies.get('access_token')?.value;
+
+  if (!accessToken) {
+    return false;
+  }
+
+  return !isTokenExpired(accessToken);
+}
+
+/**
+ * Get access token from request
+ */
+export function getRequestToken(request: NextRequest): string | null {
+  const accessToken = request.cookies.get('access_token')?.value;
+
+  if (!accessToken) {
+    return null;
+  }
+
+  if (isTokenExpired(accessToken)) {
+    return null;
+  }
+
+  return accessToken;
+}
+
+/**
+ * Extract bearer token from a standard Request (Authorization header or access_token cookie).
+ * Framework-agnostic — works with any Request-compatible object (Next.js, Node, edge runtimes).
+ * Returns the raw token string without expiry validation.
+ */
+export function getTokenFromRequest(req: Request): string | undefined {
+  // Authorization: Bearer <token>
+  const authHeader = req.headers.get('authorization');
+  if (authHeader?.startsWith('Bearer ')) {
+    const token = authHeader.slice(7).trim();
+    if (token) return token;
+  }
+
+  // Fallback: access_token cookie (parsed from Cookie header)
+  const cookieHeader = req.headers.get('cookie');
+  if (cookieHeader) {
+    const match = cookieHeader
+      .split(';')
+      .map((part) => part.trim())
+      .find((part) => part.startsWith('access_token='));
+
+    if (match) {
+      const token = match.slice('access_token='.length).trim();
+      if (token) return token;
+    }
+  }
+
+  return undefined;
+}

package/src/server/session.ts

@@ -0,0 +1,115 @@
+/**
+ * Server-side session validation
+ * For Next.js API routes and server components
+ */
+
+import { cookies } from 'next/headers';
+import type { Session, AuthUser, TokenPayload } from '../types';
+import { decodeToken, isTokenExpired } from '../utils';
+
+/**
+ * Get session from server-side cookies and headers
+ */
+export async function getServerSession(
+  apiBaseUrl: string
+): Promise<Session | null> {
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get('access_token')?.value;
+
+  if (!accessToken) {
+    return null;
+  }
+
+  if (isTokenExpired(accessToken)) {
+    return null;
+  }
+
+  try {
+    const user = await fetchUser(apiBaseUrl, accessToken);
+    const payload = decodeToken(accessToken);
+
+    if (!payload) {
+      return null;
+    }
+
+    return {
+      user,
+      accessToken,
+      expiresAt: payload.exp * 1000,
+    };
+  } catch (error) {
+    console.error('Failed to get server session:', error);
+    return null;
+  }
+}
+
+/**
+ * Fetch user data from Django backend
+ */
+async function fetchUser(
+  apiBaseUrl: string,
+  accessToken: string
+): Promise<AuthUser> {
+  const response = await fetch(`${apiBaseUrl}/api/v1/auth/me/`, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+    cache: 'no-store',
+  });
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch user');
+  }
+
+  return response.json();
+}
+
+/**
+ * Validate session and return user or null
+ */
+export async function validateSession(
+  apiBaseUrl: string
+): Promise<AuthUser | null> {
+  const session = await getServerSession(apiBaseUrl);
+  return session?.user || null;
+}
+
+/**
+ * Require authenticated session (throws if not authenticated)
+ */
+export async function requireAuth(apiBaseUrl: string): Promise<Session> {
+  const session = await getServerSession(apiBaseUrl);
+
+  if (!session) {
+    throw new Error('Unauthorized');
+  }
+
+  return session;
+}
+
+/**
+ * Refresh access token using refresh token cookie
+ */
+export async function refreshServerToken(
+  apiBaseUrl: string
+): Promise<string | null> {
+  try {
+    const response = await fetch(`${apiBaseUrl}/api/v1/auth/token/refresh/`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      credentials: 'include',
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = await response.json();
+    return data.access;
+  } catch (error) {
+    console.error('Token refresh failed:', error);
+    return null;
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,142 @@
+/**
+ * Authentication types for StartSimpli apps
+ */
+
+/**
+ * Generic token pair (access + optional refresh)
+ */
+export interface TokenPair {
+  access: string;
+  refresh?: string;
+}
+
+/**
+ * Generic decoded JWT payload — framework and backend agnostic
+ */
+export interface DecodedToken {
+  sub?: string;
+  email?: string;
+  exp?: number;
+  iat?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Generic auth session — framework agnostic
+ */
+export interface AuthSession {
+  user: {
+    id: string;
+    email: string;
+    [key: string]: unknown;
+  };
+  accessToken: string;
+  refreshToken?: string;
+}
+
+/**
+ * User profile from Django backend
+ */
+export interface AuthUser {
+  id: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  isEmailVerified: boolean;
+  createdAt: string;
+  updatedAt: string;
+  // Company/team context (if applicable)
+  companies?: Array<{
+    id: string;
+    name: string;
+    role: 'owner' | 'admin' | 'member' | 'viewer';
+  }>;
+  currentCompanyId?: string;
+}
+
+/**
+ * JWT token payload structure
+ */
+export interface TokenPayload {
+  token_type: 'access';
+  exp: number;
+  iat: number;
+  jti: string;
+  user_id: string;
+}
+
+/**
+ * Session data stored in client
+ */
+export interface Session {
+  user: AuthUser;
+  accessToken: string;
+  expiresAt: number;
+}
+
+/**
+ * Login response from Django backend
+ */
+export interface LoginResponse {
+  access: string;
+  user: AuthUser;
+}
+
+/**
+ * Token refresh response
+ */
+export interface RefreshResponse {
+  access: string;
+}
+
+/**
+ * Permission check result
+ */
+export interface PermissionCheck {
+  hasPermission: boolean;
+  reason?: string;
+}
+
+/**
+ * Auth configuration options
+ */
+export interface AuthConfig {
+  apiBaseUrl: string;
+  tokenRefreshInterval?: number; // milliseconds, default 4 minutes
+  onSessionExpired?: () => void;
+  onUnauthorized?: () => void;
+}
+
+/**
+ * Auth state for React context
+ */
+export interface AuthState {
+  session: Session | null;
+  isLoading: boolean;
+  isAuthenticated: boolean;
+}
+
+/**
+ * Company role hierarchy
+ */
+export type CompanyRole = 'owner' | 'admin' | 'member' | 'viewer';
+
+/**
+ * Role hierarchy map (higher number = more permissions)
+ */
+export const ROLE_HIERARCHY: Record<CompanyRole, number> = {
+  owner: 4,
+  admin: 3,
+  member: 2,
+  viewer: 1,
+};
+
+/**
+ * Check if role has sufficient permissions
+ */
+export function hasRolePermission(
+  userRole: CompanyRole,
+  requiredRole: CompanyRole
+): boolean {
+  return ROLE_HIERARCHY[userRole] >= ROLE_HIERARCHY[requiredRole];
+}

package/src/utils/cookies.ts

@@ -0,0 +1,86 @@
+/**
+ * Cookie utilities for client-side access
+ */
+
+/**
+ * Get cookie value by name
+ */
+export function getCookie(name: string): string | null {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+
+  const value = `; ${document.cookie}`;
+  const parts = value.split(`; ${name}=`);
+
+  if (parts.length === 2) {
+    return parts.pop()?.split(';').shift() || null;
+  }
+
+  return null;
+}
+
+/**
+ * Set cookie with options
+ */
+export function setCookie(
+  name: string,
+  value: string,
+  options: {
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+  } = {}
+): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  const {
+    maxAge,
+    path = '/',
+    domain,
+    secure = true,
+    sameSite = 'lax',
+  } = options;
+
+  let cookie = `${name}=${value}`;
+
+  if (maxAge) {
+    cookie += `; Max-Age=${maxAge}`;
+  }
+
+  cookie += `; Path=${path}`;
+
+  if (domain) {
+    cookie += `; Domain=${domain}`;
+  }
+
+  if (secure) {
+    cookie += '; Secure';
+  }
+
+  cookie += `; SameSite=${sameSite}`;
+
+  document.cookie = cookie;
+}
+
+/**
+ * Get the Django CSRF token from cookies
+ */
+export function getCsrfToken(): string | null {
+  return getCookie('csrftoken');
+}
+
+/**
+ * Delete cookie by name
+ */
+export function deleteCookie(name: string, path: string = '/'): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  document.cookie = `${name}=; Path=${path}; Expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './token';
+export * from './cookies';
+export * from '../validation';

package/src/utils/token.ts

@@ -0,0 +1,89 @@
+/**
+ * JWT token utilities
+ */
+
+import type { TokenPayload, DecodedToken } from '../types';
+
+/**
+ * Decode JWT token payload (does NOT verify signature)
+ */
+export function decodeToken(token: string): TokenPayload | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const payload = parts[1];
+    const decoded = JSON.parse(atob(payload));
+    return decoded as TokenPayload;
+  } catch (error) {
+    console.error('Failed to decode token:', error);
+    return null;
+  }
+}
+
+/**
+ * Check if token is expired
+ */
+export function isTokenExpired(token: string): boolean {
+  const payload = decodeToken(token);
+  if (!payload) {
+    return true;
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  return payload.exp <= now;
+}
+
+/**
+ * Get token expiration time in milliseconds
+ */
+export function getTokenExpiresAt(token: string): number | null {
+  const payload = decodeToken(token);
+  if (!payload) {
+    return null;
+  }
+
+  return payload.exp * 1000;
+}
+
+/**
+ * Get raw JWT payload as a generic record — framework and backend agnostic.
+ * Does NOT verify the signature; use only for reading claims client-side.
+ */
+export function getTokenPayload(token: string): DecodedToken | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const payload = parts[1];
+    const decoded = JSON.parse(atob(payload));
+
+    if (typeof decoded !== 'object' || decoded === null) {
+      return null;
+    }
+
+    return decoded as DecodedToken;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if token needs refresh (expires in less than 5 minutes)
+ */
+export function shouldRefreshToken(token: string): boolean {
+  const expiresAt = getTokenExpiresAt(token);
+  if (!expiresAt) {
+    return true;
+  }
+
+  const now = Date.now();
+  const timeUntilExpiry = expiresAt - now;
+  const FIVE_MINUTES = 5 * 60 * 1000;
+
+  return timeUntilExpiry < FIVE_MINUTES;
+}