@mostajs/auth 3.0.2 → 3.1.0

package/dist/lib/anon-token.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Génère un nouveau token anonyme — 32 caractères hexadécimaux issus de
+ * 16 bytes de `randomBytes` (CSPRNG).
+ */
+export declare function generateAnonToken(): string;
+/**
+ * Formate un email synthétique stable pour un token + un scope.
+ * Le scope évite qu'un même token "fuite" inter-projets *(domaine
+ * différent → email différent → respondent distinct par projet)*.
+ *
+ * Le résultat est non-routable (`.anon.local`) — pas de risque
+ * d'envoi mail par accident.
+ *
+ * @example
+ *   anonEmail('a1b2c3d4e5f6', 'survey-2026')
+ *   → 'anon-a1b2c3d4e5f6@survey-2026.anon.local'
+ */
+export declare function anonEmail(token: string, scope: string): string;
+/**
+ * Vrai si l'email donné a la forme générée par `anonEmail` — utile
+ * pour repérer les respondents anonymes dans les dashboards / exports
+ * sans avoir à stocker un flag séparé *(quoique le flag reste une
+ * bonne pratique pour la requête DB)*.
+ */
+export declare function isAnonEmail(email: string | null | undefined): boolean;
+/**
+ * Convention de nom du cookie à utiliser. Le consumer reste libre de
+ * choisir le sien, mais cette constante factorise la pratique courante.
+ */
+export declare const ANON_COOKIE_DEFAULT_NAME = "anon_tk";
+/**
+ * Options de cookie recommandées (utilisées par les implémentations
+ * Next/Express). Le consumer applique celles-ci à son cookie store.
+ */
+export declare const ANON_COOKIE_DEFAULT_OPTIONS: {
+    httpOnly: boolean;
+    sameSite: "lax";
+    path: string;
+    maxAge: number;
+};

package/dist/lib/anon-token.js

@@ -0,0 +1,69 @@
+// @mostajs/auth — Anonymous token primitives — v3.1.0+
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Pour les questionnaires / pages publiques `visibility=public-anon` qui
+// veulent retrouver les réponses entre sessions sans demander d'email.
+// Le module fournit uniquement les **primitives** : génération d'un token
+// aléatoire et formatage d'un email synthétique stable. Le **stockage du
+// cookie** est laissé au consumer car la signature dépend du framework
+// (Next.js `cookies()`, Express `res.cookie()`, etc.).
+//
+// Design clé :
+//   - 16 bytes de hasard cryptographique → 32 chars hex. Suffisant contre
+//     la collision (probabilité < 2⁻⁶⁴ pour 10⁹ tokens).
+//   - Email synthétique de la forme `anon-<token12>@<scope>.anon.local` :
+//     stable, reconnaissable comme anon dans les exports / dashboards,
+//     non-routable (TLD `.local` réservé) → impossible d'envoyer un mail
+//     dessus par accident.
+//   - Aucune dépendance externe — uniquement `node:crypto`.
+import { randomBytes } from 'node:crypto';
+/**
+ * Génère un nouveau token anonyme — 32 caractères hexadécimaux issus de
+ * 16 bytes de `randomBytes` (CSPRNG).
+ */
+export function generateAnonToken() {
+    return randomBytes(16).toString('hex');
+}
+/**
+ * Formate un email synthétique stable pour un token + un scope.
+ * Le scope évite qu'un même token "fuite" inter-projets *(domaine
+ * différent → email différent → respondent distinct par projet)*.
+ *
+ * Le résultat est non-routable (`.anon.local`) — pas de risque
+ * d'envoi mail par accident.
+ *
+ * @example
+ *   anonEmail('a1b2c3d4e5f6', 'survey-2026')
+ *   → 'anon-a1b2c3d4e5f6@survey-2026.anon.local'
+ */
+export function anonEmail(token, scope) {
+    const t = String(token ?? '').slice(0, 12);
+    const s = String(scope ?? 'default').toLowerCase().replace(/[^a-z0-9-]+/g, '-');
+    return `anon-${t}@${s}.anon.local`;
+}
+/**
+ * Vrai si l'email donné a la forme générée par `anonEmail` — utile
+ * pour repérer les respondents anonymes dans les dashboards / exports
+ * sans avoir à stocker un flag séparé *(quoique le flag reste une
+ * bonne pratique pour la requête DB)*.
+ */
+export function isAnonEmail(email) {
+    if (!email)
+        return false;
+    return /^anon-[a-f0-9]{12}@[a-z0-9-]+\.anon\.local$/.test(email);
+}
+/**
+ * Convention de nom du cookie à utiliser. Le consumer reste libre de
+ * choisir le sien, mais cette constante factorise la pratique courante.
+ */
+export const ANON_COOKIE_DEFAULT_NAME = 'anon_tk';
+/**
+ * Options de cookie recommandées (utilisées par les implémentations
+ * Next/Express). Le consumer applique celles-ci à son cookie store.
+ */
+export const ANON_COOKIE_DEFAULT_OPTIONS = {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 60 * 60 * 24 * 365, // 1 an
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/auth",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Authentication — complete: email/password (Argon2id) + OAuth + magic link + MFA TOTP + WebAuthn/Passkeys + RGPD lifecycle + device_flow/pkce events + accountId propagation server↔client",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",
@@ -113,6 +113,11 @@
       "import": "./dist/lib/magic-link.js",
       "default": "./dist/lib/magic-link.js"
     },
+    "./lib/anon-token": {
+      "types": "./dist/lib/anon-token.d.ts",
+      "import": "./dist/lib/anon-token.js",
+      "default": "./dist/lib/anon-token.js"
+    },
     "./lib/mfa-totp": {
       "types": "./dist/lib/mfa-totp.d.ts",
       "import": "./dist/lib/mfa-totp.js",