@astratra/security 1.9.1 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -309,6 +309,55 @@ propre store (Redis, etc.) qui implémente la même interface
309
309
  (`revoke`, `isRevoked`, et optionnellement `revokeAllForUser`/
310
310
  `isRevokedForUser`).
311
311
 
312
+ ## Rester connecté (jetons de rafraîchissement)
313
+
314
+ Un jeton d'accès est court par choix : c'est cette brièveté qui limite les
315
+ dégâts d'un vol. Le prix, c'est qu'il faut quelque chose pour le renouveler —
316
+ et ce quelque chose est un identifiant à longue vie. Mal fait, on a remplacé un
317
+ risque d'une heure par un risque d'un mois.
318
+
319
+ ```js
320
+ const refreshTokens = createRefreshTokenService({
321
+ store: createMemoryRefreshTokenStore(),
322
+ ttlMs: 30 * 24 * 60 * 60 * 1000
323
+ });
324
+
325
+ const { token, familyId } = await refreshTokens.issue({ userId: user.id });
326
+ const next = await refreshTokens.rotate(token); // l'ancien est mort
327
+ await refreshTokens.revokeAllForUser(user.id); // mot de passe changé
328
+ ```
329
+
330
+ **Ce n'est pas un JWT.** Le jeton ne prouve rien par lui-même et ne porte aucune
331
+ information : c'est une chaîne aléatoire, qui n'a de sens que comme ligne dans
332
+ un magasin. C'est ce qui le rend **révocable** — un jeton signé reste valable
333
+ jusqu'à son expiration, quoi qu'on en pense entre-temps.
334
+
335
+ **Il est rangé en empreinte, jamais en clair.** Une base volée ne donne alors
336
+ aucune session. Le jeton a toute l'entropie voulue, donc un SHA-256 suffit : il
337
+ n'y a rien à casser par force brute, et un hachage lent à chaque renouvellement
338
+ ne serait qu'une surface de déni de service.
339
+
340
+ **Il tourne à chaque usage.** Le jeton présenté est consommé, un neuf prend sa
341
+ place. Un jeton vu deux fois est donc une anomalie, pas un cas normal.
342
+
343
+ **Un rejeu tue la famille.** Quand un jeton déjà consommé revient, quelqu'un en
344
+ a gardé une copie : le client légitime est passé à autre chose depuis. Refuser
345
+ ce seul jeton laisserait le voleur avec celui **en cours** — c'est donc toute la
346
+ chaîne issue de cette connexion qui est révoquée. La vraie personne se
347
+ reconnecte : c'est le prix correct d'une session volée.
348
+
349
+ ### L'alphabet, et le bug qui l'a imposé
350
+
351
+ Les jetons sont en **hexadécimal**, pas en base64url. Ce dernier contient `-`,
352
+ donc environ un jeton sur cent trente portait un `--` quelque part. Le WAF
353
+ (section plus bas) lit `--` dans un corps de requête comme un commentaire SQL et
354
+ répond 403 : cette session ne pouvait alors **plus jamais** être renouvelée,
355
+ puisque le client rejoue le même jeton et se fait bloquer à chaque fois.
356
+ L'utilisateur était déconnecté pour des raisons que personne ne savait
357
+ reproduire.
358
+
359
+ Un identifiant ne doit jamais pouvoir être lu comme du contenu.
360
+
312
361
  ## Codes uniques
313
362
 
314
363
  ```js
@@ -553,6 +602,224 @@ const webauthn = createWebauthnService(createMemoryWebauthnStore(), {
553
602
  });
554
603
  ```
555
604
 
