myaidev-method 0.2.8 → 0.2.9

package/src/server/auth/README.md

@@ -0,0 +1,290 @@
+# Authentication System
+
+Effect-TS based authentication system for MyAIDev Method web server.
+
+## Architecture
+
+### Services Layer
+
+**AuthService** - High-level authentication orchestration
+- `register()` - User registration with validation
+- `login()` - User authentication with session creation
+- `logout()` - Session revocation
+- `verifyToken()` - JWT verification and session validation
+
+**PasswordService** - Password hashing and validation
+- `hash()` - bcrypt password hashing (12 rounds)
+- `verify()` - Password verification
+- `validatePasswordStrength()` - Password strength requirements
+
+**TokenService** - JWT token management
+- `generateToken()` - Create signed JWT (RS256)
+- `verifyToken()` - Verify and decode JWT
+- `hashToken()` - SHA-256 token hashing
+
+**UserRepository** - User data persistence
+- `create()` - Create new user
+- `findById()` - Find user by ID
+- `findByEmail()` - Find user by email
+- `findByUsername()` - Find user by username
+- `update()` - Update user data
+- `incrementFailedLogins()` - Track failed login attempts
+- `resetFailedLogins()` - Reset failed login counter
+
+**SessionRepository** - Session management
+- `create()` - Create new session
+- `findById()` - Find session by ID
+- `findByTokenHash()` - Find session by token hash
+- `revoke()` - Revoke single session
+- `revokeAllForUser()` - Revoke all user sessions
+- `deleteExpired()` - Clean up expired sessions
+
+**AuditLogService** - Security audit logging
+- `log()` - Record security events
+
+### Middleware
+
+**authMiddleware** - Hono middleware for route protection
+- Extracts token from `Authorization: Bearer <token>` or `auth_token` cookie
+- Verifies token and session validity
+- Injects `user` and `session` into Hono context
+- Returns 401 for authentication failures
+
+### Routes
+
+**POST /api/auth/register**
+```typescript
+Request: { username: string; email: string; password: string }
+Response: { user: { id, username, email, emailVerified } }
+Status: 201 Created | 400 Validation Error | 500 Server Error
+```
+
+**POST /api/auth/login**
+```typescript
+Request: { email: string; password: string }
+Response: { user: { id, username, email, emailVerified }, token: string }
+Cookie: auth_token (httpOnly, secure, sameSite=strict)
+Status: 200 OK | 401 Unauthorized | 500 Server Error
+```
+
+**POST /api/auth/logout** (requires auth)
+```typescript
+Response: { message: "Logged out successfully" }
+Status: 200 OK | 401 Unauthorized | 500 Server Error
+```
+
+**GET /api/auth/me** (requires auth)
+```typescript
+Response: { user: { id, username, email, emailVerified, createdAt, lastLoginAt } }
+Status: 200 OK | 401 Unauthorized | 500 Server Error
+```
+
+## Security Features
+
+### Password Requirements
+- Minimum 8 characters
+- At least 1 uppercase letter
+- At least 1 lowercase letter
+- At least 1 number
+- Hashed with bcrypt (12 rounds)
+
+### Account Lockout
+- 5 failed login attempts triggers lockout
+- 15 minute lockout duration
+- Automatic unlock after duration expires
+- Failed attempts reset on successful login
+
+### Session Management
+- JWT tokens with RS256 signing
+- 7 day token expiration
+- Session stored with token hash (SHA-256)
+- Session validation on every request
+- Revocable sessions
+
+### Cookie Configuration
+```typescript
+{
+  httpOnly: true,
+  secure: process.env.NODE_ENV === "production",
+  sameSite: "strict",
+  maxAge: 7 * 24 * 60 * 60, // 7 days
+  path: "/"
+}
+```
+
+### Linux Username Generation
+- Sanitized from user's username
+- Lowercase alphanumeric + underscores
+- Must start with letter
+- Max 32 characters
+- Guaranteed unique with counter suffix if needed
+
+## Usage Example
+
+### Integration with Hono
+
+```typescript
+import { Hono } from "hono";
+import { authRouter, authMiddleware } from "./auth/index.js";
+
+const app = new Hono();
+
+// Public routes
+app.route("/api/auth", authRouter);
+
+// Protected routes
+app.get("/api/protected", authMiddleware, (c) => {
+  const user = c.get("user");
+  const session = c.get("session");
+  return c.json({ message: `Hello ${user.username}` });
+});
+
+export default app;
+```
+
+### Direct Service Usage
+
+```typescript
+import { Effect } from "effect";
+import { AppLayer } from "./auth/middleware/authMiddleware.js";
+import { AuthService } from "./auth/services/AuthService.js";
+
+const registerUser = Effect.gen(function* () {
+  const authService = yield* AuthService;
+  const user = yield* authService.register(
+    "testuser",
+    "test@example.com",
+    "SecurePass123",
+    "127.0.0.1",
+    "Mozilla/5.0"
+  );
+  return user;
+});
+
+const user = await Effect.runPromise(
+  Effect.provide(registerUser, AppLayer)
+);
+```
+
+## Error Handling
+
+All services use typed Effect errors:
+
+- **AuthError** - Authentication failures (401)
+  - `INVALID_CREDENTIALS` - Wrong email/password
+  - `ACCOUNT_LOCKED` - Too many failed attempts
+  - `TOKEN_EXPIRED` - Session expired
+  - `SESSION_REVOKED` - Session invalidated
+  - `USER_INACTIVE` - Account disabled
+
+- **ValidationError** - Input validation failures (400)
+  - Field-specific error messages
+  - Password strength requirements
+  - Email format validation
+
+- **DatabaseError** - Database operation failures (500)
+  - Generic database errors
+  - Connection issues
+
+## Audit Logging
+
+All authentication events are logged:
+- `USER_REGISTERED` - New user registration
+- `USER_LOGIN` - Successful login
+- `USER_LOGOUT` - User logout
+- `LOGIN_FAILED` - Failed login attempt
+- `ACCOUNT_LOCKED` - Account locked notification
+
+Audit logs include:
+- User ID
+- Action type
+- Resource type and ID
+- IP address
+- User agent
+- Timestamp
+- Additional details
+
+## Testing
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { Effect } from "effect";
+import { AppLayer } from "./middleware/authMiddleware.js";
+import { AuthService } from "./services/AuthService.js";
+
+describe("AuthService", () => {
+  it("should register a new user", async () => {
+    const registerEffect = Effect.gen(function* () {
+      const authService = yield* AuthService;
+      return yield* authService.register(
+        "testuser",
+        "test@example.com",
+        "SecurePass123"
+      );
+    });
+
+    const user = await Effect.runPromise(
+      Effect.provide(registerEffect, AppLayer)
+    );
+
+    expect(user.username).toBe("testuser");
+    expect(user.email).toBe("test@example.com");
+    expect(user.passwordHash).toBeTruthy();
+  });
+});
+```
+
+## Dependencies
+
+- `effect` - Effect-TS for composable error handling
+- `hono` - Web framework
+- `bcrypt` - Password hashing
+- `jose` - JWT handling (RS256)
+- `node:crypto` - Token hashing and UUID generation
+
+## Design Patterns
+
+### Effect-TS Context.Tag Pattern
+All services use `Context.Tag` for dependency injection:
+```typescript
+export class ServiceName extends Context.Tag("ServiceName")<
+  ServiceName,
+  ServiceInterface
+>() {
+  static Live = Layer.effect(this, Effect.gen(function* () {
+    // Dependencies
+    const dep = yield* DependencyService;
+
+    // Implementation
+    return { method: () => Effect.succeed(result) };
+  }));
+}
+```
+
+### Layer Composition
+Dependencies are composed into a single `AppLayer`:
+```typescript
+export const AppLayer = Layer.mergeAll(
+  DatabaseService.Live,
+  PasswordService.Live,
+  TokenService.Live
+).pipe(
+  Layer.provideMerge(UserRepository.Live),
+  Layer.provideMerge(SessionRepository.Live),
+  Layer.provideMerge(AuditLogService.Live),
+  Layer.provideMerge(AuthService.Live)
+);
+```
+
+### Effect.gen for Composition
+All business logic uses `Effect.gen` with `yield*`:
+```typescript
+const operation = Effect.gen(function* () {
+  const service = yield* Service;
+  const result = yield* service.method();
+  return result;
+});
+```
+
+### No Type Casting
+All type conversions are explicit and safe - no `as` type assertions.

package/src/server/auth/controllers/AuthController.ts

@@ -0,0 +1,129 @@
+import { Context, Effect, Layer } from "effect";
+import { AuthService } from "../services/AuthService.js";
+import {
+  AuthError,
+  AuthResponse,
+  DatabaseError,
+  LoginRequest,
+  RegisterRequest,
+  User,
+  ValidationError,
+} from "../../../shared/types.js";
+
+export interface RegisterResult {
+  user: {
+    id: string;
+    username: string;
+    email: string;
+    emailVerified: boolean;
+  };
+}
+
+export interface LoginResult extends AuthResponse {}
+
+export interface MeResult {
+  user: {
+    id: string;
+    username: string;
+    email: string;
+    emailVerified: boolean;
+    createdAt: number;
+    lastLoginAt: number | null;
+  };
+}
+
+export class AuthController extends Context.Tag("AuthController")<
+  AuthController,
+  {
+    readonly register: (
+      data: RegisterRequest,
+      ipAddress?: string | null,
+      userAgent?: string | null
+    ) => Effect.Effect<RegisterResult, AuthError | ValidationError | DatabaseError>;
+    readonly login: (
+      data: LoginRequest,
+      ipAddress?: string | null,
+      userAgent?: string | null
+    ) => Effect.Effect<LoginResult, AuthError | DatabaseError>;
+    readonly logout: (
+      sessionId: string,
+      userId: string
+    ) => Effect.Effect<void, DatabaseError>;
+    readonly me: (user: User) => Effect.Effect<MeResult, never>;
+  }
+>() {
+  static Live = Layer.effect(
+    this,
+    Effect.gen(function* () {
+      const authService = yield* AuthService;
+
+      const register = (
+        data: RegisterRequest,
+        ipAddress?: string | null,
+        userAgent?: string | null
+      ): Effect.Effect<RegisterResult, AuthError | ValidationError | DatabaseError> =>
+        Effect.gen(function* () {
+          const user = yield* authService.register(
+            data.username,
+            data.email,
+            data.password,
+            ipAddress,
+            userAgent
+          );
+
+          return {
+            user: {
+              id: user.id,
+              username: user.username,
+              email: user.email,
+              emailVerified: user.emailVerified,
+            },
+          };
+        });
+
+      const login = (
+        data: LoginRequest,
+        ipAddress?: string | null,
+        userAgent?: string | null
+      ): Effect.Effect<LoginResult, AuthError | DatabaseError> =>
+        Effect.gen(function* () {
+          const result = yield* authService.login(
+            data.email,
+            data.password,
+            ipAddress,
+            userAgent
+          );
+
+          return {
+            user: {
+              id: result.user.id,
+              username: result.user.username,
+              email: result.user.email,
+              emailVerified: result.user.emailVerified,
+            },
+            token: result.token,
+          };
+        });
+
+      const logout = (
+        sessionId: string,
+        userId: string
+      ): Effect.Effect<void, DatabaseError> =>
+        authService.logout(sessionId, userId);
+
+      const me = (user: User): Effect.Effect<MeResult, never> =>
+        Effect.succeed({
+          user: {
+            id: user.id,
+            username: user.username,
+            email: user.email,
+            emailVerified: user.emailVerified,
+            createdAt: user.createdAt,
+            lastLoginAt: user.lastLoginAt,
+          },
+        });
+
+      return { register, login, logout, me };
+    })
+  );
+}

package/src/server/auth/example-usage.ts

@@ -0,0 +1,159 @@
+/**
+ * Example usage of the authentication system
+ * This file demonstrates how to integrate the auth system with Hono
+ */
+
+import { Hono } from "hono";
+import { Layer } from "effect";
+import { createAuthRoutes, createAuthMiddleware } from "./index.js";
+import { PasswordService } from "./services/PasswordService.js";
+import { TokenService } from "./services/TokenService.js";
+import { UserRepository } from "./services/UserRepository.js";
+import { SessionRepository } from "./services/SessionRepository.js";
+import { AuditLogService } from "./services/AuditLogService.js";
+import { AuthService } from "./services/AuthService.js";
+import { DatabaseService } from "../database/db.js";
+
+// Build the complete application layer with all services
+const DbLayer = DatabaseService.Live({
+  path: process.env["DB_PATH"] || "./auth.db",
+  timeout: 5000,
+  verbose: process.env["NODE_ENV"] === "development",
+});
+
+const IndependentServices = Layer.mergeAll(
+  PasswordService.Live,
+  TokenService.Live,
+  AuditLogService.Live
+);
+
+const Repositories = Layer.mergeAll(
+  UserRepository.Live,
+  SessionRepository.Live
+);
+
+const Auth = AuthService.Live;
+
+const AppLayer = Layer.mergeAll(
+  IndependentServices,
+  Repositories,
+  Auth
+).pipe(Layer.provide(DbLayer));
+
+// Create main app
+const app = new Hono();
+
+// Create middleware and routes with AppLayer
+const authMiddleware = createAuthMiddleware(AppLayer);
+const authRouter = createAuthRoutes(AppLayer, authMiddleware);
+
+// Mount authentication routes (public)
+app.route("/api/auth", authRouter);
+
+// Protected route example - requires authentication
+app.get("/api/protected/profile", authMiddleware, (c) => {
+  const user = c.get("user");
+  const session = c.get("session");
+
+  return c.json({
+    message: "This is a protected endpoint",
+    user: {
+      id: user.id,
+      username: user.username,
+      email: user.email,
+    },
+    session: {
+      id: session.id,
+      createdAt: session.createdAt,
+      expiresAt: session.expiresAt,
+    },
+  });
+});
+
+// Protected route example - user data
+app.get("/api/protected/data", authMiddleware, (c) => {
+  const user = c.get("user");
+
+  return c.json({
+    data: {
+      userId: user.id,
+      username: user.username,
+      linuxUsername: user.linuxUsername,
+      isActive: user.isActive,
+      emailVerified: user.emailVerified,
+    },
+  });
+});
+
+// Admin-only route example
+app.get("/api/protected/admin", authMiddleware, (c) => {
+  const user = c.get("user");
+
+  // Add your own admin check logic here
+  // For example, check if user has admin role
+  if (user.email !== "admin@example.com") {
+    return c.json({ error: "FORBIDDEN", message: "Admin access required" }, 403);
+  }
+
+  return c.json({
+    message: "Welcome to admin panel",
+    adminData: "Sensitive information",
+  });
+});
+
+// Health check endpoint (public)
+app.get("/health", (c) => {
+  return c.json({ status: "ok", timestamp: Date.now() });
+});
+
+// Start server
+const port = process.env["PORT"] || 3000;
+console.log(`Server starting on port ${port}`);
+
+export default app;
+
+/**
+ * To run this example:
+ *
+ * 1. Install dependencies:
+ *    npm install hono effect bcrypt jose
+ *
+ * 2. Set up environment:
+ *    export NODE_ENV=development
+ *    export PORT=3000
+ *
+ * 3. Initialize database:
+ *    node --import tsx/esm src/server/database/init-db.ts
+ *
+ * 4. Run the server:
+ *    node --import tsx/esm src/server/auth/example-usage.ts
+ *
+ * API Usage Examples:
+ *
+ * Register:
+ *   curl -X POST http://localhost:3000/api/auth/register \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"username":"testuser","email":"test@example.com","password":"SecurePass123"}'
+ *
+ * Login:
+ *   curl -X POST http://localhost:3000/api/auth/login \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"email":"test@example.com","password":"SecurePass123"}' \
+ *     -c cookies.txt
+ *
+ * Access protected endpoint (with cookie):
+ *   curl http://localhost:3000/api/protected/profile \
+ *     -b cookies.txt
+ *
+ * Access protected endpoint (with Bearer token):
+ *   curl http://localhost:3000/api/protected/profile \
+ *     -H "Authorization: Bearer <token>"
+ *
+ * Get current user:
+ *   curl http://localhost:3000/api/auth/me \
+ *     -b cookies.txt
+ *
+ * Logout:
+ *   curl -X POST http://localhost:3000/api/auth/logout \
+ *     -b cookies.txt
+ */

package/src/server/auth/index.ts

@@ -0,0 +1,19 @@
+// Authentication module exports
+
+// Services
+export { AuthService } from "./services/AuthService.js";
+export { PasswordService } from "./services/PasswordService.js";
+export { TokenService } from "./services/TokenService.js";
+export { UserRepository } from "./services/UserRepository.js";
+export { SessionRepository } from "./services/SessionRepository.js";
+export { AuditLogService } from "./services/AuditLogService.js";
+
+// Controllers
+export { AuthController } from "./controllers/AuthController.js";
+
+// Middleware
+export { createAuthMiddleware } from "./middleware/authMiddleware.js";
+export type { AppRuntimeContext } from "./middleware/authMiddleware.js";
+
+// Routes
+export { createAuthRoutes } from "./routes/authRoutes.js";

package/src/server/auth/layers.ts

@@ -0,0 +1,57 @@
+import { Layer } from "effect";
+import { PasswordService } from "./services/PasswordService.js";
+import { TokenService } from "./services/TokenService.js";
+import { UserRepository } from "./services/UserRepository.js";
+import { SessionRepository } from "./services/SessionRepository.js";
+import { AuditLogService } from "./services/AuditLogService.js";
+import { AuthService } from "./services/AuthService.js";
+import { DatabaseService } from "../database/db.js";
+import { UserManagementLayer } from "../user-management/layers.js";
+
+/**
+ * Creates the complete application layer with all auth services
+ * @param dbConfig Database configuration
+ * @returns Complete layer with all services including DatabaseService
+ */
+export const createAppLayer = (dbConfig: { path: string; timeout?: number; verbose?: boolean }) => {
+  // Base database layer
+  const DbLayer = DatabaseService.Live(dbConfig);
+
+  // Service layers that don't require DatabaseService
+  const IndependentServices = Layer.mergeAll(
+    PasswordService.Live,
+    TokenService.Live
+  );
+
+  // Services and repositories that require DatabaseService
+  const DbDependentServices = Layer.mergeAll(
+    AuditLogService.Live,
+    UserRepository.Live,
+    SessionRepository.Live
+  );
+
+  // Provide DatabaseService to dependent services
+  const DbDependentWithDb = Layer.provide(DbDependentServices, DbLayer);
+
+  // Merge all services and database
+  const BaseServices = Layer.mergeAll(
+    IndependentServices,
+    DbDependentWithDb,
+    DbLayer
+  );
+
+  // Add user management layer
+  const ServicesWithUserManagement = Layer.mergeAll(
+    BaseServices,
+    UserManagementLayer
+  );
+
+  // Provide all dependencies to AuthService
+  const AuthWithDeps = Layer.provide(AuthService.Live, ServicesWithUserManagement);
+
+  // Complete application layer - merge everything
+  return Layer.mergeAll(
+    ServicesWithUserManagement,
+    AuthWithDeps
+  );
+};