Skip to content

Commit 3eb1622

Browse files
tacxoutacxou
committed
feat: Add detailed JSDoc comments to Agents DTOs and AgentState enum for improved documentation
1 parent 4eeb7b0 commit 3eb1622

File tree

4 files changed

+388
-44
lines changed

4 files changed

+388
-44
lines changed

‎apps/api/src/core/agents/_dto/agents.dto.ts‎

Lines changed: 171 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,216 @@
1-
import { ApiProperty, PartialType } from '@nestjs/swagger';
2-
import { IsString, IsNotEmpty, ValidateNested, IsEmail, IsBoolean, IsMongoId, IsOptional } from 'class-validator';
3-
import { Type } from 'class-transformer';
4-
import { StatePartDTO } from './parts/state.part.dto';
5-
import { SecurityPartDTO } from './parts/security.part.dto';
6-
import { CustomFieldsDto } from '~/_common/abstracts/dto/custom-fields.dto';
1+
import { ApiProperty, PartialType } from '@nestjs/swagger'
2+
import { IsString, IsNotEmpty, ValidateNested, IsEmail, IsBoolean, IsMongoId, IsOptional } from 'class-validator'
3+
import { Type } from 'class-transformer'
4+
import { StatePartDTO } from './parts/state.part.dto'
5+
import { SecurityPartDTO } from './parts/security.part.dto'
6+
import { CustomFieldsDto } from '~/_common/abstracts/dto/custom-fields.dto'
77

8+
/**
9+
* DTO pour la création d'un agent.
10+
*
11+
* Ce DTO définit les données requises et optionnelles pour créer un nouvel agent
12+
* dans le système. Il inclut les validations nécessaires pour garantir l'intégrité
13+
* des données et hérite des fonctionnalités de champs personnalisés.
14+
*
15+
* @class AgentsCreateDto
16+
* @extends {CustomFieldsDto}
17+
*
18+
* @description
19+
* Données requises :
20+
* - username : Nom d'utilisateur unique
21+
* - email : Adresse email unique et valide
22+
* - password : Mot de passe (sera haché automatiquement avec Argon2)
23+
* - state : État de lifecycle de l'agent
24+
*
25+
* Données optionnelles :
26+
* - displayName : Nom d'affichage convivial
27+
* - thirdPartyAuth : Méthode d'authentification tierce
28+
* - baseURL : URL de base pour l'agent
29+
* - security : Configuration de sécurité (clés, restrictions, etc.)
30+
* - hidden : Indicateur de visibilité de l'agent
31+
* - customFields : Champs personnalisés additionnels (hérité)
32+
*
33+
* Note : Le mot de passe sera automatiquement haché et une clé secrète
34+
* sera générée lors de la création par le service AgentsService.
35+
*
36+
* @example
37+
* ```typescript
38+
* const createDto: AgentsCreateDto = {
39+
* username: "john.doe",
40+
* email: "john.doe@example.com",
41+
* password: "SecurePassword123!",
42+
* displayName: "John Doe",
43+
* state: { current: AgentState.PENDING },
44+
* baseURL: "/",
45+
* hidden: false
46+
* };
47+
* ```
48+
*/
849
export class AgentsCreateDto extends CustomFieldsDto {
9-
// @IsMongoId()
10-
// @IsNotEmpty()
11-
// @ApiProperty({ type: String })
12-
// public entityId: string
13-
50+
/**
51+
* Nom d'utilisateur unique de l'agent.
52+
*
53+
* @type {string}
54+
* @required
55+
*/
1456
@IsString()
1557
@IsNotEmpty()
1658
@ApiProperty()
17-
public username: string;
59+
public username: string
1860

61+
/**
62+
* Nom d'affichage de l'agent.
63+
*
64+
* @type {string}
65+
* @optional
66+
*/
1967
@IsString()
2068
@IsOptional()
2169
@ApiProperty()
22-
public displayName?: string;
70+
public displayName?: string
2371

72+
/**
73+
* Adresse email unique de l'agent.
74+
* Doit être une adresse email valide.
75+
*
76+
* @type {string}
77+
* @required
78+
*/
2479
@IsEmail()
2580
@IsNotEmpty()
2681
@ApiProperty()
27-
public email: string;
82+
public email: string
2883

84+
/**
85+
* Mot de passe de l'agent.
86+
* Sera automatiquement haché avec Argon2 avant stockage.
87+
*
88+
* @type {string}
89+
* @required
90+
*/
2991
@IsString()
3092
@IsNotEmpty()
3193
@ApiProperty()
32-
public password: string;
94+
public password: string
3395

96+
/**
97+
* Méthode d'authentification tierce.
98+
*
99+
* @type {string}
100+
* @optional
101+
* @default "local"
102+
* @example "local", "oauth2", "saml"
103+
*/
34104
@IsString()
35105
@IsOptional()
36106
@ApiProperty()
37-
public thirdPartyAuth?: string;
107+
public thirdPartyAuth?: string
38108

109+
/**
110+
* État de lifecycle de l'agent.
111+
*
112+
* @type {StatePartDTO}
113+
* @required
114+
*/
39115
@ValidateNested()
40116
@Type(() => StatePartDTO)
41117
@IsNotEmpty()
42118
@ApiProperty({ type: StatePartDTO })
43-
public state: StatePartDTO;
119+
public state: StatePartDTO
44120

121+
/**
122+
* URL de base pour l'agent.
123+
*
124+
* @type {string}
125+
* @optional
126+
* @default "/"
127+
*/
45128
@IsString()
46129
@IsOptional()
47130
@ApiProperty()
48-
public baseURL?: string;
49-
50-
// @IsArray()
51-
// @IsString({ each: true })
52-
// @ApiProperty({ type: [String] })
53-
// public roles: string[];
131+
public baseURL?: string
54132

133+
/**
134+
* Configuration de sécurité de l'agent.
135+
* Contient les clés, restrictions et paramètres de sécurité.
136+
*
137+
* @type {SecurityPartDTO}
138+
*/
55139
@ValidateNested()
56140
@Type(() => SecurityPartDTO)
57141
@ApiProperty({ type: SecurityPartDTO })
58-
public security: SecurityPartDTO;
142+
public security: SecurityPartDTO
59143

144+
/**
145+
* Indicateur de visibilité de l'agent.
146+
* Si true, l'agent est masqué dans les listes publiques.
147+
*
148+
* @type {boolean}
149+
* @optional
150+
*/
60151
@IsBoolean()
61152
@IsOptional()
62153
@ApiProperty()
63-
public hidden: boolean;
154+
public hidden: boolean
64155
}
65156