605
+ ## Fichiers privés : un lien signé par lecteur
606
+
607
+ Une balise `<img>` ou un lecteur audio n'envoient aucun en-tête
608
+ `Authorization` : un fichier privé ne peut donc pas être protégé par la seule
609
+ session, l'adresse elle-même doit porter un laissez-passer. C'est là qu'était le
610
+ vrai défaut.
611
+
612
+ **Le défaut.** Un message avec pièce jointe était diffusé en direct avec son
613
+ lien déjà signé — signé pour l'**expéditeur**, puisque c'est sa requête qui
614
+ produisait le message. Le destinataire ouvrait le fichier en empruntant
615
+ l'identité de l'autre, et le laissez-passer expirait un quart d'heure plus tard
616
+ dans une conversation restée ouverte. D'où la règle : **une diffusion ne porte
617
+ que le chemin** ; chaque lecteur demande **son** lien au moment d'afficher, et
618
+ le serveur revérifie le droit de lire à cette demande.
619
+
620
+ ```js
621
+ const {
622
+ createPrivateFileLinks, createPrivateFileHandler,
623
+ serializeForReader, serializeForBroadcast,
624
+ resolveStoredFile, privateFileHeaders
625
+ } = require('@astratra/security');
626
+
627
+ const links = createPrivateFileLinks({
628
+ secret: process.env.FILE_LINK_SECRET, // dédié, 32 caractères au moins
629
+ basePath: '/api/files',
630
+ // relu à chaque vérification : « déconnecter partout » tue aussi les liens déjà remis
631
+ accountVersion: async (accountId) => (await users.findById(accountId))?.tokenVersion ?? null
632
+ });
633
+
634
+ app.get('/api/files/:kind/:id', createPrivateFileHandler({
635
+ links,
636
+ authenticate: authMiddleware,
637
+ loadFile: (kind, id) => files[kind].findById(id),
638
+ canRead: (reader, kind, file) => policy.canRead(reader, kind, file), // ta règle d'accès
639
+ loadReader: (accountId) => users.findById(accountId),
640
+ send: (file, req, res) => {
641
+ const local = resolveStoredFile(PRIVATE_ROOT, file.storedName);
642
+ if (!local) return res.status(404).json({ success: false, code: 'FILE_UNAVAILABLE' });
643
+ res.set(privateFileHeaders({ mime: file.mime, fileName: file.name }));
644
+ return res.sendFile(local, { dotfiles: 'deny' });
645
+ }
646
+ }));
647
+
648
+ // Réponse à UNE personne : ses propres liens.
649
+ res.json(serializeForReader(messages, { links, reader: req.user, kind: 'messages', clearWhenDeleted: ['fileThumb'] }));
650
+ // Socket, push, webhook : le chemin seul.
651
+ io.to(room).emit('message', serializeForBroadcast(message, { links, kind: 'messages', clearWhenDeleted: ['fileThumb', 'content'] }));
652
+ ```
653
+
654
+ Les trois portes de la route, dans cet ordre :
655
+
656
+ | Requête | Qui lit | Rend |
657
+ |---|---|---|
658
+ | `?ticket=…` | le compte nommé dans le laissez-passer | le fichier |
659
+ | `?link=1` | la **session** (jamais un laissez-passer) | le lien de l'appelant |
660
+ | rien | la session | le fichier |
661
+
662
+ **Un laissez-passer n'en fabrique jamais un autre.** `?link=1` accompagné d'un
663
+ `ticket` passe par la session : sinon un lien fuité se renouvellerait sans fin.
664
+
665
+ **Le lien est stable pendant un pas.** Signé « maintenant », il changeait à
666
+ chaque réponse pour le même fichier : un fil relu toutes les cinq secondes
667
+ rendait une adresse neuve à chaque fois, aucun cache ne reconnaissait l'image,
668
+ et le lecteur audio repartait de zéro — un vocal ne se terminait jamais (202
669
+ requêtes en une minute, 79 Mo servis pour 600 Ko de fichiers). Le laissez-passer
670
+ est calé sur un pas de quinze minutes et vit deux pas.
671
+
672
+ **Hexadécimal de bout en bout.** Un JWT est en base64url, donc contient `-` :
673
+ environ un laissez-passer sur cent portait un `--`, que le WAF lit comme un
674
+ commentaire SQL dans la chaîne de requête. Ce fichier répondait alors 403 à
675
+ cette personne pendant tout le pas, sans que personne sache le reproduire.
676
+
677
+ **Ce qui est vérifié :** la signature (avant toute lecture du contenu),
678
+ l'expiration (un laissez-passer daté du futur est refusé), le fichier exact
679
+ (`kind` et `id`), le compte et sa version de session. Un refus d'accès répond le
680
+ même 404 qu'un fichier absent ; les corps ne portent qu'un `code`, jamais de
681
+ texte — les mots appartiennent à ton catalogue.
682
+
683
+ **Parcours de dossier.** `resolveStoredFile` n'accepte qu'un nom nu (ni
684
+ séparateur, ni NUL) et exige que le chemin résolu soit strictement **dans** la
685
+ racine : `.`, `..` et toute forme non prévue sont refusés.
686
+
687
+ **Un élément supprimé perd son adresse ET son aperçu, à toutes les
688
+ profondeurs.** Une citation (`replyTo`) d'un message supprimé porte le même
689
+ risque que le message lui-même.
690
+
691
+ ## Appareils de connexion et alertes de changement
692
+
693
+ ```js
694
+ const {
695
+ createLoginDeviceTracker, createMemoryLoginDeviceStore,
696
+ createChangeAlerts, createSecurityAlerter
697
+ } = require('@astratra/security');
698
+
699
+ const devices = createLoginDeviceTracker({
700
+ store: createMemoryLoginDeviceStore(), // upsert ATOMIQUE en prod (index unique)
701
+ secret: process.env.DEVICE_FINGERPRINT_SECRET,
702
+ notify: (account, event) => notifications.create(account.id, { key: 'security.new_login_device' })
703
+ });
704
+ // APRÈS avoir accordé la session ; ne lève jamais.
705
+ devices.record(user, { ip: req.ip, userAgent: req.headers['user-agent'] });
706
+
707
+ const changes = createChangeAlerts({
708
+ send: ({ to, key, locale, detail }) => mailer.send(to, t(locale, `${key}.subject`), t(locale, `${key}.body`, { detail }))
709
+ });
710
+ await changes.alert(user, 'password', { to: user.email });
711
+ await changes.alert(user, 'email', { previousEmail: before, newEmail: user.email });
712
+ await changes.alert(user, 'trusted-device', { to: user.email, detail: 'iPhone (iOS)' });
713
+ ```
714
+
715
+ **« Appareil » = agent utilisateur + famille d'adresse** (/16 en IPv4, /48 en
716
+ IPv6). Un /24 changeait à chaque bascule d'antenne d'un opérateur mobile : une
717
+ alerte par jour pour son propre téléphone, et une alerte quotidienne n'est plus
718
+ lue. L'IPv6 est **développée** avant d'être coupée : `2001:db8::5` et
719
+ `2001:db8:0:1::5` sont le même /48. Seule une empreinte HMAC est gardée, bornée
720
+ par compte. Aucune alerte à la toute première connexion.
721
+
722
+ **Un changement d'adresse prévient l'ANCIENNE.** La nouvelle est déjà entre les
723
+ mains de qui a fait la manœuvre. Une **première** adresse ne prévient personne.
724
+
725
+ **Un envoi raté ne fait jamais échouer le changement** : le mot de passe est
726
+ déjà modifié ; une erreur ferait croire le contraire.
727
+
728
+ **Aucun texte ici.** Le module décide QUAND prévenir et QUI ; tu reçois une clé
729
+ de catalogue (`security.change.password`, `…email`, `…factor-added`,
730
+ `…factor-removed`, `…recovery-codes`, `…trusted-device`) et la langue du compte.
731
+ Pas de bouton d'action dans une alerte : elle ne doit pas apprendre à cliquer
732
+ sur un lien reçu par courriel.
733
+
734
+ `createSecurityAlerter({ channels })` diffuse une alerte **d'exploitation**
735
+ (webhook, boîte dédiée) : un canal en panne ne fait pas taire les autres, et
736
+ rien ne remonte à la requête qui l'a levée.
737
+
738
+ ## Appareil de confiance (Face ID, empreinte)
739
+
740
+ Se reconnecter par le verrou du téléphone plutôt que par le mot de passe, sur
741
+ un appareil qui s'est déjà connecté.
742
+
743
+ **Un secret roté, pas une paire de clés.** Une paire n'apporte quelque chose que
744
+ si la clé privée reste dans la puce sécurisée et ne signe qu'après la biométrie
745
+ — ce qui demande un module natif. En JavaScript, elle serait rangée dans le même
746
+ trousseau que le secret, et volée de la même façon. Le secret roté donne en plus
747
+ ce que la paire ne donne pas : **un secret copié puis rejoué se voit**.
748
+
749
+ ```js
750
+ const { createTrustedDeviceService, createMemoryTrustedDeviceStore, TrustedDeviceError } = require('@astratra/security');
751
+
752
+ const trusted = createTrustedDeviceService({
753
+ store: createMemoryTrustedDeviceStore(), // consume() = compare-and-swap ATOMIQUE en prod
754
+ pepper: process.env.TRUSTED_DEVICE_PEPPER,
755
+ onReplay: async ({ accountId }) => { // on ne sait pas qui est le vrai : tout tombe
756
+ await refreshTokens.revokeAllForUser(accountId);
757
+ await alerter.send({ level: 'FATAL', type: 'trusted_device.replay', meta: { accountId } });
758
+ }
759
+ });
760
+
761
+ // POST /trusted-devices — session COMPLÈTE exigée
762
+ const device = await trusted.enroll({
763
+ accountId: user.id,
764
+ credentialStamp: user.passwordHash, // mot de passe changé = appareil éteint
765
+ requireSecondFactor: policy.needsMfa(user),
766
+ secondFactorVerified: req.user.mfaVerified,
767
+ deviceName: req.body.deviceName,
768
+ platform: req.body.platform
769
+ });
770
+ await changes.alert(user, 'trusted-device', { to: user.email, detail: device.deviceName });
771
+
772
+ // POST /trusted-device/session — sans session
773
+ try {
774
+ const next = await trusted.exchange(req.body, { loadAccount: async (id) => {
775
+ const u = await users.findById(id);
776
+ return u && { credentialStamp: u.passwordHash, disabled: u.suspended || u.deletionPending };
777
+ } });
778
+ const session = await issueSession(next.accountId, { mfaVerified: next.secondFactorVerified });
779
+ res.json({ ...session, trustedDevice: { deviceId: next.deviceId, secret: next.secret } });
780
+ } catch (error) {
781
+ if (error instanceof TrustedDeviceError) return res.status(error.statusCode).json({ success: false, code: error.code });
782
+ throw error;
783
+ }
784
+ ```
785
+
786
+ Si ton émission de session refuse (compte suspendu, rôle coupé), appelle
787
+ `trusted.revoke(next.id, 'session-refused')`. Branche `trusted.revokeAll(id)` sur
788
+ « déconnecter partout », le changement de mot de passe et la suppression de
789
+ compte ; la **déconnexion simple garde l'appareil** — c'est tout son intérêt.
790
+
791
+ Garanties : empreinte HMAC seule en base ; enrôlement depuis une session
792
+ complète ; secret consommé une fois, de façon atomique ; rejeu → appareil
793
+ révoqué + `onReplay` ; lien au mot de passe en vigueur ; 30 jours sans usage ;
794
+ 10 essais par appareil et par quart d'heure (monte **aussi**
795
+ `createLoginLimiter` par adresse) ; cinq appareils au plus ; même erreur pour
796
+ tout échec. Un appareil révoqué est simplement refusé : le traiter en rejeu
797
+ déconnecterait son propriétaire partout pour un vieux téléphone.
798
+
799
+ ### Le protocole, côté téléphone (`@astratra/native`)
800
+
801
+ Les deux paquets parlent le même contrat :
802
+
803
+ | Étape | Téléphone | Serveur |
804
+ |---|---|---|
805
+ | Activer | `gate.enable()` (invite biométrique), puis `POST /trusted-devices` avec `{ deviceName, platform }` | `enroll()` → `{ deviceId, secret }` (hex 32 / 64) |
806
+ | Ranger | `keystore.setItemAsync('<ns>.trustedDevice', JSON.stringify({ deviceId, secret }))` — le même `Keystore` que `createSecureSession` | rien en clair |
807
+ | Se reconnecter | `gate.confirm()` **puis** `POST /trusted-device/session` avec `{ deviceId, secret }` | `exchange()` → session + **nouveau** secret |
808
+ | Après | écrire le nouveau secret **avant** d'utiliser la session : l'ancien est mort | l'ancien reste en empreinte pour reconnaître un rejeu |
809
+ | Oublier | `POST /trusted-device/forget` avec `{ deviceId, secret }`, puis effacer la clé | `forget()`, réponse identique dans tous les cas |
810
+
811
+ La biométrie reste **locale** : le serveur ne reçoit jamais de preuve
812
+ biométrique, il reçoit le secret que le trousseau ne libère qu'après
813
+ `gate.confirm()`. Un secret perdu entre la réponse et l'écriture (application
814
+ tuée) ne se rattrape pas : l'appareil repasse par le mot de passe.
815
+
816
+ **Attention à `createSecureSession().clear()`** : à la déconnexion, il efface le
817
+ drapeau biométrique, donc `gate.confirm()` répond `false` ensuite — alors que
818
+ l'appareil de confiance existe justement pour se reconnecter **après** une
819
+ déconnexion. Garde le secret d'appareil sous sa propre clé (non effacée par
820
+ `clear()`), et fonde l'offre « se connecter avec Face ID » sur la présence de ce
821
+ secret et sur `gate.read().supported`, pas sur `enabled`.
822
+
556
823
  ## Tests
