@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/references/base/components.md

@@ -6,7 +6,7 @@ difficulty: advanced
 
 # Deep Dive: Components
 
-Technical reference for `BaseComponent`—the foundation for creating reusable, pluggable features in Ignis. Components are powerful containers that can group together multiple providers, services, controllers, repositories, and even entire mini-applications into a single, redistributable module.
+Technical reference for `BaseComponent`-the foundation for creating reusable, pluggable features in IGNIS. Components are powerful containers that can group together multiple providers, services, controllers, repositories, and even entire mini-applications into a single, redistributable module.
 
 **File:** `packages/core/src/base/components/base.ts`
 
@@ -17,7 +17,7 @@ Technical reference for `BaseComponent`—the foundation for creating reusable,
 | **Encapsulation** | Bundle feature bindings (services, controllers) into single class |
 | **Lifecycle Management** | Auto-called `binding()` method during startup |
 | **Default Bindings** | Self-contained with automatic DI registration |
-| **Idempotent Configure** | `configure()` is safe to call multiple times — runs `binding()` only once |
+| **Idempotent Configure** | `configure()` is safe to call multiple times - runs `binding()` only once |
 | **Controller Transports** | `RestComponent` and `GrpcComponent` handle controller discovery per transport |
 
 
@@ -52,29 +52,42 @@ src/components/auth/
 │   │   ├── index.ts
 │   │   ├── keys.ts
 │   │   ├── types.ts
-│   │   └── constants.ts
+│   │   ├── constants.ts
+│   │   └── codecs.ts
 │   ├── controllers/
 │   │   ├── index.ts
-│   │   └── auth.controller.ts
+│   │   ├── factory.ts
+│   │   └── jwks/
+│   ├── middlewares/
+│   ├── providers/
 │   ├── services/
 │   │   ├── index.ts
-│   │   └── jwt-token.service.ts
+│   │   ├── basic/
+│   │   └── bearer/
+│   │       ├── jws.service.ts
+│   │       └── jwks/
 │   └── strategies/
 │       ├── index.ts
-│       ├── jwt.strategy.ts
-│       └── basic.strategy.ts
+│       ├── jws.strategy.ts
+│       ├── jwks.strategy.ts
+│       ├── basic.strategy.ts
+│       └── strategy-registry.ts
 └── models/
     ├── index.ts
     ├── entities/
-    │   └── user-token.model.ts
+    │   ├── user.model.ts
+    │   ├── role.model.ts
+    │   ├── permission.model.ts
+    │   └── policy-definition.model.ts
     └── requests/
         ├── sign-in.schema.ts
-        └── sign-up.schema.ts
+        ├── sign-up.schema.ts
+        └── change-password.schema.ts
 ```
 
 ### Controller Transport Component
 
-Transport components live under `src/components/controller/` and are instantiated directly by the application during `registerControllers()` — they are **not** registered via `this.component()`.
+Transport components live under `src/components/controller/` and are instantiated directly by the application during `registerControllers()` - they are **not** registered via `this.component()`.
 
 ```
 src/components/controller/
