docs: update API documentation and plugin security features for clarity and consistency

Author: Lasim

services/backend/API_DOCUMENTATION.md

@@ -178,6 +178,7 @@ fastify.post<{ Body: RequestBody }>(
 ### What NOT to Do (Anti-patterns)
 
 ❌ **Don't do manual validation in handlers:**
+
 ```typescript
 // BAD: Manual validation (redundant)
 const parsedBody = myRequestBodySchema.safeParse(request.body);
@@ -197,6 +198,7 @@ if (request.body.type !== 'mysql' && request.body.type !== 'sqlite') {
 ```
 
 ✅ **Do trust Fastify's automatic validation:**
+
 ```typescript
 // GOOD: Trust the validation - if handler runs, data is valid
 const { name, count, type } = request.body; // Already validated by Fastify
@@ -206,7 +208,7 @@ const { name, count, type } = request.body; // Already validated by Fastify
 
 The validation chain works as follows:
 
-**Zod Schema → JSON Schema → Fastify Validation → Handler**
+#### Zod Schema → JSON Schema → Fastify Validation → Handler
 
 1. **Zod Schema**: Define validation rules using Zod
 2. **JSON Schema**: Convert to OpenAPI format using `zodToJsonSchema()`
@@ -218,6 +220,7 @@ If validation fails, Fastify automatically returns a 400 error **before** your h
 ### Real-World Examples
 
 See these files for complete examples of proper Zod validation:
+
 - `src/routes/db/setup.ts` - Database setup with enum validation
 - `src/routes/db/status.ts` - Simple GET endpoint with response schemas
 - `src/routes/auth/loginEmail.ts` - Login with required string fields
@@ -329,7 +332,7 @@ All plugin routes are automatically namespaced under `/api/plugin/<plugin-name>/
 
 For a plugin with ID `example-plugin`:
 
-```
+```bash
 GET    /api/plugin/example-plugin/examples
 GET    /api/plugin/example-plugin/examples/:id
 POST   /api/plugin/example-plugin/examples

services/backend/PLUGINS.md

@@ -16,6 +16,7 @@ DeployStack's plugin architecture allows for extensible, modular development wit
 ## Security Features
 
 ### Route Isolation & Security
+
 DeployStack implements strict route isolation to ensure plugins cannot interfere with core functionality or each other:
 
 - **Automatic Namespacing**: All plugin routes are automatically prefixed with `/api/plugin/<plugin-id>/`
@@ -24,13 +25,15 @@ DeployStack implements strict route isolation to ensure plugins cannot interfere
 - **Core Route Protection**: Plugins cannot access or modify core routes (`/api/auth/*`, `/api/users/*`, etc.)
 
 ### Security Benefits
+
 1. **Prevents Route Hijacking**: Malicious plugins cannot override authentication or user management routes
 2. **Eliminates Route Conflicts**: Multiple plugins cannot register conflicting routes
 3. **Predictable API Surface**: All plugin APIs follow consistent `/api/plugin/<name>/` structure
 4. **Easy Auditing**: Route ownership is immediately clear from the URL structure
 5. **Fail-Safe Design**: Plugins that don't follow the new system simply won't have routes registered
 
 ### Example Security Enforcement
+
 ```typescript
 // ❌ This will NOT work - no direct app access
 async initialize(app: FastifyInstance, db: AnyDatabase | null) {

services/backend/src/plugins/example-plugin/index.ts

@@ -5,14 +5,14 @@ import {
   type GlobalSettingsExtension,
   type PluginRouteManager
 } from '../../plugin-system/types';
-import { type FastifyInstance } from 'fastify';
+
 import { type AnyDatabase, getSchema } from '../../db'; // Import getSchema
 import { type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'; // For type guard
 import { type NodePgDatabase } from 'drizzle-orm/node-postgres'; // For casting db
 import { type SQLiteTable } from 'drizzle-orm/sqlite-core';     // For casting table from schema
 import { type PgTable } from 'drizzle-orm/pg-core';         // For casting table from schema
 // import { exampleEntities } from './schema'; // No longer directly used for queries
-import { eq, sql } from 'drizzle-orm';
+import { sql } from 'drizzle-orm';
 
 // Helper type guard to check for BetterSQLite3Database specific methods
 function isSQLiteDB(db: AnyDatabase): db is BetterSQLite3Database<any> {
@@ -144,6 +144,7 @@ class ExamplePlugin implements Plugin {
   };
 
   // Initialize the plugin (non-route initialization only)
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   async initialize(db: AnyDatabase | null) {
     console.log(`[${this.meta.id}] Initializing...`);
     // Non-route initialization only - routes are now registered via registerRoutes method

services/backend/src/plugins/example-plugin/routes.ts

@@ -7,6 +7,7 @@ import { type PgTable } from 'drizzle-orm/pg-core';
 import { eq } from 'drizzle-orm';
 
 // Helper type guard to check for BetterSQLite3Database specific methods
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function isSQLiteDB(db: AnyDatabase): db is BetterSQLite3Database<any> {
   return typeof (db as BetterSQLite3Database).get === 'function' &&
          typeof (db as BetterSQLite3Database).all === 'function' &&
@@ -58,6 +59,7 @@ export async function registerRoutes(routeManager: PluginRouteManager, db: AnyDa
 
     if (isSQLiteDB(db)) {
       // Cast to SQLiteTable to access its 'id' column for the 'eq' condition
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const typedTable = table as SQLiteTable & { id: any }; 
       example = await db
         .select()
@@ -66,6 +68,7 @@ export async function registerRoutes(routeManager: PluginRouteManager, db: AnyDa
         .get();
     } else {
       // Cast to PgTable to access its 'id' column for the 'eq' condition
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const typedTable = table as PgTable & { id: any };
       const rows = await (db as NodePgDatabase)
         .select()

services/backend/src/routes/auth/updateProfile.ts

@@ -135,6 +135,7 @@ export default async function updateProfileRoute(fastify: FastifyInstance) {
         }
 
         // Prepare update data - only include fields that are provided
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const updateData: any = {
           updated_at: new Date()
         };

services/backend/src/services/emailVerificationService.ts

@@ -1,5 +1,5 @@
 import { getDb, getSchema } from '../db';
-import { eq, and, lt, gt } from 'drizzle-orm';
+import { eq, lt, gt } from 'drizzle-orm';
 import { generateId } from 'lucia';
 import { hash, verify } from '@node-rs/argon2';
 import { EmailService } from '../email';

services/backend/tests/unit/plugin-system/plugin-manager.test.ts

@@ -143,8 +143,8 @@ describe('PluginManager', () => {
     describe('initializePlugins', () => {
       it('should initialize all loaded plugins', async () => {
         await pluginManager.initializePlugins();
-        expect(plugin1.initialize).toHaveBeenCalledWith(mockApp, mockDb);
-        expect(plugin2.initialize).toHaveBeenCalledWith(mockApp, mockDb);
+        expect(plugin1.initialize).toHaveBeenCalledWith(mockDb);
+        expect(plugin2.initialize).toHaveBeenCalledWith(mockDb);
         expect(pluginManager['initialized']).toBe(true);
       });
 

services/backend/tests/unit/routes/auth/registerEmail.test.ts

@@ -6,13 +6,15 @@ import { hash } from '@node-rs/argon2';
 import { generateId } from 'lucia';
 import { TeamService } from '../../../../src/services/teamService';
 import { GlobalSettingsInitService } from '../../../../src/global-settings';
+import { EmailVerificationService } from '../../../../src/services/emailVerificationService';
 
 // Mock dependencies
 vi.mock('../../../../src/db');
 vi.mock('@node-rs/argon2');
 vi.mock('lucia');
 vi.mock('../../../../src/services/teamService');
 vi.mock('../../../../src/global-settings');
+vi.mock('../../../../src/services/emailVerificationService');
 vi.mock('../../../../src/lib/lucia', () => ({
   getLucia: vi.fn(() => ({
     createSessionCookie: vi.fn(() => ({
@@ -30,6 +32,7 @@ const mockHash = hash as MockedFunction<typeof hash>;
 const mockGenerateId = generateId as MockedFunction<typeof generateId>;
 const mockTeamService = TeamService as any;
 const mockGlobalSettingsInitService = GlobalSettingsInitService as any;
+const mockEmailVerificationService = EmailVerificationService as any;
 
 describe('Register Email Route', () => {
   let mockFastify: Partial<FastifyInstance>;
@@ -86,6 +89,7 @@ describe('Register Email Route', () => {
     mockGenerateId.mockReturnValueOnce('user-id-123').mockReturnValueOnce('session-id-123');
     mockGlobalSettingsInitService.isEmailRegistrationEnabled = vi.fn().mockResolvedValue(true);
     mockTeamService.createDefaultTeamForUser = vi.fn().mockResolvedValue({ id: 'team-123', name: 'Default Team' });
+    mockEmailVerificationService.isVerificationRequired = vi.fn().mockResolvedValue(false);
 
     // Setup route handlers storage
     routeHandlers = {};
@@ -179,7 +183,7 @@ describe('Register Email Route', () => {
       expect(mockReply.status).toHaveBeenCalledWith(201);
       expect(mockReply.send).toHaveBeenCalledWith({
         success: true,
-        message: 'User registered successfully. Please log in to continue.',
+        message: 'User registered successfully. You are now logged in as the global administrator.',
         user: {
           id: 'user-id-123',
           username: 'testuser',
@@ -235,7 +239,7 @@ describe('Register Email Route', () => {
       expect(mockReply.status).toHaveBeenCalledWith(201);
       expect(mockReply.send).toHaveBeenCalledWith({
         success: true,
-        message: 'User registered successfully. Please log in to continue.',
+        message: 'User registered successfully. You can now log in to your account.',
         user: expect.objectContaining({
           role_id: 'global_user',
         }),
@@ -285,7 +289,7 @@ describe('Register Email Route', () => {
       expect(mockReply.status).toHaveBeenCalledWith(201);
       expect(mockReply.send).toHaveBeenCalledWith({
         success: true,
-        message: 'User registered successfully. Please log in to continue.',
+        message: 'User registered successfully. You are now logged in as the global administrator.',
         user: expect.objectContaining({
           first_name: null,
           last_name: null,