557
824
 
558
825
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/security",
3
- "version": "1.9.1",
3
+ "version": "1.11.0",
4
4
  "description": "Generic authentication and security middleware for Astratra workspaces.",
5
5
  "engines": {
6
6
  "node": ">=20"
package/src/index.d.ts CHANGED
@@ -507,3 +507,390 @@ export function createMemoryAuditStore(): AuditStore & {
507
507
 
508
508
  export function hashEvent(event: Record<string, unknown>): string;
509
509
  export const GENESIS_HASH: string;
510
+
511
+ /* ────────────────────────── Refresh tokens ────────────────────────── */
512
+
513
+ export type RefreshTokenErrorCode =
514
+ | 'REFRESH_TOKEN_INVALID'
515
+ | 'REFRESH_TOKEN_EXPIRED'
516
+ | 'REFRESH_TOKEN_REUSED';
517
+
518
+ export class RefreshTokenError extends Error {
519
+ name: 'RefreshTokenError';
520
+ code: RefreshTokenErrorCode;
521
+ constructor(message: string, code: RefreshTokenErrorCode);
522
+ }
523
+
524
+ export interface RefreshTokenRecord {
525
+ id: string;
526
+ familyId: string;
527
+ userId: string;
528
+ /** SHA-256 of the token. The token itself is never stored. */
529
+ hash: string;
530
+ createdAt: number;
531
+ expiresAt: number;
532
+ consumedAt: number | null;
533
+ revokedAt: number | null;
534
+ }
535
+
536
+ export interface RefreshTokenStore {
537
+ save(record: RefreshTokenRecord): Promise<unknown>;
538
+ findByHash(hash: string): Promise<RefreshTokenRecord | null>;
539
+ markConsumed(id: string, at: number): Promise<unknown>;
540
+ revokeFamily(familyId: string, at: number): Promise<unknown>;
541
+ revokeAllForUser(userId: string, at: number): Promise<unknown>;
542
+ deleteExpired?(before: number): Promise<number>;
543
+ }
544
+
545
+ export function createMemoryRefreshTokenStore(): RefreshTokenStore & {
546
+ all(): Promise<RefreshTokenRecord[]>;
547
+ };
548
+
549
+ export interface IssuedRefreshToken {
550
+ /** Hand this to the client. It is never stored, and never seen again. */
551
+ token: string;
552
+ id: string;
553
+ familyId: string;
554
+ userId: string;
555
+ expiresAt: number;
556
+ }
557
+
558
+ export interface RefreshTokenService {
559
+ issue(input: { userId: string }): Promise<IssuedRefreshToken>;
560
+ /** Spends the token and returns the next one. Replay revokes the family. */
561
+ rotate(token: string | null | undefined): Promise<IssuedRefreshToken>;
562
+ revokeFamily(familyId: string): Promise<void>;
563
+ revokeAllForUser(userId: string): Promise<void>;
564
+ prune(): Promise<number>;
565
+ fingerprint(token: string): string;
566
+ }
567
+
568
+ export function createRefreshTokenService(options: {
569
+ store: RefreshTokenStore;
570
+ ttlMs?: number;
571
+ now?: () => number;
572
+ randomToken?: () => string;
573
+ }): RefreshTokenService;
574
+
575
+ /* ─────────────────────── Private file links ─────────────────────── */
576
+
577
+ export type PrivateFileLinkFailure =
578
+ | 'missing'
579
+ | 'malformed'
580
+ | 'bad-signature'
581
+ | 'expired'
582
+ | 'wrong-file'
583
+ | 'unknown-account'
584
+ | 'revoked';
585
+
586
+ export interface PrivateFileReader {
587
+ id?: unknown;
588
+ _id?: unknown;
589
+ /** Session version; a pass signed under an older one is refused. */
590
+ version?: number;
591
+ tokenVersion?: number;
592
+ [key: string]: unknown;
593
+ }
594
+
595
+ export interface SignedFileLink {
596
+ /** Hex only: a WAF never reads it as an SQL comment. */
597
+ ticket: string;
598
+ url: string;
599
+ issuedAt: number;
600
+ expiresAt: number;
601
+ }
602
+
603
+ export type PrivateFileLinkCheck =
604
+ | { valid: true; accountId: string; version: number; expiresAt: number }
605
+ | { valid: false; reason: PrivateFileLinkFailure };
606
+
607
+ export interface PrivateFileLinks {
608
+ readonly stepSeconds: number;
609
+ readonly ticketParam: string;
610
+ /** A pass for ONE reader and ONE file, identical within a time step. */
611
+ sign(input: { kind: string; fileId: unknown; accountId: unknown; version?: number }): SignedFileLink;
612
+ /** The reader's own link, or null without a reader. */
613
+ linkFor(kind: string, fileId: unknown, reader: PrivateFileReader | null | undefined): string | null;
614
+ /** The address with no pass — the only form a broadcast may carry. */
615
+ pathFor(kind: string, fileId: unknown): string;
616
+ verify(ticket: string | null | undefined, target: { kind: string; fileId: unknown }): Promise<PrivateFileLinkCheck>;
617
+ }
618
+
619
+ export function createPrivateFileLinks(options: {
620
+ /** Dedicated to file links, at least 32 characters. */
621
+ secret: string;
622
+ stepSeconds?: number;
623
+ basePath?: string;
624
+ ticketParam?: string;
625
+ /** Current session version of an account, null once it no longer exists. */
626
+ accountVersion?: (accountId: string) => Awaitable<number | null | undefined>;
627
+ now?: () => number;
628
+ }): PrivateFileLinks;
629
+
630
+ export interface FileFieldOptions {
631
+ /** Kind of the file, or a function of the record. */
632
+ kind: string | ((record: Record<string, unknown>) => string);
633
+ field?: string;
634
+ idField?: string;
635
+ deletedField?: string;
636
+ /** Fields nulled on a deleted record — a thumbnail, a quoted text. */
637
+ clearWhenDeleted?: string[];
638
+ }
639
+
640
+ /** For a response to ONE reader: every file address becomes that reader's link. */
641
+ export function serializeForReader<T>(value: T, options: FileFieldOptions & { links: PrivateFileLinks; reader: PrivateFileReader | null | undefined }): T;
642
+ /** For anything sent to several people: the path only. */
643
+ export function serializeForBroadcast<T>(value: T, options: FileFieldOptions & { links: PrivateFileLinks }): T;
644
+ /** A bare stored name resolved strictly inside root, or null. */
645
+ export function resolveStoredFile(root: string, name: string): string | null;
646
+ export function privateFileHeaders(file: { mime?: string; fileName?: string }): Record<string, string>;
647
+
648
+ export interface PrivateFileRequest extends RequestLike {
649
+ params?: { kind?: string; id?: string; [key: string]: string | undefined };
650
+ }
651
+
652
+ export function createPrivateFileHandler<TFile = unknown, TReader extends PrivateFileReader = PrivateFileReader>(options: {
653
+ links: PrivateFileLinks;
654
+ /** Your session middleware; must set req.user. */
655
+ authenticate: RequestHandler;
656
+ loadFile: (kind: string, id: string) => Awaitable<TFile | null | undefined>;
657
+ canRead: (reader: TReader, kind: string, file: TFile) => Awaitable<boolean>;
658
+ /** The reader behind a valid pass. */
659
+ loadReader: (accountId: string) => Awaitable<TReader | null | undefined>;
660
+ send: (file: TFile, req: PrivateFileRequest, res: ResponseLike) => Awaitable<unknown>;
661
+ }): (req: PrivateFileRequest, res: ResponseLike, next: NextFunction) => Promise<unknown>;
662
+
663
+ export const PRIVATE_FILE_STEP_SECONDS: number;
664
+
665
+ /* ─────────────────────── Sign-in devices and change alerts ─────────────────────── */
666
+
667
+ /** /16 in IPv4, /48 in IPv6 (expanded first), 'unknown' otherwise. */
668
+ export function ipFamily(ip: string | null | undefined): string;
669
+
670
+ export interface LoginDeviceStore {
671
+ /** Must be atomic: exactly one `inserted: true` per new (account, fingerprint). */
672
+ upsert(accountId: string, fingerprint: string, at: number): Awaitable<{ inserted: boolean }>;
673
+ count(accountId: string): Awaitable<number>;
674
+ keepMostRecent?(accountId: string, keep: number): Awaitable<unknown>;
675
+ }
676
+
677
+ export interface LoginDeviceRow {
678
+ accountId: string;
679
+ fingerprint: string;
680
+ firstSeenAt: number;
681
+ lastSeenAt: number;
682
+ }
683
+
684
+ export function createMemoryLoginDeviceStore(): LoginDeviceStore & { all(): Promise<LoginDeviceRow[]> };
685
+
686
+ export interface LoginDeviceAccount {
687
+ id?: unknown;
688
+ _id?: unknown;
689
+ [key: string]: unknown;
690
+ }
691
+
692
+ export interface LoginDeviceResult {
693
+ isNew: boolean;
694
+ firstDevice: boolean;
695
+ notified: boolean;
696
+ error?: true;
697
+ }
698
+
699
+ export interface LoginDeviceTracker {
700
+ /** Never throws: call it after the session is granted. */
701
+ record(account: LoginDeviceAccount, context?: { ip?: string; userAgent?: string }): Promise<LoginDeviceResult>;
702
+ fingerprint(context?: { ip?: string; userAgent?: string }): string;
703
+ }
704
+
705
+ export function createLoginDeviceTracker<TAccount extends LoginDeviceAccount = LoginDeviceAccount>(options: {
706
+ store: LoginDeviceStore;
707
+ secret: string;
708
+ notify: (account: TAccount, event: { type: 'new-login-device'; at: number }) => Awaitable<unknown>;
709
+ maxDevices?: number;
710
+ onError?: (error: unknown) => void;
711
+ now?: () => number;
712
+ }): LoginDeviceTracker;
713
+
714
+ export const DEFAULT_MAX_LOGIN_DEVICES: number;
715
+
716
+ export type ChangeType =
717
+ | 'password'
718
+ | 'email'
719
+ | 'factor-added'
720
+ | 'factor-removed'
721
+ | 'recovery-codes'
722
+ | 'trusted-device';
723
+
724
+ export const CHANGE_TYPES: readonly ChangeType[];
725
+
726
+ export interface ChangeAlertMessage<TAccount = unknown> {
727
+ to: string;
728
+ /** `${keyPrefix}.${change}` — render it from your own catalogue. */
729
+ key: string;
730
+ locale?: string;
731
+ change: ChangeType;
732
+ detail?: string;
733
+ account: TAccount;
734
+ }
735
+
736
+ export interface ChangeAlerts<TAccount = unknown> {
737
+ /** Never throws on a failed send; resolves whether the alert was handed over. */
738
+ alert(account: TAccount, change: ChangeType, input?: {
739
+ to?: string;
740
+ previousEmail?: string;
741
+ newEmail?: string;
742
+ detail?: string;
743
+ }): Promise<boolean>;
744
+ readonly CHANGE_TYPES: readonly ChangeType[];
745
+ }
746
+
747
+ export function createChangeAlerts<TAccount = unknown>(options: {
748
+ send: (message: ChangeAlertMessage<TAccount>) => Awaitable<unknown>;
749
+ keyPrefix?: string;
750
+ localeOf?: (account: TAccount) => string | undefined;
751
+ onError?: (error: unknown, change: ChangeType) => void;
752
+ }): ChangeAlerts<TAccount>;
753
+
754
+ export type AlertLevel = 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
755
+ export const ALERT_LEVELS: readonly AlertLevel[];
756
+
757
+ export interface OperatorAlert {
758
+ level: AlertLevel;
759
+ type: string;
760
+ subject: string;
761
+ message?: string;
762
+ meta: Record<string, unknown>;
763
+ timestamp: string;
764
+ }
765
+
766
+ export function createSecurityAlerter(options?: {
767
+ channels?: Array<(alert: OperatorAlert) => Awaitable<unknown>>;
768
+ log?: (line: string, alert: OperatorAlert) => void;
769
+ now?: () => number;
770
+ }): {
771
+ /** True when at least one channel delivered. Never throws. */
772
+ send(alert?: { level?: string; type?: string; subject?: string; message?: string; meta?: Record<string, unknown> }): Promise<boolean>;
773
+ };
774
+
775
+ /* ─────────────────────── Trusted devices ─────────────────────── */
776
+
777
+ export type TrustedDeviceErrorCode =
778
+ | 'TRUSTED_DEVICE_REJECTED'
779
+ | 'TRUSTED_DEVICE_THROTTLED'
780
+ | 'SECOND_FACTOR_REQUIRED';
781
+
782
+ export class TrustedDeviceError extends Error {
783
+ name: 'TrustedDeviceError';
784
+ code: TrustedDeviceErrorCode;
785
+ statusCode: 401 | 403 | 429;
786
+ retryAfterMs?: number;
787
+ constructor(code: TrustedDeviceErrorCode, extra?: Record<string, unknown>);
788
+ }
789
+
790
+ export interface TrustedDeviceRecord {
791
+ id: string;
792
+ accountId: string;
793
+ deviceId: string;
794
+ secretHash: string;
795
+ previousHashes: string[];
796
+ secondFactorVerified: boolean;
797
+ credentialBinding: string;
798
+ deviceName: string;
799
+ platform: 'ios' | 'android' | 'web' | 'other';
800
+ createdAt: number;
801
+ lastUsedAt: number;
802
+ expiresAt: number;
803
+ revokedAt: number | null;
804
+ revokedReason: string | null;
805
+ }
806
+
807
+ export interface TrustedDeviceFilter {
808
+ id?: string | string[];
809
+ accountId?: string;
810
+ deviceId?: string;
811
+ secretHash?: string;
812
+ }
813
+
814
+ export interface TrustedDeviceStore {
815
+ create(record: Omit<TrustedDeviceRecord, 'previousHashes'>): Awaitable<unknown>;
816
+ findByDeviceId(deviceId: string): Awaitable<TrustedDeviceRecord | null>;
817
+ /** Atomic compare-and-swap on secretHash. */
818
+ consume(id: string, expectedHash: string, next: { secretHash: string; lastUsedAt: number; expiresAt: number; keep: number }): Awaitable<boolean>;
819
+ /** Revokes the non-revoked rows matching filter; returns how many. */
820
+ revoke(filter: TrustedDeviceFilter, reason: string, at: number, keepUntil: number): Awaitable<number>;
821
+ listActive(accountId: string): Awaitable<TrustedDeviceRecord[]>;
822
+ }
823
+
824
+ export function createMemoryTrustedDeviceStore(): TrustedDeviceStore & { all(): Promise<TrustedDeviceRecord[]> };
825
+
826
+ export interface AttemptCounter {
827
+ hit(key: string, windowMs: number, at: number): Awaitable<{ count: number; resetAt: number }>;
828
+ }
829
+
830
+ export function createMemoryAttemptCounter(): AttemptCounter;
831
+
832
+ export interface TrustedDeviceProof {
833
+ deviceId: string;
834
+ secret: string;
835
+ }
836
+
837
+ export interface EnrolledTrustedDevice extends TrustedDeviceProof {
838
+ id: string;
839
+ expiresAt: number;
840
+ }
841
+
842
+ export interface TrustedDeviceExchange extends TrustedDeviceProof {
843
+ id: string;
844
+ accountId: string;
845
+ secondFactorVerified: boolean;
846
+ expiresAt: number;
847
+ }
848
+
849
+ export interface TrustedDeviceSummary {
850
+ id: string;
851
+ deviceName: string;
852
+ platform: string;
853
+ createdAt: number;
854
+ lastUsedAt: number;
855
+ expiresAt: number;
856
+ }
857
+
858
+ export interface TrustedDeviceService {
859
+ enroll(input: {
860
+ accountId: string;
861
+ /** Changes whenever the password changes — the stored password hash. */
862
+ credentialStamp: string;
863
+ requireSecondFactor?: boolean;
864
+ secondFactorVerified?: boolean;
865
+ deviceName?: string;
866
+ platform?: string;
867
+ }): Promise<EnrolledTrustedDevice>;
868
+ exchange(
869
+ proof: Partial<TrustedDeviceProof> | null | undefined,
870
+ context: { loadAccount: (accountId: string) => Awaitable<{ credentialStamp: unknown; disabled?: boolean } | null | undefined> }
871
+ ): Promise<TrustedDeviceExchange>;
872
+ forget(proof: Partial<TrustedDeviceProof> | null | undefined): Promise<void>;
873
+ list(accountId: string): Promise<TrustedDeviceSummary[]>;
874
+ remove(accountId: string, id: string): Promise<boolean>;
875
+ revokeAll(accountId: string, reason?: string): Promise<number>;
876
+ revoke(id: string, reason?: string): Promise<number>;
877
+ fingerprint(secret: string): string;
878
+ }
879
+
880
+ export function createTrustedDeviceService(options: {
881
+ store: TrustedDeviceStore;
882
+ pepper: string;
883
+ attempts?: AttemptCounter;
884
+ maxAttempts?: number;
885
+ attemptWindowMs?: number;
886
+ idleTtlMs?: number;
887
+ maxDevices?: number;
888
+ keptFingerprints?: number;
889
+ retentionAfterRevokeMs?: number;
890
+ onReplay?: (event: { accountId: string; id: string; at: number }) => Awaitable<unknown>;
891
+ onError?: (error: unknown) => void;
892
+ now?: () => number;
893
+ }): TrustedDeviceService;
894
+
895
+ export const TRUSTED_DEVICE_ID_PATTERN: RegExp;
896
+ export const TRUSTED_DEVICE_SECRET_PATTERN: RegExp;
package/src/index.js CHANGED
@@ -14,7 +14,11 @@ module.exports = {
14
14
  ...require('./cookies'),
15
15
  ...require('./csrf'),
16
16
  ...require('./revocation'),
17
+ ...require('./refreshTokens'),
17
18
  ...require('./stableStringify'),
18
19
  ...require('./serviceSignature'),
19
- ...require('./auditChain')
20
+ ...require('./auditChain'),
21
+ ...require('./privateFileLinks'),
22
+ ...require('./loginDevices'),
23
+ ...require('./trustedDevices')
20
24
  };