@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 +267 -0
- package/package.json +1 -1
- package/src/index.d.ts +387 -0
- package/src/index.js +5 -1
- package/src/loginDevices.js +298 -0
- package/src/privateFileLinks.js +327 -0
- package/src/refreshTokens.js +214 -0
- package/src/trustedDevices.js +390 -0
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
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
|
};
|