Skip to content

Commit 4eeb7b0

Browse files
tacxoutacxou
committed
feat: Add detailed JSDoc comments to SecurityPart and StatePart schemas for improved documentation
1 parent 1153dcc commit 4eeb7b0

File tree

3 files changed

+344
-42
lines changed

3 files changed

+344
-42
lines changed

‎apps/api/src/core/agents/_schemas/_parts/security.part.schema.ts‎

Lines changed: 96 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,126 @@
1-
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
2-
import { Document } from 'mongoose';
1+
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose'
2+
import { Document } from 'mongoose'
33

4+
/**
5+
* Schéma Mongoose pour la partie sécurité des agents.
6+
*
7+
* Ce sous-schéma regroupe toutes les informations relatives à la sécurité
8+
* d'un agent, incluant l'authentification multi-facteurs, l'historique des
9+
* mots de passe, les restrictions réseau et les clés cryptographiques.
10+
*
11+
* @class SecurityPart
12+
* @extends {Document}
13+
*
14+
* @description
15+
* Fonctionnalités de sécurité supportées :
16+
* - Historique des anciens mots de passe pour empêcher la réutilisation
17+
* - Authentification à deux facteurs (OTP via TOTP)
18+
* - Authentification U2F/FIDO pour les clés de sécurité matérielles
19+
* - Restriction d'accès par réseau/IP
20+
* - Forcer le changement de mot de passe à la prochaine connexion
21+
* - Clé secrète unique pour les opérations cryptographiques
22+
*
23+
* Note : Le schéma utilise `_id: false` car il est intégré comme sous-document
24+
* dans le schéma Agent principal et n'a pas besoin de son propre identifiant.
25+
*
26+
* @example
27+
* ```typescript
28+
* {
29+
* oldPasswords: ["$argon2id$v=19$m=...", "$argon2id$v=19$m=..."],
30+
* otpKey: "JBSWY3DPEHPK3PXP",
31+
* u2fKey: ["key-handle-1", "key-handle-2"],
32+
* allowedNetworks: ["192.168.1.0/24", "10.0.0.0/8"],
33+
* changePwdAtNextLogin: false,
34+
* secretKey: "a1b2c3d4e5f6..."
35+
* }
36+
* ```
37+
*/
438
@Schema({ _id: false })
539
export class SecurityPart extends Document {
40+
/**
41+
* Historique des anciens mots de passe hachés.
42+
* Permet d'empêcher la réutilisation des mots de passe précédents
43+
* pour renforcer la sécurité.
44+
*
45+
* @type {string[]}
46+
* @optional
47+
* @default []
48+
*/
649
@Prop({
750
type: [String],
851
default: [],
952
})
10-
public oldPasswords?: string[];
53+
public oldPasswords?: string[]
1154

55+
/**
56+
* Clé secrète pour l'authentification OTP (One-Time Password).
57+
* Utilisée pour générer les codes TOTP pour l'authentification à deux facteurs.
58+
*
59+
* @type {string}
60+
* @optional
61+
* @example "JBSWY3DPEHPK3PXP"
62+
*/
1263
@Prop({
1364
type: String,
1465
})
15-
public otpKey?: string;
66+
public otpKey?: string
1667

68+
/**
69+
* Clés U2F/FIDO enregistrées pour l'authentification matérielle.
70+
* Tableau des identifiants de clés de sécurité physiques enregistrées.
71+
*
72+
* @type {string[]}
73+
* @optional
74+
*/
1775
@Prop({
1876
type: [String],
1977
})
20-
public u2fKey?: string[];
78+
public u2fKey?: string[]
2179

80+
/**
81+
* Liste des réseaux/IP autorisés pour cet agent.
82+
* Restriction d'accès basée sur l'adresse IP ou le réseau en notation CIDR.
83+
* Si vide, aucune restriction réseau n'est appliquée.
84+
*
85+
* @type {string[]}
86+
* @optional
87+
* @example ["192.168.1.0/24", "10.0.0.0/8", "203.0.113.42"]
88+
*/
2289
@Prop({
2390
type: [String],
2491
})
25-
public allowedNetworks?: string[];
92+
public allowedNetworks?: string[]
2693

94+
/**
95+
* Indique si l'agent doit changer son mot de passe à la prochaine connexion.
96+
* Utilisé pour forcer le renouvellement du mot de passe, par exemple
97+
* après une réinitialisation ou une politique de sécurité.
98+
*
99+
* @type {boolean}
100+
* @default false
101+
*/
27102
@Prop({
28103
type: Boolean,
29104
default: false,
30105
})
31-
public changePwdAtNextLogin: boolean;
106+
public changePwdAtNextLogin: boolean
32107

108+
/**
109+
* Clé secrète unique de l'agent.
110+
* Générée automatiquement à la création de l'agent (64 caractères hexadécimaux).
111+
* Utilisée pour les opérations cryptographiques (signature, chiffrement, tokens, etc.).
112+
*
113+
* @type {string}
114+
* @required
115+
* @example "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
116+
*/
33117
@Prop({
34118
type: String,
35119
})
36-
public secretKey: string;
120+
public secretKey: string
37121
}
38122

