my-ssap 1.0.0

package/README.md

@@ -0,0 +1,269 @@
+A lightweight, zero-dependency utility package for simple personal full-stack projects. It provides a clean API to manage Express server-side sessions and React frontend protected routes without complex configurations.
+
+## Installation
+
+Ensure you have your peer dependencies installed in your projects:
+
+```bash
+npm install ssap
+```
+
+---
+
+## 🛠️ Backend Usage (Express)
+
+Import server-side helpers from `ssap/backend`.
+
+```javascript
+import express from 'express';
+import { initSession, requireAuth } from 'ssap/backend';
+
+const app = express();
+app.use(express.json());
+
+// 1. Initialize session middleware with a secret key
+app.use(initSession('your-secure-dev-secret-key', false)); // Set second param to true in production (HTTPS)
+
+// 2. Login Route (Set session details on successful authentication)
+app.post('/api/login', (req, res) => {
+  const { username, password } = req.body;
+  
+  // Validate credentials here...
+  if (username === 'admin' && password === 'password') {
+    req.session.userId = 1;
+    req.session.username = username;
+    return res.json({ authenticated: true, message: 'Logged in!' });
+  }
+  
+  return res.status(401).json({ authenticated: false, error: 'Invalid credentials' });
+});
+
+// 3. Auth Check Route (Used by React to verify active sessions)
+app.get('/api/auth-check', (req, res) => {
+  if (req.session && req.session.userId) {
+    return res.json({ authenticated: true, username: req.session.username });
+  }
+  return res.status(401).json({ authenticated: false });
+});
+
+// 4. Logout Route
+app.post('/api/logout', (req, res) => {
+  req.session.destroy((err) => {
+    if (err) return res.status(500).json({ message: 'Could not log out' });
+    res.clearCookie('connect.sid');
+    return res.json({ authenticated: false });
+  });
+});
+
+// 5. Protect sensitive endpoints using the middleware
+app.get('/api/dashboard-data', requireAuth, (req, res) => {
+  res.json({ message: 'Welcome to your private dashboard data!' });
+});
+
+```
+
+---
+
+## 💻 Frontend Usage (React + React Router)
+
+Import frontend context and route wrappers from `ssap/frontend`.
+
+### 1. Setup Your App Routing (`App.jsx`)
+
+Wrap your routing setup inside `AuthProvider` and secure internal routes using the `<ProtectedRoute />` component.
+
+```jsx
+import React from 'react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { AuthProvider, ProtectedRoute } from 'ssap/frontend';
+
+import Login from './pages/Login';
+import Dashboard from './pages/Dashboard';
+
+export default function App() {
+  return (
+    <AuthProvider authCheckUrl="/api/auth-check">
+      <BrowserRouter>
+        <Routes>
+          {/* Public Route */}
+          <Route path="/login" element={<Login />} />
+          
+          {/* Protected Routes Block */}
+          <Route element={<ProtectedRoute redirectTo="/login" />}>
+            <Route path="/dashboard" element={<Dashboard />} />
+          </Route>
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+
+```
+
+### 2. Consuming Auth State in Components (`Dashboard.jsx`)
+
+Use the `useAuth` hook to access the logged-in user details or display loading states while the initial check finishes.
+
+```jsx
+import React from 'react';
+import { useAuth } from 'ssap/frontend';
+
+export default function Dashboard() {
+  const { user, loading } = useAuth();
+
+  if (loading) return <div>Checking auth state...</div>;
+
+  return (
+    <div>
+      <h1>Welcome, {user?.username}!</h1>
+      <p>This page is fully protected from unauthenticated guests.</p>
+    </div>
+  );
+}
+
+```
+
+---
+
+## API Reference
+
+### Backend Exports (`ssap/backend`)
+
+* `initSession(secretKey, isProduction)`: Configures cookie-backed express sessions. Disables `secure` flag on localhost when `isProduction` is false.
+* `requireAuth(req, res, next)`: Express middleware that blocks incoming requests if `req.session.userId` is missing. Returns a `401 Unauthorized` response.
+
+### Frontend Exports (`ssap/frontend`)
+
+* `<AuthProvider authCheckUrl="/api/auth-check">`: Handles checking current cookie status on boot. Caches context values globally.
+* `useAuth()`: Access global hook context properties: `{ user, setUser, loading }`.
+* `<ProtectedRoute redirectTo="/login" />`: Route-level element guarding children paths using `react-router-dom` standard `<Outlet />`.
+
+---
+
+## 🛠️ Backend Usage (Express)
+
+Import server-side helpers from `ssap/backend`.
+
+```javascript
+import express from 'express';
+import { initSession, requireAuth } from 'ssap/backend';
+
+const app = express();
+app.use(express.json());
+
+// 1. Initialize session middleware with a secret key
+app.use(initSession('your-secure-dev-secret-key', false)); // Set second param to true in production (HTTPS)
+
+// 2. Login Route (Set session details on successful authentication)
+app.post('/api/login', (req, res) => {
+  const { username, password } = req.body;
+  
+  // Validate credentials here...
+  if (username === 'admin' && password === 'password') {
+    req.session.userId = 1;
+    req.session.username = username;
+    return res.json({ authenticated: true, message: 'Logged in!' });
+  }
+  
+  return res.status(401).json({ authenticated: false, error: 'Invalid credentials' });
+});
+
+// 3. Auth Check Route (Used by React to verify active sessions)
+app.get('/api/auth-check', (req, res) => {
+  if (req.session && req.session.userId) {
+    return res.json({ authenticated: true, username: req.session.username });
+  }
+  return res.status(401).json({ authenticated: false });
+});
+
+// 4. Logout Route
+app.post('/api/logout', (req, res) => {
+  req.session.destroy((err) => {
+    if (err) return res.status(500).json({ message: 'Could not log out' });
+    res.clearCookie('connect.sid');
+    return res.json({ authenticated: false });
+  });
+});
+
+// 5. Protect sensitive endpoints using the middleware
+app.get('/api/dashboard-data', requireAuth, (req, res) => {
+  res.json({ message: 'Welcome to your private dashboard data!' });
+});
+
+```
+
+---
+
+## 💻 Frontend Usage (React + React Router)
+
+Import frontend context and route wrappers from `ssap/frontend`.
+
+### 1. Setup Your App Routing (`App.jsx`)
+
+Wrap your routing setup inside `AuthProvider` and secure internal routes using the `<ProtectedRoute />` component.
+
+```jsx
+import React from 'react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { AuthProvider, ProtectedRoute } from 'ssap/frontend';
+
+import Login from './pages/Login';
+import Dashboard from './pages/Dashboard';
+
+export default function App() {
+  return (
+    <AuthProvider authCheckUrl="/api/auth-check">
+      <BrowserRouter>
+        <Routes>
+          {/* Public Route */}
+          <Route path="/login" element={<Login />} />
+          
+          {/* Protected Routes Block */}
+          <Route element={<ProtectedRoute redirectTo="/login" />}>
+            <Route path="/dashboard" element={<Dashboard />} />
+          </Route>
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+
+```
+
+### 2. Consuming Auth State in Components (`Dashboard.jsx`)
+
+Use the `useAuth` hook to access the logged-in user details or display loading states while the initial check finishes.
+
+```jsx
+import React from 'react';
+import { useAuth } from 'ssap/frontend';
+
+export default function Dashboard() {
+  const { user, loading } = useAuth();
+
+  if (loading) return <div>Checking auth state...</div>;
+
+  return (
+    <div>
+      <h1>Welcome, {user?.username}!</h1>
+      <p>This page is fully protected from unauthenticated guests.</p>
+    </div>
+  );
+}
+
+```
+
+---
+
+## API Reference
+
+### Backend Exports (`ssap/backend`)
+
+* `initSession(secretKey, isProduction)`: Configures cookie-backed express sessions. Disables `secure` flag on localhost when `isProduction` is false.
+* `requireAuth(req, res, next)`: Express middleware that blocks incoming requests if `req.session.userId` is missing. Returns a `401 Unauthorized` response.
+
+### Frontend Exports (`ssap/frontend`)
+
+* `<AuthProvider authCheckUrl="/api/auth-check">`: Handles checking current cookie status on boot. Caches context values globally.
+* `useAuth()`: Access global hook context properties: `{ user, setUser, loading }`.
+* `<ProtectedRoute redirectTo="/login" />`: Route-level element guarding children paths using `react-router-dom` standard `<Outlet />`.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "my-ssap",
+  "version": "1.0.0",
+  "description": "A Simple Session-based Authentication Package",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Rubayita",
+  "license": "ISC",
+  "type": "module",
+  "exports": {
+    "./backend": "./src/backend.js",
+    "./frontend": "./src/frontend.jsx"
+  },
+  "peerDependencies": {
+    "express-session": "^1.18.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
+  }
+}