@@ -110,14 +123,16 @@ export class HealthCheckBindingKeys {
 ```typescript
 // src/components/auth/authenticate/common/keys.ts
 export class AuthenticateBindingKeys {
-  static readonly AUTHENTICATE_OPTIONS = '@app/authenticate/options';
-  static readonly JWT_OPTIONS = '@app/authenticate/jwt/options';
+  static readonly REST_OPTIONS = '@app/authenticate/rest-options';
+  static readonly JWT_OPTIONS = '@app/authenticate/jwt-options';
+  static readonly JWKS_OPTIONS = '@app/authenticate/jwks-options';
+  static readonly BASIC_OPTIONS = '@app/authenticate/basic-options';
 }
 ```
 
 **Naming Convention:**
 - Class name: `[Feature]BindingKeys`
-- Key format: `@app/[component]/[feature]` or `@app/[component]/[sub-feature]/[name]`
+- Key format: `@app/[component]/[feature]`
 
 ### 2. Types (`types.ts`)
 
@@ -134,38 +149,49 @@ export interface IHealthCheckOptions {
 
 ```typescript
 // src/components/auth/authenticate/common/types.ts
-import { Context } from 'hono';
-import { AnyObject, ValueOrPromise } from '@venizia/ignis-helpers';
+import { AnyObject } from '@venizia/ignis-helpers';
+import { Env } from 'hono';
 
 // Options interface for the component
 export interface IAuthenticateOptions {
-  jwtOptions?: IJWTTokenServiceOptions;
-  basicOptions?: IBasicTokenServiceOptions;
-  restOptions?: {
-    useAuthController?: boolean;
-    controllerOpts?: TDefineAuthControllerOpts;
-  };
+  restOptions?: TAuthenticationRestOptions;
+  jwtOptions?: TJWTTokenServiceOptions;
+  basicOptions?: TBasicTokenServiceOptions;
 }
 
-// Service options interface
-export interface IJWTTokenServiceOptions {
-  jwtSecret: string;
-  applicationSecret: string;
-  getTokenExpiresFn: () => ValueOrPromise<number>;
-}
+// Service options type (JWS or JWKS)
+export type TJWTTokenServiceOptions =
+  | { standard: typeof JOSEStandards.JWS; options: IJWSTokenServiceOptions }
+  | { standard: typeof JOSEStandards.JWKS; options: TJWKSTokenServiceOptions };
 
 // Service contract interface
 export interface IAuthService<
-  SIRQ = AnyObject,
+  E extends Env = Env,
+  // SignIn types
+  SIRQ extends TSignInRequest = TSignInRequest,
   SIRS = AnyObject,
+  // SignUp types
+  SURQ extends TSignUpRequest = TSignUpRequest,
+  SURS = AnyObject,
+  // ChangePassword types
+  CPRQ extends TChangePasswordRequest = TChangePasswordRequest,
+  CPRS = AnyObject,
+  // UserInformation types
+  UIRQ = AnyObject,
+  UIRS = AnyObject,
+  // RefreshToken types
+  RTRS = AnyObject,
 > {
-  signIn(context: Context, opts: SIRQ): Promise<SIRS>;
-  signUp(context: Context, opts: SIRQ): Promise<SIRS>;
+  signIn(context: TContext<E>, opts: SIRQ): Promise<SIRS>;
+  signUp(context: TContext<E>, opts: SURQ): Promise<SURS>;
+  changePassword(context: TContext<E>, opts: CPRQ): Promise<CPRS>;
+  getUserInformation?(context: TContext<E>, opts: UIRQ): Promise<UIRS>;
+  refreshToken?(context: TContext<E>): Promise<RTRS>;
 }
 
 // Auth user type
 export interface IAuthUser {
-  userId: string;
+  userId: IdType;
   [extra: string | symbol]: any;
 }
 ```
@@ -198,9 +224,7 @@ export class Authentication {
 **With validation (for user-configurable values):**
 
 ```typescript
-// src/components/swagger/common/constants.ts
-import { TConstValue } from '@venizia/ignis-helpers';
-
+// src/components/api-reference/common/constants.ts
 export class DocumentUITypes {
   static readonly SWAGGER = 'swagger';
   static readonly SCALAR = 'scalar';
@@ -214,6 +238,9 @@ export class DocumentUITypes {
   }
 }
 
+// src/components/api-reference/common/types.ts
+import { TConstValue } from '@venizia/ignis-helpers';
+
 // Extract union type: 'swagger' | 'scalar'
 export type TDocumentUIType = TConstValue<typeof DocumentUITypes>;
 ```
@@ -227,7 +254,6 @@ Define route path constants for controllers.
 export class HealthCheckRestPaths {
   static readonly ROOT = '/';
   static readonly PING = '/ping';
-  static readonly METRICS = '/metrics';
 }
 ```
 
@@ -269,7 +295,7 @@ The `super()` constructor in your component can take the following options:
 | Option | Type | Description |
 | :--- | :--- | :--- |
 | `scope` | `string` | **Required.** A unique name for the component, typically `MyComponent.name`. Used for logging. |
-| `initDefault` | `{ enable: false } \| { enable: true; container: Container }` | If `enable` is `true`, the `bindings` defined below will be automatically registered with the provided `container` (usually the application instance) when `configure()` is called — but only if they are not already bound. Defaults to `{ enable: false }`. |
+| `initDefault` | `{ enable: false } \| { enable: true; container: Container }` | If `enable` is `true`, the `bindings` defined below will be automatically registered with the provided `container` (usually the application instance) when `configure()` is called - but only if they are not already bound. Defaults to `{ enable: false }`. |
 | `bindings` | `Record<string \| symbol, Binding>` | An object where keys are binding keys and values are `Binding` instances. These are the default services, values, or providers that your component offers. Defaults to `{}`. |
 
 ### Properties
@@ -278,14 +304,14 @@ The `super()` constructor in your component can take the following options:
 | :--- | :--- | :--- | :--- |
 | `bindings` | `Record<string \| symbol, Binding>` | `protected` | Default bindings the component provides. Can be set in constructor or assigned directly in the constructor body. |
 | `initDefault` | `TInitDefault` | `protected` | Controls whether default bindings are auto-registered to a container. |
-| `isConfigured` | `boolean` | `protected` | Guard flag — prevents `configure()` from running more than once. |
+| `isConfigured` | `boolean` | `protected` | Guard flag - prevents `configure()` from running more than once. |
 
 ### Methods
 
 | Method | Signature | Description |
 | :--- | :--- | :--- |
 | `binding()` | `abstract binding(): ValueOrPromise<void>` | **Abstract.** Override this to register services, controllers, and other resources. Called by `configure()`. |
-| `configure(opts?)` | `async configure(opts?: ConfigurableOptions): Promise<void>` | Entry point. Calls `initDefaultBindings()` (if enabled), then `binding()`. Idempotent — skips if already configured. |
+| `configure(opts?)` | `async configure(opts?: ConfigurableOptions): Promise<void>` | Entry point. Calls `initDefaultBindings()` (if enabled), then `binding()`. Idempotent - skips if already configured. |
 | `initDefaultBindings(opts)` | `protected initDefaultBindings(opts: { container: Container }): void` | Iterates `this.bindings` and registers each into the container if not already bound. |
 
 ### Lifecycle Flow
@@ -440,7 +466,7 @@ export class GrpcBindingKeys {
 }
 ```
 
-> **Note:** `GrpcComponent` is excluded from the barrel export at `src/components/controller/index.ts`. Import it directly from `@venizia/ignis/components/controller/grpc` if needed.
+> **Note:** `GrpcComponent` is excluded from the barrel export at `src/components/controller/index.ts`. You never import it in application code - `BaseApplication.registerControllers()` instantiates it automatically when `transports` includes `'grpc'`.
 
 
 ## Component Implementation Patterns
@@ -449,7 +475,7 @@ export class GrpcBindingKeys {
 
 ```typescript
 // src/components/health-check/component.ts
-import { BaseApplication, BaseComponent, inject, CoreBindings, Binding, ValueOrPromise } from '@venizia/ignis';
+import { BaseApplication, BaseComponent, controller, inject, CoreBindings, Binding, ValueOrPromise } from '@venizia/ignis';
 import { HealthCheckBindingKeys, IHealthCheckOptions } from './common';
 import { HealthCheckController } from './controller';
 
@@ -501,16 +527,15 @@ export class HealthCheckComponent extends BaseComponent {
 // src/components/auth/authenticate/component.ts
 import { BaseApplication, BaseComponent, inject, CoreBindings, Binding, ValueOrPromise } from '@venizia/ignis';
 import { getError } from '@venizia/ignis-helpers';
-import { AuthenticateBindingKeys, IAuthenticateOptions, IBasicTokenServiceOptions, IJWTTokenServiceOptions } from './common';
-import { BasicTokenService, JWTTokenService } from './services';
+import {
+  AuthenticateBindingKeys,
+  TAuthenticationRestOptions,
+  TBasicTokenServiceOptions,
+  TJWTTokenServiceOptions,
+} from './common';
+import { BasicTokenService, JWSTokenService } from './services';
 import { defineAuthController } from './controllers';
 
-const DEFAULT_OPTIONS: IAuthenticateOptions = {
-  restOptions: {
-    useAuthController: false,
-  },
-};
-
 export class AuthenticateComponent extends BaseComponent {
   constructor(
     @inject({ key: CoreBindings.APPLICATION_INSTANCE })
@@ -519,66 +544,63 @@ export class AuthenticateComponent extends BaseComponent {
     super({
       scope: AuthenticateComponent.name,
       initDefault: { enable: true, container: application },
+      // Only restOptions gets a default here - jwtOptions/basicOptions are
+      // bound separately (by the app, before registration) since at least one is required.
       bindings: {
-        [AuthenticateBindingKeys.AUTHENTICATE_OPTIONS]: Binding.bind<IAuthenticateOptions>({
-          key: AuthenticateBindingKeys.AUTHENTICATE_OPTIONS,
-        }).toValue(DEFAULT_OPTIONS),
+        [AuthenticateBindingKeys.REST_OPTIONS]: Binding.bind<TAuthenticationRestOptions>({
+          key: AuthenticateBindingKeys.REST_OPTIONS,
+        }).toValue({ useAuthController: false }),
       },
     });
   }
 
-  // Validate at least one auth option is provided
-  private validateOptions(opts: IAuthenticateOptions): void {
-    if (!opts.jwtOptions && !opts.basicOptions) {
+  override binding(): ValueOrPromise<void> {
+    const jwtOptions = this.application.get<TJWTTokenServiceOptions>({
+      key: AuthenticateBindingKeys.JWT_OPTIONS,
+      isOptional: true,
+    });
+    const basicOptions = this.application.get<TBasicTokenServiceOptions>({
+      key: AuthenticateBindingKeys.BASIC_OPTIONS,
+      isOptional: true,
+    });
+
+    if (!jwtOptions && !basicOptions) {
       throw getError({
         message: '[AuthenticateComponent] At least one of jwtOptions or basicOptions must be provided',
       });
     }
-  }
 
-  // Configure JWT authentication if jwtOptions is provided
-  private defineJWTAuth(opts: IAuthenticateOptions): void {
-    if (!opts.jwtOptions) return;
-
-    this.application
-      .bind<IJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS })
-      .toValue(opts.jwtOptions);
-    this.application.service(JWTTokenService);
-  }
-
-  // Configure Basic authentication if basicOptions is provided
-  private defineBasicAuth(opts: IAuthenticateOptions): void {
-    if (!opts.basicOptions) return;
-
-    this.application
-      .bind<IBasicTokenServiceOptions>({ key: AuthenticateBindingKeys.BASIC_OPTIONS })
-      .toValue(opts.basicOptions);
-    this.application.service(BasicTokenService);
-  }
-
-  // Configure auth controllers if enabled
-  private defineControllers(opts: IAuthenticateOptions): void {
-    if (!opts.restOptions?.useAuthController) return;
-
-    // Auth controller requires JWT for token generation
-    if (!opts.jwtOptions) {
-      throw getError({
-        message: '[defineControllers] Auth controller requires jwtOptions to be configured',
-      });
+    // JWT auth supports both JWS (shared-secret) and JWKS (issuer/verifier) standards -
+    // see the real component for the full switch over `jwtOptions.standard`.
+    if (jwtOptions) {
+      this.application
+        .bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS })
+        .toValue(jwtOptions);
+      this.application.service(JWSTokenService);
     }
 
-    this.application.controller(defineAuthController(opts.restOptions.controllerOpts));
-  }
+    if (basicOptions) {
+      this.application
+        .bind<TBasicTokenServiceOptions>({ key: AuthenticateBindingKeys.BASIC_OPTIONS })
+        .toValue(basicOptions);
+      this.application.service(BasicTokenService);
+    }
 
-  override binding(): ValueOrPromise<void> {
-    const options = this.application.get<IAuthenticateOptions>({
-      key: AuthenticateBindingKeys.AUTHENTICATE_OPTIONS,
+    const restOptions = this.application.get<TAuthenticationRestOptions>({
+      key: AuthenticateBindingKeys.REST_OPTIONS,
+      isOptional: true,
     });
 
-    this.validateOptions(options);
-    this.defineJWTAuth(options);
-    this.defineBasicAuth(options);
-    this.defineControllers(options);
+    if (restOptions?.useAuthController) {
+      // Auth controller requires JWT for token generation
+      if (!jwtOptions) {
+        throw getError({
+          message: '[AuthenticateComponent] Auth controller requires jwtOptions to be configured',
+        });
+      }
+
+      this.application.controller(defineAuthController(restOptions.controllerOpts));
+    }
   }
 }
 ```
@@ -588,7 +610,7 @@ export class AuthenticateComponent extends BaseComponent {
 When controllers need to be dynamically configured:
 
 ```typescript
-// src/components/static-asset/component.ts
+// src/components/static-asset/component.ts (condensed)
 override binding(): ValueOrPromise<void> {
   const componentOptions = this.application.get<TStaticAssetsComponentOptions>({
     key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
@@ -596,18 +618,24 @@ override binding(): ValueOrPromise<void> {
 
   // Create multiple controllers from configuration
   for (const [key, opt] of Object.entries(componentOptions)) {
+    const { storage, controller, helper, extra } = opt;
+
     this.application.controller(
       AssetControllerFactory.defineAssetController({
-        controller: opt.controller,
-        storage: opt.storage,
-        helper: opt.helper,
+        controller,
+        storage,
+        helper,
+        useMetaLink: opt.useMetaLink,
+        metaLink: opt.useMetaLink ? opt.metaLink : undefined,
+        options: { ...extra /* , normalizeLinkFn fallback */ },
       }),
     );
 
     this.application.logger.info(
-      '[binding] Asset storage bound | Key: %s | Type: %s',
+      `[binding] Asset storage is bound | Key: %s | Storage type: %s | UseMetaLink: %s`,
       key,
-      opt.storage,
+      storage,
+      Boolean(opt.useMetaLink),
     );
   }
 }
@@ -615,30 +643,31 @@ override binding(): ValueOrPromise<void> {
 
 ### Component without `initDefault` (Manual Binding Assignment)
 
-Some components skip `initDefault` and assign `this.bindings` directly in the constructor body:
+A component may instead declare its defaults but NOT register them, by omitting `initDefault` and assigning `this.bindings` in the constructor body:
 
 ```typescript
-// src/components/swagger/component.ts
-export class SwaggerComponent extends BaseComponent {
+export class CustomComponent extends BaseComponent {
   constructor(
     @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
   ) {
-    super({ scope: SwaggerComponent.name });
+    super({ scope: CustomComponent.name });
 
     this.bindings = {
-      [SwaggerBindingKeys.SWAGGER_OPTIONS]: Binding.bind<ISwaggerOptions>({
-        key: SwaggerBindingKeys.SWAGGER_OPTIONS,
-      }).toValue(DEFAULT_SWAGGER_OPTIONS),
+      [CustomBindingKeys.OPTIONS]: Binding.bind<ICustomOptions>({
+        key: CustomBindingKeys.OPTIONS,
+      }).toValue(DEFAULT_CUSTOM_OPTIONS),
     };
   }
 
   override async binding() {
-    // Read options, configure OpenAPI doc endpoint, UI endpoint, etc.
+    // Read options, then wire the component's routes/services.
   }
 }
 ```
 
-In this pattern, `initDefault` defaults to `{ enable: false }`, so the bindings are defined but not auto-registered. The component manages its own option reading and setup in `binding()`.
+With `initDefault` omitted it defaults to `{ enable: false }`, so the bindings are defined but not auto-registered - the component takes over its own option reading and setup in `binding()`.
+
+The shipped `ApiReferenceComponent` does **not** use this pattern: it passes `initDefault: { enable: true, container: application }` and its `bindings` through `super()`, so its default `IApiReferenceOptions` binding lands in the container immediately (see [API Reference](/extensions/components/api-reference)).
 
 
 ## Built-in Components
@@ -648,19 +677,19 @@ In this pattern, `initDefault` defaults to `{ enable: false }`, so the bindings
 | Component | Key Features |
 |-----------|-------------|
 | **HealthCheckComponent** | `GET /health` (default path, configurable). Registers `HealthCheckController` with `GET /` and `POST /ping` endpoints. |
-| **SwaggerComponent** | OpenAPI doc at `/doc/openapi.json`, UI at `/doc/explorer` (Scalar by default, Swagger UI also supported). Auto-populates app info and server URL. Registers JWT and Basic security schemes. |
-| **AuthenticateComponent** | JWT and/or Basic auth strategies. Optional auth controller (`signIn`/`signUp`). Token services (`JWTTokenService`, `BasicTokenService`). |
-| **AuthorizationComponent** | Casbin-based RBAC, permission mapping, `authorize()` middleware. |
+| **ApiReferenceComponent** | OpenAPI doc at `/doc/openapi.json`, UI at `/doc/explorer` (Scalar by default, Swagger UI also supported). Auto-populates app info and server URL. Registers JWT and Basic security schemes. |
+| **AuthenticateComponent** | JWT and/or Basic auth strategies. Optional auth controller (`signIn`/`signUp`). Token services (`JWSTokenService`, `BasicTokenService`). |
+| **AuthorizeComponent** | Casbin-based RBAC, permission mapping, `authorize()` middleware. |
 | **RequestTrackerComponent** | Registers Hono `requestId()` middleware and a `RequestSpyMiddleware` for `x-request-id` header tracking and request body parsing. |
 
 ### Excluded from Barrel (Import Directly)
 
 | Component | Import Path | Key Features |
 |-----------|-------------|-------------|
-| **StaticAssetComponent** | `@venizia/ignis/components/static-asset` | File upload/download CRUD, MinIO/Disk storage. |
-| **MailComponent** | `@venizia/ignis/components/mail` | Nodemailer/Mailgun transporters, Direct/BullMQ/InternalQueue executors. |
-| **SocketIOComponent** | `@venizia/ignis/components/socket-io` | Socket.IO server with Redis adapter for horizontal scaling. |
-| **WebSocketComponent** | `@venizia/ignis/components/websocket` | WebSocket support. |
+| **StaticAssetComponent** | `@venizia/ignis/static-asset` | File upload/download CRUD, MinIO/Disk storage. |
+| **MailComponent** | `@venizia/ignis/mail` | Nodemailer/Mailgun transporters, Direct/BullMQ/InternalQueue executors. |
+| **SocketIOComponent** | `@venizia/ignis/socket-io` | Socket.IO server with Redis adapter for horizontal scaling. |
+| **WebSocketComponent** | `@venizia/ignis/websocket` | WebSocket support. |
 
 ### Controller Transport Components (Not Registered via `this.component()`)
 
@@ -719,13 +748,13 @@ For complex nested configurations:
 
 ```typescript
 override binding(): ValueOrPromise<void> {
-  const extraOptions = this.application.get<Partial<ISwaggerOptions>>({
-    key: SwaggerBindingKeys.SWAGGER_OPTIONS,
+  const extraOptions = this.application.get<Partial<IApiReferenceOptions>>({
+    key: ApiReferenceBindingKeys.API_REFERENCE_OPTIONS,
     isOptional: true,
   }) ?? {};
 
   // Deep merge nested objects
-  const options: ISwaggerOptions = {
+  const options: IApiReferenceOptions = {
     ...DEFAULT_OPTIONS,
     ...extraOptions,
     restOptions: {
@@ -754,7 +783,7 @@ override binding(): ValueOrPromise<void> {
 | **Validation** | Validate required options in `binding()` |
 | **Logging** | Log binding activity with structured messages |
 | **Scope** | Always set `scope: ComponentName.name` |
-| **Idempotency** | `configure()` is already idempotent via `isConfigured` guard — no need to add your own |
+| **Idempotency** | `configure()` is already idempotent via `isConfigured` guard - no need to add your own |
 
 
 ## Quick Reference Template
@@ -843,7 +872,7 @@ export * from './controller';
 - **Built-in Components:**
   - [Authentication Component](/extensions/components/authentication/) - JWT authentication
   - [Health Check Component](/extensions/components/health-check) - Health endpoints
-  - [Swagger Component](/extensions/components/swagger) - API documentation
+  - [Swagger Component](/extensions/components/api-reference) - API documentation
   - [Socket.IO Component](/extensions/components/socket-io/) - WebSocket support
 
 - **Best Practices:**