@mostajs/enrollment 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -29,7 +29,7 @@
  */
 export declare const moduleInfo: {
     readonly name: "@mostajs/enrollment";
-    readonly version: "0.1.0";
+    readonly version: "0.2.0";
     readonly level: "N1";
 };
 export { generateCode, parseCode, normalizeCode, hashCode, verifyCode } from './code.js';
@@ -39,3 +39,5 @@ export type { EnrollmentServiceOptions, RequestOutcome } from './service.js';
 export { createEnrollmentAgent, generateIdentity } from './agent.js';
 export type { EnrollmentAgentOptions, AgentState, AgentIdentity } from './agent.js';
 export type { EnrollmentState, EnrollmentRequest, EnrolledSite, Invitation, EnrollmentStore, ApprovalPayload, ReenrollmentAlert, } from './types.js';
+export { readMachineId } from './machine.js';
+export type { MachineId, MachineIdSource, ReadMachineIdOptions } from './machine.js';

package/dist/index.js

@@ -27,7 +27,8 @@
  * L'approbation est un CLIC humain — mais l'agent RE-SONDE en boucle. Le client installe et part
  * travailler ; vous approuvez quand vous voulez ; la machine se rattache toute seule.
  */
-export const moduleInfo = { name: '@mostajs/enrollment', version: '0.1.0', level: 'N1' };
+export const moduleInfo = { name: '@mostajs/enrollment', version: '0.2.0', level: 'N1' };
 export { generateCode, parseCode, normalizeCode, hashCode, verifyCode } from './code.js';
 export { createEnrollmentService } from './service.js';
 export { createEnrollmentAgent, generateIdentity } from './agent.js';
+export { readMachineId } from './machine.js';