157+
/**
158+
* DTO représentant un agent complet avec son identifiant.
159+
*
160+
* Utilisé pour les réponses API qui retournent un agent existant.
161+
* Inclut toutes les propriétés de création plus l'identifiant MongoDB.
162+
*
163+
* @class AgentsDto
164+
* @extends {AgentsCreateDto}
165+
*
166+
* @example
167+
* ```typescript
168+
* const agent: AgentsDto = {
169+
* _id: "507f1f77bcf86cd799439011",
170+
* username: "john.doe",
171+
* email: "john.doe@example.com",
172+
* // ... autres propriétés
173+
* };
174+
* ```
175+
*/
66176
export class AgentsDto extends AgentsCreateDto {
177+
/**
178+
* Identifiant unique MongoDB de l'agent.
179+
*
180+
* @type {string}
181+
* @required
182+
*/
67183
@IsMongoId()
68184
@ApiProperty({ type: String })
69-
public _id: string;
185+
public _id: string
70186
}
71187

72-
export class AgentsUpdateDto extends PartialType(AgentsCreateDto) {}
188+
/**
189+
* DTO pour la mise à jour d'un agent.
190+
*
191+
* Toutes les propriétés d'AgentsCreateDto sont optionnelles pour permettre
192+
* des mises à jour partielles. Utilise PartialType de NestJS pour générer
193+
* automatiquement la version partielle du DTO de création.
194+
*
195+
* @class AgentsUpdateDto
196+
* @extends {PartialType(AgentsCreateDto)}
197+
*
198+
* @description
199+
* Note : Si le mot de passe est fourni dans les données de mise à jour,
200+
* il sera automatiquement re-haché par le service AgentsService.
201+
*
202+
* @example
203+
* ```typescript
204+
* // Mise à jour du nom d'affichage uniquement
205+
* const updateDto: AgentsUpdateDto = {
206+
* displayName: "John F. Doe"
207+
* };
208+
*
209+
* // Mise à jour de plusieurs champs
210+
* const updateDto: AgentsUpdateDto = {
211+
* displayName: "John F. Doe",
212+
* state: { current: AgentState.ACTIVE }
213+
* };
214+
* ```
215+
*/
216+
export class AgentsUpdateDto extends PartialType(AgentsCreateDto) { }

‎apps/api/src/core/agents/_dto/parts/security.part.dto.ts‎

Lines changed: 88 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,116 @@
1-
import { ApiProperty } from '@nestjs/swagger';
2-
import { IsString, IsArray, IsBoolean, IsOptional } from 'class-validator';
1+
import { ApiProperty } from '@nestjs/swagger'
2+
import { IsString, IsArray, IsBoolean, IsOptional } from 'class-validator'
33

