@venizia/ignis-docs 0.0.1-8 → 0.0.1

package/wiki/references/components/authentication.md

@@ -9,8 +9,9 @@ JWT-based authentication and authorization system for Ignis applications.
 | **AuthenticateComponent** | Main component registering auth services and controllers |
 | **AuthenticationStrategyRegistry** | Singleton managing available auth strategies |
 | **JWTAuthenticationStrategy** | JWT verification using `JWTTokenService` |
-| **JWTTokenService** | Generate, verify, encrypt/decrypt JWT tokens |
+| **JWTTokenService** | Generate, verify, encrypt/decrypt JWT tokens (safely handles undefined/null) |
 | **IAuthService** | Interface for custom auth implementation (sign-in, sign-up) |
+| **defineAuthController** | Factory function for creating custom auth controllers |
 
 ### Key Environment Variables
 
@@ -20,12 +21,26 @@ JWT-based authentication and authorization system for Ignis applications.
 | `APP_ENV_JWT_SECRET` | Sign and verify JWT signature | ✅ Yes |
 | `APP_ENV_JWT_EXPIRES_IN` | Token expiration (seconds) | Optional |
 
+### Authentication Options Configuration
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `restOptions.useAuthController` | `boolean` | Enable/disable built-in auth controller (default: `false`) |
+| `restOptions.controllerOpts` | `TDefineAuthControllerOpts` | Configuration for built-in auth controller (required if `useAuthController` is `true`) |
+| `restOptions.controllerOpts.restPath` | `string` | Base path for auth endpoints (default: `/auth`) |
+| `restOptions.controllerOpts.serviceKey` | `string` | Dependency injection key for auth service (default: `services.AuthenticationService`) |
+| `restOptions.controllerOpts.requireAuthenticatedSignUp` | `boolean` | Whether sign-up requires authentication (default: `false`) |
+| `restOptions.controllerOpts.payload` | `object` | Custom Zod schemas for request/response payloads |
+| `alwaysAllowPaths` | `string[]` | Array of paths that bypass authentication |
+| `tokenOptions` | `IJWTTokenServiceOptions` | JWT token configuration |
+
 ## Architecture Components
 
--   **`AuthenticateComponent`**: Registers all necessary services and controllers
+-   **`AuthenticateComponent`**: Registers all necessary services and optionally the authentication controller
 -   **`AuthenticationStrategyRegistry`**: Singleton managing authentication strategies
 -   **`JWTAuthenticationStrategy`**: JWT strategy implementation using `JWTTokenService`
--   **`JWTTokenService`**: Generates, verifies, encrypts/decrypts JWT payloads
+-   **`JWTTokenService`**: Generates, verifies, encrypts/decrypts JWT payloads (handles undefined/null values safely)
+-   **`defineAuthController`**: Factory function to create customizable authentication controller
 -   **Protected Routes**: Use `authStrategies` in route configs to secure endpoints
 
 ## Implementation Details
@@ -62,6 +77,8 @@ APP_ENV_JWT_EXPIRES_IN=86400
 
 In `src/application.ts`, register the `AuthenticateComponent` and the `JWTAuthenticationStrategy`. You also need to provide an `AuthenticationService`.
 
