@duplojs/agents-kit 0.1.0-beta.3 → 0.1.0-beta.6

package/docs/API/40-json-web-token/20-signer/index.md

@@ -0,0 +1,3 @@
+## Signer
+
+Configurer la signature et la vérification cryptographiques.

package/docs/API/40-json-web-token/30-cipher/10-createRSAOAEP.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Cipher.createRSAOAEP
+ *
+ * Configurer RSA-OAEP avec SHA-1.
+ */
+import { Cipher } from "@duplojs/json-web-token";
+import type * as DCommon from "@duplojs/lang/common";
+
+// PEM PKCS8
+declare const privateKey: string;
+// PEM SPKI
+declare const publicKey: string;
+
+const cipher = Cipher.createRSAOAEP({
+	privateKey,
+	publicKey,
+});
+
+type _Algorithm = DCommon.ExpectType<
+	typeof cipher.algorithm,
+	"RSA-OAEP",
+	"strict"
+>;
+
+// La factory peut être passée au handler pour fournir les clés par opération.
+const factory = Cipher.createRSAOAEP;

package/docs/API/40-json-web-token/30-cipher/10-createRSAOAEP256.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Cipher.createRSAOAEP256
+ *
+ * Configurer RSA-OAEP avec SHA-256.
+ */
+import { Cipher } from "@duplojs/json-web-token";
+import type * as DCommon from "@duplojs/lang/common";
+
+// PEM PKCS8
+declare const privateKey: string;
+// PEM SPKI
+declare const publicKey: string;
+
+const cipher = Cipher.createRSAOAEP256({
+	privateKey,
+	publicKey,
+});
+
+type _Algorithm = DCommon.ExpectType<
+	typeof cipher.algorithm,
+	"RSA-OAEP-256",
+	"strict"
+>;
+
+// La factory peut être passée au handler pour fournir les clés par opération.
+const factory = Cipher.createRSAOAEP256;

package/docs/API/40-json-web-token/30-cipher/10-factory.ts

@@ -0,0 +1,29 @@
+/**
+ * @title Cipher.factory
+ *
+ * Définir une factory de chiffrement et de déchiffrement.
+ */
+import { Cipher, RSA_OAEP } from "@duplojs/json-web-token";
+
+const createCipher = Cipher.factory(
+	"RSA-OAEP-256",
+	(params: {
+		privateKey: string;
+		publicKey: string;
+	}, algorithm) => ({
+		encrypt: (content) => RSA_OAEP.encrypt(content, params.publicKey, algorithm),
+		decrypt: (content) => RSA_OAEP.decrypt(content, params.privateKey, algorithm),
+	}),
+);
+
+// PEM PKCS8
+declare const privateKey: string;
+// PEM SPKI
+declare const publicKey: string;
+const cipher = createCipher({
+	privateKey,
+	publicKey,
+});
+const encrypted = await cipher.encrypt("session");
+// Le contenu déchiffré est "session" si les clés correspondent.
+const decrypted = await cipher.decrypt(encrypted);

package/docs/API/40-json-web-token/30-cipher/index.llms.md

@@ -0,0 +1,16 @@
+## Cipher
+
+Configurer le chiffrement et le déchiffrement facultatifs des tokens.
+
+### [Cipher.createRSAOAEP](10-createRSAOAEP.ts)
+
+Configurer RSA-OAEP avec SHA-1.
+ 
+### [Cipher.createRSAOAEP256](10-createRSAOAEP256.ts)
+
+Configurer RSA-OAEP avec SHA-256.
+ 
+### [Cipher.factory](10-factory.ts)
+
+Définir une factory de chiffrement et de déchiffrement.
+ 

package/docs/API/40-json-web-token/30-cipher/index.md

@@ -0,0 +1,3 @@
+## Cipher
+
+Configurer le chiffrement et le déchiffrement facultatifs des tokens.

package/docs/API/40-json-web-token/40-utils/10-AES_GCM.decrypt.ts

@@ -0,0 +1,17 @@
+/**
+ * @title AES_GCM.decrypt
+ *
+ * Déchiffrer avec AES-GCM et le vecteur associé.
+ */
+import { AES_GCM } from "@duplojs/json-web-token";
+
+// 16 octets UTF-8 pour A128GCM
+declare const key: string;
+const encrypted = await AES_GCM.encrypt("session", key, "A128GCM");
+const content = await AES_GCM.decrypt(
+	encrypted.cipherText,
+	key,
+	encrypted.initializationVector,
+	"A128GCM",
+);
+// Le contenu déchiffré est "session" si la clé et le vecteur correspondent.

