nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/oauth/authorizationServer.js

@@ -0,0 +1,221 @@
+//#region src/oauth/authorizationServer.ts
+/**
+* Rôle **serveur d'autorisation** — RFC 8414, les deux faces.
+*
+* On LIT les métadonnées d'un émetteur tiers (pour découvrir où sont ses clés)
+* et on PUBLIE les siennes (pour qu'un tiers découvre les nôtres). Les deux
+* faces partagent la même règle de composition de chemin ; les séparer les
+* ferait dériver en silence — un lecteur sondant là où l'émetteur ne sert pas
+* ne produit qu'un `404`, que chacun interprète comme « pas d'autorisation
+* ici ». Ici, la publication est la source et la lecture en dérive.
+*
+* Ce fichier ne parle à personne : il compose des URL, juge un document reçu et
+* compose un document à servir. C'est délibéré — les règles qui comptent
+* (l'ordre des points bien connus, l'égalité stricte de l'émetteur, le refus
+* d'un `jwks_uri` douteux) sont exactement celles qu'on n'éprouverait jamais si
+* elles vivaient au milieu d'un appel réseau.
+*
+* ⚠️ Volontairement au CŒUR, et non dans `@nodefony/security` : le module qui
+* expose les routes (`@nodefony/framework`) n'importe jamais `security`, et le
+* chemin bien connu doit rester écrit UNE fois pour les deux.
+*
+* @see references/rfc/ietf/rfc8414.txt
+* @see references/mcp-2026-07-28/spec/basic/authorization/authorization-server-discovery.mdx
+*/
+/** Suffixe bien connu des métadonnées d'un serveur d'autorisation (RFC 8414 §3). */
+const WELL_KNOWN_OAUTH = "/.well-known/oauth-authorization-server";
+/** Suffixe bien connu d'OpenID Connect Discovery 1.0 (§4). */
+const WELL_KNOWN_OIDC = "/.well-known/openid-configuration";
+/**
+* Chemin conventionnel où Nodefony publie son jeu de clés publiques.
+*
+* Le choix est LIBRE — un client ne le devine pas, il le lit dans le champ
+* `jwks_uri` du document de métadonnées. Deux raisons de le placer sous
+* `.well-known` quand même : c'est un espace réservé (RFC 8615), donc aucune
+* collision possible avec les routes de l'application ; et il ne comporte pas
+* de segment `api`, qui rangerait la route dans l'aire du pare-feu — or un jeu
+* de clés doit être lisible SANS authentification, sinon il ne sert à rien.
+*/
+const JWKS_PATH = "/.well-known/jwks.json";
+/**
+* Normalise et contrôle un identifiant d'émetteur (RFC 8414 §2).
+*
+* La RFC est explicite : c'est une URL **en `https`**, « with no query or
+* fragment components ». Les trois refus ci-dessous ne sont donc pas du zèle —
+* un émetteur porteur d'une requête ou d'un fragment ne peut pas servir à
+* composer une URL bien connue par insertion, et la comparaison d'égalité
+* stricte exigée par le §3.3 deviendrait un tirage au sort.
+*
+* `http` est refusé y compris en développement : les clés de signature arrivent
+* par ce canal, et un jeu de clés substitué en transit signe n'importe quel
+* jeton. Pour éprouver le mécanisme sans TLS, on injecte une implémentation de
+* `fetch` — pas un émetteur en clair.
+*
+* @param raw - identifiant tel qu'écrit en configuration
+* @returns l'émetteur normalisé, sans barre oblique terminale
+* @throws Error si l'identifiant ne peut pas servir d'émetteur
+*/
+function canonicalIssuer(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new Error(`émetteur invalide : « ${raw} » — une URL absolue est attendue (ex. « https://auth.example.com/realms/mon-royaume »).`);
+	}
+	if (url.protocol !== "https:") throw new Error(`émetteur invalide : « ${raw} » — la RFC 8414 §2 exige le schéma https (les clés de signature transitent par ce canal).`);
+	if (url.search || url.hash) throw new Error(`émetteur invalide : « ${raw} » — la RFC 8414 §2 interdit une requête ou un fragment dans un identifiant d'émetteur.`);
+	const composed = `${url.origin}${url.pathname}`;
+	return composed.endsWith("/") ? composed.slice(0, -1) : composed;
+}
+/**
+* Compose le CHEMIN où PUBLIER ses métadonnées (RFC 8414 §3.1).
+*
+* La règle est une **insertion**, pas une concaténation : le suffixe bien connu
+* se place entre l'hôte et le chemin de l'émetteur, « any terminating "/" MUST
+* be removed before inserting ». Un émetteur porteur d'un chemin
+* (multi-tenant : « Using path components enables supporting multiple issuers
+* per host ») se publie donc SOUS ce chemin — servir à la racine reviendrait à
+* servir un document que personne ne demande.
+*
+* C'est cette fonction qui fait autorité : {@link issuerMetadataUrls}, côté
+* lecteur, en dérive. Les deux faces ne peuvent donc pas diverger.
+*
+* @param issuer - identifiant d'émetteur (canonique ou non)
+* @returns le chemin absolu à servir en `GET`
+*
+* @example
+* ```ts
+* authorizationServerMetadataPath("https://app.example");
+* // → "/.well-known/oauth-authorization-server"
+* authorizationServerMetadataPath("https://app.example/tenant1");
+* // → "/.well-known/oauth-authorization-server/tenant1"
+* ```
+*/
+function authorizationServerMetadataPath(issuer) {
+	const { pathname } = new URL(canonicalIssuer(issuer));
+	return pathname === "/" ? WELL_KNOWN_OAUTH : `${WELL_KNOWN_OAUTH}${pathname}`;
+}
+/**
+* Compose, dans l'ORDRE NORMATIF, les URL où chercher les métadonnées.
+*
+* L'ordre n'est pas une préférence de goût : la spécification impose d'essayer
+* plusieurs points, et le premier document valide gagne. Un émetteur avec
+* chemin (multi-tenant) se découvre par **insertion** — placer le suffixe en
+* queue interrogerait le tenant, pas le serveur ; un émetteur sans chemin n'a
+* que deux formes possibles.
+*
+* La première URL est celle que {@link authorizationServerMetadataPath} sert :
+* c'est ce qui garantit qu'une application Nodefony est découvrable par une
+* autre application Nodefony.
+*
+* @param issuer - émetteur déjà normalisé par {@link canonicalIssuer}
+* @returns les URL à essayer, dans l'ordre
+*
+* @example
+* ```ts
+* issuerMetadataUrls("https://auth.example.com/tenant1");
+* // → [".../.well-known/oauth-authorization-server/tenant1",
+* //    ".../.well-known/openid-configuration/tenant1",
+* //    ".../tenant1/.well-known/openid-configuration"]
+* ```
+*/
+function issuerMetadataUrls(issuer) {
+	const url = new URL(issuer);
+	const path = url.pathname === "/" ? "" : url.pathname;
+	const oauth = `${url.origin}${authorizationServerMetadataPath(issuer)}`;
+	if (path === "") return [oauth, `${url.origin}${WELL_KNOWN_OIDC}`];
+	return [
+		oauth,
+		`${url.origin}${WELL_KNOWN_OIDC}${path}`,
+		`${url.origin}${path}${WELL_KNOWN_OIDC}`
+	];
+}
+/**
+* Juge un document de métadonnées reçu.
+*
+* ⭐ **L'égalité stricte de l'émetteur est la garde centrale** (RFC 8414 §3.3,
+* OIDC Discovery §4.3) : sans elle, un document servi par `attaquant.example`
+* qui se déclare `"issuer": "https://honnête.example"` serait accepté, et ses
+* clés vérifieraient des jetons au nom de l'émetteur légitime. La comparaison
+* est faite sur la forme canonique des DEUX côtés — une barre oblique
+* terminale ne doit ni faire échouer un document valide, ni servir à faire
+* passer deux identifiants pour un seul.
+*
+* Le `jwks_uri` est exigé en `https` mais **pas sur l'origine de l'émetteur** :
+* des émetteurs majeurs servent légitimement leurs clés ailleurs (Google publie
+* `accounts.google.com` et ses clés sur `www.googleapis.com`). La garde qui
+* compte est en amont — le document vient d'un émetteur déclaré en
+* configuration, jamais d'une valeur lue dans un jeton.
+*
+* @param document - le document tel que reçu (JSON déjà analysé)
+* @param expectedIssuer - émetteur canonique utilisé pour composer l'URL
+* @returns les deux champs retenus
+* @throws Error si le document ne peut pas être utilisé
+*/
+function validateIssuerMetadata(document, expectedIssuer) {
+	if (typeof document !== "object" || document === null) throw new Error("métadonnées d'émetteur : document JSON attendu.");
+	const doc = document;
+	const issuer = doc.issuer;
+	if (typeof issuer !== "string" || issuer.length === 0) throw new Error("métadonnées d'émetteur : champ `issuer` absent.");
+	let declared;
+	try {
+		declared = canonicalIssuer(issuer);
+	} catch {
+		throw new Error(`métadonnées d'émetteur : « ${issuer} » n'est pas un identifiant valide.`);
+	}
+	if (declared !== canonicalIssuer(expectedIssuer)) throw new Error(`métadonnées d'émetteur : le document déclare « ${declared} » alors qu'il a été demandé à « ${expectedIssuer} ». RFC 8414 §3.3 impose l'égalité — un document qui parle au nom d'un autre est rejeté.`);
+	const jwksUri = doc.jwks_uri;
+	if (typeof jwksUri !== "string" || jwksUri.length === 0) throw new Error("métadonnées d'émetteur : champ `jwks_uri` absent — sans jeu de clés, aucune signature ne peut être vérifiée.");
+	let keys;
+	try {
+		keys = new URL(jwksUri);
+	} catch {
+		throw new Error(`métadonnées d'émetteur : \`jwks_uri\` « ${jwksUri} » n'est pas une URL.`);
+	}
+	if (keys.protocol !== "https:") throw new Error(`métadonnées d'émetteur : \`jwks_uri\` « ${jwksUri} » doit être en https.`);
+	return {
+		issuer: declared,
+		jwksUri: keys.href
+	};
+}
+/**
+* Compose le document de métadonnées d'émetteur.
+*
+* @param input - ce que l'application déclare d'elle-même
+* @returns le document, prêt à sérialiser
+* @throws Error si l'émetteur ne peut pas servir d'identifiant RFC 8414 §2, ou
+*         si le jeu de clés n'est pas joignable en `https`
+*/
+function buildAuthorizationServerMetadata(input) {
+	const issuer = canonicalIssuer(input.issuer);
+	const jwksUri = new URL(input.jwksPath ?? "/.well-known/jwks.json", `${issuer}/`);
+	if (jwksUri.protocol !== "https:") throw new Error(`métadonnées d'émetteur : \`jwks_uri\` « ${jwksUri.href} » doit être en https (RFC 8414 §2).`);
+	return {
+		issuer,
+		jwks_uri: jwksUri.href,
+		response_types_supported: [],
+		grant_types_supported: []
+	};
+}
+/**
+* Extrait les scopes accordés d'une charge utile de jeton d'accès.
+*
+* Deux formes coexistent dans le parc réel : `scope`, chaîne séparée par des
+* espaces (RFC 8693 §4.1, RFC 9068 §2.2 — la forme normalisée), et `scp`,
+* tableau, qu'emploient plusieurs fournisseurs majeurs. Ignorer la seconde
+* ferait apparaître comme « sans aucun droit » des jetons parfaitement valides,
+* et pousserait à contourner la vérification des scopes plutôt qu'à la
+* corriger.
+*
+* @param payload - charge utile d'un jeton DÉJÀ vérifié
+* @returns les scopes, éventuellement vides — jamais `undefined`
+*/
+function extractScopes(payload) {
+	const scope = payload.scope;
+	if (typeof scope === "string") return scope.split(" ").filter((s) => s.length > 0);
+	const scp = payload.scp;
+	if (Array.isArray(scp)) return scp.filter((s) => typeof s === "string" && s.length > 0);
+	return [];
+}
+//#endregion
+export { JWKS_PATH, authorizationServerMetadataPath, buildAuthorizationServerMetadata, canonicalIssuer, extractScopes, issuerMetadataUrls, validateIssuerMetadata };