package/dist/machine.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @mostajs/enrollment — Lire l'identifiant de la MACHINE, sans dépendance native.
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * Licence : AGPL-3.0-or-later
+ *
+ * ─── POURQUOI ICI ────────────────────────────────────────────────────────────
+ * L'agent exige un `machineId`, et TOUTE machine qui s'enrôle doit savoir le produire. Le laisser
+ * à la charge de chaque application, c'est garantir N implémentations divergentes — et une
+ * dépendance à `node-machine-id` (binaire natif) qui interdirait un `.exe` PUR-JS.
+ *
+ * ─── CE QUE CET IDENTIFIANT EST, ET N'EST PAS ────────────────────────────────
+ * Il **identifie**, il n'**authentifie** pas. Il est lisible par n'importe qui sur le poste et
+ * falsifiable par quiconque contrôle la machine. C'est la clé Ed25519 — privée, jamais transmise —
+ * qui authentifie. Le `machineId` sert à une seule chose : reconnaître « c'est le même poste » afin
+ * de LEVER L'ALERTE de ré-enrôlement quand la clé, elle, a changé.
+ *
+ * ─── ET IL EST HACHÉ ─────────────────────────────────────────────────────────
+ * On ne transmet JAMAIS le GUID brut de l'OS. Il est haché avec un `salt` propre à l'application :
+ *   - la console n'apprend pas l'identifiant système du client (elle n'en a aucun besoin) ;
+ *   - le même poste enrôlé dans deux applications donne deux identifiants DIFFÉRENTS — impossible
+ *     de recouper les parcs de deux clients.
+ * Le hachage est stable : même poste + même salt ⇒ même identifiant, indéfiniment.
+ */
+/** D'où vient l'identifiant — utile pour DIRE au client ce qui se passe, notamment `aleatoire`. */
+export type MachineIdSource = 'windows-registry' | 'linux-machine-id' | 'macos-ioplatform' | 'aleatoire';
+export interface MachineId {
+    /** L'identifiant à transmettre : haché, stable, propre à l'application. */
+    id: string;
+    source: MachineIdSource;
+    /**
+     * Présent UNIQUEMENT quand l'OS n'a rien fourni et qu'une graine a dû être tirée au sort.
+     * **L'hôte DOIT la persister** et la repasser en `fallback` au démarrage suivant.
+     *
+     * Sans cela, `id` change à chaque lancement et la machine — pourtant déjà enrôlée — se
+     * représente comme un poste inconnu à chaque redémarrage. Le module ne peut pas persister à
+     * votre place (il ne choisit pas votre stockage) : il vous rend donc la graine, explicitement.
+     */
+    seedToPersist?: string;
+}
+export interface ReadMachineIdOptions {
+    /**
+     * Sel propre à l'application (ex. `'ticketflow-server'`). Deux applications ⇒ deux identifiants
+     * pour le MÊME poste : aucun recoupement de parcs possible.
+     */
+    salt: string;
+    /**
+     * Identifiant de repli, DÉJÀ PERSISTÉ par l'hôte, si l'OS n'en fournit aucun. Voir ci-dessous
+     * pourquoi il DOIT être persisté.
+     */
+    fallback?: string | null;
+}
+/**
+ * Lit l'identifiant de la machine, haché avec le sel de l'application.
+ *
+ * ─── LE REPLI ALÉATOIRE EST UN PIÈGE — LISEZ CECI ────────────────────────────
+ * Quand l'OS ne fournit rien (conteneur nu, registre verrouillé), on renvoie `source: 'aleatoire'`
+ * et un identifiant tiré au sort. **L'hôte DOIT le persister** et le repasser en `fallback` aux
+ * démarrages suivants. Sinon l'identifiant change à chaque lancement — et la machine, déjà
+ * enrôlée, se présente à chaque fois comme un poste inconnu.
+ *
+ * On ne le persiste pas nous-mêmes : ce module ne choisit pas votre stockage (fichier ? base ?
+ * `userData` d'Electron ?). Mais on vous DIT, par `source`, que la persistance est obligatoire.
+ */
+export declare function readMachineId(opts: ReadMachineIdOptions): Promise<MachineId>;

package/dist/machine.js

@@ -0,0 +1,105 @@
+/**
+ * @mostajs/enrollment — Lire l'identifiant de la MACHINE, sans dépendance native.
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * Licence : AGPL-3.0-or-later
+ *
+ * ─── POURQUOI ICI ────────────────────────────────────────────────────────────
+ * L'agent exige un `machineId`, et TOUTE machine qui s'enrôle doit savoir le produire. Le laisser
+ * à la charge de chaque application, c'est garantir N implémentations divergentes — et une
+ * dépendance à `node-machine-id` (binaire natif) qui interdirait un `.exe` PUR-JS.
+ *
+ * ─── CE QUE CET IDENTIFIANT EST, ET N'EST PAS ────────────────────────────────
+ * Il **identifie**, il n'**authentifie** pas. Il est lisible par n'importe qui sur le poste et
+ * falsifiable par quiconque contrôle la machine. C'est la clé Ed25519 — privée, jamais transmise —
+ * qui authentifie. Le `machineId` sert à une seule chose : reconnaître « c'est le même poste » afin
+ * de LEVER L'ALERTE de ré-enrôlement quand la clé, elle, a changé.
+ *
+ * ─── ET IL EST HACHÉ ─────────────────────────────────────────────────────────
+ * On ne transmet JAMAIS le GUID brut de l'OS. Il est haché avec un `salt` propre à l'application :
+ *   - la console n'apprend pas l'identifiant système du client (elle n'en a aucun besoin) ;
+ *   - le même poste enrôlé dans deux applications donne deux identifiants DIFFÉRENTS — impossible
+ *     de recouper les parcs de deux clients.
+ * Le hachage est stable : même poste + même salt ⇒ même identifiant, indéfiniment.
+ */
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { hmacSha256, randomKey } from '@mostajs/crypto-box';
+const run = (cmd, args) => new Promise((resolve, reject) => {
+    // execFile, PAS exec : aucun shell, donc aucune injection possible même si un jour un
+    // paramètre venait de l'extérieur.
+    execFile(cmd, args, { timeout: 5_000, windowsHide: true }, (err, stdout) => {
+        if (err)
+            reject(err);
+        else
+            resolve(String(stdout));
+    });
+});
+/** Le GUID BRUT de l'OS. Interne : il ne doit jamais sortir d'ici sans être haché. */
+async function guidNatif() {
+    try {
+        if (process.platform === 'win32') {
+            // MachineGuid : posé par Windows à l'installation, stable, lisible sans privilège.
+            const out = await run(`${process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\reg.exe`, [
+                'QUERY', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid',
+            ]);
+            const m = /MachineGuid\s+REG_SZ\s+(\S+)/i.exec(out);
+            if (m)
+                return { brut: m[1], source: 'windows-registry' };
+            return null;
+        }
+        if (process.platform === 'darwin') {
+            const out = await run('/usr/sbin/ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice']);
+            const m = /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(out);
+            if (m)
+                return { brut: m[1], source: 'macos-ioplatform' };
+            return null;
+        }
+        if (process.platform === 'linux') {
+            // /etc/machine-id (systemd) ; le repli D-Bus couvre les distributions qui ne l'ont pas.
+            for (const f of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+                try {
+                    const brut = (await readFile(f, 'utf8')).trim();
+                    if (brut)
+                        return { brut, source: 'linux-machine-id' };
+                }
+                catch { /* fichier absent : on essaie le suivant */ }
+            }
+        }
+        // Tout autre OS (AIX, BSD, SunOS…) : on ne devine PAS. Étiqueter `linux-machine-id` un
+        // identifiant qui ne vient pas de Linux serait un mensonge dans les journaux — et le jour où
+        // il faudra diagnostiquer une machine qui se ré-enrôle sans cesse, ce mensonge coûtera cher.
+        return null;
+    }
+    catch {
+        // Registre verrouillé par une GPO, conteneur sans /etc/machine-id, binaire absent… On ne
+        // fait pas échouer l'application pour ça : l'appelant recevra `aleatoire` et saura quoi dire.
+        return null;
+    }
+}
+/**
+ * Lit l'identifiant de la machine, haché avec le sel de l'application.
+ *
+ * ─── LE REPLI ALÉATOIRE EST UN PIÈGE — LISEZ CECI ────────────────────────────
+ * Quand l'OS ne fournit rien (conteneur nu, registre verrouillé), on renvoie `source: 'aleatoire'`
+ * et un identifiant tiré au sort. **L'hôte DOIT le persister** et le repasser en `fallback` aux
+ * démarrages suivants. Sinon l'identifiant change à chaque lancement — et la machine, déjà
+ * enrôlée, se présente à chaque fois comme un poste inconnu.
+ *
+ * On ne le persiste pas nous-mêmes : ce module ne choisit pas votre stockage (fichier ? base ?
+ * `userData` d'Electron ?). Mais on vous DIT, par `source`, que la persistance est obligatoire.
+ */
+export async function readMachineId(opts) {
+    const natif = await guidNatif();
+    if (natif) {
+        // HMAC et pas SHA-256 nu : sans clé, un GUID Windows (espace connu et énumérable) se
+        // retrouverait par force brute à partir du haché. Le sel, secret ou non, coupe le dictionnaire.
+        return { id: hmacSha256(opts.salt, natif.brut), source: natif.source };
+    }
+    const repli = opts.fallback?.trim();
+    if (repli)
+        return { id: hmacSha256(opts.salt, repli), source: 'aleatoire' };
+    // Aucune graine fournie : on en tire une — et on la REND, pour que l'hôte la persiste. La
+    // garder pour nous produirait un identifiant neuf à chaque démarrage : le pire des deux mondes.
+    const graine = randomKey(32).toString('hex');
+    return { id: hmacSha256(opts.salt, graine), source: 'aleatoire', seedToPersist: graine };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/enrollment",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Enrôler une machine chez un client distant, sans configuration : code dictable au téléphone (usage unique, 7 jours), identité Ed25519 générée sur la machine, approbation par un clic dans la console, re-tentative automatique. Compose crypto-box et scheduler.",
   "license": "AGPL-3.0-or-later",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",