@ressjs/vite-router 0.5.2 → 0.6.0-rc.0

package/dist/security/head-tags.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Qué puede poner una página en el `<head>`.
+ *
+ * El `<head>` es el lugar más rentable para inyectar algo: un `<script>` ahí
+ * corre antes que la página, un `<meta http-equiv="refresh">` la redirige, y un
+ * `<base>` cambia a dónde apunta cada URL relativa del documento. Por eso lo que
+ * se admite es una lista cerrada y no una lista de lo prohibido.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEAD_TAG_ALLOWLIST = void 0;
+exports.renderHeadTags = renderHeadTags;
+const escape_1 = require("./escape");
+exports.HEAD_TAG_ALLOWLIST = ['meta', 'link', 'title', 'base', 'style', 'noscript'];
+/** Etiquetas sin contenido, que se emiten autocerradas. */
+const VOID_TAGS = new Set(['meta', 'link', 'base']);
+/**
+ * Valores de `rel` admitidos en un `<link>`.
+ *
+ * Fuera de esta lista quedan cosas como `import`, que carga y ejecuta un
+ * documento entero.
+ */
+const LINK_REL_ALLOWLIST = new Set([
+    'stylesheet',
+    'preload',
+    'prefetch',
+    'preconnect',
+    'dns-prefetch',
+    'icon',
+    'apple-touch-icon',
+    'manifest',
+    'canonical',
+    'alternate',
+    'modulepreload',
+]);
+/**
+ * `http-equiv` que se descartan: uno redirige la página y el otro declara una
+ * política de contenido que debilitaría la que emite el framework por cabecera.
+ */
+const BLOCKED_HTTP_EQUIV = new Set(['refresh', 'content-security-policy']);
+/**
+ * Filtra y emite las etiquetas adicionales del `<head>`.
+ *
+ * Nunca se concatena un string de HTML crudo que aporte la aplicación: la
+ * entrada es siempre estructurada, y cada atributo pasa por el escapado.
+ */
+function renderHeadTags(tags, ctx, options = {}) {
+    const allowed = new Set([
+        ...exports.HEAD_TAG_ALLOWLIST,
+        ...(options.extraAllowlist ?? []),
+        'script',
+    ]);
+    const out = [];
+    let baseEmitted = false;
+    for (const rawTag of tags ?? []) {
+        // Los nombres de atributo HTML no distinguen mayúsculas: para el navegador
+        // `HTTP-EQUIV` y `http-equiv` son el mismo atributo. Si las reglas de abajo
+        // sólo miraran la forma en minúsculas tal cual la escribió la página,
+        // `{ 'HTTP-EQUIV': 'refresh' }` pasaba sin que ninguna regla lo reconociera.
+        // Por eso se normaliza acá, antes de evaluar CUALQUIER regla, y se emite ya
+        // normalizado.
+        const tag = { ...rawTag, attrs: normalizeAttrNames(rawTag?.attrs) };
+        const name = String(tag?.tag ?? '').toLowerCase();
+        if (!allowed.has(name)) {
+            discard(ctx, name, 'no está entre las etiquetas admitidas en <head>');
+            continue;
+        }
+        if (name === 'script' && !options.allowScriptTags && !isJsonLdScript(tag)) {
+            discard(ctx, name, 'los scripts ejecutables no están habilitados en la configuración');
+            continue;
+        }
+        if (name === 'base') {
+            if (baseEmitted) {
+                discard(ctx, name, 'ya hay un <base>; sólo se admite uno por documento');
+                continue;
+            }
+            baseEmitted = true;
+        }
+        if (name === 'link' && !isAllowedLink(tag)) {
+            discard(ctx, name, `su rel no está admitido`);
+            continue;
+        }
+        if (name === 'meta' && isBlockedMeta(tag)) {
+            discard(ctx, name, 'su http-equiv no está admitido');
+            continue;
+        }
+        // El contenido de un <style> se emite sin escapar —es CSS, no HTML—, así
+        // que lo único que puede sacarlo de su elemento es un cierre literal.
+        if (name === 'style' && /<\/style/i.test(tag.children ?? '')) {
+            discard(ctx, name, 'su contenido cierra el elemento');
+            continue;
+        }
+        out.push(emit(name, tag, options.nonce));
+    }
+    return out.join('\n');
+}
+function emit(name, tag, nonce) {
+    const attrs = { ...(tag.attrs ?? {}) };
+    if (nonce && (name === 'style' || name === 'script'))
+        attrs.nonce = nonce;
+    const rendered = (0, escape_1.renderAttrs)(attrs, { where: `<${name}>`, isProduction: true });
+    const open = rendered ? `<${name} ${rendered}` : `<${name}`;
+    if (VOID_TAGS.has(name))
+        return `${open}>`;
+    // CSS y JavaScript son elementos de texto crudo. Se neutraliza el único
+    // fragmento que puede cerrar el elemento desde su contenido.
+    const body = name === 'style' || name === 'script'
+        ? String(tag.children ?? '').replace(new RegExp(`</${name}`, 'gi'), `<\\/${name}`)
+        : (0, escape_1.escapeHtmlText)(tag.children ?? '');
+    return `${open}>${body}</${name}>`;
+}
+function isAllowedLink(tag) {
+    const rel = String(tag.attrs?.rel ?? '').toLowerCase().trim();
+    return rel !== '' && rel.split(/\s+/).every((r) => LINK_REL_ALLOWLIST.has(r));
+}
+function isBlockedMeta(tag) {
+    const httpEquiv = String(tag.attrs?.['http-equiv'] ?? '').toLowerCase().trim();
+    return BLOCKED_HTTP_EQUIV.has(httpEquiv);
+}
+function isJsonLdScript(tag) {
+    return String(tag.attrs?.type ?? '').toLowerCase().trim() === 'application/ld+json';
+}
+/**
+ * Los nombres de React que no son el atributo HTML en minúsculas. Son los
+ * mismos que traduce `htmlAttributeName` en `@ressjs/assets`: un
+ * `pageConfig.head` y un `<Head>` con la misma prop tienen que emitir y
+ * filtrarse igual.
+ */
+const REACT_ATTRIBUTE_ALIASES = {
+    httpEquiv: 'http-equiv',
+    className: 'class',
+};
+/**
+ * Baja cada nombre de atributo a minúsculas, que es como el navegador los ve.
+ *
+ * Los alias de React van aparte: `httpEquiv` en minúsculas queda `httpequiv`,
+ * que el navegador NO reconoce como `http-equiv` (no redirige), y `className`
+ * quedaría `classname` en vez de `class`.
+ */
+function normalizeAttrNames(attrs) {
+    if (!attrs)
+        return {};
+    const camelCaseAliases = REACT_ATTRIBUTE_ALIASES;
+    const normalized = {};
+    for (const [name, value] of Object.entries(attrs)) {
+        const key = (camelCaseAliases[name] ?? name).toLowerCase();
+        normalized[key] = value;
+    }
+    return normalized;
+}
+function discard(ctx, name, why) {
+    if (ctx.isProduction)
+        return;
+    const where = ctx.route ? ` de ${ctx.route}` : '';
+    console.warn(`[ress] etiqueta <${name}> descartada en <head>${where}: ${why}.`);
+}