39-
export const SecurityPartSchema = SchemaFactory.createForClass(SecurityPart);
123+
/**
124+
* Factory pour créer le schéma Mongoose à partir de la classe SecurityPart.
125+
*/
126+
export const SecurityPartSchema = SchemaFactory.createForClass(SecurityPart)

‎apps/api/src/core/agents/_schemas/_parts/state.part.schema.ts‎

Lines changed: 102 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,124 @@
1-
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
2-
import { Document } from 'mongoose';
3-
import { AgentState, AgentStateList } from '~/core/agents/_enum/agent-state.enum';
1+
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose'
2+
import { Document } from 'mongoose'
3+
import { AgentState, AgentStateList } from '~/core/agents/_enum/agent-state.enum'
44

5+
/**
6+
* Schéma Mongoose pour la partie état des agents.
7+
*
8+
* Ce sous-schéma gère l'état de lifecycle d'un agent, permettant de suivre
9+
* son statut actuel (actif, inactif, suspendu, etc.) et de conserver les
10+
* informations relatives aux suspensions temporaires.
11+
*
12+
* @class StatePart
13+
* @extends {Document}
14+
*
15+
* @description
16+
* Le système de gestion d'état permet de :
17+
* - Suivre l'état actuel de l'agent dans son cycle de vie
18+
* - Enregistrer la date du dernier changement d'état
19+
* - Gérer les suspensions temporaires avec date de début, fin et raison
20+
* - Implémenter des workflows de validation et d'activation
21+
*
22+
* États typiques d'un agent (voir AgentState) :
23+
* - PENDING : En attente d'activation
24+
* - ACTIVE : Actif et opérationnel
25+
* - INACTIVE : Désactivé temporairement
26+
* - SUSPENDED : Suspendu (avec date de fin possible)
27+
* - DELETED : Marqué pour suppression
28+
*
29+
* Note : Le schéma utilise `_id: false` car il est intégré comme sous-document
30+
* dans le schéma Agent principal et n'a pas besoin de son propre identifiant.
31+
*
32+
* @example
33+
* ```typescript
34+
* {
35+
* current: AgentState.ACTIVE,
36+
* lastChangedAt: ISODate("2025-11-25T10:00:00Z"),
37+
* suspendedAt: null,
38+
* suspendedUntil: null,
39+
* suspendedReason: null
40+
* }
41+
*
42+
* // Exemple d'agent suspendu
43+
* {
44+
* current: AgentState.SUSPENDED,
45+
* lastChangedAt: ISODate("2025-11-25T10:00:00Z"),
46+
* suspendedAt: ISODate("2025-11-25T10:00:00Z"),
47+
* suspendedUntil: ISODate("2025-12-25T10:00:00Z"),
48+
* suspendedReason: "Violation de la politique de sécurité"
49+
* }
50+
* ```
51+
*/
552
@Schema({ _id: false })
653
export class StatePart extends Document {
54+
/**
55+
* État actuel de l'agent dans son cycle de vie.
56+
* Représente le statut opérationnel de l'agent.
57+
*
58+
* @type {number}
59+
* @required
60+
* @default AgentState.PENDING
61+
* @see {AgentState}
62+
* @see {AgentStateList}
63+
*/
764
@Prop({
865
required: true,
966
type: Number,
1067
enum: AgentStateList,
1168
default: AgentState.PENDING,
1269
})
13-
public current: number;
70+
public current: number
1471

72+
/**
73+
* Date du dernier changement d'état.
74+
* Permet de tracer quand l'agent a changé d'état pour la dernière fois.
75+
*
76+
* @type {Date}
77+
* @optional
78+
* @default Date actuelle
79+
*/
1580
@Prop({
1681
type: Date,
1782
default: new Date(),
1883
})
19-
public lastChangedAt?: Date;
84+
public lastChangedAt?: Date
2085

86+
/**
87+
* Date de début de suspension.
88+
* Indique quand l'agent a été suspendu.
89+
* Uniquement renseigné si l'état actuel est SUSPENDED.
90+
*
91+
* @type {Date}
92+
* @optional
93+
*/
2194
@Prop({ type: Date })
22-
public suspendedAt?: Date;
95+
public suspendedAt?: Date
2396

97+
/**
98+
* Date de fin de suspension.
99+
* Indique jusqu'à quand l'agent est suspendu.
100+
* Si non renseignée, la suspension est indéfinie.
101+
*
102+
* @type {Date}
103+
* @optional
104+
* @example ISODate("2025-12-31T23:59:59Z")
105+
*/
24106
@Prop({ type: Date })
25-
public suspendedUntil?: Date;
107+
public suspendedUntil?: Date
26108

109+
/**
110+
* Raison de la suspension.
111+
* Texte libre expliquant pourquoi l'agent a été suspendu.
112+
*
113+
* @type {string}
114+
* @optional
115+
* @example "Violation de la politique de sécurité", "Inactivité prolongée"
116+
*/
27117
@Prop({ type: String })
28-
public suspendedReason?: string;
118+
public suspendedReason?: string
29119
}
30120

31-
export const StatePartSchema = SchemaFactory.createForClass(StatePart);
121+
/**
122+
* Factory pour créer le schéma Mongoose à partir de la classe StatePart.
123+
*/
124+
export const StatePartSchema = SchemaFactory.createForClass(StatePart)

0 commit comments

Comments
 (0)