package/docs/API/40-json-web-token/40-utils/10-AES_GCM.encrypt.ts

@@ -0,0 +1,11 @@
+/**
+ * @title AES_GCM.encrypt
+ *
+ * Chiffrer avec AES-GCM et récupérer le vecteur utilisé.
+ */
+import { AES_GCM } from "@duplojs/json-web-token";
+
+// 16 octets UTF-8 pour A128GCM, issue d'une source sécurisée
+declare const key: string;
+const encrypted = await AES_GCM.encrypt("session", key, "A128GCM");
+// cipherText et initializationVector sont encodés en Base64URL.

package/docs/API/40-json-web-token/40-utils/10-AES_GCM.generateInitializationVector.ts

@@ -0,0 +1,9 @@
+/**
+ * @title AES_GCM.generateInitializationVector
+ *
+ * Produire un vecteur aléatoire de 12 octets.
+ */
+import { AES_GCM } from "@duplojs/json-web-token";
+
+// 12 octets aléatoires
+const iv = AES_GCM.generateInitializationVector();

package/docs/API/40-json-web-token/40-utils/10-HMAC.sign.ts

@@ -0,0 +1,13 @@
+/**
+ * @title HMAC.sign
+ *
+ * Signer avec HMAC.
+ */
+import { HMAC } from "@duplojs/json-web-token";
+
+// secret fourni par une source sécurisée
+declare const secret: string;
+// Base64URL
+const signature = await HMAC.sign("session", secret, "HS256");
+// Résultat booléen de la vérification cryptographique.
+const isValid = await HMAC.verify("session", signature, secret, "HS256");

package/docs/API/40-json-web-token/40-utils/10-HMAC.verify.ts

@@ -0,0 +1,11 @@
+/**
+ * @title HMAC.verify
+ *
+ * Vérifier une signature HMAC.
+ */
+import { HMAC } from "@duplojs/json-web-token";
+
+declare const secret: string;
+const signature = await HMAC.sign("session", secret, "HS512");
+// Résultat booléen de la vérification cryptographique.
+const isValid = await HMAC.verify("session", signature, secret, "HS512");

package/docs/API/40-json-web-token/40-utils/10-RSA.sign.ts

@@ -0,0 +1,14 @@
+/**
+ * @title RSA.sign
+ *
+ * Signer avec une clé privée RSA PKCS8.
+ */
+import { RSA } from "@duplojs/json-web-token";
+
+declare const privateKey: string;
+// PEM SPKI correspondant
+declare const publicKey: string;
+// Base64URL
+const signature = await RSA.sign("session", privateKey, "RS256");
+// Résultat booléen de la vérification cryptographique.
+const isValid = await RSA.verify("session", signature, publicKey, "RS256");

package/docs/API/40-json-web-token/40-utils/10-RSA.verify.ts

@@ -0,0 +1,13 @@
+/**
+ * @title RSA.verify
+ *
+ * Vérifier une signature RSA avec une clé publique SPKI.
+ */
+import { RSA } from "@duplojs/json-web-token";
+
+// PEM PKCS8 correspondant
+declare const privateKey: string;
+declare const publicKey: string;
+const signature = await RSA.sign("session", privateKey, "RS512");
+// Résultat booléen de la vérification cryptographique.
+const isValid = await RSA.verify("session", signature, publicKey, "RS512");

package/docs/API/40-json-web-token/40-utils/10-RSA_OAEP.decrypt.ts

@@ -0,0 +1,13 @@
+/**
+ * @title RSA_OAEP.decrypt
+ *
+ * Déchiffrer avec une clé privée RSA-OAEP PKCS8.
+ */
+import { RSA_OAEP } from "@duplojs/json-web-token";
+
+declare const privateKey: string;
+// PEM SPKI correspondant
+declare const publicKey: string;
+const encrypted = await RSA_OAEP.encrypt("session", publicKey, "RSA-OAEP-256");
+// Le contenu déchiffré est "session" si les clés correspondent.
+const content = await RSA_OAEP.decrypt(encrypted, privateKey, "RSA-OAEP-256");

package/docs/API/40-json-web-token/40-utils/10-RSA_OAEP.encrypt.ts

@@ -0,0 +1,10 @@
+/**
+ * @title RSA_OAEP.encrypt
+ *
+ * Chiffrer avec une clé publique RSA-OAEP SPKI.
+ */
+import { RSA_OAEP } from "@duplojs/json-web-token";
+
+declare const publicKey: string;
+// Base64URL
+const encrypted = await RSA_OAEP.encrypt("session", publicKey, "RSA-OAEP-256");

package/docs/API/40-json-web-token/40-utils/10-decodeBase64.ts

