@ressjs/vite-router 0.5.0 → 0.6.0-experimental.0

package/dist/security/config.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Opciones de seguridad del framework.
+ *
+ * Se resuelven **una vez al arrancar**, no por petición: el objeto resultante
+ * está completo y congelado, y viaja por el contexto de seguridad hasta quien lo
+ * necesite. Resolver defaults por petición sería trabajo repetido y, peor,
+ * abriría la puerta a que dos partes de la misma respuesta usen valores
+ * distintos.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSecurityOptions = resolveSecurityOptions;
+/**
+ * Defaults.
+ *
+ * Dos ausencias son deliberadas y están explicadas donde se aplican:
+ * `frameOptions` apagada, porque ress.js sirve páginas embebidas por diseño, y
+ * `hsts` apagada, porque activarla sobre un dominio que todavía sirve HTTP por
+ * alguna ruta lo deja inaccesible.
+ */
+function resolveSecurityOptions(user = {}) {
+    return deepFreeze({
+        clientProps: {
+            expose: user.clientProps?.expose ?? [],
+            exposeServerSideProps: user.clientProps?.exposeServerSideProps ?? true,
+        },
+        maxStateBytes: user.maxStateBytes ?? 131072,
+        onStateOverLimit: user.onStateOverLimit ?? 'warn',
+        varyOnUserAgent: user.varyOnUserAgent ?? false,
+        serializePlatform: user.serializePlatform ?? 'auto',
+        headers: {
+            contentTypeOptions: user.headers?.contentTypeOptions ?? true,
+            referrerPolicy: user.headers?.referrerPolicy ?? 'strict-origin-when-cross-origin',
+            frameOptions: user.headers?.frameOptions ?? false,
+            hsts: user.headers?.hsts ?? false,
+        },
+        cache: {
+            html: user.cache?.html ?? 'private, no-cache, must-revalidate',
+            immutableMaxAge: user.cache?.immutableMaxAge ?? 31536000,
+            staticMaxAge: user.cache?.staticMaxAge ?? 0,
+        },
+        csp: {
+            enabled: user.csp?.enabled ?? false,
+            reportOnly: user.csp?.reportOnly ?? false,
+            directives: user.csp?.directives ?? {},
+            ...(user.csp?.reportUri ? { reportUri: user.csp.reportUri } : {}),
+        },
+        head: {
+            allowScriptTags: user.head?.allowScriptTags ?? false,
+            extraTagAllowlist: user.head?.extraTagAllowlist ?? [],
+        },
+        dev: {
+            ...(user.dev?.allowedHosts ? { allowedHosts: user.dev.allowedHosts } : {}),
+            allowedOrigins: user.dev?.allowedOrigins ?? false,
+        },
+    });
+}
+/**
+ * Congela en profundidad.
+ *
+ * Que las opciones sean inmutables importa porque el objeto se comparte entre
+ * todas las peticiones: una mutación desde el código de una página cambiaría la
+ * política de seguridad para todas las siguientes.
+ */
+function deepFreeze(value) {
+    if (value && typeof value === 'object') {
+        for (const key of Object.getOwnPropertyNames(value)) {
+            deepFreeze(value[key]);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/security/csp.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Política de seguridad de contenido.
+ *
+ * El obstáculo es el bloque de estado inline: cualquier política que valga la
+ * pena prohíbe `'unsafe-inline'`, y sin autorización explícita ese bloque no se
+ * ejecuta y la hidratación no encuentra sus props.
+ *
+ * Se resuelve con un **nonce por petición** y no con un hash: el contenido del
+ * bloque cambia en cada petición porque cambian las props, así que un hash
+ * habría que recalcularlo igual, y cuesta un SHA-256 sobre todo el estado contra
+ * 16 bytes de aleatoriedad.
+ */
+export interface CspOptions {
+    enabled: boolean;
+    reportOnly: boolean;
+    directives: Record<string, string[] | false>;
+    reportUri?: string;
+}
+/** Uno por petición. */
+export declare function createNonce(): string;
+/**
+ * La política, con el nonce ya inyectado.
+ *
+ * La aplicación puede endurecer cualquier directiva reemplazando su lista, pero
+ * el nonce vuelve a `script-src` siempre: una política que la aplicación
+ * escribió sin él dejaría la página sin hidratar, y eso se ve como un error de
+ * la aplicación y no de su configuración.
+ */
+export declare function buildCsp(opts: CspOptions, nonce: string, isProduction: boolean): string;
+/** Nombre del grupo que enlaza la directiva `report-to` con `Reporting-Endpoints`. */
+export declare const REPORT_GROUP = "ress-csp";
+/**
+ * La cabecera que declara a dónde van los informes.
+ *
+ * `report-to` nombra un grupo, no una dirección: sin esta cabecera que lo
+ * define, la directiva no apunta a ningún lado y los informes se pierden.
+ */
+export declare function reportingEndpointsHeader(reportUri: string): string;
+/** Qué cabecera lleva la política, según se aplique o sólo se reporte. */
+export declare function cspHeaderName(opts: CspOptions): string;
+/**
+ * Respeta la política que ya escribió la aplicación, inyectándole el nonce.
+ *
+ * Una empresa va a querer su propia política —sus dominios, sus proveedores— y
+ * escribirla con un middleware de Express es la forma natural de hacerlo. Pisarla
+ * sería decidir por ella.
+ *
+ * Lo único que el framework agrega es el nonce en `script-src`: sin él, el bloque
+ * de estado no se ejecuta y la página no hidrata, y eso se ve como un error de la
+ * aplicación en vez de una consecuencia de su configuración. Es la misma regla
+ * que rige para las directivas declaradas en la configuración.
+ */
+export declare function injectNonce(existing: string, nonce: string): string;

package/dist/security/csp.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Política de seguridad de contenido.
+ *
+ * El obstáculo es el bloque de estado inline: cualquier política que valga la
+ * pena prohíbe `'unsafe-inline'`, y sin autorización explícita ese bloque no se
+ * ejecuta y la hidratación no encuentra sus props.
+ *
+ * Se resuelve con un **nonce por petición** y no con un hash: el contenido del
+ * bloque cambia en cada petición porque cambian las props, así que un hash
+ * habría que recalcularlo igual, y cuesta un SHA-256 sobre todo el estado contra
+ * 16 bytes de aleatoriedad.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPORT_GROUP = void 0;
+exports.createNonce = createNonce;
+exports.buildCsp = buildCsp;
+exports.reportingEndpointsHeader = reportingEndpointsHeader;
+exports.cspHeaderName = cspHeaderName;
+exports.injectNonce = injectNonce;
+const node_crypto_1 = require("node:crypto");
+/** Uno por petición. */
+function createNonce() {
+    return (0, node_crypto_1.randomBytes)(16).toString('base64');
+}
+/**
+ * La política, con el nonce ya inyectado.
+ *
+ * La aplicación puede endurecer cualquier directiva reemplazando su lista, pero
+ * el nonce vuelve a `script-src` siempre: una política que la aplicación
+ * escribió sin él dejaría la página sin hidratar, y eso se ve como un error de
+ * la aplicación y no de su configuración.
+ */
+function buildCsp(opts, nonce, isProduction) {
+    const defaults = {
+        'default-src': ["'self'"],
+        'script-src': ["'self'", `'nonce-${nonce}'`],
+        // `'unsafe-inline'` es el punto débil conocido de la política por defecto:
+        // se queda mientras el pipeline pueda emitir estilos inline.
+        'style-src': ["'self'", `'nonce-${nonce}'`, "'unsafe-inline'"],
+        'img-src': ["'self'", 'data:', 'blob:'],
+        'font-src': ["'self'", 'data:'],
+        'connect-src': ["'self'"],
+        'object-src': ["'none'"],
+        // Impide que un <base> inyectado redirija todas las URLs relativas.
+        'base-uri': ["'self'"],
+        'form-action': ["'self'"],
+    };
+    if (!isProduction) {
+        // El cliente de recarga en caliente de Vite necesita evaluar código y abrir
+        // un WebSocket.
+        defaults['script-src'].push("'unsafe-eval'");
+        defaults['connect-src'].push('ws:', 'wss:');
+    }
+    const merged = { ...defaults };
+    for (const [directive, value] of Object.entries(opts.directives ?? {})) {
+        merged[directive] = value;
+    }
+    if (Array.isArray(merged['script-src']) && !merged['script-src'].some(isNonce)) {
+        merged['script-src'] = [...merged['script-src'], `'nonce-${nonce}'`];
+    }
+    const parts = Object.entries(merged)
+        .filter((entry) => Array.isArray(entry[1]))
+        .map(([directive, values]) => `${directive} ${values.join(' ')}`);
+    // `report-to` es lo vigente; `report-uri` quedó deprecado pero se sigue
+    // emitiendo porque hay navegadores que sólo entienden ese.
+    if (opts.reportUri) {
+        parts.push(`report-uri ${opts.reportUri}`);
+        parts.push(`report-to ${exports.REPORT_GROUP}`);
+    }
+    return parts.join('; ');
+}
+/** Nombre del grupo que enlaza la directiva `report-to` con `Reporting-Endpoints`. */
+exports.REPORT_GROUP = 'ress-csp';
+/**
+ * La cabecera que declara a dónde van los informes.
+ *
+ * `report-to` nombra un grupo, no una dirección: sin esta cabecera que lo
+ * define, la directiva no apunta a ningún lado y los informes se pierden.
+ */
+function reportingEndpointsHeader(reportUri) {
+    return `${exports.REPORT_GROUP}="${reportUri}"`;
+}
+const isNonce = (v) => v.startsWith("'nonce-");
+/** Qué cabecera lleva la política, según se aplique o sólo se reporte. */
+function cspHeaderName(opts) {
+    return opts.reportOnly ? 'Content-Security-Policy-Report-Only' : 'Content-Security-Policy';
+}
+/**
+ * Respeta la política que ya escribió la aplicación, inyectándole el nonce.
+ *
+ * Una empresa va a querer su propia política —sus dominios, sus proveedores— y
+ * escribirla con un middleware de Express es la forma natural de hacerlo. Pisarla
+ * sería decidir por ella.
+ *
+ * Lo único que el framework agrega es el nonce en `script-src`: sin él, el bloque
+ * de estado no se ejecuta y la página no hidrata, y eso se ve como un error de la
+ * aplicación en vez de una consecuencia de su configuración. Es la misma regla
+ * que rige para las directivas declaradas en la configuración.
+ */
+function injectNonce(existing, nonce) {
+    const directives = existing
+        .split(';')
+        .map((d) => d.trim())
+        .filter(Boolean);
+    const index = directives.findIndex((d) => /^script-src\b/i.test(d));
+    if (index === -1) {
+        // Sin `script-src`, manda `default-src`. Se agrega una que lo herede y sume
+        // el nonce, en vez de tocar la que la aplicación escribió.
+        const fallback = directives.find((d) => /^default-src\b/i.test(d));
+        const base = fallback ? fallback.replace(/^default-src\b/i, '').trim() : "'self'";
+        return [...directives, `script-src ${base} 'nonce-${nonce}'`].join('; ');
+    }
+    if (directives[index].includes("'nonce-"))
+        return existing;
+    directives[index] = `${directives[index]} 'nonce-${nonce}'`;
+    return directives.join('; ');
+}

package/dist/security/dev-hardening.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Verificaciones del servidor de desarrollo.
+ *
+ * El servidor de desarrollo corre con acceso al proyecto entero y sin
+ * autenticación. Las tres configuraciones que se rechazan acá lo vuelven
+ * alcanzable desde afuera de la máquina, y las tres se escriben por comodidad —
+ * para probar desde el teléfono, para que ande un iframe— sin que sea evidente
+ * qué se abre.
+ */
+export interface DevServerConfig {
+    server?: {
+        allowedHosts?: boolean | string[];
+        cors?: boolean | {
+            origin?: unknown;
+        };
+        fs?: {
+            strict?: boolean;
+            deny?: string[];
+        };
+    };
+    legacy?: {
+        skipWebSocketTokenCheck?: boolean;
+    };
+}
+/**
+ * Archivos que el servidor de desarrollo nunca debe entregar, además de los que
+ * Vite ya niega.
+ */
+export declare const DENIED_FILES: string[];
+/**
+ * Corre al arrancar en desarrollo. Falla con un mensaje que dice qué hacer.
+ *
+ * Es un error de arranque y no un aviso a propósito: un aviso en la consola de
+ * un servidor de desarrollo no lo lee nadie.
+ */
+export declare function assertDevServerHardening(config?: DevServerConfig): void;
+/** Lo que el plugin aporta a la configuración del servidor de desarrollo. */
+export declare function devServerDefaults(allowedOrigins: string[] | false): {
+    cors: {
+        origin: boolean | string[];
+    };
+    fs: {
+        strict: boolean;
+        deny: string[];
+    };
+};

package/dist/security/dev-hardening.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Verificaciones del servidor de desarrollo.
+ *
+ * El servidor de desarrollo corre con acceso al proyecto entero y sin
+ * autenticación. Las tres configuraciones que se rechazan acá lo vuelven
+ * alcanzable desde afuera de la máquina, y las tres se escriben por comodidad —
+ * para probar desde el teléfono, para que ande un iframe— sin que sea evidente
+ * qué se abre.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DENIED_FILES = void 0;
+exports.assertDevServerHardening = assertDevServerHardening;
+exports.devServerDefaults = devServerDefaults;
+/**
+ * Archivos que el servidor de desarrollo nunca debe entregar, además de los que
+ * Vite ya niega.
+ */
+exports.DENIED_FILES = [
+    '.env',
+    '.env.*',
+    '*.pem',
+    '*.key',
+    '*.crt',
+    'ress.config.*',
+    '**/.git/**',
+];
+/**
+ * Corre al arrancar en desarrollo. Falla con un mensaje que dice qué hacer.
+ *
+ * Es un error de arranque y no un aviso a propósito: un aviso en la consola de
+ * un servidor de desarrollo no lo lee nadie.
+ */
+function assertDevServerHardening(config = {}) {
+    const server = config.server ?? {};
+    if (server.allowedHosts === true) {
+        throw new Error('[ress] `server.allowedHosts: true` desactiva la validación de la cabecera Host, ' +
+            'lo que permite que una página cualquiera resuelva su dominio a tu máquina y ' +
+            'lea lo que sirve tu servidor de desarrollo.\n' +
+            'Declará el host que necesitás: `server: { allowedHosts: ["mi-host.local"] }`.');
+    }
+    const origin = typeof server.cors === 'object' ? server.cors?.origin : server.cors;
+    if (origin === true || origin === '*') {
+        throw new Error('[ress] `server.cors.origin` abierto permite que cualquier sitio lea las respuestas ' +
+            'de tu servidor de desarrollo, incluido el código fuente de tu proyecto.\n' +
+            'Declará los orígenes que necesitás: `server: { cors: { origin: ["https://mi-sitio.local"] } }`.');
+    }
+    if (config.legacy?.skipWebSocketTokenCheck) {
+        console.warn('[ress] `legacy.skipWebSocketTokenCheck` desactiva la validación de origen del ' +
+            'WebSocket de recarga en caliente. Con eso, una página abierta en otra pestaña ' +
+            'puede conectarse a tu servidor de desarrollo y pedirle archivos del proyecto.');
+    }
+}
+/** Lo que el plugin aporta a la configuración del servidor de desarrollo. */
+function devServerDefaults(allowedOrigins) {
+    return {
+        // `origin: false` no emite cabeceras de CORS: otro origen puede disparar el
+        // pedido, pero no puede leer la respuesta.
+        cors: { origin: allowedOrigins === false ? false : allowedOrigins },
+        fs: {
+            strict: true,
+            deny: exports.DENIED_FILES,
+        },
+    };
+}

package/dist/security/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Qué ve quien pide una página cuando algo falla.
+ *
+ * Un stack trace en la respuesta entrega la estructura de directorios del
+ * servidor, las versiones de las dependencias y a veces el contenido de una
+ * consulta. En desarrollo eso es exactamente lo que se quiere ver; en producción
+ * es reconocimiento gratis.
+ *
+ * El error completo **siempre** se registra del lado del servidor. Lo que cambia
+ * es lo que viaja.
+ */
+export interface PublicError {
+    statusCode: number;
+    message: string;
+    /** Sólo en desarrollo. */
+    stack?: string;
+    /** Sólo en desarrollo. */
+    original?: string;
+}
+/**
+ * Un error cuyo mensaje está pensado para mostrarse.
+ *
+ * Es la única forma de que un mensaje sobreviva a producción: la aplicación
+ * puede decir «el producto no existe» sin que eso abra la puerta a que se filtre
+ * un error del framework.
+ */
+export declare class PublicFacingError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+export declare function sanitizeError(err: unknown, isProduction: boolean): PublicError;
+/** Registra el error completo, con el contexto que hace falta para encontrarlo. */
+export declare function logServerError(err: unknown, ctx: {
+    method?: string;
+    url?: string;
+    statusCode: number;
+}): void;

package/dist/security/errors.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Qué ve quien pide una página cuando algo falla.
+ *
+ * Un stack trace en la respuesta entrega la estructura de directorios del
+ * servidor, las versiones de las dependencias y a veces el contenido de una
+ * consulta. En desarrollo eso es exactamente lo que se quiere ver; en producción
+ * es reconocimiento gratis.
+ *
+ * El error completo **siempre** se registra del lado del servidor. Lo que cambia
+ * es lo que viaja.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicFacingError = void 0;
+exports.sanitizeError = sanitizeError;
+exports.logServerError = logServerError;
+/**
+ * Un error cuyo mensaje está pensado para mostrarse.
+ *
+ * Es la única forma de que un mensaje sobreviva a producción: la aplicación
+ * puede decir «el producto no existe» sin que eso abra la puerta a que se filtre
+ * un error del framework.
+ */
+class PublicFacingError extends Error {
+    statusCode;
+    constructor(message, statusCode = 400) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'PublicFacingError';
+    }
+}
+exports.PublicFacingError = PublicFacingError;
+const STATUS_TEXT = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    409: 'Conflict',
+    410: 'Gone',
+    422: 'Unprocessable Entity',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+};
+function sanitizeError(err, isProduction) {
+    const statusCode = readStatusCode(err);
+    const error = err instanceof Error ? err : undefined;
+    if (!isProduction) {
+        return {
+            statusCode,
+            message: error?.message ?? String(err),
+            ...(error?.stack ? { stack: error.stack } : {}),
+            original: String(err),
+        };
+    }
+    // La excepción deliberada: un mensaje que la aplicación marcó como público.
+    if (err instanceof PublicFacingError) {
+        return { statusCode, message: err.message };
+    }
+    return { statusCode, message: STATUS_TEXT[statusCode] ?? 'Internal Server Error' };
+}
+/**
+ * Un código de estado que no sea un entero entre 400 y 599 es 500.
+ *
+ * Devolver el valor tal cual dejaría que un error con `statusCode: 200` se
+ * respondiera como éxito, o que uno con una cadena rompiera la respuesta entera.
+ */
+function readStatusCode(err) {
+    const raw = err;
+    const candidate = raw?.statusCode ?? raw?.status;
+    return typeof candidate === 'number' &&
+        Number.isInteger(candidate) &&
+        candidate >= 400 &&
+        candidate <= 599
+        ? candidate
+        : 500;
+}
+/** Registra el error completo, con el contexto que hace falta para encontrarlo. */
+function logServerError(err, ctx) {
+    console.error(`[ress] ${ctx.method ?? 'GET'} ${ctx.url ?? '?'} → ${ctx.statusCode}`, err instanceof Error ? (err.stack ?? err.message) : err);
+}

package/dist/security/escape.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Escapado de HTML.
+ *
+ * Todo dato de la aplicación que llegue al documento pasa por acá. La regla es
+ * escapar **por carácter y no por secuencia**: buscar `</script>` es frágil
+ * porque `</ScRiPt >` también cierra el elemento y la lista de variantes es
+ * larga; escapar el `<` las cubre todas.
+ */
+/** Para texto entre etiquetas: el contenido de `<title>`, por ejemplo. */
+export declare function escapeHtmlText(value: unknown): string;
+/**
+ * Para el valor de un atributo, que siempre se emite entre comillas dobles.
+ *
+ * Se escapan las dos comillas aunque sólo una pueda cerrar el atributo: cuesta
+ * lo mismo y hace que la función siga siendo correcta si alguien la usa en otro
+ * contexto.
+ */
+export declare function escapeAttrValue(value: unknown): string;
+/**
+ * Valida un nombre de atributo. Devuelve `null` si no se puede emitir.
+ *
+ * Se rechaza todo lo que empiece con `on`: son manejadores de eventos, y un
+ * valor controlado por quien envía la petición dentro de uno es ejecución de
+ * código. `srcdoc` va por lo mismo — su contenido es un documento entero.
+ */
+export declare function safeAttrName(name: string): string | null;
+export interface EscapeContext {
+    /** Dónde se está emitiendo, para que el aviso diga qué elemento. */
+    where: string;
+    isProduction: boolean;
+    route?: string;
+}
+/**
+ * Serializa un mapa de atributos ya escapado. Devuelve `''` si no queda ninguno.
+ *
+ * Un atributo rechazado se descarta. En desarrollo se avisa; en producción no,
+ * porque un registro por petición sobre un dato que controla quien ataca es en
+ * sí mismo una forma de inundar los logs.
+ */
+export declare function renderAttrs(attrs: Record<string, unknown>, ctx: EscapeContext | string): string;

package/dist/security/escape.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Escapado de HTML.
+ *
+ * Todo dato de la aplicación que llegue al documento pasa por acá. La regla es
+ * escapar **por carácter y no por secuencia**: buscar `</script>` es frágil
+ * porque `</ScRiPt >` también cierra el elemento y la lista de variantes es
+ * larga; escapar el `<` las cubre todas.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeHtmlText = escapeHtmlText;
+exports.escapeAttrValue = escapeAttrValue;
+exports.safeAttrName = safeAttrName;
+exports.renderAttrs = renderAttrs;
+const HTML_ESCAPES = {
+    // El `&` va primero, siempre: si se reemplazara después, volvería a escapar
+    // los `&` que introducen los otros cuatro reemplazos.
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+const HTML_ESCAPE_RE = /[&<>"']/g;
+/** Para texto entre etiquetas: el contenido de `<title>`, por ejemplo. */
+function escapeHtmlText(value) {
+    return String(value ?? '').replace(HTML_ESCAPE_RE, (c) => HTML_ESCAPES[c]);
+}
+/**
+ * Para el valor de un atributo, que siempre se emite entre comillas dobles.
+ *
+ * Se escapan las dos comillas aunque sólo una pueda cerrar el atributo: cuesta
+ * lo mismo y hace que la función siga siendo correcta si alguien la usa en otro
+ * contexto.
+ */
+function escapeAttrValue(value) {
+    return escapeHtmlText(value);
+}
+/** Forma válida de un nombre de atributo en HTML. */
+const ATTR_NAME_RE = /^[A-Za-z_:][A-Za-z0-9_.:-]*$/;
+/** Esquemas que ejecutan código si el navegador navega a ellos. */
+const DANGEROUS_VALUE_RE = /^\s*(?:javascript:|data:text\/html)/i;
+/**
+ * Valida un nombre de atributo. Devuelve `null` si no se puede emitir.
+ *
+ * Se rechaza todo lo que empiece con `on`: son manejadores de eventos, y un
+ * valor controlado por quien envía la petición dentro de uno es ejecución de
+ * código. `srcdoc` va por lo mismo — su contenido es un documento entero.
+ */
+function safeAttrName(name) {
+    if (!ATTR_NAME_RE.test(name))
+        return null;
+    const lower = name.toLowerCase();
+    if (lower.startsWith('on'))
+        return null;
+    if (lower === 'srcdoc')
+        return null;
+    return name;
+}
+/**
+ * Serializa un mapa de atributos ya escapado. Devuelve `''` si no queda ninguno.
+ *
+ * Un atributo rechazado se descarta. En desarrollo se avisa; en producción no,
+ * porque un registro por petición sobre un dato que controla quien ataca es en
+ * sí mismo una forma de inundar los logs.
+ */
+function renderAttrs(attrs, ctx) {
+    const context = typeof ctx === 'string' ? { where: ctx, isProduction: true } : ctx;
+    const parts = [];
+    for (const [rawName, rawValue] of Object.entries(attrs ?? {})) {
+        const name = safeAttrName(rawName);
+        if (!name) {
+            discard(context, rawName, 'no es un nombre de atributo admitido');
+            continue;
+        }
+        const value = String(rawValue ?? '');
+        if (DANGEROUS_VALUE_RE.test(value)) {
+            discard(context, rawName, 'su valor usa un esquema que ejecuta código');
+            continue;
+        }
+        parts.push(`${name}="${escapeAttrValue(value)}"`);
+    }
+    return parts.join(' ');
+}
+function discard(ctx, name, why) {
+    if (ctx.isProduction)
+        return;
+    const where = ctx.route ? `${ctx.where} de ${ctx.route}` : ctx.where;
+    console.warn(`[ress] atributo descartado en ${where}: "${name}" — ${why}.`);
+}

package/dist/security/head-tags.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+import { type EscapeContext } from './escape';
+/** Una etiqueta estructurada. F-004 la produce; acá se filtra y se emite. */
+export interface HeadTag {
+    tag: string;
+    attrs?: Record<string, unknown>;
+    /** Contenido textual, para `title` y `style`. */
+    children?: string;
+}
+export declare const HEAD_TAG_ALLOWLIST: readonly ["meta", "link", "title", "base", "style"];
+export interface HeadTagOptions {
+    /** `script` no está en la lista por defecto. Esto lo agrega. */
+    allowScriptTags?: boolean;
+    /** Etiquetas que el proyecto suma a la lista. */
+    extraAllowlist?: readonly string[];
+    /** Autoriza los bloques inline ante la política de contenido. */
+    nonce?: string;
+}
+/**
+ * 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.
+ */
+export declare function renderHeadTags(tags: readonly HeadTag[], ctx: EscapeContext, options?: HeadTagOptions): string;