+**Basic Setup (without built-in auth controller):**
+
 ```typescript
 // src/application.ts
 import {
@@ -79,7 +96,116 @@ export class Application extends BaseApplication {
 
   registerAuth() {
     this.service(AuthenticationService);
-    this.component(AuthenticateComponent);
+    this.component(AuthenticateComponent, {
+      restOptions: {
+        useAuthController: false, // Default: controller not registered
+      },
+      alwaysAllowPaths: [],
+      tokenOptions: {
+        applicationSecret: process.env.APP_ENV_APPLICATION_SECRET,
+        jwtSecret: process.env.APP_ENV_JWT_SECRET,
+        getTokenExpiresFn: () => Number(process.env.APP_ENV_JWT_EXPIRES_IN || 86400),
+      },
+    });
+    AuthenticationStrategyRegistry.getInstance().register({
+      container: this,
+      name: Authentication.STRATEGY_JWT,
+      strategy: JWTAuthenticationStrategy,
+    });
+  }
+
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.registerAuth();
+    // ...
+  }
+}
+```
+
+**Advanced Setup (with built-in auth controller):**
+
+```typescript
+import {
+  AuthenticateComponent,
+  Authentication,
+  AuthenticationStrategyRegistry,
+  JWTAuthenticationStrategy,
+  BaseApplication,
+  ValueOrPromise,
+} from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+import { AuthenticationService } from './services';
+
+export class Application extends BaseApplication {
+  // ...
+
+  registerAuth() {
+    this.service(AuthenticationService);
+    this.component(AuthenticateComponent, {
+      restOptions: {
+        useAuthController: true, // Enable built-in auth controller
+        controllerOpts: {
+          restPath: '/auth', // Base path for auth endpoints
+          serviceKey: 'services.AuthenticationService', // Default service key
+          requireAuthenticatedSignUp: false, // Whether sign-up requires authentication
+          payload: {
+            signIn: {
+              request: { 
+                schema: z.object({
+                  identifier: z.object({
+                    type: z.string(),
+                    value: z.string(),
+                  }),
+                  credential: z.object({
+                    type: z.string(),
+                    value: z.string(),
+                  }),
+                })
+              },
+              response: { 
+                schema: z.object({
+                  token: z.string(),
+                })
+              },
+            },
+            signUp: {
+              request: { 
+                schema: z.object({
+                  username: z.string(),
+                  email: z.string().email(),
+                  password: z.string().min(8),
+                })
+              },
+              response: { 
+                schema: z.object({
+                  token: z.string(),
+                  userId: z.string(),
+                })
+              },
+            },
+            changePassword: {
+              request: { 
+                schema: z.object({
+                  oldPassword: z.string(),
+                  newPassword: z.string().min(8),
+                })
+              },
+              response: { 
+                schema: z.object({
+                  success: z.boolean(),
+                })
+              },
+            },
+          },
+        },
+      },
+      alwaysAllowPaths: [],
+      tokenOptions: {
+        applicationSecret: process.env.APP_ENV_APPLICATION_SECRET,
+        jwtSecret: process.env.APP_ENV_JWT_SECRET,
+        getTokenExpiresFn: () => Number(process.env.APP_ENV_JWT_EXPIRES_IN || 86400),
+      },
+    });
     AuthenticationStrategyRegistry.getInstance().register({
       container: this,
       name: Authentication.STRATEGY_JWT,
@@ -110,6 +236,7 @@ import {
   IJWTTokenPayload,
   JWTTokenService,
   TSignInRequest,
+  getError,
 } from '@venizia/ignis';
 import { Context } from 'hono';
 
@@ -130,7 +257,7 @@ export class AuthenticationService extends BaseService implements IAuthService {
     const user = { id: 'user-id-from-db', roles: [] }; // Dummy user
 
     if (identifier.value !== 'test_username' || credential.value !== 'test_password') {
-      throw new Error('Invalid credentials');
+      throw getError({ message: 'Invalid credentials' });
     }
     // --- End of custom logic ---
 
@@ -146,19 +273,107 @@ export class AuthenticationService extends BaseService implements IAuthService {
 
   async signUp(context: Context, opts: any): Promise<any> {
     // Implement your sign-up logic
-    throw new Error('Method not implemented.');
+    throw getError({ message: 'Method not implemented.' });
   }
 
   async changePassword(context: Context, opts: any): Promise<any> {
     // Implement your change password logic
-    throw new Error('Method not implemented.');
+    throw getError({ message: 'Method not implemented.' });
   }
 }
 ```
 
 This service is then registered in `application.ts` as shown in the previous step. It injects the `JWTTokenService` (provided by the `AuthenticateComponent`) to generate a token upon successful sign-in.
 
-#### 3. Securing Routes
+#### 3. Custom Authentication Controller (Optional)
+
+If you need more control over the authentication endpoints, you can create a custom controller using the `defineAuthController` factory function.
+
+```typescript
+// src/controllers/custom-auth.controller.ts
+import { defineAuthController } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+
+export const CustomAuthController = defineAuthController({
+  restPath: '/api/auth',
+  serviceKey: 'services.AuthenticationService',
+  requireAuthenticatedSignUp: true, // Require authentication for sign-up
+  payload: {
+    signIn: {
+      request: {
+        schema: z.object({
+          email: z.string().email(),
+          password: z.string(),
+        }),
+      },
+      response: {
+        schema: z.object({
+          token: z.string(),
+          expiresIn: z.number(),
+        }),
+      },
+    },
+    signUp: {
+      request: {
+        schema: z.object({
+          email: z.string().email(),
+          password: z.string().min(8),
+          firstName: z.string(),
+          lastName: z.string(),
+        }),
+      },
+      response: {
+        schema: z.object({
+          token: z.string(),
+          userId: z.string(),
+        }),
+      },
+    },
+    changePassword: {
+      request: {
+        schema: z.object({
+          currentPassword: z.string(),
+          newPassword: z.string().min(8),
+        }),
+      },
+      response: {
+        schema: z.object({
+          success: z.boolean(),
+          message: z.string().optional(),
+        }),
+      },
+    },
+  },
+});
+```
+
+Then register it in your application:
+
+```typescript
+// src/application.ts
+import { CustomAuthController } from './controllers/custom-auth.controller';
+
+export class Application extends BaseApplication {
+  registerAuth() {
+    this.service(AuthenticationService);
+    this.component(AuthenticateComponent, {
+      restOptions: { useAuthController: false }, // Disable built-in controller
+      // ... other options
+    });
+    
+    // Register your custom controller
+    this.controller(CustomAuthController);
+    
+    AuthenticationStrategyRegistry.getInstance().register({
+      container: this,
+      name: Authentication.STRATEGY_JWT,
+      strategy: JWTAuthenticationStrategy,
+    });
+  }
+}
+```
+
+#### 4. Securing Routes
 
 In your controllers, use decorator-based routing (`@get`, `@post`, etc.) with the `authStrategies` property in the `configs` object to protect endpoints. This will automatically run the necessary authentication middlewares and attach the authenticated user to the Hono `Context`, which can then be accessed type-safely using `TRouteContext`.
 