4+
/**
5+
* DTO pour la partie sécurité d'un agent.
6+
*
7+
* Ce DTO définit les paramètres de sécurité d'un agent, incluant l'authentification
8+
* multi-facteurs, l'historique des mots de passe, les restrictions réseau et les
9+
* clés cryptographiques.
10+
*
11+
* @class SecurityPartDTO
12+
*
13+
* @description
14+
* Fonctionnalités de sécurité supportées :
15+
* - Historique des anciens mots de passe pour empêcher la réutilisation
16+
* - Authentification à deux facteurs via OTP (TOTP)
17+
* - Authentification U2F/FIDO avec clés de sécurité matérielles
18+
* - Restriction d'accès par réseau/IP (notation CIDR)
19+
* - Forcer le changement de mot de passe à la prochaine connexion
20+
* - Clé secrète unique pour les opérations cryptographiques
21+
*
22+
* Note : La clé secrète est générée automatiquement à la création de l'agent
23+
* par le service AgentsService et ne devrait généralement pas être fournie
24+
* manuellement lors de la création.
25+
*
26+
* @example
27+
* ```typescript
28+
* const security: SecurityPartDTO = {
29+
* otpKey: "JBSWY3DPEHPK3PXP",
30+
* allowedNetworks: ["192.168.1.0/24", "10.0.0.0/8"],
31+
* changePwdAtNextLogin: true
32+
* };
33+
* ```
34+
*/
435
export class SecurityPartDTO {
36+
/**
37+
* Historique des anciens mots de passe hachés.
38+
* Permet d'empêcher la réutilisation des mots de passe précédents.
39+
*
40+
* @type {string[]}
41+
* @readonly En pratique, ne devrait pas être modifiée manuellement
42+
* @optional
43+
*/
544
@IsArray()
645
@IsString({ each: true })
746
@ApiProperty({ type: [String] })
8-
public oldPasswords?: string[];
47+
public oldPasswords?: string[]
948

49+
/**
50+
* Clé secrète pour l'authentification OTP (One-Time Password).
51+
* Utilisée pour générer les codes TOTP pour l'authentification à deux facteurs.
52+
*
53+
* @type {string}
54+
* @optional
55+
* @example "JBSWY3DPEHPK3PXP"
56+
*/
1057
@IsString()
1158
@IsOptional()
1259
@ApiProperty()
13-
public otpKey?: string;
60+
public otpKey?: string
1461

62+
/**
63+
* Clés U2F/FIDO enregistrées pour l'authentification matérielle.
64+
* Tableau des identifiants de clés de sécurité physiques.
65+
*
66+
* @type {string[]}
67+
* @optional
68+
*/
1569
@IsArray()
1670
@IsString({ each: true })
1771
@IsOptional()
1872
@ApiProperty({ type: [String] })
19-
public u2fKey?: string[];
73+
public u2fKey?: string[]
2074

75+
/**
76+
* Liste des réseaux/IP autorisés pour cet agent.
77+
* Restriction d'accès basée sur l'adresse IP ou le réseau en notation CIDR.
78+
* Si vide, aucune restriction réseau n'est appliquée.
79+
*
80+
* @type {string[]}
81+
* @optional
82+
* @example ["192.168.1.0/24", "10.0.0.0/8", "203.0.113.42"]
83+
*/
2184
@IsArray()
2285
@IsString({ each: true })
2386
@IsOptional()
2487
@ApiProperty({ type: [String] })
25-
public allowedNetworks?: string[];
88+
public allowedNetworks?: string[]
2689

90+
/**
91+
* Indique si l'agent doit changer son mot de passe à la prochaine connexion.
92+
* Utilisé pour forcer le renouvellement du mot de passe après une
93+
* réinitialisation ou suite à une politique de sécurité.
94+
*
95+
* @type {boolean}
96+
* @optional
97+
*/
2798
@IsBoolean()
2899
@IsOptional()
29100
@ApiProperty()
30-
public changePwdAtNextLogin: boolean;
101+
public changePwdAtNextLogin: boolean
31102

103+
/**
104+
* Clé secrète unique de l'agent.
105+
* Générée automatiquement à la création (64 caractères hexadécimaux).
106+
* Utilisée pour les opérations cryptographiques (signature, chiffrement, tokens).
107+
*
108+
* @type {string}
109+
* @optional
110+
* @readonly En pratique, ne devrait pas être fournie manuellement
111+
*/
32112
@IsString()
33113
@IsOptional()
34114
@ApiProperty()
35-
public secretKey?: string;
115+
public secretKey?: string
36116
}

0 commit comments

Comments
 (0)