@mostajs/auth 3.0.2 → 3.2.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/dist/lib/invite-token.d.ts

@@ -0,0 +1,54 @@
+export interface InviteTokenPayload {
+    /** Identifiant opaque de la ressource (project id, cohort id, etc.). */
+    id: string;
+    /** Expiration epoch ms. */
+    exp: number;
+    /** Version du format (réservé pour évolutions, default 1). */
+    v?: number;
+    /** Champs métier libres — ex: kind, role, scope. */
+    meta?: Record<string, string | number | boolean>;
+}
+/**
+ * Signe un token. Le payload est sérialisé en JSON puis encodé en
+ * base64url, signé HMAC-SHA256 avec `secret`. La signature est
+ * concaténée au payload : `body.sig`.
+ *
+ * @param secret  Clé HMAC (≥ 32 bytes recommandés en prod).
+ * @param id      Identifiant de la ressource encodée.
+ * @param ttlMs   Durée de validité en ms (default 60 jours).
+ * @param meta    Champs métier optionnels.
+ */
+export declare function signInviteToken(secret: string | Buffer, id: string, ttlMs?: number, meta?: Record<string, string | number | boolean>): string;
+export type VerifyResult = {
+    ok: true;
+    payload: InviteTokenPayload;
+} | {
+    ok: false;
+    reason: 'malformed' | 'bad_signature' | 'expired';
+};
+/**
+ * Vérifie + décode un token. Validation en 3 passes :
+ *   1. format `<body>.<sig>`
+ *   2. signature HMAC en time-safe compare
+ *   3. payload non expiré
+ */
+export declare function verifyInviteToken(secret: string | Buffer, token: string): VerifyResult;
+/**
+ * Variante simplifiée — retourne le payload ou null si invalide.
+ * Utile pour les callers qui ne distinguent pas les raisons d'échec.
+ */
+export declare function decodeInviteToken(secret: string | Buffer, token: string): InviteTokenPayload | null;
+/**
+ * Factory — retourne `{ sign, verify, decode }` pré-liés à un secret.
+ * Évite de répéter le secret à chaque appel.
+ *
+ * @example
+ *   const inviteTokens = createInviteTokenSigner(process.env.INVITE_SECRET!)
+ *   const t = inviteTokens.sign('project-42')
+ *   const p = inviteTokens.decode(t)
+ */
+export declare function createInviteTokenSigner(secret: string | Buffer): {
+    sign: (id: string, ttlMs?: number, meta?: Record<string, string | number | boolean>) => string;
+    verify: (token: string) => VerifyResult;
+    decode: (token: string) => InviteTokenPayload | null;
+};

package/dist/lib/invite-token.js

@@ -0,0 +1,105 @@
+// @mostajs/auth — Invite token (HMAC signed) — v3.2.0+
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Token signé HMAC pour matérialiser une invitation persistente vers une
+// ressource (projet, cohort, contenu privé). Plus léger qu'un magic-link :
+//   - pas de nonce single-use → le même lien peut être scanné/cliqué N fois
+//   - pas de DB write → pure crypto stateless
+//   - TTL long (jours / semaines) — adapté au QR code affiché en
+//     présentation, ou au lien collé dans un mailing étalé.
+//
+// Compromis : un attaquant qui intercepte le lien peut s'inscrire à la
+// place du destinataire — d'où la signature HMAC + un payload minimal
+// (juste un id de ressource), et l'usage en complément d'un magic-link
+// sur les actions sensibles.
+//
+// Format : `<base64url(json-payload)>.<base64url(hmac)>`
+import { createHmac, timingSafeEqual } from 'node:crypto';
+function b64url(buf) {
+    return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromB64url(s) {
+    const pad = (4 - (s.length % 4)) % 4;
+    return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(pad), 'base64');
+}
+function asKey(secret) {
+    return Buffer.isBuffer(secret) ? secret : Buffer.from(secret, 'utf8');
+}
+/**
+ * Signe un token. Le payload est sérialisé en JSON puis encodé en
+ * base64url, signé HMAC-SHA256 avec `secret`. La signature est
+ * concaténée au payload : `body.sig`.
+ *
+ * @param secret  Clé HMAC (≥ 32 bytes recommandés en prod).
+ * @param id      Identifiant de la ressource encodée.
+ * @param ttlMs   Durée de validité en ms (default 60 jours).
+ * @param meta    Champs métier optionnels.
+ */
+export function signInviteToken(secret, id, ttlMs = 60 * 24 * 3600 * 1000, meta) {
+    const payload = { id, exp: Date.now() + ttlMs, v: 1 };
+    if (meta)
+        payload.meta = meta;
+    const body = b64url(Buffer.from(JSON.stringify(payload), 'utf8'));
+    const sig = createHmac('sha256', asKey(secret)).update(body).digest();
+    return `${body}.${b64url(sig)}`;
+}
+/**
+ * Vérifie + décode un token. Validation en 3 passes :
+ *   1. format `<body>.<sig>`
+ *   2. signature HMAC en time-safe compare
+ *   3. payload non expiré
+ */
+export function verifyInviteToken(secret, token) {
+    const parts = token.split('.');
+    if (parts.length !== 2)
+        return { ok: false, reason: 'malformed' };
+    const [body, sig] = parts;
+    const expected = createHmac('sha256', asKey(secret)).update(body).digest();
+    let got;
+    try {
+        got = fromB64url(sig);
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    if (got.length !== expected.length)
+        return { ok: false, reason: 'bad_signature' };
+    if (!timingSafeEqual(got, expected))
+        return { ok: false, reason: 'bad_signature' };
+    let payload;
+    try {
+        payload = JSON.parse(fromB64url(body).toString('utf8'));
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    if (typeof payload.id !== 'string' || typeof payload.exp !== 'number')
+        return { ok: false, reason: 'malformed' };
+    if (Date.now() > payload.exp)
+        return { ok: false, reason: 'expired' };
+    return { ok: true, payload };
+}
+/**
+ * Variante simplifiée — retourne le payload ou null si invalide.
+ * Utile pour les callers qui ne distinguent pas les raisons d'échec.
+ */
+export function decodeInviteToken(secret, token) {
+    const r = verifyInviteToken(secret, token);
+    return r.ok ? r.payload : null;
+}
+/**
+ * Factory — retourne `{ sign, verify, decode }` pré-liés à un secret.
+ * Évite de répéter le secret à chaque appel.
+ *
+ * @example
+ *   const inviteTokens = createInviteTokenSigner(process.env.INVITE_SECRET!)
+ *   const t = inviteTokens.sign('project-42')
+ *   const p = inviteTokens.decode(t)
+ */
+export function createInviteTokenSigner(secret) {
+    return {
+        sign: (id, ttlMs, meta) => signInviteToken(secret, id, ttlMs, meta),
+        verify: (token) => verifyInviteToken(secret, token),
+        decode: (token) => decodeInviteToken(secret, token),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/auth",
-  "version": "3.0.2",
+  "version": "3.2.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,16 @@
       "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/invite-token": {
+      "types": "./dist/lib/invite-token.d.ts",
+      "import": "./dist/lib/invite-token.js",
+      "default": "./dist/lib/invite-token.js"
+    },
     "./lib/mfa-totp": {
       "types": "./dist/lib/mfa-totp.d.ts",
       "import": "./dist/lib/mfa-totp.js",