@mostajs/auth-dialects 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @mostajs/auth-dialects
+
+Format [Keep a Changelog](https://keepachangelog.com/fr/1.0.0/) · [SemVer](https://semver.org/lang/fr/).
+Auteur : Dr Hamid MADANI <drmdh@msn.com>
+
+## [0.1.0] — 2026-06-21
+
+### Added
+- Registre **zéro-dépendance** des « variétés » de connexion (**dialectes**), façon `@mostajs/orm` (DB-agnostique, port `userRepo`).
+- Deux familles (`kind`) : **magic-link** (`mail`, `sms` = *magic-sms-link*, `mail&sms`) et **biometric** WebAuthn (`face`, `finger`, `iris`).
+- `defaultDialects()` — catalogue des 6 variétés ; `mail`/`sms`/`mail&sms` `active`, `face`/`finger`/`iris` `planned` (à câbler via `@mostajs/auth` WebAuthn).
+- `createDialectRegistry({dialects?})` → `list/get/byKind/active/planned/select(identifier)/register(d)` (upsert par key, mise en tête = priorité, **extensible**).
+- Helpers `normalizePhone`, `looksLikePhone`, constantes `KINDS`/`STATUS`.
+- Tests `@mostajs/mjs-unit` (9 verts) + README + llms.txt.
+
+### Notes
+- Extrait de `incubator/app/auth.mjs` (extraction-first §10) — l'app le consomme désormais en composition.
+- WebAuthn ne distingue pas face/finger/iris au niveau protocole (`uv=required`, l'OS choisit) : un seul mécanisme, noms = branding.
+- Placé dans `@mostajs/auth-stack` (avec `sms-lite`/`smtp-lite`/`broadcast` regroupés dans le stack auth).

package/README.md

@@ -0,0 +1,80 @@
+# @mostajs/auth-dialects
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · Licence : AGPL-3.0-or-later
+Membre du **`@mostajs/auth-stack`** (avec `mosta-auth`, `mosta-auth-lite`, `mosta-auth-flow`, `mosta-sms-lite`, `mosta-smtp-lite`, `mosta-broadcast`).
+
+Registre **zéro-dépendance** des **« variétés » de connexion** — les **dialectes** —
+pour l'authentification, dans l'esprit de `@mostajs/orm` (DB-agnostique, **ports**
+injectés). Une variété de login = un **dialecte**.
+
+> **Façon dialectes** — même paradigme que les *drivers* de `@mostajs/sms-lite`, les
+> *canaux* de `@mostajs/broadcast` et les *schémas* de `@mostajs/nomenclature` :
+> un registre extensible où l'on **enregistre** des variantes sans toucher au flux.
+
+## Deux familles (`kind`)
+
+| Famille | Principe | Variétés |
+|---|---|---|
+| `magic-link` | sans mot de passe — le **lien magique** est **livré** par un/des canal(aux) | `mail`, `sms` (**magic-sms-link**), `mail&sms` |
+| `biometric` | vérification **sur l'appareil** via **WebAuthn/passkeys** (déléguée à `@mostajs/auth`) | `face`, `finger`, `iris` |
+
+## Catalogue par défaut (les 6)
+
+| key | kind | status | canaux / mécanisme |
+|---|---|---|---|
+| `mail` | magic-link | active | `email` — `match`=email, `resolve`=findByEmail |
+| `sms` | magic-link | active | `sms` (**magic-sms-link**) — `match`=numéro, `resolve`=findByPhone |
+| `mail&sms` | magic-link | active | `email`+`sms` — comportement par défaut (compte avec email **et** numéro) |
+| `face` | biometric | planned | **face-api.js** (client) + **PWA scan** (caméra) — `provider=face-api`, `capture=pwa-scan` |
+| `finger` | biometric | planned | WebAuthn platform, `uv=required` (`provider=webauthn`) |
+| `iris` | biometric | planned | WebAuthn platform, `uv=required` (`provider=webauthn`) |
+
+> **`face` ≠ `finger`/`iris`** : la reconnaissance faciale passe par **face-api.js**
+> (ML côté navigateur) avec **capture caméra en PWA** (`pwa-scan`) — pas de WebAuthn.
+> `finger`/`iris` utilisent l'**authentificateur de plateforme WebAuthn**.
+>
+> **Réalité WebAuthn** (finger/iris) : on **ne peut pas** exiger « iris » plutôt
+> qu'« empreinte » — l'OS choisit la modalité (`userVerification: required`) ;
+> les deux noms sont du **branding/UX** sur un seul mécanisme.
+
+## Usage
+
+```js
+import { createDialectRegistry } from '@mostajs/auth-dialects';
+
+const reg = createDialectRegistry();
+
+// 1) sélection par identifiant (email ou numéro)
+const dialect = reg.select(identifier);     // 'a@b.dz' → mail ; '+213…' → sms
+if (dialect?.resolve) {
+  const user = await dialect.resolve(identifier, userRepo);   // port { findByEmail, findByPhone }
+  if (user) { /* émettre le magic-link pour user.email, livrer selon dialect.channels */ }
+}
+
+// 2) introspection (UI / matrice / doc)
+reg.byKind('biometric');   // [face, finger, iris]
+reg.active();              // [mail, sms, mail&sms]
+
+// 3) extension — ajouter une variété sans toucher au flux
+reg.register({
+  key: 'whatsapp', label: 'WhatsApp', kind: 'magic-link', status: 'active',
+  match: (id) => String(id).startsWith('wa:'),
+  resolve: (id, repo) => repo.findByPhone(id),
+});
+```
+
+## API
+
+- `createDialectRegistry({ dialects? })` → `{ list, get, byKind, active, planned, select, register }`
+- `defaultDialects()` → les 6 dialectes
+- `normalizePhone(s)` · `looksLikePhone(id)` · `KINDS` · `STATUS`
+
+`register(d)` fait un **upsert par `key`** et place le dialecte **en tête**
+(priorité de `select`). DB-agnostique : `resolve` dépend du **port `userRepo`**
+fourni par le consumer.
+
+## Référence d'implémentation
+
+`Hadhinat` `incubator/app/auth.mjs` consomme ce registre ; le transport SMS est
+`@mostajs/sms-lite` (méthode **magic-sms-link**) ; la biométrie sera câblée via
+WebAuthn de `@mostajs/auth`. Voir `llms.txt`.

package/llms.txt

@@ -0,0 +1,54 @@
+# @mostajs/auth-dialects — llms.txt
+
+RÔLE
+  Registre ZÉRO-DÉPENDANCE des « variétés » de connexion (DIALECTES) pour l'auth — façon @mostajs/orm
+  (DB-agnostique, ports injectés). Une variété = un DIALECTE. Deux familles (kind) :
+    • magic-link : sans mot de passe, lien magique LIVRÉ par canal — mail, sms (« magic-sms-link »), mail&sms.
+    • biometric  : vérification sur l'APPAREIL via WebAuthn/passkeys — face, finger, iris — déléguée à @mostajs/auth.
+  Le module NE résout PAS les comptes : chaque dialecte magic-link reçoit un PORT userRepo {findByEmail, findByPhone}.
+  Version 0.1.0 · AGPL-3.0-or-later · Dr Hamid MADANI <drmdh@msn.com>. Membre du stack @mostajs/auth-stack.
+
+EXPORTS (src/index.js)
+  KINDS = { MAGIC_LINK:'magic-link', BIOMETRIC:'biometric' }
+  STATUS = { ACTIVE:'active', PLANNED:'planned' }
+  normalizePhone(s) -> string|null            (E.164 : garde « + » + chiffres)
+  looksLikePhone(id) -> boolean               (email vs numéro)
+  defaultDialects() -> Dialect[]              (les 6 : mail, sms, mail&sms, face, finger, iris)
+  createDialectRegistry({ dialects? }) -> {
+    list(), get(key), byKind(kind), active(), planned(),
+    select(identifier) -> Dialect|null,        (1er dialecte dont match(identifier) est vrai)
+    register(dialect) -> registre               (upsert par key, mis EN TÊTE → priorité ; chaînable)
+  }
+
+FORME D'UN DIALECTE
+  { key, label, kind, status, channels?:string[], requires?:'sms', notFound?:string,
+    match?(id)->bool, resolve?(id, userRepo)->Promise<user|null>,   // magic-link sélectionnables par identifiant
+    authenticator?:'platform', uv?:'required' }                     // biométriques (WebAuthn)
+  - match/resolve : SEULS les magic-link auto-sélectionnables (mail, sms). L'ordre compte (1re correspondance).
+  - sans match() (mail&sms, face, finger, iris) : au CATALOGUE (UI/doc) mais pas auto-sélectionnés par un identifiant.
+
+CATALOGUE PAR DÉFAUT (les 6)
+  mail      magic-link  active   channels=[email]         match=email   resolve=findByEmail   notFound=unknown_email
+  sms       magic-link  active   channels=[sms]  requires=sms  match=phone  resolve=findByPhone  notFound=unknown_phone
+  mail&sms  magic-link  active   channels=[email,sms] requires=sms   (défaut quand un compte a email+numéro)
+  face      biometric   planned  provider=face-api capture=pwa-scan         (reconnaissance faciale CLIENT via face-api.js + caméra PWA — PAS WebAuthn)
+  finger    biometric   planned  provider=webauthn authenticator=platform uv=required   (à câbler via @mostajs/auth)
+  iris      biometric   planned  provider=webauthn authenticator=platform uv=required
+
+USAGE
+  import { createDialectRegistry } from '@mostajs/auth-dialects';
+  const reg = createDialectRegistry();
+  const dialect = reg.select(identifier);             // email→mail, numéro→sms
+  if (dialect?.resolve) { const user = await dialect.resolve(identifier, userRepo); /* émettre le magic-link pour user.email */ }
+  // étendre :
+  reg.register({ key:'whatsapp', kind:'magic-link', status:'active', match:id=>id.startsWith('wa:'), resolve:(id,r)=>r.findByPhone(id) });
+
+PIÈGES
+  - WebAuthn ne permet PAS d'exiger « iris » plutôt que « empreinte » : l'OS choisit la modalité (UV=required).
+    face/finger/iris = même mécanisme, noms = branding/UX. 1 seul flux WebAuthn côté serveur.
+  - magic-sms-link : le jeton est long → corps SMS en GSM-7 strict (sans accents) sinon UCS-2 multiplie les segments
+    (Twilio trial : erreur 30044). Cf. @mostajs/auth llms §LIVRAISON MULTI-CANAL.
+  - DB-agnostique : sans userRepo, resolve() ne peut rien faire (port à fournir par le consumer).
+
+RÉFÉRENCE D'IMPLÉMENTATION
+  Hadhinat incubator/app/auth.mjs (consomme ce registre) ; @mostajs/sms-lite (transport SMS) ; @mostajs/auth (WebAuthn).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mostajs/auth-dialects",
+  "version": "0.1.0",
+  "description": "Registre ZÉRO-DÉPENDANCE des « variétés » de connexion (DIALECTES) pour l'auth : magic-link (mail / sms = magic-sms-link / mail&sms) + biométrie WebAuthn (face / finger / iris). DB-agnostique (port userRepo), extensible (register).",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [
+    "mostajs",
+    "auth",
+    "login",
+    "magic-link",
+    "magic-sms-link",
+    "sms",
+    "passwordless",
+    "webauthn",
+    "passkey",
+    "biometric",
+    "dialects",
+    "zero-dependency"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.0"
+  },
+  "scripts": {
+    "test": "bash test-scripts/run-tests.sh"
+  }
+}

package/src/index.js

@@ -0,0 +1,92 @@
+// @mostajs/auth-dialects — registre des « variétés » de connexion (DIALECTES), façon @mostajs/orm pour l'auth.
+// ZÉRO DÉPENDANCE. Une « variété » de connexion = un DIALECTE. Deux familles (kind) :
+//   • magic-link : sans mot de passe, le lien magique est LIVRÉ par un/des canal(aux) — mail, sms, mail&sms.
+//   • biometric  : vérification côté APPAREIL via WebAuthn/passkeys — face, finger, iris — déléguée à @mostajs/auth
+//                  (startAuthentication/finishAuthentication, authenticator 'platform', userVerification 'required').
+// NB protocole : WebAuthn ne permet PAS d'exiger « iris » plutôt que « empreinte » — l'OS choisit la modalité ;
+//   face/finger/iris partagent donc le même mécanisme (UV=required), les noms sont du branding/UX.
+// Le module ne RÉSOUT pas les comptes lui-même : chaque dialecte magic-link reçoit un PORT userRepo
+//   ({ findByEmail, findByPhone }) fourni par le consumer (extraction-first, DB-agnostique comme @mostajs/orm).
+// Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+
+export const KINDS = Object.freeze({ MAGIC_LINK: 'magic-link', BIOMETRIC: 'biometric' });
+export const STATUS = Object.freeze({ ACTIVE: 'active', PLANNED: 'planned' });
+
+/** Normalise un numéro en gardant « + » et les chiffres (E.164) : « +213 790-37 35 90 » → « +213790373590 ». */
+export function normalizePhone(s) {
+  if (!s) return null;
+  const p = String(s).replace(/[^\d+]/g, '');
+  return p.replace(/\+(?=.*\+)/g, '') || null;   // un seul « + », en tête
+}
+
+/** Heuristique : un identifiant de connexion est-il un numéro de mobile (vs un email) ? */
+export function looksLikePhone(id) {
+  const s = String(id || '').trim();
+  if (s.includes('@')) return false;
+  return /^\+?[\d][\d\s.\-()]{5,}$/.test(s);
+}
+
+/**
+ * Catalogue par défaut des 6 variétés. Forme d'un dialecte :
+ *   { key, label, kind, status, channels?, requires?, notFound?, match?(id)->bool, resolve?(id,userRepo)->Promise<user|null>,
+ *     authenticator?, uv? }
+ *   - match/resolve : uniquement les magic-link sélectionnables par identifiant. L'ordre compte (1re correspondance gagne).
+ *   - sans match() (mail&sms, biométriques) : au CATALOGUE (UI/doc) mais pas auto-sélectionnés par un identifiant.
+ */
+export function defaultDialects() {
+  return [
+    // — magic-link, par canal de livraison —
+    {
+      key: 'mail', label: 'Email → magic-link', kind: KINDS.MAGIC_LINK, status: STATUS.ACTIVE,
+      channels: ['email'], notFound: 'unknown_email',
+      match: (id) => String(id).includes('@'),
+      resolve: (id, repo) => repo.findByEmail(id),
+    },
+    {
+      key: 'sms', label: 'Mobile → magic-sms-link', kind: KINDS.MAGIC_LINK, status: STATUS.ACTIVE,
+      channels: ['sms'], requires: 'sms', notFound: 'unknown_phone',
+      match: (id) => looksLikePhone(id),
+      resolve: (id, repo) => repo.findByPhone(id),
+    },
+    {
+      key: 'mail&sms', label: 'Email + SMS (double canal)', kind: KINDS.MAGIC_LINK, status: STATUS.ACTIVE,
+      channels: ['email', 'sms'], requires: 'sms',
+      // Pas de match() : COMPORTEMENT par défaut quand un compte a email + numéro (le port d'envoi livre sur les deux).
+    },
+    // — biométrie — deux familles de fournisseurs (provider) :
+    //   • face   : reconnaissance faciale côté CLIENT via face-api.js + capture caméra en PWA (« pwa-scan ») — pas de WebAuthn.
+    //   • finger/iris : authentificateur de plateforme WebAuthn/passkeys (vérification sur l'appareil), à câbler via @mostajs/auth.
+    { key: 'face', label: 'Reconnaissance faciale (face-api + PWA scan)', kind: KINDS.BIOMETRIC, status: STATUS.PLANNED, provider: 'face-api', capture: 'pwa-scan' },
+    { key: 'finger', label: 'Empreinte digitale (WebAuthn)', kind: KINDS.BIOMETRIC, status: STATUS.PLANNED, provider: 'webauthn', authenticator: 'platform', uv: 'required' },
+    { key: 'iris', label: 'Iris (WebAuthn)', kind: KINDS.BIOMETRIC, status: STATUS.PLANNED, provider: 'webauthn', authenticator: 'platform', uv: 'required' },
+  ];
+}
+
+/**
+ * Crée un registre de dialectes (extensible). API :
+ *   list()                 → copie du catalogue
+ *   get(key)               → un dialecte | null
+ *   byKind(kind)           → dialectes d'une famille
+ *   active()/planned()     → par statut
+ *   select(identifier)     → 1er dialecte dont match(identifier) est vrai (ou null)
+ *   register(dialect)      → upsert par key (mis EN TÊTE → priorité de match) ; renvoie le registre (chaînable)
+ */
+export function createDialectRegistry({ dialects = defaultDialects() } = {}) {
+  const list = dialects.map((d) => ({ ...d }));
+  const api = {
+    list: () => list.map((d) => ({ ...d })),
+    get: (key) => list.find((d) => d.key === key) || null,
+    byKind: (kind) => list.filter((d) => d.kind === kind).map((d) => ({ ...d })),
+    active: () => list.filter((d) => d.status === STATUS.ACTIVE).map((d) => ({ ...d })),
+    planned: () => list.filter((d) => d.status === STATUS.PLANNED).map((d) => ({ ...d })),
+    select: (identifier) => list.find((d) => typeof d.match === 'function' && d.match(identifier)) || null,
+    register(d) {
+      if (!d || !d.key) throw new Error('@mostajs/auth-dialects: dialect.key requis');
+      const i = list.findIndex((x) => x.key === d.key);
+      if (i >= 0) list[i] = { ...list[i], ...d };
+      else list.unshift(d);   // priorité de correspondance (avant mail/sms)
+      return api;
+    },
+  };
+  return api;
+}