package/dist/security/headers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Cabeceras de la respuesta.
+ *
+ * Todas se emiten **antes** de escribir el cuerpo: una vez que la respuesta
+ * empezó a escribirse ya no se pueden cambiar, y el intento tira una excepción
+ * que enmascara el error original.
+ */
+import type { ServerResponse } from 'node:http';
+import { type Axis } from '@ressjs/platform';
+import type { ResolvedSecurityOptions } from './config';
+export interface HeaderContext {
+    isProduction: boolean;
+    /**
+     * Ejes por los que **esta** respuesta varía.
+     *
+     * Sale de las variantes que la página declara: una página sin variantes
+     * devuelve el mismo documento a cualquier cliente, y declarar que varía por
+     * dieciocho cabeceras obliga a una caché intermedia a guardar una entrada por
+     * combinación de algo que no cambia nunca.
+     *
+     * Vacío o `null` significa que no se emite `Vary` de plataforma.
+     */
+    varyBy?: readonly Axis[] | null;
+    /** Cabeceras de la red de distribución que el proyecto declaró. */
+    edge?: readonly {
+        header: string;
+        axis: string;
+    }[];
+    nonce?: string;
+    kind: 'html' | 'error';
+}
+/**
+ * Agrega campos a `Vary` sin duplicar y sin reemplazar lo que ya haya.
+ *
+ * Reemplazar sería destruir el trabajo de un middleware anterior: si alguien
+ * declaró `Vary: Accept-Language` porque su respuesta depende del idioma, y el
+ * framework lo pisa, el CDN sirve la traducción equivocada.
+ *
+ * Un `Vary: *` existente no se toca: ya es más restrictivo que cualquier lista.
+ */
+export declare function appendVary(res: ServerResponse, fields: readonly string[]): void;
+/**
+ * Aplica las cabeceras de seguridad de una respuesta.
+ *
+ * Es idempotente y no pisa lo que la aplicación ya haya definido, con dos
+ * excepciones: `Vary`, que amplía, y el `Content-Type` del HTML, que fija —el
+ * `charset` explícito es parte del endurecimiento, porque sin él un navegador
+ * puede inferir una codificación en la que los mismos bytes significan otra cosa.
+ */
+export declare function applySecurityHeaders(res: ServerResponse, opts: ResolvedSecurityOptions, ctx: HeaderContext): void;
+/**
+ * ¿Una caché compartida podría guardar una respuesta con este `Cache-Control`?
+ *
+ * Se decide al revés que adivinando: la respuesta queda fuera de una caché
+ * compartida sólo si lo prohíbe explícitamente, con `no-store` o con `private`
+ * sin lista de campos. `private="set-cookie"` no alcanza (la caché guarda el
+ * resto), tampoco un `private` que aparece como nombre de campo dentro de las
+ * comillas, y cualquier otra forma —`max-age=060`, directivas que no conocemos,
+ * o ninguna— cuenta como compartible. Reconocer las directivas de frescura en
+ * vez de las de privacidad dejaba pasar variantes como esa.
+ */
+export declare function isShareableCacheControl(value: unknown): boolean;
+/** El `Cache-Control` dado, o uno privado si el dado dejaría compartir la respuesta. */
+export declare function privateCacheControl(value: string): string;
+/**
+ * Cuánto puede cachearse un archivo estático.
+ *
+ * Un nombre con hash de contenido cambia cuando cambia el contenido, así que se
+ * puede guardar para siempre. Cualquier otro nombre puede volver a servirse con
+ * contenido distinto, y un archivo guardado como inmutable por error es
+ * irrecuperable: no hay forma de invalidarlo en el navegador de quien ya lo
+ * bajó. Por eso el default es revalidar.
+ */
+export declare function classifyAsset(pathname: string, buildOutputs: ReadonlySet<string>): 'immutable' | 'revalidate';
+/** El valor de `Cache-Control` de un archivo estático según su clase. */
+export declare function assetCacheControl(kind: 'immutable' | 'revalidate', opts: ResolvedSecurityOptions): string;

