Vérifier qu’un mot de passe respecte la politique

"""
Contrôler un mot de passe contre la politique que la norme demande vraiment.

Niveau N0. La NIST SP 800-63B-4 est courte, et ses exigences sont des règles,
pas des jugements : quinze caractères pour un mot de passe employé seul, au
moins soixante-quatre permis, aucune règle de composition, aucun changement
périodique, et une comparaison à une liste de mots de passe déjà connus pour
avoir fuité. Quatre des cinq sont de l'arithmétique sur une chaîne.

Le « au moins soixante-quatre permis » est un plancher sur le plafond, pas le
plafond : le prendre pour un plafond refuse une phrase de passe de soixante-
dix caractères, ce que produit un gestionnaire réglé sur six mots, c'est-à-
dire un bon mot de passe refusé par une règle de forme, dans une fiche dont
toute la thèse est que les règles de forme mènent aux mauvais. Le plafond par
défaut est donc à deux cent cinquante-six, et il borne le hachage, pas le
jugement.

Le « au moins soixante-quatre permis » est un plancher sur le plafond, pas le
plafond : le prendre pour un plafond refuse une phrase de passe de soixante-
dix caractères, ce que produit un gestionnaire réglé sur six mots, c'est-à-
dire un bon mot de passe refusé par une règle de forme, dans une fiche dont
toute la thèse est que les règles de forme mènent aux mauvais. Le plafond par
défaut est donc à deux cent cinquante-six, et il borne le hachage, pas le
jugement.

La cinquième est la seule qui sorte de la machine, et elle en sort presque
rien. Le service Have I Been Pwned prend les cinq premiers caractères du
SHA-1 du mot de passe et rend tous les suffixes qui commencent par eux — huit
cents environ — si bien que le mot de passe n'est jamais envoyé, que le
service ne peut pas savoir lequel des huit cents était demandé, et que la
réponse est un compte. C'est ce que fait `pwned_count` plus bas, et cela mérite
d'être lu : tout l'argument de confidentialité tient en deux lignes.

Quelque chose sort donc de votre infrastructure — cinq caractères d'une
empreinte, jamais le mot de passe —, et le bloc de risques de cette fiche le
déclare : `third-party`. Et parce que ce contrôle tourne sur un chemin
d'inscription, un service qui ne répond pas ne lève pas ici : l'échec revient
en `blocklist-unavailable` dans `reasons`, avec `breaches` nul, et c'est
l'appelant qui décide d'accepter ou de refuser l'inscription. Refuser tout le
monde parce qu'un tiers est en panne est une panne qu'on n'a pas choisie ;
accepter en silence, c'est sauter sans le dire le seul contrôle que la norme
met en SHALL.

Ce que ce fichier ne fait délibérément pas, c'est compter les majuscules, les
chiffres et les symboles. La norme l'interdit — « Verifiers and CSPs SHALL
NOT impose other composition rules » — parce que ces règles poussent vers
« Motdepasse1! », que la liste de fuites attrape et qu'aucune règle de
composition n'attrape.
"""

from __future__ import annotations

import hashlib
import unicodedata

# SP 800-63B-4, section 3.1.1.2: fifteen characters for a password used as a
# single factor, eight when it is only one factor among several.
MINIMUM = 15
MINIMUM_WITH_SECOND_FACTOR = 8

# The standard says « SHOULD permit a maximum password length of at least 64
# characters »: sixty-four is a floor on the ceiling, not the ceiling. Taking
# it as one turns down a seventy-character passphrase — six words out of a
# password manager — which is a good password refused by a rule of shape, in
# an entry whose whole thesis is that rules of shape push people towards bad
# ones. Two hundred and fifty-six is the usual ceiling; it exists to bound the
# hashing, not to judge anything.
MAXIMUM = 256

RANGE_URL = "https://api.pwnedpasswords.com/range/"

# Reasons that block. A blocklist that did not answer is reported and never
# decided: refusing every sign-up because a third party is down is an outage
# you did not choose, and accepting in silence is the check the standard puts
# in a SHALL, skipped without a word. The caller decides; `reasons` is what it
# decides on.
BLOCKING = ("not-text", "too-short", "too-long", "context-word", "breached")


def pwned_count(password: str, fetch=None) -> int:
    """
    How many breaches this password appears in, without sending the password.

    Only the first five characters of its SHA-1 leave: the service answers with
    every suffix sharing that prefix, and the comparison happens here. The
    `Add-Padding` header makes every answer the same size, so the length of the
    response says nothing either.
    """
    if fetch is None:  # pragma: no cover - needs a network
        def fetch(url: str) -> str:
            import urllib.request

            request = urllib.request.Request(url, headers={"Add-Padding": "true"})
            with urllib.request.urlopen(request, timeout=5) as response:
                return response.read().decode("utf-8")

    digest = hashlib.sha1(password.encode("utf-8")).hexdigest().upper()
    for line in fetch(RANGE_URL + digest[:5]).splitlines():
        suffix, _, count = line.strip().partition(":")
        if suffix == digest[5:]:
            return int(count)
    return 0


