@astratra/security 1.10.0 → 1.11.1
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/LICENSE +1 -1
- package/README.md +218 -0
- package/package.json +1 -1
- package/src/index.d.ts +326 -0
- package/src/index.js +4 -1
- package/src/loginDevices.js +298 -0
- package/src/privateFileLinks.js +327 -0
- package/src/trustedDevices.js +390 -0
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -602,6 +602,224 @@ const webauthn = createWebauthnService(createMemoryWebauthnStore(), {
|
|
|
602
602
|
});
|
|
603
603
|
```
|
|
604
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
|
+
|
|
605
823
|
## Tests
|
|
606
824
|
|
|
607
825
|
```bash
|
package/package.json
CHANGED
package/src/index.d.ts
CHANGED
|
@@ -571,3 +571,329 @@ export function createRefreshTokenService(options: {
|
|
|
571
571
|
now?: () => number;
|
|
572
572
|
randomToken?: () => string;
|
|
573
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;
|
|
897
|
+
|
|
898
|
+
export const DEFAULT_PERMISSIONS_POLICY: 'geolocation=(), camera=(), microphone=(), payment=()';
|
|
899
|
+
export const DEFAULT_CSRF_COOKIE_NAME: 'astratra_csrf';
|
package/src/index.js
CHANGED
|
@@ -17,5 +17,8 @@ module.exports = {
|
|
|
17
17
|
...require('./refreshTokens'),
|
|
18
18
|
...require('./stableStringify'),
|
|
19
19
|
...require('./serviceSignature'),
|
|
20
|
-
...require('./auditChain')
|
|
20
|
+
...require('./auditChain'),
|
|
21
|
+
...require('./privateFileLinks'),
|
|
22
|
+
...require('./loginDevices'),
|
|
23
|
+
...require('./trustedDevices')
|
|
21
24
|
};
|