package/src/backend.js

@@ -0,0 +1,19 @@
+import session from 'express-session';
+
+export function initSession(secretKey) {
+    return session({
+        secret: secretKey,
+        resave: false,
+        saveUninitialized: false,
+        cookie:{
+            maxAge: 1000 * 60 * 60 * 24
+        }
+    })
+}
+
+export function requireAuth(req, res, next) {
+    if (req.session && req.session.userID){
+        return next();
+    }
+    return res.status(401).json({ authenticated: false, Error: 'Unauthenticated' })
+}

package/src/frontend.jsx

@@ -0,0 +1,42 @@
+import React from 'react'
+import { Navigate, Outlet } from 'react-router-dom'
+
+const AuthContext = React.createContext(null)
+
+export function AuthProvider({ children, authCheckUrl = '/auth/auth-check' }){
+    const [ user, setUser ] = React.useState(null)
+    const [ loadiing, setLoading ] = React.useState(true)
+
+    React.useEffect(()=>{
+        fetch(authCheckUrl)
+            .then((res)=>res.json())
+            .then((data) => {
+                if (data.authenticated) {
+                    setUser(data)
+                }
+            })
+            .catch(() => setUser(null))
+            .finally(() => setLoading(false))
+    }, [authCheckUrl])
+
+    return (
+        <AuthContext.Provider value={{ user, setUser, loading }}>
+            {children}
+        </AuthContext.Provider>
+    )
+}
+
+export function useAuth() {
+    return React.useContext(AuthContext)
+}
+
+export function ProtectedRoute({
+    redirectTo = '/login'
+}){
+    const { user, loading } = useAuth();
+
+    if (loading) return <div>Loading authenticated...</div>
+    if (!user) return <Navigate to={redirectTo} replace />
+
+    return <Outlet />
+}