@@ -0,0 +1,9 @@
+/**
+ * @title decodeBase64
+ *
+ * Décoder du Base64 en octets.
+ */
+import { decodeBase64, decodeText } from "@duplojs/json-web-token";
+
+// "hello"
+const text = decodeText(decodeBase64("aGVsbG8="));

package/docs/API/40-json-web-token/40-utils/10-decodeBase64Url.ts

@@ -0,0 +1,9 @@
+/**
+ * @title decodeBase64Url
+ *
+ * Décoder du Base64URL en octets.
+ */
+import { decodeBase64Url, decodeText } from "@duplojs/json-web-token";
+
+// "hello"
+const text = decodeText(decodeBase64Url("aGVsbG8"));

package/docs/API/40-json-web-token/40-utils/10-decodeText.ts

@@ -0,0 +1,9 @@
+/**
+ * @title decodeText
+ *
+ * Décoder des octets UTF-8.
+ */
+import { decodeText, encodeText } from "@duplojs/json-web-token";
+
+// "café"
+const text = decodeText(encodeText("café"));

package/docs/API/40-json-web-token/40-utils/10-encodeBase64.ts

@@ -0,0 +1,9 @@
+/**
+ * @title encodeBase64
+ *
+ * Encoder des octets en Base64.
+ */
+import { encodeBase64, encodeText } from "@duplojs/json-web-token";
+
+// "aGVsbG8="
+const encoded = encodeBase64(encodeText("hello"));

package/docs/API/40-json-web-token/40-utils/10-encodeBase64Url.ts

@@ -0,0 +1,9 @@
+/**
+ * @title encodeBase64Url
+ *
+ * Encoder du texte ou des octets en Base64URL sans remplissage.
+ */
+import { encodeBase64Url } from "@duplojs/json-web-token";
+
+// "aGVsbG8"
+const encoded = encodeBase64Url("hello");

package/docs/API/40-json-web-token/40-utils/10-encodeText.ts

@@ -0,0 +1,9 @@
+/**
+ * @title encodeText
+ *
+ * Encoder une chaîne en UTF-8.
+ */
+import { encodeText } from "@duplojs/json-web-token";
+
+// octets UTF-8
+const bytes = encodeText("café");

package/docs/API/40-json-web-token/40-utils/10-isBase64Url.ts

@@ -0,0 +1,11 @@
+/**
+ * @title isBase64Url
+ *
+ * Vérifier la forme d’une chaîne Base64URL.
+ */
+import { isBase64Url } from "@duplojs/json-web-token";
+
+// true
+const valid = isBase64Url("aGVsbG8");
+// false
+const invalid = isBase64Url("a+");

package/docs/API/40-json-web-token/40-utils/10-jsonParse.ts

@@ -0,0 +1,11 @@
+/**
+ * @title jsonParse
+ *
+ * Lire du JSON ou renvoyer undefined si la syntaxe est invalide.
+ */
+import { jsonParse } from "@duplojs/json-web-token";
+
+// objet JSON
+const payload = jsonParse("{\"userId\":\"42\"}");
+// undefined
+const invalid = jsonParse("{");

package/docs/API/40-json-web-token/40-utils/10-pemToBinary.ts

@@ -0,0 +1,11 @@
+/**
+ * @title pemToBinary
+ *
+ * Convertir une clé PEM en octets DER.
+ */
+import { pemToBinary } from "@duplojs/json-web-token";
+
+// clé PEM SPKI
+declare const publicKey: string;
+// octets DER
+const der = pemToBinary(publicKey);

package/docs/API/40-json-web-token/40-utils/index.llms.md