def check_password(password, *, second_factor: bool = False, context=(), fetch=None) -> dict:
    """
    Say whether this password may be accepted, and why not when it may not.

    `context` is the short list of words a password must not be — the site's
    name, the account's local part — which the standard allows a blocklist to
    carry. It is compared after normalisation and without case, and nothing
    else about the password's shape is judged.

    `fetch` is injected by the tests; in production it is an HTTPS request.
    It runs on a sign-up path, so a service that does not answer must not raise
    here: the failure comes back as `blocklist-unavailable` in `reasons`, with
    `breaches` at None, and `acceptable` says what the rest of the check says.
    Only `BLOCKING` reasons make a password unacceptable.
    """
    if not isinstance(password, str):
        return _report(False, ["not-text"], None, 0)

    # The standard asks for NFC, so that a password typed with a composed « é »
    # and one typed with « e » plus an accent are the same password.
    normalised = unicodedata.normalize("NFC", password)
    length = len(normalised)
    reasons = []
    floor = MINIMUM_WITH_SECOND_FACTOR if second_factor else MINIMUM
    if length < floor:
        reasons.append("too-short")
    if length > MAXIMUM:
        reasons.append("too-long")
    # Lower case rather than case folding, so that the two languages of this
    # page compare the same way: folding turns « ß » into « ss », lowering
    # leaves it alone, and JavaScript has no folding.
    folded = normalised.lower()
    if any(folded == unicodedata.normalize("NFC", word).lower() for word in context):
        reasons.append("context-word")

    # The blocklist is asked last, and only for a password that could still be
    # accepted: a request that will change nothing is a request not to make.
    breaches = None
    if not reasons:
        try:
            breaches = pwned_count(normalised, fetch)
        except Exception:  # noqa: BLE001 - see BLOCKING: an outage is not a verdict
            reasons.append("blocklist-unavailable")
        else:
            if breaches:
                reasons.append("breached")
    blocking = [reason for reason in reasons if reason in BLOCKING]
    return _report(not blocking, reasons, breaches, length)


def _report(acceptable: bool, reasons: list, breaches: int | None, length: int) -> dict:
    return {"acceptable": acceptable, "reasons": reasons, "breaches": breaches, "length": length}

/**
 * Contrôler un mot de passe contre la politique que la norme demande vraiment.
 *
 * Niveau N0. La NIST SP 800-63B-4 est courte, et ses exigences sont des règles,
 * pas des jugements : quinze caractères pour un mot de passe employé seul, au
 * moins soixante-quatre permis, aucune règle de composition, aucun changement
 * périodique, et une comparaison à une liste de mots de passe déjà connus pour
 * avoir fuité. Quatre des cinq sont de l'arithmétique sur une chaîne.
 *
 * Le « au moins soixante-quatre permis » est un plancher sur le plafond, pas le
 * plafond : le prendre pour un plafond refuse une phrase de passe de soixante-
 * dix caractères, ce que produit un gestionnaire réglé sur six mots, c'est-à-
 * dire un bon mot de passe refusé par une règle de forme, dans une fiche dont
 * toute la thèse est que les règles de forme mènent aux mauvais. Le plafond par
 * défaut est donc à deux cent cinquante-six, et il borne le hachage, pas le
 * jugement.
 *
 * Le « au moins soixante-quatre permis » est un plancher sur le plafond, pas le
 * plafond : le prendre pour un plafond refuse une phrase de passe de soixante-
 * dix caractères, ce que produit un gestionnaire réglé sur six mots, c'est-à-
 * dire un bon mot de passe refusé par une règle de forme, dans une fiche dont
 * toute la thèse est que les règles de forme mènent aux mauvais. Le plafond par
 * défaut est donc à deux cent cinquante-six, et il borne le hachage, pas le
 * jugement.
 *
 * La cinquième est la seule qui sorte de la machine, et elle en sort presque
 * rien. Le service Have I Been Pwned prend les cinq premiers caractères du
 * SHA-1 du mot de passe et rend tous les suffixes qui commencent par eux — huit
 * cents environ — si bien que le mot de passe n'est jamais envoyé, que le
 * service ne peut pas savoir lequel des huit cents était demandé, et que la
 * réponse est un compte. C'est ce que fait `pwnedCount` plus bas, et cela mérite
 * d'être lu : tout l'argument de confidentialité tient en deux lignes.
 *
 * Quelque chose sort donc de votre infrastructure — cinq caractères d'une
 * empreinte, jamais le mot de passe —, et le bloc de risques de cette fiche le
 * déclare : `third-party`. Et parce que ce contrôle tourne sur un chemin
 * d'inscription, un service qui ne répond pas ne lève pas ici : l'échec revient
 * en `blocklist-unavailable` dans `reasons`, avec `breaches` nul, et c'est
 * l'appelant qui décide d'accepter ou de refuser l'inscription. Refuser tout le
 * monde parce qu'un tiers est en panne est une panne qu'on n'a pas choisie ;
 * accepter en silence, c'est sauter sans le dire le seul contrôle que la norme
 * met en SHALL.
 *
 * Ce que ce fichier ne fait délibérément pas, c'est compter les majuscules, les
 * chiffres et les symboles. La norme l'interdit — « Verifiers and CSPs SHALL
 * NOT impose other composition rules » — parce que ces règles poussent vers
 * « Motdepasse1! », que la liste de fuites attrape et qu'aucune règle de
 * composition n'attrape.
 */

