@opensas/xml-rest-adapter 0.2.1 → 0.2.2

package/README.md

@@ -8,3 +8,132 @@ npm: https://www.npmjs.com/package/@opensas/xml-rest-adapter
 ```bash
 pnpm add @opensas/xml-rest-adapter
 ```
+
+## Cómo funciona, paso a paso
+
+`createXmlRestAdapter(app)` recibe la definición de una aplicación (nombre, cómo autenticar,
+cómo autorizar, a qué base conectarse, qué objetos exponer) y devuelve dos funciones:
+`resolveUser` y `handle`. No importa qué framework o runtime uses — ambas trabajan con `Request`/
+`Response` de la Fetch API estándar, nada específico de SvelteKit ni de Node.
+
+**1. Creá el adapter una sola vez**, con la config de tu app:
+
+```ts
+import { createXmlRestAdapter, endpoints } from '@opensas/xml-rest-adapter';
+
+const adapter = createXmlRestAdapter({
+	name: 'MiApp', // tiene que coincidir con el Codigo de la app en Meta (o usá aplicacionCodigo)
+	authentication: { type: 'iis-node' }, // o { type: 'none' } para apps públicas/anónimas
+	authorization: { type: 'metaSSC', dbInfo: process.env.META_DATABASE_URL },
+	dbInfo: process.env.MI_APP_DATABASE_URL, // connection string ADO.NET, o un objeto DbInfo
+	pagination: 'sql', // 'com+' solo para SPs viejos sin @SqlPaginate
+	endpoints: endpoints(['Provincia', 'TipoDato']), // qué objetos expone esta app
+});
+```
+
+**2. Por cada request, resolvé quién está llamando** — `resolveUser` acepta el `Request` tal cual
+(extrae la identidad según `authentication.type`) o un `string` ya resuelto:
+
+```ts
+const result = await adapter.resolveUser(request);
+if (!result.ok) {
+	/* result.error: AppError con status/code/title — devolvelo como respuesta */
+}
+const usuario = result.data;
+```
+
+**3. Dejá que el adapter atienda el request** — `handle` necesita el `Request`, el segmento de
+URL después de tu ruta (objeto, y opcionalmente `/id`), y el `usuario` del paso anterior:
+
+```ts
+const response = await adapter.handle(request, path, usuario);
+```
+
+Eso es todo — `handle` decide la acción (Consulta/Alta/Modificacion/Baja) según el método HTTP
+(`GET`/`POST`/`PUT`/`DELETE`), valida permisos, arma y ejecuta el `xml{Objeto}_{Accion}` contra
+SQL Server, y devuelve la `Response` ya lista (JSON o el error correspondiente).
+
+## Ejemplo con SvelteKit
+
+Un solo archivo alcanza — la carpeta **tiene** que ser `[...path]` (rest parameter), porque
+`objeto`/`id` no son segmentos fijos:
+
+```ts
+// src/routes/mi-app/[...path]/+server.ts
+import { createXmlRestAdapter, endpoints, jsonError } from '@opensas/xml-rest-adapter';
+import { env } from '$env/dynamic/private';
+import type { RequestHandler } from './$types.js';
+
+const adapter = createXmlRestAdapter({
+	name: 'MiApp',
+	authentication: { type: 'iis-node' },
+	authorization: { type: 'metaSSC', dbInfo: env.META_DATABASE_URL },
+	dbInfo: env.MI_APP_DATABASE_URL,
+	pagination: 'sql',
+	endpoints: endpoints(['Provincia', 'TipoDato']),
+});
+
+// Un solo handler para los 4 verbos — `fallback` los atrapa a todos, `.handle()` decide la
+// acción según `event.request.method`.
+export const fallback: RequestHandler = async (event) => {
+	const result = await adapter.resolveUser(event.request);
+	if (!result.ok) return jsonError(result.error);
+	return adapter.handle(event.request, event.params.path, result.data);
+};
+```
+
+Con esto, `GET /mi-app/Provincia?_limit=10`, `POST /mi-app/TipoDato`, `PUT /mi-app/Provincia/5`,
+`DELETE /mi-app/Provincia/5` ya funcionan. Ejemplo completo y corrible en
+[`examples/consumer-svelte/`](examples/consumer-svelte/).
+
+## Ejemplo con Node puro (sin ningún framework)
+
+`handle()`/`resolveUser()` no requieren nada de SvelteKit — alcanza con las `Request`/`Response`
+globales que trae Node 18+. Un servidor mínimo con `node:http`:
+
+```js
+import { createServer } from 'node:http';
+import { createXmlRestAdapter, endpoints, jsonError } from '@opensas/xml-rest-adapter';
+
+const adapter = createXmlRestAdapter({
+	name: 'MiApp',
+	authentication: { type: 'none' }, // sin IIS: no hay identidad real que extraer del request
+	authorization: { type: 'none' },
+	dbInfo: process.env.MI_APP_DATABASE_URL,
+	pagination: 'sql',
+	endpoints: endpoints(['Provincia']),
+});
+
+const server = createServer(async (req, res) => {
+	const url = new URL(req.url, `http://${req.headers.host}`);
+	const path = url.pathname.replace(/^\//, ''); // 'Provincia' o 'Provincia/5'
+	const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+
+	const request = new Request(url, {
+		method: req.method,
+		headers: req.headers,
+		body: hasBody ? req : undefined,
+		duplex: hasBody ? 'half' : undefined,
+	});
+
+	const userResult = await adapter.resolveUser(request);
+	const response = userResult.ok
+		? await adapter.handle(request, path, userResult.data)
+		: jsonError(userResult.error);
+
+	res.writeHead(response.status, Object.fromEntries(response.headers));
+	res.end(Buffer.from(await response.arrayBuffer()));
+});
+
+server.listen(3000);
+```
+
+Prueba mínima sin siquiera levantar un servidor HTTP (construyendo los `Request` a mano y
+llamando a `handle()` directo) en [`examples/consumer/test.mjs`](examples/consumer/test.mjs).
+
+## Más
+
+- [`docs/uso-interno.md`](docs/uso-interno.md) — gotchas y detalles que no son obvios a la
+  primera (qué campo tiene que matchear con Meta, cómo mapea `endpoints`/URL/SP, etc.).
+- [`docs/proximos-pasos.md`](docs/proximos-pasos.md) — el porqué de cada decisión de diseño.
+- [`CHANGELOG.md`](CHANGELOG.md) — qué cambió entre versiones.

package/dist/index.js

@@ -8,7 +8,7 @@
 //   export const fallback: RequestHandler = async (event) => {
 //     const result = await adapter.resolveUser(event.request);
 //     if (!result.ok) return jsonError(result.error);
-//     return adapter.handle(event, result.data);
+//     return adapter.handle(event.request, event.params.path, result.data);
 //   };
 export { createXmlRestAdapter } from './create-adapter.js';
 export { endpoints } from './endpoints.js';

package/dist/parse-request.js

@@ -5,7 +5,7 @@
 // nada contra la base — deja el XmlSentencia listo para pasarle a execXmlSentencia/
 // execXmlConsulta.
 import { appError } from './errors.js';
-import { toXmlAlta, toXmlBaja, toXmlConsulta, toXmlConsultaId, toXmlModificacion, } from './request-to-xml.js';
+import { errorEnListaCampos, toXmlAlta, toXmlBaja, toXmlConsulta, toXmlConsultaId, toXmlModificacion, } from './request-to-xml.js';
 import { err, ok } from './result.js';
 import { checkPermiso, validParams } from './valid.js';
 const MULTIPART_CONTENT_TYPE = 'multipart/form-data';
@@ -55,6 +55,13 @@ export async function parseRequest(app, request, path, usuario) {
     const operador = usuario.domainUser;
     const url = new URL(request.url);
     if (metodo === 'GET') {
+        // toXmlConsultaId no lee _fields/_order de la URL (Campos/Orden fijos, ver
+        // request-to-xml.ts) — la validación solo aplica al listado.
+        if (!id) {
+            const error = errorEnListaCampos(url.searchParams);
+            if (error)
+                return err(appError(error, 'VALIDATION_ERROR'));
+        }
         const sentencia = id
             ? toXmlConsultaId(url.searchParams, app, objeto, id, operador, fieldId)
             : toXmlConsulta(url.searchParams, app, objeto, operador);

package/dist/request-to-xml.d.ts

@@ -1,5 +1,6 @@
 import { type Aplicacion } from './types.js';
 import { type XmlSentencia } from './xml.js';
+export declare function errorEnListaCampos(urlSearchParams: URLSearchParams): string | null;
 export declare function toXmlConsulta(urlSearchParams: URLSearchParams, app: Aplicacion, objeto: string, operador: string): XmlSentencia;
 export declare function toXmlConsultaId(urlSearchParams: URLSearchParams, app: Aplicacion, objeto: string, id: number, username: string, fieldId?: string): XmlSentencia;
 export declare function toXmlAlta(app: Aplicacion, objeto: string, username: string, data: Record<string, string>): XmlSentencia;

package/dist/request-to-xml.js

@@ -15,6 +15,60 @@ const QUERY_KEYS = {
     campos: '_fields',
     orden: '_order',
 };
+const getXmlOrden = (orden) => orden
+    .split(',')
+    .map((field) => field.trim())
+    .map((field) => {
+    if (field.startsWith('-'))
+        return field.slice(1) + ' DESC';
+    if (field.startsWith('+'))
+        return field.slice(1);
+    return field;
+})
+    .join(',');
+const IDENTIFICADOR_SQL = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// Defensa en profundidad — espejo de dbo.esListaDeCampos (docker/fixture/scripts/02-support.sql,
+// ver también docs/todos/sql-injection-campos-orden.md en convenios_web). La capa autoritativa es
+// esa función en SQL Server: cubre también a los consumidores legacy (apps ASP clásico) que le
+// pegan directo al SP sin pasar por acá. Esta validación solo evita el viaje a la base y da un
+// 400 más claro cuando el caller es este adapter. No hace falta el caso especial de
+// 'Count(*) as count' que sí tiene el lado SQL: ese literal lo arma execXmlConsulta (db.ts)
+// server-side, en un punto que nunca lee _fields/_order de la URL.
+function esListaDeCampos(lista, permiteAscDesc) {
+    if (!lista || lista.trim() === '')
+        return true;
+    if (lista === '*')
+        return true;
+    return lista.split(',').every((item) => {
+        const campo = item.trim();
+        if (campo === '')
+            return false;
+        if (!permiteAscDesc)
+            return IDENTIFICADOR_SQL.test(campo);
+        const partes = campo.split(/\s+/);
+        if (partes.length > 2)
+            return false;
+        const [nombre, direccion] = partes;
+        if (!IDENTIFICADOR_SQL.test(nombre))
+            return false;
+        return direccion === undefined || ['ASC', 'DESC'].includes(direccion.toUpperCase());
+    });
+}
+// null = válido. String no vacío = mensaje de error (_fields/_order no son listas de columnas).
+// Valida el _order ya traducido a la forma `Campo[,Campo][ DESC]` (post getXmlOrden) — el prefijo
+// +/- de la URL no es lo que llega a la SP, así que no tiene sentido validar contra ese formato.
+export function errorEnListaCampos(urlSearchParams) {
+    const campos = urlSearchParams.get(QUERY_KEYS.campos);
+    if (!esListaDeCampos(campos, false)) {
+        return `${QUERY_KEYS.campos} inválido: solo se admite una lista de nombres de columna separados por coma.`;
+    }
+    const ordenRaw = urlSearchParams.get(QUERY_KEYS.orden);
+    const orden = ordenRaw ? getXmlOrden(ordenRaw) : null;
+    if (!esListaDeCampos(orden, true)) {
+        return `${QUERY_KEYS.orden} inválido: solo se admite una lista de nombres de columna (con +/- opcional) separados por coma.`;
+    }
+    return null;
+}
 export function toXmlConsulta(urlSearchParams, app, objeto, operador) {
     const metodoDefault = 'Consulta';
     const metodo = urlSearchParams.get(QUERY_KEYS.metodo) || metodoDefault;
@@ -85,17 +139,6 @@ export function toXmlBaja(app, objeto, username, data = {}) {
         Parametro: { Tabla: objeto, ...data },
     });
 }
-const getXmlOrden = (orden) => orden
-    .split(',')
-    .map((field) => field.trim())
-    .map((field) => {
-    if (field.startsWith('-'))
-        return field.slice(1) + ' DESC';
-    if (field.startsWith('+'))
-        return field.slice(1);
-    return field;
-})
-    .join(',');
 const keysToCondition = (params) => {
     const cond = [];
     for (const [key, value] of params) {

package/dist/xml.js

@@ -28,6 +28,12 @@ export function xmlConsulta(options) {
             Campos: options.Parametro?.Campos || '*',
             Orden: options.Parametro?.Orden,
             Condiciones: options.Parametro?.Condiciones,
+            // Lista fija a propósito, no spread de options.Parametro: agregar un campo nuevo acá
+            // es una decisión explícita, no "lo que sea que venga en el objeto" — evita que una
+            // key con otro nombre en el futuro se cuele sin que nadie la haya revisado. ShowSql
+            // (bit de xmlConsulta_Parse/ixmlTabla_Consulta, ver docker/fixture/scripts/02-support.sql)
+            // devuelve el SQL armado sin ejecutarlo — lo usan las pruebas de sql-injection.fixture.test.ts.
+            ShowSql: options.Parametro?.ShowSql,
         },
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@opensas/xml-rest-adapter",
-	"version": "0.2.1",
+	"version": "0.2.2",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -57,37 +57,37 @@
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
-		"@playwright/test": "^1.62.1",
+		"@playwright/test": "^1.63.0",
 		"@sveltejs/adapter-auto": "^7.0.1",
 		"@sveltejs/kit": "^2.63.0",
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "^7.1.2",
 		"@types/mssql": "^12.3.0",
-		"@types/node": "^24",
+		"@types/node": "^24.13.5",
 		"dotenv": "^17.4.2",
-		"eslint": "^10.4.1",
+		"eslint": "^10.10.0",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-check-file": "^3.3.2",
 		"eslint-plugin-simple-import-sort": "^13.0.0",
 		"eslint-plugin-svelte": "^3.19.0",
 		"eslint-plugin-unicorn": "^71.1.0",
-		"globals": "^17.6.0",
+		"globals": "^17.12.0",
 		"jiti": "^2.7.0",
-		"prettier": "^3.8.3",
+		"prettier": "^3.9.7",
 		"prettier-plugin-svelte": "^4.1.0",
 		"publint": "^0.3.21",
-		"svelte": "^5.56.1",
+		"svelte": "^5.57.0",
 		"svelte-check": "^4.6.0",
-		"tsx": "^4.23.12",
+		"tsx": "^4.23.13",
 		"typescript": "^6.0.3",
-		"typescript-eslint": "^8.60.1",
-		"vite": "^8.0.16",
+		"typescript-eslint": "^8.70.0",
+		"vite": "^8.3.0",
 		"vitest": "^4.1.8"
 	},
 	"keywords": [
 		"svelte"
 	],
 	"dependencies": {
-		"mssql": "^12.7.0"
+		"mssql": "^12.7.2"
 	}
 }