@@ -0,0 +1,76 @@
+## Utilitaires JWT
+
+Manipuler les encodages et les primitives cryptographiques publiques.
+
+### [AES_GCM.decrypt](10-AES_GCM.decrypt.ts)
+
+Déchiffrer avec AES-GCM et le vecteur associé.
+ 
+### [AES_GCM.encrypt](10-AES_GCM.encrypt.ts)
+
+Chiffrer avec AES-GCM et récupérer le vecteur utilisé.
+ 
+### [AES_GCM.generateInitializationVector](10-AES_GCM.generateInitializationVector.ts)
+
+Produire un vecteur aléatoire de 12 octets.
+ 
+### [HMAC.sign](10-HMAC.sign.ts)
+
+Signer avec HMAC.
+ 
+### [HMAC.verify](10-HMAC.verify.ts)
+
+Vérifier une signature HMAC.
+ 
+### [RSA.sign](10-RSA.sign.ts)
+
+Signer avec une clé privée RSA PKCS8.
+ 
+### [RSA.verify](10-RSA.verify.ts)
+
+Vérifier une signature RSA avec une clé publique SPKI.
+ 
+### [RSA_OAEP.decrypt](10-RSA_OAEP.decrypt.ts)
+
+Déchiffrer avec une clé privée RSA-OAEP PKCS8.
+ 
+### [RSA_OAEP.encrypt](10-RSA_OAEP.encrypt.ts)
+
+Chiffrer avec une clé publique RSA-OAEP SPKI.
+ 
+### [decodeBase64](10-decodeBase64.ts)
+
+Décoder du Base64 en octets.
+ 
+### [decodeBase64Url](10-decodeBase64Url.ts)
+
+Décoder du Base64URL en octets.
+ 
+### [decodeText](10-decodeText.ts)
+
+Décoder des octets UTF-8.
+ 
+### [encodeBase64](10-encodeBase64.ts)
+
+Encoder des octets en Base64.
+ 
+### [encodeBase64Url](10-encodeBase64Url.ts)
+
+Encoder du texte ou des octets en Base64URL sans remplissage.
+ 
+### [encodeText](10-encodeText.ts)
+
+Encoder une chaîne en UTF-8.
+ 
+### [isBase64Url](10-isBase64Url.ts)
+
+Vérifier la forme d’une chaîne Base64URL.
+ 
+### [jsonParse](10-jsonParse.ts)
+
+Lire du JSON ou renvoyer undefined si la syntaxe est invalide.
+ 
+### [pemToBinary](10-pemToBinary.ts)
+
+Convertir une clé PEM en octets DER.
+ 

package/docs/API/40-json-web-token/40-utils/index.md

@@ -0,0 +1,3 @@
+## Utilitaires JWT
+
+Manipuler les encodages et les primitives cryptographiques publiques.

package/docs/API/40-json-web-token/index.md

@@ -0,0 +1,3 @@
+# @duplojs/json-web-token
+
+Politiques JWT réutilisables, signature, chiffrement facultatif et primitives cryptographiques.

package/docs/API/50-form/10-vue/10-construction/10-createForm.ts

@@ -0,0 +1,48 @@
+/**
+ * @title createForm
+ *
+ * Associer des templates à une fabrique de formulaires Vue.
+ */
+import { createForm, useMultiLayout, type GetCheckedValue } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+import { grid } from "../fixtures/templates";
+
+// La fabrique peut servir à plusieurs formulaires ; chaque appel reçoit son champ racine.
+const useForm = createForm(grid.useTemplates());
+
+const { component: ContactForm, currentValue, check, reset, dispose } = useForm(
+	useMultiLayout({
+		email: useTextInput({
+			label: "Email",
+			dataStructure: DDataStructure.string([DDataStructure.email()]),
+		}),
+	}),
+);
+
+// La saisie brute reste une chaîne ; seul le succès de check garantit le format email.
+type _Raw = DCommon.ExpectType<
+	typeof currentValue.value,
+	{ email: string },
+	"strict"
+>;
+type _Checked = DCommon.ExpectType<
+	GetCheckedValue<typeof check>,
+	{ email: string & DString.Email },
+	"strict"
+>;
+
+// Succès avec la valeur validée, ou erreurs associées aux champs.
+const result = await check();
+void result;
+
+// À monter dans Vue ; son slot par défaut reçoit le bouton de soumission.
+void ContactForm;
+
+// Restaure la valeur initiale.
+reset();
+
+// Libère les scopes internes lorsque le formulaire n'est plus utilisé.
+dispose();

package/docs/API/50-form/10-vue/10-construction/10-createFormField.ts

@@ -0,0 +1,66 @@
+/**
+ * @title createFormField
+ *
+ * Construire une primitive de champ personnalisée pour un formulaire Vue.
+ */
+import { createForm, createFormField, useMultiLayout, type FormField, type FormFieldSlots } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+import { grid } from "../fixtures/templates";
+
+// Un layout qui présente un champ dans une section utilise le template du contexte.
+// Le champ enfant conserve son modèle et ses garanties de validation.
+function useTitledField<GenericValue, GenericChecked, GenericSlots extends FormFieldSlots>(
+	field: FormField<GenericValue, GenericChecked, GenericSlots>,
+	title: string,
+) {
+	return createFormField<
+		GenericValue,
+		GenericChecked,
+		GenericSlots
+	>(
+		(modelValue, parentKey, context) => {
+			const key = `${parentKey}_TITLE`;
+			const child = field.new(modelValue, key, context);
+
+			return {
+				check: () => child.check(),
+				reset: () => child.reset(),
+				dispose: () => child.dispose(),
+				getVNode: () => context.templates.section.getVNode(
+					{
+						fieldKey: key,
+						getCurrentValue: () => modelValue.value,
+						title,
+					},
+					{ formField: () => child.getVNode() },
+				),
+			};
+		},
+		field.defaultValue,
+	);
+}
+
+// Le formulaire instancie le layout avec le modèle initial du champ enfant.
+const useForm = createForm(grid.useTemplates());
+const { component: ProfileForm, currentValue, check, reset, dispose } = useForm(
+	useTitledField(
+		useMultiLayout({
+			name: useTextInput({ label: "Name" }),
+		}),
+		"Profile",
+	),
+);
+
+type _Value = DCommon.ExpectType<
+	typeof currentValue.value,
+	{ name: string },
+	"strict"
+>;
+
+// check, reset et dispose sont délégués à l'enfant ; reset du formulaire restaure aussi le modèle initial.
+const result = await check();
+void result;
+void ProfileForm;
+reset();
+dispose();