package/dist/node/oauth/protectedResource.js

@@ -0,0 +1,293 @@
+import { readBearerHeader } from "../runtime/bearer.js";
+//#region src/oauth/protectedResource.ts
+/**
+* Rôle **serveur de ressource** OAuth 2.1 — publier ce qu'on protège, et refuser
+* en disant où obtenir un jeton.
+*
+* ## Ce que ce fichier n'est pas
+*
+* Il n'est **pas** un serveur d'autorisation, et il n'y en a jamais eu besoin :
+* délivrer des jetons est un rôle distinct, que les spécifications placent
+* explicitement hors du serveur de ressource (« may be hosted with the resource
+* server **or a separate entity** »). Avoir écrit l'inverse a servi d'excuse à ne
+* rien faire pendant tout un cycle — le reste à faire était un ordre de grandeur
+* plus petit que ce qu'on s'était raconté.
+*
+* Il n'est pas non plus lié au **Model Context Protocol**, qui n'en est que le
+* premier consommateur. Rien ici ne connaît JSON-RPC, les outils ou le
+* catalogue : une ressource, une audience, un jeton, un refus. C'est ce qui
+* permettra à une porte agentique de production, ou à une API d'agents, de
+* réutiliser ces briques sans qu'un protocole de développement ne déteigne sur
+* elles.
+*
+* ## Plusieurs ressources dans une même application
+*
+* La RFC 9728 le prévoit par construction : le chemin de la ressource est
+* **inséré** dans l'URL bien connue (§3.1 — « Using path components enables
+* supporting multiple resources per host »). Une application peut donc protéger
+* `/nodefony/mcp` et, demain, une autre porte, chacune avec ses propres
+* serveurs d'autorisation, ses scopes et son audience — sans qu'aucune de ces
+* fonctions change.
+*
+* @see references/rfc/ietf/rfc9728.txt — métadonnées de la ressource protégée
+* @see references/rfc/ietf/rfc6750.txt — présentation du jeton, `WWW-Authenticate`
+* @see references/rfc/ietf/rfc8707.txt — l'audience, qui LIE un jeton à CE serveur
+*/
+/** Préfixe bien connu des métadonnées d'une ressource protégée (RFC 9728 §3). */
+const WELL_KNOWN = "/.well-known/oauth-protected-resource";
+/**
+* Normalise et contrôle une URI canonique de ressource (RFC 8707 §2).
+*
+* Trois refus, tous vécus comme des sources d'erreur silencieuse ailleurs :
+* l'absence de schéma (une audience relative ne se compare à rien), un fragment
+* (interdit — il ne voyage jamais jusqu'au serveur, donc deux URI distinctes
+* seraient reçues identiques), et un schéma non `http(s)`.
+*
+* La barre oblique terminale est retirée : les deux formes sont des URI
+* valides, mais l'audience se compare par **chaîne exacte** — publier une forme
+* et valider l'autre produit un refus que rien n'explique.
+*
+* @param raw - URI telle qu'écrite en configuration
+* @returns l'URI canonique, sans barre terminale
+* @throws Error si l'URI ne peut pas servir d'audience
+*/
+function canonicalResourceUri(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new Error(`URI de ressource invalide : « ${raw} » — une URI absolue est attendue (ex. « https://mon-app.example/nodefony/mcp »).`);
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error(`URI de ressource invalide : schéma « ${url.protocol} » — http(s) attendu.`);
+	if (url.hash) throw new Error(`URI de ressource invalide : « ${raw} » porte un fragment, que la RFC 8707 §2 interdit (il n'atteint jamais le serveur).`);
+	const composed = `${url.origin}${url.pathname}${url.search}`;
+	return composed.endsWith("/") && url.pathname !== "/" ? composed.slice(0, -1) : composed.replace(/\/$/, "");
+}
+/**
+* Compose le CHEMIN où publier les métadonnées, à partir de l'URI de la
+* ressource (RFC 9728 §3.1).
+*
+* La règle est une insertion, pas une concaténation : le suffixe bien connu se
+* place **entre l'hôte et le chemin** de la ressource. Une application qui
+* publierait `…/nodefony/mcp/.well-known/…` servirait un document que personne
+* ne demande jamais.
+*
+* @param resource - URI canonique de la ressource (ou son seul chemin)
+* @returns le chemin absolu à servir en `GET`
+*
+* @example
+* ```ts
+* protectedResourceMetadataPath("https://app.example/nodefony/mcp");
+* // → "/.well-known/oauth-protected-resource/nodefony/mcp"
+* protectedResourceMetadataPath("https://app.example");
+* // → "/.well-known/oauth-protected-resource"
+* ```
+*/
+function protectedResourceMetadataPath(resource) {
+	let path = resource;
+	if (/^[a-z][a-z0-9+.-]*:\/\//i.test(resource)) {
+		const url = new URL(resource);
+		path = `${url.pathname}${url.search}`;
+	}
+	if (path === "/" || path === "") return WELL_KNOWN;
+	const trimmed = path.endsWith("/") ? path.slice(0, -1) : path;
+	return `${WELL_KNOWN}${trimmed.startsWith("/") ? "" : "/"}${trimmed}`;
+}
+/**
+* Compose l'URL ABSOLUE des métadonnées — celle qui part dans le défi.
+*
+* @param resource - URI canonique de la ressource
+* @returns l'URL complète du document de métadonnées
+*/
+function protectedResourceMetadataUrl(resource) {
+	const canonical = canonicalResourceUri(resource);
+	const { origin } = new URL(canonical);
+	return `${origin}${protectedResourceMetadataPath(canonical)}`;
+}
+/**
+* Compose le document de métadonnées.
+*
+* @param input - ce que l'application déclare de sa ressource
+* @returns le document, prêt à sérialiser
+* @throws Error si aucun serveur d'autorisation n'est déclaré, ou si l'URI de
+*         ressource ne peut pas servir d'audience
+*/
+function buildProtectedResourceMetadata(input) {
+	const servers = input.authorizationServers.filter((s) => typeof s === "string" && s.length > 0);
+	if (servers.length === 0) throw new Error("métadonnées de ressource protégée : aucun serveur d'autorisation déclaré. Un document sans `authorization_servers` ne mène nulle part — le client apprendrait qu'un jeton est requis sans jamais pouvoir en obtenir un.");
+	const metadata = {
+		resource: canonicalResourceUri(input.resource),
+		authorization_servers: [...servers],
+		bearer_methods_supported: ["header"]
+	};
+	if (input.scopesSupported && input.scopesSupported.length > 0) metadata.scopes_supported = [...input.scopesSupported];
+	if (input.resourceName) metadata.resource_name = input.resourceName;
+	if (input.resourceDocumentation) metadata.resource_documentation = input.resourceDocumentation;
+	return metadata;
+}
+/** Codes d'erreur d'un porteur — RFC 6750 §3.1. */
+const BearerError = {
+	/**
+	* Requête mal formée (schéma inconnu, jeton absent après `Bearer`).
+	* La RFC veut **400**, pas 401 : rien n'a été présenté qu'on puisse juger.
+	*/
+	INVALID_REQUEST: "invalid_request",
+	/** Jeton expiré, révoqué, mal formé, ou d'une autre audience → **401**. */
+	INVALID_TOKEN: "invalid_token",
+	/** Identité prouvée, droits insuffisants → **403**. */
+	INSUFFICIENT_SCOPE: "insufficient_scope"
+};
+/**
+* Compose l'en-tête `WWW-Authenticate` d'un refus.
+*
+* ⭐ **C'est cet en-tête qui rend l'autorisation apprenable.** Sans lui, un
+* refus est un mur : le client ignore qu'un jeton existe, où le demander et pour
+* quels droits. Avec `resource_metadata`, il remonte seul jusqu'au serveur
+* d'autorisation — c'est le seul mécanisme normalisé pour cela.
+*
+* 🔴 **Le code d'erreur est OMIS quand la requête ne portait aucune information
+* d'authentification** — la RFC 6750 §3 le demande explicitement (« the resource
+* server SHOULD NOT include an error code or other error information »). Un
+* `invalid_token` sur une requête sans jeton ferait croire au client que son
+* jeton est mauvais, et le pousserait à le renouveler en boucle.
+*
+* @param challenge - de quoi composer le défi
+* @returns la valeur de l'en-tête `WWW-Authenticate`
+*/
+function buildBearerChallenge(challenge) {
+	const parts = [`resource_metadata="${challenge.resourceMetadataUrl}"`];
+	if (challenge.scopes && challenge.scopes.length > 0) parts.push(`scope="${challenge.scopes.join(" ")}"`);
+	if (challenge.error) parts.push(`error="${challenge.error}"`);
+	if (challenge.description) parts.push(`error_description="${sanitizeDescription(challenge.description)}"`);
+	return `Bearer ${parts.join(", ")}`;
+}
+/**
+* Restreint une description à ce que la RFC 6750 §3 autorise.
+*
+* La grammaire y est explicite — `%x20-21 / %x23-5B / %x5D-7E` — soit l'ASCII
+* imprimable **sans** guillemet ni antislash. Ce n'est pas une coquetterie : un
+* en-tête HTTP n'est pas de l'UTF-8, et un simple accent y ressort en mojibake
+* chez le client (constaté : « jeton refusé » arrivait en « jeton refus? »).
+* Un antislash, lui, casserait carrément la grammaire de la chaîne citée.
+*
+* Le filtrage vit ICI, au point de composition, et non dans chaque message :
+* autrement le prochain texte accentué reproduirait le défaut, et personne ne
+* le verrait — un en-tête abîmé ne fait échouer aucun test qui ne le lit pas.
+*
+* @param raw - description telle qu'écrite par l'appelant
+* @returns la description réduite au jeu de caractères autorisé
+*/
+function sanitizeDescription(raw) {
+	let out = "";
+	for (const char of raw.replace(/"/g, "'")) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code >= 32 && code <= 33 || code >= 35 && code <= 91 || code >= 93 && code <= 126) {
+			out += char;
+			continue;
+		}
+		out += " ";
+	}
+	return out.replace(/ {2,}/g, " ").trim();
+}
+/**
+* Nom sous lequel un {@link IAccessTokenVerifier} se pose dans le conteneur.
+*
+* ⭐ **La constante vit ICI, avec le contrat, et pas ailleurs.** Le nom est le
+* point de rendez-vous entre deux paquets qui ne se connaissent pas : celui qui
+* POSE le vérificateur (la sécurité, qui porte la cryptographie) et ceux qui le
+* LISENT (toute porte protégée). Écrit en dur de chaque côté, il vaut jusqu'au
+* jour où l'un des deux le renomme — un littéral ne casse aucune compilation,
+* et la porte cherche alors un service que personne ne pose. Importé, un
+* renommage devient une erreur de type.
+*
+* Le nom est **générique** à dessein : le contrat prend l'audience en
+* paramètre, donc une seule implémentation sert autant de ressources protégées
+* que l'application en publie (RFC 9728 §3.1).
+*/
+const ACCESS_TOKEN_VERIFIER = "accessTokenVerifier";
+/**
+* Décide du sort d'une requête d'après l'en-tête `Authorization`.
+*
+* **Fonction pure** (hors l'appel au vérificateur) : elle ne touche ni au
+* socket, ni au conteneur, ni à l'horloge — d'où le fait que chacun de ses
+* verdicts, statuts et en-têtes compris, s'éprouve sans démarrer de serveur.
+*
+* @param authorizationHeader - valeur brute de l'en-tête, ou rien
+* @param policy - ce que la ressource exige
+* @param verify - ce qui sait valider un jeton, s'il y a quelque chose
+* @returns le verdict à appliquer
+*/
+async function authorizeProtectedResource(authorizationHeader, policy, verify) {
+	const lu = readBearerHeader(authorizationHeader);
+	if (lu.kind === "absent" || lu.kind === "empty") {
+		if (policy.allowAnonymous) return { outcome: "anonymous" };
+		return {
+			outcome: "challenge",
+			status: 401,
+			wwwAuthenticate: buildBearerChallenge({
+				resourceMetadataUrl: policy.metadataUrl,
+				scopes: policy.scopes
+			})
+		};
+	}
+	if (lu.kind === "other") return {
+		outcome: "challenge",
+		status: 400,
+		wwwAuthenticate: buildBearerChallenge({
+			resourceMetadataUrl: policy.metadataUrl,
+			scopes: policy.scopes,
+			error: BearerError.INVALID_REQUEST,
+			description: "malformed Authorization header, Bearer scheme expected"
+		})
+	};
+	const token = lu.token;
+	if (!verify) return { outcome: "unverifiable" };
+	let principal = null;
+	try {
+		for (const audience of [policy.resource, ...policy.acceptedResources ?? []]) {
+			principal = await verify(token, audience);
+			if (principal !== null) break;
+		}
+	} catch (error) {
+		return {
+			outcome: "unverifiable",
+			why: error.message
+		};
+	}
+	if (principal === null) {
+		if (policy.allowAnonymous) return {
+			outcome: "anonymous",
+			rejected: true
+		};
+		return {
+			outcome: "challenge",
+			status: 401,
+			wwwAuthenticate: buildBearerChallenge({
+				resourceMetadataUrl: policy.metadataUrl,
+				scopes: policy.scopes,
+				error: BearerError.INVALID_TOKEN,
+				description: "token rejected"
+			})
+		};
+	}
+	return {
+		outcome: "authenticated",
+		principal
+	};
+}
+/**
+* L'appelant présente-t-il TOUS les scopes exigés ?
+*
+* « Tous », et pas « au moins un » : un scope borne un pouvoir, et les cumuler
+* par disjonction reviendrait à accorder le plus large de la liste.
+*
+* @param granted - scopes accordés au porteur
+* @param required - scopes exigés par l'opération
+* @returns les scopes MANQUANTS — tableau vide si rien ne manque
+*/
+function missingScopes(granted, required) {
+	if (required.length === 0) return [];
+	return required.filter((s) => !granted.includes(s));
+}
+//#endregion
+export { ACCESS_TOKEN_VERIFIER, BearerError, authorizeProtectedResource, buildBearerChallenge, buildProtectedResourceMetadata, canonicalResourceUri, missingScopes, protectedResourceMetadataPath, protectedResourceMetadataUrl };

