mbkauthe 4.1.4 → 4.2.0

package/docs/api.md

@@ -41,11 +41,15 @@ Authorization: Bearer <your_api_token>
 - **Stateless:** Validates against the `ApiTokens` table on every request.
 - **Expiration:** Tokens can have an optional expiration date.
 - **Permissions:** API tokens inherit the permissions of the user who created them.
+- **Scopes:** Tokens have a scope (`read-only` or `write`) that controls which HTTP methods are allowed:
+  - `read-only`: Only GET, HEAD, and OPTIONS requests (safe, read-only operations)
+  - `write`: All HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
 - **Usage Tracking:** The system updates the `LastUsed` timestamp on every successful request.
 
 **Errors:**
 - `401 Unauthorized` (Code 1005: `INVALID_AUTH_TOKEN`): Token is malformed or not found.
 - `401 Unauthorized` (Code 1006: `API_TOKEN_EXPIRED`): Token exists but has passed its expiration date.
+- `403 Forbidden` (Code 1007: `TOKEN_SCOPE_INSUFFICIENT`): Token scope doesn't allow this HTTP method.
 
 **Example Usage:**
 
@@ -424,6 +428,184 @@ fetch('/mbkauthe/api/logout', {
 
 ### Multi-Account Endpoints
 
+---
+
+#### Token Management Endpoints
+
+##### `POST /mbkauthe/api/token`
+
+Create a new API token for the authenticated user.
+
+**Rate Limit:** 10 requests per minute
+
+**Authentication:** Session required (cookie or Bearer token)
+
+**Request Body:**
+```json
+{
+  "name": "string (required, 1-255 chars, friendly name for the token)",
+  "expiresDays": "number (optional, 1-365, default 90)",
+  "scope": "string (optional, 'read-only' or 'write', default 'read-only')",
+  "allowedApps": "array (optional, app names or ['*'] for all apps)"
+}
+```
+
+**Token Scopes:**
+- `read-only`: Allows only read operations (GET, HEAD, OPTIONS methods)
+- `write`: Allows all operations (GET, POST, PUT, DELETE, PATCH, etc.)
+
+**Token Application Access:**
+- Omit `allowedApps`: Token inherits from user's allowed apps
+- `["app1", "app2"]`: Token restricted to specific apps (must be subset of user's apps for non-SuperAdmin)
+- `["*"]`: All user's apps (non-SuperAdmin) or all system apps (SuperAdmin only)
+- **SuperAdmin bypass**: SuperAdmin tokens work on any app regardless of `allowedApps` configuration
+
+**Success Response (201 Created):**
+```json
+{
+  "success": true,
+  "token": "mbk_7f83a92b1dc4e5a6f89b012c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
+  "tokenId": 42,
+  "prefix": "mbk_7f83a92",
+  "name": "My API Token",
+  "scope": "read-only",
+  "allowedApps": ["App1", "App2"],
+  "expiresAt": "2025-04-27T12:34:56.000Z",
+  "createdAt": "2025-01-27T12:34:56.000Z",
+  "message": "Token created successfully. Save it now - it won't be shown again."
+}
+```
+
+**Error Responses:**
+
+| Status Code | Error Code | Message |
+|------------|------------|---------|
+| 400 | MISSING_REQUIRED_FIELD | Token name is required (1-255 characters) |
+| 400 | MISSING_REQUIRED_FIELD | expiresDays must be between 1 and 365 |
+| 400 | MISSING_REQUIRED_FIELD | Invalid scope. Available scopes: read-only, write |
+| 400 | MISSING_REQUIRED_FIELD | allowedApps must be an array |
+| 401 | SESSION_NOT_FOUND | Not authenticated |
+| 403 | INSUFFICIENT_PERMISSIONS | Only SuperAdmin can create tokens with '*' (all apps) access |
+| 403 | INSUFFICIENT_PERMISSIONS | You don't have access to app 'X' |
+| 500 | INTERNAL_SERVER_ERROR | Internal Server Error |
+
+**Example Requests:**
+
+*Create a read-only token for specific apps:*
+```javascript
+const response = await fetch('/mbkauthe/api/token', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer mbk_existing_token...' // or use session cookie
+  },
+  body: JSON.stringify({
+    name: 'CI/CD Pipeline Token',
+    expiresDays: 30,
+    scope: 'read-only',
+    allowedApps: ['App1', 'App2']
+  })
+});
+```
+
+*Create a write token with inherited app access:*
+```javascript
+const response = await fetch('/mbkauthe/api/token', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    name: 'Admin API Token',
+    scope: 'write'
+    // allowedApps omitted - inherits from user
+  })
+});
+```
+
+---
+
+##### `GET /mbkauthe/api/tokens`
+
+List all API tokens for the authenticated user (token value not included).
+
+**Rate Limit:** 10 requests per minute
+
+**Authentication:** Session required (cookie or Bearer token)
+
+**Success Response (200 OK):**
+```json
+{
+  "success": true,
+  "tokens": [
+    {
+      "id": 42,
+      "name": "CI/CD Pipeline Token",
+      "prefix": "mbk_7f83a92",
+      "scope": "read-only",
+      "allowedApps": ["App1", "App2"],
+      "lastUsed": "2025-01-27T10:15:30.000Z",
+      "createdAt": "2025-01-27T12:34:56.000Z",
+      "expiresAt": "2025-04-27T12:34:56.000Z",
+      "expired": false
+    },
+    {
+      "id": 43,
+      "name": "Admin API Token",
+      "prefix": "mbk_a1b2c3d",
+      "scope": "write",
+      "allowedApps": null,
+      "lastUsed": null,
+      "createdAt": "2025-01-26T08:20:15.000Z",
+      "expiresAt": null,
+      "expired": false
+    }
+  ],
+  "count": 2
+}
+```
+
+**Note:** `allowedApps: null` means the token inherits from user's allowed apps.
+
+**Error Responses:**
+
+| Status Code | Error Code | Message |
+|------------|------------|---------|
+| 401 | SESSION_NOT_FOUND | Not authenticated |
+| 500 | INTERNAL_SERVER_ERROR | Internal Server Error |
+
+---
+
+##### `DELETE /mbkauthe/api/token/:id`
+
+Revoke (delete) an API token by its ID.
+
+**Rate Limit:** 10 requests per minute
+
+**Authentication:** Session required (cookie or Bearer token)
+
+**URL Parameters:**
+- `id`: Token ID (integer)
+
+**Success Response (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Token revoked successfully"
+}
+```
+
+**Error Responses:**
+
+| Status Code | Error Code | Message |
+|------------|------------|---------|
+| 400 | MISSING_REQUIRED_FIELD | Invalid token ID |
+| 401 | SESSION_NOT_FOUND | Not authenticated |
+| 404 | SESSION_NOT_FOUND | Token not found or not owned by you |
+| 500 | INTERNAL_SERVER_ERROR | Internal Server Error |
+
+---
+
+### Multi-Account Endpoints
+
 #### `GET /mbkauthe/accounts`
 
 Renders the account switching page, allowing users to switch between remembered accounts on the device.

package/docs/db.md

@@ -78,6 +78,8 @@ CREATE TABLE "ApiTokens" (
     "Name" VARCHAR(255) NOT NULL, -- User-provided friendly name
     "TokenHash" VARCHAR(128) NOT NULL UNIQUE, -- Hashed access token (SHA-256)
     "Prefix" VARCHAR(32) NOT NULL, -- First few chars of token for ID
+    "Scope" VARCHAR(20) DEFAULT 'read-only', -- Token scope: 'read-only' or 'write'
+    "AllowedApps" JSONB DEFAULT NULL, -- Apps this token can access
     "LastUsed" TIMESTAMP WITH TIME ZONE,
     "CreatedAt" TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
     "ExpiresAt" TIMESTAMP WITH TIME ZONE -- Optional expiration
@@ -87,6 +89,38 @@ CREATE INDEX IF NOT EXISTS idx_apitokens_tokenhash ON "ApiTokens" ("TokenHash");
 CREATE INDEX IF NOT EXISTS idx_apitokens_username ON "ApiTokens" ("UserName");
 ```
 
+**Token Permissions (JSONB):**
+
+The `Permissions` column stores both scope and allowed apps in a single JSONB structure for optimal performance:
+
+```json
+{
+  "scope": "read-only" | "write",
+  "allowedApps": null | ["app1", "app2"] | ["*"] | []
+}
+```
+
+**Scope Values:**
+- `read-only`: Allows only safe, read-only HTTP methods (GET, HEAD, OPTIONS)
+- `write`: Allows all HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
+
+**AllowedApps Values:**
+- `null` (default): Token inherits allowed apps from user's `AllowedApps` in Users table
+- `["app1", "app2"]`: Token is restricted to specific apps (must be subset of user's apps)
+- `["*"]`: Token has access to all user's apps (for non-SuperAdmin) or all apps in system (SuperAdmin only)
+- `[]` (empty array): Token has no app access (effectively disabled)
+
+**Note**: SuperAdmin users bypass all app permission checks, so their tokens work on any app regardless of the `allowedApps` value.
+
+**Security:**
+- Tokens are stored as SHA-256 hashes (never plain text)
+- Only the prefix (first 11 characters) is stored for identification
+- The full token is only shown once during creation
+- Scope enforcement is applied at the middleware level before route processing
+- App access is validated against both token restrictions and user permissions
+- **SuperAdmin exception**: SuperAdmin users bypass app permission checks - their tokens work on any app regardless of `allowedApps` configuration
+- Wildcard `["*"]` for non-SuperAdmin means "all apps the user has access to", not "all apps in system"
+
 ## How It Works
 
 ### Login Flow (GitHub/Google)

package/docs/db.sql

@@ -137,13 +137,29 @@ INSERT INTO "Users" ("UserName", "Password", "Role", "Active", "HaveMailAccount"
 CREATE TABLE "ApiTokens" (
     "id" SERIAL PRIMARY KEY,
     "UserName" VARCHAR(50) NOT NULL REFERENCES "Users"("UserName") ON DELETE CASCADE,
-    "Name" VARCHAR(255) NOT NULL, -- User-provided friendly name
-    "TokenHash" VARCHAR(128) NOT NULL UNIQUE, -- Hashed access token
-    "Prefix" VARCHAR(32) NOT NULL, -- First few chars of token for ID
+    "Name" VARCHAR(255) NOT NULL,
+    "TokenHash" VARCHAR(128) NOT NULL UNIQUE,
+    "Prefix" VARCHAR(32) NOT NULL,
+    "Permissions" JSONB NOT NULL DEFAULT '{"scope":"read-only","allowedApps":null}'::jsonb,
     "LastUsed" TIMESTAMP WITH TIME ZONE,
     "CreatedAt" TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-    "ExpiresAt" TIMESTAMP WITH TIME ZONE -- Optional expiration
+    "ExpiresAt" TIMESTAMP WITH TIME ZONE
 );
 
+-- Basic indexes
 CREATE INDEX IF NOT EXISTS idx_apitokens_tokenhash ON "ApiTokens" ("TokenHash");
 CREATE INDEX IF NOT EXISTS idx_apitokens_username ON "ApiTokens" ("UserName");
+
+-- Performance indexes
+CREATE INDEX IF NOT EXISTS idx_apitokens_tokenhash_expires ON "ApiTokens" ("TokenHash", "ExpiresAt") WHERE "ExpiresAt" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_apitokens_username_created ON "ApiTokens" ("UserName", "CreatedAt" DESC);
+CREATE INDEX IF NOT EXISTS idx_apitokens_expires ON "ApiTokens" ("ExpiresAt") WHERE "ExpiresAt" IS NOT NULL;
+
+-- JSONB indexes for fast permission queries
+CREATE INDEX IF NOT EXISTS idx_apitokens_permissions_gin ON "ApiTokens" USING GIN ("Permissions");
+CREATE INDEX IF NOT EXISTS idx_apitokens_permissions_scope ON "ApiTokens" (("Permissions"->>'scope'));
+
+-- Data integrity constraints
+ALTER TABLE "ApiTokens" ADD CONSTRAINT chk_apitokens_permissions_scope CHECK ("Permissions"->>'scope' IN ('read-only', 'write'));
+ALTER TABLE "ApiTokens" ADD CONSTRAINT chk_apitokens_name_not_empty CHECK (LENGTH(TRIM("Name")) > 0);
+ALTER TABLE "ApiTokens" ADD CONSTRAINT chk_apitokens_expires_future CHECK ("ExpiresAt" IS NULL OR "ExpiresAt" > "CreatedAt");

package/docs/error-messages.md

@@ -174,6 +174,16 @@ The provided API token is invalid.
 #### `1006 - API_TOKEN_EXPIRED`
 The provided API token has expired.
 
+#### `1007 - TOKEN_SCOPE_INSUFFICIENT`
+Token scope doesn't allow the requested operation.
+```javascript
+{
+    errorCode: 1007,
+    message: "This API token doesn't have permission for this operation.",
+    hint: "Use a token with 'write' scope or create a new one with appropriate permissions"
+}
+```
+
 ### Rate Limiting (1100-1199)
 
 #### `1101 - RATE_LIMIT_EXCEEDED`

package/index.d.ts

@@ -25,6 +25,7 @@ declare global {
         role: 'SuperAdmin' | 'NormalUser' | 'Guest';
         sessionId?: string;
         allowedApps?: string[];
+        tokenScope?: 'read-only' | 'write' | null;
       };
       preAuthUser?: {
         id: number;
@@ -146,6 +147,26 @@ declare module 'mbkauthe' {
     updated_at: Date;
   }
 
+  // API Token Types
+  export type TokenScope = 'read-only' | 'write';
+  
+  export interface TokenPermissions {
+    scope: TokenScope;
+    allowedApps: string[] | null;
+  }
+
+  export interface ApiToken {
+    id: number;
+    UserName: string;
+    Name: string;
+    TokenHash: string;
+    Prefix: string;
+    Permissions: TokenPermissions;
+    LastUsed?: Date;
+    CreatedAt: Date;
+    ExpiresAt?: Date;
+  }
+
   // API Response Types
   export interface LoginResponse {
     success: boolean;

package/lib/config/tokenScopes.js

@@ -0,0 +1,59 @@
+/**
+ * API Token Scope Configuration
+ * Defines available scopes and methods for token-based access control
+ */
+
+// Available scopes
+export const TOKEN_SCOPES = {
+  'read-only': {
+    name: 'Read Only',
+    description: 'Allows only read operations (GET, HEAD, OPTIONS)',
+    allowedMethods: ['GET', 'HEAD', 'OPTIONS']
+  },
+  'write': {
+    name: 'Write (Full Access)',
+    description: 'Allows all operations (GET, POST, PUT, DELETE, PATCH, etc.)',
+    allowedMethods: '*' // All methods
+  }
+};
+
+export const DEFAULT_SCOPE = 'read-only';
+
+/**
+ * Check if a token scope allows the given HTTP method
+ * @param {string} scope - Token scope ('read-only' or 'write')
+ * @param {string} method - HTTP method (GET, POST, etc.)
+ * @returns {boolean}
+ */
+export function canAccessMethod(scope, method) {
+  if (!scope || !TOKEN_SCOPES[scope]) return false;
+  
+  const scopeConfig = TOKEN_SCOPES[scope];
+  
+  // Full access scope
+  if (scopeConfig.allowedMethods === '*') return true;
+  
+  // Check if method is in allowed list
+  return scopeConfig.allowedMethods.includes(method.toUpperCase());
+}
+
+/**
+ * Validate if a scope is valid
+ * @param {string} scope - Scope to validate
+ * @returns {boolean}
+ */
+export function isValidScope(scope) {
+  return TOKEN_SCOPES.hasOwnProperty(scope);
+}
+
+/**
+ * Get all available scopes with descriptions
+ * @returns {Object}
+ */
+export function getAvailableScopes() {
+  return Object.entries(TOKEN_SCOPES).map(([key, value]) => ({
+    scope: key,
+    name: value.name,
+    description: value.description
+  }));
+}

package/lib/middleware/auth.js

@@ -4,6 +4,7 @@ import { renderError } from "../utils/response.js";
 import { clearSessionCookies, cachedCookieOptions, readAccountListFromCookie } from "../config/cookies.js";
 import { ErrorCodes, createErrorResponse } from "../utils/errors.js";
 import { hashApiToken } from "../config/security.js";
+import { canAccessMethod } from "../config/tokenScopes.js";
 
 /**
  * Validates a Bearer token (API Token or Session UUID)
@@ -21,7 +22,8 @@ async function validateTokenAuthentication(req) {
   if (token.startsWith('mbk_')) {
     const tokenHash = hashApiToken(token);
     const tokenQuery = `
-      SELECT t.id, t."UserName", t."ExpiresAt", u.id as uid, u."Active", u."Role", u."AllowedApps", u."FullName"
+      SELECT t.id, t."UserName", t."ExpiresAt", t."Permissions",
+             u.id as uid, u."Active", u."Role", u."AllowedApps" as user_allowed_apps, u."FullName"
       FROM "ApiTokens" t
       JOIN "Users" u ON t."UserName" = u."UserName"
       WHERE t."TokenHash" = $1 LIMIT 1
@@ -29,24 +31,37 @@ async function validateTokenAuthentication(req) {
     const tokenResult = await dblogin.query({ name: 'validate-api-token', text: tokenQuery, values: [tokenHash] });
 
     if (tokenResult.rows.length === 0) return { error: 'INVALID_TOKEN' };
-    
+
     const row = tokenResult.rows[0];
     if (row.ExpiresAt && new Date(row.ExpiresAt) <= new Date()) return { error: 'TOKEN_EXPIRED' };
 
+    // Parse permissions from JSONB
+    const permissions = row.Permissions || { scope: 'read-only', allowedApps: null };
+    const tokenScope = permissions.scope || 'read-only';
+    const tokenAllowedApps = permissions.allowedApps;
+
+    // Determine allowed apps: token-specific takes precedence over user's apps
+    let allowedApps = row.user_allowed_apps;
+    if (tokenAllowedApps !== null) {
+      allowedApps = tokenAllowedApps;
+    }
+
     // Update usage
     dblogin.query({
-        text: 'UPDATE "ApiTokens" SET "LastUsed" = NOW() WHERE id = $1',
-        values: [row.id]
+      text: 'UPDATE "ApiTokens" SET "LastUsed" = NOW() WHERE id = $1',
+      values: [row.id]
     }).catch(e => console.error('[mbkauthe] Failed to update token usage:', e));
 
     return {
-        id: row.uid,
-        username: row.UserName,
-        fullname: row.FullName,
-        role: row.Role,
-        sessionId: 'api-token-session',
-        allowedApps: row.AllowedApps,
-        active: row.Active
+      id: row.uid,
+      username: row.UserName,
+      fullname: row.FullName,
+      role: row.Role,
+      sessionId: 'api-token-session',
+      allowedApps: allowedApps,
+      userAllowedApps: row.user_allowed_apps, // Pass user apps for wildcard validation
+      active: row.Active,
+      tokenScope: tokenScope
     };
   }
 
@@ -58,37 +73,72 @@ async function validateSession(req, res, next) {
   if (req.headers.authorization) {
     try {
       const tokenUser = await validateTokenAuthentication(req);
-      
+
       if (tokenUser && !tokenUser.error) {
-         if (!tokenUser.active) {
-            return res.status(401).json(createErrorResponse(401, ErrorCodes.ACCOUNT_INACTIVE));
-         }
-
-         if (tokenUser.role !== "SuperAdmin") {
-            const allowedApps = tokenUser.allowedApps;
-            const hasAllowedApps = Array.isArray(allowedApps) && allowedApps.length > 0;
-            if (!hasAllowedApps || !allowedApps.some(app => app && app.toLowerCase() === mbkautheVar.APP_NAME.toLowerCase())) {
+        if (!tokenUser.active) {
+          return res.status(401).json(createErrorResponse(401, ErrorCodes.ACCOUNT_INACTIVE));
+        }
+
+        // SuperAdmin bypasses app permission checks
+        if (tokenUser.role !== "SuperAdmin") {
+          // API tokens must respect their app restrictions for non-SuperAdmin users
+          const allowedApps = tokenUser.allowedApps;
+          const userAllowedApps = tokenUser.userAllowedApps;
+          
+          // allowedApps should always be an array (never null at this point)
+          // If token had null allowedApps, it was already replaced with user's apps in validateTokenAuthentication
+          if (!Array.isArray(allowedApps) || allowedApps.length === 0) {
+            return res.status(401).json(createErrorResponse(401, ErrorCodes.APP_NOT_AUTHORIZED));
+          }
+          
+          // Check if token has access to current app
+          const hasWildcard = allowedApps.includes('*');
+          const hasSpecificApp = allowedApps.some(app => app && app.toLowerCase() === mbkautheVar.APP_NAME.toLowerCase());
+          
+          // If wildcard, check against user's allowed apps (wildcard means "all user's apps", not "all apps")
+          if (hasWildcard) {
+            const userHasApp = userAllowedApps && Array.isArray(userAllowedApps) && 
+              userAllowedApps.some(app => app && app.toLowerCase() === mbkautheVar.APP_NAME.toLowerCase());
+            if (!userHasApp) {
               return res.status(401).json(createErrorResponse(401, ErrorCodes.APP_NOT_AUTHORIZED));
             }
-         }
-
-         // Populate session for downstream
-         req.session.user = {
-            id: tokenUser.id,
-            username: tokenUser.username,
-            fullname: tokenUser.fullname,
-            role: tokenUser.role,
-            sessionId: tokenUser.sessionId,
-            allowedApps: tokenUser.allowedApps,
-         };
-         req.userRole = tokenUser.role;
-         return next();
+          } else if (!hasSpecificApp) {
+            return res.status(401).json(createErrorResponse(401, ErrorCodes.APP_NOT_AUTHORIZED));
+          }
+        }
+
+        // Populate session for downstream
+        req.session.user = {
+          id: tokenUser.id,
+          username: tokenUser.username,
+          fullname: tokenUser.fullname,
+          role: tokenUser.role,
+          sessionId: tokenUser.sessionId,
+          allowedApps: tokenUser.allowedApps,
+          tokenScope: tokenUser.tokenScope || null, // Add scope for token-based auth
+        };
+        req.userRole = tokenUser.role;
+        
+        // Validate token scope for API token requests
+        if (tokenUser.tokenScope) {
+          const requestMethod = req.method;
+          if (!canAccessMethod(tokenUser.tokenScope, requestMethod)) {
+            return res.status(403).json(createErrorResponse(403, ErrorCodes.TOKEN_SCOPE_INSUFFICIENT, {
+              message: `Token scope '${tokenUser.tokenScope}' does not allow ${requestMethod} requests`,
+              tokenScope: tokenUser.tokenScope,
+              requestedMethod: requestMethod,
+              hint: 'Use a token with write scope for write operations'
+            }));
+          }
+        }
+        
+        return next();
       }
-      
+
       // Token provided but invalid (or null if format incorrect)
       let errorCode = ErrorCodes.INVALID_AUTH_TOKEN;
       if (tokenUser && tokenUser.error === 'TOKEN_EXPIRED') {
-         errorCode = ErrorCodes.API_TOKEN_EXPIRED;
+        errorCode = ErrorCodes.API_TOKEN_EXPIRED;
       }
       return res.status(401).json(createErrorResponse(401, errorCode));
 
@@ -102,7 +152,7 @@ async function validateSession(req, res, next) {
   if (!req.session.user) {
     console.log("[mbkauthe] User not authenticated");
     console.log("[mbkauthe]: ", req.session.user);
-    return renderError(res, {
+    return renderError(res, req, {
       code: 401,
       error: "Not Logged In",
       message: "You Are Not Logged In. Please Log In To Continue.",
@@ -365,7 +415,7 @@ export async function reloadSessionUser(req, res) {
 
     // Sync cookies for client UI (non-httpOnly)
     try {
-            res.cookie('username', req.session.user.username, { ...cachedCookieOptions, httpOnly: false });
+      res.cookie('username', req.session.user.username, { ...cachedCookieOptions, httpOnly: false });
       res.cookie('fullName', req.session.user.fullname || req.session.user.username, { ...cachedCookieOptions, httpOnly: false });
       res.cookie('sessionId', req.session.user.sessionId, cachedCookieOptions);
     } catch (cookieErr) {

package/lib/middleware/scopeValidator.js

@@ -0,0 +1,32 @@
+/**
+ * Scope Validation Middleware
+ * Validates HTTP methods against token scopes
+ */
+
+import { canAccessMethod } from '../config/tokenScopes.js';
+import { ErrorCodes, createErrorResponse } from '../utils/errors.js';
+
+/**
+ * Middleware to validate that the token's scope allows the request method
+ * Only applies to API token authentication (not session cookies)
+ */
+export function validateTokenScope(req, res, next) {
+  // Only validate for API token requests (not cookie-based sessions)
+  // Check if this request was authenticated via API token
+  if (req.session?.user?.sessionId === 'api-token-session' && req.session?.user?.tokenScope) {
+    const tokenScope = req.session.user.tokenScope;
+    const requestMethod = req.method;
+    
+    // Check if scope allows this HTTP method
+    if (!canAccessMethod(tokenScope, requestMethod)) {
+      return res.status(403).json(createErrorResponse(403, ErrorCodes.TOKEN_SCOPE_INSUFFICIENT, {
+        message: `Token scope '${tokenScope}' does not allow ${requestMethod} requests`,
+        tokenScope,
+        requestedMethod: requestMethod,
+        hint: 'Use a token with write scope for write operations'
+      }));
+    }
+  }
+  
+  next();
+}

package/lib/routes/misc.js

@@ -186,6 +186,12 @@ router.get('/test', validateSession, LoginLimit, async (req, res) => {
   }
 });
 
+router.post('/test', validateSession, LoginLimit, async (req, res) => {
+  if (req.session?.user) {
+    return res.json({ success: true, message: "You are logged in" });
+  }
+});
+
 // API: check current session validity (JSON) — minimal response
 router.get('/api/checkSession', LoginLimit, async (req, res) => {
   try {

package/lib/utils/errors.js

@@ -34,6 +34,7 @@ export const ErrorCodes = {
   INVALID_TOKEN_FORMAT: 1004,
   INVALID_AUTH_TOKEN: 1005,
   API_TOKEN_EXPIRED: 1006,
+  TOKEN_SCOPE_INSUFFICIENT: 1007,
 
   // Rate limiting (1100-1199)
   RATE_LIMIT_EXCEEDED: 1101,
@@ -75,7 +76,7 @@ export const ErrorMessages = {
   [ErrorCodes.APP_NOT_AUTHORIZED]: {
     message: "Not authorized for this application",
     userMessage: "You don't have permission to access this application.",
-    hint: "Contact your administrator if you believe this is an error"
+    hint: "This token may not be authorized for the requested app."
   },
 
   // 2FA
@@ -160,6 +161,11 @@ export const ErrorMessages = {
     userMessage: "The provided API token has expired.",
     hint: "Please generate a new API token"
   },
+  [ErrorCodes.TOKEN_SCOPE_INSUFFICIENT]: {
+    message: "Token scope insufficient",
+    userMessage: "This API token doesn't have permission for this operation.",
+    hint: "Use a token with 'write' scope or create a new one with appropriate permissions"
+  },
 
   // Rate Limiting
   [ErrorCodes.RATE_LIMIT_EXCEEDED]: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkauthe",
-  "version": "4.1.4",
+  "version": "4.2.0",
   "description": "MBKTech's reusable authentication system for Node.js applications.",
   "main": "index.js",
   "type": "module",

package/views/header.handlebars

@@ -13,104 +13,6 @@
                 <span class="logo-comp">mbktech</span></span>
         </a>
 
-        <div class="header-actions">
-            {{#if userLoggedIn}}
-            <div class="profile-menu">
-                <button class="profile-trigger" type="button" aria-expanded="false" aria-haspopup="true">
-                    <img src="/mbkauthe/user/profilepic?u={{username}}" alt="Profile" class="profile-avatar">
-                </button>
-                <div class="profile-dropdown" role="menu">
-                    <a class="profile-item" role="menuitem" title="{{username}}">
-                        <span>@{{username}}</span>
-                    </a>
-                    <a class="profile-item" href="https://portal.mbktech.org/user/settings" role="menuitem"
-                        title="Settings">
-                        <i class="fas fa-cog"></i>
-                        <span>Settings</span>
-                    </a>
-                    <a class="profile-item" href="/mbkauthe/accounts" role="menuitem"
-                        title="Switch or Add another Account">
-                        <i class="fa fa-user-group"></i>
-                        <span>Switch account</span>
-                    </a>
-                    <button class="profile-item" type="button" data-action="logout" role="menuitem" title="Logout">
-                        <i class="fas fa-sign-out-alt"></i>
-                        <span>Logout</span>
-                    </button>
-                </div>
-            </div>
-            {{else}}
-            <a class="btn-login" style="text-decoration: none;" href="/mbkauthe/login"><i
-                    class="fas fa-sign-in-alt"></i> Login</a>
-            {{/if}}
-        </div>
+        {{> profilemenu}}
     </div>
-</header>
-
-<script>
-    (() => {
-        const trigger = document.querySelector('header .profile-trigger');
-        const dropdown = document.querySelector('header .profile-dropdown');
-
-        if (!trigger || !dropdown) {
-            return;
-        }
-
-        const closeMenu = () => {
-            dropdown.classList.remove('open');
-            trigger.setAttribute('aria-expanded', 'false');
-        };
-
-        trigger.addEventListener('click', (event) => {
-            event.stopPropagation();
-            const isOpen = dropdown.classList.toggle('open');
-            trigger.setAttribute('aria-expanded', String(isOpen));
-        });
-
-        document.addEventListener('click', (event) => {
-            if (!dropdown.contains(event.target) && !trigger.contains(event.target)) {
-                closeMenu();
-            }
-        });
-
-        document.addEventListener('keydown', (event) => {
-            if (event.key === 'Escape') {
-                closeMenu();
-            }
-        });
-
-        const logoutButton = dropdown.querySelector('[data-action="logout"]');
-        if (logoutButton) {
-            logoutButton.addEventListener('click', async () => {
-                const originalLabel = logoutButton.textContent;
-                logoutButton.disabled = true;
-                logoutButton.textContent = 'Logging out...';
-
-                try {
-                    const response = await fetch('/mbkauthe/api/logout', {
-                        method: 'POST',
-                        headers: {
-                            'Content-Type': 'application/json'
-                        },
-                        credentials: 'include'
-                    });
-
-                    const result = await response.json().catch(() => ({}));
-
-                    if (response.ok) {
-                        window.location.reload();
-                    } else {
-                        alert(result.message || 'Logout failed. Please try again.');
-                    }
-                } catch (error) {
-                    console.error('[mbkauthe] Error during logout:', error);
-                    alert('Logout failed. Please try again.');
-                } finally {
-                    logoutButton.disabled = false;
-                    logoutButton.textContent = originalLabel;
-                    closeMenu();
-                }
-            });
-        }
-    })();
-</script>
+</header>

package/views/profilemenu.handlebars

@@ -0,0 +1,187 @@
+<div class="header-actions">
+    {{#if userLoggedIn}}
+    <div class="profile-menu">
+        <button class="profile-trigger" type="button" aria-expanded="false" aria-haspopup="true">
+            <img src="/mbkauthe/user/profilepic?u={{username}}" alt="Profile" class="profile-avatar">
+        </button>
+        <div class="profile-dropdown" role="menu">
+            <a class="profile-item" role="menuitem" title="{{username}}">
+                <span>@{{username}}</span>
+            </a>
+            <a class="profile-item" href="https://portal.mbktech.org/user/settings" role="menuitem" title="Settings">
+                <i class="fas fa-cog"></i>
+                <span>Settings</span>
+            </a>
+            <a class="profile-item" href="/mbkauthe/accounts" role="menuitem" title="Switch or Add another Account">
+                <i class="fa fa-user-group"></i>
+                <span>Switch account</span>
+            </a>
+            <button class="profile-item" type="button" data-action="logout" role="menuitem" title="Logout">
+                <i class="fas fa-sign-out-alt"></i>
+                <span>Logout</span>
+            </button>
+        </div>
+    </div>
+    {{else}}
+    <a class="btn-login" style="text-decoration: none;" href="/mbkauthe/login"><i class="fas fa-sign-in-alt"></i>
+        Login</a>
+    {{/if}}
+</div>
+<style>
+    .header-actions {
+        display: flex;
+        align-items: center;
+        gap: 0.75rem;
+        margin-left: auto;
+    }
+
+    .profile-menu {
+        position: relative;
+    }
+
+    .profile-trigger {
+        width: 45px;
+        height: 45px;
+        border-radius: 999px;
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        background: rgba(255, 255, 255, 0.04);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        cursor: pointer;
+        transition: var(--transition);
+    }
+
+    .profile-trigger:hover {
+        border-color: var(--accent);
+        box-shadow: 0 10px 30px rgba(0, 184, 148, 0.2);
+    }
+
+    .profile-trigger:focus-visible {
+        outline: 2px solid var(--accent);
+        outline-offset: 2px;
+    }
+
+    .profile-avatar {
+        width: 40px;
+        height: 40px;
+        border-radius: 999px;
+        object-fit: cover;
+        background: var(--dark);
+    }
+
+    .profile-dropdown {
+        position: absolute;
+        right: 0;
+        top: calc(100% + 0.5rem);
+        background: var(--darker);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: var(--border-radius);
+        min-width: 190px;
+        box-shadow: 0 12px 32px rgba(0, 0, 0, 0.4);
+        padding: 0;
+        opacity: 0;
+        visibility: hidden;
+        transform: translateY(-6px);
+        transition: var(--transition);
+        z-index: 1000;
+    }
+
+    .profile-dropdown.open {
+        opacity: 1;
+        visibility: visible;
+        transform: translateY(0);
+    }
+
+    .profile-item {
+        width: 100%;
+        display: block;
+        padding: 0.85rem 1rem;
+        color: var(--text);
+        background: transparent;
+        border: none;
+        text-decoration: none;
+        text-align: left;
+        font-weight: 600;
+        letter-spacing: 0.01em;
+        cursor: pointer;
+        transition: var(--transition);
+    }
+
+    .profile-item:hover {
+        background: rgba(255, 255, 255, 0.05);
+        color: var(--accent);
+    }
+
+    .profile-item:disabled {
+        opacity: 0.6;
+        cursor: not-allowed;
+    }
+</style>
+<script>
+    (() => {
+        const trigger = document.querySelector('header .profile-trigger');
+        const dropdown = document.querySelector('header .profile-dropdown');
+
+        if (!trigger || !dropdown) {
+            return;
+        }
+
+        const closeMenu = () => {
+            dropdown.classList.remove('open');
+            trigger.setAttribute('aria-expanded', 'false');
+        };
+
+        trigger.addEventListener('click', (event) => {
+            event.stopPropagation();
+            const isOpen = dropdown.classList.toggle('open');
+            trigger.setAttribute('aria-expanded', String(isOpen));
+        });
+
+        document.addEventListener('click', (event) => {
+            if (!dropdown.contains(event.target) && !trigger.contains(event.target)) {
+                closeMenu();
+            }
+        });
+
+        document.addEventListener('keydown', (event) => {
+            if (event.key === 'Escape') {
+                closeMenu();
+            }
+        });
+
+        const logoutButton = dropdown.querySelector('[data-action="logout"]');
+        if (logoutButton) {
+            logoutButton.addEventListener('click', async () => {
+                const originalLabel = logoutButton.textContent;
+                logoutButton.disabled = true;
+                logoutButton.textContent = 'Logging out...';
+
+                try {
+                    const response = await fetch('/mbkauthe/api/logout', {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json'
+                        },
+                        credentials: 'include'
+                    });
+
+                    const result = await response.json().catch(() => ({}));
+
+                    if (response.ok) {
+                        window.location.reload();
+                    } else {
+                        alert(result.message || 'Logout failed. Please try again.');
+                    }
+                } catch (error) {
+                    console.error('[mbkauthe] Error during logout:', error);
+                    alert('Logout failed. Please try again.');
+                } finally {
+                    logoutButton.disabled = false;
+                    logoutButton.textContent = originalLabel;
+                    closeMenu();
+                }
+            });
+        }
+    })();
+</script>

package/views/sharedStyles.handlebars

@@ -53,96 +53,6 @@
         margin: 0 auto;
     }
 
-    .header-actions {
-        display: flex;
-        align-items: center;
-        gap: 0.75rem;
-        margin-left: auto;
-    }
-
-    .profile-menu {
-        position: relative;
-    }
-
-    .profile-trigger {
-        width: 45px;
-        height: 45px;
-        border-radius: 999px;
-        border: 1px solid rgba(255, 255, 255, 0.12);
-        background: rgba(255, 255, 255, 0.04);
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        cursor: pointer;
-        transition: var(--transition);
-    }
-
-    .profile-trigger:hover {
-        border-color: var(--accent);
-        box-shadow: 0 10px 30px rgba(0, 184, 148, 0.2);
-    }
-
-    .profile-trigger:focus-visible {
-        outline: 2px solid var(--accent);
-        outline-offset: 2px;
-    }
-
-    .profile-avatar {
-        width: 40px;
-        height: 40px;
-        border-radius: 999px;
-        object-fit: cover;
-        background: var(--dark);
-    }
-
-    .profile-dropdown {
-        position: absolute;
-        right: 0;
-        top: calc(100% + 0.5rem);
-        background: var(--darker);
-        border: 1px solid rgba(255, 255, 255, 0.08);
-        border-radius: var(--border-radius);
-        min-width: 190px;
-        box-shadow: 0 12px 32px rgba(0, 0, 0, 0.4);
-        padding: 0;
-        opacity: 0;
-        visibility: hidden;
-        transform: translateY(-6px);
-        transition: var(--transition);
-        z-index: 1000;
-    }
-
-    .profile-dropdown.open {
-        opacity: 1;
-        visibility: visible;
-        transform: translateY(0);
-    }
-
-    .profile-item {
-        width: 100%;
-        display: block;
-        padding: 0.85rem 1rem;
-        color: var(--text);
-        background: transparent;
-        border: none;
-        text-decoration: none;
-        text-align: left;
-        font-weight: 600;
-        letter-spacing: 0.01em;
-        cursor: pointer;
-        transition: var(--transition);
-    }
-
-    .profile-item:hover {
-        background: rgba(255, 255, 255, 0.05);
-        color: var(--accent);
-    }
-
-    .profile-item:disabled {
-        opacity: 0.6;
-        cursor: not-allowed;
-    }
-
     .logo {
         display: flex;
         align-items: center;