package/dist/security/headers.js

@@ -0,0 +1,278 @@
+"use strict";
+/**
+ * Cabeceras de la respuesta.
+ *
+ * Todas se emiten **antes** de escribir el cuerpo: una vez que la respuesta
+ * empezó a escribirse ya no se pueden cambiar, y el intento tira una excepción
+ * que enmascara el error original.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendVary = appendVary;
+exports.applySecurityHeaders = applySecurityHeaders;
+exports.isShareableCacheControl = isShareableCacheControl;
+exports.privateCacheControl = privateCacheControl;
+exports.classifyAsset = classifyAsset;
+exports.assetCacheControl = assetCacheControl;
+const platform_1 = require("@ressjs/platform");
+/**
+ * Agrega campos a `Vary` sin duplicar y sin reemplazar lo que ya haya.
+ *
+ * Reemplazar sería destruir el trabajo de un middleware anterior: si alguien
+ * declaró `Vary: Accept-Language` porque su respuesta depende del idioma, y el
+ * framework lo pisa, el CDN sirve la traducción equivocada.
+ *
+ * Un `Vary: *` existente no se toca: ya es más restrictivo que cualquier lista.
+ */
+function appendVary(res, fields) {
+    const current = res.getHeader('Vary');
+    const existing = Array.isArray(current) ? current.join(', ') : String(current ?? '');
+    if (existing.trim() === '*')
+        return;
+    const present = new Set(existing
+        .split(',')
+        .map((f) => f.trim().toLowerCase())
+        .filter(Boolean));
+    const merged = existing ? [existing.trim()] : [];
+    for (const field of fields) {
+        if (present.has(field.toLowerCase()))
+            continue;
+        present.add(field.toLowerCase());
+        merged.push(field);
+    }
+    if (merged.length)
+        res.setHeader('Vary', merged.join(', '));
+}
+/**
+ * Aplica las cabeceras de seguridad de una respuesta.
+ *
+ * Es idempotente y no pisa lo que la aplicación ya haya definido, con dos
+ * excepciones: `Vary`, que amplía, y el `Content-Type` del HTML, que fija —el
+ * `charset` explícito es parte del endurecimiento, porque sin él un navegador
+ * puede inferir una codificación en la que los mismos bytes significan otra cosa.
+ */
+function applySecurityHeaders(res, opts, ctx) {
+    if (res.headersSent) {
+        if (!ctx.isProduction) {
+            console.warn('[ress] no se pudieron aplicar las cabeceras de seguridad: la respuesta ya empezó a enviarse.');
+        }
+        return;
+    }
+    // Nunca incluye User-Agent: tiene tantos valores que una caché que separe
+    // por él casi nunca acierta. Es una decisión de política, no un límite del
+    // protocolo: la detección lo usa igual (R-10), y por eso lo que depende de
+    // la plataforma no se declara compartible (ver más abajo).
+    const fields = (0, platform_1.varyHeadersForAxes)(ctx.varyBy ?? [], {
+        // Sólo las que el proyecto declaró para su red: declarar cabeceras que nadie
+        // manda vuelve a inflar la clave de caché, que es lo que se quería evitar.
+        edge: ctx.edge,
+    });
+    if (fields.length) {
+        appendVary(res, fields);
+        requestClientHints(res);
+    }
+    if (opts.headers.contentTypeOptions)
+        setIfAbsent(res, 'X-Content-Type-Options', 'nosniff');
+    if (opts.headers.referrerPolicy) {
+        setIfAbsent(res, 'Referrer-Policy', opts.headers.referrerPolicy);
+    }
+    // No se emite por defecto: ress.js sirve páginas embebidas en apps por diseño,
+    // y una política de encuadre rompería el caso de uso principal.
+    if (opts.headers.frameOptions) {
+        setIfAbsent(res, 'X-Frame-Options', opts.headers.frameOptions);
+    }
+    // Apagada por defecto: activarla sobre un dominio que todavía sirve HTTP por
+    // alguna ruta lo deja inaccesible, y esa decisión es del proyecto.
+    if (opts.headers.hsts && ctx.isProduction) {
+        const { maxAge, includeSubDomains, preload } = opts.headers.hsts;
+        setIfAbsent(res, 'Strict-Transport-Security', [
+            `max-age=${maxAge}`,
+            includeSubDomains ? 'includeSubDomains' : '',
+            preload ? 'preload' : '',
+        ]
+            .filter(Boolean)
+            .join('; '));
+    }
+    setIfAbsent(res, 'Content-Type', 'text/html; charset=utf-8');
+    // Un archivo servido como documento por un visor de otra tecnología puede
+    // leer políticas de dominio cruzado que nadie revisó. Cuesta una cabecera.
+    setIfAbsent(res, 'X-Permitted-Cross-Domain-Policies', 'none');
+    // `X-XSS-Protection` no se emite a propósito: el filtro que activaba está
+    // retirado de los navegadores y, donde queda, introduce vulnerabilidades
+    // propias. La política de contenido es lo que lo reemplaza.
+    // Una página de error guardada por un intermediario es un incidente: el
+    // siguiente que pida esa URL recibe el error de otro.
+    if (ctx.kind === 'error') {
+        res.setHeader('Cache-Control', 'no-store');
+    }
+    else {
+        // `private` porque el HTML renderizado en el servidor puede llevar datos de
+        // la sesión. F-010 lo sobrescribe en las rutas que genere estáticamente.
+        setIfAbsent(res, 'Cache-Control', opts.cache.html);
+        forbidSharedCacheIfSettingCookies(res, ctx);
+        forbidSharedCacheIfPlatformDependent(res, opts, ctx);
+    }
+}
+/**
+ * ¿Una caché compartida podría guardar una respuesta con este `Cache-Control`?
+ *
+ * Se decide al revés que adivinando: la respuesta queda fuera de una caché
+ * compartida sólo si lo prohíbe explícitamente, con `no-store` o con `private`
+ * sin lista de campos. `private="set-cookie"` no alcanza (la caché guarda el
+ * resto), tampoco un `private` que aparece como nombre de campo dentro de las
+ * comillas, y cualquier otra forma —`max-age=060`, directivas que no conocemos,
+ * o ninguna— cuenta como compartible. Reconocer las directivas de frescura en
+ * vez de las de privacidad dejaba pasar variantes como esa.
+ */
+function isShareableCacheControl(value) {
+    return !cacheControlDirectives(value).some((d) => d === 'private' || d === 'no-store' || d.startsWith('no-store='));
+}
+/**
+ * Las directivas de un `Cache-Control`, en minúsculas.
+ *
+ * Se separa por comas respetando las comillas: en `private="set-cookie, x"`
+ * la coma es parte del argumento, no el fin de la directiva. Separar a ciegas
+ * convertía el `private` de adentro en una directiva propia.
+ */
+function cacheControlDirectives(value) {
+    const directives = [];
+    let current = '';
+    let quoted = false;
+    let escaped = false;
+    for (const char of String(value ?? '')) {
+        if (escaped) {
+            current += char;
+            escaped = false;
+        }
+        else if (quoted && char === '\\') {
+            current += char;
+            escaped = true;
+        }
+        else if (char === '"') {
+            quoted = !quoted;
+            current += char;
+        }
+        else if (char === ',' && !quoted) {
+            directives.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    directives.push(current);
+    return directives.map((d) => d.trim().toLowerCase()).filter(Boolean);
+}
+/** El `Cache-Control` dado, o uno privado si el dado dejaría compartir la respuesta. */
+function privateCacheControl(value) {
+    return isShareableCacheControl(value) ? 'private, no-cache' : value;
+}
+/**
+ * Un HTML que depende de la plataforma nunca se declara compartible.
+ *
+ * La detección usa siempre el User-Agent, y el User-Agent no se declara en
+ * `Vary`: tiene tantos valores que una caché que separe por él casi nunca
+ * acierta. Es una decisión de política, no un límite del protocolo: sin ese
+ * campo en `Vary`, dos clientes que sólo difieren en User-Agent comparten la
+ * clave de caché aunque reciban documentos distintos. Entonces ese documento no
+ * puede ser compartible, venga el `Cache-Control` de `security.cache.html` o de
+ * un middleware.
+ *
+ * Depende de la plataforma si la página tiene variantes o si el documento lleva
+ * la plataforma serializada. Si la aplicación misma lee el User-Agent en su
+ * código y declara la respuesta pública, le toca declarar su propio `Vary`.
+ */
+function forbidSharedCacheIfPlatformDependent(res, opts, ctx) {
+    if (ctx.varyBy == null)
+        return;
+    const dependsOnPlatform = ctx.varyBy.length > 0 || opts.serializePlatform === 'always';
+    if (!dependsOnPlatform)
+        return;
+    const current = res.getHeader('Cache-Control');
+    if (!isShareableCacheControl(current))
+        return;
+    res.setHeader('Cache-Control', 'private, no-cache');
+    if (!ctx.isProduction) {
+        console.warn(`[ress] la respuesta depende de la plataforma y su Cache-Control (${String(current)}) ` +
+            'dejaba que una caché compartida la guardara. Se cambió a `private, no-cache`: ' +
+            'le habría entregado a un cliente la variante de otro.');
+    }
+}
+/**
+ * Pide al navegador las pistas de plataforma que necesita la resolución.
+ *
+ * `Sec-CH-UA-Form-Factors` es la señal que dice `Desktop`, `Mobile`, `Tablet` o
+ * `TV`: exactamente lo que hoy hay que adivinar del User-Agent, pero con cuatro
+ * valores posibles en vez de cientos de miles. Es de alta entropía, así que el
+ * navegador no la manda salvo que el servidor la pida.
+ *
+ * `Critical-CH` hace que la **primera** petición se reintente ya con la pista,
+ * en lugar de servir una variante adivinada y acertar recién en la segunda.
+ * Cuesta un viaje extra la primera vez y sólo se pide en las páginas que varían.
+ *
+ * Es una mejora para navegadores basados en Chromium. Safari y Firefox no
+ * mandan estas pistas, y para ellos el User-Agent sigue siendo la única señal
+ * disponible en una navegación directa.
+ */
+function requestClientHints(res) {
+    const hints = 'Sec-CH-UA-Platform, Sec-CH-UA-Mobile, Sec-CH-UA-Form-Factors';
+    setIfAbsent(res, 'Accept-CH', hints);
+    setIfAbsent(res, 'Critical-CH', 'Sec-CH-UA-Form-Factors');
+}
+/**
+ * Una respuesta que entrega una cookie no puede guardarse en una caché compartida.
+ *
+ * Si un intermediario la guarda, el siguiente que pida esa URL recibe **la
+ * cookie de otro**: la sesión de una persona pasa a la siguiente. Es de los
+ * incidentes más caros que produce una configuración de caché, y ocurre en
+ * cuanto alguien pone la caché del HTML en `public` sin acordarse de que un
+ * middleware setea una cookie.
+ *
+ * El default `private` ya lo evita; esto protege al proyecto que lo cambió.
+ */
+function forbidSharedCacheIfSettingCookies(res, ctx) {
+    if (!res.getHeader('set-cookie'))
+        return;
+    const current = String(res.getHeader('Cache-Control') ?? '');
+    if (!/\bpublic\b/.test(current))
+        return;
+    res.setHeader('Cache-Control', current.replace(/\bpublic\b/, 'private'));
+    if (!ctx.isProduction) {
+        console.warn('[ress] la respuesta entrega una cookie y su Cache-Control decía `public`. ' +
+            'Se cambió a `private`: una caché compartida le habría entregado esa cookie ' +
+            'a quien pidiera la misma URL después.');
+    }
+}
+function setIfAbsent(res, name, value) {
+    if (res.getHeader(name) === undefined)
+        res.setHeader(name, value);
+}
+/** Nombre de archivo con un hash de contenido: `algo-A1b2C3d4.js`. */
+const HASHED_NAME_RE = /-[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
+/**
+ * Cuánto puede cachearse un archivo estático.
+ *
+ * Un nombre con hash de contenido cambia cuando cambia el contenido, así que se
+ * puede guardar para siempre. Cualquier otro nombre puede volver a servirse con
+ * contenido distinto, y un archivo guardado como inmutable por error es
+ * irrecuperable: no hay forma de invalidarlo en el navegador de quien ya lo
+ * bajó. Por eso el default es revalidar.
+ */
+function classifyAsset(pathname, buildOutputs) {
+    const normalized = pathname.replace(/^\//, '');
+    const fileName = normalized.split('/').pop() ?? '';
+    // Un documento cacheado de forma inmutable deja la aplicación congelada.
+    if (fileName.endsWith('.html'))
+        return 'revalidate';
+    // El manifest es la fuente autoritativa: son nombres que generó el
+    // empaquetador y por construcción llevan el hash del contenido.
+    if (buildOutputs.has(normalized))
+        return 'immutable';
+    // Respaldo para los archivos que emite un plugin sin pasar por el manifest.
+    return HASHED_NAME_RE.test(fileName) ? 'immutable' : 'revalidate';
+}
+/** El valor de `Cache-Control` de un archivo estático según su clase. */
+function assetCacheControl(kind, opts) {
+    return kind === 'immutable'
+        ? `public, max-age=${opts.cache.immutableMaxAge}, immutable`
+        : `public, max-age=${opts.cache.staticMaxAge}, must-revalidate`;
+}

package/dist/security/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Endurecimiento del renderizado en el servidor.
+ *
+ * Reúne lo que protege una respuesta: qué se serializa hacia el cliente, cómo se
+ * escapa lo que llega al documento, qué cabeceras lleva y qué se cuenta cuando
+ * algo falla.
+ */
+export { resolveSecurityOptions } from './config';
+export type { ClientPropsPolicy, ResolvedSecurityOptions, SecurityContext, SecurityOptions, } from './config';
+export { escapeAttrValue, escapeHtmlText, renderAttrs, safeAttrName } from './escape';
+export type { EscapeContext } from './escape';
+export { HEAD_TAG_ALLOWLIST, renderHeadTags } from './head-tags';
+export type { HeadTag, HeadTagOptions } from './head-tags';
+export { checkStateSize, renderStateScript, serializeState, SerializationError, } from './serialize';
+export type { SizeCheck, StateBlock } from './serialize';
+export { appendVary, applySecurityHeaders, isShareableCacheControl, privateCacheControl, assetCacheControl, classifyAsset, } from './headers';
+export type { HeaderContext } from './headers';
+export { buildCsp, cspHeaderName, createNonce, injectNonce, reportingEndpointsHeader, } from './csp';
+export type { CspOptions } from './csp';
+export { logServerError, PublicFacingError, sanitizeError } from './errors';
+export type { PublicError } from './errors';
+export { pickClientProps, withheldKeys } from './client-props';
+export { assertDevServerHardening, DENIED_FILES, devServerDefaults } from './dev-hardening';
+export type { DevServerConfig } from './dev-hardening';

package/dist/security/index.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Endurecimiento del renderizado en el servidor.
+ *
+ * Reúne lo que protege una respuesta: qué se serializa hacia el cliente, cómo se
+ * escapa lo que llega al documento, qué cabeceras lleva y qué se cuenta cuando
+ * algo falla.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devServerDefaults = exports.DENIED_FILES = exports.assertDevServerHardening = exports.withheldKeys = exports.pickClientProps = exports.sanitizeError = exports.PublicFacingError = exports.logServerError = exports.reportingEndpointsHeader = exports.injectNonce = exports.createNonce = exports.cspHeaderName = exports.buildCsp = exports.classifyAsset = exports.assetCacheControl = exports.privateCacheControl = exports.isShareableCacheControl = exports.applySecurityHeaders = exports.appendVary = exports.SerializationError = exports.serializeState = exports.renderStateScript = exports.checkStateSize = exports.renderHeadTags = exports.HEAD_TAG_ALLOWLIST = exports.safeAttrName = exports.renderAttrs = exports.escapeHtmlText = exports.escapeAttrValue = exports.resolveSecurityOptions = void 0;
+var config_1 = require("./config");
+Object.defineProperty(exports, "resolveSecurityOptions", { enumerable: true, get: function () { return config_1.resolveSecurityOptions; } });
+var escape_1 = require("./escape");
+Object.defineProperty(exports, "escapeAttrValue", { enumerable: true, get: function () { return escape_1.escapeAttrValue; } });
+Object.defineProperty(exports, "escapeHtmlText", { enumerable: true, get: function () { return escape_1.escapeHtmlText; } });
+Object.defineProperty(exports, "renderAttrs", { enumerable: true, get: function () { return escape_1.renderAttrs; } });
+Object.defineProperty(exports, "safeAttrName", { enumerable: true, get: function () { return escape_1.safeAttrName; } });
+var head_tags_1 = require("./head-tags");
+Object.defineProperty(exports, "HEAD_TAG_ALLOWLIST", { enumerable: true, get: function () { return head_tags_1.HEAD_TAG_ALLOWLIST; } });
+Object.defineProperty(exports, "renderHeadTags", { enumerable: true, get: function () { return head_tags_1.renderHeadTags; } });
+var serialize_1 = require("./serialize");
+Object.defineProperty(exports, "checkStateSize", { enumerable: true, get: function () { return serialize_1.checkStateSize; } });
+Object.defineProperty(exports, "renderStateScript", { enumerable: true, get: function () { return serialize_1.renderStateScript; } });
+Object.defineProperty(exports, "serializeState", { enumerable: true, get: function () { return serialize_1.serializeState; } });
+Object.defineProperty(exports, "SerializationError", { enumerable: true, get: function () { return serialize_1.SerializationError; } });
+var headers_1 = require("./headers");
+Object.defineProperty(exports, "appendVary", { enumerable: true, get: function () { return headers_1.appendVary; } });
+Object.defineProperty(exports, "applySecurityHeaders", { enumerable: true, get: function () { return headers_1.applySecurityHeaders; } });
+Object.defineProperty(exports, "isShareableCacheControl", { enumerable: true, get: function () { return headers_1.isShareableCacheControl; } });
+Object.defineProperty(exports, "privateCacheControl", { enumerable: true, get: function () { return headers_1.privateCacheControl; } });
+Object.defineProperty(exports, "assetCacheControl", { enumerable: true, get: function () { return headers_1.assetCacheControl; } });
+Object.defineProperty(exports, "classifyAsset", { enumerable: true, get: function () { return headers_1.classifyAsset; } });
+var csp_1 = require("./csp");
+Object.defineProperty(exports, "buildCsp", { enumerable: true, get: function () { return csp_1.buildCsp; } });
+Object.defineProperty(exports, "cspHeaderName", { enumerable: true, get: function () { return csp_1.cspHeaderName; } });
+Object.defineProperty(exports, "createNonce", { enumerable: true, get: function () { return csp_1.createNonce; } });
+Object.defineProperty(exports, "injectNonce", { enumerable: true, get: function () { return csp_1.injectNonce; } });
+Object.defineProperty(exports, "reportingEndpointsHeader", { enumerable: true, get: function () { return csp_1.reportingEndpointsHeader; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "logServerError", { enumerable: true, get: function () { return errors_1.logServerError; } });
+Object.defineProperty(exports, "PublicFacingError", { enumerable: true, get: function () { return errors_1.PublicFacingError; } });
+Object.defineProperty(exports, "sanitizeError", { enumerable: true, get: function () { return errors_1.sanitizeError; } });
+var client_props_1 = require("./client-props");
+Object.defineProperty(exports, "pickClientProps", { enumerable: true, get: function () { return client_props_1.pickClientProps; } });
+Object.defineProperty(exports, "withheldKeys", { enumerable: true, get: function () { return client_props_1.withheldKeys; } });
+var dev_hardening_1 = require("./dev-hardening");
+Object.defineProperty(exports, "assertDevServerHardening", { enumerable: true, get: function () { return dev_hardening_1.assertDevServerHardening; } });
+Object.defineProperty(exports, "DENIED_FILES", { enumerable: true, get: function () { return dev_hardening_1.DENIED_FILES; } });
+Object.defineProperty(exports, "devServerDefaults", { enumerable: true, get: function () { return dev_hardening_1.devServerDefaults; } });

package/dist/security/serialize.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Serialización del estado que viaja al cliente.
+ *
+ * El JSON se embebe en un `<script>` inline, así que además de ser JSON válido
+ * tiene que sobrevivir a dos gramáticas más: la del HTML, que busca `</script`,
+ * `<!--` y `<!` dentro del elemento, y la de JavaScript, donde U+2028 y U+2029
+ * son terminadores de línea que parten un literal de cadena.
+ */
+export declare class SerializationError extends Error {
+    readonly reason: string;
+    readonly path: string;
+    constructor(reason: string, path: string);
+}
+/**
+ * Serializa un valor para embeberlo en un `<script>` inline.
+ *
+ * El resultado es JSON válido y `JSON.parse` lo devuelve idéntico al original.
+ */
+export declare function serializeState(value: unknown, path?: string): string;
+export interface StateBlock {
+    /** Nombre de la variable global. Ej: `__RESS_PROPS__`. */
+    varName: string;
+    value: unknown;
+}
+/**
+ * El bloque `<script>` con el estado.
+ *
+ * Recibe el nonce cuando hay política de contenido: sin él, el bloque no se
+ * ejecuta y la hidratación no encuentra sus props.
+ */
+export declare function renderStateScript(blocks: StateBlock[], nonce?: string): string;
+export interface SizeCheck {
+    bytes: number;
+    overLimit: boolean;
+    /** Las claves de primer nivel más pesadas: es lo que hace accionable el aviso. */
+    heaviest: Array<{
+        key: string;
+        bytes: number;
+    }>;
+}
+/**
+ * Cuánto pesa el estado que viaja.
+ *
+ * Se mide sobre el string **ya serializado y escapado**, que es lo que
+ * efectivamente se transfiere, y en bytes y no en caracteres, porque un
+ * carácter fuera de ASCII ocupa más de uno.
+ */
+export declare function checkStateSize(serialized: string, limitBytes: number, value?: unknown): SizeCheck;