package/dist/node/package.js

@@ -0,0 +1,4 @@
+//#region package.json
+var version = "10.0.0-alpha.2";
+//#endregion
+export { version };

package/dist/node/realtime/IRealtimeTransport.js

@@ -0,0 +1,32 @@
+//#region src/realtime/IRealtimeTransport.ts
+/**
+* IRealtimeTransport — le SEUL maillon qui diffère client/serveur.
+*
+* Le protocole ({@link JsonRpcPeer}) et les « smarts » (stats, pub/sub) sont
+* isomorphes ; seule la façon dont les **octets** entrent et sortent change. On
+* isole donc le transport derrière cette interface : un même endpoint compose
+* N transports.
+*
+* Implémentations :
+*  - `BrowserWsTransport` (navigateur, `WebSocket` + reconnect géré au-dessus)
+*  - `WsConnectionTransport` (serveur, wrap d'une connexion `ws` — P… RealtimeController)
+*  - futurs P13 : `Tcp`/`Udp`/`Redis`/`SipTransport` (RealtimeService / IRealtimeHub)
+*
+* Les états suivent les constantes `WebSocket` (0..3) pour rester universels —
+* voir {@link TransportState}.
+*
+* ── Sens des flux ──
+*  Sortant : `send` (frame brute déjà sérialisée), `close`.
+*  Entrant : le owner branche `onMessage` (chaque frame reçue) ; `onOpen`/`onClose`/
+*  `onError` pilotent le cycle de vie (l'orchestration reconnect/heartbeat vit
+*  AU-DESSUS, dans l'endpoint — le transport reste « bête »).
+*/
+/** États d'un transport — alignés sur les constantes `WebSocket`. */
+const TransportState = {
+	CONNECTING: 0,
+	OPEN: 1,
+	CLOSING: 2,
+	CLOSED: 3
+};
+//#endregion
+export { TransportState };