import { createHash } from 'node:crypto';

// SP 800-63B-4, section 3.1.1.2: fifteen characters for a password used as a
// single factor, eight when it is only one factor among several.
export const MINIMUM = 15;
export const MINIMUM_WITH_SECOND_FACTOR = 8;

// The standard says « SHOULD permit a maximum password length of at least 64
// characters »: sixty-four is a floor on the ceiling, not the ceiling. Taking
// it as one turns down a seventy-character passphrase — six words out of a
// password manager — which is a good password refused by a rule of shape, in
// an entry whose whole thesis is that rules of shape push people towards bad
// ones. Two hundred and fifty-six is the usual ceiling; it exists to bound the
// hashing, not to judge anything.
export const MAXIMUM = 256;

export const RANGE_URL = 'https://api.pwnedpasswords.com/range/';

// Reasons that block. A blocklist that did not answer is reported and never
// decided: refusing every sign-up because a third party is down is an outage
// you did not choose, and accepting in silence is the check the standard puts
// in a SHALL, skipped without a word. The caller decides; `reasons` is what it
// decides on.
export const BLOCKING = ['not-text', 'too-short', 'too-long', 'context-word', 'breached'];

/**
 * How many breaches this password appears in, without sending the password.
 *
 * Only the first five characters of its SHA-1 leave: the service answers with
 * every suffix sharing that prefix, and the comparison happens here. The
 * `Add-Padding` header makes every answer the same size, so the length of the
 * response says nothing either.
 */
export async function pwnedCount(password, fetchRange) {
  const get = fetchRange ?? (async (url) => {
    /* c8 ignore next 3 -- needs a network */
    const response = await fetch(url, { headers: { 'Add-Padding': 'true' } });
    return response.text();
  });

  const digest = createHash('sha1').update(password, 'utf8').digest('hex').toUpperCase();
  const body = await get(RANGE_URL + digest.slice(0, 5));
  for (const line of body.split(/\r?\n/)) {
    const [suffix, count] = line.trim().split(':');
    if (suffix === digest.slice(5)) return Number(count);
  }
  return 0;
}

/**
 * Say whether this password may be accepted, and why not when it may not.
 *
 * `context` is the short list of words a password must not be — the site's
 * name, the account's local part — which the standard allows a blocklist to
 * carry. It is compared after normalisation and without case, and nothing else
 * about the password's shape is judged.
 *
 * `fetchRange` is injected by the tests; in production it is an HTTPS request.
 * It runs on a sign-up path, so a service that does not answer must not throw
 * here: the failure comes back as `blocklist-unavailable` in `reasons`, with
 * `breaches` at null, and `acceptable` says what the rest of the check says.
 * Only `BLOCKING` reasons make a password unacceptable.
 *
 * @param {string} password
 * @param {{secondFactor?: boolean, context?: string[], fetchRange?: Function}} [options]
 */
export async function checkPassword(password, { secondFactor = false, context = [], fetchRange } = {}) {
  if (typeof password !== 'string') return report(false, ['not-text'], null, 0);

  // The standard asks for NFC, so that a password typed with a composed « é »
  // and one typed with « e » plus an accent are the same password.
  const normalised = password.normalize('NFC');
  const length = [...normalised].length;
  const reasons = [];
  const floor = secondFactor ? MINIMUM_WITH_SECOND_FACTOR : MINIMUM;
  if (length < floor) reasons.push('too-short');
  if (length > MAXIMUM) reasons.push('too-long');
  // Lower case rather than case folding, so that the two languages of this
  // page compare the same way: folding turns « ß » into « ss », lowering
  // leaves it alone, and JavaScript has no folding.
  const folded = normalised.toLowerCase();
  if (context.some((word) => word.normalize('NFC').toLowerCase() === folded)) {
    reasons.push('context-word');
  }

  // The blocklist is asked last, and only for a password that could still be
  // accepted: a request that will change nothing is a request not to make.
  let breaches = null;
  if (reasons.length === 0) {
    try {
      breaches = await pwnedCount(normalised, fetchRange);
      if (breaches) reasons.push('breached');
    } catch {
      // See BLOCKING: an outage is not a verdict.
      reasons.push('blocklist-unavailable');
    }
  }
  const blocking = reasons.filter((reason) => BLOCKING.includes(reason));
  return report(blocking.length === 0, reasons, breaches, length);
}

const report = (acceptable, reasons, breaches, length) => ({
  acceptable, reasons, breaches, length,
});