Node
Votre site vérifie au plus une fois par minute si Manicou lui demande de se protéger.
Dans l’espace client, ce code est déjà rempli pour votre site.
Copiez les fichiers
manicou.mjs,garde.mjsetnode.mjsdans le dossiermanicou/du sitemaintenance.mjsau même endroit, la page que verront vos visiteurs, à mettre à votre nom
Branchez le garde avant vos routes
Express ou Connectimport { garderNode } from "./manicou/node.mjs"; import page from "./manicou/maintenance.mjs"; app.use(garderNode({ sonde: "snd_…", domaine: "…", adresse: "https://app.manicou.dev/api/v1", cles: { "k1": "…" }, page, }));Redémarrez le site
Les fichiers
manicou.mjs Voir le code
manicou.mjs// Vérifier l'état que Manicou signe pour une sonde (pièce C23 de docs/CONSTRUCTION.md). À recopier dans la recette du
// site, sans aucun paquet : Web Crypto suffit (Cloudflare Workers, Node 20 et plus, Deno, Vercel, Netlify).
//
// Le message suit Standard Webhooks, signature « v1a » (Ed25519) sur « id.horodatage.corps ». Un état ne s'applique que
// s'il est signé par une des clés de Manicou recopiées dans la recette, récent, pour ce domaine et cette sonde, pas
// expiré, et d'un numéro au moins égal au dernier appliqué. Un état refusé ne change rien : le site garde l'état qu'il
// applique jusqu'au prochain état valable.
const TOLERANCE = 300; // secondes d'écart permises entre l'horloge du site et l'heure de signature
const NIVEAUX = ["normal", "restreint", "maintenance"];
const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
function octets(base64) {
if (!BASE64.test(base64) || base64.length % 4 !== 0) return null;
try {
return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
} catch {
return null;
}
}
async function signeParManicou(message, signatures, cles) {
for (const s of signatures.split(" ")) {
if (!s.startsWith("v1a,")) continue;
const signature = octets(s.slice(4));
if (!signature || signature.length !== 64) continue;
for (const cle of Object.values(cles)) {
const brute = octets(cle);
if (!brute || brute.length !== 32) continue;
try {
const publique = await crypto.subtle.importKey("raw", brute, { name: "Ed25519" }, false, ["verify"]);
if (await crypto.subtle.verify({ name: "Ed25519" }, publique, signature, message)) return true;
} catch {
// une clé ou une signature que Web Crypto refuse ne vérifie rien
}
}
}
return false;
}
// entetes : un objet Headers, ou un objet simple ; corps : le texte reçu, tel quel ; cles : { identifiant: clé en base64 }.
// Rend { ok: true, etat: { niveau, numero, essai, expireLe, echeance, parti, observation } }, ou { ok: false, raison }.
//
// Depuis la 0.12.141, l'état dit aussi jusqu'à quand le garde peut le tenir sans nouvelle de Manicou (echeance, une date, ou null
// en normal), et parti vaut true quand le site a quitté Manicou. Depuis la 0.12.180, un état normal peut porter observation, le
// niveau que le garde observe sans l'appliquer, quand l'interrupteur de Manicou est posé (D-145). Tous sont facultatifs, et une
// recette plus ancienne les ignore, et reste ouverte.
export async function verifierEtat({ entetes, corps, cles, domaine, sonde, dernierNumero = 0, maintenant = Math.floor(Date.now() / 1000) }) {
const lire = (nom) => {
if (typeof entetes?.get === "function") return entetes.get(nom) ?? "";
for (const [cle, valeur] of Object.entries(entetes ?? {})) if (cle.toLowerCase() === nom) return String(valeur);
return "";
};
const id = lire("webhook-id");
const horodatage = lire("webhook-timestamp");
const signatures = lire("webhook-signature");
if (!id || !signatures || !/^\d{1,12}$/.test(horodatage)) return { ok: false, raison: "entetes" };
if (Math.abs(maintenant - Number(horodatage)) > TOLERANCE) return { ok: false, raison: "horodatage" };
if (!(await signeParManicou(new TextEncoder().encode(`${id}.${horodatage}.${corps}`), signatures, cles))) return { ok: false, raison: "signature" };
let e;
try {
e = JSON.parse(corps);
} catch {
return { ok: false, raison: "corps" };
}
const expire = typeof e?.expireLe === "string" ? Date.parse(e.expireLe) : NaN;
if (typeof e?.sonde !== "string" || typeof e.domaine !== "string" || !NIVEAUX.includes(e.niveau) || !Number.isInteger(e.numero) || typeof e.essai !== "boolean" || Number.isNaN(expire)) {
return { ok: false, raison: "corps" };
}
const echeance = e.echeance ?? null;
if (echeance !== null && (typeof echeance !== "string" || Number.isNaN(Date.parse(echeance)))) return { ok: false, raison: "corps" };
if (e.parti !== undefined && typeof e.parti !== "boolean") return { ok: false, raison: "corps" };
if (e.observation !== undefined && (e.niveau !== "normal" || !["restreint", "maintenance"].includes(e.observation))) return { ok: false, raison: "corps" };
if (e.domaine.toLowerCase() !== domaine.toLowerCase()) return { ok: false, raison: "domaine" };
if (e.sonde !== sonde) return { ok: false, raison: "sonde" };
if (expire / 1000 <= maintenant) return { ok: false, raison: "expire" };
if (e.numero < dernierNumero) return { ok: false, raison: "numero" };
return { ok: true, etat: { niveau: e.niveau, numero: e.numero, essai: e.essai, expireLe: e.expireLe, echeance, parti: e.parti === true, observation: e.observation ?? null } };
}
garde.mjs Voir le code
garde.mjs// Le garde d'un site (pièce C23 de docs/CONSTRUCTION.md) : il lit l'état que Manicou signe pour sa sonde, le vérifie
// (manicou.mjs), et l'applique à chaque requête. Commun aux recettes JavaScript : cloudflare.mjs, node.mjs, vercel.mjs,
// netlify.mjs.
//
// - normal : tout passe ;
// - restreint : le site reste lisible ; ce qui n'est pas GET ou HEAD, une mise à niveau (WebSocket), une méthode ou une adresse
// demandée par un paramètre ou un en-tête, un chemin qu'un serveur lirait autrement, et les chemins sensibles (administration,
// connexion), répondent 503 ;
// - maintenance : tout répond 503.
//
// L'état se relit au plus une fois par minute. Un état refusé, une panne de Manicou ou un réseau coupé ne changent rien
// jusqu'à l'échéance de l'état appliqué (D-111), six heures pour le restreint et quarante-huit pour la maintenance, que chaque
// lecture renouvelle. Passée cette échéance sans nouvelle de Manicou, le site rouvre. Sans aucun état valable, le garde part
// fermé, en restreint par défaut (`demarrage`), le temps d'une lecture si Manicou répond, six heures au plus sinon, et réessaie
// toutes les dix secondes. robots.txt et la route de santé donnée dans `sante`, demandés tels quels en lecture, passent toujours.
// En maintenance, le garde répond lui-même à robots.txt, pour qu'aucune requête n'entre dans le site.
//
// Un état normal qui porte `observation` vient de l'interrupteur de Manicou (D-145) : le site reste ouvert, et le garde note au
// journal du site ce que le niveau observé aurait refusé. Une erreur du garde laisse passer la requête et se dit au journal.
import { verifierEtat } from "./manicou.mjs";
const LECTURES = ["GET", "HEAD"];
const NIVEAUX = ["normal", "restreint", "maintenance"];
// Sans état valable jamais lu, l'essai suivant vient vite.
const REESSAI = 10_000;
const HEURE = 3_600_000;
// Ce qu'un état tient sans nouvelle de Manicou, au plus (D-111). Une échéance signée plus courte s'applique, une plus longue non.
export const ECHEANCES = { restreint: 6 * HEURE, maintenance: 48 * HEURE };
// L'échéance renouvelée ne se réécrit au stockage qu'une fois par heure. KV gratuit n'accepte que mille écritures par jour.
const REECRITURE = HEURE;
// Un même avis au journal du site, au plus une fois par heure, et une ligne d'observation par cause toutes les dix minutes.
const AVIS = HEURE;
const AVIS_OBSERVATION = 10 * 60_000;
// Ce que le garde répond à robots.txt en maintenance, sans toucher au site. Rien n'est interdit, et chaque page répond 503.
export const ROBOTS = "User-agent: *\nDisallow:\n";
export const CHEMINS_SENSIBLES = ["/admin", "/administrator", "/connexion", "/login", "/user/login", "/wp-admin", "/wp-login.php"];
export const MESSAGES = {
maintenance: "Le site est en maintenance pour quelques minutes. Merci de revenir un peu plus tard.",
restreint: "Cette action est suspendue pour quelques minutes. Merci de réessayer un peu plus tard.",
};
// Les en-têtes qui demandent une autre méthode à un cadriciel (D8). L'API REST de WordPress et Slim 4 les lisent même sur un GET, et
// l'OWASP CRS les refuse. En restreint, une requête qui en porte un répond 503. x-middleware-subrequest fait sauter le middleware
// d'un Next.js ancien (CVE-2025-29927).
export const ENTETES_DE_METHODE = ["x-http-method-override", "x-http-method", "x-method-override", "x-middleware-subrequest"];
// Les en-têtes qui donnent une autre adresse que la requête (d'anciens Symfony et Zend, IIS). Leur adresse se juge comme celle de la
// requête.
export const ENTETES_DE_REECRITURE = ["x-original-url", "x-rewrite-url"];
// Ce que le garde dit au journal du site, en observation.
const CAUSES = {
maintenance: "maintenance",
ecriture: "écriture",
"mise-a-niveau": "mise à niveau",
methode: "méthode demandée par un paramètre ou un en-tête",
reecriture: "adresse donnée par un en-tête",
ambigu: "chemin qu'un serveur lirait autrement",
sensible: "chemin sensible",
};
// Les minuscules ASCII seules, comme strtolower de PHP 8 : les chemins sensibles s'écrivent en ASCII.
const minuscules = (texte) => texte.replace(/[A-Z]+/g, (m) => m.toLowerCase());
// Les points et les espaces qui finissent un segment, ôtés depuis la fin par une boucle, comme rtrim en PHP. L'expression `/[. ]+$/`
// reprenait à chaque position d'une longue suite de points suivie d'une lettre, en temps quadratique, 237 ms pour seize mille points,
// sur chaque GET que le garde juge (relu par la session du garde du kit, 18 novembre 2026).
function sansPointsFinaux(segment) {
let n = segment.length;
while (n > 0 && (segment[n - 1] === "." || segment[n - 1] === " ")) n--;
return segment.slice(0, n);
}
// Le chemin canonisé une fois, et ce qu'il a d'ambigu (D12, audit des limites du 15 novembre 2026). Décodé une fois, « \ » lu comme
// « / », les « / » répétés réunis, « . » et « .. » résolus, les points et espaces qui finissent un segment ôtés (Windows les
// ignore), en minuscules. Ambigu, ce qu'un serveur ou un système de fichiers lirait autrement que ce chemin : un « / », un « \ » ou un
// « . » encodés, un encodage cassé ou qui reste après le décodage, un caractère de contrôle, « ; » (Tomcat, Spring), « :: » ou « :$ »
// (les flux de NTFS), « ~ » suivi d'un chiffre (les noms courts de Windows), un segment fait de points et d'espaces autre que « . »
// et « .. ». En restreint, un chemin ambigu répond 503.
export function canoniser(brut) {
const s = String(brut ?? "/");
let ambigu = /%(2f|5c|2e)/i.test(s) || /%(?![0-9a-f]{2})/i.test(s);
let d;
try {
d = decodeURIComponent(s);
} catch {
// Un encodage cassé, ou des octets qui ne sont pas de l'UTF-8 : décodé octet par octet, et ambigu.
d = s.replace(/%([0-9a-f]{2})/gi, (_, h) => String.fromCharCode(parseInt(h, 16)));
ambigu = true;
}
if (/%[0-9a-f]{2}/i.test(d) || /[\u0000-\u001f\u007f]/.test(d) || d.includes(";") || /::|:\$/.test(d) || /~[0-9]/.test(d)) ambigu = true;
const pile = [];
for (const segment of d.replaceAll("\\", "/").split("/")) {
if (segment === "" || segment === ".") continue;
if (segment === "..") {
pile.pop();
continue;
}
if (/^[. ]+$/.test(segment)) {
// « .. » suivi d'une espace, « ... » : Windows en fait « .. » ou rien.
ambigu = true;
continue;
}
pile.push(minuscules(sansPointsFinaux(segment)));
}
return { chemin: `/${pile.join("/")}`, ambigu };
}
// Le chemin d'une cible, canonisé, sans dire s'il est ambigu, comme manicou_normaliser en PHP. « //wp-admin », « /WP-ADMIN »,
// « /wp-%61dmin » ou « /x/../wp-admin » sont bien /wp-admin.
export const normaliser = (brut) => canoniser(decouper(brut).chemin).chemin;
// Une cible de requête (« /chemin?requête », ou « http://hôte/chemin?requête ») en { chemin, requete }, sans la lire comme une
// adresse : new URL("//wp-admin/x", base) prendrait « wp-admin » pour un hôte.
export function decouper(cible) {
let brut = String(cible ?? "/");
const absolue = brut.match(/^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#]*/);
if (absolue) brut = brut.slice(absolue[0].length) || "/";
brut = brut.split("#")[0];
const q = brut.indexOf("?");
return q < 0 ? { chemin: brut || "/", requete: "" } : { chemin: brut.slice(0, q) || "/", requete: brut.slice(q + 1) };
}
// Ce qu'une requête des plateformes à Request (Cloudflare, Vercel, Netlify) donne au garde.
export function requeteDuWeb(request) {
const u = new URL(request.url);
return { methode: request.method, chemin: u.pathname, requete: u.search.slice(1), entetes: request.headers };
}
// Le nom d'un paramètre comme PHP le lit dans $_GET : décodé, « + » lu comme une espace, ses espaces de tête ôtées, « . » et les
// espaces lus « _ », et ce qui suit un « [ » fermé laissé au tableau. « ?.method=POST » est donc $_GET['_method'].
export function nomDeParametre(brut) {
let k;
try {
k = decodeURIComponent(brut.replaceAll("+", " "));
} catch {
k = brut.replaceAll("+", " ").replace(/%([0-9a-f]{2})/gi, (_, h) => String.fromCharCode(parseInt(h, 16)));
}
k = k.replace(/^ +/, "");
let nom = "";
for (let i = 0; i < k.length; i++) {
const c = k[i];
if (c === " " || c === ".") nom += "_";
else if (c === "[") return k.indexOf("]", i + 1) >= 0 ? nom : `${nom}_${k.slice(i + 1).replace(/[ .[]/g, "_")}`;
else nom += c;
}
return nom;
}
// Les paramètres de la chaîne de requête, nom lu comme PHP le lit, en minuscules, et valeur décodée.
function parametres(requete) {
const liste = [];
if (!requete) return liste;
for (const morceau of String(requete).split("&")) {
if (!morceau) continue;
const egal = morceau.indexOf("=");
const nom = minuscules(nomDeParametre(egal < 0 ? morceau : morceau.slice(0, egal)));
let valeur = egal < 0 ? "" : morceau.slice(egal + 1).replaceAll("+", " ");
try {
valeur = decodeURIComponent(valeur);
} catch {
// une valeur mal encodée se juge telle quelle
}
liste.push([nom, valeur]);
}
return liste;
}
// Un en-tête d'une requête, dans un objet Headers ou dans les en-têtes de Node (noms en minuscules, une valeur ou une liste).
function entete(entetes, nom) {
if (!entetes) return null;
if (typeof entetes.get === "function") return entetes.get(nom);
const v = entetes[nom];
if (v === undefined || v === null) return null;
return Array.isArray(v) ? v.join(", ") : String(v);
}
// « /wp-admin » couvre /wp-admin et /wp-admin/…, pas /wp-adminx.
const sensible = (chemin, prefixes) => prefixes.some((p) => chemin === p || chemin.startsWith(`${p}/`));
// La page de maintenance de Manicou (maintenance.html, ou maintenance.en.html, une fois le nom et le contact du site remplis). Le
// site qui la donne dans `page`, en texte (maintenance.mjs, à importer), la sert à la place du message. Telle quelle en maintenance. En restreint, la phrase
// de son élément id="manicou-phrase" devient celle du mode restreint, dans la langue de la page, ou `phraseRestreint`.
export const PHRASES_RESTREINT = {
fr: "Une faille de sécurité qui touche de nombreux sites est en cours.<br>Certains services sont suspendus en attendant son correctif.",
en: "A security vulnerability affecting many websites is under way.<br>Some services are suspended until its fix.",
};
// La page ne charge ni script ni fichier d'ailleurs. Son style est dans la page, ses images et ses polices en data.
const CSP_PAGE = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
export function pageRestreinte(page, phrase) {
const repere = page.indexOf('id="manicou-phrase"');
const ouvre = repere < 0 ? -1 : page.indexOf(">", repere);
const ferme = ouvre < 0 ? -1 : page.indexOf("</p>", ouvre);
if (ferme < 0) return page;
const langue = page.slice(0, 400).toLowerCase().includes('lang="en') ? "en" : "fr";
return page.slice(0, ouvre + 1) + (phrase ?? PHRASES_RESTREINT[langue]) + page.slice(ferme);
}
// La réponse du garde porte X-Manicou, avec le niveau, le numéro de l'ordre appliqué et l'empreinte de la sonde. Manicou y
// reconnaît l'effet de son ordre en cours, et non un 503 du site lui-même ou d'un autre garde du même hôte (D11).
const refus = (niveau, message, page, entete) => ({
statut: 503,
entetes: page
? { "content-type": "text/html; charset=utf-8", "retry-after": "300", "cache-control": "no-store", "content-security-policy": CSP_PAGE, "x-content-type-options": "nosniff", "x-manicou": entete }
: { "content-type": "text/plain; charset=utf-8", "retry-after": "300", "cache-control": "no-store", "x-manicou": entete },
corps: page ?? message,
});
const robots = () => ({ statut: 200, entetes: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }, corps: ROBOTS });
// Les huit premiers chiffres hexadécimaux du SHA-256 de la sonde. Ils distinguent deux sites sans livrer l'identifiant, qui
// ouvre la lecture de l'état.
async function empreinteDe(sonde) {
const octets = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(sonde)));
return Array.from(octets.slice(0, 4), (o) => o.toString(16).padStart(2, "0")).join("");
}
// Ce que le niveau refuse d'une requête, ou null. q : { methode, chemin (tel qu'il arrive, avant tout décodage), requete (la chaîne
// de requête brute, sans « ? »), entetes }. Sans requete, le chemin peut porter la sienne, qui s'en sépare. Rend { raison, robots? }.
export function juger(niveau, q, { chemins = CHEMINS_SENSIBLES.map(normaliser), sante = [] } = {}) {
if (niveau === "normal") return null;
const { methode, entetes = null } = q;
const { chemin: brut, requete } = q.requete === undefined || q.requete === null ? decouper(q.chemin) : { chemin: String(q.chemin ?? "/"), requete: String(q.requete) };
const lecture = LECTURES.includes(String(methode ?? "GET").toUpperCase());
const miseANiveau = Boolean(entete(entetes, "upgrade"));
// Les exceptions se comparent au chemin brut, octet pour octet, sans chaîne de requête (D16) : une normalisation large les élargit.
const telQuel = lecture && !miseANiveau && !requete;
if (telQuel && sante.includes(brut)) return null;
if (niveau === "maintenance") {
// robots.txt, servi par le garde lui-même : rien n'entre dans le site.
if (lecture && !miseANiveau && canoniser(brut).chemin === "/robots.txt") return { raison: "robots", robots: true };
return { raison: "maintenance" };
}
if (telQuel && brut === "/robots.txt") return null;
if (!lecture) return { raison: "ecriture" };
if (miseANiveau) return { raison: "mise-a-niveau" };
if (ENTETES_DE_METHODE.some((n) => entete(entetes, n) !== null)) return { raison: "methode" };
const raison = jugerCible(brut, requete, chemins);
if (raison) return { raison };
for (const nom of ENTETES_DE_REECRITURE) {
const autre = entete(entetes, nom);
if (autre === null) continue;
const { chemin: c, requete: r } = decouper(autre);
if (jugerCible(c, r, chemins)) return { raison: "reecriture" };
}
return null;
}
// En restreint, ce qu'une adresse a d'interdit : une méthode demandée par `_method`, un chemin ambigu ou sensible. ?rest_route=
// sert l'API REST de WordPress comme /wp-json/ : sa route se juge comme un chemin sous /wp-json.
function jugerCible(chemin, requete, chemins) {
const params = parametres(requete);
if (params.some(([nom]) => nom === "_method")) return "methode";
const c = canoniser(chemin);
if (c.ambigu) return "ambigu";
if (sensible(c.chemin, chemins)) return "sensible";
for (const [nom, valeur] of params) {
if (nom !== "rest_route") continue;
const route = canoniser(`/wp-json/${valeur}`);
if (route.ambigu) return "ambigu";
if (sensible(route.chemin, chemins)) return "sensible";
}
return null;
}
// reglages : { sonde, domaine, cles, adresse, cheminsSensibles?, messages?, page? (le HTML de la page de maintenance, en texte),
// phraseRestreint? (en HTML), rafraichir? (secondes), delai? (millisecondes), sante? (les chemins de la route de santé du site,
// qui passent toujours en lecture, demandés tels quels), demarrage? ("restreint" par défaut, "maintenance" ou "normal", ce qui
// s'applique tant qu'aucun état valable n'a été lu) }
// options : { fetch, maintenant (millisecondes), stockage: { lire(), ecrire(etat) }, journal(texte) }. Le stockage garde le
// dernier état vérifié avec sa sonde et son échéance entre deux démarrages (KV sur Cloudflare, un fichier avec Node). Le journal
// est celui du site, la sortie d'erreur par défaut.
export function creerGarde(reglages, { fetch: chercher = globalThis.fetch.bind(globalThis), maintenant = () => Date.now(), stockage = null, journal = (texte) => console.error(texte) } = {}) {
const { sonde, domaine, cles, adresse } = reglages;
if (!sonde || !domaine || !cles || !adresse) throw new Error("manicou : sonde, domaine, cles et adresse sont obligatoires");
if (!adresse.startsWith("https://") && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?\//.test(adresse)) throw new Error("manicou : l'adresse doit être en https");
if (reglages.demarrage !== undefined && !NIVEAUX.includes(reglages.demarrage)) throw new Error("manicou : demarrage vaut normal, restreint ou maintenance");
if (reglages.sante !== undefined && (!Array.isArray(reglages.sante) || !reglages.sante.every((c) => typeof c === "string" && c.startsWith("/")))) throw new Error("manicou, sante est une liste de chemins qui commencent par /");
const chemins = (reglages.cheminsSensibles ?? CHEMINS_SENSIBLES).map(normaliser);
// La route de santé se compare telle qu'elle est écrite dans les réglages, au chemin brut de la requête (D16).
const sante = [...(reglages.sante ?? [])];
const messages = { ...MESSAGES, ...reglages.messages };
if (reglages.page !== undefined && (typeof reglages.page !== "string" || !reglages.page.includes("<"))) throw new Error("manicou : page est le HTML de la page de maintenance, en texte");
const pages = reglages.page ? { maintenance: reglages.page, restreint: pageRestreinte(reglages.page, reglages.phraseRestreint) } : {};
const rafraichir = (reglages.rafraichir ?? 60) * 1000;
const delai = reglages.delai ?? 2000;
const demarrage = reglages.demarrage ?? "restreint";
const empreinte = empreinteDe(sonde);
// Le dernier état vérifié, sur Manicou ou dans le stockage, { niveau, numero, echeance, observation? }, l'échéance en
// millisecondes, null en normal. Sans lui, l'heure du premier départ, qui borne le niveau de départ.
let verifie = null;
let depuis = null;
let echeanceEcrite = null;
let charge = !stockage;
let dernierEssai = -Infinity;
let enCours = null;
const avis = new Map();
const observees = new Map();
const signaler = (cause, texte, ecart = AVIS) => {
const t = maintenant();
if (t - (avis.get(cause) ?? -Infinity) < ecart) return false;
avis.set(cause, t);
try {
journal(texte);
} catch {
// un journal qui échoue ne retient pas le site
}
return true;
};
const garder = (etat) => stockage?.ecrire({ sonde, ...etat }).catch(() => {});
// Le niveau à appliquer à l'instant t.
function niveauA(t) {
if (verifie) {
if (verifie.niveau === "normal" || t < verifie.echeance) return verifie.niveau;
signaler("echeance", `[manicou] Aucune nouvelle de Manicou depuis l'échéance de l'état ${verifie.niveau} n° ${verifie.numero}, le site rouvre en attendant.`);
return "normal";
}
if (demarrage === "normal" || t < (depuis ?? t) + ECHEANCES[demarrage]) return demarrage;
signaler("depart", "[manicou] Aucun état valable lu depuis le départ du garde, le site rouvre en attendant. Vérifiez la sonde, les clés et l'adresse des réglages.");
return "normal";
}
async function charger(t) {
charge = true;
try {
const lu = await stockage.lire();
// Un état gardé pour une autre sonde, ou par une recette d'avant la 0.12.141 qui ne gardait pas la sonde, ne vaut rien ici
// (D5). Un site recréé suit ainsi les ordres de sa nouvelle sonde dès le premier.
if (lu?.sonde !== sonde) return;
const observation = lu.observation === undefined || (lu.niveau === "normal" && ["restreint", "maintenance"].includes(lu.observation));
if (lu.connu === true && NIVEAUX.includes(lu.niveau) && Number.isInteger(lu.numero) && observation && (lu.niveau === "normal" ? lu.echeance === null : Number.isFinite(lu.echeance))) {
verifie = { niveau: lu.niveau, numero: lu.numero, echeance: lu.echeance, ...(lu.observation ? { observation: lu.observation } : {}) };
echeanceEcrite = lu.echeance;
} else if (lu.connu === false && Number.isFinite(lu.depuis) && lu.depuis <= t) depuis = lu.depuis;
} catch {
// rien de gardé
}
}
// L'heure de Manicou d'après l'en-tête Date de sa réponse. Un écart de plus de cinq minutes fige le garde, et se dit (D14).
function horloge(date, t) {
const sienne = Date.parse(date ?? "");
if (Number.isNaN(sienne)) return signaler("horloge", "[manicou] L'état de Manicou est refusé, son heure s'écarte de plus de cinq minutes de celle de ce serveur. Remettez l'horloge du serveur à l'heure.");
const ecart = Math.round((t - sienne) / 1000);
if (Math.abs(ecart) <= 300) return;
signaler("horloge", `[manicou] L'horloge de ce serveur ${ecart > 0 ? "avance" : "retarde"} de ${Math.abs(ecart)} s sur celle de Manicou (en-tête Date). Aucun état ne s'applique tant qu'elle n'est pas remise à l'heure.`);
}
async function relire() {
const t = maintenant();
if (!charge) await charger(t);
if (!verifie && depuis === null) {
depuis = t;
await garder({ connu: false, depuis });
}
try {
const r = await chercher(`${adresse}/sites/etat?sonde=${encodeURIComponent(sonde)}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(delai) });
if (!r.ok) return;
const corps = await r.text();
const avant = verifie ?? { niveau: "normal", numero: 0 };
const v = await verifierEtat({ entetes: r.headers, corps, cles, domaine, sonde, dernierNumero: avant.numero, maintenant: Math.floor(t / 1000) });
if (!v.ok) {
if (v.raison === "horodatage") horloge(r.headers.get("date"), t);
return;
}
const { niveau, numero, observation } = v.etat;
// Renouvelée à chaque lecture, jamais au-delà de six ou quarante-huit heures, même si Manicou signe plus loin.
const echeance = niveau === "normal" ? null : Math.min(t + ECHEANCES[niveau], v.etat.echeance ? Date.parse(v.etat.echeance) : Infinity);
const change = numero !== avant.numero || niveau !== avant.niveau || (observation ?? null) !== (avant.observation ?? null);
const premier = !verifie;
verifie = { niveau, numero, echeance, ...(observation ? { observation } : {}) };
depuis = null;
if (v.etat.parti) signaler("parti", "[manicou] Manicou ne suit plus ce site, et lui sert l'état normal. Retirez la recette de Manicou du site, la directive qui la charge d'abord.");
if (change && observation) signaler("observation", `[manicou] Manicou a mis le garde en observation du ${observation}. Le site reste ouvert, et ce que le ${observation} aurait refusé se note ici.`, 0);
if (change || premier || (echeance !== null && (echeanceEcrite === null || echeance - echeanceEcrite >= REECRITURE))) {
echeanceEcrite = echeance;
await garder({ connu: true, ...verifie });
}
if (!change) return;
// L'accusé est indicatif : Manicou constate l'effet de l'extérieur. Une erreur ici ne change rien.
await chercher(`${adresse}/sites/accuses`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ sonde, numero, niveau, applique: true }),
signal: AbortSignal.timeout(delai),
}).catch(() => {});
} catch {
// Manicou injoignable, ou réponse illisible, et le dernier état vérifié tient jusqu'à son échéance.
}
}
// Relit l'état s'il est dû, et attend la lecture en cours.
async function actualiser() {
if (maintenant() - dernierEssai >= (verifie ? rafraichir : REESSAI)) {
dernierEssai = maintenant();
enCours = relire().finally(() => {
enCours = null;
});
}
if (enCours) await enCours;
}
// En observation, ce que le niveau observé aurait refusé, compté par cause et noté au plus toutes les dix minutes.
function observer(niveau, raison, { methode, chemin, requete }) {
const n = (observees.get(raison) ?? 0) + 1;
observees.set(raison, n);
const cible = `${chemin}${requete ? `?${requete}` : ""}`.slice(0, 200);
const texte = `[manicou] En observation du ${niveau}, ${n} requête${n > 1 ? "s auraient" : " aurait"} reçu 503 depuis le dernier avis, pour ${CAUSES[raison] ?? raison}, dont ${String(methode ?? "GET").toUpperCase().slice(0, 20)} ${JSON.stringify(cible)}.`;
if (signaler(`observation:${raison}`, texte, AVIS_OBSERVATION)) observees.set(raison, 0);
}
return {
// { methode, chemin, requete?, entetes? } → null pour laisser passer, ou { statut, entetes, corps } pour répondre à la place du
// site. Le chemin est celui de la requête, avant tout décodage, la requête sa chaîne brute sans « ? ».
async decider(q) {
try {
await actualiser();
const niveau = niveauA(maintenant());
const observe = niveau === "normal" ? (verifie?.observation ?? null) : null;
if (niveau === "normal" && !observe) return null;
const d = juger(observe ?? niveau, q, { chemins, sante });
if (!d) return null;
if (observe) {
if (!d.robots) observer(observe, d.raison, q);
return null;
}
if (d.robots) return robots();
const entete = `${niveau}; numero=${verifie?.numero ?? 0}; sonde=${await empreinte}`;
if (niveau === "maintenance") return refus(niveau, messages.maintenance, pages.maintenance, entete);
return refus(niveau, messages.restreint, pages.restreint, entete);
} catch {
// Le garde ne bloque jamais un site, même par une erreur à lui (D21).
signaler("erreur", "[manicou] Le garde a échoué sur une requête et l'a laissée passer. Recopiez le dossier manicou/ en entier, et signalez-le à Manicou.");
return null;
}
},
actualiser,
// Le dernier état vérifié, { niveau, numero, echeance, observation? } ; normal et 0 tant qu'aucun n'est lu.
etat: () => (verifie ? { ...verifie } : { niveau: "normal", numero: 0, echeance: null }),
// Le niveau appliqué à cet instant, échéance comprise.
niveau: () => niveauA(maintenant()),
connu: () => verifie !== null,
};
}
node.mjs Voir le code
node.mjs// La recette Node (pièce C23 de docs/CONSTRUCTION.md) : le garde (garde.mjs) en intergiciel, pour Express, Connect, ou un
// serveur node:http. Node 20 ou plus. Avec `fichier`, l'état appliqué se garde sur le disque entre deux démarrages.
//
// import { garderNode } from "./manicou/node.mjs";
// import page from "./manicou/maintenance.mjs";
// const garder = garderNode({ sonde: "…", domaine: "…", adresse: "…", cles: { … }, page, fichier: "/var/lib/monsite/manicou.json" });
// app.use(garder);
// garder.proteger(app.listen(3000));
//
// page est la page que voit un visiteur arrêté (maintenance.mjs, mise au nom du site) ; sans elle, une phrase en texte.
// garder.proteger(serveur) garde aussi les mises à niveau (WebSocket, Socket.IO), que Node donne à l'événement « upgrade » sans
// passer par l'intergiciel, et ferme celles qui restent ouvertes quand l'état se resserre (D3). Le premier passage par l'intergiciel
// garde aussi le serveur qui l'a reçu, mais une mise à niveau peut arriver avant lui.
//
// Sans framework : const garder = garderNode({ … }); garder.proteger(http.createServer((req, res) => garder(req, res, () => votreSite(req, res))));
import { readFile, rename, writeFile } from "node:fs/promises";
import { creerGarde, decouper } from "./garde.mjs";
// Ce qu'une connexion mise à niveau tient au plus sans que le garde regarde l'état, en millisecondes.
const REGARD = 10_000;
const stockageFichier = (fichier) =>
fichier && {
lire: async () => JSON.parse(await readFile(fichier, "utf8")),
ecrire: async (etat) => {
await writeFile(`${fichier}.tmp`, JSON.stringify(etat), { mode: 0o600 });
await rename(`${fichier}.tmp`, fichier);
},
};
// Le chemin de la requête, sans la lire comme une adresse : new URL("//wp-admin/x", base) prendrait « wp-admin » pour un
// hôte. Une cible absolue (« http://hôte/chemin ») garde son chemin, comme le router d'Express le lit.
export const cheminDe = (cible) => decouper(cible).chemin;
// Ce qu'une requête de Node donne au garde, sa cible coupée en chemin et chaîne de requête, sans rien décoder.
const requeteDe = (req) => ({ methode: req.method ?? "GET", ...decouper(req.url), entetes: req.headers ?? {} });
// Le refus écrit sur la connexion d'une mise à niveau, qui n'a pas de réponse HTTP à elle.
function refuserConnexion(socket, d, methode) {
const corps = methode === "HEAD" ? "" : String(d.corps ?? "");
const entetes = { ...d.entetes, connection: "close", "content-length": String(Buffer.byteLength(corps)) };
const lignes = Object.entries(entetes).map(([nom, valeur]) => `${nom}: ${valeur}`);
socket.end(`HTTP/1.1 ${d.statut} Service Unavailable\r\n${lignes.join("\r\n")}\r\n\r\n${corps}`);
}
export function garderNode(reglages, options = {}) {
const garde = creerGarde(reglages, { stockage: stockageFichier(reglages.fichier), ...options });
const gardes = new WeakSet();
// Garde les événements « upgrade » et « connect » du serveur, que Node donne à leurs écouteurs sans passer par l'intergiciel. Une
// mise à niveau compte comme une écriture : elle passe en normal, et répond 503 en restreint comme en maintenance.
function proteger(serveur) {
if (!serveur || typeof serveur.emit !== "function" || gardes.has(serveur)) return serveur;
gardes.add(serveur);
const ouvertes = new Set();
const emettre = serveur.emit;
serveur.emit = function (evenement, req, socket, tete, ...reste) {
if ((evenement !== "upgrade" && evenement !== "connect") || !socket) return emettre.call(this, evenement, req, socket, tete, ...reste);
const q = requeteDe(req);
// CONNECT n'est pas une lecture, et la mise à niveau porte son en-tête Upgrade : le garde les juge comme des écritures.
garde.decider(q).then(
(d) => {
if (d) return refuserConnexion(socket, d, q.methode);
ouvertes.add(socket);
socket.once("close", () => ouvertes.delete(socket));
emettre.call(this, evenement, req, socket, tete, ...reste);
},
() => emettre.call(this, evenement, req, socket, tete, ...reste),
);
return this.listenerCount(evenement) > 0;
};
// Une connexion ouverte en normal écrit comme une requête : quand l'état se resserre, elle se ferme, et le client se reconnecte
// sous le garde.
const regard = setInterval(() => {
if (ouvertes.size === 0) return;
garde
.actualiser()
.then(() => {
if (garde.niveau() === "normal") return;
for (const s of ouvertes) s.destroy();
ouvertes.clear();
})
.catch(() => {});
}, REGARD);
regard.unref?.();
serveur.once?.("close", () => clearInterval(regard));
return serveur;
}
const intergiciel = async (req, res, suite) => {
proteger(req.socket?.server);
const d = await garde.decider(requeteDe(req));
if (!d) return suite();
res.writeHead(d.statut, d.entetes);
res.end(req.method === "HEAD" ? undefined : d.corps);
};
intergiciel.proteger = proteger;
intergiciel.garde = garde;
return intergiciel;
}
maintenance.mjs Voir le code
maintenance.mjs// La page de maintenance de Manicou pour les recettes JavaScript : le HTML de maintenance.html, en texte, à importer. Mettez-y
// [Nom du site], [téléphone], [numéro sans espace] et [e-mail], et votre logo à la place du carré, puis donnez-la au garde :
// import page from "./manicou/maintenance.mjs";
// garderNode({ …, page }); // ou garderPages, garderWorker, garderVercel, garderNetlify
export default `<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex">
<title>[Nom du site]</title>
<style>
*{box-sizing:border-box}
body{margin:0;background:#fff;color:#171717;font:16px/1.6 system-ui,-apple-system,"Segoe UI",sans-serif;text-align:center}
header{padding:40px 24px 0}
.logo{width:72px;height:72px;margin:0 auto;border-radius:16px;background:#171717}
.nom{margin:12px 0 0;font-size:1.125rem;font-weight:600}
main{max-width:40rem;margin:0 auto;padding:48px 24px}
h1{margin:0 0 16px;font-size:2.5rem;line-height:1.15;font-weight:600;letter-spacing:-.02em}
p{margin:0}
.phrase,.joindre,.manicou{color:#4d4d4d}
.joindre{margin-top:40px;font-size:.9375rem}
.contact{display:flex;flex-direction:column;align-items:center;gap:8px;margin-top:8px}
a{color:inherit;font-size:1.125rem;text-underline-offset:.25em}
footer{padding:0 24px 40px;font-size:.875rem}
@media (max-width:640px){header{padding-top:28px}.logo{width:56px;height:56px}main{padding:32px 20px}h1{font-size:1.75rem}}
</style>
</head>
<body>
<header>
<!-- Votre logo à la place de ce carré, en image intégrée (data:) -->
<div class="logo"></div>
<p class="nom">[Nom du site]</p>
</header>
<main>
<h1>[Nom du site] vous protège.</h1>
<p class="phrase" id="manicou-phrase">Une faille de sécurité qui touche de nombreux sites est en cours.<br>Nous attendons son correctif pour reprendre le service.</p>
<p class="joindre">Pour nous joindre</p>
<p class="contact"><a href="tel:[numéro sans espace]">[téléphone]</a><a href="mailto:[e-mail]">[e-mail]</a></p>
</main>
<footer>
<p class="manicou">Site protégé par Manicou</p>
</footer>
</body>
</html>
`;
L’essai
Lancez-le depuis l’espace client, il vérifie la recette en direct.