package/docs/API/50-form/10-vue/10-construction/10-createGridTemplates.ts

@@ -0,0 +1,39 @@
+/**
+ * @title createGridTemplates
+ *
+ * Configurer les templates Vue en grille et leurs commandes.
+ */
+import { createForm } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+
+// La configuration Grid exige les options repeat, step et union, même si le formulaire ne les utilise pas.
+// Les options form, input, multi, check et section peuvent être omises.
+const grid = createGridTemplates({
+	repeat: {
+		addLabel: "Add",
+		removeLabel: "Remove",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+		resetButton: templateFormResetButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+	input: { columns: 6 },
+});
+
+// Ensemble complet pour createForm.
+const useForm = createForm(grid.useTemplates());
+const { component: TheForm } = useForm(
+	useTextInput({
+		label: "Title",
+		// Surcharge locale de la configuration input.
+		template: grid.useInputTemplate({ columns: 12 }),
+	}),
+);

package/docs/API/50-form/10-vue/10-construction/10-createInput.ts

@@ -0,0 +1,46 @@
+/**
+ * @title createInput
+ *
+ * Construire un champ à partir d'un composant Vue compatible avec v-model.
+ */
+import { createInput, type GetFormFieldCheckedValue, type GetFormFieldValue } from "@duplojs/form/vue";
+import AddressInput from "./fixtures/AddressInput.vue";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+// AddressInput.vue déclare modelValue comme chaîne et exige la prop hint.
+// La fabrique fournit cette prop requise et une valeur initiale inférée depuis le composant.
+const useAddressInput = createInput(
+	AddressInput,
+	{
+		defaultValue: "",
+		props: {
+			hint: "We use this address to contact you.",
+			placeholder: "name@example.com",
+		},
+	},
+);
+
+const address = useAddressInput({
+	label: "Email",
+	props: {
+		hint: "Your contact address",
+		placeholder: "contact@example.com",
+	},
+	dataStructure: DDataStructure.string([DDataStructure.email()]),
+});
+
+// Les props locales doivent respecter le contrat du composant, y compris ses props requises.
+// Elles complètent les props initiales et remplacent les clés communes.
+// La validation enrichit le résultat.
+type _Raw = DCommon.ExpectType<
+	GetFormFieldValue<typeof address>,
+	string,
+	"strict"
+>;
+type _Checked = DCommon.ExpectType<
+	GetFormFieldCheckedValue<typeof address>,
+	string & DString.Email,
+	"strict"
+>;

package/docs/API/50-form/10-vue/10-construction/10-createTemplate.ts

@@ -0,0 +1,36 @@
+/**
+ * @title createTemplate
+ *
+ * Configurer un composant Vue comme template de formulaire.
+ */
+import { createForm, createTemplate, useMultiLayout } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import { GridInputTemplate } from "@duplojs/form/vueGrid";
+import { grid } from "../fixtures/templates";
+
+// La fabrique fixe le composant et les props par défaut hors props système.
+const useCompactInputTemplate = createTemplate(
+	"input",
+	GridInputTemplate,
+	{ props: { columns: 6 } },
+);
+
+// Le template global utilise six colonnes pour les inputs de ce formulaire.
+const useForm = createForm({
+	...grid.useTemplates(),
+	input: useCompactInputTemplate(),
+});
+
+const { component: ArticleForm, dispose } = useForm(
+	useMultiLayout({
+		title: useTextInput({ label: "Title" }),
+		summary: useTextInput({
+			label: "Summary",
+			// Cette instance surcharge les colonnes pour ce champ uniquement.
+			template: useCompactInputTemplate({ columns: 12 }),
+		}),
+	}),
+);
+
+void ArticleForm;
+dispose();