@@ -199,12 +414,15 @@ export class TestController extends BaseController {
   secureData(c: TRouteContext<typeof SECURE_ROUTE_CONFIG>) {
     // 'c' is fully typed here, including c.get and c.json return type
     const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload | undefined;
-    return c.json({ message: `Hello, ${user?.userId || 'guest'} from protected data` });
+    return c.json(
+      { message: `Hello, ${user?.userId || 'guest'} from protected data` },
+      HTTP.ResultCodes.RS_2.Ok,
+    );
   }
 }
 ```
 
-#### 4. Accessing the Current User in Context
+#### 5. Accessing the Current User in Context
 
 After a route has been processed, the authenticated user's payload is available directly on the Hono `Context` object, using the `Authentication.CURRENT_USER` key.
 

package/wiki/references/components/health-check.md

@@ -127,7 +127,7 @@ export class HealthCheckController extends BaseController {
 
   @api({ configs: ROUTE_CONFIGS['/'] })
   checkHealth(c: TRouteContext<typeof ROUTE_CONFIGS['/']>) {
-    return c.json({ status: 'ok' });
+    return c.json({ status: 'ok' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
   @api({ configs: ROUTE_CONFIGS['/ping'] })

package/wiki/references/components/index.md

@@ -1,6 +1,6 @@
 # Components
 
-Reusable, pluggable modules that encapsulate specific features in Ignis applications.
+Reusable, pluggable modules that group together related features. A component can encapsulate various resources such as providers, services, controllers, repositories, or even an entire mini-application, providing a clean way to modularize and share complex logic across Ignis applications.
 
 ## Built-in Components
 

package/wiki/references/components/swagger.md

@@ -158,7 +158,7 @@ export class HelloController extends BaseController {
         },
       },
       handler: (c) => {
-        return c.json({ message: 'Hello, `Ignis`!' });
+        return c.json({ message: 'Hello, `Ignis`!' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
   }

package/wiki/references/helpers/error.md

@@ -26,10 +26,10 @@ Extends native `Error` with HTTP status codes and machine-readable message codes
 You can create a new `ApplicationError` with a message, status code, and an optional message code.
 
 ```typescript
-import { ApplicationError, HTTP } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis';
 
 // Throw an error for a resource not found
-throw new ApplicationError({
+throw getError({
   message: 'User not found',
   statusCode: HTTP.ResultCodes.RS_4.NotFound,
   messageCode: 'USER_NOT_FOUND',

package/wiki/references/helpers/inversion.md

@@ -2,7 +2,12 @@
 
 Core DI system enabling loosely coupled, testable, and extensible code.
 
-> **Package Architecture Note:** The core DI container functionality has been extracted to a standalone package `@venizia/ignis-inversion`. The `@venizia/ignis-helpers` package extends and re-exports this functionality with application-specific enhancements (logging, framework metadata). All imports from `@venizia/ignis-helpers` or `@venizia/ignis` continue to work as before - backward compatibility is maintained.
+> **Architecture Update:** The core DI container functionality has been extracted to a standalone package `@venizia/ignis-inversion`.
+>
+> *   **Standalone Container:** `@venizia/ignis-inversion` (Generic DI)
+> *   **Framework Integration:** `@venizia/ignis` (extends Core DI with Framework Metadata)
+>
+> Previously, this module resided in `@venizia/ignis-helpers`. It has now been moved to **Core** (`@venizia/ignis`) to better align with the framework architecture.
 
 ## Quick Reference
 
@@ -141,11 +146,11 @@ export class UserController extends BaseController {
 The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a singleton class responsible for storing and retrieving all the metadata attached by decorators like `@inject`, `@controller`, `@get`, etc.
 
 -   **Base File:** `packages/inversion/src/registry.ts` (core MetadataRegistry)
--   **Extended File:** `packages/helpers/src/helpers/inversion/registry.ts` (with framework metadata)
+-   **Extended File:** `packages/core/src/helpers/inversion/registry.ts` (with framework metadata)
 
 ### Role in DI
 
 -   When you use a decorator (e.g., `@inject`), it calls a method on the `MetadataRegistry.getInstance()` to store information about the injection (like the binding key and target property/parameter).
 -   When the `Container` instantiates a class, it queries the `MetadataRegistry` to find out which dependencies need to be injected and where.
 
-You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.
+You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.